harness-everything 0.40.0 → 0.41.0

package/hooks/scripts/lib/doc-reconciliation-qualification.json

@@ -0,0 +1,34 @@
+{
+  "schema": "harness.doc-reconciliation.qualification.v1",
+  "host": "claude-code",
+  "hostVersion": "2.1.308",
+  "captureRecordVersion": "claude-capture-record/1",
+  "run": "Run 2b",
+  "payloadKinds": {
+    "PostToolUse": [
+      "agent_id",
+      "interrupted",
+      "tool_use_id"
+    ],
+    "PreToolUse": [
+      "agent_id",
+      "tool_use_id"
+    ],
+    "SubagentStart": [
+      "agent_id"
+    ],
+    "SubagentStop": [
+      "agent_id"
+    ]
+  },
+  "correlation": {
+    "preToPostByToolUseId": true,
+    "interruptedExplicit": true,
+    "subagentStartStopSameAgent": true,
+    "agentResultAliasCorrelated": true
+  },
+  "sanitizedCapture": {
+    "file": "doc-reconciliation-capture.sanitized.jsonl",
+    "sha256": "db4d8c85d2ba0fd06f53f455f31b125dd194e9a22cb337687bc0e295a16f02e5"
+  }
+}

package/hooks/scripts/lib/workflow-obligations.js

@@ -673,6 +673,13 @@ function updateStep(context, stepId, disposition, options = {}) {
     withholdPilotVerification(context, loaded.set);
     throw new Error('document verification pending: S1 grants no document credit');
   }
+  // Review-mode refusal (pilot ON only): a self-authored or non-independent review PASS stays pending.
+  if (disposition === 'pass' && step.stepType === 'review') {
+    const pilot = require('./doc-reconciliation-pilot');
+    if (pilot.reviewRequired(loaded.set) && !pilot.independentReviewAccepted(context)) {
+      throw new Error('review pending: a self-authored or non-independent review cannot pass this step; an independent host quality review is required');
+    }
+  }
   step.status = disposition;
   step.evidence = evidence;
   step.reasonCode = reasonCode;

package/hooks/scripts/state-persist.js

@@ -4,6 +4,16 @@ const path = require('path');
 const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
 const { cwdOf, classifyShell, isVerificationShell, directMutationInWorkspace } = require('./lib/workflow-isolation');
 const { observeTool } = require('./lib/telemetry');
+
+// S2b doc-reconciliation pilot capture (docs/doc-workflow-reconciliation.md
+// § S2b "Activation and pilot-only scope", "Claude capture and origin-provider
+// contract"): pilot-only, fail-open to the host, and gated on the exact
+// switch value `1` before any collector logic runs. OFF must return to the
+// existing legacy path before pilot collection; capture never executes a
+// command, verifier or generator and never blocks a tool or Stop.
+const PILOT_CAPTURE_EVENT_NAMES = ['PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'SubagentStart', 'SubagentStop'];
+// Task/Agent results were never routed here before S2b, so they stay capture-only: the legacy handoff path does not run for them.
+const CAPTURE_ONLY_TOOLS = ['Task', 'Agent'];
 let inputData = '';
 const timeout = setTimeout(() => processState(null), 200);
 process.stdin.on('data', chunk => { inputData += chunk; });
@@ -11,7 +21,30 @@ process.stdin.on('end', () => { clearTimeout(timeout); try { processState(JSON.p
 function processState(payload) {
   try {
     const sessionId = payload && (payload.session_id || payload.sessionId);
+    const captureEventName = payload ? (payload.hook_event_name || payload.hookEventName) || '' : '';
+    const captureToolName = payload ? (payload.tool_name || payload.tool || '') : '';
+    const captureOnly = captureEventName === 'SubagentStart' || captureEventName === 'SubagentStop'
+      || captureEventName === 'PreToolUse'
+      || (captureEventName === 'PostToolUse' && CAPTURE_ONLY_TOOLS.indexOf(captureToolName) !== -1);
+    if (captureOnly && process.env.HARNESS_DOC_RECONCILIATION_PILOT !== '1') {
+      process.exit(0);
+      return;
+    }
     const root = getWorkspaceRoot(payload);
+    // SubagentStart/SubagentStop were never routed to this script before S2b.
+    // They are capture-only events: the legacy handoff state path stays
+    // untouched for them, so wiring them while OFF adds no writes at all.
+    if (captureEventName === 'SubagentStart' || captureEventName === 'SubagentStop') {
+      persistPilotCapture(payload, captureEventName, sessionId, root);
+      process.exit(0);
+      return;
+    }
+    // Pre-tool launch capture and Task/Agent result capture: capture-only, no legacy handoff state is written.
+    if (captureEventName === 'PreToolUse' || (captureEventName === 'PostToolUse' && CAPTURE_ONLY_TOOLS.indexOf(captureToolName) !== -1)) {
+      persistPilotCapture(payload, captureEventName, sessionId, root);
+      process.exit(0);
+      return;
+    }
     const stateFile = path.join(getSessionDir(root, sessionId), 'handoff-state.json');
     let state = { status: 'idle', timestamp: new Date().toISOString() };
     if (fs.existsSync(stateFile)) { try { state = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch (_) {} }
@@ -25,7 +58,7 @@ function processState(payload) {
     const rawExitCode = toolResponse.exitCode ?? toolResponse.exit_code ?? payload.exitCode;
     const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
     const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
-    const hookEvent = payload.hook_event_name || payload.hookEventName || '';
+    const hookEvent = captureEventName;
     const isSuccessEvent = hookEvent === 'PostToolUse';
     const isFailed = hookEvent === 'PostToolUseFailure' || (exitCode !== undefined && exitCode !== 0) || (!isSuccessEvent && exitCode === undefined && stderrSignal);
     const toolName = payload.tool_name || payload.tool || 'command';
@@ -44,10 +77,53 @@ function processState(payload) {
       const commandClass = classifyShell(command);
       if (commandClass !== 'read-only' && commandClass !== 'worktree-setup') state.lastEditAt = Date.now();
       // Verification evidence needs a confirmed success: a PostToolUse event or an explicit zero exit.
-      if (!isFailed && (isSuccessEvent || exitCode === 0) && isVerificationShell(command, { cwd: cwdOf(payload, root), root })) { state.lastVerifyAt = Date.now(); state.lastVerifyExitCode = exitCode ?? null; }
+      // Pilot ON only: a registered, argv-validated doc-check that resolves to this install's own runtime is the document
+      // verification evidence, and only at the shipped pin (R3-02). Any other path earns no verification evidence. OFF stays legacy.
+      const pilotEnabled = process.env.HARNESS_DOC_RECONCILIATION_PILOT === '1';
+      const docCheck = pilotEnabled ? require('./lib/doc-reconciliation-provider') : null;
+      const installedCheck = docCheck && docCheck.registeredInstalledCheck(command, cwdOf(payload, root));
+      const docCheckCandidate = installedCheck && installedCheck.kind !== 'not-candidate';
+      const pinCheckable = installedCheck && installedCheck.installed
+        && (installedCheck.kind === 'accepted' || installedCheck.reason === 'implementation-pin-mismatch');
+      // A non-candidate that is compound or names the checker is not generic verification (trustRisk); the scanner miss does not clear it.
+      const verifies = docCheckCandidate
+        ? Boolean(pinCheckable) && docCheck.fileDigest(installedCheck.installed) === docCheck.SHIPPED_DOC_CHECK_DIGEST
+        : !(pilotEnabled && docCheck.trustRisk(command)) && isVerificationShell(command, { cwd: cwdOf(payload, root), root });
+      if (!isFailed && (isSuccessEvent || exitCode === 0) && verifies) {
+        const verifiedAt = Date.now();
+        const verifiedExitCode = exitCode ?? null;
+        state.lastVerifyAt = verifiedAt;
+        state.lastVerifyExitCode = verifiedExitCode;
+        if (pilotEnabled) {
+          const source = docCheckCandidate ? 'Doc' : 'Generic';
+          state[`last${source}VerifyAt`] = verifiedAt;
+          state[`last${source}VerifyExitCode`] = verifiedExitCode;
+        }
+      }
     }
     fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
     observeTool(payload);
+    persistPilotCapture(payload, captureEventName, sessionId, root);
   } catch (_) {}
   process.exit(0);
 }
+
+// Pilot-only capture journaling. Every guard is placed before any collector
+// work; any failure is swallowed (fail-open), and the hook output/exit is
+// never changed by capture.
+function persistPilotCapture(payload, eventName, sessionId, root) {
+  try {
+    if (!payload || process.env.HARNESS_DOC_RECONCILIATION_PILOT !== '1') return;
+    if (PILOT_CAPTURE_EVENT_NAMES.indexOf(eventName) === -1) return;
+    const provider = require('./lib/doc-reconciliation-provider');
+    const entry = provider.buildCaptureRecord(payload, eventName, root);
+    if (!entry) return;
+    const sessionDir = getSessionDir(root, sessionId);
+    // Observation-time identity: the workflow and pin in force when the host event was captured.
+    const observed = provider.observedIdentityFor(sessionDir);
+    if (observed) entry.observedIdentity = observed;
+    // Each capture is one exclusively created event file; the compatibility journal is rebuilt from them (not tamper-proof).
+    provider.writeImmutableEvent(sessionDir, entry);
+    provider.rebuildJournalView(sessionDir);
+  } catch (_) { /* fail-open: capture failures never reach the host */ }
+}

package/hooks/scripts/workflow-stop-gate.js

@@ -16,7 +16,8 @@ function decide(payload) {
     const context = loadWorkflow(payload);
     const { workflow, sessionDir } = context;
     if (!workflow || workflow.state === 'deferred') return;
-    const handoff = readJson(path.join(sessionDir, 'handoff-state.json'));
+    const handoffFile = path.join(sessionDir, 'handoff-state.json');
+    let handoff = readJson(handoffFile);
     const unresolved = [];
     const diagnostics = [];
     let requiredFault = false;
@@ -36,11 +37,15 @@ function decide(payload) {
 
     required(() => planningUnresolved(context));
     if (String(workflow.strategy || '').startsWith('fable-')) {
-      if (!unresolved.length) require('./lib/doc-reconciliation-pilot').assess(context, null);
+      if (!unresolved.length) {
+        require('./lib/doc-reconciliation-pilot').assess(context, null);
+      }
       const match = matchingRun(context);
       unresolved.push(...(match ? unresolvedStages(match, workflow, handoff?.lastEditAt || 0) : ['correlated-run-missing']));
     } else {
       required(() => unresolvedObligations(context));
+      // Assessment can withdraw stale document verification; read the current aggregate afterward.
+      handoff = readJson(handoffFile);
       const lastEdit = Math.max(workflow.lastMutationAt || 0, handoff?.lastEditAt || 0);
       if (lastEdit && (handoff?.lastVerifyAt || 0) < lastEdit) unresolved.push('verification-after-edit-missing');
     }

package/opencode-plugin/README.md

@@ -104,6 +104,21 @@ new breaker failure. A reflection artifact itself does not count as a code edit.
 
 ## Installation
 
+**OpenCode 2.x (and newer 1.18.29+):** the module default-exports
+`{ id: "harness.enforcement", setup(ctx) }` and registers `ctx.tool.hook("execute.before|after")`
+plus `ctx.event.subscribe()` through the OpenCode 2 plugin context. OpenCode 2
+never loads a named-export-only plugin: it fails with `Plugin must export a
+default definition with an id and an effect or setup function`
+(SchemaError at `["default"]`). The named `HarnessEnforcement` export stays
+available for OpenCode 1.x hosts: it receives the V1 context
+(`{client, directory}`) and returns a V1 hooks object
+(`tool.execute.before`, `tool.execute.after`, `event`); the V2 `setup`
+adapter wraps that factory and maps the V2 hook events onto it, so the
+enforcement logic is shared, not duplicated.
+
+Direction:
+named factory (V1 hosts/tests) → default-export setup adapter → V2 domains.
+
 Copy `index.mjs` into opencode's plugin directory **under a `.js` filename** -
 it is self-contained, no sibling files required:
 

package/opencode-plugin/index.mjs

@@ -932,3 +932,80 @@ export const HarnessEnforcement = async ({ client, directory }) => {
     },
   }
 }
+
+// ---------------------------------------------------------------------------
+// OpenCode 2.x entrypoint.
+//
+// OpenCode 2 changed the plugin contract: a plugin default-exports
+// { id, setup(ctx) } and registers hooks through domains (ctx.tool.hook,
+// ctx.event.subscribe, ctx.session.*) instead of returning a hooks object from
+// a named factory. A named-export-only module fails to load with
+// "Plugin must export a default definition with an id and an effect or setup
+// function" (SchemaError at ["default"]) - this is what tripped the global
+// install on this machine's OpenCode 2.1.3.
+//
+// The named `HarnessEnforcement` factory above keeps the hooks-object shape
+// used by the repository mechanism tests (and by OpenCode 1.x hosts); this
+// default export adapts it to the V2 hooks. Tool hook events are verified
+// OpenCode 2.1.3 shapes: execute.before is {tool, sessionID, agent, messageID,
+// id, input} with `input` carrying the tool args; execute.after adds
+// {status, result | error}.
+export default {
+  id: "harness.enforcement",
+  async setup(ctx) {
+    const hooks = await HarnessEnforcement({
+      client: {
+        session: {
+          // V1 shutdown path calls client.session.prompt({path, body}) twice;
+          // map it onto the V2 session API instead of duplicating the code.
+          prompt: ({ path, body }) =>
+            ctx.session.prompt({
+              sessionID: path && path.id,
+              text: (body && body.parts || []).map((part) => part && part.text || "").join(""),
+            }),
+        },
+      },
+      directory: (ctx.location && ctx.location.directory) || ctx.directory,
+    })
+
+    await ctx.tool.hook("execute.before", (event) =>
+      hooks["tool.execute.before"](toolEventInput(event), { args: event.input }))
+    await ctx.tool.hook("execute.after", (event) =>
+      hooks["tool.execute.after"](toolEventInput(event), { args: event.input }))
+
+    const events = new AbortController()
+    void (async () => {
+      for await (const raw of ctx.event.subscribe({ signal: events.signal })) {
+        try {
+          await hooks.event({
+            event: {
+              type: raw.type,
+              // V1 event handlers read {type, properties}; V2 events are flat
+              // objects, so pass both shapes.
+              properties: raw.properties ?? raw,
+            },
+          })
+        } catch { // fail open, same as the hooks themselves
+        }
+      }
+    })()
+    return () => events.abort()
+  },
+}
+
+// Build the V1-shaped (input, output) pair the legacy hooks expect from the
+// V2 tool-hook event: legacy telemetry reads callID/agentID/sessionID and
+// `.args`, and edit detection reads output.args, which is the same input args
+// object in the V2 API.
+function toolEventInput(event) {
+  const input = event.input && typeof event.input === "object" ? event.input : {}
+  return {
+    ...input,
+    args: input,
+    tool: event.tool,
+    sessionID: event.sessionID,
+    agentID: event.agent,
+    callID: event.id,
+    callId: event.id,
+  }
+}

package/opencode-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-enforcement",
   "description": "Repository inventory for the opencode enforcement plugin and its standalone helper",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Harness OS: An Orchestrated Agent Operating System for AI-driven Development",
   "main": "harness-everything/scripts/bootstrap.js",
   "bin": {

package/plugins/harness-everything/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/hooks/scripts/lib/doc-reconciliation-capture.sanitized.jsonl

@@ -0,0 +1,26 @@
+{"run":"1","source":"wrapper-stdin","wrapperLabel":"PreToolUse","event":"PreToolUse","tool_use_id":"<tool-use-1>","payload":{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_use_id":"<tool-use-1>","session_id":"<session-1>","prompt_id":"<prompt-1>","tool_input_command":"node <scratch>/plugin/harness-everything/scripts/doc-check.js check --workspace <scratch>/project --config .agents/harness-everything/project-docs.json --changed-path docs/a.md","cwd":"<scratch>/project","transcript_path":"<home-path>"}}
+{"run":"2a","source":"wrapper-stdin","wrapperLabel":"PreToolUse","event":"PreToolUse","tool_use_id":"<tool-use-2>","payload":{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_use_id":"<tool-use-2>","session_id":"<session-2>","prompt_id":"<prompt-2>","tool_input_command":"node <scratch>/plugin/harness-everything/scripts/doc-check.js check --workspace <scratch>/project --config .agents/harness-everything/project-docs.json --changed-path docs/a.md","cwd":"<scratch>/project","transcript_path":"<home-path>"}}
+{"run":"2b","source":"wrapper-stdin","wrapperLabel":"PreToolUse","event":"PreToolUse","tool_use_id":"<tool-use-3>","payload":{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_use_id":"<tool-use-3>","session_id":"<session-3>","prompt_id":"<prompt-3>","tool_input_command":"node \"<scratch>/plugin/harness-everything/scripts/doc-check.js\" check --workspace <scratch>/project --config .agents/harness-everything/project-docs.json --changed-path docs/a.md","cwd":"<scratch>/project","transcript_path":"<home-path>"}}
+{"run":"2b","source":"wrapper-stdin","wrapperLabel":"PostToolUse","event":"PostToolUse","tool_use_id":"<tool-use-3>","interrupted":false,"payload":{"hook_event_name":"PostToolUse","tool_name":"Bash","tool_use_id":"<tool-use-3>","session_id":"<session-3>","prompt_id":"<prompt-3>","tool_input_command":"node \"<scratch>/plugin/harness-everything/scripts/doc-check.js\" check --workspace <scratch>/project --config .agents/harness-everything/project-docs.json --changed-path docs/a.md","cwd":"<scratch>/project","transcript_path":"<home-path>","tool_response":{"keys":["interrupted","isImage","noOutputExpected","stderr","stdout"],"interrupted":false,"digest":"sha256:22cd89eb079e65f996432f65cfd9bed1a29366def8f3f8af9af94c26c60bd1f5"}}}
+{"run":"2b","source":"wrapper-stdin","wrapperLabel":"PreToolUse","event":"PreToolUse","tool_use_id":"<tool-use-4>","payload":{"hook_event_name":"PreToolUse","tool_name":"Agent","tool_use_id":"<tool-use-4>","session_id":"<session-3>","prompt_id":"<prompt-3>","cwd":"<scratch>/project","transcript_path":"<home-path>"}}
+{"run":"2b","source":"wrapper-stdin","wrapperLabel":"SubagentStart","event":"SubagentStart","agent_id":"<agent-1>","payload":{"hook_event_name":"SubagentStart","session_id":"<session-3>","prompt_id":"<prompt-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","cwd":"<scratch>/project","transcript_path":"<home-path>"}}
+{"run":"2b","source":"wrapper-stdin","wrapperLabel":"PreToolUse","event":"PreToolUse","tool_use_id":"<tool-use-5>","agent_id":"<agent-1>","payload":{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_use_id":"<tool-use-5>","session_id":"<session-3>","prompt_id":"<prompt-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","tool_input_command":"cat docs/a.md && git diff docs/a.md && shasum -a 256 docs/a.md","cwd":"<scratch>/project","transcript_path":"<home-path>"}}
+{"run":"2b","source":"wrapper-stdin","wrapperLabel":"PreToolUse","event":"PreToolUse","tool_use_id":"<tool-use-6>","agent_id":"<agent-1>","payload":{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_use_id":"<tool-use-6>","session_id":"<session-3>","prompt_id":"<prompt-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","tool_input_command":"git diff docs/a.md","cwd":"<scratch>/project","transcript_path":"<home-path>"}}
+{"run":"2b","source":"wrapper-stdin","wrapperLabel":"PostToolUse","event":"PostToolUse","tool_use_id":"<tool-use-6>","agent_id":"<agent-1>","interrupted":false,"payload":{"hook_event_name":"PostToolUse","tool_name":"Bash","tool_use_id":"<tool-use-6>","session_id":"<session-3>","prompt_id":"<prompt-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","tool_input_command":"git diff docs/a.md","cwd":"<scratch>/project","transcript_path":"<home-path>","tool_response":{"keys":["interrupted","isImage","noOutputExpected","stderr","stdout"],"interrupted":false,"digest":"sha256:5ff449b9366059bd45c22c411728c93b8c4b5d5a083f1243c7882279b8b2e656"}}}
+{"run":"2b","source":"wrapper-stdin","wrapperLabel":"PreToolUse","event":"PreToolUse","tool_use_id":"<tool-use-7>","agent_id":"<agent-1>","payload":{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_use_id":"<tool-use-7>","session_id":"<session-3>","prompt_id":"<prompt-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","tool_input_command":"ls docs; grep -rni retr . --include=*.md","cwd":"<scratch>/project","transcript_path":"<home-path>"}}
+{"run":"2b","source":"wrapper-stdin","wrapperLabel":"PostToolUse","event":"PostToolUse","tool_use_id":"<tool-use-7>","agent_id":"<agent-1>","interrupted":false,"payload":{"hook_event_name":"PostToolUse","tool_name":"Bash","tool_use_id":"<tool-use-7>","session_id":"<session-3>","prompt_id":"<prompt-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","tool_input_command":"ls docs; grep -rni retr . --include=*.md","cwd":"<scratch>/project","transcript_path":"<home-path>","tool_response":{"keys":["interrupted","isImage","noOutputExpected","returnCodeInterpretation","stderr","stdout"],"interrupted":false,"digest":"sha256:f4f1baf50b0770a29763b15493f7c7f315321f5c2c92b5288b18d20c3480f97a"}}}
+{"run":"2b","source":"wrapper-stdin","wrapperLabel":"SubagentStop","event":"SubagentStop","agent_id":"<agent-1>","payload":{"hook_event_name":"SubagentStop","session_id":"<session-3>","prompt_id":"<prompt-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","cwd":"<scratch>/project","transcript_path":"<home-path>","agent_transcript_path":"<home-path>","last_assistant_message":"Review verdict: approve\n\nSummary: The only change to `docs/a.md` is \"retries once\" becoming \"retries twice\". The front matter is intact, and the link to `b.md` resolves because that file exists. Nothing else in the repo mentions retries, so I found no contradiction. I could not check the \"twice\" claim against the code, since this repo has no code or other source for it. I also couldn't compute a SHA-256, because the shell blocked `shasum`.\n\nReviewed artifact digest: `<scratch>/project/docs/a.md`, the working-tree version, uncommitted on top of baseline 8648a71. The identifying content is the diff hunk `@@ -3,4 +3,4 @@`, with the blob change `0936062..3bea475`. The body line is \"The checkout retries twice. See [b](b.md).\""}}
+{"run":"2b","source":"wrapper-stdin","wrapperLabel":"PostToolUse","event":"PostToolUse","tool_use_id":"<tool-use-4>","payload":{"hook_event_name":"PostToolUse","tool_name":"Agent","tool_use_id":"<tool-use-4>","session_id":"<session-3>","prompt_id":"<prompt-3>","cwd":"<scratch>/project","transcript_path":"<home-path>","tool_response":{"keys":["agentId","agentType","canContinueAgent","content","harnessNoteCount","harnessSectionHash","harnessTailCount","prompt","resolvedModel","status","toolStats","totalDurationMs","totalTokens","totalToolUseCount","usage"],"status":"completed","agentId":"<agent-1>","digest":"sha256:f035f2ed002f3dc6827f3109a8fdbc99ae439472bc504fc4d460b5bf0ac4204e"}}}
+{"run":"1","source":"journal-record","event":"PreToolUse","tool_use_id":"<tool-use-1>","record":{"captureId":"<capture-1>","event":"PreToolUse","tool_use_id":"<tool-use-1>","session_id":"<session-1>","command":"node <scratch>/plugin/harness-everything/scripts/doc-check.js check --workspace <scratch>/project --config .agents/harness-everything/project-docs.json --changed-path docs/a.md","cwd":"<scratch>/project","responseDigest":"eb045d78d273107348b0300c01d29b7552d622abbc6faf81b3ec55359aa9950c"}}
+{"run":"1","source":"journal-record","event":"PreToolUse","tool_use_id":"<tool-use-1>","record":{"captureId":"<capture-2>","event":"PreToolUse","tool_use_id":"<tool-use-1>","session_id":"<session-1>","command":"node <scratch>/plugin/harness-everything/scripts/doc-check.js check --workspace <scratch>/project --config .agents/harness-everything/project-docs.json --changed-path docs/a.md","cwd":"<scratch>/project","responseDigest":"eb045d78d273107348b0300c01d29b7552d622abbc6faf81b3ec55359aa9950c"}}
+{"run":"2b","source":"journal-record","event":"PreToolUse","tool_use_id":"<tool-use-3>","record":{"captureId":"<capture-3>","event":"PreToolUse","tool_use_id":"<tool-use-3>","session_id":"<session-3>","command":"node \"<scratch>/plugin/harness-everything/scripts/doc-check.js\" check --workspace <scratch>/project --config .agents/harness-everything/project-docs.json --changed-path docs/a.md","cwd":"<scratch>/project","responseDigest":"eb045d78d273107348b0300c01d29b7552d622abbc6faf81b3ec55359aa9950c"}}
+{"run":"2b","source":"journal-record","event":"PostToolUse","tool_use_id":"<tool-use-3>","interrupted":false,"record":{"captureId":"<capture-4>","event":"PostToolUse","tool_use_id":"<tool-use-3>","session_id":"<session-3>","command":"node \"<scratch>/plugin/harness-everything/scripts/doc-check.js\" check --workspace <scratch>/project --config .agents/harness-everything/project-docs.json --changed-path docs/a.md","cwd":"<scratch>/project","interrupted":false,"responseDigest":"80ccfae628fb7127a06592ddb8439b864093a34d1b11007d5b137fbc6f95fcef"}}
+{"run":"2b","source":"journal-record","event":"PreToolUse","tool_use_id":"<tool-use-4>","record":{"captureId":"<capture-5>","event":"PreToolUse","tool_use_id":"<tool-use-4>","session_id":"<session-3>","cwd":"<scratch>/project","responseDigest":"eb045d78d273107348b0300c01d29b7552d622abbc6faf81b3ec55359aa9950c"}}
+{"run":"2b","source":"journal-record","event":"SubagentStart","agent_id":"<agent-1>","record":{"captureId":"<capture-6>","event":"SubagentStart","session_id":"<session-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","cwd":"<scratch>/project","responseDigest":"eb045d78d273107348b0300c01d29b7552d622abbc6faf81b3ec55359aa9950c"}}
+{"run":"2b","source":"journal-record","event":"PreToolUse","tool_use_id":"<tool-use-5>","agent_id":"<agent-1>","record":{"captureId":"<capture-7>","event":"PreToolUse","tool_use_id":"<tool-use-5>","session_id":"<session-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","command":"cat docs/a.md && git diff docs/a.md && shasum -a 256 docs/a.md","cwd":"<scratch>/project","responseDigest":"eb045d78d273107348b0300c01d29b7552d622abbc6faf81b3ec55359aa9950c"}}
+{"run":"2b","source":"journal-record","event":"PreToolUse","tool_use_id":"<tool-use-6>","agent_id":"<agent-1>","record":{"captureId":"<capture-8>","event":"PreToolUse","tool_use_id":"<tool-use-6>","session_id":"<session-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","command":"git diff docs/a.md","cwd":"<scratch>/project","responseDigest":"eb045d78d273107348b0300c01d29b7552d622abbc6faf81b3ec55359aa9950c"}}
+{"run":"2b","source":"journal-record","event":"PostToolUse","tool_use_id":"<tool-use-6>","agent_id":"<agent-1>","interrupted":false,"record":{"captureId":"<capture-9>","event":"PostToolUse","tool_use_id":"<tool-use-6>","session_id":"<session-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","command":"git diff docs/a.md","cwd":"<scratch>/project","interrupted":false,"responseDigest":"f8770735e00cf9d10b07d43d91379c17ab2ca5444610dd3d5944b52912d13369"}}
+{"run":"2b","source":"journal-record","event":"PreToolUse","tool_use_id":"<tool-use-7>","agent_id":"<agent-1>","record":{"captureId":"<capture-10>","event":"PreToolUse","tool_use_id":"<tool-use-7>","session_id":"<session-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","command":"ls docs; grep -rni retr . --include=*.md","cwd":"<scratch>/project","responseDigest":"eb045d78d273107348b0300c01d29b7552d622abbc6faf81b3ec55359aa9950c"}}
+{"run":"2b","source":"journal-record","event":"PostToolUse","tool_use_id":"<tool-use-7>","agent_id":"<agent-1>","interrupted":false,"record":{"captureId":"<capture-11>","event":"PostToolUse","tool_use_id":"<tool-use-7>","session_id":"<session-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","command":"ls docs; grep -rni retr . --include=*.md","cwd":"<scratch>/project","interrupted":false,"responseDigest":"4a1d1e23f6b3c88bbc86f5960e2492acc61d65201a9cea4863610c068beb907c"}}
+{"run":"2b","source":"journal-record","event":"SubagentStop","agent_id":"<agent-1>","record":{"captureId":"<capture-12>","event":"SubagentStop","session_id":"<session-3>","agent_id":"<agent-1>","agent_type":"doc-reviewer","cwd":"<scratch>/project","reviewVerdict":"approve","reviewSummary":"Summary: The only change to `docs/a.md` is \"retries once\" becoming \"retries twice\". The front matter is intact, and the link to `b.md` resolves because that file exists. Nothing else in the repo mentions retries, so I found no contradiction. I could not check the \"twice\" claim against the code, since this repo has no code or other source for it. I also couldn't compute a SHA-256, because the shell blocked `shasum`.\n\n\nReviewed artifact digest: `<scratch>/project/docs/a.md`, the working-tree version, uncommitted on top of baseline 8648a71. The identifying content is the diff hunk `@@ -3,4 +3,4 @@`, with the blob change `0936062..3bea475`. The body line is \"The checkout retries twice. See [b](b.md).\"","responseDigest":"eb045d78d273107348b0300c01d29b7552d622abbc6faf81b3ec55359aa9950c"}}
+{"run":"2b","source":"journal-record","event":"PostToolUse","tool_use_id":"<tool-use-4>","agent_id":"<agent-1>","record":{"captureId":"<capture-13>","event":"PostToolUse","tool_use_id":"<tool-use-4>","session_id":"<session-3>","agent_id":"<agent-1>","cwd":"<scratch>/project","responseDigest":"51be05fc9c852f14829a9e01ccd0b2d9d743e0d16c237de69db752d100fad0dc"}}

package/plugins/harness-everything/hooks/scripts/lib/doc-reconciliation-pilot.js

@@ -111,10 +111,157 @@ function collect(context) {
   return deriveDocObligations(facts).filter(item => item.strength === 'MUST' && item.applicability !== 'N/A');
 }
 
+// S2b credit chain (F4): produce the snapshot, accept the origin-provider events, and check them against the expected
+// MUSTs. Credit only when the core marks the evidence eligible. Production has no qualification, so it stays withheld.
+function creditChain(context, set, dependencies = {}) {
+  if (require('./doc-reconciliation-provider').readCaptureView(context.sessionDir).tampered) {
+    return { eligible: false, diagnostics: [{ code: 'journal-tampered', message: 'the capture journal no longer matches its immutable event records' }] };
+  }
+  const { produceDocSnapshot } = require('./doc-reconciliation-producer');
+  const { acceptDocEvents } = require('./doc-reconciliation-events');
+  const { checkAcceptedDocEvidence } = require('./doc-reconciliation-core');
+  const baseline = context.workflow.docReconciliationBaseline;
+  const requirements = Array.isArray(set?.requirements) ? set.requirements : [];
+  const taskId = `task-${requirements.map(item => item.id).join('+') || 'none'}`;
+  const sessionId = context.sessionId;
+  const { createClaudeOriginProvider, journalExecutors } = require('./doc-reconciliation-provider');
+  const captures = readCaptures(context);
+  const originProvider = dependencies.originProvider || createClaudeOriginProvider({
+    hostId: 'claude-code',
+    sessionId,
+    workspaceRoot: context.root,
+    workflowId: context.workflow.workflowId,
+    workflowRevision: context.workflow.revision,
+    taskId,
+    principals: { author: sessionId, executors: journalExecutors(captures, sessionId) },
+    baseline,
+    captures,
+  });
+  const produced = produceDocSnapshot({
+    workspaceRoot: context.root,
+    baseline,
+    workflow: { workflowId: context.workflow.workflowId, sessionId, workflowRevision: context.workflow.revision },
+    task: { taskId, requirements },
+    scope: { prdRoot: 'docs/prd/' },
+    activeHost: 'claude-code',
+    prdRoot: 'docs/prd/',
+  }, { originProvider });
+  if (produced.state !== 'ready' || !produced.snapshot) return { eligible: false, diagnostics: produced.diagnostics, unsatisfied: [] };
+  const eventRefs = captureReferences(context);
+  const accepted = acceptDocEvents({ snapshot: produced.snapshot, eventRefs }, { originProvider });
+  const checked = checkAcceptedDocEvidence({ snapshot: produced.snapshot, accepted, mode: 'verification' });
+  // Credit covers only the expected MUSTs that were both accepted and satisfied (passing, observed). N/A never counts.
+  const passing = new Set((checked.results || []).filter(r => r.observation === 'observed' && r.outcome === 'pass').map(r => r.obligationId));
+  const expected = new Set(checked.checkedMustIds || []);
+  const satisfied = produced.snapshot.obligations.filter(o => o.strength === 'MUST' && o.applicability !== 'N/A' && expected.has(o.id) && passing.has(o.id));
+  return {
+    eligible: checked.eligible === true,
+    capabilities: checked.eligible === true ? [...new Set(satisfied.map(o => o.capability))] : [],
+    satisfiedObligationIds: satisfied.map(o => o.id),
+    unsatisfied: checked.unsatisfied || [],
+    acceptedRefs: Object.keys(accepted.acceptedIndex || {}),
+    diagnostics: [...(accepted.diagnostics || []), ...(checked.diagnostics || [])],
+    rejected: accepted.rejected || [],
+  };
+}
+
+// Report diagnostics are objects with the obligation they concern (F12); a global fault has obligationId null.
+function diagnosticOf(item) {
+  if (item && typeof item === 'object') return { ...item, code: item.code || 'unknown', obligationId: item.obligationId ?? null };
+  return { code: String(item), obligationId: null };
+}
+
+// Review-mode refusal (F4 I2a): with the pilot ON in a supported (non-Fable) workflow, a review step PASS needs an
+// independent quality-review record. The provider's own independence rules decide it: a host agent_id that differs from
+// the author session, an explicit approve verdict, a non-empty summary and the bound final-artifact digest.
+function reviewRequired(set) {
+  return enabled() && set?.stepBindingsEnabled === true && !String(set?.strategy || '').startsWith('fable-');
+}
+
+// The review step is independent of credit qualification: the step records host-observed independence, while document
+// credit itself still needs the validated qualification (assess).
+function independentReviewAccepted(context) {
+  const { reviewRecordIndependent, journalExecutors } = require('./doc-reconciliation-provider');
+  const view = require('./doc-reconciliation-provider').readCaptureView(context.sessionDir);
+  if (view.tampered) return false;
+  const captures = view.records;
+  const principals = { author: context.sessionId, executors: journalExecutors(captures, context.sessionId) };
+  const pin = context.workflow.docReconciliationBaseline;
+  return captures.some(item => recordOf(item) && item.session_id === context.sessionId
+    && recordOf(item.observedIdentity) && item.observedIdentity.workflowId === context.workflow.workflowId
+    && item.observedIdentity.workflowRevision === context.workflow.revision
+    && (!pin || (recordOf(item.observedIdentity.baselinePin) && item.observedIdentity.baselinePin.commit === pin.commit))
+    && reviewRecordIndependent(item, captures, principals));
+}
+
+function recordOf(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+
+// The session capture records are the only host-event source. A missing journal means no events; a journal that no longer
+// equals its immutable event files is tampered and yields no events, so the chain withholds.
+function readCaptures(context) {
+  return require('./doc-reconciliation-provider').readCaptureView(context.sessionDir).records;
+}
+
+// Only explicit PostToolUse doc-check candidates are offered; ordinary Edit or Agent results are not (R3-01).
+const docCheckCandidate = item => item.event === 'PostToolUse'
+  && require('./doc-reconciliation-provider').resolveDocCheckInvocation(item.command, item.cwd).kind !== 'not-candidate';
+
+function captureReferences(context) {
+  const captures = readCaptures(context);
+  const candidates = captures
+    .filter(item => item && typeof item.ref === 'string' && (item.event === 'SubagentStop' || docCheckCandidate(item)))
+    .filter(item => item.event !== 'SubagentStop');
+  const reviews = captures.filter(item => item && typeof item.ref === 'string' && item.event === 'SubagentStop');
+  const references = [];
+  for (const [index, capability] of ['doc-lint', 'link-check'].entries()) {
+    const ordered = index ? candidates.slice(1).concat(candidates.slice(0, 1)) : candidates;
+    references.push(...ordered.map(item => `${item.ref}#${capability}`));
+  }
+  // The adapter accepts one event per capability; rotating candidate order lets separate valid runs fill each capability.
+  return [...references, ...reviews.map(item => `${item.ref}#quality-review`)];
+}
+
+// R3-02: verification recorded before an installed-runtime change is withdrawn once the live doc-check leaves the pin.
+// Capture time sees the pristine runtime, so only assessment can catch a later change. Scoped to sessions that ran a doc-check.
+function withdrawChangedRuntimeVerification(context) {
+  try {
+    const provider = require('./doc-reconciliation-provider');
+    const installed = provider.installedDocCheck();
+    if (!installed || provider.fileDigest(installed) === provider.SHIPPED_DOC_CHECK_DIGEST) return;
+    if (!readCaptures(context).some(item => {
+      if (!item || item.event !== 'PostToolUse') return false;
+      const invocation = provider.resolveDocCheckInvocation(item.command, item.cwd);
+      return invocation.kind === 'accepted' || invocation.reason === 'implementation-pin-mismatch';
+    })) return;
+    const file = path.join(context.sessionDir, 'handoff-state.json');
+    const handoff = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const genericAt = handoff.lastGenericVerifyAt;
+    const hasGeneric = typeof genericAt === 'number' && Number.isFinite(genericAt);
+    const hasDoc = typeof handoff.lastDocVerifyAt === 'number' && Number.isFinite(handoff.lastDocVerifyAt);
+    if (!hasGeneric && !hasDoc && handoff.lastVerifyAt === undefined) return;
+    delete handoff.lastDocVerifyAt;
+    delete handoff.lastDocVerifyExitCode;
+    if (hasGeneric) {
+      handoff.lastVerifyAt = genericAt;
+      if (Object.prototype.hasOwnProperty.call(handoff, 'lastGenericVerifyExitCode')) {
+        handoff.lastVerifyExitCode = handoff.lastGenericVerifyExitCode;
+      } else {
+        delete handoff.lastVerifyExitCode;
+      }
+    } else {
+      // Older aggregate-only state has unknown ownership; do not preserve it as unaffected evidence.
+      delete handoff.lastVerifyAt;
+      delete handoff.lastVerifyExitCode;
+    }
+    atomicWriteJson(file, handoff);
+  } catch { /* fail-open: no handoff state yet, or nothing to withdraw */ }
+}
+
 // Assessment is deliberately negative-credit only in S1. Unsupported topologies never enter
 // generic step reconciliation, and failures (including report persistence) never escape to Stop.
-function assess(context, set) {
+function assess(context, set, dependencies = {}) {
   if (!enabled()) return { withhold: false };
+  withdrawChangedRuntimeVerification(context);
   const report = {
     schemaVersion: 1, reportOrigin: 'runtime', pilotStatus: 'unavailable', pilotCredit: false,
     identity: null, expectedMustIds: [], results: [], unsatisfied: [], diagnostics: [],
@@ -133,6 +280,27 @@ function assess(context, set) {
         reasonCode: item.applicability === 'unknown' ? 'unknown-applicability' : 'producer-unavailable',
       }));
       if (!withhold) report.diagnostics.push('trusted-non-document-scope');
+      if (withhold) {
+        let chain;
+        try { chain = creditChain(context, set, dependencies); }
+        catch (error) { chain = { eligible: false, diagnostics: [{ code: 'collector-unavailable', message: String(error.message) }] }; }
+        // The unsatisfied list is rewritten from the chain: a MUST that the chain did not satisfy stays listed (F3).
+        const satisfied = new Set(chain.satisfiedObligationIds || []);
+        report.unsatisfied = [
+          ...musts.filter(item => !satisfied.has(item.id)).map(item => ({
+            obligationId: item.id, state: item.applicability === 'unknown' ? 'unknown' : 'pending',
+            reasonCode: item.applicability === 'unknown' ? 'unknown-applicability' : 'producer-unavailable',
+          })),
+          ...(chain.unsatisfied || []),
+        ];
+        report.creditedCapabilities = chain.eligible === true ? chain.capabilities : [];
+        report.acceptedRefs = chain.acceptedRefs || [];
+        report.diagnostics.push(...(chain.diagnostics || []));
+        // Credit needs an empty unsatisfied list across both sources and at least one satisfied capability.
+        withhold = !(chain.eligible === true && report.unsatisfied.length === 0 && report.creditedCapabilities.length > 0);
+        report.pilotCredit = !withhold;
+        report.pilotStatus = report.pilotCredit ? 'credited' : 'unresolved';
+      }
     } catch (error) {
       withhold = true;
       const reason = ['baseline-unavailable', 'config-unavailable', 'scope-unavailable', 'config-scope-changed'].includes(error.message)
@@ -141,6 +309,7 @@ function assess(context, set) {
       report.unsatisfied.push({ obligationId: 'doc-change:scope', state: 'unavailable', reasonCode: reason });
     }
   }
+  report.diagnostics = report.diagnostics.map(diagnosticOf);
   try { atomicWriteJson(path.join(context.sessionDir, 'doc-reconciliation-pilot.json'), report); }
   catch {
     if (supported) withhold = true;
@@ -149,4 +318,4 @@ function assess(context, set) {
   return { withhold, report };
 }
 
-module.exports = { enabled, captureBaseline, assess };
+module.exports = { enabled, captureBaseline, assess, reviewRequired, independentReviewAccepted };