docs: architecture principles mapped to enforcing gates and open ledgers

[thymikee]

Summary

Adds a "Principles and their gates" subsection to CONTEXT.md's Architecture section: the Clean-Architecture-shaped rules this repo runs on, each mapped to its enforcing gate and, where the rule is still bent, its open ledger (rule → gate → ledger).

Covers: the Dependency Rule (layering R1–R3/spine, #1405 as executable DIP, R6 TYPE_INVERSION_BASELINE as the shrinking ledger), acyclicity (R4 + the depgraph report of deliberately tolerated cycles), policy×detail boundaries on demonstrated axes (two registries, publicPlatformString leak guard, runnerProvider transport seam), information hiding (R7 per-field SessionState ownership), the boundaries-are-earned norm with its local evidence (#1409 viewer rejected, platform-descriptor layer deleted), test/interface coupling, and the rule that component metrics (instability/abstractness per zone) land as observatory data in #1423, never as CI thresholds.

Why

The guards exist and bite; the why behind them lived in ADRs, PR threads, and chat. One page in the domain-context file gives contributors and agents the argument to use when judging a design change and the gate to satisfy when landing it. Relates to #1412.

Validation

Docs-only; pnpm format applied, no behavior change.

Scope

1 file touched, docs-only (CONTEXT.md). No command-family scope expansion; no code, schema, or gate behavior changes.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.85 MB	1.85 MB	0 B
JS gzip	592.7 kB	592.7 kB	0 B
npm tarball	706.9 kB	706.9 kB	0 B
npm unpacked	2.47 MB	2.47 MB	0 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.0 ms	27.6 ms	+0.6 ms
CLI --help	56.8 ms	56.8 ms	+0.0 ms

Top changed chunks: no changes in the largest emitted chunks.

[thymikee]

Reviewed exact head 41dd255f. The layering R1–R7 descriptions are mostly accurate, but the architecture page is not ready:

• P1: it documents scripts/depgraph/ as a present report and says feat(scripts): dependency-graph report over the layering gate's model #1410 “stayed,” but this head has no depgraph directory/package script and feat(scripts): dependency-graph report over the layering gate's model #1410 is still open with unresolved P1 findings. Reframe this as dated/non-normative branch work or sequence the dependency after feat(scripts): dependency-graph report over the layering gate's model #1410 is actually accepted.
• P2: the rule→gate→ledger section overstates limited evidence as universal enforcement. publicPlatformString guards serialized public outputs; runnerProvider tests one adopted seam, not every policy/detail boundary. The second-consumer and stable-interface statements are norms/future hardening, while Umbrella: test-strength, gate-tightening, and code-observatory tracks #1412 remains open. Scope these claims to the concrete guards that exist.
• P3: add the required PR-body scope disclosure: 1 docs-only file, no command-family scope expansion.

Keep ready-for-human withheld.

[thymikee]

All three addressed at 802f9a1:

• P1: the acyclicity and component-metrics bullets no longer present scripts/depgraph/ as existing tooling — both now name it as proposed in feat(scripts): dependency-graph report over the layering gate's model #1410 (open, in review), with the feat(scripts): interactive dependency-graph viewer, with when-to-use guidance #1409-viewer-rejected framing kept as the design lesson. Nothing in the section depends on feat(scripts): dependency-graph report over the layering gate's model #1410 landing.
• P2: claims scoped to the guards that exist. The intro now states that bullets distinguish gate / ledger / norm. publicPlatformString is described as gating one specific DTO class (internal apple in serialized public output), runnerProvider as one adopted seam, R7 as covering SessionState only, and boundaries-are-earned + stable-interface testing are labeled norms whose only gated slice is the test-only-DI-seam workflow. Wider coverage is explicitly "direction, not current enforcement".
• P3: PR body now carries the scope disclosure — 1 docs-only file, no command-family scope expansion.

🤖 Addressed by Claude Code

[thymikee]

Re-reviewed exact head 802f9a142. Clean: CONTEXT.md now accurately distinguishes enforced rules, ratcheted ledgers, local norms, and proposed analysis; R1–R7 and the narrow serialized-output/DI-seam claims match their actual guards, while #1410 and #1423 are correctly described as proposals. All completed checks are green; pending iOS smoke is not a code-review blocker. Minor non-blocking editorial follow-up: the PR body still says every principle maps to a gate/ledger even though the corrected document also includes norms.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-27 12:29 UTC