@hanzlaa/rcode 4.3.2 → 4.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.3.2",
+  "version": "4.3.3",
   "description": "rcode — the AI team that never forgets. Persistent memory, specialist agents, and slash commands for AI IDEs. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {

package/rcode/bin/rcode-hooks.cjs

@@ -11,6 +11,7 @@
  *   stop-verify — syntax-check files changed during the response (#744)
  *   cost-track  — append per-response token usage to cost.jsonl (#745)
  *   compact-nudge — advise /rcode-trim or /clear after N Edit/Write calls (#749)
+ *   prompt-router — nudge toward rcode commands for memory consistency (#892)
  *
  * All subcommands read stdin JSON from the hook execution context.
  * Pure Node stdlib. No external dependencies.
@@ -19,6 +20,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { execSync, spawnSync } = require('child_process');
 
 /**
  * Read and parse stdin JSON.
@@ -337,8 +339,6 @@ async function bashGuard() {
  */
 async function preCompact() {
   try {
-    const path = require('path');
-    const { execSync } = require('child_process');
     await readInputJson(); // drain the PreCompact event payload
 
     const cwd = process.cwd();
@@ -518,8 +518,6 @@ async function preCompact() {
  */
 async function stopVerify() {
   try {
-    const path = require('path');
-    const { spawnSync } = require('child_process');
     const input = await readInputJson();
 
     let changed =
@@ -623,6 +621,339 @@ async function costTrack() {
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// INTENT_TABLE — keyword map for prompt-router (#892)
+//
+// WHY: When a user types a free-form prompt that matches a known rcode workflow,
+// we nudge them toward the matching command so the outcome is captured in
+// .rcode/state.json. Work done outside rcode commands never lands in state.
+//
+// Single source of truth: rcode/workflows/do.md routing table (lines ~285-320,
+// "If the text describes..."). Keep in sync — see test/prompt-router-table-sync.test.cjs
+// (Sprint 38.3).
+//
+// Order: first-match-wins, mirroring do.md's "Apply the first matching rule".
+// More-specific keyword sets come before broad ones.
+// ─────────────────────────────────────────────────────────────────────────────
+const INTENT_TABLE = [
+  // do.md: "Starting a new project, 'set up', 'initialize'" → /rcode-new-project
+  {
+    intent: 'new-project',
+    keywords: ['set up a new project', 'initialize a new project', 'start a new project', 'create a new project'],
+    command: '/rcode-new-project',
+  },
+  // do.md: "Mapping or analyzing an existing codebase" → /rcode-map-codebase
+  {
+    intent: 'map-codebase',
+    keywords: ['map the codebase', 'map this codebase', 'analyze the codebase', 'analyse the codebase', 'map existing codebase'],
+    command: '/rcode-map-codebase',
+  },
+  // do.md: "A bug, error, crash, failure, or something broken" → /rcode-debug
+  // 'error' alone is too broad (matches "what does this error mean?" etc.).
+  // Use multi-word forms that signal debug intent rather than a question.
+  {
+    intent: 'debug',
+    keywords: ['bug', 'getting an error', 'throwing an error', 'error in the', 'fix the error', 'debug this', 'crash', 'failure', 'broken', 'not working', 'fails', 'exception', 'traceback'],
+    command: '/rcode-debug',
+  },
+  // do.md: "Audit code quality, 'review changes', 'karpathy', 'check my diff', 'too complex'" → /rcode-review --karpathy
+  {
+    intent: 'audit-karpathy',
+    keywords: ['audit', 'review changes', 'check my diff', 'karpathy', 'too complex', 'complexity', 'code review'],
+    command: '/rcode-review --karpathy',
+  },
+  // do.md: "Make it simpler, 'be lazy', 'simplest solution', 'yagni', 'over-engineered'" → /rcode-lazy
+  // Generative simplicity lens (before code is written); /rcode-trim removes bloat after.
+  // 'simplify' alone is too broad (overlaps rcode-trim's existing-code territory) — use intent-bearing phrases.
+  {
+    intent: 'lazy',
+    keywords: ['be lazy', 'lazy mode', 'simplest solution', 'yagni', 'over-engineered', 'over-engineering', 'kam code likho'],
+    command: '/rcode-lazy',
+  },
+  // do.md: "Walk through a change, 'checkpoint', 'explain this diff', 'human review'" → /rcode-checkpoint-preview
+  {
+    intent: 'checkpoint',
+    keywords: ['checkpoint', 'explain this diff', 'human review', 'walk through the change', 'walk through this change'],
+    command: '/rcode-checkpoint-preview',
+  },
+  // do.md: "Brainstorm, generate ideas, 'explore options', 'what could we do'" → /rcode-brainstorm
+  {
+    intent: 'brainstorm',
+    keywords: ['brainstorm', 'generate ideas', 'explore options', 'what could we do', 'ideate', 'ideas for'],
+    command: '/rcode-brainstorm',
+  },
+  // do.md: "Exploring, researching, comparing, or 'how does X work'" → /rcode-research-phase
+  // 'research' alone fires on "based on my research..." (past-tense reference, not navigation intent).
+  // 'how does'/'how do' fire on any factual question — removed in favour of intent-bearing phrases.
+  {
+    intent: 'explore',
+    keywords: ['explore', 'research phase', 'do some research', 'comparing', 'investigate', 'look into', 'understand how'],
+    command: '/rcode-research-phase',
+  },
+  // do.md: "Scope unclear, 'which one', 'better UX', 'how should X look'" → /rcode-discuss-phase
+  {
+    intent: 'discuss',
+    keywords: ['which one', 'better ux', 'how should', 'still have confusion', 'conflicting', 'discuss the scope', 'design this', 'architect this'],
+    command: '/rcode-discuss-phase',
+  },
+  // do.md: "A complex task: refactoring, migration, multi-file architecture, system redesign,
+  // integrating a new system/service" → /rcode-add-phase
+  // 'integration'/'integrate' catch "let's do X integration", "integrate with Y" — feature-sized
+  // architectural work that belongs in a phase, not an ad-hoc edit (#907).
+  // Known mild false-positive: "run the integration tests" also matches → a harmless soft
+  // nudge toward /rcode-add-phase. Accepted: catching real integration work outweighs it,
+  // and no clean substring separates "X integration" from "integration test".
+  {
+    intent: 'add-phase',
+    keywords: ['refactor', 'migration', 'multi-file', 'system redesign', 'multi file', 'large refactor', 'architectural', 'integration', 'integrate'],
+    command: '/rcode-add-phase',
+  },
+  // do.md: "'Sprint planning', 'plan the sprint', 'next sprint'" → /rcode-sprint-planning
+  {
+    intent: 'sprint-planning',
+    keywords: ['sprint planning', 'plan the sprint', 'next sprint', 'what\'s in this sprint', "what's in this sprint"],
+    command: '/rcode-sprint-planning',
+  },
+  // do.md: "Executing a sprint, 'run the sprint', 'start sprint'" → /rcode-execute-sprint
+  {
+    intent: 'execute-sprint',
+    keywords: ['run the sprint', 'start sprint', 'execute sprint', 'work on sprint'],
+    command: '/rcode-execute-sprint',
+  },
+  // do.md: "Planning a specific phase, 'plan phase N'" → /rcode-plan
+  {
+    intent: 'plan',
+    keywords: ["let's plan", 'plan phase', 'plan this', 'let me plan', 'planning phase', 'create a plan', 'please plan', 'plan and think', 'scope this', 'scope the feature'],
+    command: '/rcode-plan',
+  },
+  // do.md: "'Create milestones', 'plan milestones', 'create roadmap'" → /rcode-new-milestone
+  {
+    intent: 'new-milestone',
+    keywords: ['create milestones', 'plan milestones', 'create roadmap', 'break project into milestones', 'new milestone', 'what milestones'],
+    command: '/rcode-new-milestone',
+  },
+  // do.md: "Break milestone into epics/stories, 'create stories', 'user stories', 'epics'" → /rcode-create-epics-and-stories
+  {
+    intent: 'epics-stories',
+    keywords: ['create epics', 'user stories', 'create stories', 'epics and stories', 'break into epics'],
+    command: '/rcode-create-epics-and-stories',
+  },
+  // do.md: "Drift / out-of-date / 'audit feature docs' / 'fill out existing PRD'" → /rcode-feature-drift
+  {
+    intent: 'feature-drift',
+    keywords: ['out of date', 'out-of-date', 'verify docs', 'audit feature docs', 'fill out existing', 'prd drift', 'docs vs code'],
+    command: '/rcode-feature-drift',
+  },
+  // do.md: "General audit / re-audit / extend / fill out / expand an existing artifact" → /rcode-audit
+  {
+    intent: 'audit',
+    keywords: ['re-audit', 'extend the audit', 'fill out the', 'expand the', 're audit'],
+    command: '/rcode-audit',
+  },
+];
+
+/**
+ * Inline flat-YAML parser — mirrors parseSimpleYaml in rcode-tools.cjs:91.
+ * Supports `key: value` lines only; strips `#` comments; unquotes.
+ * Kept inline so this file stays standalone (no cross-file require).
+ */
+function parseSimpleYamlInline(text) {
+  const out = {};
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/#.*$/, '').trim();
+    if (!line) continue;
+    const colonAt = line.indexOf(':');
+    if (colonAt === -1) continue;
+    const key = line.slice(0, colonAt).trim();
+    let val = line.slice(colonAt + 1).trim();
+    if (val.startsWith('"') && val.endsWith('"')) val = val.slice(1, -1);
+    if (val.startsWith("'") && val.endsWith("'")) val = val.slice(1, -1);
+    out[key] = val;
+  }
+  return out;
+}
+
+/**
+ * Read prompt_nudge from .rcode/config.yaml.
+ * Returns 'every' | 'once-per-intent' | 'when-stale' | 'off'.
+ * Defaults to 'every' when key is absent, file is missing, or value is unknown.
+ */
+function readPromptNudgeToggle(cwd) {
+  const VALID = new Set(['every', 'once-per-intent', 'when-stale', 'off']);
+  try {
+    const cfgPath = path.join(cwd, '.rcode', 'config.yaml');
+    const text = fs.readFileSync(cfgPath, 'utf8');
+    const parsed = parseSimpleYamlInline(text);
+    const val = (parsed.prompt_nudge || '').trim().toLowerCase();
+    return VALID.has(val) ? val : 'every';
+  } catch {
+    return 'every';
+  }
+}
+
+/**
+ * Determine whether a nudge is stale enough to fire under 'when-stale' mode.
+ *
+ * Heuristic: fire when .rcode/state.json exists AND its mtime is older than
+ * the most recent git commit timestamp, OR when state.json is absent in a
+ * .planning/ project. This is cheap and best-effort — if any check fails the
+ * function returns true (treat as stale = fire). All I/O is wrapped in
+ * try/catch to preserve the fail-open contract.
+ */
+function isStateStaleFallbackTrue(cwd) {
+  try {
+    const statePath = path.join(cwd, '.rcode', 'state.json');
+    const planningDir = path.join(cwd, '.planning');
+    const hasPlanning = fs.existsSync(planningDir);
+
+    if (!fs.existsSync(statePath)) {
+      // No state.json at all — if there IS a .planning/ dir, that means we're
+      // in a project that should have state but doesn't: treat as stale.
+      return hasPlanning;
+    }
+
+    // state.json exists — check its mtime vs last commit timestamp.
+    const stateMtime = fs.statSync(statePath).mtimeMs;
+    let lastCommitTs = null;
+    try {
+      const tsStr = execSync('git log -1 --format=%ct 2>/dev/null', {
+        cwd, encoding: 'utf8', timeout: 2000,
+      }).trim();
+      if (tsStr) lastCommitTs = parseInt(tsStr, 10) * 1000;
+    } catch { /* git unavailable or no commits */ }
+
+    if (lastCommitTs === null) return false; // can't determine, don't nag
+    return stateMtime < lastCommitTs;
+  } catch {
+    return true; // fail open: treat as stale
+  }
+}
+
+/**
+ * prompt-router: Nudge user toward rcode commands for memory consistency (#892).
+ *
+ * Runs on UserPromptSubmit. Reads stdin JSON synchronously (mirror
+ * cli/rcode-slash-router.cjs — NOT the async readInputJson() which rejects on
+ * bad JSON). Keyword-matches against INTENT_TABLE (derived from
+ * rcode/workflows/do.md lines ~285-320). On match, emits a one-line advisory
+ * via hookSpecificOutput.additionalContext. Gated by prompt_nudge config toggle.
+ * Always exits 0 with no output on any error or non-match.
+ */
+function promptRouter() {
+  try {
+    // Read stdin synchronously — mirrors cli/rcode-slash-router.cjs readStdin().
+    let raw = '';
+    try {
+      raw = fs.readFileSync(0, 'utf8');
+    } catch {
+      process.exit(0);
+    }
+
+    if (!raw.trim()) process.exit(0);
+
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      process.exit(0);
+    }
+
+    // Multi-spelling prompt field fallback — mirrors rcode-slash-router.cjs.
+    const prompt =
+      data.prompt ??
+      data.user_prompt ??
+      data.userPrompt ??
+      data.message ??
+      data.input ??
+      '';
+
+    if (typeof prompt !== 'string' || !prompt.trim()) process.exit(0);
+
+    const trimmed = prompt.trimStart();
+
+    // Skip prompts that already start with /rcode- — slash router handles those.
+    if (/^\/rcode-/.test(trimmed)) process.exit(0);
+
+    const hookEventName =
+      data.hook_event_name || data.hookEventName || 'UserPromptSubmit';
+    const cwd = process.cwd();
+
+    // ── Config toggle ────────────────────────────────────────────────────
+    const nudgeMode = readPromptNudgeToggle(cwd);
+    if (nudgeMode === 'off') process.exit(0);
+
+    // ── when-stale: check if state is stale ──────────────────────────────
+    if (nudgeMode === 'when-stale' && !isStateStaleFallbackTrue(cwd)) {
+      process.exit(0);
+    }
+
+    // ── Keyword match (first-match-wins, case-insensitive) ───────────────
+    const lower = prompt.toLowerCase();
+    let matched = null;
+    for (const entry of INTENT_TABLE) {
+      for (const kw of entry.keywords) {
+        if (lower.includes(kw.toLowerCase())) {
+          matched = entry;
+          break;
+        }
+      }
+      if (matched) break;
+    }
+
+    if (!matched) process.exit(0);
+
+    // ── once-per-intent dedupe ───────────────────────────────────────────
+    if (nudgeMode === 'once-per-intent') {
+      // Fallback key: parent PID + hourly bucket — scopes naturally to the
+      // current shell session without requiring session_id in the payload.
+      // Without this, every session shares 'default' and a dedupe file from
+      // session A silences nudges in session B permanently.
+      const sessionFallback =
+        String(process.ppid) + '-' + String(Math.floor(Date.now() / 3600000));
+      const sessionId =
+        data.session_id || data.tool_input?.session_id || sessionFallback;
+      const dedupeFile = path.join(
+        os.tmpdir(),
+        'rcode-prompt-nudge-' + sessionId + '.json'
+      );
+      try {
+        let seen = [];
+        try {
+          seen = JSON.parse(fs.readFileSync(dedupeFile, 'utf8'));
+          if (!Array.isArray(seen)) seen = [];
+        } catch { /* first run or missing file */ }
+
+        if (seen.includes(matched.intent)) process.exit(0);
+
+        seen.push(matched.intent);
+        try { fs.writeFileSync(dedupeFile, JSON.stringify(seen)); } catch {}
+      } catch {
+        // dedupe file unreadable/locked → fire anyway (fail open)
+      }
+    }
+
+    // ── Emit advisory ────────────────────────────────────────────────────
+    // #907 RC2: lead with the directive ("use X"), not a soft "consider" — a
+    // gentle memory-framed tip loses the skill-selection race to imperative
+    // SessionStart primers (e.g. superpowers' "you MUST invoke"). The memory
+    // rationale stays, but as the fallback note rather than the headline.
+    const advisory =
+      `Use ${matched.command} for this ${matched.intent} task — it's the rcode workflow built for it, and it records the outcome in .rcode/state.json. ` +
+      `Prefer it over handling this ad-hoc; if you do proceed manually, run /rcode-memory-update afterward so long-term memory stays consistent.`;
+
+    const payload = {
+      hookSpecificOutput: {
+        hookEventName,
+        additionalContext: advisory,
+      },
+    };
+    process.stdout.write(JSON.stringify(payload));
+  } catch {
+    // Fail open — never break the host CLI's prompt.
+  }
+  process.exit(0);
+}
+
 /**
  * compact-nudge: Advise /rcode-trim or /clear after N Edit/Write calls (#749).
  *
@@ -698,14 +1029,21 @@ async function main() {
     case 'compact-nudge':
       await compactNudge();
       break;
+    case 'prompt-router':
+      promptRouter(); // synchronous — exits inside; never falls through to async path
+      break;
     default:
       console.error(`Unknown subcommand: ${subcommand}`);
-      console.error('Usage: rcode-hooks.cjs pre-edit|pre-workflow|post-commit|bash-guard|pre-compact|stop-verify|cost-track|compact-nudge');
+      console.error('Usage: rcode-hooks.cjs pre-edit|pre-workflow|post-commit|bash-guard|pre-compact|stop-verify|cost-track|compact-nudge|prompt-router');
       process.exit(1);
   }
 }
 
-main().catch((err) => {
-  console.error(`Fatal error: ${err.message}`);
-  process.exit(1);
-});
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`Fatal error: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = { INTENT_TABLE };

package/rcode/commands/lens-audit.md

@@ -12,22 +12,24 @@ triggers:
   - run performance lens
   - run testability lens
   - run all lenses
-  - 15 lens audit
+  - 16 lens audit
+  - yagni lens
+  - over-engineering audit
 not-for:
   - phase audit (use /rcode-audit phase)
   - milestone audit (use /rcode-audit milestone)
   - karpathy audit without lens context (use /rcode-review --karpathy)
-description: Run a structured 15-lens code audit. Picks one lens or all 15 sequentially. Prints findings and ready-to-paste GitHub issue bodies. Never auto-fixes — audit-first.
-argument-hint: "[<1-15> | <lens-name> | all]"
+description: Run a structured 16-lens code audit. Picks one lens or all 16 sequentially. Prints findings and ready-to-paste GitHub issue bodies. Never auto-fixes — audit-first.
+argument-hint: "[<1-16> | <lens-name> | all]"
 allowed-tools: Read, Write, Bash, AskUserQuestion
 ---
 
 ## Overview
 
-15-lens audit entry point. Each lens is an independent inspection angle:
+16-lens audit entry point. Each lens is an independent inspection angle:
 security, performance, testability, extensibility, dep-health, error-recovery,
 state-machine, i18n, documentation, cross-platform, karpathy, sxo,
-observability, naming, coverage.
+observability, naming, coverage, yagni.
 
 Runs the selected lens(es), prints labelled findings, outputs GH issue bodies
 for each lens with findings. Never modifies files — audit-first, fix-second.
@@ -66,5 +68,5 @@ foldable GitHub issue bodies ready to copy-paste or pipe to `gh issue create`.
 **Negative — wrong lens number:**
 ```
 /rcode-lens-audit 99
-→ Error: lens must be 1-15 or a lens name. Run /rcode-lens-audit --help.
+→ Error: lens must be 1-16 or a lens name. Run /rcode-lens-audit --help.
 ```

package/rcode/skills/SKILLS_INDEX.md

@@ -1,6 +1,6 @@
 # rcode — Skills Index
 
-All 86 skills in rcode, organized by category: 23 agent skills, 38 action skills, 25 core skills, plus 2 shared modules.
+All 87 skills in rcode, organized by category: 23 agent skills, 38 action skills, 26 core skills, plus 2 shared modules.
 
 ## Agent Skills (23)
 
@@ -88,11 +88,12 @@ Invoked by agents via the capabilities table in their SKILL.md. Organized by SDL
 
 ---
 
-## Core Skills (25)
+## Core Skills (26)
 
 Shared utilities used across agents and workflows.
 
 - `core/rcode-init` — INTERNAL config loader (installs to .rcode/skills/, not .claude/skills/)
+- `core/rcode-lazy` — always-on YAGNI/simplicity lens; prevents bloat before code is written (rcode-trim removes it after)
 - `core/rcode-help` — meta-help on available skills
 - `core/rcode-brainstorming` — structured brainstorming workflow
 - `core/rcode-advanced-elicitation` — advanced requirements elicitation

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/SKILL.md

@@ -74,6 +74,16 @@ independent agents.
 
 ---
 
+## Safety — blast radius of skip-permissions agents
+
+Every orchestrated agent runs `cld` (= `claude --dangerously-skip-permissions`). There is **no human gate** on local destructive commands — an agent can `rm`, `git reset --hard`, overwrite files, or run any shell command without asking. So:
+
+- **Scope each agent prompt to its own worktree + area only.** State the worktree path and branch explicitly, and tell the agent to stay inside it.
+- **Worktree isolation is the only containment.** With permissions skipped, a per-agent git worktree is the single boundary that keeps one agent's mistakes from touching another's work or the main tree.
+- **Never point an autonomous agent at a shared or important tree** (your main checkout, a production clone, anything you can't afford to lose). Always a throwaway worktree.
+
+---
+
 ## herdr CLI reference
 
 ```bash
@@ -118,6 +128,8 @@ Full Phase 0-3 protocol, integration-branch rules, wave cadence, and anti-patter
 in **`references.md`** (sibling file). Key constraints:
 
 - Maintain one `campaign-integration` branch; sub-agents fork from it, never master.
+- Each wave agent reads `.planning/campaign/SHARED.md` first and appends a one-line claim
+  (`area — agent N — status`) so same-wave agents don't duplicate work.
 - Wave size: 3-5 agents, 10-15 min per wave. ScheduleWakeup ends EVERY turn.
 - Phase 3: show user the full diff + ask explicitly how to land (PR / merge / squash / leave).
 - Never push to origin master without an explicit yes — per campaign, not per session.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/backlog-building.md

@@ -52,6 +52,19 @@ git commit -m "chore(campaign): backlog snapshot at wave <N>"
 ```
 The `-f` is required if `.planning/` is gitignored (common in Rihal projects).
 
+### Campaign retro (optional)
+At campaign end, append a short `.planning/campaign/RETRO.md` so the *next* campaign on this repo starts smarter:
+- Wave sizes actually used (and which felt right vs too big).
+- What stalled — areas that needed re-dispatch, conflict hotspots, agents that went silent.
+- What merged clean on the first pass.
+
+```bash
+git add -f .planning/campaign/RETRO.md
+git commit -m "chore(campaign): retro notes for next campaign"
+```
+
+**YAGNI tension (be honest)**: this is speculative tooling — a second campaign on the same repo may never happen, and a RETRO doc no one reads is exactly the kind of over-engineering Lens 16 flags. Write it only when a follow-up campaign is genuinely likely; for a one-off campaign, skip it.
+
 ## Examples
 
 ### Building backlog from audit docs

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/merge-strategy.md

@@ -27,6 +27,23 @@ fi
 ```
 **Never compound regressions across waves.**
 
+### Per-agent verification gate (beyond compile)
+A passing TSC count proves the tree compiles — it does NOT prove the agent did the work it claimed. Before merging a branch, verify **inside the worktree**:
+
+1. **Task/audit doc exists and claims the work.** The agent's `.planning/audits/AUDIT-<area>.md` (or task doc) must exist and describe what it changed. No doc → no merge.
+2. **`pnpm test` (or the project test command) passes for the affected area.** Run the scoped suite, not just the type-checker.
+3. **Lint is clean or unchanged.** Run the project linter; a new lint regression blocks the merge the same way a TSC regression does.
+4. **The diff is non-trivial and on-topic.** `git diff campaign-integration..<branch> --stat` — an empty diff, a whitespace-only diff, or edits outside the agent's area mean the agent didn't actually do the work. Reject and re-dispatch.
+
+Only after all four pass does the branch enter the smallest-first merge order.
+
+### Resolvable provenance
+A wave is NOT "verified" until each claimed change has an **openable evidence reference** — a passing test name you can run, a diff hunk you can read, a real `file:line` you can open. A self-declared boolean (`verified: true`, `confidence: 0.94`) is not provenance; it's a claim about provenance.
+
+**If provenance can't resolve, the gate FAILS** — treat the change as unverified and block the merge.
+
+Failure mode to watch for: a verifier that stamps `"verified / 94% confidence"` while its citation layer actually renders `[object Object]` has verified *nothing*. The boolean looks green; the evidence underneath is broken. Always click through to the citation — if the reference doesn't open to the thing it claims, the verification is void regardless of the confidence number.
+
 ### Conflict resolution (delegates to herdr-orchestration)
 - Content conflicts: read both sides, keep the **more-complete superset side**, remove markers, syntax-check, stage, commit. (See herdr-orchestration rules.)
 - AA conflicts (add/add): peek both versions; if nearly identical, keep the canonical owner's version. The "owner" is the branch whose audit doc claimed the feature.

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/orchestrator-rhythm.md

@@ -56,6 +56,9 @@ If the user picks (c) or skips: NEVER claim "Scheduling 20-min wakeup" in chat
 | Phase 3 (draining last waves) | 270s | Sub-agents finishing close to each other; don't miss the last |
 | Idle (waiting on stuck pane) | 1200s | Sub-agent stuck — give it room or surface it |
 
+### Cost ceiling — estimate before dispatch
+Before dispatching a wave, the orchestrator estimates `agents × wave-duration` (and, across the campaign, the running sum of all waves) as a rough cost proxy. If a planned campaign exceeds a ceiling — by default **~20 agent-waves** or any explicit token/budget cap the user gave — the orchestrator STOPS and asks the user to confirm before continuing rather than burning budget silently. A 17-wave × 4-agent campaign is ~68 agent-runs; surface that number up front so the user can scope it down.
+
 ### Stop conditions
 The heartbeat should stop ONLY when ALL three are true:
 - Every herdr pane is `idle` or `done`
@@ -96,6 +99,12 @@ If the orchestrator hits auto-compact mid-campaign, the first turn after must:
 
 ## Anti-Patterns
 
+### Pane status is text-scraping — trust it loosely
+
+**Problem**: `agent_status` (`working`/`blocked`/`idle`) is *inferred from the pane's visible text*, not a real process signal. A stuck agent — frozen mid-output, hung on a network call, or wedged in a loop — leaves its last tokens on screen and can read `working` indefinitely. A green `working` is not proof of progress.
+**Rule (timeout heuristic, now mandatory)**: if a pane reads `working` for **25 min straight**, `herdr pane read <id>` and inspect the actual output. If there's no new progress since the last peek (no new commit, same last line), `C-c` the pane and re-dispatch the item in the next wave. Do not wait out a silently-dead agent on the strength of its status string.
+**Optional reinforcement**: have each agent emit a heartbeat marker line periodically (e.g. `echo "[hb] wave-3 still alive $(date -u +%T)"`); then "no new `[hb]` line in N min" is a far more reliable stuck-signal than the scraped status.
+
 ### Polling every 60s
 
 **Problem**: Wakeup interval shorter than 270s burns the Anthropic prompt cache repeatedly without any real work happening (sub-agents need minutes between commits).

package/rcode/skills/actions/4-implementation/rcode-herdr-orchestration/rules/wave-design.md

@@ -13,6 +13,13 @@ A campaign with too few agents underuses parallelism; too many causes merge conf
 - **Maximum: 5.** Above 5 the merge stage becomes painful and TSC regressions compound across simultaneous changes.
 - **Sequential or concurrent waves?** Concurrent only if you have >8 distinct unrelated areas AND the merge bookkeeping is automated. Default is sequential: dispatch wave → merge → dispatch wave.
 
+### Shared coordination doc
+Every wave agent reads `.planning/campaign/SHARED.md` **before starting**, and appends a one-line claim the moment it picks up an area:
+```
+<area> — agent <N> — <status>
+```
+e.g. `crm-pipeline — agent 2 — claimed`. This stops two parallel agents in the same wave from silently grabbing the same area or file domain. The orchestrator seeds the file at wave dispatch; agents only append, never rewrite. Statuses progress `claimed` → `working` → `done` (or `skipped: <reason>`). If an agent finds its target area already claimed, it stops and reports back instead of duplicating work.
+
 ### Wave scope rules
 Each agent in a wave must:
 - Own a **distinct audit area** (no two agents touching the same file domain).
@@ -46,6 +53,20 @@ For each backlog item, score before assigning to a wave:
 - Past 25 min: peek at all panes, identify stuck agents, decide kill-or-wait.
 - Hard stop: 45 min. If a wave hasn't produced commits in 45 min, something is wrong — abort and re-dispatch.
 
+### Log cost per wave
+After each wave dispatch, append a one-line cost/agent-count note to `.planning/campaign/STATE.md` so the running campaign total stays visible (and the cost ceiling in `orchestrator-rhythm.md` can be checked against it):
+```
+wave 3: 4 agents dispatched, ~12 min target — running total: 11 agent-runs
+```
+
+### Optional reviewer agent
+For waves that touch **overlapping areas**, or campaigns running **more than 3 waves**, add one reviewer agent that runs *after* the wave's coders finish but *before* the merge step. The reviewer:
+- Reads all branch diffs for the wave (`git diff campaign-integration..<branch>` per branch).
+- Flags conflicts, scope drift, and duplicated work across the branches.
+- Reports to `.planning/campaign/STATE.md` (or a `REVIEW-wave-<N>.md`) — it does NOT merge.
+
+Keep it **optional**. For small bounded work (3-4 distinct, non-overlapping areas), the flat fan-out stays the default — a reviewer agent there is pure overhead. Add it only when the conflict surface or campaign length justifies the extra agent-run.
+
 ## Examples
 
 ### Good wave-1 composition (from real session)