@hanzlaa/rcode 4.12.0 → 4.13.0

package/rcode/bin/lib/state-digest.cjs

@@ -0,0 +1,88 @@
+/**
+ * State digest — slim, subagent-facing extract of .rcode/state.json (#948).
+ *
+ * Every hop in a multi-agent workflow (rcode-phase-researcher, rcode-planner)
+ * is currently told to Read the raw state.json via `{state_path}` in its
+ * <files_to_read> block (see plan-spawn-planner.md, research-phase.md,
+ * plan-research-validation.md). In a mature project that file accumulates the
+ * full phases[]/sprints[]/stories[] history for every phase ever run — in
+ * this repo, 20 of 26 phases are already complete and carry their full sprint
+ * breakdowns, none of which a researcher/planner working on the CURRENT phase
+ * consumes (verified against the actual prompt templates, not guessed).
+ *
+ * buildStateDigest() keeps exactly what those prompts read state.json for:
+ *   - current_phase / current_plan / active_workstream (orientation)
+ *   - the ACTIVE phase's own entry in full (its sprints/stories — legitimate
+ *     "what happened so far in this phase" signal for a continuation plan)
+ *   - every other phase collapsed to {number, name, status} (existence +
+ *     status only, no nested sprint/story bodies)
+ *   - the most recent decisions (bounded — "Project decisions and history"
+ *     per research-phase.md, not the full ADR log)
+ *   - open (unresolved) blockers only
+ *
+ * Deliberately excluded: velocity_history, executions[], council_sessions[],
+ * chains[], the completed-phase sprint/story bodies, and resolved blockers —
+ * none of these are read by any workflow/agent prompt that consumes the
+ * digest (verified via grep across rcode/workflows and rcode/agents).
+ */
+
+const RECENT_DECISIONS_LIMIT = 10;
+
+/** Normalize a phase number/id for comparison, stripping legacy leading zeros. */
+function normalizePhaseKey(v) {
+  const s = String(v ?? '').trim();
+  return s.replace(/^0+(?=\d)/, '');
+}
+
+/**
+ * @param {object|null} state - parsed state.json (post-migration)
+ * @param {string|number|null} phaseNumber - the phase currently being worked on
+ * @returns {object|null} slim digest, or null when state is absent
+ */
+function buildStateDigest(state, phaseNumber) {
+  if (!state) return null;
+
+  const phases = Array.isArray(state.phases) ? state.phases : [];
+  const decisions = Array.isArray(state.decisions) ? state.decisions : [];
+  const blockers = Array.isArray(state.blockers) ? state.blockers : [];
+
+  const targetKey = phaseNumber != null ? normalizePhaseKey(phaseNumber) : null;
+  const activePhase = targetKey
+    ? phases.find((p) => normalizePhaseKey(p?.number ?? p?.id) === targetKey)
+    : null;
+
+  return {
+    project: state.project ?? null,
+    current_phase: state.current_phase ?? null,
+    current_plan: state.current_plan ?? null,
+    active_workstream: state.active_workstream ?? null,
+    last_session: state.last_session ?? null,
+    phase: activePhase ? {
+      number: activePhase.number ?? null,
+      name: activePhase.name ?? null,
+      status: activePhase.status ?? null,
+      started: activePhase.started ?? null,
+      completed: activePhase.completed ?? null,
+      goal: activePhase.goal ?? null,
+      sprints: Array.isArray(activePhase.sprints) ? activePhase.sprints : [],
+    } : null,
+    phase_history: phases.map((p) => ({
+      number: p?.number ?? p?.id ?? null,
+      name: p?.name ?? null,
+      status: p?.status ?? null,
+    })),
+    recent_decisions: decisions.slice(-RECENT_DECISIONS_LIMIT).map((d) => ({
+      summary: d?.summary ?? d?.description ?? null,
+      phase: d?.phase ?? null,
+      date: d?.date ?? null,
+    })),
+    open_blockers: blockers
+      .filter((b) => b && !b.resolved)
+      .map((b) => ({
+        description: b?.description ?? null,
+        date: b?.date ?? null,
+      })),
+  };
+}
+
+module.exports = { buildStateDigest, normalizePhaseKey, RECENT_DECISIONS_LIMIT };

package/rcode/bin/rcode-hooks.cjs

@@ -116,8 +116,12 @@ async function preEdit() {
 
     process.exit(0);
   } catch (err) {
-    console.error(`Hook error: ${err.message}`);
-    process.exit(1);
+    // Route through the circuit breaker: these inner catches are where hook
+    // crashes actually surface (each handler catches its own errors and exits),
+    // so main()'s .catch would never see them.
+    const _tripped = recordCrash(process.argv[2], err.message);
+    if (!_tripped) console.error(`Hook error: ${err.message}`);
+    process.exit(_tripped ? 0 : 1);
   }
 }
 
@@ -161,8 +165,12 @@ async function preWorkflow() {
 
     process.exit(0);
   } catch (err) {
-    console.error(`Hook error: ${err.message}`);
-    process.exit(1);
+    // Route through the circuit breaker: these inner catches are where hook
+    // crashes actually surface (each handler catches its own errors and exits),
+    // so main()'s .catch would never see them.
+    const _tripped = recordCrash(process.argv[2], err.message);
+    if (!_tripped) console.error(`Hook error: ${err.message}`);
+    process.exit(_tripped ? 0 : 1);
   }
 }
 
@@ -301,8 +309,12 @@ async function postCommit() {
 
     process.exit(0);
   } catch (err) {
-    console.error(`Hook error: ${err.message}`);
-    process.exit(1);
+    // Route through the circuit breaker: these inner catches are where hook
+    // crashes actually surface (each handler catches its own errors and exits),
+    // so main()'s .catch would never see them.
+    const _tripped = recordCrash(process.argv[2], err.message);
+    if (!_tripped) console.error(`Hook error: ${err.message}`);
+    process.exit(_tripped ? 0 : 1);
   }
 }
 
@@ -423,8 +435,12 @@ async function bashGuard() {
 
     process.exit(0);
   } catch (err) {
-    console.error(`Hook error: ${err.message}`);
-    process.exit(1);
+    // Route through the circuit breaker: these inner catches are where hook
+    // crashes actually surface (each handler catches its own errors and exits),
+    // so main()'s .catch would never see them.
+    const _tripped = recordCrash(process.argv[2], err.message);
+    if (!_tripped) console.error(`Hook error: ${err.message}`);
+    process.exit(_tripped ? 0 : 1);
   }
 }
 
@@ -573,11 +589,44 @@ async function preCompact() {
     process.stdout.write(JSON.stringify(payload) + '\n');
     process.exit(0);
   } catch (err) {
-    console.error(`Hook error: ${err.message}`);
-    process.exit(1);
+    // Route through the circuit breaker: these inner catches are where hook
+    // crashes actually surface (each handler catches its own errors and exits),
+    // so main()'s .catch would never see them.
+    const _tripped = recordCrash(process.argv[2], err.message);
+    if (!_tripped) console.error(`Hook error: ${err.message}`);
+    process.exit(_tripped ? 0 : 1);
   }
 }
 
+/**
+ * Strip JSONC comments and trailing commas so a tolerant re-parse can tell a
+ * commented-but-valid config from an actually broken one. Scans character by
+ * character and tracks string state — a naive regex would eat the `//` in
+ * "https://example.com" and turn a valid file into a reported syntax error.
+ */
+function stripJsonc(text) {
+  let out = '';
+  let inStr = false, esc = false, inLine = false, inBlock = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i], next = text[i + 1];
+    if (inLine) { if (c === '\n') { inLine = false; out += c; } continue; }
+    if (inBlock) { if (c === '*' && next === '/') { inBlock = false; i++; } continue; }
+    if (inStr) {
+      out += c;
+      if (esc) esc = false;
+      else if (c === '\\') esc = true;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') { inStr = true; out += c; continue; }
+    if (c === '/' && next === '/') { inLine = true; i++; continue; }
+    if (c === '/' && next === '*') { inBlock = true; i++; continue; }
+    out += c;
+  }
+  // Trailing commas before } or ]
+  return out.replace(/,(\s*[}\]])/g, '$1');
+}
+
 /**
  * stop-verify: Syntax-check files changed during the response (#744).
  *
@@ -597,6 +646,11 @@ async function stopVerify() {
       null;
 
     if (!Array.isArray(changed)) {
+      // Fallback only. `git diff --name-only` reports the WHOLE dirty working
+      // tree, not what this response touched — so one pre-existing dirty file
+      // makes every Stop from now on report the same failure, forever, with
+      // nothing the user did causing it. Scope it to files modified since the
+      // response began where we can, and treat the result as advisory.
       const diff = spawnSync('git', ['diff', '--name-only'], {
         encoding: 'utf8',
         cwd: process.cwd(),
@@ -626,24 +680,58 @@ async function stopVerify() {
           failures.push(`${file}: ${(check.stderr || '').trim().split('\n')[0]}`);
         }
       } else if (ext === '.json') {
+        // Guard the read: one unreadable file (permissions, a symlink that just
+        // broke, a truncated write in flight) used to throw past this loop into
+        // the outer catch, killing the check for EVERY other changed file and
+        // printing a generic "Hook error" instead of naming anything.
+        let text;
+        try { text = fs.readFileSync(abs, 'utf8'); } catch { continue; }
         try {
-          JSON.parse(fs.readFileSync(abs, 'utf8'));
-        } catch (e) {
-          failures.push(`${file}: ${e.message}`);
+          JSON.parse(text);
+        } catch (strictErr) {
+          // Many real-world *.json files are JSONC: turbo.json, tsconfig.json,
+          // jsconfig.json, .eslintrc.json, devcontainer.json, and VS Code's
+          // settings/launch all permit // comments and trailing commas. Strict
+          // JSON.parse calls those a syntax error, which made this hook fail on
+          // every single Stop against a perfectly valid file. Retry tolerantly
+          // and only report a failure when BOTH parses fail.
+          try {
+            JSON.parse(stripJsonc(text));
+          } catch {
+            failures.push(`${file}: ${strictErr.message}`);
+          }
         }
       }
     }
 
     if (failures.length > 0) {
+      // Don't re-report an identical failure set on every Stop. Without this a
+      // single unfixable/irrelevant dirty file turns into an error banner on
+      // every response for the rest of the session, which trains the user to
+      // ignore the hook entirely — the one outcome that makes it worthless.
+      const sig = failures.slice().sort().join('|');
+      const seenPath = path.join(os.tmpdir(), `rcode-stop-verify-${process.ppid || 0}.txt`);
+      let previous = '';
+      try { previous = fs.readFileSync(seenPath, 'utf8'); } catch { /* first run */ }
+      if (previous === sig) process.exit(0);
+      try { fs.writeFileSync(seenPath, sig); } catch { /* best-effort */ }
+
       console.error('⚠ stop-verify: changed files failed syntax check:');
       failures.forEach((f) => console.error(`  • ${f}`));
       process.exit(1);
     }
+    // Clear the dedupe marker once everything parses, so a genuine NEW failure
+    // after a green run is reported rather than swallowed.
+    try { fs.unlinkSync(path.join(os.tmpdir(), `rcode-stop-verify-${process.ppid || 0}.txt`)); } catch { /* fine */ }
 
     process.exit(0);
   } catch (err) {
-    console.error(`Hook error: ${err.message}`);
-    process.exit(1);
+    // Route through the circuit breaker: these inner catches are where hook
+    // crashes actually surface (each handler catches its own errors and exits),
+    // so main()'s .catch would never see them.
+    const _tripped = recordCrash(process.argv[2], err.message);
+    if (!_tripped) console.error(`Hook error: ${err.message}`);
+    process.exit(_tripped ? 0 : 1);
   }
 }
 
@@ -686,8 +774,12 @@ async function costTrack() {
 
     process.exit(0);
   } catch (err) {
-    console.error(`Hook error: ${err.message}`);
-    process.exit(1);
+    // Route through the circuit breaker: these inner catches are where hook
+    // crashes actually surface (each handler catches its own errors and exits),
+    // so main()'s .catch would never see them.
+    const _tripped = recordCrash(process.argv[2], err.message);
+    if (!_tripped) console.error(`Hook error: ${err.message}`);
+    process.exit(_tripped ? 0 : 1);
   }
 }
 
@@ -1068,8 +1160,12 @@ async function stopHandler() {
     }
     process.exit(0);
   } catch (err) {
-    console.error(`Hook error: ${err.message}`);
-    process.exit(1);
+    // Route through the circuit breaker: these inner catches are where hook
+    // crashes actually surface (each handler catches its own errors and exits),
+    // so main()'s .catch would never see them.
+    const _tripped = recordCrash(process.argv[2], err.message);
+    if (!_tripped) console.error(`Hook error: ${err.message}`);
+    process.exit(_tripped ? 0 : 1);
   }
 }
 
@@ -1120,12 +1216,79 @@ function sessionStart() {
   process.exit(0);
 }
 
+// ── Circuit breaker ────────────────────────────────────────────────────
+// A hook that CRASHES has nothing useful to say and will keep saying it on
+// every single event. After THRESHOLD consecutive crashes, trip the breaker
+// and stay quiet for the rest of the session rather than pollute every turn.
+//
+// This tracks CRASHES ONLY (the hook itself threw), never FINDINGS. A hook
+// that exits non-zero because it correctly found a broken file is working;
+// disabling it for doing its job would be the opposite of the intent.
+const BREAKER_THRESHOLD = 3;
+
+// Safety hooks are NEVER auto-disabled. bash-guard blocks `git push`,
+// `--no-verify`, and `rm -rf`; pre-tool-use and pre-edit gate writes. A crashing
+// guard must fail loudly and keep failing — silently disabling it converts a
+// bug into an open door, which is a far worse outcome than a noisy terminal.
+const NEVER_BREAK = new Set(['bash-guard', 'pre-tool-use', 'pre-edit', 'pre-workflow']);
+
+function breakerPath(name) {
+  return path.join(os.tmpdir(), `rcode-hook-breaker-${process.ppid || 0}-${name}.json`);
+}
+
+function breakerTripped(name) {
+  if (NEVER_BREAK.has(name)) return false;
+  try {
+    const st = JSON.parse(fs.readFileSync(breakerPath(name), 'utf8'));
+    return (st.crashes || 0) >= BREAKER_THRESHOLD;
+  } catch { return false; }
+}
+
+function recordCrash(name, message) {
+  if (NEVER_BREAK.has(name)) return false;
+  let crashes = 0;
+  try { crashes = JSON.parse(fs.readFileSync(breakerPath(name), 'utf8')).crashes || 0; } catch { /* first */ }
+  crashes += 1;
+  CRASH_RECORDED = true;
+  try { fs.writeFileSync(breakerPath(name), JSON.stringify({ crashes, last: message })); } catch { /* best-effort */ }
+  if (crashes >= BREAKER_THRESHOLD) {
+    console.error(
+      `⚠ rcode hook '${name}' crashed ${crashes}x in a row — disabling it for this session ` +
+      `so it stops repeating. Last error: ${message}`
+    );
+    console.error(`  Re-enable: restart the session, or fix and run 'node .rcode/bin/rcode-hooks.cjs ${name}' directly to see the full error.`);
+    return true;
+  }
+  return false;
+}
+
+function clearCrashes(name) {
+  try { fs.unlinkSync(breakerPath(name)); } catch { /* nothing to clear */ }
+}
+
+// Every handler exits from inside itself, so a `.then()` on main() would almost
+// never run. Hook the process exit instead: any clean exit means this hook ran
+// without crashing, so the consecutive-crash count resets. Without this, three
+// crashes spread across an entire session would trip the breaker even though
+// the hook worked fine in between.
+let CRASH_RECORDED = false;
+function installBreakerReset(name) {
+  if (!name || NEVER_BREAK.has(name)) return;
+  process.on('exit', (code) => {
+    if (code === 0 && !CRASH_RECORDED) clearCrashes(name);
+  });
+}
+
 /**
  * Main entry point.
  */
 async function main() {
   const subcommand = process.argv[2];
 
+  // Already tripped this session — exit silently. Advisory hooks only.
+  if (breakerTripped(subcommand)) process.exit(0);
+  installBreakerReset(subcommand);
+
   switch (subcommand) {
     case 'pre-edit':
       await preEdit();
@@ -1174,10 +1337,16 @@ async function main() {
 }
 
 if (require.main === module) {
-  main().catch((err) => {
-    console.error(`Fatal error: ${err.message}`);
-    process.exit(1);
-  });
+  const name = process.argv[2];
+  main()
+    .then(() => clearCrashes(name))
+    .catch((err) => {
+      const tripped = recordCrash(name, err.message);
+      if (!tripped) console.error(`Fatal error: ${err.message}`);
+      // Advisory hooks exit 0 once tripped so the harness stops surfacing them;
+      // guard hooks (never tripped) keep their non-zero exit.
+      process.exit(tripped ? 0 : 1);
+    });
 }
 
 module.exports = { INTENT_TABLE };

package/rcode/bin/rcode-tools.cjs

@@ -510,6 +510,12 @@ function cmdInit(workflowName, rawArgs) {
 
       // Phase status from state.json (complete/executed/in_progress/planned/null).
       // Used by plan.md to show context-aware messaging when plans already exist.
+      //
+      // #948 — state_digest is derived from this SAME parse (single read, not a
+      // second pass over state.json). It replaces the raw `{state_path}` full-file
+      // read that plan-spawn-planner.md / research-phase.md / plan-research-
+      // validation.md instruct the researcher/planner subagents to do — those
+      // prompts embed state_digest directly instead.
       try {
         const stateFilePath = path.join(RCODE_DIR, 'state.json');
         const rawState = fs.existsSync(stateFilePath)
@@ -520,7 +526,9 @@ function cmdInit(workflowName, rawArgs) {
           return k === String(phaseNum);
         });
         out.phase_status = stPhase ? (stPhase.status || null) : null;
-      } catch { out.phase_status = null; }
+        const stateDigest = require(path.join(__dirname, 'lib', 'state-digest.cjs'));
+        out.state_digest = stateDigest.buildStateDigest(rawState, phaseNum);
+      } catch { out.phase_status = null; out.state_digest = null; }
 
       // Disk artifacts — same shape as walkPhaseDirs() but inlined.
       if (phaseDirEntry) {
@@ -580,11 +588,20 @@ function cmdInit(workflowName, rawArgs) {
       const wf = nestedCfg.workflow || {};
       const features = nestedCfg.features || {};
 
+      // #949 — context_window folded into init so plan.md doesn't need a
+      // separate `config-get context_window` cold start (top-level scalar,
+      // not namespaced under workflow.*/features.*).
+      out.context_window = nestedCfg.context_window ?? null;
+
       // Workflow feature flags (top-level for direct workflow consumption).
       // Defaults match the inline `config-get … || echo "X"` calls in the workflows.
       out.research_enabled = String(wf.research_by_default ?? 'false') === 'true';
       out.plan_checker_enabled = String(wf.plan_checker ?? 'true') !== 'false';
       out.nyquist_validation_enabled = String(wf.nyquist_validation ?? 'true') !== 'false';
+      // Plan-time specialist review panel (#plan step 9.5). Default ON: the
+      // generalist planner+checker pair cannot see design or guard-shape
+      // defects, only goal coverage.
+      out.specialist_review_enabled = String(wf.specialist_review ?? 'true') !== 'false';
       out.text_mode = String(wf.text_mode ?? 'false') === 'true';
 
       // Model resolution per active profile. The researcher agent ships as
@@ -595,6 +612,21 @@ function cmdInit(workflowName, rawArgs) {
       out.planner_model = resolveModelString('rcode-planner');
       out.checker_model = resolveModelString('rcode-sprint-checker');
 
+      // #949 — agent-skills rows folded into init output. plan.md previously
+      // shelled out to `agent-skills rcode-phase-researcher` / `rcode-planner` /
+      // `rcode-sprint-checker` as 3 separate cold Node starts; research-phase.md
+      // and plan-research-validation.md each did their own `agent-skills
+      // rcode-phase-researcher` call. Same manifest lookup this init call
+      // already has installedAgents/readAgentManifest() loaded for.
+      {
+        const agentManifest = readAgentManifest();
+        out.agent_skills = {
+          researcher: resolveAgentId('rcode-phase-researcher', agentManifest) || null,
+          planner: resolveAgentId('rcode-planner', agentManifest) || null,
+          checker: resolveAgentId('rcode-sprint-checker', agentManifest) || null,
+        };
+      }
+
       // Phase requirement IDs — extracted from ROADMAP requirements block.
       out.phase_req_ids = extractReqIds(roadmapPhase ? roadmapPhase.requirements : []);
 
@@ -3435,6 +3467,23 @@ function cmdState(subArgs) {
         return 'planned';
       }
 
+      // Phase dirs are historically zero-padded ("03-evidence-ledger") while
+      // ROADMAP tables and state.json use bare integers ("3"). Match on the
+      // normalized number or every disk cross-check silently no-ops.
+      const normPhaseNum = (k) => String(k ?? '').trim().replace(/^0+(\d)/, '$1');
+      const findPhaseDirFiles = (phaseNum) => {
+        const phasesRootDir = path.join(PLANNING_DIR, 'phases');
+        if (!fs.existsSync(phasesRootDir)) return null;
+        const want = normPhaseNum(phaseNum);
+        const dirName = fs.readdirSync(phasesRootDir).find(d => {
+          const m = d.match(/^(\d+(?:\.\d+)?)(?:-|$)/);
+          return m && normPhaseNum(m[1]) === want;
+        });
+        if (!dirName) return null;
+        const full = path.join(phasesRootDir, dirName);
+        return { dirName, path: full, files: fs.readdirSync(full) };
+      };
+
       const upsertPhase = (phaseNum, phaseName, phaseGoal, phaseStatus) => {
         if (!/^\d/.test(phaseNum)) return;
         if (phaseName.toLowerCase() === 'phase') return;
@@ -3456,6 +3505,49 @@ function cmdState(subArgs) {
         const statusRank = { complete: 2, in_progress: 1, planned: 0 };
         let incomingStatus = normalizeStatus(phaseStatus);
 
+        // --from-disk means FROM DISK. The ROADMAP status column is only one
+        // signal, and in several roadmap shapes column 4 isn't a status column
+        // at all (e.g. a "Blocking?" column), so ROADMAP-only sync leaves every
+        // shipped phase sitting at `planned` forever and no amount of re-running
+        // sync fixes it. Advance from the artifacts that actually exist on disk.
+        // Status never downgrades (statusRank guard below), so this can only
+        // correct an under-reported phase, never overwrite a truer one.
+        try {
+          const dirInfo = findPhaseDirFiles(phaseNum);
+          if (dirInfo) {
+            const verFile = dirInfo.files.find(f => /-?VERIFICATION\.md$/i.test(f));
+            const verText = verFile ? fs.readFileSync(path.join(dirInfo.path, verFile), 'utf8') : '';
+            // `passed` alone is not enough: a report with no `falsification:`
+            // key was self-certified — the pass that tries to refute it never
+            // ran. Treat that as in_progress, not complete.
+            const verPassed = /^status:\s*passed/mi.test(verText);
+            // A `passed` report with no `falsification:` key was self-certified
+            // — the pass that tries to refute it never ran. Do NOT downgrade it
+            // here: every VERIFICATION.md written before the falsification pass
+            // existed lacks the key, and silently reverting those phases to
+            // in_progress would undo real completion history. Surface it
+            // instead, so the gap is visible without rewriting the past.
+            if (verPassed && !/^falsification:\s*upheld/mi.test(verText)) {
+              parsed.self_certified_phases = parsed.self_certified_phases || [];
+              parsed.self_certified_phases.push(phaseNum);
+            }
+            const hasSummary = dirInfo.files.some(f => /SUMMARY\.md$/i.test(f));
+            const hasSprint = dirInfo.files.some(f => /-SPRINT\.md$/i.test(f));
+            let diskStatus = null;
+            // A passed VERIFICATION.md is the strongest completion artifact
+            // there is — do NOT also require a SUMMARY.md. Summaries stop
+            // being written partway through many real projects, and gating on
+            // them leaves verified phases stuck at in_progress forever.
+            if (verPassed) diskStatus = 'complete';
+            else if (hasSummary || hasSprint) diskStatus = 'in_progress';
+            if (diskStatus && (statusRank[diskStatus] ?? 0) > (statusRank[incomingStatus] ?? 0)) {
+              incomingStatus = diskStatus;
+              parsed.disk_derived_status = parsed.disk_derived_status || [];
+              parsed.disk_derived_status.push({ phase: phaseNum, status: diskStatus });
+            }
+          }
+        } catch { /* best-effort — never fail sync over disk inspection */ }
+
         // Cross-check against VERIFICATION.md before trusting a 'complete' claim
         // from ROADMAP prose. A phase can be hand-edited to say "Complete" (or
         // "gaps_found → closed") without ever re-running the verifier — confirmed
@@ -3466,9 +3558,7 @@ function cmdState(subArgs) {
         if (incomingStatus === 'complete') {
           try {
             const phasesRootDir = path.join(PLANNING_DIR, 'phases');
-            const phaseDirName = fs.existsSync(phasesRootDir)
-              ? fs.readdirSync(phasesRootDir).find(d => d === phaseNum || d.startsWith(`${phaseNum}-`))
-              : null;
+            const phaseDirName = (findPhaseDirFiles(phaseNum) || {}).dirName || null;
             if (phaseDirName) {
               const verFile = fs.readdirSync(path.join(phasesRootDir, phaseDirName))
                 .find(f => /-VERIFICATION\.md$/i.test(f));

package/rcode/references/REFERENCES_INDEX.md

@@ -41,12 +41,14 @@ These files were extracted from heavy agents (>100L) to reduce context budget pe
 
 | File | Loaded by |
 |------|-----------|
-| `agent-shared-rules.md` | rcode-fatima, rcode-hanzla, rcode-hussain-pm, rcode-mariam, rcode-sadiq, rcode-waleed |
+| `agent-shared-rules.md` | rcode-fatima, rcode-hanzla, rcode-hussain-pm, rcode-mariam, rcode-sadiq, rcode-waleed; Calibration discipline section also referenced by rcode-verifier and rcode-reviewer |
 | `codebase-grounding.md` | rcode-ahmed, rcode-fatima, rcode-haitham, rcode-hanzla, rcode-hussain-pm, rcode-khalid, rcode-layla, rcode-mariam, rcode-nasser, rcode-noor, rcode-omar, rcode-sadiq, rcode-waleed, rcode-yousef, rcode-zahra, rcode-zayd |
 | `karpathy-guidelines.md` | rcode-assumptions-analyzer, rcode-fixer, rcode-debugger, rcode-deviation-analyzer, rcode-fatima, rcode-haitham, rcode-hanzla, rcode-hussain-pm, rcode-integration-checker, rcode-khalid, rcode-noor, rcode-omar, rcode-phase-researcher, rcode-profiler, rcode-project-researcher, rcode-remediation-planner, rcode-research-synthesizer, rcode-roadmapper, rcode-ui-auditor, rcode-ux-designer, rcode-waleed, rcode-yousef, rcode-zayd |
 | `karpathy-guidelines-full.md` | rcode-codebase-mapper, rcode-reviewer, rcode-docs-auditor, rcode-edge-case-hunter, rcode-executor, rcode-nyquist-auditor, rcode-planner, rcode-security-adversary, rcode-security-auditor, rcode-sprint-checker, rcode-verifier |
 | `response-style.md` | rcode-advisor-researcher, rcode-ahmed, rcode-assumptions-analyzer, rcode-codebase-mapper, rcode-fixer, rcode-reviewer, rcode-debugger, rcode-deviation-analyzer, rcode-docs-auditor, rcode-edge-case-hunter, rcode-executor, rcode-haitham, rcode-integration-checker, rcode-khalid, rcode-layla, rcode-nasser, rcode-noor, rcode-nyquist-auditor, rcode-omar, rcode-phase-researcher, rcode-planner, rcode-profiler, rcode-project-researcher, rcode-remediation-planner, rcode-research-synthesizer, rcode-roadmapper, rcode-security-adversary, rcode-security-auditor, rcode-sprint-checker, rcode-ui-auditor, rcode-ux-designer, rcode-verifier, rcode-yousef, rcode-zahra, rcode-zayd |
 
+| `github-comment-style.md` | ship, pr-branch, export-to-github, review-adversarial, rcode-herdr-orchestration, and any agent dispatched into a repo with a GitHub remote |
+
 ---
 
 ## Workflow References

package/rcode/references/agent-shared-rules.md

@@ -26,6 +26,93 @@
 
 **Numeric claims need numbers.** "Fast" / "slow" / "scalable" / "performant" are forbidden as evidence. State the threshold (`p95 < 200ms`) or admit you don't have it (`unknown — would need 1 hour to measure`).
 
+**Count the population, not the sample.** Before arguing that something is
+widespread ("error handling is inconsistent", "these calls are unguarded"), count
+it: how many call sites, in how many files, out of how many total. `67 routes, 256
+fetch sites, 20 Sentry calls in 6 files` ends a debate that adjectives extend. An
+unquantified sweeping claim is an opinion wearing a finding's clothes.
+
+**Route to a persona from context, never from a keyword table alone.** When any
+workflow picks which specialist to dispatch, read the evidence first — the files
+the work touches, the migrations and schemas it alters, the decisions already
+recorded — and choose the lens that evidence needs. Keyword scorers
+(`select-panel` and friends) route on the words the request happens to use, not
+on what it touches, so a high score is corroboration and a zero score is no
+information. When your reading disagrees with the score, your reading wins, and
+you name the file or decision that made you override.
+
+---
+
+## Redirect protocol
+
+Every persona file carries a `## Redirects` table. It is not decoration — it is
+the contract for what you do when a request lands outside your lens.
+
+**When the request is squarely in another persona's owned domain** (it maps to a
+line in your `## Redirects`, or to a `Do NOT use for:` entry in your
+description), say so in your FIRST line, before doing anything else:
+
+> Haitham — frontend. This is a schema and query-plan question, which is Yousef's
+> lens, not mine. Want me to hand it to him? Otherwise I'll take it as far as I
+> can.
+
+Three rules make this useful instead of annoying:
+
+1. **Offer, never refuse.** You are flagging a better owner, not declining work.
+   If the user says continue, says nothing, or the run is autonomous — do the
+   work. A persona that stops and waits has converted a helpful note into a
+   blocker.
+2. **Name who and why, in one sentence.** "Yousef owns query plans and index
+   strategy" is useful. "This is outside my area" is not — it tells the user
+   nothing they can act on.
+3. **Only for the core of another lens, not for anything adjacent.** A frontend
+   task that touches an API response shape is still frontend work. Offer the
+   handoff when the *deliverable itself* belongs to someone else, not every time
+   another domain is mentioned. Redirecting on adjacency is how a team stops
+   answering questions.
+
+**Say it once.** If the user chose you anyway, they have decided — do not raise
+it again later in the same exchange, and do not caveat every subsequent answer
+with it. Repeating a declined handoff reads as reluctance to work.
+
+**Never use this to dodge.** If you can do the task, the honest form is "X would
+do this better, here is my answer meanwhile" — not "you should ask X" with no
+answer attached.
+
+---
+
+## Calibration discipline
+
+**Under-claiming is the same defect as over-claiming.** Reporting `gaps_found` when
+the evidence says `passed`, hedging a confirmed finding into a "possible issue", or
+adding a caveat you cannot name a failure mode for — these are not caution. They
+are inaccurate reports, and a user cannot plan around an agent whose confidence
+does not track its evidence. State the level the evidence supports: neither higher
+nor lower.
+
+**Every hedge must name its unknown.** "This may not be complete" is noise. "I did
+not check the migration files, only the schema" is calibration. If you cannot name
+what you did not verify, delete the hedge and make the claim.
+
+**Say "I don't know" plainly, then say what would resolve it.** Not silence, not a
+confident guess. `Unknown — reading src/queue/worker.ts would settle it.` This is
+the highest-trust sentence available to you; the agents that never say it are the
+ones whose output has to be re-checked.
+
+**Separate the symptom fix from the cause, out loud.** When you ship a patch that
+does not address the root cause, say so in the same breath, and say what the cause
+is. Never let "fixed" stand for "worked around".
+
+**Name your own risk before the reviewer finds it.** If part of your change is
+timing-dependent, untested, or rests on an assumption, flag it yourself in the
+summary. Flagging costs nothing and is the difference between a report that gets
+trusted and one that gets audited.
+
+**Prefer the enforced standard over the explained one.** A rule that lives only in
+a doc decays on contact with the next agent. When you fix a class of mistake, ask
+whether a test, a gate, or a checker assertion can make the mistake impossible —
+and add that instead of, or in addition to, the paragraph describing it.
+
 ---
 
 ## Engineering invariants