@hanzlaa/rcode 4.12.1 → 4.14.0

package/rcode/bin/lib/roadmap.cjs

@@ -127,28 +127,69 @@ function extractPhases(content) {
   return phases;
 }
 
+// Requirement IDs come in two shapes and BOTH are real:
+//   REQ-AUTH, REQ-FOO-BAR   — the documented convention
+//   FOUND-01, RENT-04, OBJ-06, AUTHZ-04 — what projects actually write
+// This must stay in step with extractReqIds() in rcode-tools.cjs. Two copies of
+// this pattern already drifted once: one was widened for domain prefixes and
+// this one was not, so `roadmap get-phase` kept returning requirements: [] on
+// every domain-prefixed project.
+const REQ_ID_RE = /\bREQ-[A-Z0-9][A-Z0-9-]*\b|\b[A-Z][A-Z0-9]{1,15}-\d+[a-z]?\b/g;
+
+/**
+ * Build a matcher for a labelled block, tolerant of how the label is actually
+ * written. Roadmapper emits `**Success criteria:**` (colon inside the bold,
+ * lowercase c) while the old parser demanded `**Success Criteria**:` (colon
+ * outside). Two rcode components disagreeing about rcode's own format is what
+ * made get-phase unable to read its own roadmapper's output.
+ *
+ * Accepts: **Label:**  |  **Label**:  |  ## Label  |  Label:
+ * Returns { inline, list } — inline is same-line content, list is the block
+ * of bullet/numbered lines that follows. Callers use whichever is present.
+ */
+function matchLabelledBlock(section, label) {
+  const l = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // [ \t]* everywhere the match must NOT cross a line. Using \s* here let the
+  // label matcher swallow the newline, so the first bullet of the following
+  // list was captured as "inline" and its description text was thrown away —
+  // `- CITY-02 per-city page exists` came back as just `CITY-02`.
+  const re = new RegExp(
+    '(?:\\*\\*[ \\t]*' + l + '[ \\t]*:?[ \\t]*\\*\\*[ \\t]*:?|#{1,4}[ \\t]*' + l + '[ \\t]*:?|^[ \\t]*' + l + '[ \\t]*:)' +
+    '([^\\n]*)\\n((?:[ \\t]*(?:\\d+\\.|[-*])[ \\t]+[^\\n]+\\n?)*)',
+    'im'
+  );
+  const m = section.match(re);
+  if (!m) return null;
+  return { inline: (m[1] || '').trim(), list: m[2] || '' };
+}
+
+function splitListBlock(block) {
+  return String(block).split('\n')
+    .map((l) => l.replace(/^[ \t]*(?:\d+\.|[-*])[ \t]+/, '').trim())
+    .filter(Boolean);
+}
+
 function parseRequirements(section) {
-  // Matches both bold-style (**Requirements:**) and heading-style (### Requirements)
-  // followed by a list block.
-  const listMatch = section.match(/(?:\*\*Requirements(?::\*\*|\*\*:)|#{1,4}\s*Requirements\s*:?)[^\n]*\n((?:\s*(?:\d+\.|[-*])\s+[^\n]+\n?)+)/i);
-  if (listMatch) {
-    return listMatch[1].split('\n')
-      .map((l) => l.replace(/^\s*(?:\d+\.|[-*])\s+/, '').trim())
-      .filter(Boolean);
+  const block = matchLabelledBlock(section, 'Requirements');
+  if (block) {
+    // A following list block wins; otherwise take the same-line value, which is
+    // how roadmapper writes it: `**Requirements:** FOUND-01, FOUND-02, RENT-04`.
+    const fromList = splitListBlock(block.list);
+    if (fromList.length > 0) return fromList;
+    if (block.inline) {
+      const ids = block.inline.match(REQ_ID_RE);
+      if (ids && ids.length > 0) return [...new Set(ids)];
+      return block.inline.split(/\s*,\s*/).map(x => x.trim()).filter(Boolean);
+    }
   }
 
-  // Also capture REQ-IDs from inline lines like:
-  //   **REQs:** REQ-004, REQ-010, REQ-020
-  //   Requirements: REQ-001, REQ-002
-  //   **Covers:** REQ-001, REQ-003
-  // Collect every line in the section that contains REQ-\d+ patterns.
+  // Last resort: sweep the whole section for requirement IDs on any line
+  // (covers `**REQs:**`, `**Covers:**`, and prose mentions).
   const seen = new Set();
   const out = [];
-  const reqIdRe = /\bREQ-[A-Z0-9][A-Z0-9-]*\b/g;
   for (const line of section.split('\n')) {
-    if (!/REQ-/i.test(line)) continue;
-    const ids = line.match(reqIdRe) || [];
-    for (const id of ids) {
+    const matches = line.match(REQ_ID_RE) || [];
+    for (const id of matches) {
       if (!seen.has(id)) { seen.add(id); out.push(id); }
     }
   }
@@ -156,12 +197,11 @@ function parseRequirements(section) {
 }
 
 function parseSuccessCriteria(section) {
-  // Matches both bold-style (**Success Criteria:**) and heading-style (### Success Criteria)
-  const match = section.match(/(?:\*\*Success Criteria\*\*[^\n]*:|#{1,4}\s*Success Criteria\s*:?)\s*\n((?:\s*(?:\d+\.|[-*])\s+[^\n]+\n?)+)/i);
-  if (!match) return [];
-  return match[1].split('\n')
-    .map((l) => l.replace(/^\s*(?:\d+\.|[-*])\s+/, '').trim())
-    .filter(Boolean);
+  const block = matchLabelledBlock(section, 'Success criteria');
+  if (!block) return [];
+  const fromList = splitListBlock(block.list);
+  if (fromList.length > 0) return fromList;
+  return block.inline ? [block.inline] : [];
 }
 
 function parsePlans(section) {

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 };