S2 — Rewrite the physical-architecture standard's directory tree (closes C-84)

[Polichinel]

S2 of epic #240. Closes #242 and register C-84. Documentation only — src/ untouched, no public API change, CONFORMANCE_FLOOR stays 1.0.0.

Depended on #252 (S1), which corrected the layering paragraph in this same file. That is why these were separate stories: S1 owned :48-49 and :67, S2 owns the tree those lines sit under.

The problem

docs/standards/physical_architecture_standard.md §2 held the repository's authoritative directory tree — the document a contributor is pointed at to answer "where does this file go?", and one ADR-007 expects agents to read. It was a pre-implementation design sketch that was never revised after the package was built:

Claimed	Reality
weight_frame.py "(anticipated)"	never shipped
mask_frame.py "(anticipated)"	never shipped
target_frame.py "(anticipated)"	shipped in v1.0.0, has its own CIC
metadata.py	missing from the tree
_typing.py	missing — and it has the highest fan-in in the leaf (8)
conformance/	missing — the one surface whose primary caller is another repository
views_frames_summarize/	absent entirely
views_frames_reconcile/	absent entirely

Eight of thirteen leaf modules, one of three packages, two phantom files. The document was also undated, so its staleness was invisible — every CIC carries a Last reviewed line and all eight are current; this standard had nothing.

What changed

• §2 rewritten to all three shipped packages and all 36 modules, ordered by the ADR-002 layering S1 corrected, with the ADR-001 category annotated on each file that has one.
• _typing.py and conformance/ marked as having no category, and why — one is a typing helper (C-19), the other verifies the ontology rather than belonging to it (ADR-016). Inventing category numbers for them would have been worse than saying so.
• A Last reviewed date and a perishability note at the top: the tree is authoritative and therefore perishable; update it in the same change that moves a module.
• The phantom frames are replaced by a sentence recording the actual rule — new frame types are additive MINOR (ADR-018) and belong in the tree the day they ship, not before — plus what carrying them cost.

Verification

Per the refinement S1 added to C-77, the check matches the shape of the claim rather than a fixed phrase, and was mutation-tested in both directions before being trusted. It parses the fenced tree and diffs it against src/**/*.py:

$ python3 treecheck.py
source modules: 36
missing from tree: none
in tree but absent from src/: none
packages absent from tree: none
exit=0

$ # mutation 1 — reinstate a phantom module in the tree
in tree but absent from src/: ['weight_frame.py']          exit=1

$ # mutation 2 — hide a real module from the tree
missing from tree: ['views_frames/metadata.py']            exit=1

Both failure directions are caught, which is what makes the green run mean anything. This is the lesson from S1, where C-82's first verification pasted real output from a real command and still missed two surviving occurrences because the command could not have found them.

$ bash docs/validate_docs.sh   → PASSED
$ uv run ruff check .          → All checks passed
$ uv run ruff format --check . → 77 files already formatted
$ uv run mypy src/             → no issues in 36 source files
$ uv run lint-imports          → 2 kept, 0 broken
$ uv run pytest --cov --cov-fail-under=100 → 100.00%, green

Two contradictions the rewrite surfaced, fixed here

Extending the tree to three packages made two existing sections wrong. Both were created by this change, so both are fixed in it rather than deferred:

• §3 forbids utils/helpers/common dumping grounds — while the newly-visible views_frames_summarize/_common.py and views_frames/_typing.py carry exactly such names. §3 now states why each is a focused module (two functions with one responsibility; two array aliases) and that a third unrelated concern is the signal to split, not to widen the exception.
• §5 said compliance would be audited "once the leaf is stood up" — it has been released for months. It now names the two rules that are machine-enforced (test_one_concept_per_file for §1; the import-linter contracts and test_package_dependency_dag for §4) and states plainly that the tree is not machine-checked — it is kept current by the review note at the top.

Deliberately not done

The tree check is not folded into docs/validate_docs.sh. It is a natural fourth assertion alongside S6's three (#246), but that script is bash-and-grep by design — the docs CI job installs no Python on purpose — and parsing a fenced tree is the one candidate of the four that plausibly cannot be done in bash. Recorded on #246 for S6 to decide rather than pre-empted here.

Section 1's rules, the naming convention, and the Category taxonomy are untouched. They are accurate and test-enforced. This story fixed the tree, the date, and the two contradictions the tree created.

Register

C-84 closed and moved to Resolved: open 17 → 16, resolved 65 → 66.

🤖 Generated with Claude Code