harness-everything 0.36.4 → 0.38.0

package/hooks/scripts/lib/doc-reconciliation-pilot.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { atomicWriteJson } = require('./fable-contracts');
+
+const enabled = () => process.env.HARNESS_DOC_RECONCILIATION_PILOT === '1';
+
+function git(root, args) {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) if (key.startsWith('GIT_')) delete env[key];
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      env, encoding: 'utf8', timeout: 10000, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (cause) {
+    throw new Error('baseline-unavailable', { cause });
+  }
+}
+
+function runtimeModule(name) {
+  for (const relative of ['../../../harness-everything/scripts', '../../../skills/harness-everything/scripts']) {
+    const file = path.resolve(__dirname, relative, name + '.js');
+    if (fs.existsSync(file)) return require(file);
+  }
+  throw new Error('document runtime unavailable');
+}
+
+// Only capture at plan/start. A later credit assessment must never advance the baseline to HEAD.
+function captureBaseline(context) {
+  if (!enabled() || context.workflow.docReconciliationBaseline) return;
+  try {
+    const root = git(context.root, ['rev-parse', '--show-toplevel']).trim();
+    const commit = git(root, ['rev-parse', '--verify', 'HEAD^{commit}']).trim();
+    context.workflow.docReconciliationBaseline = { root, commit };
+  } catch {
+    // Absence is intentionally retained; credit assessment will fail closed.
+  }
+}
+
+// PR #351 review P1 (config authority): derivation runs on the current config, so a candidate
+// config edit could de-scope a baseline-governed path. Every resolver-selectable config source —
+// `.agents/harness-everything/project-docs.json` and each host `<home>/harness-everything/manifest.json`
+// for the resolver's PLATFORM_HOMES — is byte-compared at the recorded baseline commit and in the
+// working tree. An edit, an addition or a removal all fail closed before derivation; absence of a
+// source on either side is allowed and only a difference is fatal.
+const PROJECT_DOCS_CONFIG_RELPATH = '.agents/harness-everything/project-docs.json';
+
+function configSourcePaths(resolver) {
+  return [
+    PROJECT_DOCS_CONFIG_RELPATH,
+    ...(resolver.PLATFORM_HOMES || []).map(home => `${home}/harness-everything/manifest.json`),
+  ];
+}
+
+function bytesAtBaseline(root, commit, relative) {
+  const listed = git(root, ['ls-tree', '-r', '--name-only', '-z', commit, '--', relative]);
+  if (!listed.split('\0').includes(relative)) return null; // absent at the baseline is allowed
+  return git(root, ['show', `${commit}:${relative}`]); // other Git failures stay baseline-unavailable
+}
+
+function bytesInTree(root, relative) {
+  try {
+    return fs.readFileSync(path.join(root, relative), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null; // absent in the working tree is allowed
+    throw error;
+  }
+}
+
+function assertConfigScopeUnchanged(root, baseline, resolver) {
+  for (const relative of configSourcePaths(resolver)) {
+    if (bytesAtBaseline(root, baseline.commit, relative) !== bytesInTree(root, relative)) {
+      throw new Error('config-scope-changed');
+    }
+  }
+}
+
+function collect(context) {
+  const baseline = context.workflow.docReconciliationBaseline;
+  if (!baseline) throw new Error('baseline-unavailable');
+  const root = git(context.root, ['rev-parse', '--show-toplevel']).trim();
+  if (root !== baseline.root || !/^[0-9a-f]{40,64}$/.test(baseline.commit)) throw new Error('baseline-unavailable');
+  const resolver = runtimeModule('project-docs-resolver');
+  const resolved = resolver.resolveDocsConfig(root);
+  if (!['project', 'host'].includes(resolved.status)) throw new Error('config-unavailable');
+  assertConfigScopeUnchanged(root, baseline, resolver);
+  const { readGitBaseInventory, scanWorkspaceFiles } = runtimeModule('doc-lifecycle');
+  // Broaden artifact discovery only, never the config passed to obligation derivation. Code/REQ-test
+  // facts require baseline bytes outside governed document globs as well.
+  const base = readGitBaseInventory(root, baseline.commit, { governed: [{ path: '**/*', role: 'reference' }] });
+  const basePaths = git(root, ['ls-tree', '-r', '--name-only', '-z', baseline.commit]).split('\0').filter(Boolean);
+  if (!base.available) throw new Error('baseline-unavailable');
+  if (base.files.length !== basePaths.length) throw new Error('scope-unavailable');
+  const paths = [...new Set(git(root, ['ls-files', '-c', '-o', '--exclude-standard', '-z']).split('\0').filter(Boolean))];
+  const existing = paths.filter(relative => {
+    try {
+      if (!fs.lstatSync(path.join(root, relative)).isFile()) throw new Error('scope-unavailable');
+      return true;
+    } catch (error) {
+      if (error.code === 'ENOENT') return false; // tracked deletion
+      throw error;
+    }
+  });
+  const candidate = scanWorkspaceFiles(root, { paths: existing });
+  if (candidate.length !== existing.length) throw new Error('scope-unavailable');
+  const snapshots = files => ({ files: Object.fromEntries(files.map(item => [item.path, item.bytes.toString('utf8')])) });
+  const { deriveDocFacts, deriveDocObligations } = runtimeModule('doc-obligations');
+  const { facts } = deriveDocFacts({ base: snapshots(base.files), candidate: snapshots(candidate), config: resolved.config, inventory: { complete: true } });
+  return deriveDocObligations(facts).filter(item => item.strength === 'MUST' && item.applicability !== 'N/A');
+}
+
+// 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) {
+  if (!enabled()) return { withhold: false };
+  const report = {
+    schemaVersion: 1, reportOrigin: 'runtime', pilotStatus: 'unavailable', pilotCredit: false,
+    identity: null, expectedMustIds: [], results: [], unsatisfied: [], diagnostics: [],
+  };
+  const supported = set?.stepBindingsEnabled === true && !String(context.workflow.strategy || '').startsWith('fable-');
+  let withhold = false;
+  if (!supported) report.diagnostics.push('unsupported-workflow');
+  else {
+    try {
+      const musts = collect(context);
+      withhold = musts.length > 0;
+      report.pilotStatus = 'unresolved';
+      report.expectedMustIds = musts.map(item => item.id);
+      report.unsatisfied = musts.map(item => ({
+        obligationId: item.id, state: item.applicability === 'unknown' ? 'unknown' : 'pending',
+        reasonCode: item.applicability === 'unknown' ? 'unknown-applicability' : 'producer-unavailable',
+      }));
+      if (!withhold) report.diagnostics.push('trusted-non-document-scope');
+    } catch (error) {
+      withhold = true;
+      const reason = ['baseline-unavailable', 'config-unavailable', 'scope-unavailable', 'config-scope-changed'].includes(error.message)
+        ? error.message : 'collector-unavailable';
+      report.diagnostics.push(reason);
+      report.unsatisfied.push({ obligationId: 'doc-change:scope', state: 'unavailable', reasonCode: reason });
+    }
+  }
+  try { atomicWriteJson(path.join(context.sessionDir, 'doc-reconciliation-pilot.json'), report); }
+  catch {
+    if (supported) withhold = true;
+    console.error('[Workflow Reminder] Document pilot report unavailable; no document verification credit.');
+  }
+  return { withhold, report };
+}
+
+module.exports = { enabled, captureBaseline, assess };

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

@@ -510,6 +510,33 @@ function planningUnresolved(context, plan = context.workflow?.pendingPlan || con
   return [...new Set(unresolved)];
 }
 
+function withholdPilotVerification(context, set) {
+  // PR #351 review P2 (persistence failure): the credit decision is applied in memory first —
+  // aggregate verify becomes pending and a satisfied workflow becomes running — and only then is
+  // that state persisted best-effort. A failed obligations-file write records the
+  // withhold-persist-failed diagnostic and a reminder; it never escapes, never leaves the decision
+  // unapplied, and never changes the callers' refusal contract (exit 2 / step:<verify>:pending).
+  // PR #351 re-review P2a (scope of the recovery): this run made an actual ON, supported,
+  // withheld pilot decision. The marker is transient and per-run — it lives on the in-memory
+  // context object itself (saveWorkflow persists only context.workflow) and is never written
+  // to disk; Stop's pending-path persistence recovery is scoped by it.
+  context.docReconciliationWithheldRun = true;
+  const verify = set.obligations.find(item => item.id === 'verify');
+  if (verify) verify.status = 'pending';
+  if (context.workflow.state === 'satisfied') context.workflow.state = 'running';
+  try {
+    atomicWriteJson(obligationPath(context.sessionDir), set);
+  } catch {
+    if (!Array.isArray(context.workflow.docReconciliationDiagnostics)) {
+      context.workflow.docReconciliationDiagnostics = [];
+    }
+    if (!context.workflow.docReconciliationDiagnostics.includes('withhold-persist-failed')) {
+      context.workflow.docReconciliationDiagnostics.push('withhold-persist-failed');
+    }
+    console.error('[Workflow Reminder] Document verification withheld in memory; persisting the obligations state failed (withhold-persist-failed). No document verification credit.');
+  }
+}
+
 function updateObligation(context, obligationId, disposition, options = {}) {
   if (!SAFE_ID.test(obligationId || '')) throw new Error('--obligation-id must be a stable obligation id');
   if (!['pass', 'escaped', 'blocked'].includes(disposition)) throw new Error('--disposition must be pass, escaped, or blocked');
@@ -529,6 +556,12 @@ function updateObligation(context, obligationId, disposition, options = {}) {
     if (!scope) throw new Error('--scope is required when escaping an obligation');
   }
   if (disposition === 'blocked' && !reasonCode) throw new Error('--reason-code is required when blocking an obligation');
+  if (disposition === 'pass' && ['execute', 'verify'].includes(obligationId)
+      && require('./doc-reconciliation-pilot').assess(context, loaded.set).withhold) {
+    obligation.status = 'pending';
+    withholdPilotVerification(context, loaded.set);
+    throw new Error('document verification pending: S1 grants no document credit');
+  }
   obligation.status = disposition;
   obligation.evidence = evidence;
   obligation.reasonCode = reasonCode;
@@ -635,6 +668,11 @@ function updateStep(context, stepId, disposition, options = {}) {
       throw new Error('resolve active-step bindings before passing the step: ' + ids.join(', '));
     }
   }
+  if (disposition === 'pass' && step.stepType === 'verification'
+      && require('./doc-reconciliation-pilot').assess(context, loaded.set).withhold) {
+    withholdPilotVerification(context, loaded.set);
+    throw new Error('document verification pending: S1 grants no document credit');
+  }
   step.status = disposition;
   step.evidence = evidence;
   step.reasonCode = reasonCode;
@@ -651,6 +689,12 @@ function unresolvedObligations(context) {
   const unresolved = planningUnresolved(context, plan);
   const loaded = loadObligationSet(context, plan);
   if (!loaded.set) return unresolved;
+  if (!unresolved.length && require('./doc-reconciliation-pilot').assess(context, loaded.set).withhold) {
+    withholdPilotVerification(context, loaded.set);
+    for (const step of loaded.set.requirements.filter(item => item.stepType === 'verification')) {
+      unresolved.push('step:' + step.id + ':pending');
+    }
+  }
   if (!['running', 'satisfied', 'blocked', 'failed'].includes(context.workflow.state)) {
     unresolved.push('execution:not-started');
   }

package/hooks/scripts/workflow-disposition.js

@@ -173,6 +173,7 @@ function main() {
     if (!['pending', 'active'].includes(workflow.state)) throw new Error('requirements/workflow composition belongs before execution starts');
     const selectedPlan = recomposePlan(workflow, args.strategy);
     const result = recordPlanning(context, args.requirementsJson, selectedPlan, args.strategy, args.evidence);
+    require('./lib/doc-reconciliation-pilot').captureBaseline(context);
     saveWorkflow(context);
     process.stdout.write(JSON.stringify({
       state: workflow.state,
@@ -192,6 +193,7 @@ function main() {
     const unresolvedPlanning = planningUnresolved(context, plan);
     if (unresolvedPlanning.length) throw new Error('resolve requirement decomposition/workflow selection first: ' + unresolvedPlanning.join(', '));
 
+    require('./lib/doc-reconciliation-pilot').captureBaseline(context);
     if (!String(plan.strategy || '').startsWith('fable-')) {
       activatePlan(workflow, plan);
       workflow.revision++;

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

@@ -36,6 +36,7 @@ function decide(payload) {
 
     required(() => planningUnresolved(context));
     if (String(workflow.strategy || '').startsWith('fable-')) {
+      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 {
@@ -52,7 +53,29 @@ function decide(payload) {
       // A failed required validation leaves the workflow file as recorded; it is never marked satisfied.
       if (!requiredFault) {
         workflow.unresolved = pending;
-        saveWorkflow(context);
+        // PR #351 follow-up (unwritable session store): persisting the pending downgrade is
+        // best-effort. A failing saveWorkflow() must not swallow the decision or leak exception
+        // text: record the withhold-persist-failed diagnostic on the shared context diagnostics
+        // (also when the earlier obligations write already failed) and still emit the reminder
+        // below. Stop stays non-blocking: exit 0, no retry loop, no lock.
+        // Scope of the recovery (PR #351 re-review): the local recovery and the
+        // withhold-persist-failed diagnostic apply only when this Stop run made an actual ON,
+        // supported, withheld pilot decision (`withholdPilotVerification` sets the transient
+        // per-run marker on the context). On switch-OFF, Fable and persisted-untyped paths the
+        // marker is never set, so the error is rethrown and reaches Stop's outer handler exactly
+        // as the pre-S1 legacy reference: same stderr, same exit 0, no pilot diagnostic.
+        try {
+          saveWorkflow(context);
+        } catch (error) {
+          if (context.docReconciliationWithheldRun !== true) throw error;
+          if (!Array.isArray(context.workflow.docReconciliationDiagnostics)) {
+            context.workflow.docReconciliationDiagnostics = [];
+          }
+          if (!context.workflow.docReconciliationDiagnostics.includes('withhold-persist-failed')) {
+            context.workflow.docReconciliationDiagnostics.push('withhold-persist-failed');
+          }
+          warn('Pending-workflow persistence failed (withhold-persist-failed); the unresolved evidence below is still binding.');
+        }
       }
       warn('Unresolved workflow evidence: ' + pending.join(', ') + '. Resolve/verify before claiming completion.');
       return;

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.36.4",
+  "version": "0.38.0",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.36.4",
+  "version": "0.38.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.36.4",
+  "version": "0.38.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-pilot.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { atomicWriteJson } = require('./fable-contracts');
+
+const enabled = () => process.env.HARNESS_DOC_RECONCILIATION_PILOT === '1';
+
+function git(root, args) {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) if (key.startsWith('GIT_')) delete env[key];
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      env, encoding: 'utf8', timeout: 10000, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (cause) {
+    throw new Error('baseline-unavailable', { cause });
+  }
+}
+
+function runtimeModule(name) {
+  for (const relative of ['../../../harness-everything/scripts', '../../../skills/harness-everything/scripts']) {
+    const file = path.resolve(__dirname, relative, name + '.js');
+    if (fs.existsSync(file)) return require(file);
+  }
+  throw new Error('document runtime unavailable');
+}
+
+// Only capture at plan/start. A later credit assessment must never advance the baseline to HEAD.
+function captureBaseline(context) {
+  if (!enabled() || context.workflow.docReconciliationBaseline) return;
+  try {
+    const root = git(context.root, ['rev-parse', '--show-toplevel']).trim();
+    const commit = git(root, ['rev-parse', '--verify', 'HEAD^{commit}']).trim();
+    context.workflow.docReconciliationBaseline = { root, commit };
+  } catch {
+    // Absence is intentionally retained; credit assessment will fail closed.
+  }
+}
+
+// PR #351 review P1 (config authority): derivation runs on the current config, so a candidate
+// config edit could de-scope a baseline-governed path. Every resolver-selectable config source —
+// `.agents/harness-everything/project-docs.json` and each host `<home>/harness-everything/manifest.json`
+// for the resolver's PLATFORM_HOMES — is byte-compared at the recorded baseline commit and in the
+// working tree. An edit, an addition or a removal all fail closed before derivation; absence of a
+// source on either side is allowed and only a difference is fatal.
+const PROJECT_DOCS_CONFIG_RELPATH = '.agents/harness-everything/project-docs.json';
+
+function configSourcePaths(resolver) {
+  return [
+    PROJECT_DOCS_CONFIG_RELPATH,
+    ...(resolver.PLATFORM_HOMES || []).map(home => `${home}/harness-everything/manifest.json`),
+  ];
+}
+
+function bytesAtBaseline(root, commit, relative) {
+  const listed = git(root, ['ls-tree', '-r', '--name-only', '-z', commit, '--', relative]);
+  if (!listed.split('\0').includes(relative)) return null; // absent at the baseline is allowed
+  return git(root, ['show', `${commit}:${relative}`]); // other Git failures stay baseline-unavailable
+}
+
+function bytesInTree(root, relative) {
+  try {
+    return fs.readFileSync(path.join(root, relative), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null; // absent in the working tree is allowed
+    throw error;
+  }
+}
+
+function assertConfigScopeUnchanged(root, baseline, resolver) {
+  for (const relative of configSourcePaths(resolver)) {
+    if (bytesAtBaseline(root, baseline.commit, relative) !== bytesInTree(root, relative)) {
+      throw new Error('config-scope-changed');
+    }
+  }
+}
+
+function collect(context) {
+  const baseline = context.workflow.docReconciliationBaseline;
+  if (!baseline) throw new Error('baseline-unavailable');
+  const root = git(context.root, ['rev-parse', '--show-toplevel']).trim();
+  if (root !== baseline.root || !/^[0-9a-f]{40,64}$/.test(baseline.commit)) throw new Error('baseline-unavailable');
+  const resolver = runtimeModule('project-docs-resolver');
+  const resolved = resolver.resolveDocsConfig(root);
+  if (!['project', 'host'].includes(resolved.status)) throw new Error('config-unavailable');
+  assertConfigScopeUnchanged(root, baseline, resolver);
+  const { readGitBaseInventory, scanWorkspaceFiles } = runtimeModule('doc-lifecycle');
+  // Broaden artifact discovery only, never the config passed to obligation derivation. Code/REQ-test
+  // facts require baseline bytes outside governed document globs as well.
+  const base = readGitBaseInventory(root, baseline.commit, { governed: [{ path: '**/*', role: 'reference' }] });
+  const basePaths = git(root, ['ls-tree', '-r', '--name-only', '-z', baseline.commit]).split('\0').filter(Boolean);
+  if (!base.available) throw new Error('baseline-unavailable');
+  if (base.files.length !== basePaths.length) throw new Error('scope-unavailable');
+  const paths = [...new Set(git(root, ['ls-files', '-c', '-o', '--exclude-standard', '-z']).split('\0').filter(Boolean))];
+  const existing = paths.filter(relative => {
+    try {
+      if (!fs.lstatSync(path.join(root, relative)).isFile()) throw new Error('scope-unavailable');
+      return true;
+    } catch (error) {
+      if (error.code === 'ENOENT') return false; // tracked deletion
+      throw error;
+    }
+  });
+  const candidate = scanWorkspaceFiles(root, { paths: existing });
+  if (candidate.length !== existing.length) throw new Error('scope-unavailable');
+  const snapshots = files => ({ files: Object.fromEntries(files.map(item => [item.path, item.bytes.toString('utf8')])) });
+  const { deriveDocFacts, deriveDocObligations } = runtimeModule('doc-obligations');
+  const { facts } = deriveDocFacts({ base: snapshots(base.files), candidate: snapshots(candidate), config: resolved.config, inventory: { complete: true } });
+  return deriveDocObligations(facts).filter(item => item.strength === 'MUST' && item.applicability !== 'N/A');
+}
+
+// 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) {
+  if (!enabled()) return { withhold: false };
+  const report = {
+    schemaVersion: 1, reportOrigin: 'runtime', pilotStatus: 'unavailable', pilotCredit: false,
+    identity: null, expectedMustIds: [], results: [], unsatisfied: [], diagnostics: [],
+  };
+  const supported = set?.stepBindingsEnabled === true && !String(context.workflow.strategy || '').startsWith('fable-');
+  let withhold = false;
+  if (!supported) report.diagnostics.push('unsupported-workflow');
+  else {
+    try {
+      const musts = collect(context);
+      withhold = musts.length > 0;
+      report.pilotStatus = 'unresolved';
+      report.expectedMustIds = musts.map(item => item.id);
+      report.unsatisfied = musts.map(item => ({
+        obligationId: item.id, state: item.applicability === 'unknown' ? 'unknown' : 'pending',
+        reasonCode: item.applicability === 'unknown' ? 'unknown-applicability' : 'producer-unavailable',
+      }));
+      if (!withhold) report.diagnostics.push('trusted-non-document-scope');
+    } catch (error) {
+      withhold = true;
+      const reason = ['baseline-unavailable', 'config-unavailable', 'scope-unavailable', 'config-scope-changed'].includes(error.message)
+        ? error.message : 'collector-unavailable';
+      report.diagnostics.push(reason);
+      report.unsatisfied.push({ obligationId: 'doc-change:scope', state: 'unavailable', reasonCode: reason });
+    }
+  }
+  try { atomicWriteJson(path.join(context.sessionDir, 'doc-reconciliation-pilot.json'), report); }
+  catch {
+    if (supported) withhold = true;
+    console.error('[Workflow Reminder] Document pilot report unavailable; no document verification credit.');
+  }
+  return { withhold, report };
+}
+
+module.exports = { enabled, captureBaseline, assess };

package/plugins/harness-everything/hooks/scripts/lib/workflow-obligations.js

@@ -510,6 +510,33 @@ function planningUnresolved(context, plan = context.workflow?.pendingPlan || con
   return [...new Set(unresolved)];
 }
 
+function withholdPilotVerification(context, set) {
+  // PR #351 review P2 (persistence failure): the credit decision is applied in memory first —
+  // aggregate verify becomes pending and a satisfied workflow becomes running — and only then is
+  // that state persisted best-effort. A failed obligations-file write records the
+  // withhold-persist-failed diagnostic and a reminder; it never escapes, never leaves the decision
+  // unapplied, and never changes the callers' refusal contract (exit 2 / step:<verify>:pending).
+  // PR #351 re-review P2a (scope of the recovery): this run made an actual ON, supported,
+  // withheld pilot decision. The marker is transient and per-run — it lives on the in-memory
+  // context object itself (saveWorkflow persists only context.workflow) and is never written
+  // to disk; Stop's pending-path persistence recovery is scoped by it.
+  context.docReconciliationWithheldRun = true;
+  const verify = set.obligations.find(item => item.id === 'verify');
+  if (verify) verify.status = 'pending';
+  if (context.workflow.state === 'satisfied') context.workflow.state = 'running';
+  try {
+    atomicWriteJson(obligationPath(context.sessionDir), set);
+  } catch {
+    if (!Array.isArray(context.workflow.docReconciliationDiagnostics)) {
+      context.workflow.docReconciliationDiagnostics = [];
+    }
+    if (!context.workflow.docReconciliationDiagnostics.includes('withhold-persist-failed')) {
+      context.workflow.docReconciliationDiagnostics.push('withhold-persist-failed');
+    }
+    console.error('[Workflow Reminder] Document verification withheld in memory; persisting the obligations state failed (withhold-persist-failed). No document verification credit.');
+  }
+}
+
 function updateObligation(context, obligationId, disposition, options = {}) {
   if (!SAFE_ID.test(obligationId || '')) throw new Error('--obligation-id must be a stable obligation id');
   if (!['pass', 'escaped', 'blocked'].includes(disposition)) throw new Error('--disposition must be pass, escaped, or blocked');
@@ -529,6 +556,12 @@ function updateObligation(context, obligationId, disposition, options = {}) {
     if (!scope) throw new Error('--scope is required when escaping an obligation');
   }
   if (disposition === 'blocked' && !reasonCode) throw new Error('--reason-code is required when blocking an obligation');
+  if (disposition === 'pass' && ['execute', 'verify'].includes(obligationId)
+      && require('./doc-reconciliation-pilot').assess(context, loaded.set).withhold) {
+    obligation.status = 'pending';
+    withholdPilotVerification(context, loaded.set);
+    throw new Error('document verification pending: S1 grants no document credit');
+  }
   obligation.status = disposition;
   obligation.evidence = evidence;
   obligation.reasonCode = reasonCode;
@@ -635,6 +668,11 @@ function updateStep(context, stepId, disposition, options = {}) {
       throw new Error('resolve active-step bindings before passing the step: ' + ids.join(', '));
     }
   }
+  if (disposition === 'pass' && step.stepType === 'verification'
+      && require('./doc-reconciliation-pilot').assess(context, loaded.set).withhold) {
+    withholdPilotVerification(context, loaded.set);
+    throw new Error('document verification pending: S1 grants no document credit');
+  }
   step.status = disposition;
   step.evidence = evidence;
   step.reasonCode = reasonCode;
@@ -651,6 +689,12 @@ function unresolvedObligations(context) {
   const unresolved = planningUnresolved(context, plan);
   const loaded = loadObligationSet(context, plan);
   if (!loaded.set) return unresolved;
+  if (!unresolved.length && require('./doc-reconciliation-pilot').assess(context, loaded.set).withhold) {
+    withholdPilotVerification(context, loaded.set);
+    for (const step of loaded.set.requirements.filter(item => item.stepType === 'verification')) {
+      unresolved.push('step:' + step.id + ':pending');
+    }
+  }
   if (!['running', 'satisfied', 'blocked', 'failed'].includes(context.workflow.state)) {
     unresolved.push('execution:not-started');
   }

package/plugins/harness-everything/hooks/scripts/workflow-disposition.js

@@ -173,6 +173,7 @@ function main() {
     if (!['pending', 'active'].includes(workflow.state)) throw new Error('requirements/workflow composition belongs before execution starts');
     const selectedPlan = recomposePlan(workflow, args.strategy);
     const result = recordPlanning(context, args.requirementsJson, selectedPlan, args.strategy, args.evidence);
+    require('./lib/doc-reconciliation-pilot').captureBaseline(context);
     saveWorkflow(context);
     process.stdout.write(JSON.stringify({
       state: workflow.state,
@@ -192,6 +193,7 @@ function main() {
     const unresolvedPlanning = planningUnresolved(context, plan);
     if (unresolvedPlanning.length) throw new Error('resolve requirement decomposition/workflow selection first: ' + unresolvedPlanning.join(', '));
 
+    require('./lib/doc-reconciliation-pilot').captureBaseline(context);
     if (!String(plan.strategy || '').startsWith('fable-')) {
       activatePlan(workflow, plan);
       workflow.revision++;

package/plugins/harness-everything/hooks/scripts/workflow-stop-gate.js

@@ -36,6 +36,7 @@ function decide(payload) {
 
     required(() => planningUnresolved(context));
     if (String(workflow.strategy || '').startsWith('fable-')) {
+      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 {
@@ -52,7 +53,29 @@ function decide(payload) {
       // A failed required validation leaves the workflow file as recorded; it is never marked satisfied.
       if (!requiredFault) {
         workflow.unresolved = pending;
-        saveWorkflow(context);
+        // PR #351 follow-up (unwritable session store): persisting the pending downgrade is
+        // best-effort. A failing saveWorkflow() must not swallow the decision or leak exception
+        // text: record the withhold-persist-failed diagnostic on the shared context diagnostics
+        // (also when the earlier obligations write already failed) and still emit the reminder
+        // below. Stop stays non-blocking: exit 0, no retry loop, no lock.
+        // Scope of the recovery (PR #351 re-review): the local recovery and the
+        // withhold-persist-failed diagnostic apply only when this Stop run made an actual ON,
+        // supported, withheld pilot decision (`withholdPilotVerification` sets the transient
+        // per-run marker on the context). On switch-OFF, Fable and persisted-untyped paths the
+        // marker is never set, so the error is rethrown and reaches Stop's outer handler exactly
+        // as the pre-S1 legacy reference: same stderr, same exit 0, no pilot diagnostic.
+        try {
+          saveWorkflow(context);
+        } catch (error) {
+          if (context.docReconciliationWithheldRun !== true) throw error;
+          if (!Array.isArray(context.workflow.docReconciliationDiagnostics)) {
+            context.workflow.docReconciliationDiagnostics = [];
+          }
+          if (!context.workflow.docReconciliationDiagnostics.includes('withhold-persist-failed')) {
+            context.workflow.docReconciliationDiagnostics.push('withhold-persist-failed');
+          }
+          warn('Pending-workflow persistence failed (withhold-persist-failed); the unresolved evidence below is still binding.');
+        }
       }
       warn('Unresolved workflow evidence: ' + pending.join(', ') + '. Resolve/verify before claiming completion.');
       return;

package/plugins/harness-everything/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "harness-everything",
-  "version": "0.36.4",
+  "version": "0.38.0",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/skills/harness-everything/SKILL.md

@@ -4,7 +4,7 @@ description: "Route software/project work through Harness: classify tier/topolog
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.36.4
+  version: 0.38.0
 ---
 
 # Harness Everything

package/plugins/harness-everything/skills/harness-everything/scripts/doc-lifecycle.js

@@ -2396,6 +2396,6 @@ function main(argv = process.argv.slice(2)) {
   return analysis.diagnostics.some(item => item.severity === 'error') ? 1 : 0;
 }
 
-module.exports = { parseFrontmatter, parseRequirementBlocks, collectDocs, analyzeDocs, resolveRef, lintDocs, buildIndex, diffRevisions };
+module.exports = { readGitBaseInventory, scanWorkspaceFiles, parseFrontmatter, parseRequirementBlocks, collectDocs, analyzeDocs, resolveRef, lintDocs, buildIndex, diffRevisions };
 
 if (require.main === module) process.exitCode = main();