feat(report): stop the risk surface claiming more than it measures (#3111, #3112, #3113, #3114)

[squid-protocol]

Closes #3111. Closes #3112. Closes #3113. Closes #3114.

Four issues from one real-repo plausibility audit (IBM's zopeneditor-sample — COBOL/PL-I/JCL/HLASM/REXX, 51 files). None changes how anything is computed. All four change what the report claims.

The shared defect

The brief's Primary Risk Drivers line took the top four vectors by raw value. Two of the thirteen — spec_match and documentation — are "fraction not covered by a convention" meters, so on any codebase lacking that convention they sit at ceiling. Both read mode 100 / median 50 on the sample scan, and they took 2 of 4 slots on all ten top-10 entries.

A line whose only job is to discriminate between files was reprinting two constants and burying the vectors that actually differed. Reproduced as a test — with both at 100 and four ordinary vectors below them, the line now reports only the four that differentiate:

Top Surface Vectors: Mutation Surface (100.0%), Guard Balance (91.5%),
                     Test Surface (80.0%), Complexity Load (61.8%)
Documentation Coverage: 100.0% of unit weight undocumented

#3111 — spec alignment opt-in, default OFF

--spec-alignment. When off it is absent from every display surface, not rendered as 0.0 — a 0.0 asserts perfect spec alignment, the opposite of "not measured". Section 6 says so explicitly and names the flag.

The stored vector stays dense and numeric (the slot holds 0.0). Injecting None would have meant auditing ~25 positional consumers, several of which crash on it — gpu_recorder does int(v * 10), network_risk_sensor multiplies, dev_agent_firewall sums, record_keeper writes REAL columns — and dense-0.0 is already how the engine represents the history vectors it ablates (galaxyscope.py:1174). Honesty is enforced at the render surfaces, which is where the issue asked for it.

#3114 — documentation reframed, not disabled

Still computed, still tabled (marked _(coverage)_), still reported per file as "X% of unit weight undocumented" — but no longer eligible for the driver narrative. Its own contract (#2908) defines it as a coverage gap over units, so coverage is where it belongs.

Both are declared once, in analysis_lens:

OPTIONAL_VECTORS = {"spec_match": "SPEC_ALIGNMENT"}
CONTEXT_VECTORS  = {"documentation": "documentation coverage, not a fragility driver"}

with a single inactive_vectors() resolver every renderer consults, so a second optional vector needs no renderer edits. A contract test asserts both name real RISK_SCHEMA entries and that the families stay disjoint — off and reframed are different asks.

#3112 — the Cumulative Risk composite is removed

sum() over the whole 13-entry risk_vector: independently scaled sigmoids added with no weighting and no unit, yielding Cumulative Risk: 556.29. Unrepairable in place — ~31% of the sum was constant or dead, and summing the vectors re-created exactly the composite risk score that the #2982/#2991 validation record retired.

⚠️ BREAKING — --max-systemic-threat. Was cumulative_risk × blast_radius, now structural_magnitude × blast_radius. Intent unchanged and arguably better served ("fail when something structurally heavy is also widely depended upon"), and both factors are now unit-honest. Thresholds do not carry over — the scales differ — and are deliberately not silently rescaled: a fabricated conversion factor fails more quietly than an obvious re-tune. Flag help and docs/vectors.md both say so.

#3113 — the brief leads with the answer

A new executive summary, before any formula exposition. It reuses #2556's zero-guard, so a flat import graph is reported as flat rather than ranked by scan order — and it independently reproduced the two facts that audit verified against source:

## 1. EXECUTIVE SUMMARY
- Scope: 48 analyzed artifact(s), 2273 LOC. Dominant languages: ...
- Load-bearing artifact: `INCLUDES/BALSTATS.inc` -- 3 in-repo importer(s) depend on it.
- Top orchestrator: `JCL/RUN.jcl` -- pulls in 14 dependencies, the widest assembly point.
- Heaviest artifact: `COBOL/SAM1.cbl` at magnitude 257.24 (structural weight, not risk).

Sections 11 and 12 answered "which files deserve attention first" twice, and the one that ranked did so on the composite #3112 deleted. Now one list, ordered by magnitude, each entry carrying a consequence assembled from edges the brief already computed but never stated:

- Blast Radius: changing it is visible to 1 in-repo importer(s); it depends on 2;
                blast radius 30.522; role: Pure Producer (Foundation)

Outbound comes from raw_imports (matching section 7 and the summary) because the resolved out_degree can read 0 directly above a line naming two imports — a regression test pins that.

The 75-line lexicon and the non-predictive disclaimer move to Appendix A, verbatim. #3113 was explicit that the honesty is an asset and must be kept; it just shouldn't be the wall a reader climbs to reach the findings. A pointer is left where section 2 was. The AI output directive that told consumers to hunt for "massive Cumulative Risk" now points at magnitude and blast radius and explicitly forbids summing the vectors.

Section order: 0, 0.5, 1 (exec), 1.5, 3 … 10.7, 11 (ranked), 12, 12.5, 12.8, Appendix A. Brief went 883 → 845 lines on the sample repo, with the verified content first.

Fixtures

Second commit, 2,426 differences per master, all attributable:

count	what
2,230	Specification Exposure — per-file vector no longer measured (#3111)
193	spec_match — the same vector's ecosystem aggregates
39	removed 4. High-Value Forensic Report/cumulative_risk paths (#3112)

Zero topological churn, zero added paths, nothing outside those groups. This is the first real fixture bump since #3141 marked these -diff — it renders as Bin 57926723 -> 57919405 bytes rather than ~400k lines, and was reviewed with bless_scope.py, exactly as that PR argued.

Each fixture was blessed from an environment matching the CI leg that checks it (PyYAML-only for zero-dep; +tiktoken/pandas/xgboost for full-precision), after a first attempt recorded "numpy": false into the zero-dep fixture — my machine leaking into a fixture whose purpose is to describe an environment without optional engines. Missing Dependencies is compared; only Absolute Project Path, timestamps and the git footprint are sanitized. Both modes verified green locally.

Verification

• 9,890 tests pass (--ignore=tests/security_auditing, and deselecting the known-stale local fidelity_table check)
• 22 new tests covering all four issues, including the measured defect and the out_degree regression
• both golden_crucible modes pass from their matching venvs
• ruff_audit.py --ci: no new findings beyond the 8-finding baseline
• mypy gitgalaxy/: identical to main — 5 pre-existing missing-stub errors, none introduced

Notes

docs/vectors.md records all four, including why ~115 historical docs/wiki/ teardowns keep their retired cumulative_risk numbers instead of being edited — they're dated analyses of what the engine really did emit, and rewriting them would falsify the record. (#3112 estimated ~8; it's 115.) docs/gitgalaxy_architecture_brief.md is regenerated by the scheduled self-scan and drops the metric on its next run.

One near-miss recorded in the fixture commit: a clean-corpus run disagreed with main on .gitgalaxy/dependency_cache.db's recorded Size, which looked like a volatile artifact of the scan recording its own cache. It isn't — that file is tracked in language-crucible at v1.3.0 at exactly 20480 bytes, committed by accident in corpus commit 6a2257c. The mismatch came from me deleting a tracked corpus file. main was never broken, the corpus is restored, and the pre-emptive fix was reverted. Worth its own issue: a dependency-cache DB checked into the corpus is now load-bearing for fixture reproducibility.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HwA8w2WpBqJg3AGf3yvYeF

[github-actions]

🐦‍⬛ Muninn Security Scan

✅ No security issues found.

🐦‍⬛ Powered by Muninn · Skald Lab