Epic: risk_documentation becomes a per-unit coverage ratio (Phase 4 score contract; child of #2812)

[squid-protocol]

Child of #2812 (Phase 4 · score contracts). First formula to get a score contract; the pattern here is meant to be reused for risk_api_exposure, risk_tech_debt and func_complexity_gini, the other score-layer rows still carrying open-defect cells.

Labels: epic metrics core-engine roadmap

Why this epic exists (one paragraph)

_calc_documentation does not measure documentation. On the rosetta corpus every term but one is flat: no function has impact above 50 (the "opaque execution" term is dead), every file is under the 50-line evidence floor (the denominator is a constant 70), and the multipliers do not move the observed values. What remains is a sigmoid over 2 × api, so one adjusted-api hit per file is worth about 13 points on a 0–100 scale. The adjusted api count is assembled from two overlapping sources (the language's api rule plus the orphan-census credit, minus a tokenizer-dependent overlap), and every way that assembly fails lands in a different score cluster: 79 where a name is counted twice (m4, makefile, scheme, cobol), 55 where the rule sees one token and the census credits three (css, agc_assembly, yacc), 18 where the census is unanswerable or broken (dockerfile, html, yaml, haskell), 0 where the rule matches nothing (jcl, sqlite, objective-c main). On real code the same equation flips regime: a 500-line file with the same three undocumented public functions scores about 15, because the denominator is now the file length. That is the −0.83 length leak the bias report already flags, seen from the other side. Four of the eleven open-defect cells on the scoreboard and the corpus's single confirmed length leak are this one formula.

The goal restated: risk_documentation is the share of a file's callable surface a reader cannot recover from documentation. A ratio over units, not a density over lines. Identical intent scores identically by construction, not by tuning.

The contract

risk_documentation — of the units extracted from a file (functions, methods, paragraphs, steps), the weight-share that is undocumented. A unit is public when its name is in the file's public name set. A unit is documented when a doc-rule match is anchored to its header window. Public units weigh double; a unit's weight rises by one per reflection_metaprogramming hit inside it. A folder-level documentation umbrella shields the whole file multiplicatively. A file with no extracted units has no value (n/a), not zero.

for each extracted unit u:
    weight(u)  = (2 if public(u) else 1) + reflection_hits_inside(u)
    exposed(u) = weight(u) if not documented(u) else 0

risk_documentation = 100 × Σ exposed(u) / Σ weight(u) × (1 − umbrella_shield × doc_umbrella)
                   = n/a when Σ weight(u) = 0

Definitions that carry the contract:

• public name set = names the api rule matched on the unit's own header ∪ names in an export list (_visibility_export / _visibility_export_list, the unreferenced_by_name reads 0.25/file for haskell and scheme: a module export list and a type signature are declarations, not references #2823 machinery) ∪ units left uncalled in a file that something imports (the Contextual Baseline Fix's orphans). A union of names: a unit cannot be public twice, and a tokenizer miss costs one unit rather than doubling the file. This is the per-unit form of raw_arch_api bands a per-file declaration count against a per-function median — one granularity mismatch, three red columns #2771's complaint (a per-file declaration count banded against a per-function median).
• documented = a doc-rule match whose span ends inside the unit's header window: the k lines immediately before start_line, or the leading lines of the body (docstring position). Not the slicer's docstring field, which is a per-language "preceding comment" heuristic: on the corpus it captures python's planted # HACK: comment as a docstring, reads 13 of 13 for jcl, and 0 for fortran, haskell and scheme.
• reflection inside the unit is engine PR 2: per-file dynamism count replaces the flat irc term (child of #2716) #2719's dynamism kept where it belongs: runtime-decided behaviour raises the weight of that unit instead of adding a hit to a file total.
• umbrella = doc_umbrella as today (GuideStar folder coverage, README-upgraded). The only file-level defence that survives.

What leaves the equation, with the reason:

term	why it goes
doc_loc × 0.33	a comment-line count is not coverage, and it is one of the two length terms
ownership × 0.5	who maintains a file is a different question, already carried by silo/authorship views
opaque_execution (impact > 50 ∧ no docstring)	dead on small functions; its intent (load-bearing undocumented code) is what public weighting expresses
/ (_mass_loc(loc) + 20) and the sigmoid	the length regime; the ratio is already 0–100
popularity and silo multipliers, path modifier mp	blast radius sits next to the score in the same report row; a coverage ratio does not change because the file lives in a config folder
doc_weight, ownership_weight, doc_loc_weight, loc_smoothing, threshold_base, sigmoid_slope	six knobs become two: public_weight (2.0), umbrella_shield (0.5)

Weights are counts, not lengths. Per-function impact contains 0.05 × effective_loc; weighting by it re-imports length through the side door. Impact stays the hitlist's ranking key.

Decisions to approve before Phase 2 starts

• D1 The score is a ratio over extracted units; no per-LOC term, no sigmoid, no small-file floor.
• D2 public(u) is the name-set union above. This is the same set risk_api_exposure should read; that formula's own contract is a separate epic but shares Phases 1–2 here.
• D3 documented(u) is the header-anchored doc match, not docstring. docstring is left as is (it feeds the brief's text), not deleted.
• D4 Ownership, doc_loc, opaque_execution, popularity/silo multipliers and mp leave the equation. path-and-extension-modifiers in the ledger drops risk_documentation from its signal list when this lands.
• D5 No damping knob for one-unit files (0 or 100). Roll-ups are already mass-weighted. Revisit only if Phase 5 shows hitlist noise.
• D6 Engine keeps emitting a float; n/a is inferred by the reporting layer from unit count 0, the same convention the corpus tooling already uses for rule absence (no None in the risk vector).

Expected values (acceptance numbers)

file	today	after
rosetta a/b/c, every language	17.9 → 79.2 depending on api assembly	100 (3 public units, 0 documented)
rosetta main, entry documented	33.4	75 where the api rule sees entry, 86 where it does not (an api contract cell, surfaced on purpose)
css, yaml, html, sqlite, markdown	0 → 55	n/a
500-line file, 10 public units, 2 documented	≈ 15	80
20-line file, 3 public units, 0 documented	40.6	100
length-leak row (bias_report.md)	rho −0.83, leak	rho 0 by construction

Phases

• 0 · Design freeze gitgalaxy — docs/risk_documentation_contract.md (the contract sentence, the equation, the leave-list table, D1–D6), and the per-unit decomposition that produced the cluster table above committed as tests/tools/audit_documentation_inputs.py (scan → per-file arch_api, credit, doc_loc, score; reproduces every corpus score from the inputs). Approve D1–D6 on this issue.
  done when the contract doc is merged as draft and the acceptance table above is agreed.

• 1 · The name set is right before anything reads it gitgalaxy + keyword-rosetta — prerequisites, all already filed or owed:

  • api_declared_orphans tokenizes api lines with \b\w+\b, so a hyphenated or qualified name is never recognised as already-declared (#2731's double count returns for cobol and scheme) #2827 — api_declared_orphans tokenizer (\b\w+\b cannot see PROBE-GLOBALS, probe-globals); cobol + scheme, 3 cells
  • m4/makefile corpus re-plant against Add visibility-export rules for m4 and makefile (#2872) #2902's export rules (engine half merged; corpus half owed, keyword-rosetta#53 lineage); 4 cells
  • Contextual Baseline Fix reads a weaker dependency resolver than every column it is audited by (haskell) #2871 — haskell module names invisible to the popularity tally, so the credit never fires and orphans stay; 1 doc cell + the tech-debt outlier
  • c api rule counts top-level variable declarations as public surface (a.c reads api 5 for 3 functions; +25.0% sits at the band edge) #2907 — c's api rule counts top-level variable declarations (int shared_region = in data/c/a.c reads api 5 for 3 functions); raw_arch_api 3.75 vs median 3 sits at exactly +25.0%, in band by zero margin, unledgered
    done when arch_api reads 3 in every a/b/c file that has an api rule, and the risk_api_exposure / raw_arch_api / risk_documentation open cells attributable to these are 0.

• 2 · Per-unit attributes in the detector gitgalaxy (T2) — three attributes on every extracted unit: is_public (name-set union, D2), is_documented (header-window doc match, D3), reflection_hits (the unit's own reflection_metaprogramming count, already sliced per function). Recorded as three function_data columns and in the audit JSON. Counts do not move: golden masters change by new columns only.

  • detector: _public_name_set(file) from api header matches + _export_declaration_offsets + healed orphans; _doc_anchored(unit) over the comment stream (the doc rule reads comments, per ownership has no stated contract: solidity counts the SPDX license line on every file, five languages count copyright notices and license prose, three count the phrase 'created by' in sentences, and five doc rules still double-count the author tag #2882's stream convention)
  • contract tests in tests/core_engine/test_detector.py: one per declaration family (docstring-position, preceding-block, export-list, positional-invocation languages)
  • keyword-rosetta: verify_language.py reads function_data; manifests gain units_public / units_documented per file; the rule-contract-audit skill run once across 46 languages for the two attributes
    done when 46/46 languages read public = 3, documented = 0 in a/b/c; main reads documented = 1 (entry) and public 3 or 4 with the split ledgered against the api contract; no unexplained cell.

• 3 · The equation gitgalaxy (T2, label rosetta:rebless-owed) — replace _calc_documentation with the ratio; delete the six tuning keys in analysis_lens.py, add public_weight and umbrella_shield; call site in signal_processor.py passes units + umbrella only.

  • tests: tests/core_engine/test_signal_processor.py (new pins), test_uef_length_invariance.py and tests/tools/audit_length_invariance.py (documentation is now exactly length-invariant: assert equality, not tolerance), tests/tools/audit_risk_equations.py (no tier/fid term left to audit for this formula)
  • golden masters: both legs re-blessed via tests/tools/crucible_check.py --update --yes; every file's documentation score moves, so the diff is scoped by the decomposition tool before blessing
  • prose that prints the equation: llm_recorder.py ("12. Documentation Risk Exposure …"), docs/wiki/08-03-transforming-regex-counts.md (the dynamism row), docs/gitgalaxy_architecture_brief.md self-scan regen
    done when both golden legs are blessed with a scoped diff, the length audit reads rho 0, and the corpus reads the acceptance table.

• 4 · Corpus re-bless and scoreboard keyword-rosetta — manifests to the acceptance values; ledger: path-and-extension-modifiers drops risk_documentation, m4-makefile-api-scores-above-stratum and the api-declared-orphans-blind-to-non-word-names documentation half retire on Phase 1's verifying scan; bias_report.py: risk_dependencies() learns the per-unit inputs so a documentation cell attributes to a unit, reads_constant flips to False (the formula stops reading fid, so the metric is no longer banded within a strictness stratum, which today hides yacc at +28% against the global median), the leak table row becomes the proof.
  done when risk_documentation is 46/46 in band (n/a where declared), 0 open, and the report bands it against the global median.

• 5 · Real-code validation gitgalaxy — before/after on the language-crucible and on the two README example repos (curl, cics-genapp): score distribution, top-20 documentation hitlist diff, count of one-unit files at 100 and whether any reaches a hitlist. Decide D5 on evidence. docs/incidence_report.md in keyword-rosetta gains the documentation row.
  done when the before/after comment is on this epic and D5 is confirmed or a damping design is filed as its own issue.

• 6 · Closure — the contract row goes stated (score contracts get their own section in signal_contracts.py / docs/signal_contracts.md, the first entry); docs/contract_roadmap.md §4 Phase 4 marks this formula done; README "Accuracy, measured" copy refreshed with the live numbers (the paragraph still carries 2026-09-06's 90% / 2.7%; docs/validation.md carries 75% / 3 of 33).
  done when open-defect cells attributable to risk_documentation = 0, the sheet row is stated, and the next score contract (risk_api_exposure) can copy this epic's phase list.

Sequencing

0 design freeze ──► 1 name set (4 items, independent of each other)
                         │
                         ▼
                    2 per-unit attributes (counts unchanged)
                         │
                         ▼
                    3 equation + golden bless ──► 4 corpus re-bless ──► 5 real-code check ──► 6 close

Phase 1 and Phase 2 can run in parallel; Phase 3 must not start until both are merged, because the ratio reads the name set and a wrong set would be blessed into the golden masters. One layer per engine PR (rule | slicer | scoring), as #2812 rule 4.

Non-goals

• risk_api_exposure's own formula (its contract is the next epic; it inherits Phases 1–2 unchanged).
• Changing impact, docstring extraction, or the doc umbrella's computation.
• Any damping for small files unless Phase 5 shows the need (D5).
• Re-tuning any other _calc_*; the commensurability audit tool in Epic: contracts at every layer — stream, count, score (the rosetta roadmap; child of #2560) #2812 Phase 4 is a separate deliverable this epic will feed one worked example into.

Issue disposition

issue	action
#2827, #2871	Phase 1 prerequisites; keep, unchanged
#2872	closed (engine half #2902); the corpus re-plant is Phase 1 item 2
#2771 (raw_arch_api granularity)	answered by D2's per-unit name set; close when Phase 2 lands
#2719 (dynamism replaces flat irc)	kept, moved per unit (D1); no reversal
#2655 (evidence-mass floor)	the floor stays for the other density formulas; this formula stops reading it
bias report length-leak row for risk_documentation	resolved by construction in Phase 3; the row stays as the proof
keyword-rosetta risk-documentation-zero-evidence-guard (retired)	the guard's role (no surface → 0) becomes n/a (D6); note on the entry, no revival

Evidence behind the "why"

Sensitivity of today's equation to the adjusted api count per file (all other inputs at the corpus values, doc_loc = 2):

adjusted api / file	0	1	2	3	4	5	6	7
risk_documentation	0	17.9	27.9	40.6	54.8	68.2	79.2	86

Where the corpus lands and why (per-file scan of 20 languages against engine main, 2026-09-09; every score reproduced from the formula):

adjusted api / file	languages (a/b/c)	mechanism
6	makefile, m4, scheme, cobol	raw 3 + orphan credit 3: overlap check never recognises the names (#2827, #2872)
5	c (a.c only)	globals plants match the api rule as top-level declarations
4	css, agc_assembly, yacc	raw 1 + credit 3; yacc adds 4 reflection hits
3	the mainstream pack; objective-c via credit alone (raw 0)	intended
1	dockerfile, html, yaml (census n/a), haskell (#2871)	raw 1, no credit
0	jcl, sqlite, objective-c main	zero-evidence guard

[squid-protocol]

claiming Phase 0 — Fable 5.1 — branch design/risk-documentation-contract

status Phase 0: done pending CI — PR #2910 (docs/risk_documentation_contract.md as draft + tests/tools/audit_documentation_inputs.py). 46/46 corpus languages, 185 files, every recorded risk_documentation reproduced from its inputs at engine 81b895c.

Filed from the decomposition:

• c api rule counts top-level variable declarations as public surface (a.c reads api 5 for 3 functions; +25.0% sits at the band edge) #2907 — c's api rule counts the two globals plants as public surface (a.c api 5 for 3 functions; +25.0% exactly at the band edge). Added as Phase 1 item 4.
• meta['popularity'] is never set before calculate_risk_vector: the popularity terms in documentation, verification, api_exposure and the threat vector are dead #2909 — meta['popularity'] is never set before calculate_risk_vector, so the popularity terms in documentation, verification, api_exposure and the threat vector are dead. D4's removal of the multiplier is therefore score-neutral today. Not blocking.

D1–D6 are on the contract doc for review. Phase 1 next (#2907 first: smallest, unblocks c's cell).

[squid-protocol]

status Phase 1 / #2907: engine PR #2911 open (rosetta:rebless-owed), CI running. rule_probe crucible 1141 → 1040, rosetta 15 → 13, nothing gained; every lost match read. Corpus effect: c a.c api 5 → 3 only. Corpus re-bless of data/c opens after #2911 merges. Remaining Phase 1: #2827, #2871, m4/makefile re-plant.

[squid-protocol]

status Phase 1: #2907 merged (#2911); corpus re-bless keyword-rosetta#110 open and green. #2827 → engine PR #2914 open (rosetta:rebless-owed): cobol + scheme a/b/c api_orphan_credit 3 → 0, nothing else moves; golden masters blessed (14 lua/perl/zig files on the four api-fed keys). Corpus branch rebless/2827-declared-orphans (both manifests + ledger retirement) prepared, opens after #2914 merges. Remaining Phase 1: #2871 (haskell), m4/makefile re-plant.

[squid-protocol]

status Phase 1: all four items now have PRs.

• c api rule counts top-level variable declarations as public surface (a.c reads api 5 for 3 functions; +25.0% sits at the band edge) #2907 → c api: a file-scope variable is globals' hit, not public surface (#2907) #2911 MERGED; corpus keyword-rosetta#110 (+ the c comment decoy re-word decoy_check asked for).
• api_declared_orphans tokenizes api lines with \b\w+\b, so a hyphenated or qualified name is never recognised as already-declared (#2731's double count returns for cobol and scheme) #2827 → api_declared_orphans: test the orphan's real name, not \b\w+\b tokens (#2827) #2914 (CI running); corpus branch rebless/2827-declared-orphans ready, opens after merge.
• Contextual Baseline Fix reads a weaker dependency resolver than every column it is audited by (haskell) #2871 → Contextual Baseline Fix: case-fold the resolver for case-insensitive-import languages (#2871) #2915 (CI running): the orchestrator's resolver gains fortran USE targets resolve case-sensitively in the dependency DAG (uppercase legacy style loses the whole import graph) #2540's case-folded Stage 1c; haskell a/b/c orphans 3 → 0, risk_tech_debt onto the stratum median; golden masters unchanged; corpus branch rebless/2871-haskell-ledger ready (ledger retirement only), opens after merge.
• m4/makefile re-plant → keyword-rosetta#112 open now (engine half Add visibility-export rules for m4 and makefile (#2872) #2902 already on main): api_orphan_credit 3 → 0 in every a/b/c, nothing else moves, ledger m4-makefile-api-scores-above-stratum retired.

When #2914/#2915 and the three corpus PRs land, the scoreboard's 11 open-defect cells drop to 1 (makefile func_complexity_gini, its own ledger entry, no issue yet) and Phase 1's done-when holds: arch_api reads 3 in every a/b/c that has an api rule. Phase 2 (per-unit is_public / is_documented / reflection_hits) is next and needs D1–D6 approved.

[squid-protocol]

Efficiency assessment of this plan (2026-09-09, after Phase 0 + Phase 1)

Written from the session that ran Phases 0 and 1, so the numbers are what it actually cost, not a guess. The plan's phases are right. The way they were run was the expensive way, and the repo already owns the cheap way for rule contracts (.claude/skills/rule-contract-audit, .claude/agents/contract-audit-scout.md, tests/tools/bless_scope.py). None of it was used here because none of it names the score layer. The fix is to make the score-layer twin of that kit before Phase 2, not after, because this will not be the last formula (risk_api_exposure, risk_tech_debt, func_complexity_gini are queued on this same epic's pattern).

Where the tokens went (measured on Phases 0–1)

cost centre	what happened	what should have happened
Hand-rolled scripts, repeated	the per-file decomposition was written inline before it became a tool; the round-trip-preserving manifest/ledger JSON edit was written 4×; the lost/gained-lines diff for a rule change was written 2×; the scoped golden-master diff (golden_diff + bucketing) was written 2× although bless_scope.py already does it	one tool each, run by the scout
Everything in the orchestrator context	rule_probe dumps, crucible windows, 46-language audits, ledger verdicts (single entries run to 3 KB) were all read in the main context	scout returns digests; orchestrator holds ten digests, never a dump
Serial by hand	three Phase 1 fixes were built one after another in one context; each is independent (different files, different languages)	three build+scout pairs in parallel, orchestrator reads three digests
Environment traps	a worktree created at the wrong path (relative to -C), a background job launched from the wrong cwd (the shell's cwd had drifted), a stale corpus worktree that produced a phantom high_risk_execution mismatch, a cd inside a gh command that moved the shell for every later call	one worktree_env script that creates/refreshes and prints the exports; absolute paths always
CI polling	gh pr checks polled by hand a dozen times across four PRs	one --watch in the background per PR, then nothing until it notifies
PR bodies	the same four sections (Measured / Corpus / Golden masters / Tests) typed four times	generated from the tools' own output

The irreducible orchestrator work was small and is the only part worth the strong model: the contract sentence and D1–D6; the read-every-lost-line pass on a rule change (the first #2907 candidate lost 21 Doom K&R definitions — a scout would have reported "21 lost lines start with a bare return type", the decision was one line); the per-cell verdicts in the ledger; and the go/no-go on each bless scope. Everything else was retrieval, measurement and formatting.

What to build before Phase 2 (each is an issue: gitgalaxy #2916, keyword-rosetta#113)

Engine (tests/tools/):

• audit_score_inputs.py <risk_metric> — generalise audit_documentation_inputs.py: an adapter table per _calc_* (DB columns → call arguments, the EQUATION_CASES shape audit_length_invariance.py already uses), reproduce every recorded risk_<metric> from its recorded inputs, print the cluster table by dominant input and the sensitivity table, exit 1 on residual. Phase 0 of any score contract becomes one command and one digest. Also the tool that says, for a formula nobody has looked at, which input actually drives it.
• rule_probe.py --diff-lines before.json after.json — the lost/gained matched-lines listing (with 2 lines of context for multi-line matches). The read-every-lost-line pass is the orchestrator's; the listing is not.
• contract_pr_check.py — runs the gauntlet legs in parallel from one worktree (extraction tests for the touched languages, rosetta_audit against the corpus worktree at origin/main, crucible_check, bless_scope on the result, audit_check) and prints the PR-body block. One invocation, one digest, no retyping.
• worktree_env.sh <name> [--corpus] — git fetch, create or move gitgalaxy-worktrees/<name> (and keyword-rosetta-worktrees/<name>) to origin/main, print export PYTHONPATH= GITGALAXY_PATH= GALAXYSCOPE_BIN= LANGUAGE_CRUCIBLE_PATH= KEYWORD_ROSETTA_PATH= for copy-paste. Refuses to run inside the primary checkout.
• .claude/agents/contract-audit-scout.md: the environment section names /srv/storage_16tb/projects/gitgalaxy/v6/.venv, which is not this machine's venv (the working one is ~/nyx_projects/gitgalaxy/.venv, full precision at .crucible_venvs/full_precision). A scout dispatched today runs the wrong engine or fails on import. Fix the paths, add audit_score_inputs and contract_pr_check to its job list.
• .claude/skills/score-contract-audit/SKILL.md — the score-layer twin of rule-contract-audit: same tier table (orchestrator / scout / build / adversary), same "never delegate" list, phases = this epic's phases with the exact commands, the D-decision template, the acceptance-table template, and docs/_score_contract_template.md with the sections risk_documentation_contract.md uses (sentence · equation · what today's formula measures · leave-list with reasons · decisions · acceptance · consumers · phase map).

Corpus (keyword-rosetta/tools/):

• rebless.py <lang> --engine <worktree> --note "<dated sentence>" [--retire <ledger-id> --resolved-by gitgalaxy#N --verdict "..."] — scan with the named engine, diff observed vs manifest, apply only the cells that moved (printing them), append the note, retire the ledger entry, preserve the formatting the files actually use (manifest indent=2, ensure_ascii=False; ledger ensure_ascii=True), re-run verify_language. The 4× hand-rolled python, once.
• screen_plant.py --engine <worktree> — it hard-codes the primary checkout today (the skill already warns about this).
• open_rebless_pr.sh <N> (or a bias-history.yml step): when engine main carries Closes #N and a pushed branch rebless/<N>-* exists, open the corpus PR with the standard body. The engine-first merge order is inherent; the remembering is not. Three corpus branches sat pushed-but-unopened this session waiting on human merges.
• ledger_show.py <id> [--short] — id, signal, languages, disposition, status, the first and last 300 chars of the verdict. Reading a whole entry to check one field cost ~3 KB each time.

Per-phase checklists for THIS epic (copy into the phase comment when claiming it)

Phase 2 · per-unit attributes (gitgalaxy)

• worktree_env.sh fix-2908-p2; claim comment on this issue.
• ▸ scout: audit_score_inputs.py risk_documentation digest at engine main — the baseline every later step is compared to.
• orchestrator: write the exact spec for is_public (name-set union: api header match ∪ export-list names ∪ healed orphans), is_documented (header-window doc match; k lines before start_line or leading body lines), reflection_hits. Name the header window's k and the docstring-position rule per lexical family before any code.
• ▸ build: detector attributes + three function_data columns + audit JSON; contract tests per declaration family (docstring-position · preceding-block · export-list · positional-invocation).
• ▸ scout: rosetta_audit 46/46 (counts must not move — this phase adds columns only); crucible_check (expect new columns only; bless_scope leaf-key table must show no signal key).
• ▸ scout: per-language table of units_public / units_documented for a/b/c/main → orchestrator decides the 3-vs-4 dispatcher split per language against the api contract and ledgers it.
• corpus: verify_language.py reads the two new keys; manifests gain them (rebless.py --add-keys); one ledger entry for the split.
• contract_pr_check.py → PR body; label rosetta:rebless-owed; push the corpus branch before the engine PR merges.

Phase 3 · the equation (gitgalaxy)

• orchestrator: the equation is already written (§1 of the contract doc); confirm D1–D6 are approved on this issue. No code before that.
• ▸ build: replace _calc_documentation; delete six tuning keys, add two; update test_signal_processor.py, test_uef_length_invariance.py, audit_length_invariance.py (equality, not tolerance), audit_risk_equations.py; the brief text in llm_recorder.py; wiki 08-03.
• ▸ scout: audit_score_inputs.py risk_documentation at the new formula — every corpus file must read the acceptance table (100 / 75-or-86 / n/a); bless_scope on the golden masters — leaf-key table must be Documentation Exposure + its aggregates only; length-leak row rho 0.
• orchestrator go/no-go on the scope table; bless; contract_pr_check.py → PR body; rosetta:rebless-owed.

Phase 4 · corpus re-bless (keyword-rosetta)

• rebless.py for all 46 (one loop); path-and-extension-modifiers drops risk_documentation; bias_report.py's risk_dependencies() learns the per-unit inputs and reads_constant flips; na_check/decoy_check/ledger_orphan_check clean; open_rebless_pr.sh.

Phase 5 · real-code check — ▸ scout: before/after top-20 documentation hitlist on curl + cics-genapp + the crucible, count of one-unit files at 100; orchestrator decides D5 from the digest.

Phase 6 · closure — sheet row stated; roadmap tick; README + validation.md numbers refreshed (both still carry September-6 figures).

Rules of thumb that fell out of this session

1. Measure with a tool or not at all. Anything measured inline gets re-measured next session.
2. The orchestrator reads digests and lost lines, never dumps. If a tool's output is more than ~40 lines, it needs a --summary.
3. Every environment fact is a script, not a memory. Worktrees, exports, corpus location, venv: worktree_env.sh prints them; nothing else should.
4. Pre-build the corpus branch; automate the open. The merge order is the only serial dependency; nothing else in a phase should wait on a human.
5. Independent fixes run in parallel agents. Phase 1 was three independent engine PRs; run them as three build+scout pairs.
6. decoy_check after any api-rule change; a rule narrowing can drop a comment decoy below the floor (it did, for c).