Boundary Guard

Boundary Guard

Generic game logic → substrate (riir-games). View renders state, doesn't compute it. FFI moves raw bytes only.

Spec source — each repo's BOUNDARY.md

Every repo ships a root BOUNDARY.md — the per-repo contract this skill audits against: Owns / Does not own / May depend on (crate-granular allowlist with Location) / Inherited (links) / Drift ledger. The 8-surface table below is the workspace methodology; the per-repo rules + exceptions come from that repo's BOUNDARY.md, not from this file's prose. Findings are therefore two classes: code-vs-contract violations and contract rot (drift row without an open issue, allowlist row without a gate, by-design row whose decision record is gone).

Two scripts, one job each (added 2026-08-21, Issue 737 T-CI/T-GATE):

The contract script replaces prose-only allowlists; it is the successor of Issue 724 Phase 2's "document the contract and review by hand". EXEMPT_LEAKS in the per-repo guard deliberately STAYS file-granular — the ledger is surface-granular, and collapsing the two would lose the file:line precision Check E needs.

Partial-clone boxes (riir-ai Issue 939, the katgpt-rs Issue 765 idiom one repo over): C0d (a path dep whose target sibling is absent) and C0e (a ../<repo> routing reference that does not resolve) both decide by asking whether a DIRECTORY exists under the workspace root, so a box carrying a subset of the workspace reds on every edge and route into an un-cloned sibling. Export BOUNDARY_PARTIAL_CLONE=1 there and those two ABSENT-TARGET verdicts report as loud instrument-alive DEFERRALS instead; the rest of the gate runs at full strength and the exit code is untouched. Never auto-detected and never set in CI — from the walk alone a genuinely DELETED sibling is set-identical to an un-cloned one. Deliberately narrow: a target that IS present and merely routed wrong (C0a's missing contract, a C0e route into obsolete/) stays a hard finding in every posture. --self-test pins both postures plus that narrowing (10 arms); it is two-sided, so jamming the marker on or off reds it.

Drift-ledger semantics (scripts consume this): Disposition ∈ fixable | owner-call | by-design. fixable/owner-call rows REQUIRE an open issue; by-design rows cite a decision record instead. Issue closes → row removed in the same commit. Exit semantics: ledger unparseable → hard error; finding mapped to a row → exit 0 with a LOUD known-drift count; unmapped finding → exit 1; row-without-open-issue → exit 1 (rot). Never silently fail open or closed.

Eight surfaces

The dApp three-test rule (surface 8 detail — riir-chain Issues 096/097 + riir-dapps Proposal 001)

1. Product — would a commerce customer of this chain want it in their dependency? (An NFT is a token → yes. A quest/recipe/kill-credit predicate → no.)
2. Value — BigInt fungible currency, a token, or an authority binding? Not FAME/XP/items/reputation/karma/quest progress.
3. Rate — quorum-coordination ops are Glacial (≤0.1 Hz); settlement transactions are capacity-share bound (783 req/s measured floor) — different limits, both binding.

The defining axis is agreement (Research 003 §"The Second Axis" "Must agree on" column) — value and rate are the disqualifying tests, not the definition. Full argument + failure-mode matrix: riir-dapps/.proposals/001_agreement_boundary_and_tiered_durability.md.

All greps should return empty (clean), modulo the sanctioned opt-in exceptions noted per-surface.

<!-- retired surfaces, kept as lineage: `riir-unity` (C# Unity host) and
`mmorpg-remake-unity` were moved to `git/obsolete/` by owner act on 2026-09-04,
`riir-armageddon` on 2026-09-02. Surface 5's old command globbed
`riir-unity/**/*.cs` and could no longer run — worse than stale, because a
non-matching zsh glob aborts the whole command line rather than returning
nothing, so the check would have looked skipped rather than broken. The
`WireProtocol.cs` precedent it cited (riir-unity Issue 002 Phase A, a
cross-language contract documented on both sides instead of re-filed) is the
part worth keeping and applies to `riir-viewbridge/csharp/` under surface 6. -->

Methodology lesson (2026-08-15 run): exclusion filters can hide exactly what you're looking for — the "who enables feature X" grep returned zero because the forwarder lines contain katgpt-core and were killed by grep -v katgpt-core. Vocabulary-translation care applies to filters, not just search terms.

Failure pattern

"Helper" in consumer → wrapped in System impl → grows loops + math → stuck in consumer. Same applies to C# view code reimplementing substrate logic.

Extraction checklist

Before adding to consumer src/ or view C#/Bevy:

1. Is this generic game behavior? → substrate (riir-games)
2. Does substrate already have it? → grep riir-games/src/{swarm,motivation,combat}/
3. Can it be parameterized? → trait (ThreatSource) or config struct
4. Is the consumer/view just data + wiring? → if loops/math/constants present, STOP

If unsure → file an issue, don't add the code.

Filing violations

1. .issues/NNN_boundary_*.md in the repo
2. Reference which surface (1–7)
3. Include file:line + grep output
4. Propose extraction target (substrate module + trait)
5. Issue BEFORE fix — every fixable finding gets its .issues/NNN_boundary_*.md filed BEFORE any fix commit, even trivially-fixable ones. The fix commit references the issue; closing the issue removes the drift row in the SAME commit. Only the guard/script tooling itself may be fixed in-run — boundary CODE never.

Move by script, never regenerate

Any relocation of boundary content — extracting superseded sections from AGENTS.md into BOUNDARY.md, removing drift rows, linking READMEs, or any future crate/repo move — is done by script (git mv + anchored sed/python) with a before/after grep-parity check (every rule sentence present exactly once post-move). Re-typing or regenerating the content is forbidden. Grounding: the AGENTS.md section silently dropped by a concurrent session's stale-buffer commit (88e5f98), and the edit-fuzzy-match that ate a raw-string # terminator — both would have been caught by parity checks.

Running

# workspace contract (dep graph + contract honesty + split-prep gates)
cd riir-ai && ./scripts/ci_boundary_contract.sh          # exit 0 = clean
./scripts/ci_boundary_contract.sh --list-deps            # measured edge set
./scripts/ci_boundary_contract.sh --repo riir-chain      # one repo

# per-repo code logic (surface 1)
cd riir-mmorpg-examples && ./scripts/ci_boundary_guard.sh # exit 0 = clean

Exit codes (contract script): 0 clean or all-findings-mapped (LOUD known-drift count), 1 unmapped finding or contract rot, 2 hard error — a missing or unparseable contract never fails open. For other repos' code-logic checks, adapt the guard's SRC_DIR + patterns. Or as pre-commit: exec ./scripts/ci_boundary_guard.sh

Run boundary checks VIA this skill — not as ad-hoc greps. The skill reads each repo's BOUNDARY.md as the contract, applies the methodology below, and records the run in the log. The T-CI/T-GATE wiring landed 2026-08-21, so the full via-skill run is now available (and the first one is logged below).

Run log

Compacted 2026-09-08 (user-directed — the file crossed 100 KB of context); re-compacted 2026-09-11 (post-09-08 rows had regressed to multi-clause narratives). Rows carried full narratives until these compactions; git log -p -- .agents/skills/boundary-guard/SKILL.md (the katgpt-rs repo) recovers any of them verbatim. New rows append ONE line each. Pruned 2026-09-21: 105 → 15 rows, 71KB → 30KB — the one-line convention held but the cadence didn't (~10 rows/day re-bloated it since the 09-11 re-compaction; third prune). Maintenance rule: whenever this file exceeds 60KB, prune the run table to the newest 15 rows — enforced mechanically by scripts/skill_size_gate.py (80KB hard ceiling, all .agents/skills/*/SKILL.md); recovery via git log -p as above.

Standing lessons (distilled from the compacted rows — load-bearing process rules)

• Read the exit UNPIPED. cmd | tail; echo $? reads TAIL's exit (re-proven twice); outputs go to /tmp, read the real exit or PIPESTATUS. A piped gate summary cannot vouch for an exit code — and a green summary over an unstaged body is worse: the 20th run's "exit 0" was FALSE while C0e's implementation sat unstaged (a6ca9ccbd docs-only; body landed 10977dd23).
• Verify the script not-mid-edit before running: mtime vs the last recorded run + bash -n + clean in git status. A sibling rewriting the script mid-run truncated a measurement after SP1 while the first attempt still reported exit 0 (the 2026-09-04 membership row) — bash re-reads by byte offset. The script anchors ROOT from its own path, so /tmp snapshot-copy immunization CANNOT work; diff-vs-snapshot before running the live script instead.
• Parser replay for stale shared checkouts: run the script's own allowlist awk against git show origin/<default>:BOUNDARY.md — a sibling branch predating a row reads exit-1 on disk while main is CLEAN (the riir-train until-merge artifact class); touching the sibling branch is forbidden.
• Detection-only discipline: file .issues/NNN_boundary_*.md BEFORE any fix; sibling WIP (staged sets, mid-flight sweeps, dirty manifests) is measured as-found and never fixed by the idle unit — the sweep owner re-pins C6 at closeout (the 2575b6519 precedent). A landed growth WITHOUT its re-pin, though, is repaired by whoever finds it once the landing session is gone (the honest up-pin class: verify zero training semantics, pin UP with the reason).
• The C6 ledger row text must be apostrophe-free and the real detector is bash -n, not running the guard — bash 3.2's quote tracker reports the wrong line (~20 below the guilty one).
• Expected shapes, not findings: the 2 known-drift rows (the ledgered mmorpg-remaster pair); C7 = 4 repos with no tracked lockfile; scoped --repo runs print C7/C8 out-of-scope notes only.
• C8/C9 standing advisory (owner call, never an idle-unit act): consumer lockfiles pin katgpt-rs @6f392727 and drift further behind develop each window — 326 (09-03) → 739 commits behind with 7 security fixes in the gap (09-11, the 70th run) across 3 lockfiles, plus a second divergent pin in riir-chain (167/1). Recorded every run; the bump is the owner's. Gap ENUMERATED 09-10 with the script's own predicate (689 behind at the 37th run, @c478ab9f chain pin 0 security): the 6 = 2× SIMD soundness (99afbab9 safe-code OOB read + heap-corrupting write in katgpt-types/src/simd/ — CWE-125, simd_dot_f32 unchecked-len; 5b028c00 the near-verbatim katgpt-dec twin) + 2× FFI/panic-UB hardening (af2e48e1 catch_unwind on 10 wasmi extern fns; e854958e/96543f4f the 208-site NaN-comparator sec heal) + 2dec22a1 (a filed, not-fixed, EngramHotSwap nested-swap soundness hazard) — the sharp half is that the two SIMD holes are MEMORY-SAFETY bugs in the exact substrate the three deploy lockfiles compile today, so the bump is a soundness call, not a freshness preference. RESOLVED 2026-09-11 (owner call executed, subagent re-verdicted): all three consumer locks bumped 6f392727 → c478ab9f, and the discovery corrected the advisory's own premises. The 3 tracked lockfiles are riir-dapps cloudflare/kat-service, riir-mmorpg-examples cloudflare/warm-tier-do, and riir-esp32 crates/riir-satellite-probe — NOT riir-kat/riir-dao, which carry no tracked lock at all (the C7 class). The consumers pin branch = "main", so the reachable target was main tip c478ab9f, which already contains ALL 6 enumerated fixes; the 7th grep hit in the develop-only range is a docs commit (the advisory's own enumeration) — a predicate false-positive class: the sec-subject grep matches docs commits whose subject contains "soundness". riir-chain's "divergent pin" re-verdicted to the same answer: it already sits at main tip c478ab9f, zero action needed. All builds/tests green per consumer (kat-service 143 tests + wasm32; warm-tier-do 4 + wasm32; satellite-probe esp32c6 release). Commits: dapps c9203a2+6342519, mmorpg 0afb52b, esp32 2bfb795. Going forward the "behind develop" count is a branch-policy artifact (branch=main), not a security gap — the advisory's remaining value is the C9 one-rev agreement, which this bump achieved (all 4 build roots on c478ab9f).
• Guard output truncates in tail views — capture the FULL violation list when filing (the "8 = 6 unique" enumeration error).
• Never suppress fetch output you act on — a silenced fetch failed and produced a false empty-divergence read while the push error was right (the 59th run, 4090 box).
• git show HEAD:<dir> on a directory prints the tree LISTING — honest dir LOC is an ls-tree -r + cat-file sum. rustfmt --emit stdout prints a 2-line filename header — a round-trip harness must strip it.
• The staged-set check must be a SEPARATE command (or commit git commit -- <paths>): chained add && diff --cached && commit swept a sibling's entire staged set once (the 30127c4 incident); recovery anatomy lives in that row's history — read the reflog before any second corrective action.
• A prose contract cannot catch an inverted measurement — every "repo X may depend on Y" row is a measurement with a direction; that is why the contract script parses tables instead of prose (the first full run's founding lesson).

Run table