Epic: cross-repo architecture landscape

[kyle-sexton]

Brief

TLDR

A new skill in the architecture plugin that maps a fleet of repositories into a C4 System Landscape plus an application-portfolio table (with a thin setup skill owning the consumer's architecture declaration), and a six-dimension completeness check folded into the design-handoff gate as advisory coverage reporting. No enterprise-architecture framework is shipped as a skill.

Goal

Answer "what systems do we have, who owns them, what do they run on, and how do they relate" from the repositories themselves, and give the design-handoff gate a cheap completeness lens over the six dimensions (what, how, where, who, when, why) without importing a framework.

Constraints

• Skill content is organization-agnostic: no publisher or organization names in the skill body.
• Repository discovery: the argument selects the mode. An explicit repository list bypasses discovery; a scan root triggers it, through the repo-fleet-hygiene canonical-repo discovery when that plugin is installed (presence-gated) and through a bundled walk otherwise. The collaborator's discovery is scoped, not argument-free, so a run with neither argument stops.
• Output lands in the consumer's declared architecture home, not a location this plugin picks. The declaration is a convention doc at the consumer's convention home (<home>/architecture/README.md, keys architecture_dir, landscape_dialect) converged by architecture:setup apply (pointer region and topic doc, as the pilot setup does); with nothing declared or confirmed, map-landscape stops rather than defaulting the location.
• The completeness check is advisory: it reports coverage and never blocks the gate on its own.
• No TOGAF or Zachman framework prose ships in either deliverable.

Acceptance criteria

• A map-landscape skill exists in the architecture plugin, discovers repositories from an explicit list argument, and uses the fleet-hygiene discovery when that plugin is present and a scan root is given.
• The skill emits a C4 System Landscape view plus a portfolio table carrying owner, target framework, runtime, dependencies, and last-touched date for each discovered repository.
• An architecture:setup skill reports the declaration state (check) and converges the pointer region and topic doc idempotently (apply), per the fleet setup contract.
• The design-handoff gate reports coverage of what, how, where, who, when, and why across resolved and directional design threads as an advisory table, and no coverage gap causes the gate to fail.

Captured assumptions

• The facts in the portfolio table (owner, framework, runtime, dependencies, last touched) are derivable from repository contents and metadata without a separate registry. Qualified: owner degrades CODEOWNERS → remote owner → unknown and is never guessed from commit authors; last touched is the local HEAD date (nothing fetches).
• Structurizr DSL and mermaid are both acceptable landscape dialects; the consumer's convention picks. Qualified: Structurizr has a native systemLandscape view; mermaid has no landscape diagram type, so the landscape renders as a C4Context with no focal system, and mermaid marks its C4 syntax experimental (verified 2026-09-06; recheck when a mermaid release adds a landscape type or drops the notice).

Out-of-scope

• Baseline-versus-target gap analysis. There is no written target architecture to compare against yet.
• TOGAF ADM guidance, the Zachman grid as a standalone skill, capability maps, and work-breakdown structures.
• A standalone design-document skill.
• Container-level or component-level C4 views.
• Any write to a consumer's root instruction file outside the marked convention-home region.

Deferred questions

• C3: baseline-versus-target gap analysis, blocked until a written target architecture exists to compare the discovered landscape against.
• Whether repo-fleet-hygiene should publish a discovery-only mode or a documented plan-JSON schema for consumers (today the seam is --plan-file plus a schema_version check with a bundled fallback, and a discovery-only use pays for a full audit that collects GitHub evidence).
• Whether /planning:design should prompt for the six dimensions at design time, upstream of the gate.

Execution shape: per-item PRs

Amendment note (2026-09-06, planning slice #3807)

Body amended from the verified plan (docs/topics/cross-repo-landscape/PLAN.md, branch plan/3807-cross-repo-landscape, contract-tier, never merges): criterion 1 gains "and a scan root is given" because the fleet-hygiene discovery stops without a scope; the discovery constraint now says the argument selects the mode (an explicit list bypasses discovery outright); a third criterion covers the architecture:setup skill the plugin philosophy requires once a consumer configuration surface exists; the design-handoff criterion widens "resolved" to "resolved and directional"; the architecture-home constraint names the declaration mechanism this lane creates (none existed) and the no-silent-default rule; both captured assumptions are qualified; "six-interrogative" wording replaced by "six-dimension" so the framework vocabulary the constraints forbid does not appear in the Brief either.

[kyle-sexton]

Container closed: cross-repo landscape

Every sub-item is closed and the shipped whole passed an independent close-out review run in a fresh context that had not written any of the work.

Shipping PRs

• feat(architecture): map a C4 system landscape and application portfolio over discovered repos #3901 — map-landscape and the architecture:setup skill (architecture/map-landscape: C4 system landscape + application-portfolio table over discovered repos #3816), merged as 09b824700
• feat(planning): report six-dimension coverage in the design-handoff gate #3899 — the six-dimension coverage table in design-handoff (planning/design-handoff: Zachman six-interrogative completeness check in the gate #3817), merged as 63f52be65
• architecture: plan map-landscape skill and Zachman completeness check #3807 was the planning slice and shipped no code; it is judged on its closing comment

Verdict

Closes. Every amended acceptance criterion is delivered on current main, every gate passes, and the two defects the review found are follow-ups against a captured assumption rather than against a stated criterion.

The review confirmed all five amendments actually landed: the mode-selecting argument, the scan-root clause, the added architecture:setup criterion, the widening of the design-handoff criterion to "resolved and directional", and the qualified assumptions.

Two things it verified rather than accepted. The fleet-hygiene seam is real: audit-fleet.sh emits schema_version: 1 and the repositories[].discovered/canonical/remote fields that map-landscape reads. And the coverage table is genuinely advisory: the FAIL sentence is byte-identical to before, and an eval pins that a coverage gap still passes the gate.

Gates on current main: 54 setup skills, 3 retirement manifests, and 3359 plugin files checked; All 2 plugin copies match plugins/claude-config/lib/resolve-convention-home.sh.; 44 cases, 0 failed on the portfolio-facts tests; changelog parity, skill-count claims, orphaned fixtures and markdownlint all clean. The vendored resolver is byte-identical to the canonical copy by cmp and is enrolled in the sync gate.

Follow-ups, none of which blocked this close

1. An owner can still be fabricated. A file:///home/u/web remote yields "owner":"home" carrying evidence.owner: "origin remote URL", so a guessed fact arrives with a citation. That violates the script's own "never a guess" rule. A fix exists only as uncommitted local edits and is being landed as its own PR.
2. Two C4 dialect surfaces now exist. authoring-formats says diagram_dialect.system deliberately has no default and excludes mermaid as experimental; the new architecture row defaults landscape_dialect to mermaid, citing the same upstream page and date. The amended Brief authorized this, but a consumer now declares a C4 dialect in two documents with disjoint value sets. Worth reconciling to one surface or recording why there are two.
3. The planning plugin shipped 0.38.0 rather than the 0.37.0 the sub-item named, because another PR took that version first. No criterion is affected.

The plan branch plan/3807-cross-repo-landscape is contract-tier and never merges; it will be pruned.

Closing per the ship ritual. A closed container stays findable but leaves the active views, so no shipped spec sits in the open tracker for a future agent to trust over the code.