Feature: make the pinned arcade reference the authority every build and review checks against

[StarshipSuperjam]

Closes #111

A green mechanical check below shows this change conforms to the engine's rules — not that it is correct. What covers correctness is the behavioural steps in Review and your own read of the change; a green check is never a substitute for that. Your merge is the binding gate.

About those checks: only the one that runs when the change is proposed for merge can stop a risky merge — a check that ran while the change was still being written is early advice. Each check is itself proven against a deliberately broken example it must catch, so a passing check can't be one that quietly did nothing — but that proves the check works, not that this change is right. And a check that could not run leaves its area unverified.

Purpose

Make the pinned arcade source the authority every build and review checks the port against, instead of the docs/spec/ prose.

• Motivated by the slice 8 (Feature: Toroid vertical slice — first live flying enemy (slice 8) #110) Toroid-swing regression: a settled spec sentence described the swing backwards, both conformance reviewers flagged the correct build against the prose, the session "fixed" the build to match, and three gameplay bugs reached the playtest. The session then had no local reference to check against and had to fetch the source over the web.

Impact: a citation that no longer points where it claims cannot pass unnoticed, and a reviewer reads the arcade source itself before a build is handed over for playtest.

Scope

Tools, a citation audit, a fidelity-gated handover, a CI backstop, two review personas, and a conduct rule — no gameplay code.

• tools/reference_checkout.py — a verified throwaway clone of jotd666/xevious at the pin, so any session or CI can open the cited source (ensure/path/verify; offline once cached).
• tools/reference_citations.py — resolves every citation in docs/spec/ and docs/mechanics/ to a real label and line range at the pin (102 citations, 0 unresolved).
• tools/playtest_package.py — the handover gate: it runs the reference checks and refuses to build a playtest .sb3 while any citation is unresolved.
• The one-time citation audit that corrects the citations the resolver could not resolve.
• .github/workflows/reference-fidelity.yml — an advisory CI backstop.
• Two reference-fidelity review personas at the plan and pre-submission gates, and a conduct-reference-outranks-spec code, plus an always-loaded section in CLAUDE.md/AGENTS.md.

Change profile — the shape of this pull request at a glance:

• Size: 35 files changed, +1529 / −38 lines.
• Kinds of thing touched: 2 tools, 1 operation, 32 other files (not in the engine's map).
• Where: docs, tests, tools, .claude/agents, .codex/agents, .engine/tools, .engine, .engine/conduct, .engine/knowledge, .engine/operations, .github, .gitignore, AGENTS.md, CLAUDE.md, README.md.
• Shape: 10 commits on this branch.

Impact: the reference becomes the authority mechanically (resolver + handover gate + CI) and by routed judgment (the personas), and every session loads the rule.

Behaviors

The falsifiable capabilities this change delivers, each with the test that exercises it:

• A verified reference checkout is obtainable without leaving the repo or fetching over the web — tests/test_reference_checkout.py.
• Every citation resolves to a real label and range at the pin; a nonexistent label, an approximate ~NNN, an over-wide range, or a missing file fails — tests/test_reference_citations.py, tests/test_reference_corpus.py.
• The handover tool refuses to build while any citation is unresolved — tests/test_playtest_package.py.

Out of scope

Deliberately excluded, with reasons.

• The bare-range → labelled-citation conversions the resolver only advises on. On inspection the "clean" set was an artifact of a line-based advisory over-reporting citations the paragraph-based resolver already checks (verified: update_solvalou_sprite_XY, find_idle_and_init_radiating_bullet, and others resolve today); the genuine remainder either maps awkwardly to a single label ("the four angle tables span 6290–6427") or exceeds the span cap. Forcing labels would reduce accuracy, so they stay as prose.
• The aerial-enemies.md Toroid swing prose made explicit ("reverses away", not homing). That draft doc is being rewritten by in-flight PR Feature: Toroid vertical slice — first live flying enemy (slice 8) #110; the clarification belongs there.
• Making the citation check a required merge gate. You chose in-session + advisory CI (backstop only); see Risk.

Impact: the settled-doc edits are held to the genuinely-broken citations, keeping the guardrail-ack surface tight.

Risk

No engine guardrail is weakened; the friction is deliberate consent, and two engine self-tests are hand-edited.

• Settled specs + guarded policy → guardrail-ack. This edits four settled specs (core-game-systems, player-craft-and-weapons, difficulty-and-formations, area-progression-and-terrain) and the guarded docs/REFERENCE_POLICY.md. All are locator-only or a disclosed posture change; none change gameplay meaning. Apply guardrail-ack to clear the product-lock and guarded-path checks.
• docs/REFERENCE_POLICY.md posture change, called out distinctly. The policy said "nothing here depends on [the reference clone]." After this, the fidelity tooling depends on the reference being obtainable at the pin (not on a stored copy). Your guardrail-ack covers this as a deliberate change, not a typo fix.
• Two engine self-tests are hand-edited. test_conduct and test_lens_consumption hardcode the shipped defaults and fail when a project uses a documented feature (a conduct code, a project review persona). They are relaxed minimally. These files are overwritten on each engine update, so the edits must be re-applied then. Filed as Engine fault: required self-tests block documented per-deployment customization (project conduct code and review persona) #113; you noted such an issue won't reach the engine home, so this is a recurring per-update chore.
• "Fails CI" is advisory, not blocking — an accepted deviation from the issue text. Issue Feature: Make the pinned arcade reference the authority every build and review checks against #111 said a bad citation should "fail CI"; you chose in-session enforcement + advisory CI. So a broken citation turns the advisory reference-fidelity check red but does not block merge. Recorded here as the deliberate choice it is.
• Engine update drops the lens wiring. The reference-fidelity line in build-orchestration.md is overwritten on update; the hard lens-consumption check then goes red with a self-describing fix. A recurring one-line chore.

Impact: every friction here is a consent gate you clear or a disclosed recurring cost, not a silent weakening.

Validation

Full local suites green; the new CI job passes; two checks stay red pending your guardrail-ack.

• 217 project tests pass; python tools/scratch_project.py verify and reference_extract.py --verify pass; reference_citations.py reports 102 checked, 0 unresolved against a real clone at the pin; actionlint clean.
• The engine CI check-suite passes with no hard findings; the two previously-failing engine self-tests now pass; a full engine self-test run confirms no other breakage.
• On the live PR, reference-fidelity, xevious-project, runtime-harness, secret-scan, CodeQL, actionlint, and engine-overlay-disclosure are green. engine-ci and engine-guard stay red until you apply guardrail-ack (the settled-doc / guarded-policy gate).

Impact: an approver can rely on the mechanical checks; the two red ones are your consent step, not defects.

Review

A thorough cold review ran at Standard depth: four plan-review passes before building and five pre-submission passes after, plus a blind reference-fidelity replay. Real findings were fixed; two blocking findings were corrected.

• Plan-review (architecture, feasibility, risk-governance, product-intent) shaped the design before any code: block extent from the label index (not bytes_under_label), bare file-token normalization and paren-group scoping, a CI-safe git identity in tests, and the matrix-regen check were all adopted from these passes.
• Pre-submission (spec-conformance, divergence-hunter, technical-integrity, security-governance, reference-fidelity) ran cold on the built change. Outcomes:
  • Blocking (technical-integrity), fixed: the resolver never scanned the file+range (no-label) citation shape, so four real citations were invisible and an impossible .inc citation would pass. Now scanned (98 → 102 citations), with a fixture test.
  • Blocking (spec-conformance), fixed: two required engine self-tests failed on this project's conduct code and persona lens. Relaxed minimally; both pass; engine fault Engine fault: required self-tests block documented per-deployment customization (project conduct code and review persona) #113 filed.
  • Serious, fixed: an over-wide range was accepted (now capped at 256 lines); the second ~514 survived and its guard no-oped (both fixed); unguarded git steps raised raw tracebacks (now clean CheckoutError); the playtest checklist routed around the handover gate (now through it); CI actions pinned to SHAs.
  • Confirmed not a defect: leaving reference_citations.py and playtest_package.py unguarded is your explicit choice (guard the pin-deciding files only); the citation audit fixes are genuine, verified against the source.
• Between reviewed and submitted: the reviewed commit was 86f4bef; four fix commits followed (b6ad1d8, 41bb604, 75ea249, and this body). Net change since the reviewed version: about +190 / −40 lines across the resolver, checkout tool, tests, two engine self-tests, and three docs — a material post-review delta, re-verified by the full suite and a fresh resolver run (102/0).

Impact: the engine's own account of the review — your merge is the binding gate.

Demonstration

The slice-8 replay: the reference-fidelity persona, blind to the answer, reads the source and judges the prose.

• Run the persona (or by hand) against docs/spec/aerial-enemies.md lines 41–44 with a checkout present. It opens src/xevious_main.68k toroid_toggle_dir 3289–3321 and the two swing arms, determines from the source alone that the swing reverses away from the craft (the two arms adjust _dY by ∓1, locked at the trigger), and reports whether the prose is faithful. In this PR's run it correctly found the swing is a reversal and the current wording faithful — the exact read that was missing when slice 8 trusted the prose.
• Mechanically: python3 tools/reference_citations.py --checkout "$(python3 tools/reference_checkout.py path)" prints 102 citations checked, 0 unresolved; break any cited label or range and it prints that citation as unresolved and exits non-zero.

Impact: you can watch the gate read the source and catch a wrong citation, rather than trust the prose.

Files of interest

The core is three tools and the resolver logic.

• tools/reference_citations.py — the resolver (grammar, scoping, resolution rule).
• tools/reference_checkout.py, tools/playtest_package.py — the checkout and the handover gate.
• .claude/agents/reference-fidelity*.md — the review personas.
• The citation audit across docs/spec/*.md and docs/mechanics/{020,022,015}.

Impact: these most determine whether the reference stays the authority.

AI involvement

Built with Claude Code (Opus 4.8).

• Claude designed and wrote the tools, tests, personas, and docs; ran four cold plan-review and five cold pre-submission passes (Opus and Sonnet review personas) and a blind reference-fidelity replay; dispositioned every finding and fixed the blocking ones. Load-bearing judgment: the citation grammar and resolution rule, the span cap value, and the disposition of the deferred conversions.
• All citation fixes were verified against the pinned source, not authored from memory.

Impact: the resolver logic and the citation audit are where AI judgment is load-bearing; the source verification bounds it.

🤖 Generated with Claude Code

[github-actions]

This pull request touches more than one kind of engine file. Here is what the next update does with each — none of it blocks your merge:

Heads-up: this pull request changes engine files the next engine update is set to overwrite.

The engine keeps its own machinery current by replacing these files wholesale when you update — so a change you make to them here won't survive the next update; it will quietly revert:

• .engine/operations/build-orchestration.md
• .engine/tools/test_conduct.py
• .engine/tools/test_lens_consumption.py

If that was a one-off, this is just so you know. If you want the change to last, the durable home for an edit to engine machinery is upstream in the engine project these files come from (StarshipSuperjam/engine-template) — a fix there travels to every update. And if what you actually want is to customize how the engine behaves, the settings that do survive an update are your tunable policy (via /engine-tune) and your operator notes — those are preserved; these files are not.

These engine-internal files are regenerated by the update.

The engine rebuilds them from your project's own current state on each update. A change here that reflects a real change in your project — you edited what the file is generated from and regenerated it — is reproduced, not lost. But content typed directly into one of these files, with no matching change to the source it comes from, will not survive: it is rebuilt away on the next update. So if you meant to change what one of these records, edit the source it is generated from (for the settled-criteria record, your docs/spec/), not the file itself:

• .engine/knowledge/graph.json

This is a heads-up only — it does not block your merge, and your merge is the decision.