@damiangilgonzalez/harness 1.3.12 → 1.3.14

package/targets/agents.js

@@ -32,7 +32,7 @@ const AGENT_TARGETS = {
   claude: { dir: '.claude/agents', ext: '.md', format: 'md', model: (t) => (t === 'heavy' ? 'opus' : 'sonnet') },
   junie: { dir: '.junie/agents', ext: '.md', format: 'md', model: (t) => (t === 'heavy' ? 'opus' : 'sonnet') },
   cursor: { dir: '.cursor/agents', ext: '.md', format: 'md', model: (t) => TIER_MODEL.anthropic[t] },
-  opencode: { dir: '.opencode/agents', ext: '.md', format: 'md', mode: 'subagent', model: (t) => `anthropic/${TIER_MODEL.anthropic[t]}` },
+  opencode: { dir: '.opencode/agents', ext: '.md', format: 'md', mode: 'subagent', toolsFormat: 'map', model: (t) => `anthropic/${TIER_MODEL.anthropic[t]}` },
   gemini: { dir: '.gemini/agents', ext: '.md', format: 'md', model: (t) => TIER_MODEL.google[t] },
   copilot: { dir: '.github/agents', ext: '.agent.md', format: 'md', model: (t) => TIER_MODEL.anthropic[t] },
   kiro: { dir: '.kiro/agents', ext: '.json', format: 'json', model: (t) => (t === 'heavy' ? 'claude-opus-4' : 'claude-sonnet-4') },
@@ -68,7 +68,15 @@ ${REFUTER_FOUR_INPUTS}
 3. Did you inspect the relevant **caller, import, and relevant test**?
 4. Can the severity survive the **existing guards** you verified?
 
-If an answer is no, lower the severity or omit the finding. Every **HIGH or CRITICAL** needs the line and failure mode in the report. **Zero findings with an attack list is valid.**
+If an answer is no, lower the severity or omit the finding. Every **blocker or should-fix** needs the line and failure mode in the report. **Zero findings with an attack list is valid.**
+
+**Report findings in one shape, so the panel can be consolidated** — a fenced ${'`json findings`'} block holding an array (empty when you found nothing):
+
+${'```'}json findings
+[{ "lens": "<your lens>", "severity": "blocker|should-fix|nit|question", "file": "path/from/repo/root", "line": 42, "claim": "one sentence: what is wrong", "failure_scenario": "concrete input + state -> wrong result", "evidence": "the exact changed line, quoted" }]
+${'```'}
+
+${'`rsc review consolidate`'} merges what several lenses reported about the same place and sends each unique blocker or should-fix to ${'`finding-verifier`'}, whose job is to prove it false. A blocker or should-fix with no ${'`file`'}, ${'`line`'} or ${'`failure_scenario`'} is downgraded to a question there, mechanically.
 
 **Common false positives to reject:** an equivalent mutant with no diverging input; a documented dummy value that never reaches a sink; a deliberate boundary already enforced by a caller; generated/vendor code outside the change; style preference presented as correctness; and a theoretical race with no shared state or overlapping lifetime.
 
@@ -126,8 +134,36 @@ ${REFUTER_CONTRACT}
 
 **Check the mapping both ways:** every acceptance criterion needs a falsification procedure that can be made to fail, and every test should trace to something someone asked for.`,
   },
+  // The second half of ECC's orch-review, adapted: after `rsc review consolidate` collapses the panel's
+  // duplicates, every unique blocker/should-fix gets ONE more fresh context whose default is that the
+  // finding is false. A refuter attacks the diff; the verifier attacks the finding. Same asymmetry,
+  // pointed the other way — which is what stops an exaggerated lens from reaching the author as a blocker.
+  {
+    name: 'finding-verifier',
+    desc: 'Adversarial verifier of review findings: takes ONE consolidated finding and tries to prove it false against the code. Default stance: the finding is false; only a reproduced or traced failure is CONFIRMED. Fresh context, edits nothing.',
+    body: `You are the **finding verifier** for this project. ${'`code-review`'} hands you **one** finding that survived ${'`rsc review consolidate`'} — a blocker or should-fix some refuter lens reported against a diff. Your job is to **prove it false**. Your starting position is that it is false; the finding has to beat you.
+
+**Your inputs:** the finding (location, claim, failure scenario, evidence) plus the same four the lenses had —
+
+${REFUTER_FOUR_INPUTS}
+
+**You do NOT get** the refuter's reasoning or the builder's defence. Judge the claim against the code, not against either story.
+
+**How to try to kill it:**
+1. Read the cited line **and** its callers, guards and tests — the check that makes it impossible often lives two functions up, or in a caller that never passes that input.
+2. Try the failure scenario for real when you can: run the test, execute the command, or write a throwaway check in a temp directory outside the repo. An observed failure outranks any argument.
+3. Ask whether the change **caused** it. A defect that was already there is real but does not block this delivery.
+
+**Verdict — exactly one, with its proof:**
+- **CONFIRMED** — you reproduced it, or traced a reachable path from a concrete input to the wrong result. Quote the output or the path. Only this verdict may block.
+- **REFUTED** — you found what makes it impossible (the guard, the caller, the type, the test). Cite it with file and line.
+- **UNPROVEN** — neither: it becomes a question for the human, and questions never block.
+
+Also state whether the severity holds. A CONFIRMED finding whose blast radius is narrow is a should-fix, not a blocker — say so. You fix nothing and edit no file: your output is the verdict, the proof, and the commands you ran.`,
+  },
 ];
 
+
 export const BASE_AGENT_NAMES = Object.freeze(AGENTS.map((agent) => agent.name));
 export { stackAgents, stackAgentNames, validateAgentCatalog };
 export const allAgentNames = () => [...BASE_AGENT_NAMES, ...stackAgentNames()];
@@ -160,7 +196,14 @@ export function writeDeveloperTier(cwd, tier) {
 function renderMd(spec, model, agent) {
   const fm = ['---', `name: ${agent.name}`, `description: "${agent.desc}"`, `model: ${model}`];
   if (spec.mode) fm.push(`mode: ${spec.mode}`);
-  if (agent.tools) fm.push(`tools: [${agent.tools.join(', ')}]`);
+  if (agent.tools) {
+    if (spec.toolsFormat === 'map') {
+      fm.push('tools:');
+      for (const tool of agent.tools) fm.push(`  ${tool}: true`);
+    } else {
+      fm.push(`tools: [${agent.tools.join(', ')}]`);
+    }
+  }
   fm.push('---', '');
   return `${fm.join('\n')}${agent.body}\n`;
 }

package/targets/claude.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, rmSyn
 import { dirname, join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { linkOrCopy } from './index.js';
+import { ensureShadowClaudeMd, removeShadowClaudeMd } from './agents-md-shadow.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 // Shell tools the PreToolUse guards listen on. On Windows the primary shell is the PowerShell tool,
@@ -48,11 +49,23 @@ export function hookWiringOf(entry) {
 // other settings are preserved. Empty event arrays (and an empty hooks object) are
 // pruned so we don't leave noise behind.
 export function unwireHook(paths) {
+  // The bootstrap lives in the COMMITTED tree, so leaving it behind does not just orphan a file the
+  // way a stray `.rsc/` entry would — it leaves an executable in something the user pushes. Nothing
+  // else removes it: uninstall and purge only ever knew about `.rsc/`.
+  try {
+    rmSync(join(paths.projectRoot, '.claude', 'rsc-bootstrap.mjs'), { force: true });
+  } catch { /* never let cleanup be the thing that fails */ }
+
+  // The shadow CLAUDE.md exists only to keep the hook from being doubled by a natively-read
+  // AGENTS.md. Unwiring the hook removes the reason for it. Only ever takes back an untouched one.
+  const shadow = removeShadowClaudeMd(paths.projectRoot);
+  const removed = shadow ? [shadow] : [];
+
   const file = paths.hookTarget;
-  if (!existsSync(file)) return [];
+  if (!existsSync(file)) return removed;
   let settings;
-  try { settings = JSON.parse(readFileSync(file, 'utf8')); } catch { return []; }
-  if (!settings.hooks) return [];
+  try { settings = JSON.parse(readFileSync(file, 'utf8')); } catch { return removed; }
+  if (!settings.hooks) return removed;
   for (const event of Object.keys(settings.hooks)) {
     settings.hooks[event] = (settings.hooks[event] || []).filter((e) => {
       const s = hookWiringOf(e);
@@ -62,7 +75,7 @@ export function unwireHook(paths) {
   }
   if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
   writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
-  return [file];
+  return [...removed, file];
 }
 
 // SessionStart runs a project-local session-start.mjs via `node`: it prints
@@ -82,6 +95,23 @@ export function unwireHook(paths) {
 const P = '${CLAUDE_PROJECT_DIR}';
 const at = (...seg) => `${P}/${seg.join('/')}`;
 
+// Everything below points at `.rsc/`, which git does not carry — so in a clone every one of these
+// commands runs against a file that is not there and the client shows the module loader's stack
+// trace instead of a hook. The fix is not to make each script survive its own absence (it cannot:
+// the guards import only node builtins, so a missing entry file fails before a line of theirs runs).
+// The fix is to point the wiring at a file that IS committed, and let it decide: delegate when the
+// harness is mounted, speak once when it is not.
+//
+// The script's own path stays in the command as an argument, so every dedup/unwire needle
+// (`.rsc/session-start.`, `.rsc/ship-guard.`, …) still matches and idempotency is untouched.
+// Three modes, because a hook's event decides what it is allowed to say. `announce` is the one hook
+// that may open with the offer (one per session, no marker needed). `guard` is a shell guard, and in
+// an unbuilt harness it is the only place that can notice someone is about to do the thing the
+// missing guard protected. `quiet` delegates and never speaks.
+const BOOTSTRAP = '.claude/rsc-bootstrap.mjs';
+const viaBootstrap = (mode, target, ...args) =>
+  [`node "${at(...BOOTSTRAP.split('/'))}"`, `"${mode}"`, `"${P}"`, `"${target}"`, ...args].join(' ');
+
 export function wireHook(paths, sourceMd, policy = {}) {
   const scriptDest = join(paths.projectRoot, '.rsc', 'session-start.mjs');
   mkdirSync(dirname(scriptDest), { recursive: true });
@@ -92,6 +122,11 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // sibling too. Missing it does not break startup — the sweep is wrapped — it just goes silent.
   copyFileSync(join(HERE, 'worktree-reaper.mjs'), join(paths.projectRoot, '.rsc', 'worktree-reaper.mjs'));
   copyFileSync(join(HERE, 'session-start.mjs'), scriptDest);
+  // The one harness file that belongs in the committed tree rather than in `.rsc/`: it is the only
+  // thing standing between a clone and seven stack traces, so it has to survive `git clone`.
+  const bootstrapDest = join(paths.projectRoot, '.claude', 'rsc-bootstrap.mjs');
+  mkdirSync(dirname(bootstrapDest), { recursive: true });
+  copyFileSync(join(HERE, 'clone-bootstrap.mjs'), bootstrapDest);
 
   let suggestRel = at(relative(paths.projectRoot, paths.skillDir('suggest')).split(sep).join('/'), 'SKILL.md');
   const operationsSuggest = join(paths.projectRoot, '.rsc', 'suggest-always-on.md');
@@ -99,7 +134,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
     writeFileSync(operationsSuggest, '# rsc-suggest — always-on operations layer\n\nRead `docs/wiki/harness/user-profile.md` before acting. Use `orient` to keep the user situated and `suggest` to offer a missing skill only when the current task needs it. Close with the configured orientation block.\n');
     suggestRel = at('.rsc', 'suggest-always-on.md');
   } else if (existsSync(operationsSuggest)) rmSync(operationsSuggest, { force: true });
-  const cmd = `node "${at('.rsc', 'session-start.mjs')}" "${suggestRel}" "${P}"`;
+  const cmd = viaBootstrap('announce', at('.rsc', 'session-start.mjs'), `"${suggestRel}"`, `"${P}"`);
 
   const file = paths.hookTarget;
   const settings = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
@@ -118,9 +153,9 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // the workspace has no harness wiki. Registered idempotently on both events, with
   // any prior rsc worklog-checkpoint entry (.sh or .mjs) dropped first.
   const wlDest = join(paths.projectRoot, '.rsc', 'worklog-checkpoint.mjs');
-  const written = [paths.hookTarget, scriptDest, wlDest];
+  const written = [paths.hookTarget, scriptDest, wlDest, bootstrapDest];
   copyFileSync(join(HERE, 'worklog-checkpoint.mjs'), wlDest);
-  const wlCmd = `node "${at('.rsc', 'worklog-checkpoint.mjs')}" "${P}"`;
+  const wlCmd = viaBootstrap('quiet', at('.rsc', 'worklog-checkpoint.mjs'), `"${P}"`);
   for (const event of ['PreCompact', 'SessionEnd']) {
     settings.hooks[event] ||= [];
     settings.hooks[event] = settings.hooks[event].filter(
@@ -140,26 +175,13 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // sello.mjs is ship-guard's sibling import (hooks are materialized file-by-file,
   // so the deterministic sello core must land next to the guard that loads it).
   copyFileSync(join(HERE, 'sello.mjs'), join(paths.projectRoot, '.rsc', 'sello.mjs'));
-  const sgCmd = `node "${at('.rsc', 'ship-guard.mjs')}" "${P}"`;
+  const sgCmd = viaBootstrap('guard', at('.rsc', 'ship-guard.mjs'), `"${P}"`);
   settings.hooks.PreToolUse ||= [];
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
     (e) => !hookWiringOf(e).includes('.rsc/ship-guard.'),
   );
   settings.hooks.PreToolUse.push({ matcher: SHELL_TOOLS, hooks: [{ type: 'command', command: sgCmd }] });
 
-  // Danger guard: a PreToolUse(Bash) hook that DENIES irreversible foot-gun commands
-  // (rm -rf, git push --force, DROP/TRUNCATE, DELETE/UPDATE without WHERE, dd to /dev,
-  // curl|bash, …) when the user-profile says the user is NON-technical (default-safe
-  // when no profile exists yet; never guards a fully `technical` user). Materialized +
-  // node-run (Windows-safe), idempotent, fail-open, opt-out via .rsc/.no-danger-guard.
-  const dgDest = join(paths.projectRoot, '.rsc', 'danger-guard.mjs');
-  copyFileSync(join(HERE, 'danger-guard.mjs'), dgDest);
-  const dgCmd = `node "${at('.rsc', 'danger-guard.mjs')}" "${P}"`;
-  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
-    (e) => !hookWiringOf(e).includes('.rsc/danger-guard.'),
-  );
-  settings.hooks.PreToolUse.push({ matcher: SHELL_TOOLS, hooks: [{ type: 'command', command: dgCmd }] });
-
   // Gitmoji guard: a PreToolUse(Bash) hook that DENIES a `git commit` whose message
   // carries no gitmoji (gitmoji.dev) in front of the Conventional Commits header. The
   // convention lives in `git-workflow`; prose asks, this hook decides — at the one
@@ -169,7 +191,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // .rsc/.no-gitmoji.
   const gmDest = join(paths.projectRoot, '.rsc', 'gitmoji-guard.mjs');
   copyFileSync(join(HERE, 'gitmoji-guard.mjs'), gmDest);
-  const gmCmd = `node "${at('.rsc', 'gitmoji-guard.mjs')}" "${P}"`;
+  const gmCmd = viaBootstrap('guard', at('.rsc', 'gitmoji-guard.mjs'), `"${P}"`);
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
     (e) => !hookWiringOf(e).includes('.rsc/gitmoji-guard.'),
   );
@@ -185,24 +207,24 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // (non-rsc) UserPromptSubmit hooks are preserved.
   const fgDest = join(paths.projectRoot, '.rsc', 'userprompt-gate.mjs');
   copyFileSync(join(HERE, 'userprompt-gate.mjs'), fgDest);
-  const fgCmd = `node "${at('.rsc', 'userprompt-gate.mjs')}" "${P}"`;
+  const fgCmd = viaBootstrap('quiet', at('.rsc', 'userprompt-gate.mjs'), `"${P}"`);
   settings.hooks.UserPromptSubmit ||= [];
   settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
     (e) => !hookWiringOf(e).includes('.rsc/userprompt-gate.'),
   );
   settings.hooks.UserPromptSubmit.push({ hooks: [{ type: 'command', command: fgCmd }] });
-  written.push(sgDest, dgDest, gmDest, fgDest, join(paths.projectRoot, '.rsc', 'sello.mjs'));
+  written.push(sgDest, gmDest, fgDest, join(paths.projectRoot, '.rsc', 'sello.mjs'));
   } else {
     for (const event of ['PreToolUse', 'UserPromptSubmit']) {
       if (!settings.hooks[event]) continue;
       settings.hooks[event] = settings.hooks[event].filter((entry) => {
         const body = hookWiringOf(entry);
-        return !body.includes('.rsc/ship-guard.') && !body.includes('.rsc/danger-guard.') &&
+        return !body.includes('.rsc/ship-guard.') &&
           !body.includes('.rsc/gitmoji-guard.') && !body.includes('.rsc/userprompt-gate.');
       });
       if (!settings.hooks[event].length) delete settings.hooks[event];
     }
-    for (const name of ['ship-guard.mjs', 'danger-guard.mjs', 'gitmoji-guard.mjs', 'userprompt-gate.mjs', 'sello.mjs']) {
+    for (const name of ['ship-guard.mjs', 'gitmoji-guard.mjs', 'userprompt-gate.mjs', 'sello.mjs']) {
       rmSync(join(paths.projectRoot, '.rsc', name), { force: true });
     }
     written.push(operationsSuggest);
@@ -213,7 +235,35 @@ export function wireHook(paths, sourceMd, policy = {}) {
     for (const id of policy.plugins) settings.enabledPlugins[id] = true;
   }
 
+  // Danger guard: its own decision, not part of the code-hook block above (#273). `init` promises it
+  // to non-technical and mixed users whatever the project is, and a plan that predates the field is
+  // read as "yes": a non-technical operations install gets the guard it was missing on its next sync,
+  // and a technical user gets a guard that stands down at runtime.
+  settings.hooks.PreToolUse ||= [];
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter((e) => !hookWiringOf(e).includes('.rsc/danger-guard.'));
+  if (policy.dangerGuard !== false) {
+    // Danger guard: a PreToolUse(Bash) hook that DENIES irreversible foot-gun commands
+    // (rm -rf, git push --force, DROP/TRUNCATE, DELETE/UPDATE without WHERE, dd to /dev,
+    // curl|bash, …) when the user-profile says the user is NON-technical (default-safe
+    // when no profile exists yet; never guards a fully `technical` user). Materialized +
+    // node-run (Windows-safe), idempotent, fail-open, opt-out via .rsc/.no-danger-guard.
+    const dgDest = join(paths.projectRoot, '.rsc', 'danger-guard.mjs');
+    copyFileSync(join(HERE, 'danger-guard.mjs'), dgDest);
+    const dgCmd = viaBootstrap('guard', at('.rsc', 'danger-guard.mjs'), `"${P}"`);
+    settings.hooks.PreToolUse.push({ matcher: SHELL_TOOLS, hooks: [{ type: 'command', command: dgCmd }] });
+    written.push(dgDest);
+  } else {
+    rmSync(join(paths.projectRoot, '.rsc', 'danger-guard.mjs'), { force: true });
+  }
+  if (!settings.hooks.PreToolUse.length) delete settings.hooks.PreToolUse;
+
   mkdirSync(dirname(file), { recursive: true });
   writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+
+  // settings.json now names this project as rsc-wired, which is the predicate the shadow reads —
+  // so this call belongs AFTER the write, not before it. No-op unless the root AGENTS.md also
+  // carries the always-on body and no CLAUDE.md exists: see targets/agents-md-shadow.js.
+  const shadow = ensureShadowClaudeMd(paths.projectRoot);
+  if (shadow) written.push(shadow);
   return written;
 }