harness-everything 0.36.1 → 0.36.3

package/ci/mechanism-335-baseline-evidence.test.js

@@ -1877,7 +1877,9 @@ checkCase('335 P3 the metadata-validated rename destination digest is carried wi
   for (const target of [modules, packageModules]) {
     const label = target === modules ? 'canonical' : 'packaged';
     const ctx = prepare('rename', target);
-    const counted = countingDigestEntry(RENAME_CAPTURED, { validReads: 3, later: 'throw' });
+    // P3(r4321077631): the destination snapshot reads its own digest exactly once, so a getter
+    // that throws after that single valid read is never reached and the captured B still binds.
+    const counted = countingDigestEntry(RENAME_CAPTURED, { validReads: 1, later: 'throw' });
     const artifacts = { ...ctx.artifacts, [RENAME_TO]: counted.entry };
     const record = execRecord(ctx, 'pair-run', 'doc-change:doc-lint', {
       paths: [RENAME_FROM, RENAME_TO], candidatePaths: [], baselinePaths: [RENAME_FROM],
@@ -1892,12 +1894,74 @@ checkCase('335 P3 the metadata-validated rename destination digest is carried wi
     if (!result.artifactDigest.includes(`${RENAME_TO}=${RENAME_CAPTURED}`)) {
       failures.push(`${label}: audit=${result.artifactDigest}`);
     }
-    if (counted.reads() !== 3) failures.push(`${label}: destination reads=${counted.reads()}`);
+    if (counted.reads() !== 1) failures.push(`${label}: destination reads=${counted.reads()}`);
   }
   assert.deepStrictEqual(failures, [],
     `the validated destination digest must be carried: ${failures.join('; ')}`);
 });
 
+// #342 review P3: a destination snapshot rejected during metadata (throwing or unusable own
+// digest) is still a visited snapshot. The capture and audit lanes must never re-read it: the
+// single metadata read stays the only digest read, and a stateful getter cannot ship a later
+// value into the audit identity even though its entry failed.
+checkCase('#342 P3 a rejected destination snapshot is read exactly once even when its digest getter throws', () => {
+  const failures = [];
+  for (const target of [modules, packageModules]) {
+    const label = target === modules ? 'canonical' : 'packaged';
+    const ctx = prepare('rename', target);
+    const counted = countingDigestEntry(RENAME_CAPTURED, { validReads: 0, later: 'throw' });
+    const artifacts = { ...ctx.artifacts, [RENAME_TO]: counted.entry };
+    const record = execRecord(ctx, 'move-run', 'doc-change:doc-lint', {
+      paths: [RENAME_FROM, RENAME_TO], candidatePaths: [RENAME_TO], baselinePaths: [RENAME_FROM]
+    });
+    let out;
+    try {
+      out = runDocLint(ctx, target, { artifacts, records: [record] });
+    } catch (error) { failures.push(`${label}: escaped: ${error.message}`); continue; }
+    const result = resultOf(out, 'doc-change:doc-lint');
+    if (result.outcome !== 'none') failures.push(`${label}: outcome=${result.outcome}`);
+    if (!diagnosticCodes(out).includes('candidate-artifacts-invalid')) {
+      failures.push(`${label}: diagnostics=${diagnosticCodes(out)}`);
+    }
+    if (counted.reads() !== 1) failures.push(`${label}: destination reads=${counted.reads()}`);
+    if (!result.artifactDigest.includes(`${RENAME_TO}=missing`)) {
+      failures.push(`${label}: audit=${result.artifactDigest}`);
+    }
+  }
+  assert.deepStrictEqual(failures, [],
+    `a rejected throwing destination must be read once and never again: ${failures.join('; ')}`);
+});
+
+checkCase('#342 P3 an unusable first destination read never ships a later non-empty value into the audit', () => {
+  const failures = [];
+  for (const target of [modules, packageModules]) {
+    const label = target === modules ? 'canonical' : 'packaged';
+    const ctx = prepare('rename', target);
+    // First read: unusable ''. Any later read (which must not happen) returns non-empty
+    // RENAME_LATER, so the audit would describe it if the rejected snapshot were re-read.
+    const counted = countingDigestEntry('', { validReads: 1, later: 'value', laterValue: RENAME_LATER });
+    const artifacts = { ...ctx.artifacts, [RENAME_TO]: counted.entry };
+    const record = execRecord(ctx, 'move-run', 'doc-change:doc-lint', {
+      paths: [RENAME_FROM, RENAME_TO], candidatePaths: [RENAME_TO], baselinePaths: [RENAME_FROM]
+    });
+    let out;
+    try {
+      out = runDocLint(ctx, target, { artifacts, records: [record] });
+    } catch (error) { failures.push(`${label}: escaped: ${error.message}`); continue; }
+    const result = resultOf(out, 'doc-change:doc-lint');
+    if (result.outcome !== 'none') failures.push(`${label}: outcome=${result.outcome}`);
+    if (counted.reads() !== 1) failures.push(`${label}: destination reads=${counted.reads()}`);
+    if (result.artifactDigest.includes(RENAME_LATER)) {
+      failures.push(`${label}: audit describes a later value: ${result.artifactDigest}`);
+    }
+    if (!result.artifactDigest.includes(`${RENAME_TO}=missing`)) {
+      failures.push(`${label}: audit=${result.artifactDigest}`);
+    }
+  }
+  assert.deepStrictEqual(failures, [],
+    `an unusable destination read must stay single-read and 'missing': ${failures.join('; ')}`);
+});
+
 checkCase('335 P3 a stale pair plus a destination-only record stays none under descriptor patience', () => {
   const failures = [];
   for (const target of [modules, packageModules]) {
@@ -2116,10 +2180,12 @@ checkCase('335 P3 two accepted entries sharing a rename destination must agree o
       }
     }
 
-    // Dynamic shared destination: D1 for the first entry's metadata, D2 for the second.
+    // Dynamic shared destination: D1 for the first entry's single-read snapshot, D2 for the
+    // second (the per-entry read advances the getter). P3(r4321077631) made each entry's read
+    // exactly one, so the fixture flips after one valid read.
     {
       const { ctx } = sharedDestinationContext(target);
-      const dynamic = countingDigestEntry(RENAME_CAPTURED, { validReads: 3, later: 'value', laterValue: RENAME_LATER });
+      const dynamic = countingDigestEntry(RENAME_CAPTURED, { validReads: 1, later: 'value', laterValue: RENAME_LATER });
       const artifacts = { ...ctx.artifacts, [RENAME_TO]: dynamic.entry };
       const out = run(artifacts, [
         sharedPairRecord(ctx, 'pair-run', RENAME_CAPTURED),
@@ -2177,6 +2243,69 @@ checkCase('335 P3 two accepted entries sharing a rename destination must agree o
     `shared rename destinations must agree on the validated digest: ${failures.join('; ')}`);
 });
 
+// #342 review P3: a shared rename destination whose snapshot is rejected must stay honored.
+// invalid→valid: the first declaring entry fails its own snapshot; a later declaring entry must
+// fail closed without reading the destination again (one read total, audit 'missing').
+// valid→throw: the first entry carries a validated success; the second declaration's read
+// throws, and the poisoned visited state wins in the audit over the previously seeded success
+// (one read per declaring entry, two total).
+checkCase('#342 P3 a rejected shared destination is never read again and keeps audit precedence', () => {
+  const failures = [];
+  for (const target of [modules, packageModules]) {
+    const label = target === modules ? 'canonical' : 'packaged';
+
+    // invalid→valid: first own read unusable, later reads (which must not happen) valid.
+    {
+      const { ctx, obligations, baseline } = sharedDestinationContext(target);
+      const counted = countingDigestEntry('', { validReads: 1, later: 'value', laterValue: RENAME_CAPTURED });
+      // Read counts are scoped to the obligation under test; unrelated obligations keep the
+      // designed legacy candidate read, exactly as runDocLint's single-obligation runs do.
+      const out = target.checkDocObligations({
+        obligations: obligations.filter(item => item.id === 'doc-change:doc-lint'),
+        artifacts: { ...ctx.artifacts, [RENAME_TO]: counted.entry }, baseline,
+        executionRecords: [sharedPairRecord(ctx, 'pair-run', RENAME_CAPTURED)], reviewRecords: []
+      });
+      const result = resultOf(out, 'doc-change:doc-lint');
+      if (result.outcome !== 'none') failures.push(`${label}/invalid-to-valid: outcome=${result.outcome}`);
+      if (!diagnosticCodes(out).includes('baseline-path-invalid')) {
+        failures.push(`${label}/invalid-to-valid: diagnostics=${diagnosticCodes(out)}`);
+      }
+      if (counted.reads() !== 1) failures.push(`${label}/invalid-to-valid: destination reads=${counted.reads()}`);
+      if (result.artifactDigest.includes(RENAME_CAPTURED)) {
+        failures.push(`${label}/invalid-to-valid: audit describes a later value: ${result.artifactDigest}`);
+      }
+      if (!result.artifactDigest.includes(`${RENAME_TO}=missing`)) {
+        failures.push(`${label}/invalid-to-valid: audit=${result.artifactDigest}`);
+      }
+    }
+
+    // valid→throw: successful first snapshot, then a throwing own read on the second entry.
+    {
+      const { ctx, obligations, baseline } = sharedDestinationContext(target);
+      const counted = countingDigestEntry(RENAME_CAPTURED, { validReads: 1, later: 'throw' });
+      const out = target.checkDocObligations({
+        obligations: obligations.filter(item => item.id === 'doc-change:doc-lint'),
+        artifacts: { ...ctx.artifacts, [RENAME_TO]: counted.entry }, baseline,
+        executionRecords: [sharedPairRecord(ctx, 'pair-run', RENAME_CAPTURED)], reviewRecords: []
+      });
+      const result = resultOf(out, 'doc-change:doc-lint');
+      if (result.outcome !== 'none') failures.push(`${label}/valid-to-throw: outcome=${result.outcome}`);
+      if (!diagnosticCodes(out).includes('candidate-artifacts-invalid')) {
+        failures.push(`${label}/valid-to-throw: diagnostics=${diagnosticCodes(out)}`);
+      }
+      if (counted.reads() !== 2) failures.push(`${label}/valid-to-throw: destination reads=${counted.reads()}`);
+      if (result.artifactDigest.includes(RENAME_CAPTURED)) {
+        failures.push(`${label}/valid-to-throw: audit describes a rejected-state value: ${result.artifactDigest}`);
+      }
+      if (!result.artifactDigest.includes(`${RENAME_TO}=missing`)) {
+        failures.push(`${label}/valid-to-throw: audit=${result.artifactDigest}`);
+      }
+    }
+  }
+  assert.deepStrictEqual(failures, [],
+    `a rejected shared destination must stay single-read and audited as 'missing': ${failures.join('; ')}`);
+});
+
 // ---------------------------------------------------------------------------
 // P2 applicability-gated destination snapshot (review r4318520818 at 56f3094):
 // N/A and unknown obligations never bind evidence, so their destination digest
@@ -2220,10 +2349,11 @@ checkCase('335 P2 an inapplicable rename never consumes the destination snapshot
     }
 
     // Positive control: the applicable obligation still captures the destination snapshot
-    // once during metadata and binds against it.
+    // once during metadata and binds against it. P3(r4321077631) made that capture a
+    // single guarded read, so the getter is never consumed beyond its first valid read.
     {
       const ctx = prepare('rename', target);
-      const counted = countingDigestEntry(RENAME_CAPTURED, { validReads: 3, later: 'value', laterValue: RENAME_LATER });
+      const counted = countingDigestEntry(RENAME_CAPTURED, { validReads: 1, later: 'throw' });
       const artifacts = { ...ctx.artifacts, [RENAME_TO]: counted.entry };
       const record = {
         ...execRecord(ctx, 'pair-run', 'doc-change:doc-lint', {
@@ -2235,7 +2365,7 @@ checkCase('335 P2 an inapplicable rename never consumes the destination snapshot
       const out = checkArtifacts(ctx, artifacts, { obligations: [obligation], executionRecords: [record] }, target);
       const result = resultOf(out, 'doc-change:doc-lint');
       if (result.outcome !== 'pass') failures.push(`${label}/applicable: outcome=${result.outcome}`);
-      if (counted.reads() !== 3) failures.push(`${label}/applicable: destination getter reads=${counted.reads()}`);
+      if (counted.reads() !== 1) failures.push(`${label}/applicable: destination getter reads=${counted.reads()}`);
     }
   }
   assert.deepStrictEqual(failures, [],
@@ -2687,4 +2817,222 @@ checkCase('335 P2 the audit mirror reports the metadata-validated path snapshot,
     `the audit mirror must use the validated path snapshot: ${failures.join('; ')}`);
 });
 
+//----------------------------------------------------------------------------
+// P2(r4321077631/r4321077638) at 7217b3a: whole-baseline identity and rename
+// destination digests must each be read exactly once — the same scalar is
+// validated and captured, so a stateful getter cannot pass validation as one
+// value while evidence binds its later value.
+//----------------------------------------------------------------------------
+
+const RENAME_OLD = 'docs/adr/old.md';
+const RENAME_NEW = 'docs/adr/new.md';
+const RENAME_BASELINE_DIGEST = sha256('rename whole baseline');
+const RENAME_OLD_BASELINE = sha256('old document baseline content');
+const RENAME_DEST_B = sha256('destination content B');
+const RENAME_DEST_C = sha256('destination content C');
+
+checkCase('335 P2 the whole-baseline digest is validated and captured from one read', () => {
+  const failures = [];
+  for (const target of [modules, packageModules]) {
+    const label = target === modules ? 'canonical' : 'packaged';
+    const PATH = BASELINE_EXAMPLE;
+
+    function runWith(baseline, recordBaseDigest) {
+      return target.checkDocObligations({
+        obligations: [{
+          id: 'doc-change:doc-lint',
+          capability: 'doc-lint',
+          level: 'MUST',
+          applicability: 'applicable',
+          scope: { paths: [PATH], baselinePaths: [{ path: PATH, reason: 'deleted' }] }
+        }],
+        artifacts: {},
+        baseline,
+        executionRecords: [{
+          id: 'tomb-run',
+          obligationId: 'doc-change:doc-lint',
+          command: 'node ci/mechanism-335-baseline-evidence.test.js # tomb-run',
+          exitCode: 0,
+          provenance: 'baseline identity snapshot regression',
+          baseDigest: recordBaseDigest,
+          paths: [PATH],
+          artifactDigests: {},
+          baselineArtifacts: { [PATH]: BASELINE_EXAMPLE_VALUE }
+        }],
+        reviewRecords: []
+      });
+    }
+
+    // Stateful identity getter: validation must use the first read; a record attesting to the
+    // later value cannot pass.
+    {
+      let identityReads = 0;
+      const baseline = {
+        get digest() {
+          identityReads += 1;
+          return identityReads === 1 ? 'baseline-A' : 'baseline-B';
+        },
+        artifacts: { [PATH]: BASELINE_EXAMPLE_VALUE }
+      };
+      let out;
+      try {
+        out = runWith(baseline, 'baseline-B');
+      } catch (error) {
+        failures.push(`${label}/stateful: escaped: ${error.message}`);
+        continue;
+      }
+      const result = out.results.find(item => item.obligationId === 'doc-change:doc-lint');
+      if (identityReads !== 1) failures.push(`${label}/stateful: identity getter reads=${identityReads}`);
+      if (result.outcome === 'pass') failures.push(`${label}/stateful: a record bound to the later value passed`);
+      if (!out.diagnostics.some(item => item.code === 'stale-base-digest')
+        && !out.diagnostics.some(item => item.code === 'baseline-identity-missing')) {
+        failures.push(`${label}/stateful: diagnostics=${out.diagnostics.map(item => item.code)}`);
+      }
+    }
+
+    // Stable controls: the validated identity binds; a different identity does not.
+    {
+      const passing = runWith(
+        { digest: 'baseline-A', artifacts: { [PATH]: BASELINE_EXAMPLE_VALUE } }, 'baseline-A');
+      if (passing.results.find(item => item.obligationId === 'doc-change:doc-lint').outcome !== 'pass') {
+        failures.push(`${label}/stable: the validated identity did not pass`);
+      }
+      const stale = runWith(
+        { digest: 'baseline-B', artifacts: { [PATH]: BASELINE_EXAMPLE_VALUE } }, 'baseline-A');
+      const staleResult = stale.results.find(item => item.obligationId === 'doc-change:doc-lint');
+      if (staleResult.outcome !== 'none') failures.push(`${label}/stable: outcome=${staleResult.outcome}`);
+      if (!stale.diagnostics.some(item => item.code === 'stale-base-digest')) {
+        failures.push(`${label}/stable: diagnostics=${stale.diagnostics.map(item => item.code)}`);
+      }
+    }
+
+    // A throwing identity getter fails closed as a metadata error instead of escaping.
+    {
+      const baseline = {
+        get digest() {
+          throw new Error('baseline identity getter');
+        },
+        artifacts: { [PATH]: BASELINE_EXAMPLE_VALUE }
+      };
+      let out;
+      try {
+        out = runWith(baseline, 'baseline-A');
+      } catch (error) {
+        failures.push(`${label}/throwing: escaped: ${error.message}`);
+        continue;
+      }
+      const result = out.results.find(item => item.obligationId === 'doc-change:doc-lint');
+      if (result.outcome === 'pass') failures.push(`${label}/throwing: a throwing identity produced a pass`);
+      if (!out.diagnostics.some(item => item.code === 'baseline-identity-missing')) {
+        failures.push(`${label}/throwing: diagnostics=${out.diagnostics.map(item => item.code)}`);
+      }
+    }
+  }
+  assert.deepStrictEqual(failures, [],
+    `the whole-baseline identity must be captured once: ${failures.join('; ')}`);
+});
+
+checkCase('335 P2 the rename destination digest is validated and captured from one read', () => {
+  const failures = [];
+  for (const target of [modules, packageModules]) {
+    const label = target === modules ? 'canonical' : 'packaged';
+    const obligation = {
+      id: 'doc-change:doc-lint',
+      capability: 'doc-lint',
+      level: 'MUST',
+      applicability: 'applicable',
+      scope: {
+        paths: [RENAME_OLD, RENAME_NEW],
+        baselinePaths: [{ path: RENAME_OLD, reason: 'rename-from', renameTo: RENAME_NEW }]
+      }
+    };
+    const baseline = {
+      digest: RENAME_BASELINE_DIGEST,
+      artifacts: { [RENAME_OLD]: RENAME_OLD_BASELINE }
+    };
+
+    function runWith(destinationEntry, recordDestinationDigest) {
+      return target.checkDocObligations({
+        obligations: [obligation],
+        artifacts: { [RENAME_NEW]: destinationEntry },
+        baseline,
+        executionRecords: [{
+          id: 'rename-run',
+          obligationId: 'doc-change:doc-lint',
+          command: 'node ci/mechanism-335-baseline-evidence.test.js # rename-run',
+          exitCode: 0,
+          provenance: 'rename destination snapshot regression',
+          baseDigest: RENAME_BASELINE_DIGEST,
+          paths: [RENAME_OLD, RENAME_NEW],
+          artifactDigests: { [RENAME_NEW]: recordDestinationDigest },
+          baselineArtifacts: { [RENAME_OLD]: RENAME_OLD_BASELINE }
+        }],
+        reviewRecords: []
+      });
+    }
+
+    // Stateful destination digest getter: validation must use the first read B; a record
+    // carrying only the later C cannot pass.
+    {
+      let destinationReads = 0;
+      const statefulDestination = {
+        get digest() {
+          destinationReads += 1;
+          return destinationReads === 1 ? RENAME_DEST_B : RENAME_DEST_C;
+        }
+      };
+      let out;
+      try {
+        out = runWith(statefulDestination, RENAME_DEST_C);
+      } catch (error) {
+        failures.push(`${label}/stateful: escaped: ${error.message}`);
+        continue;
+      }
+      const result = out.results.find(item => item.obligationId === 'doc-change:doc-lint');
+      if (destinationReads !== 1) failures.push(`${label}/stateful: destination digest reads=${destinationReads}`);
+      if (result.outcome === 'pass') failures.push(`${label}/stateful: a record bound to the later value passed`);
+      if (!out.diagnostics.some(item => item.code === 'stale-artifact-digest')) {
+        failures.push(`${label}/stateful: diagnostics=${out.diagnostics.map(item => item.code)}`);
+      }
+    }
+
+    // Stable controls: the validated destination binds its own value; a different value is stale.
+    {
+      const passing = runWith({ digest: RENAME_DEST_B }, RENAME_DEST_B);
+      if (passing.results.find(item => item.obligationId === 'doc-change:doc-lint').outcome !== 'pass') {
+        failures.push(`${label}/stable: the validated destination did not pass; diagnostics=${passing.diagnostics.map(item => item.code)}`);
+      }
+      const stale = runWith({ digest: RENAME_DEST_B }, RENAME_DEST_C);
+      const staleResult = stale.results.find(item => item.obligationId === 'doc-change:doc-lint');
+      if (staleResult.outcome !== 'none') failures.push(`${label}/stable: outcome=${staleResult.outcome}`);
+      if (!stale.diagnostics.some(item => item.code === 'stale-artifact-digest')) {
+        failures.push(`${label}/stable: diagnostics=${stale.diagnostics.map(item => item.code)}`);
+      }
+    }
+
+    // A throwing destination digest getter fails closed instead of escaping.
+    {
+      const throwingDestination = {
+        get digest() {
+          throw new Error('destination digest getter');
+        }
+      };
+      let out;
+      try {
+        out = runWith(throwingDestination, RENAME_DEST_B);
+      } catch (error) {
+        failures.push(`${label}/throwing: escaped: ${error.message}`);
+        continue;
+      }
+      const result = out.results.find(item => item.obligationId === 'doc-change:doc-lint');
+      if (result.outcome === 'pass') failures.push(`${label}/throwing: a throwing destination produced a pass`);
+      if (!out.diagnostics.some(item => item.code === 'candidate-artifacts-invalid')) {
+        failures.push(`${label}/throwing: diagnostics=${out.diagnostics.map(item => item.code)}`);
+      }
+    }
+  }
+  assert.deepStrictEqual(failures, [],
+    `the rename destination digest must be captured once: ${failures.join('; ')}`);
+});
+
 helper.finish();

package/docs/doc-evidence-baseline-binding.md

@@ -82,10 +82,16 @@ after validation, cannot mute the stale-baseline diagnostic, and cannot drift th
 Its first read must therefore be the value every consumer sees; a getter that starts returning a
 different or unusable value later is factored out entirely. A baseline per-path inspection that
 throws during validation is a `baseline-artifact-invalid` metadata error and fails the path
-closed. The audit mirror is likewise keyed by the **validated** path snapshot rather than a
-re-read of `baselinePaths[].path`, so a stateful `path` accessor is read exactly once and a
-passing result always describes the baseline identity that validated and bound the evidence.
-closed instead of escaping the checker.
+closed instead of escaping the checker. The audit mirror is likewise keyed by the **validated**
+path snapshot rather than a re-read of `baselinePaths[].path`, so a stateful `path` accessor is
+read exactly once and a passing result always describes the baseline identity that validated and
+bound the evidence.
+
+The whole-baseline identity `baseline.digest` follows the same discipline: it is read exactly
+once and that same scalar is validated, so a stateful value cannot be inspected as A while every
+evidence comparison uses B. The rename destination's own digest is also read exactly once during
+its validated snapshot, and the captured value drives the metadata cache, binding, the stale
+diagnostics, and the audit identity.
 
 Per-path evidence must be carried explicitly. Inherited properties in `baseline.artifacts` or a
 record's `baselineArtifacts` are not own-key evidence and never satisfy a path; the trusted
@@ -110,6 +116,11 @@ candidate digest — the same one used by ordinary candidate binding, the audit
 stale diagnostics. The destination is therefore never read again through the candidate map during
 capture or binding: a nested `digest` that throws or changes after validation cannot make a stale
 destination pair bind while the audit/stale verdicts still describe the captured value. The same
+read-once guarantee extends to rejected destination snapshots: when the destination's own digest
+read throws or returns an unusable value, that failed snapshot ('') is recorded and all later
+reads for that destination path are suppressed as well — the entry's single metadata read remains
+its only digest read, and the failed path contributes `path=missing` to `artifactDigest` instead
+of a later, different value. The same
 record can cover both endpoints. Destination-only evidence, source-only tombstones, split endpoint
 records, and stale destination digests do not satisfy the source. A deletion tombstone therefore
 cannot stand in for a known rename. This destination validation and the snapshot it produces are
@@ -129,14 +140,24 @@ obligations. `N/A` and `unknown` obligations never bind evidence and keep the le
 for their audit identity (so a candidate `get` that supplies a digest is still reflected there);
 they remain `outcome: 'none'` and do not emit `candidate-artifacts-invalid` from this applicability-gated check.
 
+When several `rename-from` entries declare one shared destination, the read-once promise is scoped
+**per declaring entry**: each entry's metadata validation reads the shared destination once (their
+agreement of validated values is what detects a contradictory shared-destination snapshot). A
+poisoned destination — one whose snapshot was rejected — is honored inside the metadata loop: a
+later declaring entry fails closed without reading the destination again, and the failed snapshot
+wins in the audit, overriding any previously validated successful snapshot that an earlier entry
+carried, rather than silently describing a value the getter shipped after the failure.
+
 A rename destination's validated own digest is carried too. When more than one accepted
 `rename-from` entry shares one `renameTo`, every entry's validated own digest must agree; a
 conflicting validated digest is a contradictory shared-destination snapshot and fails the whole
 obligation closed (metadata error, `outcome: 'none'`) before any binding. The carried digest must
 be a non-empty string: a stateful `digest` accessor whose value is not a usable string is not
-carried or seeded. Only **applicable** obligations validate and carry this destination snapshot;
-`N/A` and `unknown` obligations keep the legacy candidate read for their audit identity and do not
-consume the destination getter during metadata validation.
+carried or seeded — instead the destination path is recorded as a visited failure, and neither the
+capture loop nor the audit identity reads the destination again. Only **applicable** obligations
+validate and carry this destination snapshot; `N/A` and `unknown` obligations keep the legacy
+candidate read for their audit identity and do not consume the destination getter during metadata
+validation.
 
 The binding applies to execution and review records alike. Existing review approval, waiver,
 failing-command, requirement-sync authority, and applicability rules are unchanged. A correctly

package/docs/document-lifecycle.md

@@ -4,16 +4,68 @@ Contract for the documentation family: project docs configuration (D5), document
 
 Documentation is a **consumer** of the #320 workflow/obligation abstractions. Nothing here is a second router, a standing maintenance loop or a cognitive lock: every check is a pure function that reports diagnostics.
 
-## Scope of this slice
+## Scope of this slice (status as of 2026-10-20)
 
-| Phase | Status here |
+This table distinguishes merged mechanism code from end-to-end workflow integration. The last reviewed `main` commit is `29b1d65b398e2622af97bf067078373b7fa76b26` (v0.36.2). That release commit carries `[skip ci]` and only bumps package/distribution versions on top of `e5d22584e243d5b5e587ee0279625e97a9033160`, whose full-gate `CI` run [39374474269](https://github.com/dyphn1/Harness-everything/actions/runs/39374474269) completed with every job succeeded. The historical Windows System One resident teardown (`S1-RS15`) was observed in attempt 1 of [run 39175240370](https://github.com/dyphn1/Harness-everything/actions/runs/39175240370) on `main@75e04359ae5bf11a41739f8eb04d25a76ee8f3a7`; that run completed successfully on attempt 2 and says nothing about `29b1d65`. Treat the resident teardown as a known platform limitation only when a current run on the exact SHA reproduces it, and require an all-green full-gate run for that SHA before calling any baseline green.
+
+| Phase / prerequisite | Verified implementation and remaining work |
+| --- | --- |
+| 0 — contract + RED fixtures | Agreed decisions in this document, #325 and #327; fixtures under `ci/fixtures/doc-lifecycle/`; preserve earlier design history |
+| 1a — `project-docs.json` loader | **Merged** in #327; host-only malformed manifest protection remains a separate correction in #331 / draft PR #333 |
+| 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 | **Next implementation slice, not started; #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 |
+| 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)
+
+- **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.
+- **Advisory provider suggestions:** `suggestDocProviders({activeStep, neededCapabilities, availableProviderMetadata, hostCapabilities})` yields candidate providers and unavailable reasons without altering the MUST/SHOULD obligation set, granting tool access, or eagerly reading unrelated `SKILL.md`. Existing binding resolution handles an explicitly chosen provider. No new automatic step selection.
+- **Evidence reconciliation boundary and credit order:** the pilot wires Phase 3a results into the non-Fable typed-step path only. `hooks/scripts/workflow-disposition.js` delegates `step` to `updateStep()` and `binding` to `updateBinding()` in `hooks/scripts/lib/workflow-obligations.js`. Today `updateStep()` persists `step.status = 'pass'` when every required binding is `loaded` and `--evidence` is non-empty; `syncTypedAggregateObligations()` then derives aggregate `execute`/`verify` PASS from the persisted step statuses. An authored `doc-change` step is authored work, not verification: it may advance under its existing binding contract **without claiming** any doc MUST as verified. The doc-MUST reconciliation gate belongs at the authorized `verification` step and the final-completion boundary, matching D6.6 ("All events are checked at the existing workflow's `verification` step"). Phase 3b must evaluate `checkDocObligations()` for the active scope before aggregate `verify` PASS is persisted and before the workflow reports completion; an aggregate `execute` may still reflect authored step passes, but neither aggregate may stand as completion while an applicable doc MUST is unsatisfied, and `unresolvedObligations()` must surface the unsatisfied results (`pending`/`unknown`/`unavailable`/`failed`). Ordered `doc-change → review → verification` topologies stay reachable: evidence supplied by the later `review`/`verification` steps counts at its own stage, so no stage is forced to pass early and a normative doc change cannot deadlock. Non-document steps, persisted plans, existing bindings and authorization stay unchanged.
+- **Typed aggregate writes and freshness (doc-governed scope):** aggregate PASS is not derived exclusively from persisted step passes today. `updateObligation()` accepts a direct `obligation --obligation-id execute|verify --disposition pass --evidence <text>` write for **all** non-Fable typed plans, including workflows with no applicable document MUSTs. Phase 3b's guard is scoped to typed plans/steps with an applicable, doc-governed scope: there, a direct typed `execute`/`verify` PASS must be rejected or ignored unless it was derived/reconciled from satisfied doc evidence, and the `obligation` command joins `step` in the negative tests. Non-document typed workflows and persisted plans retain today's behavior unless a separately authorized compatibility decision changes them; an already-persisted plan that gains a doc-governed scope is validated against that scope and cannot complete on a stale direct aggregate PASS. Verified doc evidence must also stay bound to the persisted candidate, task and config identity: `unresolvedObligations()` and the final completion path re-check freshness, so evidence that was valid before a later candidate edit cannot remain a completion proof solely because `status: pass` was persisted.
+- **Minimum trusted producer (3b deliverable):** Phase 3b ships the pilot-local adapter that derives the VCS baseline and candidate identity, active task scope, parsed config bytes (`configDigest` bound rather than presence-checked), PRD root, execution/verification provenance and independent reviewer identity from host state (see *Phase 3b minimum trust boundary* below). `checkDocObligations()` only proves agreement with caller-supplied values; without this producer, a 3b PASS would promote caller-attested claims. Any input the producer cannot establish stays `unknown`/`unavailable` and MUST NOT pass. Phase 3c broadens adversarial H3 validation and adds paired architectural evaluation; it does not supply the minimum producer.
+- **Pilot topology and unsupported paths:** the pilot is limited to non-Fable typed-step workflows (`stepBindingsEnabled === true`, set when typed steps exist and the strategy is not `fable-*`). Fable stage-contract paths (`fable-staged`, `fable-parallel`, `fable-multi-agent-workspace`) and workflows without the typed-step contract are explicitly **not integrated / unavailable** for doc-MUST reconciliation: a `stage-binding` disposition is never doc verification, and no fallback may mark a doc MUST satisfied. Unsupported paths report that state rather than silently passing.
+- **Negative acceptance case:** for a doc-governed typed plan whose applicable MUST is failing or unknown, no boundary may report PASS: `step --disposition pass` on the verification step, `obligation --obligation-id execute|verify --disposition pass --evidence 'done'`, and final completion must all fail closed, report the unsatisfied obligation ids, and leave aggregate `verify` pending. A loaded skill plus free-text evidence is not verification. A RED fixture covers ordered `doc-change → review → verification` with reviewer/command evidence missing first and valid later: the authored `doc-change` step advances, aggregate/final PASS stays blocked until the later evidence satisfies the MUST, and neither a premature PASS nor a deadlock occurs.
+- **Compatibility:** preserve existing non-document step bindings, authorization/Rule-of-3 semantics, old persisted plans and no new Stop/tool lock. Source and installed plugin copies must behave consistently.
+- **Pre-integration work:** the baseline-bound tombstone/rename-pair evidence required by #335 shipped in #342; the remaining pre-integration work is the reconciliation contract above. #331 / draft PR #333 is a parallel host-config safety correction; neither requires the broad #320 migration.
+
+### Phase 3c — architecture promotion gate for #320 (planned, not shipped)
+
+| Hypothesis | Objective acceptance evidence |
+| --- | --- |
+| **H1 Provider independence** | Swap/omit suggestions without changing workflow obligations; valid alternate execution evidence can satisfy an applicable MUST; no evidence cannot |
+| **H2 Active-step progressive disclosure** | Captured step output / provider metadata access shows only active-step relevance and no eager unrelated `SKILL.md` content or future-step loading |
+| **H3 Evidence reconciliation** | Adversarial replay of fabricated completion, missing verifier, stale digest/base, scope substitution, forged identity, unsupported PRD roots, contradictory/failed results and unsupported waiver yields **zero false PASS** for MUSTs, with the fixture matrix below as the observable trust boundary |
+| **H4 Task-shaped composition** | Docs-only, docs+code, REQ-citing assertions, typo-only changes, code-only uncertainty, missing independent approval and waivers produce the expected obligation union and explicit unknown/unavailable outcomes |
+
+### Phase 3b minimum trust boundary and Phase 3c H3 validation (planned, not shipped)
+
+Phase 3b delivers the minimum producer and identity/scope binding needed for a trustworthy PASS; Phase 3c extends the same seam with adversarial H3 validation and paired architectural evaluation.
+
+- **Trusted producer, not the checker:** a pilot-local adapter is a **3b deliverable**; it derives the VCS baseline and candidate identity, active task scope, project-docs config identity (parsed config bytes, not presence) and execution/review provenance from host state. `checkDocObligations()` proves only that records agree with those caller-supplied values; matching a caller-provided digest is not independent validation of the input.
+- **Identity and scope requirements:** `baseline.digest` and `baseline.artifacts[path]` come from the same recorded baseline tree; candidate artifact digests come from the candidate tree actually under review; `configDigest` is bound to the parsed config bytes rather than checked for presence; the obligation's PRD root and active task scope must match the adapter's scope, and an unsupported custom PRD root is `unavailable`.
+- **Provenance and reviewer identity:** execution and verification records need the command, non-empty provenance and integer exit code; review approval needs an independent reviewer identity distinct from the executor/author. A free-text claim, self-review, missing verifier or replayed record never satisfies a MUST.
+- **Dispositions:** absent, untrusted, stale, replayed, contradictory, malformed or unsupported inputs resolve to `unknown`/`unavailable`/failed, never PASS. The 3b fail-closed negative cases cover missing producer identity, scope substitution, unbound config bytes and stale candidate evidence; 3c adds the full adversarial fixture matrix below.
+
+| H3 fixture | Expected disposition |
 | --- | --- |
-| 0 — contract + RED fixtures | This file; fixtures under `ci/fixtures/doc-lifecycle/` |
-| 1a — `project-docs.json` loader | `multi-agent-workspace/scripts/project-docs-resolver.js` |
-| 2 — roles, IDs, aliases, legacy, supersession, index, D6.9 PRD revisions | `harness-everything/scripts/doc-lifecycle.js` |
-| 3a — `doc-change` / `requirement-sync` pure derivation and evidence producer | `harness-everything/scripts/doc-obligations.js` (facts and obligations), `harness-everything/scripts/doc-evidence.js` (`checkDocObligations`). Pilot-local: not wired into workflow disposition yet. H3 and H4 have deterministic tests; H1 and H2 are deferred to 3c. Known limits: the attested-envelope fields are caller-asserted (`configDigest` is checked for presence only, not against the parsed config); `candidateDigest` covers only `docs/prd/`, so custom PRD roots and task-scope binding are not yet verified; deleted and old rename paths are bound to trusted per-path baseline evidence ([doc-evidence-baseline-binding.md](doc-evidence-baseline-binding.md), #335), with reconciliation left out of scope |
-| 1b, 3b–3c (provider suggestions, reconciliation, H1–H2 evaluation) | Not started: blocked by #320 family metadata, D1 obligation schema and D3 evidence states. Deleted and old rename paths now use trusted baseline-bound evidence (#335); reconciliation with workflow disposition remains open |
-| 4 — derived-view generators, `describes:` drift | Not started |
+| Fabricated completion claim / no record | `unknown`; MUST unsatisfied |
+| Forged baseline or candidate digest | rejected as stale/unknown; MUST unsatisfied |
+| Scope substitution across tasks or PRD roots | `unknown`; MUST unsatisfied |
+| Unsupported custom PRD root | `unavailable`; MUST unsatisfied |
+| Replayed earlier-candidate record | stale; MUST unsatisfied |
+| Missing, non-independent or mismatched reviewer identity | MUST unsatisfied |
+| Unsupported waiver (no reason, no cited observed record, or self-bound scope) | `unsupported-waiver`; MUST unsatisfied |
+| Contradictory or failed command results | failed; not PASS |
+| Positive control: current, independently produced matching evidence | pass |
+
+Two *separate* gates apply. The **functional gate** requires contract tests, negative cases, source/package parity, host/platform compatibility and an all-green applicable CI baseline. The **architectural gate** additionally requires H1–H4 and independently reviewed paired real-task outcomes. Freeze task fixtures, acceptance rubrics, model/effort, host permissions, comparison order and thresholds **after baseline measurement but before treatment outcomes**. Compare task correctness and failures first; report successful-task token/time/tool cost and failed-run overhead separately, with uncertainty. A small inconclusive sample is not approval. Broader #320 CDG/registry compilation and physical skill moves need **explicit owner sign-off on each specific validated interface**; retain the legacy path until then.
+
+**Cross-contract acceptance assertion:** the #341 E0/E1 gates in the Phase 3b entry-gates bullet above, [#341](https://github.com/dyphn1/Harness-everything/issues/341) and #325's phase table must stay mutually consistent: a change to one gate's semantics updates the other two records, replays affected #341 fixtures first, and only then re-collects affected 3b observations. E0 enables only the bounded, reversible, doc-only runtime consumer; E1 gates expansion beyond the limited pilot; neither approves generic #320 CDG/registry promotion, which additionally requires the H1–H4 paired real-task evidence and explicit owner sign-off above.
 
 ## Configuration (D5)
 

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.36.1
+  version: 0.36.3
 ---
 
 # Harness Everything