AUD-S17: sync the C4 diagrams to the shipped architecture (ARCH-05)

[konih]

AUD-S17 / REQ-AUD-S17-01 (ARCH-05) — the C4 pages showed rego, gRPC, WASM and a GitHub adapter as if they existed, and the package sketch named three packages that have never existed. Redrawn from go list ./internal/... ./cmd/..., not from the old diagram.

go list output this was derived from

internal/adoptertest          internal/forge
internal/catalogue            internal/forge/conformance
internal/change               internal/forge/fake
internal/compare              internal/forge/gitlab
internal/core                 internal/glob
internal/core/aggregate       internal/lint
internal/core/classify        internal/provider
internal/core/decision        internal/provider/builtin
internal/core/hash            internal/render
internal/core/policy          internal/render/locale
internal/evaldecode           internal/schemadrift
                              cmd/assent

22 internal packages + cmd/assent (+ the root schemas package, which appears in the import graph).

Element mapping — container diagram

Diagram element (before)	Now
Forge adapter (read) GitLab | GitHub	split: internal/forge/gitlab + internal/forge (port) shipped; GitHub adapter → PLANNED (E10), dashed
Policy loader (.assent/ from TARGET ref)	internal/core/policy (+ internal/catalogue for pack activation)
Format adapters JSON · YAML · HCL/tfvars	folded into internal/change — there is no internal/format; diff_hcl.go/diff.go/limits.go live there
Structural differ + classifier	split: internal/change (differ) + internal/core/classify (classification)
PolicyInput	internal/evaldecode (strict decode) — the node named a type, not a container
Policy engine (envelope…)	internal/core/aggregate
assert backend (CEL-leaf trees, cel-go)	internal/core/aggregate (asserttree.go, evalscalar.go, compilecheck.go) — merged, it is not a separate container
rego backend (OPA, capability-sandboxed)	PLANNED (E11), dashed. No rego implementation exists — schemas/evaluation_input_test.go actively pins the evaluation-input schema backend-neutral. (ADR-0010's layout example still shows a .assent/rego/ tree unmarked; left as a dated record — residual #3.)
Decision + Findings + Trace + Pins	internal/core/decision (dropped "Trace" — no such artifact)
Built-ins: forge groups, OIDC/Keycloak, LDAP, owners-file	internal/provider/builtin — real builtins are builtin/gitlab-groups (alias forge-groups), repo-file, resource-owner. Keycloak/LDAP/OIDC have no builtin; moved to the context page as "reachable via the generic HTTP/exec transport"
HTTP / exec providers (digest-pinned)	internal/provider (transport.go — real HTTP + digest-pinned exec)
gRPC / WASM tiers	PLANNED (ADR-0004 tiers 3–4), dashed. Zero matches for grpc/wasm under internal/+cmd/
Renderer (escaped, redacted, lifecycle)	internal/render (+ internal/render/locale)
Forge adapter (write)	internal/forge/gitlab — merged with the read node; one adapter, not two
JSON report artifact	internal/core/decision (report emission)

New nodes for real packages the old diagram omitted entirely: internal/glob, internal/core/hash, internal/core (test-only purity guard), internal/lint, internal/adoptertest, internal/compare, internal/schemadrift, internal/forge/fake, internal/forge/conformance, schemas.

Element mapping — context diagram

Before	Now
Forge — GitLab (first) / GitHub (next)	GitLab: shipped adapter (internal/forge/gitlab). GitHub: PLANNED (E10) — no adapter code exists
CI runner — GitLab CI / GitHub Actions	GitLab CI shipped; GitHub Actions as a forge trigger marked PLANNED (E10), with a note that assent's own CI runs on Actions — project infra, not a supported forge path
Permission sources — Keycloak / LDAP / forge groups / ownership files	the three real builtins; Keycloak/LDAP explicitly "no builtin — reachable only via the generic HTTP/exec provider transport"
No long-lived service in v1	plus "serve HTTP API is PLANNED (E12)"

Deleted (mapped to nothing real, not plausibly planned)

• Subcommands explain, scan, stats, init — the old package sketch advertised all four. The real dispatch table is run doctor lint test compare catalogue render eval-input version help. No code, no epic in the meta-plan, and absent from the README maturity table → deleted rather than marked planned.
• internal/format, internal/policy, internal/harness — never existed. Replaced by an explicit "there is no …" note so the next reader does not re-invent them.
• "Trace" as a decision artifact — no such thing in internal/core/decision.
• "OIDC/Keycloak, LDAP" as builtins — no builtin exists; kept only as an HTTP/exec transport capability on the context page.

Judgment call: planned vs deleted

The rule applied, so it is reviewable: named in D-012 (or holding a deferred epic E10–E13) → marked PLANNED with its epic; otherwise deleted. D-012 names exactly rego, gRPC, WASM, GitHub adapter, serve and remote packs as designed seams, and the README maturity table already tiers them. Nothing new was decided, so no ADR — D-012 is cited in both legends.

Legend (present on both pages)

Container page:

Style	Meaning
Solid border	Shipped — names a real Go package or the real binary; present in go list ./internal/... ./cmd/...
Dashed border, PLANNED — E<n> / PLANNED — ADR-0004	Planned — designed seam, no implementation; deferred under D-012
Solid arrow	Decision-path flow; the pair is backed by a real import between those two packages
Dashed arrow	The port a planned seam would plug into — no code today

The context page uses in-label markers plus a prose legend, because C4Context cannot style nodes.

Verification

Both acceptance claims were machine-checked, not eyeballed:

• Every node → parsed the mermaid block, matched each node's first label line against go list. Result: every non-PLANNED node is a real package; every PLANNED node carries the marker; zero unmarked non-existent elements.
• Every solid edge → matched each drawn pair against the real import set from go list -f '{{.ImportPath}}|{{.Imports}}'. Result: 20/20 backed by a real import. This caught two errors mid-lane: a forge/gitlab → change edge that does not exist, and a hash → decision edge that does not exist.
• Package map → exactly the 22 internal packages + cmd/assent; no missing, no extra.

Notable finding

internal/core/hash (ADR-0017 canonical digests) has no production importer at this commit — only internal/change tests import it. Same for internal/schemadrift (test-only importers). Both are documented in a new "Packages with no production importer" section rather than drawn with a fake edge. AUD-S16 is specified to wire internal/compare → hash, so that row is explicitly dated "at this commit" and names S16.

Scope notes

• docs/vision.md is outside the stated docs/architecture/** ownership. It is in scope under the story's "check for the same lie elsewhere" clause. Three word-level edits only (Rego-as-present-tense ×2, "GitLab + GitHub" ×1) — no prose rewrite. docs/architecture/policy-profiles.md got one word-level fix (assent compare described as future; E6 shipped).
• ADRs deliberately untouched — dated records, and ADR-0004 already says "gRPC deferred" in its status line.
• internal/** untouched (another lane owns it).

Residuals for the backlog

1. internal/README.md documents 21 packages; go list returns 22 — internal/core (test-only purity guard) is missing from its tables. Not fixed here: internal/** is another lane's scope.
2. Nothing gates these diagrams. A follow-up could turn the two verification scripts used here into a real drift test (go list vs the mermaid block), the same way cmd/assent/main_clidoc_test.go pins docs/usage/cli.md. Without it, ARCH-05 can rot a fourth time.
3. ADR-0010 still shows an unmarked .assent/rego/ layout (docs/adr/0010-config-files-repo-layout.md:29,102,105 — an escape-hatch directory, a tier 2: rego rule, and rego: { file: ../rego/naming.rego }), presented as current repo layout. Deliberately not fixed here: ADRs are dated records and rewriting them exceeds this story. It is the highest-value thing a fourth ARCH audit would find, so it is logged rather than left implicit.
4. docs/architecture/policy-profiles.md is not in the mkdocs nav — published-adjacent but unreachable. validation.omitted_files: info means it can never fail the build. Noted because this lane edited the file.
5. npm is offline in the lane environment, so the mermaid source could not be parsed. Closed by review — both blocks parse cleanly under mermaid 11.16. Note for the future: task docs-build still does not validate mermaid (superfences only emits <pre class="mermaid">), so this was verified by hand, not by a gate. The PLANNED markers live in the label text rather than only in classDef, so AC1 holds even if the dashed styling fails to render.

Gates

Gate	Result
task docs-build (strict)	green
task check (full, incl. changelog-verify)	green apart from a pre-existing flake — see below
task changelog-verify standalone	green; working tree changelog-clean at the tip

Correction to an earlier version of this body, which claimed task check was "green, exit 0, zero failures" without qualification. That was one observation, not the whole picture. TestExecDigestPin/match_allows_exec fails intermittently with signal: killed — the test spawns a real binary against a ~1s deadline and loses the race under full-suite -race load. Observed here: red on run 1, green on runs 2 and 3 (exit 0); green standalone and green under -race on its own package. The independent reviewer reproduced the red and confirmed it fails identically on the base commit 7247e6d, against a Go file this markdown-only diff does not touch. So it is a pre-existing, load-dependent flake that does not count against this lane — but it is not honest to report an unqualified green. The flake is being handled separately; deliberately not fixed here.

[konih]

Review fixes pushed — b26e2c2 (S17-01 + S17-03) and 793db40 (changelog regen). PR body corrected for the task check claim; residual #5 marked closed per the mermaid 11.16 validation.

S17-01 — the composition-root claim is now derived, not asserted. go list -f '{{.Imports}}' ./cmd/assent returns 15 internal packages + root schemas; go list -deps adds internal/glob and internal/render/locale transitively; the remaining five (internal/core, internal/core/hash, internal/schemadrift, internal/forge/fake, internal/forge/conformance) are not linked into the binary at all — exactly the no-production-importer table. 15 + 2 + 5 = 22, so the page now accounts for every internal package. Both derivation commands are named inline.

S17-03 — vision.md §Modes now splits shipped (CI job, local dry-run) from planned (explain, historical scan feeding stats, webhook service), notes what covers each today (DecisionRecord and assent compare), and links usage/walkthrough.md, which already marked all three Planned. The self-inconsistency in the docs tree is gone.

Changelog — extended rather than amended: c6045b2 was already pushed and rewriting it would need a force-push this lane isn't authorized to do. task changelog-verify exits 0 and the working tree is clean at 793db40.

Not touched, per routing: S17-02 (drift gate for these pages) and S17-08 (marker-grammar.md). Not touched: the TestExecDigestPin flake.