@hecer/yoke 1.21.1 → 1.23.0

package/dist/loop/loop.js

@@ -1,9 +1,13 @@
+import { cacheIsolationProblem } from './cache-isolation.js';
+import { retainRuntimeProof } from './proof-retention.js';
 import { knownInfrastructureFailure } from "../routing/capability.js";
 import { existsSync, unlinkSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { acceptanceProtectionProblem } from '../check/command.js';
 import { join, relative } from 'node:path';
 import { isAcceptanceCriterion, loadPrd, savePrd, selectNextStory, allPass, progress, storyPathSegment } from './prd.js';
 import { stopTheLineGate, preDispatchGate } from './gates.js';
+import { observeFailure, clearFailureProgress } from './failure.js';
+import { gateIdentity, snapshotGates, reuseGates } from './gate-snapshot.js';
 import { appendDecision, contextDir } from '../context/context.js';
 import { noopReporter } from './reporter.js';
 import { consumeDecisionRequest } from './decision.js';
@@ -68,7 +72,8 @@ function runQualityReview(opts, executionDir, story, reporter) {
         }
         return { kind: 'passed' };
     };
-    return runQualityRepairLoop({
+    let failure;
+    const outcome = runQualityRepairLoop({
         quality: qualityAssessment
             ? round => {
                 reporter.phase('comparing');
@@ -85,7 +90,13 @@ function runQualityReview(opts, executionDir, story, reporter) {
             reporter.phase('repairing');
             if (!opts.repair)
                 return { kind: 'blocked', summary: 'repair callback is not configured' };
-            const result = opts.repair({ targetDir: executionDir, story }, request);
+            const observed = observeFailure({ root: opts.targetDir, directory: executionDir, story, stage: 'quality', summary: JSON.stringify(request.finding) });
+            if (observed.action === 'blocked') {
+                failure = observed.failure;
+                return { kind: 'blocked', summary: observed.feedback };
+            }
+            const targetedRequest = observed.action === 'diagnose' ? { ...request, finding: { ...request.finding, message: observed.feedback } } : request;
+            const result = opts.repair({ targetDir: executionDir, story }, targetedRequest);
             return result.success ? { kind: 'repaired' } : { kind: 'blocked', summary: result.summary };
         },
         rerunGates,
@@ -96,6 +107,7 @@ function runQualityReview(opts, executionDir, story, reporter) {
                 reporter.quality({ ...status, ...qualityMetadata });
         },
     });
+    return { ...outcome, ...(failure ? { failure } : {}) };
 }
 // Control file a supervisor drops to pause the loop at the next story boundary.
 // The loop consumes (deletes) it and stops with state 'paused' — never mid-story.
@@ -146,7 +158,7 @@ function runGate(gate, dir, storyId) {
             process.env.YOKE_STORY = prev;
     }
 }
-function consumeAmbiguity(dir) {
+export function consumeAmbiguity(dir) {
     const file = ambiguityFilePath(dir);
     if (!existsSync(file))
         return null;
@@ -167,14 +179,16 @@ function runCompletionGate(opts, stories) {
         return null;
     const previous = process.env.YOKE_PHASE;
     process.env.YOKE_PHASE = 'completion';
-    let verdict;
+    let reason;
     try {
-        verdict = opts.completion(opts.targetDir);
+        const verdict = opts.completion(opts.targetDir);
+        if (!verdict.passed)
+            reason = `integrated system did not verify: ${verdict.summary}`;
+        else if (!opts.git.isClean(opts.targetDir))
+            reason = 'completion command left source or final assets dirty; preserve changes and move rerun proofs to ignored runtime paths before resuming';
     }
     catch (error) {
-        const reason = `integrated completion gate failed: ${error.message}`;
-        (opts.reporter ?? noopReporter).blocked(reason);
-        return { status: 'blocked', iterations: 0, reason, finalProgress: progress(stories) };
+        reason = `integrated completion gate failed: ${error.message}`;
     }
     finally {
         if (previous === undefined)
@@ -182,13 +196,20 @@ function runCompletionGate(opts, stories) {
         else
             process.env.YOKE_PHASE = previous;
     }
-    if (verdict.passed)
+    if (!reason) {
+        clearFailureProgress(opts.targetDir);
         return null;
-    const reason = `integrated system did not verify: ${verdict.summary}`;
-    (opts.reporter ?? noopReporter).blocked(reason);
-    return { status: 'blocked', iterations: 0, reason, finalProgress: progress(stories) };
+    }
+    const observed = observeFailure({ root: opts.targetDir, directory: opts.targetDir, stage: 'completion', summary: reason });
+    if (observed.action !== 'retry')
+        reason = observed.feedback;
+    (opts.reporter ?? noopReporter).blocked(reason, observed.failure);
+    return { status: 'blocked', iterations: 0, reason, failure: observed.failure, finalProgress: progress(stories) };
 }
 function runCriterionGates(opts, executionDir, story) {
+    const cacheProblem = opts.isolate && executionDir !== opts.targetDir ? cacheIsolationProblem(executionDir) : undefined;
+    if (cacheProblem)
+        return { passed: false, summary: cacheProblem };
     const protectionProblem = acceptanceProtectionProblem(executionDir, opts.targetDir);
     if (protectionProblem)
         return { passed: false, summary: protectionProblem };
@@ -200,10 +221,10 @@ function runCriterionGates(opts, executionDir, story) {
     }
     if (!opts.verifyCriterion)
         return { passed: false, summary: `story ${story.id} has criteria but no criterion verifier` };
-    const evidence = criteria.map(criterion => ({
-        criterion,
-        result: opts.verifyCriterion(executionDir, story, criterion),
-    }));
+    const evidence = criteria.map(criterion => {
+        const problem = opts.isolate && executionDir !== opts.targetDir ? cacheIsolationProblem(executionDir) : undefined;
+        return { criterion, result: problem ? { passed: false, summary: problem } : opts.verifyCriterion(executionDir, story, criterion) };
+    });
     try {
         writeCriterionEvidence(opts.targetDir, story, evidence);
     }
@@ -216,6 +237,15 @@ function runCriterionGates(opts, executionDir, story) {
         : { passed: true, summary: `${evidence.length} acceptance criteria verified` };
 }
 export function runLoop(opts) {
+    if (opts.isolate)
+        for (const name of ['verify', 'design', 'perf', 'audit']) {
+            const gate = opts[name];
+            if (gate)
+                opts = { ...opts, [name]: (dir) => {
+                        const problem = dir !== opts.targetDir ? cacheIsolationProblem(dir) : undefined;
+                        return problem ? { passed: false, summary: problem } : gate(dir);
+                    } };
+        }
     let iterations = 0;
     const reporter = opts.reporter ?? noopReporter;
     for (;;) {
@@ -313,86 +343,88 @@ export function runLoop(opts) {
             const wt = join(opts.targetDir, '.yoke', 'worktrees', storyPathSegment(story.id));
             const wtPrd = join(wt, relative(opts.targetDir, opts.prdPath));
             let landed = null;
+            let activeRouting;
             try {
                 opts.git.addWorktree(opts.targetDir, wt);
-                const result = runImplementation(opts, wt, story, reporter);
+                const implementation = runImplementation(opts, wt, story, reporter);
+                const result = implementation.result;
+                activeRouting = result.routing;
                 iterations++;
                 if (result.tokens)
                     reporter.addTokens(result.tokens);
                 if (result.infrastructureFailure || result.routing?.blocked) {
                     if (result.infrastructureFailure)
                         result.routing?.recordOutcome(false, "infrastructure");
-                    reporter.blocked(result.summary);
-                    return { status: "blocked", iterations, reason: result.summary, finalProgress: progress(stories) };
+                    reporter.blocked(result.summary, implementation.failure);
+                    return { status: "blocked", iterations, reason: result.summary, ...(implementation.failure ? { failure: implementation.failure } : {}), finalProgress: progress(stories) };
                 }
                 let decision;
                 try {
                     decision = consumeDecisionRequest(wt, opts.targetDir, story.id);
                 }
                 catch (error) {
+                    result.routing?.recordOutcome(false, 'infrastructure');
                     const reason = `invalid critical decision request for story ${story.id}: ${error.message}`;
                     reporter.blocked(reason);
                     return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
                 }
                 if (decision) {
+                    result.routing?.recordOutcome(false, 'infrastructure');
                     const reason = `critical decision required for story ${story.id}: ${decision.question}`;
                     reporter.blocked(reason);
                     return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
                 }
                 const ambiguity = consumeAmbiguity(wt);
                 if (ambiguity) {
+                    result.routing?.recordOutcome(false, 'infrastructure');
                     const reason = `story ${story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`;
                     reporter.blocked(reason);
                     return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
                 }
-                const criteriaVerdict = runCriterionGates(opts, wt, story);
+                const verified = reuseGates(wt, story, implementation.gates);
+                const criteriaVerdict = verified?.criteria ?? runCriterionGates(opts, wt, story);
                 if (!criteriaVerdict.passed) {
                     result.routing?.recordOutcome(false);
                     const reason = blockReason(`story ${story.id} lacks acceptance evidence: ${criteriaVerdict.summary}`, opts.targetDir, opts.git);
-                    reporter.blocked(reason);
-                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                    return blockedMechanicalGate(opts, wt, story, 'criterion', criteriaVerdict.summary, reason, iterations, stories);
                 }
                 // Verify is the source of truth — NOT the runner's exit code. A spurious non-zero
                 // exit (e.g. a Windows .cmd wrapper ghost) must not block a story whose tests are green.
                 reporter.phase('verifying');
-                const verdict = runGate(opts.verify, wt, story.id);
+                const verdict = verified?.verify ?? runGate(opts.verify, wt, story.id);
                 if (!verdict.passed) {
                     result.routing?.recordOutcome(false);
                     const base = result.success
                         ? `story ${story.id} did not verify: ${verdict.summary}`
                         : `story ${story.id} runner failed (${result.summary}) and verify is red: ${verdict.summary}`;
                     const reason = blockReason(base, opts.targetDir, opts.git);
-                    reporter.blocked(reason);
-                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                    return blockedMechanicalGate(opts, wt, story, 'verify', verdict.summary, reason, iterations, stories);
                 }
                 if (opts.design) {
                     reporter.phase('design');
-                    const designVerdict = runGate(opts.design, wt, story.id);
+                    const designVerdict = verified?.design ?? runGate(opts.design, wt, story.id);
                     if (!designVerdict.passed) {
                         result.routing?.recordOutcome(false);
                         const reason = blockReason(`story ${story.id} failed its design gate: ${designVerdict.summary}`, opts.targetDir, opts.git);
-                        reporter.blocked(reason);
-                        return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                        return blockedMechanicalGate(opts, wt, story, 'design', designVerdict.summary, reason, iterations, stories);
                     }
                 }
                 if (opts.perf) {
                     reporter.phase('perf');
-                    const perfVerdict = runGate(opts.perf, wt, story.id);
+                    const perfVerdict = verified?.perf ?? runGate(opts.perf, wt, story.id);
                     if (!perfVerdict.passed) {
                         result.routing?.recordOutcome(false);
                         const reason = blockReason(`story ${story.id} exceeded its performance budget: ${perfVerdict.summary}`, opts.targetDir, opts.git);
-                        reporter.blocked(reason);
-                        return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                        return blockedMechanicalGate(opts, wt, story, 'perf', perfVerdict.summary, reason, iterations, stories);
                     }
                 }
                 if (opts.audit) {
                     reporter.phase('audit');
-                    const auditVerdict = runGate(opts.audit, wt, story.id);
+                    const auditVerdict = verified?.audit ?? runGate(opts.audit, wt, story.id);
                     if (!auditVerdict.passed) {
                         result.routing?.recordOutcome(false);
                         const reason = blockReason(`story ${story.id} failed security audit: ${auditVerdict.summary}`, opts.targetDir, opts.git);
-                        reporter.blocked(reason);
-                        return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                        return blockedMechanicalGate(opts, wt, story, 'audit', auditVerdict.summary, reason, iterations, stories);
                     }
                 }
                 const summary = result.success
@@ -401,14 +433,15 @@ export function runLoop(opts) {
                 const repairOutcome = runQualityReview(opts, wt, story, reporter);
                 if (repairOutcome) {
                     if (repairOutcome.kind === 'paused') {
+                        result.routing?.recordOutcome(false, 'infrastructure');
                         reporter.paused(progress(stories));
                         return { status: 'paused', iterations, finalProgress: progress(stories) };
                     }
                     const reason = repairBlockReason(repairOutcome, story, opts.targetDir, opts.git);
                     if (reason) {
                         result.routing?.recordOutcome(false);
-                        reporter.blocked(reason);
-                        return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                        reporter.blocked(reason, repairOutcome.failure);
+                        return { status: 'blocked', iterations, reason, ...(repairOutcome.failure ? { failure: repairOutcome.failure } : {}), finalProgress: progress(stories) };
                     }
                 }
                 const protection = acceptanceProtectionProblem(wt, opts.targetDir);
@@ -428,12 +461,15 @@ export function runLoop(opts) {
                 });
                 const updated = stories.map(s => (s.id === story.id ? { ...s, passes: true } : s));
                 savePrd(wtPrd, updated);
+                retainRuntimeProof(wt, story.id, opts.targetDir);
                 opts.git.commitAll(wt, `yoke: complete ${story.id} ${story.title}`, opts.commitIdentity);
                 opts.git.integrate(opts.targetDir, wt);
                 result.routing?.recordOutcome(true);
+                clearFailureProgress(opts.targetDir, story.id);
                 landed = progress(updated);
             }
             catch (e) {
+                activeRouting?.recordOutcome(false, 'infrastructure');
                 const reason = blockReason(`isolated iteration failed for ${story.id}: ${e.message}`, opts.targetDir, opts.git);
                 reporter.blocked(reason);
                 return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
@@ -452,89 +488,84 @@ export function runLoop(opts) {
                 reporter.storyDone({ id: story.id, title: story.title }, landed);
             continue;
         }
-        const result = runImplementation(opts, opts.targetDir, story, reporter);
+        const implementation = runImplementation(opts, opts.targetDir, story, reporter);
+        const result = implementation.result;
         iterations++;
         if (result.tokens)
             reporter.addTokens(result.tokens);
         if (result.infrastructureFailure || result.routing?.blocked) {
             if (result.infrastructureFailure)
                 result.routing?.recordOutcome(false, "infrastructure");
-            reporter.blocked(result.summary);
-            return { status: "blocked", iterations, reason: result.summary, finalProgress: progress(stories) };
+            reporter.blocked(result.summary, implementation.failure);
+            return { status: "blocked", iterations, reason: result.summary, ...(implementation.failure ? { failure: implementation.failure } : {}), finalProgress: progress(stories) };
         }
         let decision;
         try {
             decision = consumeDecisionRequest(opts.targetDir, opts.targetDir, story.id);
         }
         catch (error) {
+            result.routing?.recordOutcome(false, 'infrastructure');
             const reason = `invalid critical decision request for story ${story.id}: ${error.message}`;
             reporter.blocked(reason);
             return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
         }
         if (decision) {
+            result.routing?.recordOutcome(false, 'infrastructure');
             const reason = `critical decision required for story ${story.id}: ${decision.question}`;
             reporter.blocked(reason);
             return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
         }
         const ambiguity = consumeAmbiguity(opts.targetDir);
         if (ambiguity) {
+            result.routing?.recordOutcome(false, 'infrastructure');
             const reason = `story ${story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`;
             reporter.blocked(reason);
             return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
         }
-        const criteriaVerdict = runCriterionGates(opts, opts.targetDir, story);
+        const verified = reuseGates(opts.targetDir, story, implementation.gates);
+        const criteriaVerdict = verified?.criteria ?? runCriterionGates(opts, opts.targetDir, story);
         if (!criteriaVerdict.passed) {
             result.routing?.recordOutcome(false);
             const reason = blockReason(`story ${story.id} lacks acceptance evidence: ${criteriaVerdict.summary}`, opts.targetDir, opts.git);
-            reporter.blocked(reason);
-            return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+            return blockedMechanicalGate(opts, opts.targetDir, story, 'criterion', criteriaVerdict.summary, reason, iterations, stories);
         }
         // Verify is the source of truth — NOT the runner's exit code. A spurious non-zero
         // exit (e.g. a Windows .cmd wrapper ghost) must not block a story whose tests are green.
         reporter.phase('verifying');
-        const verdict = runGate(opts.verify, opts.targetDir, story.id);
+        const verdict = verified?.verify ?? runGate(opts.verify, opts.targetDir, story.id);
         if (!verdict.passed) {
             result.routing?.recordOutcome(false);
             const base = result.success
                 ? `story ${story.id} did not verify: ${verdict.summary}`
                 : `story ${story.id} runner failed (${result.summary}) and verify is red: ${verdict.summary}`;
             const reason = blockReason(base, opts.targetDir, opts.git);
-            reporter.blocked(reason);
-            return {
-                status: 'blocked',
-                iterations,
-                reason,
-                finalProgress: progress(stories),
-            };
+            return blockedMechanicalGate(opts, opts.targetDir, story, 'verify', verdict.summary, reason, iterations, stories);
         }
         if (opts.design) {
             reporter.phase('design');
-            const designVerdict = runGate(opts.design, opts.targetDir, story.id);
+            const designVerdict = verified?.design ?? runGate(opts.design, opts.targetDir, story.id);
             if (!designVerdict.passed) {
                 result.routing?.recordOutcome(false);
                 const reason = blockReason(`story ${story.id} failed its design gate: ${designVerdict.summary}`, opts.targetDir, opts.git);
-                reporter.blocked(reason);
-                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                return blockedMechanicalGate(opts, opts.targetDir, story, 'design', designVerdict.summary, reason, iterations, stories);
             }
         }
         if (opts.perf) {
             reporter.phase('perf');
-            const perfVerdict = runGate(opts.perf, opts.targetDir, story.id);
+            const perfVerdict = verified?.perf ?? runGate(opts.perf, opts.targetDir, story.id);
             if (!perfVerdict.passed) {
                 result.routing?.recordOutcome(false);
                 const reason = blockReason(`story ${story.id} exceeded its performance budget: ${perfVerdict.summary}`, opts.targetDir, opts.git);
-                reporter.blocked(reason);
-                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                return blockedMechanicalGate(opts, opts.targetDir, story, 'perf', perfVerdict.summary, reason, iterations, stories);
             }
         }
         if (opts.audit) {
             reporter.phase('audit');
-            const auditVerdict = runGate(opts.audit, opts.targetDir, story.id);
+            const auditVerdict = verified?.audit ?? runGate(opts.audit, opts.targetDir, story.id);
             if (!auditVerdict.passed) {
                 result.routing?.recordOutcome(false);
                 const reason = blockReason(`story ${story.id} failed security audit: ${auditVerdict.summary}`, opts.targetDir, opts.git);
-                reporter.blocked(reason);
-                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                return blockedMechanicalGate(opts, opts.targetDir, story, 'audit', auditVerdict.summary, reason, iterations, stories);
             }
         }
         const summary = result.success
@@ -543,17 +574,19 @@ export function runLoop(opts) {
         const repairOutcome = runQualityReview(opts, opts.targetDir, story, reporter);
         if (repairOutcome) {
             if (repairOutcome.kind === 'paused') {
+                result.routing?.recordOutcome(false, 'infrastructure');
                 reporter.paused(progress(stories));
                 return { status: 'paused', iterations, finalProgress: progress(stories) };
             }
             const reason = repairBlockReason(repairOutcome, story, opts.targetDir, opts.git);
             if (reason) {
                 result.routing?.recordOutcome(false);
-                reporter.blocked(reason);
+                reporter.blocked(reason, repairOutcome.failure);
                 return {
                     status: 'blocked',
                     iterations,
                     reason,
+                    ...(repairOutcome.failure ? { failure: repairOutcome.failure } : {}),
                     finalProgress: progress(stories),
                 };
             }
@@ -564,7 +597,6 @@ export function runLoop(opts) {
             reporter.blocked(protection);
             return { status: 'blocked', iterations, reason: protection, finalProgress: progress(stories) };
         }
-        result.routing?.recordOutcome(true);
         reporter.phase('committing');
         const dec = appendDecision(contextDir(opts.targetDir), {
             storyId: story.id,
@@ -581,6 +613,7 @@ export function runLoop(opts) {
             opts.git.commitAll(opts.targetDir, `yoke: complete ${story.id} ${story.title}`, opts.commitIdentity);
         }
         catch (e) {
+            result.routing?.recordOutcome(false, 'infrastructure');
             savePrd(opts.prdPath, onDisk); // revert — never persist passes:true without a commit
             dec.rollback(); // and never leave an orphan decision
             const reason = blockReason(`commit failed for ${story.id}: ${e.message}`, opts.targetDir, opts.git);
@@ -592,38 +625,59 @@ export function runLoop(opts) {
                 finalProgress: progress(stories),
             };
         }
+        result.routing?.recordOutcome(true);
+        clearFailureProgress(opts.targetDir, story.id);
         reporter.storyDone({ id: story.id, title: story.title }, progress(updated));
     }
 }
+function blockedMechanicalGate(opts, directory, story, stage, summary, reason, iterations, stories) {
+    const observed = observeFailure({ root: opts.targetDir, directory, story, stage, summary });
+    const detail = observed.action === 'retry' ? reason : `${reason}\n${observed.feedback}`;
+    (opts.reporter ?? noopReporter).blocked(detail, observed.failure);
+    return { status: 'blocked', iterations, reason: detail, failure: observed.failure, finalProgress: progress(stories) };
+}
 function runImplementation(opts, dir, story, reporter) {
-    let feedback;
+    let feedback = opts.feedback;
     for (let attempt = 0;; attempt++) {
         const result = opts.runner({ targetDir: dir, story, feedback });
+        const cacheProblem = opts.isolate && dir !== opts.targetDir ? cacheIsolationProblem(dir) : undefined;
+        if (cacheProblem)
+            return { result: { ...result, success: false, infrastructureFailure: true, summary: cacheProblem } };
         if (!result.routing?.canRetry || result.routing.blocked || attempt >= 7)
-            return result;
+            return { result };
         if (["decision-request.yaml", "ambiguity.md", "loop.pause"].some(name => existsSync(join(dir, ".yoke", name))) || existsSync(pauseFilePath(opts.targetDir)))
-            return result;
+            return { result };
         const protection = acceptanceProtectionProblem(dir, opts.targetDir);
         if (protection)
-            return result;
+            return { result };
+        const before = gateIdentity(dir, story);
         const criteria = runCriterionGates(opts, dir, story);
-        const gates = [opts.verify, opts.design, opts.perf, opts.audit].filter((gate) => Boolean(gate));
+        const evidence = { criteria };
         let verdict = criteria;
+        let failedStage = 'criterion';
         if (verdict.passed)
-            for (const gate of gates) {
+            for (const name of ['verify', 'design', 'perf', 'audit']) {
+                const gate = opts[name];
+                if (!gate)
+                    continue;
                 verdict = runGate(gate, dir, story.id);
+                failedStage = name;
+                evidence[name] = verdict;
                 if (!verdict.passed)
                     break;
             }
         if (verdict.passed)
-            return result;
+            return { result, gates: snapshotGates(dir, story, before, evidence) };
         if (knownInfrastructureFailure(verdict.summary)) {
             result.routing.recordOutcome(false, 'infrastructure');
-            return { ...result, success: false, infrastructureFailure: true, summary: verdict.summary, routing: { ...result.routing, blocked: true, canRetry: false } };
+            return { result: { ...result, success: false, infrastructureFailure: true, summary: verdict.summary, routing: { ...result.routing, blocked: true, canRetry: false } } };
         }
         result.routing.recordOutcome(false);
+        const observed = observeFailure({ root: opts.targetDir, directory: dir, story, stage: failedStage, summary: verdict.summary });
+        if (observed.action === 'blocked')
+            return { result: { ...result, success: false, summary: observed.feedback, routing: { ...result.routing, blocked: true, canRetry: false } }, failure: observed.failure };
         if (result.tokens)
             reporter.addTokens(result.tokens);
-        feedback = verdict.summary;
+        feedback = observed.feedback;
     }
 }

package/dist/loop/parallel-adapters.js

@@ -3,11 +3,14 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { isProviderTreeAlive, reapProviderProcesses } from './cleanup.js';
-import { realGitOps, stageImplementation } from './git.js';
+import { realGitOps, stageImplementation, RUNTIME_EXCLUDES } from './git.js';
 import { isPidAlive } from './lock.js';
 import { storyPathSegment } from './prd.js';
 import { killProcessTreeForCleanup } from './watchdog.js';
 import { parallelAcceptanceDigest, recoverParallelWorktree, retainParallelWorktree } from './recovery.js';
+import { cacheIsolationProblem } from './cache-isolation.js';
+import { retainRuntimeProof } from './proof-retention.js';
+import { writeScopesOverlap } from './scheduler.js';
 import { statePath } from '../workspace/state.js';
 export function makeParallelAdapters(targetDir, identity, injectedGit) {
     return injectedGit
@@ -62,11 +65,11 @@ function productionAdapters(targetDir, identity) {
                 return { path, baseCommit };
             },
             cleanupProcess: cleanupProviderProcesses,
-            retain: (input, reason) => {
+            retain: (input, reason, phase = 'integration') => {
                 const file = recoveryPath(targetDir, input.story.id);
                 // Preserve the path's original ownership identity when a retry is rejected again.
                 const ownerToken = ownershipTokens.get(input.worktree.path) ?? input.ownerToken;
-                retainParallelWorktree(targetDir, file, { storyId: input.story.id, worktree: input.worktree.path, baseCommit: input.worktree.baseCommit, prdHash: acceptanceDigests.get(input.story.id), ownerToken, reason });
+                retainParallelWorktree(targetDir, file, { storyId: input.story.id, worktree: input.worktree.path, baseCommit: input.worktree.baseCommit, prdHash: acceptanceDigests.get(input.story.id), ownerToken, reason, phase });
             },
             remove: input => {
                 removeOwnedWorktree(targetDir, input, owned, removed, realGitOps);
@@ -78,16 +81,23 @@ function productionAdapters(targetDir, identity) {
         git: {
             isClean: dir => realGitOps.isClean(dir),
             rebase: input => rebaseCandidate(targetDir, input),
-            commit: input => realGitOps.commitAll(input.worktree.path, `yoke: complete ${input.story.id} ${input.story.title}`, identity),
+            commit: input => {
+                const unexpected = unexpectedWrites(input, changedPaths(input.worktree.path, gitText(input.worktree.path, ['rev-parse', 'HEAD'])));
+                if (unexpected.length)
+                    throw new Error(`Candidate writes outside declared scopes after integrated gates: ${unexpected.join(', ')}`);
+                retainRuntimeProof(input.worktree.path, input.story.id, targetDir);
+                realGitOps.commitAll(input.worktree.path, `yoke: complete ${input.story.id} ${input.story.title}`, identity);
+            },
             integrate: (input, expectedHead) => integrateCandidate(targetDir, input, expectedHead),
         },
-        candidates: primary => makeCandidateLifecycle(targetDir, primary, owned, removed, realGitOps, ownershipTokens),
+        candidates: primary => makeCandidateLifecycle(targetDir, primary, owned, removed, realGitOps, ownershipTokens, acceptanceDigests.get(primary.story.id)),
     };
 }
 function cleanupProviderProcesses(input) {
     reapProviderProcesses(input.worktree.path, isPidAlive, isProviderTreeAlive, killProcessTreeForCleanup);
 }
-function makeCandidateLifecycle(targetDir, primary, owned, removed, git, ownershipTokens) {
+function makeCandidateLifecycle(targetDir, primary, owned, removed, git, ownershipTokens, acceptanceDigest) {
+    const retainedRecords = new Map();
     return {
         reserve: input => {
             const worktree = input.candidateId === 'candidate-1'
@@ -114,6 +124,23 @@ function makeCandidateLifecycle(targetDir, primary, owned, removed, git, ownersh
         reap: ownership => {
             reapProviderProcesses(ownership.worktree.path, isPidAlive, isProviderTreeAlive, killProcessTreeForCleanup);
         },
+        ...(ownershipTokens && acceptanceDigest ? {
+            retain: (ownership, reason, phase) => {
+                // The first retained candidate resumes through the existing dispatcher recovery path.
+                // Additional alternatives remain inspectable without creating a second scheduler.
+                const ownerToken = ownershipTokens.get(ownership.worktree.path) ?? ownership.ownerToken;
+                const suffix = createHash('sha256').update(ownerToken).digest('hex').slice(0, 24);
+                const file = retainedRecords.get(ownership.worktree.path) ?? (retainedRecords.size === 0
+                    ? recoveryPath(targetDir, ownership.storyId)
+                    : statePath(targetDir, 'integration-recovery', `${storyPathSegment(ownership.storyId)}-candidate-${suffix}.json`));
+                retainedRecords.set(ownership.worktree.path, file);
+                retainParallelWorktree(targetDir, file, {
+                    storyId: ownership.storyId, worktree: ownership.worktree.path, baseCommit: ownership.worktree.baseCommit,
+                    prdHash: acceptanceDigest, ownerToken, reason, phase,
+                });
+                writeCandidateStatus(targetDir, ownership, ownership.worktree.path, 'retained', reason);
+            },
+        } : {}),
         remove: ownership => {
             removeOwnedWorktree(targetDir, ownership, owned, removed, git);
             writeCandidateStatus(targetDir, ownership, ownership.worktree.path, 'removed');
@@ -159,7 +186,18 @@ function writeCandidateStatus(targetDir, input, worktree, state, reason) {
     writeFileSync(file, JSON.stringify({ storyId: input.storyId, candidateId: input.candidateId, worktree, state, ...(reason ? { reason } : {}) }));
 }
 function rebaseCandidate(targetDir, input) {
+    const cacheProblem = cacheIsolationProblem(input.worktree.path);
+    if (cacheProblem)
+        return { kind: 'reopen', reason: cacheProblem };
     const currentHead = gitText(targetDir, ['rev-parse', 'HEAD']);
+    const actual = changedPaths(input.worktree.path, input.worktree.baseCommit);
+    const unexpected = unexpectedWrites(input, actual);
+    const siblings = currentHead === input.worktree.baseCommit ? [] : changedPaths(targetDir, input.worktree.baseCommit);
+    const collisions = actual.filter(path => writeScopesOverlap([path], siblings));
+    if (unexpected.length)
+        return { kind: 'reopen', reason: `Candidate writes outside declared scopes: ${unexpected.join(', ')}${collisions.length ? `; integrated sibling collisions: ${collisions.join(', ')}` : ''}` };
+    if (collisions.length)
+        return { kind: 'reopen', reason: `Candidate writes collide with integrated sibling changes: ${collisions.join(', ')}` };
     const candidateHead = gitText(input.worktree.path, ['rev-parse', 'HEAD']);
     try {
         execFileSync('git', ['merge-base', '--is-ancestor', input.worktree.baseCommit, 'HEAD'], { cwd: input.worktree.path, stdio: 'pipe' });
@@ -229,3 +267,16 @@ function gitText(dir, args) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function changedPaths(directory, base) {
+    const read = (args) => execFileSync('git', args, { cwd: directory, stdio: 'pipe' }).toString().split('\0').filter(Boolean);
+    return [...new Set([...read(['diff', '--no-renames', '--name-only', '-z', base, '--', '.', ...RUNTIME_EXCLUDES]), ...read(['ls-files', '--others', '--exclude-standard', '-z', '--', '.', ...RUNTIME_EXCLUDES])])].filter(path => !/^(?:\.yoke\/(?:proof|context)\/|\.yoke\/prd\.(?:yaml|json)$)/u.test(path));
+}
+function unexpectedWrites(input, paths) {
+    if (input.story.writes === undefined)
+        return [];
+    const normalize = (value) => {
+        const path = value.replace(/\\/gu, '/').replace(/\/$/u, '');
+        return process.platform === 'win32' ? path.toLowerCase() : path;
+    };
+    return paths.filter(path => !input.story.writes.some(scope => normalize(path) === normalize(scope) || normalize(path).startsWith(`${normalize(scope)}/`)));
+}