Part of epic #240. Blocked by S1 (#241) — both stories edit
docs/standards/physical_architecture_standard.md. S1 corrects the layering paragraph at :48-49 and
the Circular Dependency Guard at :67; this story rewrites the tree those lines sit under. Running
them in parallel conflicts, and running this one first ships the file half-corrected.
The problem
docs/standards/physical_architecture_standard.md is 78 lines, undated and unversioned, and its
authoritative directory tree (:30-44) is a pre-implementation design sketch that was never revised
after the package was built.
Measured against find src -name '*.py' (13 modules across 3 packages):
| Claim in the tree |
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 from the tree — and it has the highest fan-in in the leaf (8) |
conformance/ |
missing from the tree — the one surface whose primary caller is another repository (ADR-016) |
views_frames_summarize/ |
absent entirely |
views_frames_reconcile/ |
absent entirely |
Eight of thirteen real modules, one of three packages, two phantom files.
Why it matters
This is the document a contributor is pointed at to answer "where does this file go?", and ADR-007
treats agents as untrusted contributors who read exactly these documents. It is also the operational
companion to ADR-002 — the one that states the one-concept-per-file rule that
tests/test_import_enforcement.py::test_one_concept_per_file enforces.
Being undated is the compounding problem: every CIC carries a **Last reviewed:** line and all
eight are current (2026-06-24 to 2026-07-31). This standard has no such marker, so its staleness is
invisible to inspection and to validate_docs.sh.
Work
How we know it is done
- Every path in the tree exists, and every
src/**/*.py module appears in the tree. Check
mechanically:
find src -name '*.py' | sed 's|src/||' | sort > /tmp/actual.txt
# then confirm each appears in the standard
- The document carries a
**Last reviewed:** date.
- No "(anticipated)" marker refers to something that shipped.
bash docs/validate_docs.sh passes.
- The layering paragraph and Circular Dependency Guard from S1 are still correct — this story must not
regress them.
Notes on scope
Do not expand this into rewriting the standard's rules (the one-concept-per-file rule, the naming
convention, the Category taxonomy). Those are accurate and enforced by tests. This story fixes the
tree and the date, nothing else.
Relevant files
docs/standards/physical_architecture_standard.md (the only file changed, plus the register) ·
reports/technical_risk_register.md (C-84) · tests/test_import_enforcement.py::test_one_concept_per_file
(the test that enforces the rule this document states)
Part of epic #240. Blocked by S1 (#241) — both stories edit
docs/standards/physical_architecture_standard.md. S1 corrects the layering paragraph at:48-49andthe Circular Dependency Guard at
:67; this story rewrites the tree those lines sit under. Runningthem in parallel conflicts, and running this one first ships the file half-corrected.
The problem
docs/standards/physical_architecture_standard.mdis 78 lines, undated and unversioned, and itsauthoritative directory tree (
:30-44) is a pre-implementation design sketch that was never revisedafter the package was built.
Measured against
find src -name '*.py'(13 modules across 3 packages):weight_frame.py"(anticipated)"mask_frame.py"(anticipated)"target_frame.py"(anticipated)"metadata.py_typing.pyconformance/views_frames_summarize/views_frames_reconcile/Eight of thirteen real modules, one of three packages, two phantom files.
Why it matters
This is the document a contributor is pointed at to answer "where does this file go?", and ADR-007
treats agents as untrusted contributors who read exactly these documents. It is also the operational
companion to ADR-002 — the one that states the one-concept-per-file rule that
tests/test_import_enforcement.py::test_one_concept_per_fileenforces.Being undated is the compounding problem: every CIC carries a
**Last reviewed:**line and alleight are current (2026-06-24 to 2026-07-31). This standard has no such marker, so its staleness is
invisible to inspection and to
validate_docs.sh.Work
:30-44to the three shipped packages and thirteen real modules. Derive itfrom
find src -name '*.py' | sort, not from memory.weight_frame.pyandmask_frame.py. If the intent to add frame types should survive,state it as prose ("new frame types are additive MINOR, ADR-018") rather than as phantom files
in an authoritative tree.
target_frame.pyas "(anticipated)".metadata.py,_typing.pyand theconformance/subpackage, each with the sameone-line-purpose + Category annotation the existing entries carry.
views_frames_summarize/andviews_frames_reconcile/— at minimum as package-levelentries with their charters (ADR-017, ADR-023) and the note that siblings never import each
other.
**Last reviewed:** YYYY-MM-DDline at the top, matching the CIC convention, so the nextdrift is detectable.
diffed against
find src -name '*.py'— not what was intended (register C-77).How we know it is done
src/**/*.pymodule appears in the tree. Checkmechanically:
**Last reviewed:**date.bash docs/validate_docs.shpasses.regress them.
Notes on scope
Do not expand this into rewriting the standard's rules (the one-concept-per-file rule, the naming
convention, the Category taxonomy). Those are accurate and enforced by tests. This story fixes the
tree and the date, nothing else.
Relevant files
docs/standards/physical_architecture_standard.md(the only file changed, plus the register) ·reports/technical_risk_register.md(C-84) ·tests/test_import_enforcement.py::test_one_concept_per_file(the test that enforces the rule this document states)