fix(architecture): straighten near-axis routes and constrain nested boundary frames (fixes #74)

[SomSamantray]

Problem and value

Fixes #74. architecture diagrams can pass validate --quality showcase (9/9, 0 errors) while visually broken in two ways:

1. Auto-routed connections between near-axis facing ports render winding outside-channel doglegs even when a straight segment is geometrically clear.
2. Strictly-nested boundary frames can sit flush with (or coincide with) their containing frame, producing an ambiguous double border.

Because Archify's value is "agents author JSON, Archify compiles deterministically, and showcase receipts gate quality", both defects ship a green receipt for a visually broken artifact. This change makes the router emit the straight route when it is clear, and makes showcase reject coincident/sub-8px nested frames with a stable machine-readable diagnostic.

Scope

• What changed:
  • alignFacingPorts (architecture renderer) now aligns unspread explicit-side facing pairs whose perpendicular offset is below the 16px automatic-port-alignment delta, so a clear straight segment renders as a 2-point route. All preserved classes (both endpoints spread, explicit via/channel/labelAt/non-auto route, non-facing sides, offset >= 16px, blocked straight path) keep today's behavior.
  • New showcase-gated composition rule composition/boundary-frame-clearance: for strictly-nested boundary pairs (one wraps set a strict subset of the other), any inner edge inset below 8px (or negative, i.e. crossing the containing frame) over an overlapping span is an error diagnostic with per-edge supportedFixes (pad guidance on pad-adjustable left/right edges; member-movement guidance on top/bottom edges).
  • Regression tests: archify/test/near-axis-routing.test.mjs (9 cases) and archify/test/boundary-composition.test.mjs (11 cases).
• What deliberately did not change:
  • standard and absent-profile documents (the rule is gated to the effective showcase profile, authored or forced).
  • Cross-cutting boundary scopes whose memberships overlap (runtime/compliance style set semantics) are never flagged.
  • The deployment-ownership-gated membership contract, all other diagram types, schemas, and the viewer.
• No unrelated changes: the only non-source changes are re-pads of checked-in showcase examples that the new rule now requires (so they model the corrected contract) plus their regenerated artifacts.

Stability impact

• Compatibility and migration risk: low. No schema or public-surface change. Existing typed JSON remains valid; standard receipts are unchanged. A showcase document with strictly-nested boundaries under the 8px inset now fails with an actionable diagnostic instead of silently passing.
• Renderer, validator, package, or generated-artifact risk: checked-in showcase examples were re-padded (checkout-platform base/head, production-deployment, mco-runtime, v1-baseline fixture) and their gallery/delta/MCO artifacts and archify.zip regenerated from source. archify.zip was rebuilt with the canonical Node 22 toolchain.
• Failure behavior and rollback path: deliver/validate return non-zero with diagnostics[] entries (stable code, evidence, supportedFixes). Rollback is a revert of this commit; no migrations.

Tests run

cd archify
node --test test/near-axis-routing.test.mjs test/boundary-composition.test.mjs   # 20/20 pass
ARCHIFY_MCO_REPO_ROOT=<mco clone> npm test   # 1046 tests: 1020 pass, 0 fail, 26 env-gated skips, exit 0
ARCHIFY_CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" node --test test/desktop-reader-browser.test.mjs  # 1/1 pass (real Chrome)

CLI repro checks (issue #74):

• near-axis repro: node bin/archify.mjs validate architecture <fixture> --quality showcase --json -> ok: true, 2-point route.
• flush nested-boundary repro: -> ok: false with only composition/boundary-frame-clearance diagnostics.

Visual evidence

Change is visual (routing and boundary-frame geometry). Automated evidence:

• visual-check on docs/gallery/artifacts/production-deployment.architecture.html and docs/cases/mco-runtime.architecture.html: ok: true, readability pass at 1440x900 / 1600x1000 / 1920x1080 / 2048x1320 (contact sheets generated).
• examples/checkout-platform-delta.html reports vertical overflow, but byte-for-byte identically on baseline main (a pre-existing tall delta-compare page; geometry unchanged by this PR).
• visual review: passed (automated) for the regenerated architecture artifacts; a human perceptual pass remains outstanding.

Generated artifacts

Regenerated from source after the geometry changes (no hand edits):

• archify.zip (canonical Node 22 build)
• docs/gallery.html, docs/gallery/manifest.json, docs/gallery/artifacts/production-deployment.architecture.html, docs/gallery/sources/production-deployment.architecture.json
• docs/assets/archify-live-proof.gif, docs/assets/archify-live-proof.json
• docs/cases/mco-runtime.architecture.html, experiments/mco-showcase/mco-runtime.html (byte-reproduced against the pinned mco repository revision via --repo-root)
• examples/checkout-platform-delta.html, examples/checkout-platform-delta.receipt.json

Unapplied review findings

Review findings that need maintainer judgment were left unapplied and are listed below so they can be resolved on this PR (each is self-contained; none blocks the change above).

• P1 — archify/renderers/architecture/render-architecture.mjs:410 — Equal-membership coincident frames still pass showcase (the boundary gate only fires for strict-subset memberships; two boundaries with identical wraps and identical pad render coincident frame rects and receive a green receipt).
  Suggested fix: under the effective showcase profile, also measure frame insets for pairs whose memberships are equal (not only strict subsets); report coincident or sub-8px edges with the same composition/boundary-frame-clearance code, and let equal membership with an adequate pad difference (real nesting) still pass.

• P2 — archify/renderers/architecture/render-architecture.mjs:358 — Shared-extreme bottom-flush guidance is unachievable (a frame's bottom edge is maxY + boundaryExtraBottom, pad-independent; when both frames share their bottom-most member, moving that member moves both bottom edges together and the inset is invariant, so the "move the extreme wrapped member" supported fix cannot reach the 8px floor).
  Suggested fix: detect when the offending top/bottom extreme is a member shared by both frames and reword the supported fix to name the required membership change (add an exclusive member beyond the extreme, or remove the member from the nested wraps), or suppress the top/bottom check for that shared-extreme case.

• P2 — archify/renderers/architecture/render-architecture.mjs:910 — Near-axis straightening can flip previously-green docs red by moving a connection label onto an obstacle (the straight two-point route pins the label in the corridor the old outside dogleg kept clear).
  Suggested fix: when a straightened candidate's default label rect collides with a component or boundary title, fall back to the deterministic dogleg for that connection, or auto-place the label at the first clear offset; at minimum add a test with an obstacle adjacent to the straight corridor of a labeled near-axis pair.

• P3 — archify/renderers/architecture/render-architecture.mjs:357 — Top-edge fix guidance omits the pad remedy above the 22px title-label floor.
  Suggested fix: make the top-edge fix string conditional (offer pad guidance when the containing top pad exceeds the floor, member guidance otherwise) or document the floor interaction in the message.

• P2 — archify/test/near-axis-routing.test.mjs:80 — Horizontal-facing (right/left) near-axis straightening is untested (all fixtures drive top/bottom pairs).
  Suggested fix: add a right/left-facing near-axis repro asserting a 2-point shared-horizontal-axis route, plus a blocked horizontal corridor variant asserting the deterministic dogleg is kept.

• P2 — archify/test/boundary-composition.test.mjs:76 — Authored-showcase profile path for the boundary gate is untested (every firing test forces the profile via CLI --quality showcase on docs with no authored meta.quality_profile).
  Suggested fix: add a doc with meta.quality_profile: 'showcase' on a flush nested pair validated with no --quality (expect failure), and one forcing --quality standard over an authored-showcase flush doc (expect pass).

• P3 — archify/test/boundary-composition.test.mjs:376 — Crossing-frame negative-inset branch is untested.
  Suggested fix: add a crossing test (inner pad >> outer clearance) asserting negative insetPx, the crossing message, and correct per-edge supported fixes; if guidance is wrong for pad-induced crossing, correct the fix-selection for negative insets.

Checklist

• I used a minimal focused change and preserved existing typed JSON behavior unless the issue requires a contract change.
• I ran the relevant targeted tests and npm test in archify/.
• I added or updated a regression test for behavioral changes.
• I checked generated artifacts and package freshness when their sources changed.
• I removed secrets, private repository content, and customer data from fixtures and screenshots.