Feature Gate Audit

feature-gate-audit — Verify feature-gate claims against production code

This skill exists because of a caught error chain: session f92a7ffe in riir-ai (2026-07-18) framed npc_sleep_time's engine-DEFAULT-ON / civ-OPT-IN state as a "promotion discrepancy" and claimed the catalog was "wired but not yet exercised in production civ tick". Session f865913e (same day) verified both claims against production code and found them factually wrong:

• The split is a deliberate layer split (engine = generic runtime; civ = IP-bearing catalog + graceful-degradation hook into SleepConsolidateNode::tick Gate 3).
• The catalog IS exercised in production via crates/riir-games-civ/src/civ/daily_loop/mod.rs:1071-1078, which calls ctx.sleep_runtime.sleep_cycle_tick(&hla, &self.dirs).

The three defenses below would have caught both errors before they landed. Apply them to every feature-gate claim you encounter.

When to use

• A doc, plan, issue, commit message, or session summary claims a "promotion discrepancy" between two crates' feature-gate status
• A doc claims a feature is "wired but not yet exercised in production"
• You encounter a // Default-off until G1–GN GOAT gate passes comment in source code
• Before promoting a feature flag to default-on (or demoting to opt-in) in any product-set repo (7; canonical list in katgpt-rs/AGENTS.md §"Repo count" — read the LIST, not the count: this cell said 7-omitting riir-dapps, then 8-counting-retired-riir-armageddon. A count that drifts from the canonical list is the exact defect this skill audits in others)
• Quarterly as a feature-gate-hygiene gate (alongside doc-sync and goat-audit)

The four defenses

Defense 1 — Verify every "discrepancy" / "not yet wired" claim against production code

NEVER propagate a doc/plan/session-summary's framing of feature-gate state without first grepping the actual production wiring. Plausible-but- wrong framings are the canonical failure mode — they read as reasoned verdicts, get propagated through summaries, and solidify into "facts" that downstream sessions trust.

Protocol:

1. Identify the production host(s) — the function that would invoke the gated code path on the hot tick. Common hosts in this stack:
   • tick_proactive_salience (salience gate)
   • tick_cgsp_curiosity (CGSP runtime)
   • tick_motivation (motivation system)
   • SleepConsolidateNode::tick (sleep-time, daily loop)
   • evolve_feeling_brain (emotion systems)
2. grep for the feature name across all .rs files in the crate tree, not just the file the doc cited:

   grep -rn "FEATURE_NAME" crates/ --include="*.rs"

3. Read the body of every host function whose signature imports a type from the gated module.
4. If a #[cfg(feature = "FEATURE_NAME")] block is reached along the tick path, the feature IS exercised in production — regardless of what the doc says.
5. If no host reaches the gated block, then the "not yet wired" claim may be accurate — but verify with a call-graph grep, not just a single-file read.

Anti-pattern — trust the summary: "the prior session said X, and the prior session is in git history, so X must be true." Prior sessions make mistakes. Git commits are not authority — production code is.

Defense 2 — Stale gate-status comments live in MULTIPLE locations; fix all of them

When a feature is promoted from opt-in to DEFAULT-ON, the promotion must propagate through five documentation surfaces. Missing any one leaves a stale comment that misleads future readers.

Canonical failure (riir-ai, 2026-07-18): the npc_sleep_time comment // Default-off until G1–G5 GOAT gate passes (Plan 341 Phase 7) existed in both crates/riir-engine/src/lib.rs:629 and crates/riir-games-civ/src/npc/sleep_time_catalog.rs:48. A prior session only caught the latter; the engine lib.rs surface went unfixed.

Protocol — the 5-surface grep (run for every feature under audit):

# In each repo that touches the feature:
grep -rn "Default-off until\|Default-OFF until" crates/ --include="*.rs"
grep -n "FEATURE_NAME" Cargo.toml crates/*/Cargo.toml
grep -n "FEATURE_NAME" crates/*/src/lib.rs
ls .benchmarks/*FEATURE_NAME* 2>/dev/null

Fix discipline: all stale surfaces go in one commit, not piecemeal. The commit message should enumerate which surfaces were fixed and cite the canonical benchmark (Promotion Review NNN) as authority.

Defense 3 — Layer splits are deliberate, not bugs

Asymmetric feature-gate status across crates is OFTEN a deliberate design, not a missed propagation. Before claiming a "discrepancy", verify that each layer is gating the SAME concern. If they're gating different concerns, the asymmetry is a layer split — update the comments to explain the split; do NOT propagate the promotion.

Established layer-split patterns in this codebase:

Three-layer split pattern (the conformal_predictive_intervals extension): The existing rows above are all two-layer splits (engine + game). The conformal primitive introduced a three-layer split — engine substrate (katgpt-rs) → engine consumer state (riir-engine karc_conformal_width) → civ routing (riir-games-civ salience_conformal_width). The middle layer exists because the per-NPC Option<KarcConformalSidecar> field has measurable overhead (Bench 567) that the consumer should opt into explicitly, distinct from the IP-bearing routing policy at the civ layer. When auditing a UQ primitive with a similar shape, look for this three-layer pattern: the engine ships the math, the engine consumer gates the per-NPC state cost, the game layer gates the IP-bearing policy. Each layer's opt-in is a separate concern and should NOT be propagated.

Established propagate-the-promotion patterns (NOT splits):

Decision rule:

• Both layers gate generic, IP-free machinery → propagate the promotion to all 5 surfaces per Defense 2.
• One layer gates IP-bearing content (catalogs, direction vectors, game-design data, trained weights) → keep the IP layer opt-in, document the split with a comment explaining the rationale.
• One layer gates heavy optional deps (riir-neuron-db, riir-chain, GPU crates) → keep that layer opt-in, document the dep-cost rationale.

Protocol — before claiming a discrepancy:

1. Read both crates' Cargo.toml comments. Do they describe the SAME concern or DIFFERENT concerns?
2. If different concerns → it's a layer split. Update the comments on both sides to explain the split; do NOT propagate the promotion.
3. If same concern → it's a real discrepancy. Propagate the promotion and update all 5 surfaces per Defense 2.

Defense 4 — "Is it gated?" is a question about a CHAIN, not a line

A gating claim sourced from a bare grep 'pub mod X' is inadmissible. The matched line almost never carries the whole answer, and each missing link has already produced a wrong verdict in this workspace:

Note the first two are the same mistake at different depths — and the second one was made while writing the correction for the first. That is the signature of this defense being skipped rather than applied once.

grep -B2 is necessary but not sufficient: it fixes link 1 and is blind to links 2-4.

# The admissible form. All four links, for one item.
F=crates/riir-engine/src/deltanet/lm_head_lora_train.rs
grep -rnB2 "pub mod lm_head_lora_train;" crates/riir-engine/src/deltanet/mod.rs  # link 1
grep -rnB2 "pub mod deltanet;"           crates/riir-engine/src/lib.rs           # link 2 (repeat per ancestor)
python3 -c "import re,io;print(re.search(r'(?m)^default\s*=\s*\[(.*?)\]',io.open('crates/riir-engine/Cargo.toml').read()))"  # link 3

Resolve the closure with the tool that owns it. Manifests defeat regexes: arrays span lines, or are one 14 kB line, or nest.

# The authority. Never a regex over Cargo.toml.
cargo metadata --no-deps --format-version 1 | python3 -c "
import json,sys
p=[x for x in json.load(sys.stdin)['packages'] if x['name']=='CRATE'][0]
f=p['features']; seen=set(); stack=list(f.get('default',[]))
while stack:
    k=stack.pop()
    if k in seen: continue
    seen.add(k); stack += [t for t in f.get(k,[]) if '/' not in t]
print(len(f.get('default',[])),'direct /',len(seen),'in closure'); print(sorted(seen))"

And the closing rule: settle it with a build, not a read. Every one of the four cases above was a reading that survived review and died on first contact with cargo. A feature matrix is cheap and decisive:

# rc=0 on every arm you claim works; the load-bearing arm is the one where the
# gate is supposed to EXCLUDE something and the crate must still compile.
for f in "" deltanet_inference deltanet_ternary_inference; do ...; done

Two traps when you do run it, both of which have reported a false verdict here: cargo ... 2>&1 | tail makes $? the tail's exit, so a failed build reports success; and in zsh args="--features foo"; cargo check $args passes one argv entry (error: unexpected argument '--features foo'), so every arm of a matrix loop "fails" while the code is fine. Redirect to a file and read rc from cargo directly; pass flags via "$@".