Skip to content

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

Description

@Polichinel

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

  • Rewrite the tree at :30-44 to the three shipped packages and thirteen real modules. Derive it
    from find src -name '*.py' | sort, not from memory.
  • Drop weight_frame.py and mask_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.
  • Un-mark target_frame.py as "(anticipated)".
  • Add metadata.py, _typing.py and the conformance/ subpackage, each with the same
    one-line-purpose + Category annotation the existing entries carry.
  • Add views_frames_summarize/ and views_frames_reconcile/ — at minimum as package-level
    entries with their charters (ADR-017, ADR-023) and the note that siblings never import each
    other.
  • Add a **Last reviewed:** YYYY-MM-DD line at the top, matching the CIC convention, so the next
    drift is detectable.
  • Update C-84 in the register to RESOLVED. State what was verified — e.g. the module list was
    diffed against find src -name '*.py' — not what was intended (register C-77).

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)

Metadata

Metadata

Assignees

No one assigned

    Labels

    blockedBlocked on a dependency or decisiondocumentationImprovements or additions to documentationriskTechnical risk registerstoryA single story within an epic

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions