harness-everything 0.37.0 → 0.38.0

package/ci/mechanism-325-3b-s1.test.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+'use strict';
+
+// #325 Phase 3b S1 strict suite: switch, trusted scope and fail-closed no-credit gate (RED).
+//
+// Every assertion in reconciliation-s1/cases.json is a strict S1 contract assertion, run against the real CLI, hook and
+// Stop entry points on both legs (source and packaged) and both modes (OFF and ON with the switch set to exactly "1").
+// Each assertion is tagged s1Kind:
+//   retired    one of the 26 S1 retire IDs in docs/doc-workflow-reconciliation.md; expected to FAIL on the current base
+//   control    behaviour that must PASS now and after GREEN (P06, P07u, P02d, OFF legacy, Stop exit 0, switch values)
+//   additional a named S1 contract case beyond the retire table (governed scope, direct aggregate, OFF-seeded, ON->OFF->ON)
+// This suite grants no pilot credit and never consults the prep registry: a FAIL here is a real gap, not a qualified one.
+// Infrastructure faults (spawn error, deadline, output bound, exit outside the declared policy, malformed output) are
+// reported as INFRA and are distinct from assertion FAIL. Exit 1 means at least one assertion FAILED; exit 2 means
+// infrastructure. The suite cannot pass until GREEN lands; that is the RED contract.
+
+const path = require('path');
+const fx = require('./lib/doc-reconciliation-prep-fixtures');
+
+const CORPUS_FILE = path.join(__dirname, 'fixtures', 'doc-obligations', 'reconciliation-s1', 'cases.json');
+const corpus = fx.readCaseCorpus(CORPUS_FILE);
+const LEGS = ['source', 'packaged'];
+const MODES = ['off', 'on'];
+const ALLOWED_OPERATORS = new Set(['equals', 'notEquals', 'includes', 'absent']);
+const S1_KINDS = new Set(['retired', 'control', 'additional']);
+const REQUIRED_CASE_FIELDS = ['id', 'family', 'description', 'topology', 'requirements', 'input', 'actions', 'expectations'];
+
+// The doc's "S1 retire" table: 26 IDs × 2 legs, by case. Any drift between this list and the corpus is a failure.
+const RETIRED_BY_CASE = {
+  P01: ['verify-exit-refused', 'verify-obligation-pending', 'stop-unsatisfied', 'stop-reports-verification'],
+  P04: ['direct-execute-refused', 'direct-verify-refused', 'verify-obligation-pending'],
+  P02a: ['verify-pass-exit', 'stop-state', 'stop-reports'],
+  P02b: ['verify-pass-exit', 'stop-state', 'stop-reports'],
+  P02c: ['verify-pass-exit', 'stop-state', 'stop-reports'],
+  P02g: ['verify-pass-exit', 'stop-state', 'stop-reports'],
+  P02f: ['verify-pass-exit', 'stop-state', 'stop-reports'],
+  P03: ['verify-pass-exit'],
+  'P07-fable-staged': ['pilot-status-unavailable'],
+  'P07-fable-parallel': ['pilot-status-unavailable'],
+  'P07-fable-multi-agent-workspace': ['pilot-status-unavailable']
+};
+const RETIRED_COUNT = Object.values(RETIRED_BY_CASE).reduce((total, ids) => total + ids.length, 0);
+
+let passed = 0;
+let failed = 0;
+let infra = 0;
+const failures = [];
+const infrastructure = [];
+
+const show = value => (value === undefined ? 'undefined' : JSON.stringify(value));
+
+// The reason a FAIL names, in the terms the doc uses: "exit 0 where 2 desired", "state satisfied where running desired".
+function reasonFor(assertion, actual) {
+  const last = assertion.path[assertion.path.length - 1];
+  const label = ({ exitCode: 'exit', state: 'state', unresolved: 'unresolved', pilotStatus: 'pilot status',
+    pilotReportOrigin: 'pilot origin', pilot: 'pilot' })[last]
+    || (assertion.path.includes('obligations') && last === 'status' ? 'obligation status' : null)
+    || (assertion.path.includes('requirements') && last === 'status' ? 'step status' : null)
+    || assertion.path.slice(-2).join('.');
+  const absent = actual && typeof actual === 'object' && actual.kind === 'absent';
+  if (assertion.operator === 'includes') {
+    return absent ? `${label} absent where ${show(assertion.expected)} desired`
+      : `${label} ${show(actual)} lacks ${show(assertion.expected)}`;
+  }
+  if (assertion.operator === 'notEquals') return `${label} ${show(actual)} where a value other than ${show(assertion.expected)} desired`;
+  if (assertion.operator === 'absent') return `${label} present where absent desired`;
+  if (absent) return `${label} absent where ${show(assertion.expected)} desired`;
+  return `${label} ${show(actual)} where ${show(assertion.expected)} desired`;
+}
+
+function record(status, id, detail) {
+  if (status === 'PASS') passed += 1;
+  else if (status === 'FAIL') { failed += 1; failures.push(id); }
+  else { infra += 1; infrastructure.push(id); }
+  console.log(`  ${status} ${id}${detail ? ` — ${detail}` : ''}`);
+}
+
+// Parity between the two legs for one replay, mirroring the prep runner's comparable() view.
+function comparable(root) {
+  const entries = Object.entries(root.actions).map(([id, action]) => [id, {
+    exitCode: action.exitCode,
+    signal: action.signal,
+    stdout: action.json === null ? action.stdout : null,
+    json: action.json,
+    stderr: action.stderr,
+    state: action.state
+  }]);
+  return fx.normalize(Object.fromEntries([...entries, ['$final', root.state]]));
+}
+
+console.log('=== #325 3b S1: strict switch, trusted scope and fail-closed no-credit suite (RED) ===');
+
+// ---- Inventory: the corpus is well formed and marks exactly the doc's retire table -----------------------------
+{
+  const problems = [];
+  const caseIds = corpus.cases.map(item => item.id);
+  if (new Set(caseIds).size !== caseIds.length) problems.push('case ids are not unique');
+  for (const item of corpus.cases) {
+    for (const field of REQUIRED_CASE_FIELDS) {
+      if (item[field] === undefined) problems.push(`${item.id} lacks ${field}`);
+    }
+    const actionIds = item.actions.map(action => action.id);
+    if (new Set(actionIds).size !== actionIds.length) problems.push(`${item.id} action ids are not unique`);
+    for (const action of item.actions) {
+      if (!fx.ALL_OPS.has(action.op)) problems.push(`${item.id}.${action.id} op ${action.op} is not allowed`);
+      for (const mode of MODES) {
+        try { fx.exitPolicy(action, mode); } catch (error) { problems.push(error.message); }
+      }
+    }
+    for (const mode of MODES) {
+      const ids = item.expectations[mode].map(assertion => assertion.id);
+      if (new Set(ids).size !== ids.length) problems.push(`${item.id}.${mode} assertion ids are not unique`);
+      for (const assertion of item.expectations[mode]) {
+        if (!ALLOWED_OPERATORS.has(assertion.operator)) problems.push(`${item.id}.${assertion.id} operator ${assertion.operator}`);
+        if (!Array.isArray(assertion.path) || assertion.path.length === 0) problems.push(`${item.id}.${assertion.id} has no path`);
+        if (!S1_KINDS.has(assertion.s1Kind)) problems.push(`${item.id}.${assertion.id} lacks a valid s1Kind`);
+      }
+    }
+  }
+  const retired = [];
+  for (const item of corpus.cases) {
+    for (const assertion of item.expectations.on) {
+      if (assertion.s1Kind === 'retired') retired.push(`${item.id}:${assertion.id}`);
+    }
+  }
+  const expected = Object.entries(RETIRED_BY_CASE).flatMap(([caseId, ids]) => ids.map(id => `${caseId}:${id}`));
+  const missing = expected.filter(entry => !retired.includes(entry));
+  const extra = retired.filter(entry => !expected.includes(entry));
+  if (missing.length || extra.length) problems.push(`retired set differs from the doc table: missing ${show(missing)} extra ${show(extra)}`);
+  if (expected.length !== RETIRED_COUNT || RETIRED_COUNT !== 26) problems.push(`the doc table names ${RETIRED_COUNT} IDs, not 26`);
+  if (problems.length) record('FAIL', 'inventory: corpus is well formed and marks the 26 S1 retire IDs', problems.join('; '));
+  else record('PASS', `inventory: corpus is well formed and marks the ${RETIRED_COUNT} S1 retire IDs`);
+}
+
+// ---- Replays: every case, both legs, both modes ----------------------------------------------------------------
+for (const item of corpus.cases) {
+  for (const mode of MODES) {
+    const roots = {};
+    for (const leg of LEGS) {
+      let root;
+      try {
+        root = fx.scrubReplay(fx.replayCase(item, leg, mode === 'on' ? { pilot: '1' } : undefined));
+      } catch (error) {
+        infrastructure.push(`${item.id}.${mode} [${leg}]`);
+        infra += 1;
+        console.log(`  INFRA ${item.id}.${mode} [${leg}] — replay failed: ${error.message.split('\n')[0]}`);
+        continue;
+      }
+      roots[leg] = root;
+      const faults = fx.infrastructureFaults(item, root, mode);
+      if (faults.length) {
+        infra += 1;
+        infrastructure.push(`${item.id}.${mode} [${leg}]`);
+        for (const fault of faults) console.log(`  INFRA ${item.id}.${mode} [${leg}] ${fault.actionId}: ${fault.message}`);
+        continue;
+      }
+      for (const assertion of item.expectations[mode]) {
+        const result = fx.evaluateAssertion(root, assertion);
+        const id = `${item.id}.${mode}.${assertion.id} [${leg}]`;
+        const tag = `(${assertion.s1Kind})`;
+        if (result.pass) record('PASS', id, tag);
+        else record('FAIL', id, `${tag} ${reasonFor(assertion, result.actual)}`);
+      }
+    }
+    if (roots.source && roots.packaged && !fx.infrastructureFaults(item, roots.source, mode).length
+      && !fx.infrastructureFaults(item, roots.packaged, mode).length) {
+      const same = JSON.stringify(comparable(roots.source)) === JSON.stringify(comparable(roots.packaged));
+      const id = `${item.id}.${mode}.parity [source=packaged]`;
+      if (same) record('PASS', id, '(control)');
+      else record('FAIL', id, '(control) source and packaged legs disagree');
+    }
+  }
+}
+
+// ---- Summary -----------------------------------------------------------------------------------------------------
+console.log(`\nS1 strict summary: ${passed} PASS, ${failed} FAIL, ${infra} INFRA across ${corpus.cases.length} cases (pilotCredit: false)`);
+if (failures.length) console.log(`FAILED assertions (${failures.length}):\n  ${failures.join('\n  ')}`);
+if (infrastructure.length) console.log(`INFRASTRUCTURE (${infrastructure.length}):\n  ${infrastructure.join('\n  ')}`);
+
+if (infra > 0) {
+  console.error('S1 suite: infrastructure faults present; these are not assertion results.');
+  process.exitCode = 2;
+} else if (failed > 0) {
+  console.error('S1 suite: assertion FAIL present (expected on the RED base; GREEN must clear every FAIL).');
+  process.exitCode = 1;
+} else {
+  console.log('S1 suite: all assertions PASS.');
+}

package/ci/prep/doc-reconciliation-red.js

@@ -38,7 +38,8 @@ const ENTRY_KEYS = ['caseId', 'assertionId', 'distribution', 'baselineSha', 'act
 const FINGERPRINT_FILES = [
   'hooks/scripts/lib/workflow-obligations.js',
   'hooks/scripts/workflow-disposition.js',
-  'hooks/scripts/workflow-stop-gate.js'
+  'hooks/scripts/workflow-stop-gate.js',
+  'hooks/scripts/lib/doc-reconciliation-pilot.js'
 ];
 const CANDIDATE_FILE = 'ci/fixtures/doc-obligations/reconciliation-prep/pending-red.candidate.json';
 const UNREVIEWED_REASON = 'needs-reason';

package/docs/doc-workflow-reconciliation.md

@@ -1,10 +1,12 @@
-# Document workflow reconciliation — Phase 3b preparation
+# Document workflow reconciliation — Phase 3b S1 runtime
 
-**Status: design and fixture contracts only. Runtime reconciliation is not shipped or activated.**
-This document refines the planned [document lifecycle contract](document-lifecycle.md#phase-3b--narrow-integration-contract-planned-not-shipped).
-The [owner's E0/E1 decision](https://github.com/dyphn1/Harness-everything/issues/325#issuecomment-6283237637)
-permits design and RED preparation before #341 E0. Even a default-OFF runtime implementation
-MUST NOT merge or activate before E0 is reviewed and accepted.
+**Status: S1 runtime ships default OFF; opt in with `HARNESS_DOC_RECONCILIATION_PILOT=1`.
+S1 grants no positive document verification credit. S2/S3 are pending; E1 has not started.**
+This document refines the [document lifecycle contract](document-lifecycle.md#phase-3b--narrow-integration-contract-s1-shipped-default-off-positive-reconciliation-not-shipped).
+The [accepted E0](https://github.com/dyphn1/Harness-everything/issues/341#issuecomment-6308604128)
+permits this limited, reversible consumer under the
+[owner's E0/E1 decision](https://github.com/dyphn1/Harness-everything/issues/325#issuecomment-6283237637).
+Current evidence establishes deterministic mechanism/package behavior, not live-host loading or E1 GO.
 
 ## Entry gates and ownership
 
@@ -112,7 +114,7 @@ capabilities, host requirements and existing binding/tool locators; it does not
 or load SKILL.md content. Candidates are optional. Swapping or omitting a provider cannot alter
 expected obligations, authorize a tool, or convert missing evidence to PASS. Existing binding
 resolution handles a chosen provider; independent valid evidence can satisfy a MUST without it.
-An unsupported host reports unavailable capability/reason. H1/H2 runtime proof remains pending.
+An unsupported host reports unavailable capability/reason. S3 provider integration and its H1/H2 runtime proof remain pending.
 
 ## S3 — advisory provider suggestions
 
@@ -227,16 +229,16 @@ live-host loading, E1 GO or #320 promotion. No S1 implementation is a dependency
 
 ## One switch and rollback
 
-Planned switch: `HARNESS_DOC_RECONCILIATION_PILOT=1`. Missing, `0`, or any other value is OFF.
-No production switch reader or runtime import is part of preparation. Test children explicitly
-set or remove the variable; requesting ON during prep still runs existing legacy production code.
+S1 reads `HARNESS_DOC_RECONCILIATION_PILOT=1`; missing, `0`, or any other value is OFF.
+OFF returns before pilot collection or state/report writes. Test children explicitly set or remove
+the variable; ON invokes the S1 runtime's scope assessment and no-credit gate.
 
-After E0, OFF preserves legacy disposition and grants zero pilot verification credit. Legacy
+OFF preserves legacy disposition and grants zero pilot verification credit. Legacy
 `pass` or `satisfied` is not relabeled as document verification. Rollback removes the opt-in,
 records that pilot credit is disabled, and preserves session/evidence history. ON→OFF→ON MUST
 recollect/reconcile rather than trust any persisted pilot or legacy PASS. Withholding pilot
-credit never rejects Stop or changes host authorization. Runtime activation still requires E0;
-the switch cannot serve as a substitute for that acceptance gate.
+credit never rejects Stop or changes host authorization. Accepted E0 permits the limited S1 opt-in;
+the switch does not authorize expansion or replace E1 GO.
 
 ## Preparation harness handoff
 
@@ -262,12 +264,12 @@ replay cases:
 | P07 | `P07-fable-staged`, `P07-fable-parallel`, `P07-fable-multi-agent-workspace`, `P07u` | Three Fable strategies and the untyped compatibility control |
 
 P08 is the suite-level source/package parity check across every replay and the shared runtime bytes;
-it is not a separate `cases.json` record. The 16 cases currently produce 13 `EXPECTED_RED` cases
-and three `CONTROL_PASS` cases (`P02d`, `P06`, and `P07u`); all replay legs must agree. These
+it is not a separate `cases.json` record. The 16 prep cases currently produce 13 `CONTROL_PASS`
+cases and three `EXPECTED_RED` cases (`P02e`, `P03`, and `P05`); all replay legs must agree. These
 statuses qualify the preparation harness only and do not grant document credit.
 
 The [pending-red.json registry](../ci/fixtures/doc-obligations/reconciliation-prep/pending-red.json)
-records 62 exact source/packaged gaps. Its root records `schemaVersion`, `phase`, `baselineSha`,
+records 10 exact source/packaged S2 gaps (five assertion IDs × two distributions), after 52 S1 entries were retired. Its root records `schemaVersion`, `phase`, `baselineSha`,
 `runtimeFingerprint`, and `entries`. The runner validates schema version, a 40-hex capture
 `baselineSha`, a 64-hex `runtimeFingerprint`, and the entry array. Each entry has exactly
 `caseId`, `assertionId`, `distribution`, `baselineSha`, `actual`, `desired`, `blocker`, and
@@ -323,16 +325,205 @@ identifies its `leg` (`source` or `packaged`), `mode` (`off` or `on`), full asse
 classification `status`, and `actual`, with `desired`/`registered` values when applicable. Case
 statuses are `EXPECTED_RED`, `CONTROL_PASS`, `INFRASTRUCTURE`, `NOT_RUN`, or `FAIL`; assertion statuses distinguish
 passing controls, unexpected passes, qualified gaps, unqualified gaps, and registry mismatches.
-`pilotCredit` is always false. `reportOrigin` belongs to the replay's `pilotReportOrigin`
-(`runtime` only for an actual runtime report, otherwise `harness` for a synthesized marker);
-it is not a field on the preparation report's assertion rows. A harness-synthesized unavailable
+`pilotCredit` is always false. The replay records origin in `pilotReportOrigin`
+(`runtime` only for an actual runtime report, otherwise `harness` for a synthesized marker).
+Preparation assertion rows do not carry `reportOrigin`; the S1 runtime report carries its own origin. A harness-synthesized unavailable
 marker is never presented as a production report.
+## S1 — switch, trusted scope and fail-closed no-credit gate
+
+**S1 runtime ships default OFF (`HARNESS_DOC_RECONCILIATION_PILOT=1` opts in). It grants no positive document verification credit; S2/S3 are pending and E1 has not started.**
+The [accepted E0](https://github.com/dyphn1/Harness-everything/issues/341#issuecomment-6308604128)
+permits this limited implementation; the [posted execution plan](https://github.com/dyphn1/Harness-everything/issues/325)
+orders Docs → RED → GREEN → independent review → green CI for each slice. S1 is a temporary
+negative-credit slice. S2 supplies trusted producer records, independent review provenance,
+positive reconciliation and freshness; only then can E1 observation begin. S3 adds optional
+provider suggestions. None of these slices authorizes wider #320 integration.
+
+### Switch and scope decision
+
+Only the exact string `1` enables `HARNESS_DOC_RECONCILIATION_PILOT`. Unset, `0`, `true`,
+whitespace and every other value are OFF. OFF MUST return before any pilot collection or
+report mutation and preserve ordinary output, status and evidence history. Legacy PASS earns
+zero pilot credit. Each ON assessment recollects current scope, including ON→OFF→ON; persisted
+pilot reports or legacy PASS cannot substitute for collection. No discovery runs a generator,
+verifier or network fetch.
+
+On supported non-Fable typed workflows (`stepBindingsEnabled === true`), doc-governed means
+current trusted task/config/baseline/candidate facts establish an applicable document MUST,
+or cannot exclude one. Governed/legacy paths and document roles are evaluated at both old and
+new endpoints, so deletion or rename cannot erase scope. D6.5 facts also include declared derived
+sources, normative content and REQ-citing tests. Use the union of derived obligations; a path
+suffix or an authored step name alone is not a scope assessment. A declared `doc-change` MAY
+request assessment but is neither sufficient nor required for governed applicability. Omitted,
+unknown, incomplete or unavailable scope MUST be treated as governed for withholding credit;
+it cannot establish an empty expected set or opt out. Only a trusted non-document assessment
+retains legacy behavior (P06). Unknown applicability remains unresolved, N/A needs its derivation
+reason, and SHOULD is not a gate.
+
+- **Config authority (PR #351 review P1).** Derivation uses the current config, so a candidate config edit could de-scope a baseline-governed path. Before deriving, S1 compares the exact bytes of every config source the resolver can select (`.agents/harness-everything/project-docs.json` and each host `harness-everything/manifest.json`) at the recorded baseline commit and in the candidate, including additions and removals. Any difference fails closed with reason `config-scope-changed`; it never establishes trusted non-document scope. S2 replaces this with a full `configDigest` binding.
+- A code-only diff (changed code with no changed REQ-citing test) yields `requirement-sync` applicability `unknown` (a MUST), so it is withheld under ON. This is the unknown-applicability cost the Docuvia pilot measures in E1; see [#350](https://github.com/dyphn1/Harness-everything/issues/350) for the false-rejection measurement.
+
+The following anchors are **source-traced at S1 base `5f9726c`**, not runtime or live-host proof:
+
+| Input / boundary | Existing seam and limit | S1 requirement |
+| --- | --- | --- |
+| Config selection | `harness-everything/scripts/project-docs-resolver.js:352` (`resolveDocsConfig`) selects/validates project or host config; active-host, absent and ambiguous branches at `:395–447`. `resolveProjectDocs` at `:607` resolves project paths, not a complete evidence identity | Reuse resolver authority and diagnostics; invalid/ambiguous config, or absent config with governed-scope uncertainty, cannot establish trusted non-doc scope. Parsed config and the bytes selected must agree |
+| Baseline / candidate collection | `harness-everything/scripts/doc-lifecycle.js:1534` (`readGitBaseInventory`) reads Git base blobs/config scope; candidate stored-byte walk at `:1398–1425`; lifecycle baseline consumption at `:1971`. These are lifecycle internals, not an exported workflow scope collector (`:2399`) | Reuse existing stored-byte semantics, but establish current task scope and complete baseline/candidate inventories, including untracked, deletion and rename endpoints; no caller-supplied fixture map is runtime authority |
+| Facts / obligations | `harness-everything/scripts/doc-obligations.js:1375` (`deriveDocFacts`) accepts snapshots/config, not host/VCS collection; `:1065` classifies governed paths; `:1390–1420` evaluates both endpoints; `:1508–1543` (`deriveDocObligations`) handles applicable/unknown capabilities | Reuse these pure APIs unchanged after trusted collection. Input shape validity is not provenance or inventory completeness |
+| Verification-step PASS | `hooks/scripts/workflow-disposition.js:279–296` delegates to `updateStep`; `hooks/scripts/lib/workflow-obligations.js:617–645` validates active step/bindings then writes status | Collect current config and diff scope after ordinary validation, before writing verification PASS |
+| Direct aggregate PASS | `hooks/scripts/workflow-disposition.js:240–258` delegates to `updateObligation`; `hooks/scripts/lib/workflow-obligations.js:513–539` accepts evidence text and writes the aggregate | Assess scope before direct `execute` or `verify` PASS, even after every authored step has passed |
+| Completion | `hooks/scripts/lib/workflow-obligations.js:648–682` reports only current active-step evidence; `hooks/scripts/workflow-stop-gate.js:36–64` checks unresolved items then may persist satisfied | Recollect config and diff scope before every completion decision, including already-satisfied and all-PASS plans |
+
+### S1 pilot-local scope collector
+
+The minimal collector ships in S1 at the seams above, enabled only by the opt-in switch.
+Its deterministic mechanism/package coverage does not establish live-host loading or positive credit.
+
+| Input / decision | S1 contract |
+| --- | --- |
+| Baseline capture | With the switch ON at workflow `plan`, record the repository top-level and the `git rev-parse HEAD` commit in workflow state; ON `start` captures them if the plan lacked a baseline. OFF returns early and records nothing |
+| Baseline unavailable | Not a Git repository, a Git failure or a missing baseline record means baseline `unavailable`; scope cannot be excluded and is treated as governed, withholding credit. An OFF-planned workflow first assessed ON at a credit boundary therefore withholds, including OFF-seeded legacy PASS→ON |
+| Candidate | Collect the current working tree, including non-ignored untracked files, deletions and renames against the recorded baseline commit. Reuse the existing `doc-lifecycle.js` readers / `readGitBaseInventory` and stored-byte semantics; do not re-implement byte normalization. Incomplete inventory means unknown scope, treated as governed |
+| Config | Use existing `resolveDocsConfig` at the candidate. Invalid or ambiguous selection, or absent config with governed-scope uncertainty, cannot establish trusted non-document scope. S1 does not yet bind `configDigest` or the task identity tuple; freshness/provenance binding belongs to S2 |
+| Decision | Feed collected snapshots/config into unchanged `deriveDocFacts` → `deriveDocObligations`. Doc-governed means any applicable or unknown document MUST. Trusted non-document scope requires complete collection and no applicable or unknown document MUST |
+
+Do not use HEAD at assessment as the baseline: a commit during the workflow could erase the
+governed diff and bypass withholding by appearing non-document.
+
+After baseline capture at plan/start, scope collection runs only at verification PASS writes,
+direct aggregate PASS writes and completion. It never runs generators, verifiers or network
+operations. Each boundary recollects candidate/config against the recorded baseline; ON→OFF→ON
+cannot replace that baseline with the latest HEAD or trust a persisted PASS.
+
+**Harness materialization:** prep replays create a temporary workspace, materialize non-empty
+`input.baseFiles` as a committed Git baseline before `plan`, then materialize
+`input.candidateFiles` as the working tree. This lets P06 establish trusted non-document scope
+and governed cases exercise actual diffs. Fixtures without `baseFiles` remain non-Git, so their
+baseline is unavailable and credit is withheld. Fixture maps alone are not runtime authority.
+
+- **Accepted S1 residual (gitignored paths):** ignored, untracked candidate content is outside the non-ignored inventory. S1 grants no positive credit either way; the S2 producer must close this gap or explicitly re-accept it.
+
+### Refusal and completion contract
+
+| Attempt with ON + supported governed/unknown scope | Required S1 result |
+| --- | --- |
+| Authored `doc-change` or review PASS | Remains reachable under existing binding/authorization rules; later missing verification does not reject earlier authored work |
+| Verification-step PASS | Exit `2`; verification status remains pending; no positive document credit |
+| Direct aggregate `obligation --obligation-id execute\|verify --disposition pass` | Exit `2`; requested aggregate stays pending; direct text cannot bypass the gate |
+| Stop / completion, including persisted or legacy PASS | Withhold current completion credit; report `step:<verify>:pending` for the verification step even if no step is active; aggregate verify is effectively pending and workflow cannot remain credited as satisfied |
+
+**Persistence failure (PR #351 review P2).** The withholding decision is applied in memory first: aggregate
+verify becomes pending, a `satisfied` workflow becomes `running`, and `step:<verify>:pending` is reported.
+Persisting that state is best-effort afterwards. A write failure adds the diagnostic `withhold-persist-failed`
+and a reminder; it never leaves the credit decision unapplied, never lets a persisted `satisfied`/PASS count as
+credit, and never makes Stop exit non-zero. Every later ON assessment recollects regardless of what is on disk.
+
+**Unwritable session store (PR #351 follow-up).** S1 cannot durably downgrade a store it cannot write: if both the
+obligations write and Stop's `saveWorkflow()` fail, the files on disk may still say `satisfied` / `verify: pass`.
+S1 therefore guarantees the following **read/credit contract** rather than durable invalidation:
+
+| Guarantee | S1 behaviour when every session write fails |
+| --- | --- |
+| Persisted state is never credit under ON | Every ON verification, direct aggregate and Stop assessment recollects scope and re-derives the decision; a stored `satisfied`, `verify: pass` or old pilot report is never read as document credit. `pilotCredit` is always `false` in S1. |
+| The decision is still emitted | Stop still prints the `Unresolved workflow evidence: … step:<verify>:pending` reminder and a `withhold-persist-failed` diagnostic, after the failed `saveWorkflow()` rather than instead of it. |
+| Stop stays non-blocking | Stop exits `0`; no lock, no retry loop. |
+| Not claimed | A durable on-disk downgrade, or that a non-pilot reader (OFF, or another tool) will see `running`. With the switch OFF, stored legacy state is legacy state. |
+
+A successful in-memory downgrade is **not** counted as durable invalidation.
+
+**Scope of the recovery (PR #351 re-review).** Stop's local persistence recovery and the `withhold-persist-failed`
+diagnostic apply **only** when this Stop run made an actual ON, supported, withheld pilot decision. With the switch
+OFF, and for Fable or persisted untyped workflows, a failing `saveWorkflow()` keeps the pre-S1 path unchanged: the
+error reaches Stop's outer handler, exactly as legacy behaviour, and no pilot diagnostic is emitted.
+
+Withholding persisted credit MUST NOT reset authored `doc-change`, review, bindings or evidence
+history merely to manufacture an active step. Compute current unresolved verification independently
+of saved PASS; do not trust old aggregate status. Test OFF-completed→ON and an all-PASS typed plan
+that acquires governed scope. Both `hooks/scripts/workflow-stop-gate.js:12–65` and
+`hooks/scripts/stop-gate.js:14–47` MUST still exit `0`, including collector errors. Reminders never
+reject Stop, authorize a tool or introduce a tool lock. Only disposition PASS attempts return `2`.
+Existing binding/authorization diagnostics precede pilot refusal (P02d).
+
+### Runtime pilot report and unsupported paths
+
+The S1 runtime report uses the shape specified in
+[trust-contract.json](../ci/fixtures/doc-obligations/reconciliation-prep/trust-contract.json):
+`schemaVersion`, `pilotStatus`, `pilotCredit`, `identity`, `expectedMustIds`, `results`,
+`unsatisfied`, `diagnostics`. Each unsatisfied item contains `obligationId`, `state`, `reasonCode`.
+S1 always reports `pilotCredit: false`; it cannot emit `verified`. Missing producer identity is
+`null`; unknown expected scope stays diagnostic/unresolved, never an inferred empty-set PASS.
+`results` retain checker observation/outcome enums unchanged. Supported withheld scope reports
+`unavailable` when collection/producer support is absent, otherwise `unresolved`; known MUSTs
+remain listed without pretending that producer evidence exists. S1 reason codes are
+`unknown-applicability` for an unknown MUST, `producer-unavailable` for an applicable MUST
+without the S2 producer, `baseline-unavailable`, `config-unavailable`, `scope-unavailable`
+for missing baseline/config or incomplete inventory, and `collector-unavailable` for other
+collector failures. Unsupported paths diagnose `unsupported-workflow`; a complete assessment
+with no applicable/unknown MUST diagnoses `trusted-non-document-scope`.
+
+An actual runtime report MUST carry `reportOrigin: runtime`; replay extraction sets
+`pilotReportOrigin: runtime` only for that captured report. The helper's
+`ci/lib/doc-reconciliation-prep-fixtures.js:runtimePilotOf()` reads the emitted report;
+missing reports retain `pilot: null` and origin `harness`, never a synthesized runtime marker.
+OFF does not produce or mutate a pilot report.
+
+With ON, loaded `fable-staged`, `fable-parallel`, `fable-multi-agent-workspace` and persisted
+untyped workflows report `unavailable`, with no credit and a reason. Fable stage bindings,
+including a correlated loaded stage binding, cannot become document verification; preserve
+existing stage lifecycle rather than entering generic typed-step reconciliation. A **new invalid
+untyped plan** is different: P07u still rejects plan creation with exit `2` and `pilot === null`.
+The separate persisted-untyped fixture covers loaded records. Unsupported paths add no Stop lock.
+
+### Registry staging and independent RED handoff
+
+S1 has **52 entries retired / 10 kept**, each assertion ID counted separately for
+`source` and `packaged`. Strict runtime assertions cover the retired entries; the reviewed prep
+registry retains these five S2 assertion IDs × two distributions:
+
+| S1 retire: 26 IDs × 2 | Assertion suffixes under `<case>.on.` |
+| --- | --- |
+| P01 | `verify-exit-refused`, `verify-obligation-pending`, `stop-unsatisfied`, `stop-reports-verification` |
+| P04 | `direct-execute-refused`, `direct-verify-refused`, `verify-obligation-pending` |
+| Each of P02a, P02b, P02c, P02f, P02g | `verify-pass-exit`, `stop-state`, `stop-reports` |
+| P03 | `verify-pass-exit` |
+| Each of the three P07 Fable cases | `pilot-status-unavailable` |
+| **S2 keep: 5 IDs × 2** | **Assertion suffixes under `<case>.on.`** |
+| P02e | `review-pass-exit`, `stop-reports` |
+| P03 | `verify-retry-exit` |
+| P05 | `stop-on-2-withheld`, `stop-on-3-withheld` |
+
+- Move retired gaps into strict runtime assertions. Declare intentional ON exit `2` in each
+  action's `expectExit`; do not weaken crash, output, deadline or other infrastructure policies
+  (`ci/lib/doc-reconciliation-prep-fixtures.js:298–352`). Preserve explicit Stop exit `0` checks.
+- P02e independent review provenance belongs to S2. Do not reject review by matching self-review
+  prose or because later verifier evidence is absent. P03 first review remains reachable; its
+  first verification is refused, and retry remains RED in S1. S2 changes retry ON `expectExit`
+  from `2` to `0` when real evidence can earn credit.
+- P05's initial ON positive verification and `stop-on-1` cannot pass in S1. Preserve a distinct S2
+  positive-credit case and its approved desired outcomes; add a separate OFF-seeded legacy PASS→ON
+  withholding case for S1. Merely changing exit policy introduces an unregistered initial-state gap.
+- Deliberately review/recapture the changed baseline and registry actual/desired qualification;
+  include the newly imported pilot module in the ordered runtime fingerprint. Then exactly the
+  targeted entries retire and the remaining `--expect-red` run must qualify on that reviewed S1
+  baseline. Deleting registry rows alone proves nothing.
+- Additional strict S1 cases: governed diff without authored `doc-change`, direct aggregate PASS
+  after authored completion, correlated Fable stage binding, persisted untyped workflow, legacy
+  PASS and ON→OFF→ON recollection. These additions are not part of the 52 existing entries.
+- Preserve P06 with trusted non-doc scope, P07u, P02d ordering, OFF controls and source/package
+  parity. Require the relevant deterministic gates plus `npm run verify:all -- --fast`, independent
+  review with no open P1/P2, and full green CI including Windows on the PR head.
+
+S1 proves only its tested no-credit mechanism. It does not prove positive reconciliation,
+independent producer provenance, live-host loading, H1–H4 effectiveness or E1 GO. Registry empty
+is a later strict-prep gate, not proof of any of those evidence layers.
+
 ## Implementation and acceptance after E0
 
-After accepted E0, implement the minimum trusted producer and optional provider adapter, add
-the switch reader and narrow W/D/completion integration, package generated copies, and remove
-pending exemptions as strict tests become GREEN. Require every expected applicable MUST and
-freshness check, source/package compatibility, negative cases and relevant green CI including
-Windows. A green preparation harness establishes only its declared mechanism/data checks.
-It does not claim runtime reconciliation, E0/E1 acceptance, independent host provenance or
-architectural benefit. E1 observations and H1–H4/paired evaluation remain separate gates.
+S1 ships the default-OFF switch, narrow disposition/completion no-credit integration and runtime
+status reporting. S2's trusted producer, positive reconciliation and freshness remain pending;
+S3's optional provider adapter remains pending. Require every expected applicable MUST and
+freshness check before positive credit, plus source/package compatibility, negative cases and
+relevant green CI including Windows. The S1 suites establish their tested mechanism/package
+contracts; they do not establish independent host provenance, live-host loading or architectural
+benefit. E1 has not started and begins only after a creditable S2; E1 GO and H1–H4/paired evidence
+remain separate gates.

package/docs/document-lifecycle.md

@@ -15,19 +15,19 @@ This table distinguishes merged mechanism code from end-to-end workflow integrat
 | 2 — roles, IDs, aliases, legacy, supersession, index, D6.9 PRD revisions | **Merged** in #327; do not rebuild this lifecycle logic for Phase 3 |
 | Step-type prerequisite (#326) | **Complete:** PR #328 merged; Harness-owned `doc-change` is explicitly declared, has no implicit TDD binding, and is not auto-inserted by router/System One |
 | 3a — document facts, obligations and evidence producer | **Merged** in #334: `harness-everything/scripts/doc-obligations.js` and `doc-evidence.js`. H3/H4 have *partial deterministic mechanism* coverage, not integrated workflow evidence. Known limitations: caller-attested envelope; `configDigest` presence-only; `candidateDigest` restricted to `docs/prd/`; missing independent task-scope binding. Deleted and old rename paths are bound to trusted per-path baseline evidence ([doc-evidence-baseline-binding.md](doc-evidence-baseline-binding.md), #335 fixed by #342), with workflow-disposition reconciliation left out of scope |
-| 3b — pilot-local provider suggestions and workflow evidence reconciliation | **Preparation complete; runtime implementation not started and #341-gated.** Provider metadata, adapter/interface design and RED fixtures may proceed in parallel with #341 Phase 0A–0C; **runtime** Evidence Reconciliation must not merge or activate before **#341 E0** is accepted (see the entry-gates bullet in the 3b contract below). Implement only a thin consumer adapter; do not wait for a generic #320 registry/CDG. Includes the minimum trusted producer for baseline/candidate/config/task-scope/reviewer identity, fail-closed negative cases, doc-governed gating on `step`/`obligation` writes at the verification/completion boundary, and freshness re-check at completion. The #335 baseline-bound deletion/rename evidence has shipped (#342); claiming complete integration still requires the reconciliation gate above. Preserve existing required-binding compatibility |
+| 3b — pilot-local provider suggestions and workflow evidence reconciliation | **S1 runtime ships default OFF** (opt in with `HARNESS_DOC_RECONCILIATION_PILOT=1`), with trusted scope assessment and fail-closed withholding; **no positive document verification credit**. See [S1 switch, trusted scope and no-credit contract](doc-workflow-reconciliation.md#s1--switch-trusted-scope-and-fail-closed-no-credit-gate). **S3 pure advisory provider suggestions shipped in 0.37.0 (not wired); S2 trusted producer/positive reconciliation/freshness is pending; E1 has not started.** Accepted #341 E0 permits this limited reversible consumer. Current evidence is deterministic mechanism/package coverage, not live-host loading or E1 GO; preserve existing required-binding compatibility |
 | 3c — H1–H4 and paired-task evaluation | **Not started.** Mechanism tests alone are insufficient for architecture promotion; compare frozen baseline and treatment on real bounded tasks, success/failure first, then conditional cost and latency |
 | 1b — shared documentation craft and family metadata | **Splittable.** Shared references and thin skill consumers can proceed independently. A small optional logical-family metadata seam may be piloted; physical skill directory moves remain blocked on #320 identity/path separation |
 | 4 — derived-view generators and `describes:` drift | **Not started.** Preserve generator authorization, deterministic regenerate-equals and scoped reminder semantics |
 
-### Phase 3b — narrow integration contract (planned, not shipped)
+### Phase 3b — narrow integration contract (S1 shipped default OFF; positive reconciliation not shipped)
 
 The preparation design, test-only provider/trust contracts, and qualified RED replay are complete:
 [Document workflow reconciliation](doc-workflow-reconciliation.md),
 [case corpus](../ci/fixtures/doc-obligations/reconciliation-prep/cases.json),
 [pending-RED registry](../ci/fixtures/doc-obligations/reconciliation-prep/pending-red.json), and
-[preparation suite](../ci/mechanism-325-3b-preparation.test.js). Runtime reconciliation remains
-unshipped and unactivated until #341 E0 is reviewed and accepted.
+[preparation suite](../ci/mechanism-325-3b-preparation.test.js). #341 E0 is accepted; S1 ships the
+default-OFF no-credit gate only. Positive reconciliation (S2) remains unshipped.
 
 - **Inputs:** explicit active `doc-change` step, D6.5 diff facts, Phase 3a obligations/evidence, available provider *metadata*, and host capabilities.
 - **Entry and activation gates (#341):** parallel preparatory work — provider metadata, adapter/interface design and RED fixtures — may proceed while #341 Phase 0A–0C runs, but the **runtime** Evidence Reconciliation must not merge or activate until **#341 E0** is reviewed and accepted (initial evidence read/binding/outcome conformance, mutation and read-order compatibility, source/package parity, zero false MUST PASS on applicable adversarial cases, and applicable green CI including Windows). After E0, only the **bounded, opt-in, reversible** documentation consumer is eligible for runtime integration at the existing verification/disposition path (no second router, forced provider, new lock, or weakened authorization, with a documented rollback), and it supplies the observed exposure for **#341 E1** (initial target 2–3 genuine development/review cycles with sufficient case mix, not elapsed time). **#341 E1 GO / REVISE / NO-GO gates expansion beyond the limited pilot, not the pilot's own observation** (missing or unrepresentative exposure is `UNCHECKED`, never an automatic GO). The H1–H4 paired-task architectural gate below stays required for any #320 promotion in addition to E1. Shared evidence-read/binding/decision defects route to #341 (fixture-first correction, regression replay, re-observation); documentation policy and the trusted host/VCS producer remain #325 deliverables here.

package/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.37.0
+  version: 0.38.0
 ---
 
 # Harness Everything

package/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();