Epic: contracts at every layer — stream, count, score (the rosetta roadmap; child of #2560)

[squid-protocol]

Child of #2560; supersedes #2669 as the handoff surface for cross-language consistency work. Strategy approved 2026-09-06. The document is docs/contract_roadmap.md (lands with #2811; formatted copy: https://claude.ai/code/artifact/debf7286-7958-48d6-91e5-48b1bbc4abc0). Read it before claiming anything here.

Why this epic exists (one paragraph)

The bias report's consistency badge paints every out-of-band cell the same red, whether the ledger validated it as "this language cannot express that" or as an open engine defect — so the scoreboard could not tell an extraction problem from a language fact, and the work kept looking like an extraction problem. Rolling the 267 gated red cells up by cause: 102 echo (derived), ~45 language inherency, ~50 extraction defects, 38 proximity-correlation effects, ~32 scoring choices. The largest engine-side finding is a layer leak, not a regex: core/spatial_correlation.py edits recorded signal counts in place (×3 cascading flux, silencer dampeners, ×5/×100 amplifiers; documented and pinned by #2631), so the count the corpus reads is never the raw count. The fix is a stated contract at each of the engine's three layers — what text a rule sees (stream), what one hit means (count), how counts combine (score) — and tooling that enforces them.

The goal restated: equal counts for equal constructs. Every remaining cross-language difference comes from one of three declared sources — a strictness stratum (design), an n/a (the language cannot express it), or a filed defect. After that a red dot is a defect by construction. The close criterion is open-defect share 0 and no draft row in the contract sheet, replacing "nothing unexplained".

Session start protocol (every session, every time)

1. gh issue view <this> --comments — the last comment per item is its true state. Claim by comment: claiming <item> — <model> — branch <name>; stop with status <item>: <done|blocked|partial> — <branch/PR> — <what remains>. Unfinished branches are pushed, never left local.
2. Read keyword-rosetta docs/bias_report.md from main (regenerated on every corpus push and nightly): the "What the red cells are" section and the open-defect share. Do not regenerate locally to triage; regenerate only to verify a change before a PR.
3. Read the signal's row in gitgalaxy/standards/signal_contracts.py and the ledger entries naming it before calling any rule a defect (two of the four issues filed from the args audit were already settled in the ledger).
4. One layer per engine PR (rule regex | slicer/DAG | correlation | scoring). One Closes #N per line. Label rosetta:rebless-owed when the corpus moves; corpus re-bless PR opens against engine main after the engine PR merges (no pins since Cross-repo choreography is circular, and every way it broke today failed green — drop the ENGINE_REF dance, machine-check the invariants #2682/ci: rosetta-audit without pins -- baseline-classified, refuses to no-op (#2682) #2699).
5. Claim a family (one signal, or one formula), never a language. The per-language issues rosetta[abap]: cross-language consistency — 3 red / 3 amber metrics, 2 ledgered shapes #2561–rosetta[zig]: cross-language consistency — 4 red / 2 amber metrics, 5 ledgered shapes #2607 are closed; per-language classification is the keyword-rosetta rosetta-language-sweep skill, called from a family audit, and live standing is python tools/language_deviations.py <lang>.

Decisions (approved 2026-09-06)

• D1 Recorded signal counts become raw counts; correlation weights move to the formulas that read them (score-neutral by construction; one golden-master bless + one corpus re-bless). → Phase 2.
• D2 Close rosetta[abap]: cross-language consistency — 3 red / 3 amber metrics, 2 ledgered shapes #2561–rosetta[zig]: cross-language consistency — 4 red / 2 amber metrics, 5 ledgered shapes #2607 and Epic: rosetta cross-language consistency — per-language deviation tracking (46 languages) #2560; this epic is the one handoff surface; Rosetta to green: cause-first batch plan + multi-session coordination (child of #2560) #2669 closed with a final status. Capstones (docs/language_status/<lang>.md §10) are written when a language reads clean by language_deviations.py, decoupled from any issue.
• D3 The contract sheet is gitgalaxy/standards/signal_contracts.py (machine-readable), rendered to docs/signal_contracts.md, checked by tests/signal_contract_audit.py --ci; how_to_add_a_language.md's comment lines are its prompt form.
• D4 Add the open-defect share now; switch the chart badge in a follow-up PR with the README copy.

Phases

• 0 · Scoreboard keyword-rosetta T2 — bias_report.py cause roll-up (categorize_out_of_band, open_defect_share, decayed_entries), "What the red cells are" section, bias_data.json["cell_categories"] / ["open_defect_share"], GATING.md category semantics, rosetta-language-sweep re-scoped, issue_status.py --post retired. → keyword-rosetta#77 (+ triage Implement Lustre/SCADE Fly-By-Wire Signatures #81). Closed keyword-rosetta#75 as a standing check.
• 1 · The sheet gitgalaxy T2 — signal_contracts.py (68 rows), signal_contract_audit.py + baseline + workflow, docs/signal_contracts.md, RULE 18 + pointer in how_to_add_a_language.md, rule-contract-audit skill, ecosystem.md. → docs(contracts): contract roadmap, signal contract sheet + baseline-gated audit, rule-contract-audit skill #2811.
• 2 · Raw counts are counts (D1) gitgalaxy — the six proximity pairs write to mitigations only; _weighted() helper in signal_processor.py; recorders carry the weighted figure under its own key; test_spatial_correlation.py pins moved; core/README.md proximity table. Both golden masters risk_*-identical; corpus state_mutation on 2 where planted; state-flux-branch-weighting decayed. → feat(core): recorded signal counts are raw counts; proximity weights move to a weighted view (#2813, D1) #2815 (+ corpus re-bless). Unblocked state_mutation has no stated contract: three incompatible definitions across 46 languages, and it governs the corpus's two worst metrics #2765.
• 3 · Count contracts, by family gitgalaxy + keyword-rosetta — one signal → stated per family via the rule-contract-audit skill. 10 of 14 planted families stated; 4 remain. Done when every sheet row is stated.
  • state_mutation state_mutation has no stated contract: three incompatible definitions across 46 languages, and it governs the corpus's two worst metrics #2765 → engine feat(contracts): state_mutation gets a stated contract — a statement that writes to existing state (#2765, Phase 3) #2818 / corpus kr#79
  • unreferenced_by_name (orphan census) orphaned_logic reports 100% dead code for five languages whose invocation model never names the callee — the family #2727 closed without covering #2806 → engine unreferenced_by_name: state the census contract, and stop asking the one language that cannot answer it #2825 / corpus kr#82
  • cobol args/globals cobol args −92%: the overlap-cost rejection was priced before #2729 planted ENTRY on every paragraph — the api cost it avoids is already paid #2804 cobol globals counts WORKING-STORAGE SECTION: a region header stacked on top of the item-level GLOBAL/EXTERNAL clauses, unconditional on every COBOL program #2805 → engine fix(cobol): globals drops WORKING-STORAGE header (#2805); args counts operands not clauses (#2804) #2830 / corpus kr#84 (args general half; corpus shape (a) of cobol args −92%: the overlap-cost rejection was priced before #2729 planted ENTRY on every paragraph — the api cost it avoids is already paid #2804 still owed)
  • branch branch has no stated contract: handler keywords, the syntax words of one conditional, and goto count as decisions in some languages and not in others #2822 → engine fix(standards): branch counts decisions — not handlers, closing words or gotos (#2822 contract, roadmap Phase 3) #2834 / corpus kr#86
  • io io has no stated contract: javascript counts an identifier named path, sqlite counts every DML keyword, and tcl's source/close are claimed by two rules each #2841 → engine fix(standards): io counts boundary operations — one owner, one statement, one boundary (#2841 contract, roadmap Phase 3) #2844 / corpus kr#90
  • test test has no stated contract: c and embedded_python count safety's planted assert, and perl's Test::More::ok( fires the rule twice #2852 → engine fix(standards): test counts framework engagement sites -- the runtime guard is safety's, a qualifier is not a second hit (#2852 contract, roadmap Phase 3) #2854 / corpus kr#94
  • func_start + class_start (the structure pair) func_start & class_start have no stated contract: 5 open cells are all collective-entry cross-product mis-marks, not rule defects #2856 → engine feat(standards): func_start and class_start contracts -- 5 open cells are collective-entry cross-product mis-marks, not rule defects (#2856, roadmap Phase 3) #2857 / corpus kr#95 — no rule change; the 5 open cells were collective-entry cross-product mis-marks (batch4/batch5/kotlin-object), now inherency/scoring. Container residue stays with functions_found[markdown] −100%: func_start is n/a for markdown but functions_found scores it anyway — the structure-count rows have no n/a mechanism #2795/classes_found: five red cells on a 0 median are language morphology, not extraction — the row needs a declaration-requirement stratum #2796/classes_found[css] red on a 0 median: a CSS class is a selector, and #1295 already ruled it out of scope on the other two charts #2798.
  • globals globals has no stated contract: 2 open cells are one-owner/ambiguity misfires, and the crucible shows the rule counting local declarations, function prototypes and hyphenated identifiers #2858 → engine feat(standards): globals counts program-lifetime bindings and ambient handles -- a local, a prototype, a section header and a constant reference are not globals (#2858 contract, roadmap Phase 3) #2860 / corpus kr#96
  • import — planted, 2 open cells (dockerfile, embedded_python)
  • safety safety has no stated contract: 2 open cells are token-double-counts and one-owner misfires, and haskell's rule counts pure, return and type constructors as runtime guards #2869 → engine safety contract (#2869): stated sentence + corollaries, 15 rules edited, two open cells to zero, golden masters re-blessed #2873 / corpus kr#101 — both cells were one-owner/type-level misfires; 15 rules edited on the corollaries; deferred menu safety contract corollary menu: type-level tokens, one-owner duals and narrow rules left in place by #2869, with no cell evidence to move them #2870
  • high_risk_execution — planted, 1 open cell (agc_assembly)
  • ownership — planted, 1 open cell (solidity)
  • cleanup — planted, 1 open cell (makefile); ownership residue from io has no stated contract: javascript counts an identifier named path, sqlite counts every DML keyword, and tcl's source/close are claimed by two rules each #2841 filed as cleanup contract: destruction of external state has no owner — c remove() left io (#2841 C2) but c's cleanup rule does not claim it #2843
  • encapsulation encapsulation has no stated contract: rust counts pub (the public modifier) and agc_assembly's rule matches every column-0 token #2766 (rule half) · immutability_locks immutability_locks has no contract: rust's let is invisible while swift's let scores 11 — and it is subtracted from the corpus's worst gated metric #2772 (rule half) — planted-adjacent, no open cell today but named in D2/roadmap
  • doc safety_bypasses planned_debt fragile_debt telemetry — planted, no open cell; contract flips the row, moves no cell
  • 8 unplanted risk inputs (concurrency dead_code debug_prints immutability_locks reflection_metaprogramming spec_exposure sync_locks llm_api): each gets a plant or a contract-level absence
  • ~41 unplanted domain sensors (architecture/subsystems/hybrid/ai-ml/appsec/literate — crypto, ml, closures, generics, …): batch a transcribed sentence + kind/unit + contract-level absence; no 46-language audit (no corpus cell to move)
  • corollary follow-ups on already-stated contracts (do not block Phase 3 close): args abap args counts call-site parameter keywords (CALL FUNCTION ... EXPORTING, PERFORM ... CHANGING) as declared parameters #2824, state_mutation state_mutation: python, embedded_python and ruby never count a plain re-assignment (narrower than the #2765 contract) #2817, branch branch still counts the break/continue family: the unconditional transfers #2822 deferred #2832 branch counts non-decision tokens the #2822 audit measured but did not touch: ruby bare ?, java bare :, python with #2833, api 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
• 4 · Score contracts + commensurability audit gitgalaxy — tests/tools/audit_commensurability.py (walks _calc_* ASTs, reads units from the sheet, flags +/− between unlike units, ungated inputs, tally denominators), then one PR per formula. Open-defect cells waiting on this layer: raw_arch_api (raw_arch_api bands a per-file declaration count against a per-function median — one granularity mismatch, three red columns #2771, 2 cells), risk_api_exposure (3 unexplained), risk_documentation (2 unexplained), risk_tech_debt (1), func_complexity_gini (1). Closes control_flow_ratio is the corpus's worst metric (33%): it divides a pinned numerator by structural_boundaries, an ungoverned 0-45 vocabulary tally #2770, raw_arch_api bands a per-file declaration count against a per-function median — one granularity mismatch, three red columns #2771, immutability_locks has no contract: rust's let is invisible while swift's let scores 11 — and it is subtracted from the corpus's worst gated metric #2772 (formula half), length leaks: func_internal_density, avg_func_loc and control_flow_ratio read file length with content and tier held equal (rosetta F.1 design pass) #2705's residue.
• D4 step 2 · chart badge → open-defect share (landed early) → keyword-rosetta#80 + README docs(readme): describe the cause-coloured rosetta chart and the open-defect share #2821.
• 5 · Closure — capstones as languages read clean; this epic closes on open-defect share 0 + no draft row. Live: 17/2639 (0.6%) open, 10/68 rows stated (measured against safety contract (#2869): stated sentence + corollaries, 15 rules edited, two open cells to zero, golden masters re-blessed #2873/kr#101 pre-merge; corpus main republishes on merge).

Status snapshot (updated 2026-09-07)

Phases 0–2 done; Phase 3 in progress; Phase 4 not started. Corpus is healthy — the remaining work is completing the sheet, not repairing a broken scoreboard.

Scoreboard: open-defect share 31 of 2296 comparable cells (1.4%) pending #2854/kr#94 merge, average consistency 93% (was 88% at the roadmap's start). test was the latest family cleared; every one of its 43 comparable cells is now in band.

The sheet — 68 rows, 6 stated (9%), 62 draft:

bucket	rows	what "stated" needs	carries open defects?
stated	8 (api args branch io state_mutation test func_start class_start)	done	args 2, api-family 2 → corollary issues only
planted, draft	11	full 46-language rule-contract-audit (engine PR + corpus PR)	6 of 11 do (~9 cells)
unplanted risk inputs	8	a plant or a contract-level absence	no (reported, not gated)
unplanted domain sensors	41	transcribed sentence + kind/unit + absence; batchable, no audit	no (no corpus cell)

What percentage needs a contract, and how much is left:

• The epic's literal close criterion is no draft row → all 62 remaining rows, but only the first two buckets (planted + risk inputs = 27 rows, 40% of the sheet) are load-bearing on the scoreboard or a gated formula. 6 of those 27 are done (22%).
• The other 60% (41 domain sensors) are documentation-grade: a batch of sentences, not audits.
• To drive open-defect share to 0 (the number that matters most): ~8 count-family audits (the planted-draft signals with cells) + the Phase 4 score layer (one commensurability tool + ~5 per-formula PRs for raw_arch_api/risk_api_exposure/risk_documentation/risk_tech_debt/func_complexity_gini), plus the stated-contract corollary fixes (cobol args −92%: the overlap-cost rejection was priced before #2729 planted ENTRY on every paragraph — the api cost it avoids is already paid #2804 corpus half, state_mutation: python, embedded_python and ruby never count a plain re-assignment (narrower than the #2765 contract) #2817, abap args counts call-site parameter keywords (CALL FUNCTION ... EXPORTING, PERFORM ... CHANGING) as declared parameters #2824, 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, branch still counts the break/continue family: the unconditional transfers #2822 deferred #2832, branch counts non-decision tokens the #2822 audit measured but did not touch: ruby bare ?, java bare :, python with #2833). Estimate: ~8 Phase-3 sessions + ~6 Phase-4 PRs + ~6 corollary fixes, then a single batch PR to state the 41 domain sensors and close the sheet.

Housekeeping owed (not blocking)

• gitgalaxy/standards/fidelity_table.py is stale against corpus main (tests/tools/fidelity_table.py --check fails on main since keyword-rosetta#74) — regen owed by the next PR touching the fidelity layer.
• Untracked scratch files in the engine working tree (gitgalaxy/tests.py, gen_tests.py, parse_regex.py, regexes.txt, temp_search.txt) trip the local ruff/mypy audits; CLAUDE.md's scratch rule applies.

Issue disposition

issues	action
#2561–#2607 (40) + #2560	closed 2026-09-06 as superseded (D2)
#2669	closed with final status; F.4 → Phase 3 families, F.5 → STRUCTURE COUNTS, F.6 retired
#2765 #2806 #2822 #2841 · #2805	closed — Phase 3 families landed (state_mutation, orphan census, branch, io; cobol globals)
#2804	open — Phase 3, cobol args corpus shape (a) still owed (engine half in #2830)
#2766 #2772	open — Phase 3 (rule half); #2772 formula half is Phase 4
#2817 #2824 #2827 #2832 #2833 #2843	open — corollaries of stated contracts (args/state_mutation/api/branch/io→cleanup); do not block Phase 3 close
#2770 #2771	open — Phase 4
#2792 #2795 #2801 #2803	closed — engine defects + structure-count n/a landed; #2796 open (classes_found declaration-requirement stratum, Phase 3 structure)
keyword-rosetta#75	closed via Phase 0

[squid-protocol]

Phase 2 (D1) engine issue: #2813. Phase 1: #2811. Phase 0: keyword-rosetta branch tools/cell-categories (PR number to follow).

[squid-protocol]

status Phase 0: done — keyword-rosetta#77 (regen at full precision: extraction 59 / correlation 20 / scoring 51 / inherency 35 / echo 102; open-defect share 79/2303 = 3.4%; 14 decayed ledger entries listed).
status Phase 1: done — #2811, all checks green including the new signal-contract-audit job.
status D2: done — 38 per-language issues + #2560 closed with the scripted comment; #2669 closed with its final status.
Phase 2 is filed as #2813 with the fix shape and proof; unclaimed.

[squid-protocol]

claiming Phase 2 (#2813) — Claude Fable 5.1 — branch fix/2813-raw-counts

[squid-protocol]

status Phase 2 (#2813): done — PR #2815 (fix/2813-raw-counts, label rosetta:rebless-owed). Both golden masters blessed: 2,822 diffs each, all in the per-file sections 6/7, every risk_* column, magnitude and coordinate byte-identical. Corpus sweep against the branch: 45/46 PASS; the one mismatch is agc_assembly c.agc memory_alloc 0→1 (the cleanup-mitigated alloc, now recorded raw) — the ledger's 21-language state-flux-branch-weighting list is decayed (since #2634 the ×3 fires on no corpus file). What remains after merge: the keyword-rosetta re-bless PR (one manifest cell + ledger flips), then #2765 is unblocked. Found on the way: #2814 (dead #if 0 branches are counted; the macro shield only serves brace matching) and the telemetry-slot bug that hid every proximity tally from the audit report (fixed in #2815).

[squid-protocol]

claiming Phase 3 · state_mutation (#2765) — Claude Fable 5.1 — branch fix/2765-state-mutation-contract

[squid-protocol]

status Phase 3 · state_mutation (#2765): partial — engine PR #2818 (fix/2765-state-mutation-contract, label rosetta:rebless-owed) is open; the corpus re-bless branch rebless/gitgalaxy-2765-state-mutation is verified 46/46 against it and its PR opens next (bias report regenerating at full precision now). Sheet row state_mutation draft → stated (3/68). 30 rules rewritten on one statement-start + bare-lvalue shape; 21 corpus languages' cells move, all attributed in docs/state_mutation_rule_contract.md. Deferred with an issue: #2817 (python/embedded_python/ruby never count a plain re-assignment). Process: tests/tools/rule_probe.py and tests/tools/bless_scope.py are now standing tools and the rule-contract-audit skill is a command recipe, so #2766 / #2772 / #2804 / #2805 should each be one shorter session.

[squid-protocol]

status Phase 3 · state_mutation (#2765): done pending merge — engine PR #2818 (CI matrix running; fast checks, tri-comparison audit green) + corpus PR keyword-rosetta#79. Regenerated report against the branch: state_mutation 0 out-of-band cells (was 16 of 43 open defects), risk_state_flux 0/45, corpus open-defect share 3.4% → 2.7%, average consistency 88% → 90%. Next family per the roadmap order: encapsulation #2766, using the rewritten rule-contract-audit skill + tests/tools/rule_probe.py / bless_scope.py from #2818.

[squid-protocol]

status D4 step 2 (chart badge → cause + open-defect share): done — keyword-rosetta#80 (chart: colour by cause, three-share bars with open-defect counts, regrouped rows in pipeline order, NOT GATED* groups with footnote, pagerank drawn once) + gitgalaxy#2821 (README paragraph above the embed). Regenerated against engine main 185061d: zero metric cells moved. Headline on corpus main after merge: open-defect share 62 of 2303 (2.7%), 90% in band across 48 gated metrics.

[squid-protocol]

status Phase 0 triage (the two collective entries + decay list): done — keyword-rosetta#81. Open-defect 62 → 54 (2.3%), correlation 11 → 0, decayed entries 14 → 5, zero metric cells moved. Found and filed #2822 (branch contract: handler keywords / syntax words of one conditional / goto; typescript safety type keywords) — next Phase 3 family after #2806. Three cells (m4/makefile risk_api_exposure, m4 risk_documentation) are now honestly UNEXPLAINED: they had coasted on a retired entry; every input is on the median and the mechanism is not isolated — recorded as an unvalidated ledger entry, candidate family #2806. The gate now skips retired entries.

[squid-protocol]

status Phase 3 · the orphan census (#2806): done pending merge — engine PR #2825 (fix/2806-orphan-invocation-model, label rosetta:rebless-owed) + corpus PR keyword-rosetta#82, verified 46/46 against each other.

The issue's premise held for one of its five languages. #2806 read orphaned_logic 3.25/file — every function unreferenced — for abap, jcl, m4, makefile and objective-c, and proposed a per-language "positional" declaration for all five. Measured: abap PERFORM, m4 bare expansion, a make prerequisite and an Objective-C selector send are all ordinary invoke-by-name forms, and the crucible shows the census seeing them (real ABAP reads a 6% unreferenced rate). What those four had in common was the corpus — their main declared a dispatch/entry unit that called nothing, where every median language's main dispatches its three probes. Planting each language's own idiom moves all four to the median with no engine change. jcl is the real case and now declares invocation_model: "positional"; the census is not computed there (334 of 376 crucible steps read unreferenced, and the 42 that cleared did so by colliding with a DSN fragment, inline SQL or a repeated step name — both tails noise).

Shape (c) landed too: orphaned_logic → unreferenced_by_name, state_slop_orphans → state_unreferenced, with an in-place column migration. Contract, six corollaries and the 46-language audit: docs/unreferenced_by_name_contract.md.

Numbers. Corpus regenerated at full precision against the branch: open-defect share 54 → 49 of 2303, average in-band 90%, raw_state_unreferenced out-of-band 13 → 8 of 46. Golden masters: 5,636 label renames plus 564 value diffs, every one jcl. Every moved cell is attributed in the corpus PR.

The three unexplained cells are NOT this family. m4/makefile risk_api_exposure and m4 risk_documentation were recorded as "candidate family #2806" in the Phase 0 triage; regenerating against this branch leaves all three exactly where they were (only jcl's risk_api_exposure/risk_documentation moved, and only because the orphan→api conversion has nothing left to convert). They are a score-layer question, so Phase 4, not Phase 3.

Filed on the way: #2823 (haskell/scheme read 0.25 — a module export list and a type signature are declarations, not references; needs _visibility_export to yield more than one name per match, plus its own plant — the sign-flip of this issue and cheapest run with it), #2824 (abap args counts call-site parameter keywords — corollary 1 of the stated args contract, exposed by this wave's plant), and a comment on #2822 (cobol branch counts a bare out-of-line PERFORM, 2,191 of 21,549 crucible hits — which is why cobol's plant is deliberately not in this wave).

One trap for the next contract session: language_lens.py compiles every string value inside a registry's rules into a regex. The first version of the declaration lived there and reached the detector as re.compile("positional") — every unit test passed (they build the extractor from LANGUAGE_DEFINITIONS, which the lens never touched) and the first golden-master bless was silently wrong. Only a real galaxyscope run showed it. A non-pattern helper belongs at the top level of the definition, beside lexical_family.

Next family per the roadmap order: #2822 (branch).