docs(architecture): make the docs true and put tripwires behind the layout rules

[LKSNDRTMLKV]

Three commits: correct every documented claim that had drifted from the code, bring the code layout standard into the repository, and put a tripwire behind each of its rules.

Why these belong together

The layout standard already existed — five numbered rules, written 2026-07-04. Exactly one of them had a test, and it is the only one that had not drifted:

Rule	Test?	Violations found
2 — mod.rs is a pure index	✅	0
1 — one public type per file	❌	37 files; worst declares 12
4 — split a tests.rs past 400 lines	❌	12 files; worst is 1,232 lines
6 — only lib.rs at src/ root	❌	33 files
7 — tests in a sibling file	❌	71 inline test modules
8 — every file opens with //!	❌	28 files

181 violations across five unenforced rules, zero across the enforced one. Nobody ignored anything on purpose — the rules simply had nothing watching them, and a rule with nothing watching it is a preference. Preferences lose to deadlines.

No files move in this PR. The rules now bind for all new and moved code; the existing backlog is worked through separately.

1. Where the standard was, and why nobody followed it

The rules lived in an archived directory in a different, private repository, and mod_rs_is_pure_index.rs cited that path from this public repo — which CLAUDE.md §6 forbids in terms. So four of the five rules were invisible to anyone working here, and the pointer to them was itself a leak. Both are fixed: the standard is now docs/architecture/CODE-LAYOUT.md, and the comment points at it.

Rules 6–10 are new, and each closes a place where practice had actually diverged: the lib.rs-only convention, sibling test files, module docs, one name for test scaffolding (test_support.rs, not fixtures.rs), and naming that separates structural tripwires from behavioural tests.

Rule 3 is demoted to guidance and labelled as such. "Free functions group by verb-domain" cannot be tested without a definition nobody would agree on, and an unenforceable rule sitting in a list of enforced ones is what teaches a reader the list is decorative.

2. How the tripwires behave

Each carries a baseline of the files that already violated it. Those pass; anything not on the list fails. A stale entry also fails, so a fixed file has to be pruned or the list stops describing anything.

Three design points worth review:

• The baseline keys on path only. An earlier draft keyed on path (892 lines), which would have failed the build every time anyone touched a baselined file for an unrelated reason. A tripwire that fires on innocent edits is one that gets deleted.
• Crates and plugins are discovered from the tree, not listed. A hardcoded roster is how a new crate ends up silently unchecked — the same failure as the WASM job that sat broken through an entire stack last week because it named ten directories literally.
• // LAYOUT-DEVIATION: <reason> exempts a file. A rule with no escape hatch gets deleted the first time it is inconvenient; a rule with a greppable, reasoned escape hatch survives. Do not add to a baseline to go green — a baseline entry states nothing, a marker has to state why.

Verified to fail

Per the standard's own rule, a gate nobody has watched fail is a gate nobody knows is wired. All four behaviours were exercised before this was committed: a probe file violating rules 1, 6, 7 and 8 plus an over-long tests.rs — all five red; adding the deviation marker — all five green; a fabricated baseline entry — red, naming the stale path; probes removed — green.

3. The documentation corrections

• 🚨 A wrong regulatory citation. PORTS.md attributed ArchivePort to ESPR Art. 13, which is the registry. The back-up duty is Art. 10(4), "independent third party" is Art. 2(32), and the availability period is Annex III(i). Fixed, and the confirmed citations added to archive.rs, which described the substance correctly but cited nothing. Every other Art. 13 reference in the codebase was checked and is genuinely about the registry.
• An unsourced number. OVERVIEW.md claimed retention of "10-20 years". Every figure recorded in every instrument manifest is 10, several marked Assumed. Replaced with how the value is actually derived.
• The base passport table was missing 15 of the 34 wire keys, and the product-group rename had corrupted the dispatch row to `product group` in both the Rust and JSON columns. Rewritten complete, pointing at PASSPORT_WIRE_KEYS as the authority since that constant is asserted against.
• DATA-MODEL.md contained zero occurrences of "instrument". New §3.5 covers the three-record shape, why applicable law is a set (Art. 5(7), no precedence rule anywhere), the three folds, why "may this bind" is never folded to a boolean, and PassportObligation's third state.
• §4.5 was factually wrong — it claimed ElectronicsData does not exist. It does, at v1.2.0. Replaced with a table of all twelve product groups, and the UnsoldGoodsReport divergence from Impl. Reg. (EU) 2026/2 is now recorded where the type is documented.
• Two docs omitted dpp-vocab entirely and undercounted crates (9 → 12) and product groups (11 → 12).
• Two false claims about the dependency graph. lib.rs (published rustdoc) and VERSIONING.md both stated every crate depends on dpp-domain. Six of eleven do not — and the VERSIONING.md copy was rationale build(deps): bump actions/upload-artifact from 4 to 7 #1 for lockstep versioning.

Where a count was the thing that goes stale, it is replaced with a pointer to the authority rather than a fresher number.

just check green — 1154 tests.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 55 complexity · 10 duplication

Metric	Results
Complexity	55
Duplication	10

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}