@hecer/yoke 1.3.0 → 1.5.0

package/dist/loop/parallel.js

@@ -12,10 +12,8 @@ export async function runParallelLoop(stories, opts) {
             activeAreas.add(story.area);
         const affinity = story.agent ?? (opts.agents?.length ? opts.agents[agentIndex++ % opts.agents.length] : undefined);
         const promise = opts.worker(story, affinity).then(result => {
-            if (result.success) {
-                story.passes = true;
+            if (result.success)
                 completed.push(story.id);
-            }
             else
                 failed.push(story.id);
         }).catch(() => { failed.push(story.id); }).finally(() => {
@@ -27,7 +25,7 @@ export async function runParallelLoop(stories, opts) {
     };
     while (iterations < opts.maxIterations && !opts.paused?.()) {
         const slots = Math.max(0, opts.maxConcurrency - active.size);
-        const ready = readyStories(stories, { activeAreas }).filter(s => !active.has(s.id) && !failed.includes(s.id)).slice(0, slots);
+        const ready = readyStories(stories, { activeAreas }).filter(s => !active.has(s.id) && !completed.includes(s.id) && !failed.includes(s.id)).slice(0, slots);
         for (const story of ready)
             launch(story);
         if (active.size === 0)

package/dist/loop/prd.js

@@ -1,6 +1,8 @@
+import { createHash } from 'node:crypto';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { parse, stringify } from 'yaml';
 import { z } from 'zod';
+import { StoryQualityDeclarationSchema } from '../quality/types.js';
 export const AcceptanceCriterionSchema = z.object({
     id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
     text: z.string().min(1),
@@ -39,6 +41,7 @@ export const StorySchema = z.object({
     agent: z.enum(['claude', 'codex', 'gemini']).optional(),
     /** Inbox request that created this story. Used for idempotent append-only intake. */
     sourceChange: z.string().min(1).optional(),
+    quality: StoryQualityDeclarationSchema.optional(),
 }).superRefine((story, ctx) => {
     const structured = story.acceptance.filter(isAcceptanceCriterion);
     const ids = structured.map(criterion => criterion.id);
@@ -58,7 +61,7 @@ export const StorySchema = z.object({
     }
 });
 export function storyPathSegment(id) {
-    return `story-${Buffer.from(id, 'utf8').toString('base64url')}`;
+    return `story-${createHash('sha256').update(id, 'utf8').digest('hex')}`;
 }
 export function isAcceptanceCriterion(value) {
     return typeof value !== 'string';

package/dist/loop/reporter.js

@@ -143,20 +143,86 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
         },
         blocked(reason) {
             const base = current ?? emptyStatus(now().toISOString());
-            persist({ ...base, state: 'blocked', reason, updatedAt: now().toISOString() }, 'blocked', `■ blocked on ${base.story ?? '?'}: ${reason}`);
+            persist({ ...withoutParallel(base), state: 'blocked', reason, updatedAt: now().toISOString() }, 'blocked', `■ blocked on ${base.story ?? '?'}: ${reason}`);
         },
         complete(progress) {
-            persist({ ...(current ?? emptyStatus(now().toISOString())), state: 'complete', phase: undefined,
+            persist({ ...withoutParallel(current ?? emptyStatus(now().toISOString())), state: 'complete', phase: undefined,
                 progress, reason: undefined, updatedAt: now().toISOString() }, 'complete', `✔ loop complete — ${progress.passed}/${progress.total}`);
         },
         capReached(progress) {
-            persist({ ...(current ?? emptyStatus(now().toISOString())), state: 'cap-reached', phase: undefined,
+            persist({ ...withoutParallel(current ?? emptyStatus(now().toISOString())), state: 'cap-reached', phase: undefined,
                 progress, updatedAt: now().toISOString() }, 'cap-reached', `◾ iteration cap reached — ${progress.passed}/${progress.total}`);
         },
         paused(progress) {
-            persist({ ...(current ?? emptyStatus(now().toISOString())), state: 'paused', phase: undefined,
+            persist({ ...withoutParallel(current ?? emptyStatus(now().toISOString())), state: 'paused', phase: undefined,
                 progress, updatedAt: now().toISOString() }, 'paused', `⏸ loop paused — ${progress.passed}/${progress.total}`);
         },
+        quality(status) {
+            const base = current ?? emptyStatus(now().toISOString());
+            persist({ ...base, quality: status, updatedAt: now().toISOString() }, 'quality', `  · quality round ${status.currentRound}…`);
+        },
+        parallel(status) {
+            const base = current ?? emptyStatus(now().toISOString());
+            const previousWorkers = base.parallel?.workers ?? [];
+            const previousIntegrator = base.parallel?.integrator;
+            const workers = status.workers?.map(worker => {
+                const previous = previousWorkers.find(candidate => sameWorker(candidate, worker));
+                return previous
+                    ? {
+                        ...worker,
+                        ...(previous.phase ? { phase: previous.phase } : {}),
+                        ...(previous.quality ? { quality: previous.quality } : {}),
+                    }
+                    : worker;
+            });
+            const reportedCandidates = previousWorkers.filter(worker => worker.candidateId && !(workers ?? []).some(candidate => sameWorker(candidate, worker)));
+            const parallel = {
+                ...status,
+                ...(workers !== undefined
+                    ? { workers: [...workers, ...reportedCandidates] }
+                    : previousWorkers.length > 0 ? { workers: previousWorkers } : {}),
+                ...(status.integrator !== undefined
+                    ? { integrator: status.integrator }
+                    : previousIntegrator ? { integrator: previousIntegrator } : {}),
+            };
+            persist({
+                ...base,
+                iteration: status.iteration ?? base.iteration,
+                progress: status.progress ?? base.progress,
+                parallel,
+                updatedAt: now().toISOString(),
+            }, 'parallel', `  · parallel ${status.activeWorkers}/${status.maxConcurrency}`);
+        },
+        parallelWorker(status) {
+            const base = current;
+            const parallel = base?.parallel;
+            if (!base || !parallel?.workers)
+                return;
+            persist({
+                ...base,
+                parallel: {
+                    ...parallel,
+                    workers: upsertWorker(parallel.workers, status),
+                },
+                updatedAt: now().toISOString(),
+            }, 'parallel-worker', `  · ${status.story} ${status.phase ?? 'quality'}…`);
+        },
+        parallelIntegrator(status) {
+            const base = current;
+            const parallel = base?.parallel;
+            if (!base || !parallel)
+                return;
+            if (status) {
+                persist({
+                    ...base,
+                    parallel: { ...parallel, integrator: status },
+                    updatedAt: now().toISOString(),
+                }, 'parallel-integrator', `  · integrating ${status.story} ${status.phase ?? 'quality'}…`);
+                return;
+            }
+            const { integrator: _integrator, ...withoutIntegrator } = parallel;
+            persist({ ...base, parallel: withoutIntegrator, updatedAt: now().toISOString() }, 'parallel-integrator', '  · integration complete');
+        },
         addTokens(usage) {
             const model = usage.model ?? tokens?.model;
             const cachedInputTokens = (tokens?.cachedInputTokens ?? 0) + (usage.cachedInputTokens ?? 0);
@@ -179,6 +245,21 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
 function emptyStatus(ts) {
     return { state: 'running', iteration: 0, progress: { passed: 0, total: 0 }, startedAt: ts, updatedAt: ts };
 }
+function sameWorker(left, right) {
+    return left.candidateId || right.candidateId
+        ? left.story === right.story && left.candidateId === right.candidateId && left.worktree === right.worktree
+        : left.story === right.story;
+}
+function upsertWorker(workers, status) {
+    const index = workers.findIndex(worker => sameWorker(worker, status));
+    return index < 0
+        ? [...workers, status]
+        : workers.map((worker, workerIndex) => workerIndex === index ? { ...worker, ...status } : worker);
+}
+function withoutParallel(status) {
+    const { parallel: _parallel, ...withoutParallel } = status;
+    return withoutParallel;
+}
 export const noopReporter = {
-    storyStart() { }, storyDone() { }, phase() { }, blocked() { }, complete() { }, capReached() { }, paused() { }, addTokens() { },
+    storyStart() { }, storyDone() { }, phase() { }, blocked() { }, complete() { }, capReached() { }, paused() { }, quality() { }, addTokens() { },
 };

package/dist/loop/run-command.js

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
-import { loadConfig, saveConfig, defaultConfig, resolveVerifyCommand } from '../retrofit/config.js';
+import { loadConfig, saveConfig, defaultConfig, resolveOutputPolicy, resolveVerifyCommand } from '../retrofit/config.js';
 import { loadPrd, progress } from './prd.js';
 import { runLoop } from './loop.js';
 import { commitPaths, realGitOps } from './git.js';
@@ -12,9 +12,12 @@ import { maybeAutoUpgrade } from '../update/upgrade.js';
 import { resolveCommitIdentity } from './identity.js';
 import { runAudit } from '../audit/command.js';
 import { detectHostAgent, resolveRunnerAgent } from '../agents/host.js';
-import { clearDecisionResume, decisionProcessingExists, decisionRequestId, formatPendingDecision, readPendingDecision, writeDecisionResume, } from './decision.js';
+import { buildTrustedDecisionResumeState, clearDecisionResume, decisionProcessingExists, decisionRequestId, formatPendingDecision, readPendingDecision, writeDecisionResume, } from './decision.js';
 import { makeAdaptiveRunner } from '../routing/router.js';
 import { runChangeApply } from '../change/inbox.js';
+import { createQualityCommandHooks } from '../quality/command.js';
+import { resolveQualityPolicy } from '../quality/types.js';
+import { runParallelLoopCommand } from './parallel-command.js';
 export const DEFAULT_IDLE_MINUTES = 20;
 const STALE_MINUTES = 20; // a running status older than this likely means the loop died
 export function relativeTime(fromIso, now) {
@@ -61,6 +64,24 @@ export function loopStatus(targetDir, now = () => new Date()) {
     }
     if (st.reason)
         lines.push(`  reason: ${st.reason}`);
+    if (st.quality)
+        lines.push(`  quality: round ${st.quality.currentRound} · ${st.quality.usedRepairs}${st.quality.unbounded ? ' unbounded repairs' : `/${st.quality.maxRepairs ?? 0} repairs`} · ${st.quality.policy}`);
+    if (st.parallel)
+        lines.push(`  parallel ${st.parallel.dispatcherId}: ${st.parallel.activeWorkers}/${st.parallel.maxConcurrency} workers · ${st.parallel.queuedCandidates} queued · ${st.parallel.integrated} integrated · ${st.parallel.reopened} reopened`);
+    const integrator = st.parallel?.integrator;
+    if (integrator) {
+        const quality = integrator.quality
+            ? ` · quality round ${integrator.quality.currentRound} · ${integrator.quality.usedRepairs}${integrator.quality.unbounded ? ' unbounded repairs' : `/${integrator.quality.maxRepairs ?? 0} repairs`}`
+            : '';
+        lines.push(`  integrator ${integrator.story} "${integrator.storyTitle}" (${integrator.provider}${integrator.model ? `/${integrator.model}` : ''}) · ${integrator.phase ?? 'working'}${quality}`);
+    }
+    for (const worker of st.parallel?.workers ?? []) {
+        const quality = worker.quality
+            ? ` · quality round ${worker.quality.currentRound} · ${worker.quality.usedRepairs}${worker.quality.unbounded ? ' unbounded repairs' : `/${worker.quality.maxRepairs ?? 0} repairs`}`
+            : '';
+        const candidate = worker.candidateId ? ` candidate ${worker.candidateId} · ${worker.worktree ?? 'worktree unknown'} · ${worker.lifecycle ?? 'working'}` : '';
+        lines.push(`  worker ${worker.story} "${worker.storyTitle}" (${worker.provider}${worker.model ? `/${worker.model}` : ''})${candidate} · ${worker.phase ?? 'working'}${quality}`);
+    }
     const ageMs = now().getTime() - Date.parse(st.updatedAt);
     if (st.state === 'running' && ageMs > STALE_MINUTES * 60_000) {
         lines.push(`  ⚠ possibly stuck — no update in ${relativeTime(st.updatedAt, now())}`);
@@ -72,11 +93,27 @@ export function resolveIdleMs(flagMinutes, configMinutes) {
     return minutes > 0 ? minutes * 60_000 : 0;
 }
 export function runLoopCommand(targetDir, opts) {
-    if ((opts.parallel ?? 1) > 1) {
-        console.error('Parallel CLI workers are not enabled yet. The dependency-aware dispatcher and merge queue are available as APIs; use --parallel=1 for the synchronous provider runner.');
+    const parallel = opts.parallel ?? 1;
+    const candidates = opts.candidates ?? 1;
+    if (!Number.isInteger(parallel) || parallel < 1) {
+        console.error('--parallel must be a positive integer');
+        return 2;
+    }
+    if (!Number.isInteger(candidates) || candidates < 1 || candidates > 5) {
+        console.error('--candidates must be an integer from 1 to 5');
         return 2;
     }
     const config = loadConfig(targetDir);
+    const maxParallelCandidates = config?.quality?.maxParallelCandidates ?? 1;
+    if (candidates > maxParallelCandidates) {
+        console.error(`--candidates=${candidates} exceeds quality.maxParallelCandidates=${maxParallelCandidates}`);
+        return 2;
+    }
+    const qualityDisabled = opts.quality === false || (!config?.quality?.enabled && opts.quality !== true && opts.qualityUnbounded !== true);
+    if (candidates > 1 && qualityDisabled) {
+        console.error(`--candidates=${candidates} requires quality; quality cannot be disabled for candidate dispatch.`);
+        return 2;
+    }
     if (!config?.loop.enabled) {
         console.error('Loop is disabled. Enable it with: yoke loop on');
         return 2;
@@ -100,6 +137,14 @@ export function runLoopCommand(targetDir, opts) {
         console.error(`No PRD found at ${path}. Create one (see canon loop/prd.schema.md).`);
         return 2;
     }
+    if (candidates > 1) {
+        const missingQuality = loadPrd(path).find(story => !story.passes && !story.quality);
+        if (missingQuality) {
+            console.error(`Story ${missingQuality.id} needs a quality declaration before --candidates=${candidates} can dispatch.`);
+            return 2;
+        }
+    }
+    const outputPolicy = resolveOutputPolicy(config);
     let verify = opts.verify;
     if (!verify) {
         const command = resolveVerifyCommand(targetDir, config);
@@ -107,16 +152,16 @@ export function runLoopCommand(targetDir, opts) {
             console.error('No verify command configured. Set verify.command in .yoke/config.yaml (e.g. "npm test") so the loop can confirm tests pass before marking work done.');
             return 2;
         }
-        verify = retryingVerifier(commandVerifier(command), config.verify?.retries ?? 1);
+        verify = retryingVerifier(commandVerifier(command, { phase: 'verify', policy: outputPolicy }), config.verify?.retries ?? 1);
     }
     // Optional performance budget gate: same contract as verify (exit 0 = within
     // budget), same flake tolerance (benchmarks are noisy).
     let perf = opts.perf;
     if (!perf && config.perf?.command) {
-        perf = retryingVerifier(commandVerifier(config.perf.command), config.perf.retries ?? 1);
+        perf = retryingVerifier(commandVerifier(config.perf.command, { phase: 'perf', policy: outputPolicy }), config.perf.retries ?? 1);
     }
     const completion = config.completion?.command
-        ? retryingVerifier(commandVerifier(config.completion.command), config.completion.retries ?? 1)
+        ? retryingVerifier(commandVerifier(config.completion.command, { phase: 'completion', policy: outputPolicy }), config.completion.retries ?? 1)
         : undefined;
     // Opt-in self-update, loop START only — this run keeps executing the version
     // it started with; a fetched upgrade applies from the next invocation.
@@ -137,8 +182,12 @@ export function runLoopCommand(targetDir, opts) {
     let audit = opts.audit;
     if (!audit && config.audit?.enabled) {
         audit = (dir) => {
-            const result = runAudit(dir, { command: config.audit?.command, suppressions: config.audit?.suppressions });
-            return { passed: result.code === 0, summary: result.error ?? (result.findings.map(f => `${f.ruleId} ${f.file}${f.line ? `:${f.line}` : ''}`).join(', ') || 'audit passed') };
+            const result = runAudit(dir, {
+                command: config.audit?.command,
+                suppressions: config.audit?.suppressions,
+                commandRunner: (command, commandDir) => commandVerifier(command, { phase: 'audit', policy: outputPolicy })(commandDir),
+            });
+            return { passed: result.code === 0, summary: result.error ?? (result.findings.map(f => `${f.ruleId} ${f.file}${f.line ? `:${f.line}` : ''}: ${f.message}`).join('\n') || 'audit passed') };
         };
     }
     if (commitIdentity) {
@@ -146,8 +195,84 @@ export function runLoopCommand(targetDir, opts) {
         announce(`Commits: ${commitIdentity.authorName} <${commitIdentity.authorEmail}> · co-authors: ${commitIdentity.allowCoAuthors ? 'allowed' : 'disabled'}`);
     }
     const idleMs = resolveIdleMs(opts.timeoutMinutes, config.loop.timeoutMinutes);
+    const qualityOverrides = {
+        ...(opts.qualityUnbounded ? { quality: true, qualityUnbounded: true } : opts.quality !== undefined ? { quality: opts.quality } : {}),
+        ...(opts.qualityRounds !== undefined ? { qualityRounds: opts.qualityRounds } : {}),
+        ...(opts.qualityMinutes !== undefined ? { qualityMinutes: opts.qualityMinutes } : {}),
+        ...(opts.qualityPolicy ? { qualityPolicy: opts.qualityPolicy } : {}),
+        ...(opts.candidates !== undefined ? { candidates: opts.candidates } : {}),
+    };
+    if (qualityOverrides.qualityUnbounded) {
+        console.error('WARNING: Quality repair limits are unbounded for this invocation. Mechanical gates, watchdog, isolation, and commit safety remain active.');
+    }
+    const configuredCriticAgent = config.quality?.critic?.agent ?? config.quality?.criticAgent ?? config.agents.find(agent => agent !== runnerAgent) ?? runnerAgent;
+    const configuredCriticModel = config.quality?.critic?.model ?? config.quality?.criticModel ?? (configuredCriticAgent === runnerAgent ? config.runner?.model : undefined);
+    if (candidates > 1 && !configuredCriticModel) {
+        console.error('Quality candidate selection requires quality.critic.model (or legacy quality.criticModel) before any runner or worktree is started.');
+        return 2;
+    }
+    const quality = createQualityCommandHooks({
+        targetDir,
+        config,
+        runnerAgent,
+        idleMs,
+        policy: qualityOverrides,
+        ...(opts.qualityRuntime ? { runtime: opts.qualityRuntime } : {}),
+    });
+    if (quality) {
+        const resolved = resolveQualityPolicy({ defaults: config.quality, overrides: qualityOverrides });
+        const criticAgent = configuredCriticAgent;
+        const repairAgent = config.quality?.repair?.agent ?? config.quality?.repairAgent ?? runnerAgent;
+        const limit = resolved.limits.unbounded ? 'unbounded' : `${resolved.limits.maxRounds ?? 3} rounds/${resolved.limits.maxMinutes ?? 60} minutes`;
+        const announce = opts.json ? console.error : console.log;
+        announce(`Quality: ${resolved.policy} · critic: ${criticAgent}${configuredCriticModel ? `/${configuredCriticModel}` : '/provider-default'} · repair: ${repairAgent}${config.quality?.repair?.model ?? config.quality?.repairModel ? `/${config.quality?.repair?.model ?? config.quality?.repairModel}` : '/provider-default'} · permissions: read-only critic/safe repair · budget: ${limit}`);
+    }
     const permissions = opts.permissions ?? config.runner?.permissions ?? 'safe';
     const routingEnabled = opts.routing ?? config.routing?.enabled ?? false;
+    const runnerSelection = {
+        model: config.runner?.model,
+        reasoningEffort: config.runner?.reasoningEffort,
+        bare: config.runner?.bare,
+        ...((routingEnabled || opts.routing === false) ? { nativeMultiAgent: false } : {}),
+    };
+    if ((parallel > 1 || candidates > 1) && routingEnabled) {
+        console.error('Adaptive routing is not available with parallel workers or quality candidates. Run with --parallel=1 --candidates=1 or disable routing.');
+        return 2;
+    }
+    const parallelProviders = [{
+            provider: runnerAgent,
+            ...(runnerSelection.model ? { model: runnerSelection.model } : {}),
+            ...(runnerSelection.reasoningEffort ? { reasoningEffort: runnerSelection.reasoningEffort } : {}),
+        }];
+    const parallelAffinityProviders = (config.routing?.workers ?? []).map(worker => ({
+        provider: worker.agent,
+        ...(worker.model ? { model: worker.model } : {}),
+        ...(worker.reasoningEffort ? { reasoningEffort: worker.reasoningEffort } : {}),
+    }));
+    const parallelStories = parallel > 1 || candidates > 1 ? loadPrd(path).filter(story => !story.passes) : [];
+    const ambiguousAffinityProvider = [...new Set(parallelStories.flatMap(story => story.agent ? [story.agent] : []))]
+        .find(agent => parallelAffinityProviders.filter(provider => provider.provider === agent).length > 1);
+    if (ambiguousAffinityProvider) {
+        console.error(`Parallel affinity provider "${ambiguousAffinityProvider}" has multiple profiles. Configure exactly one profile for each story agent.`);
+        return 2;
+    }
+    if (opts.runner) {
+        const mismatchedAffinity = parallelStories.find(story => {
+            if (!story.agent)
+                return false;
+            const provider = parallelAffinityProviders.find(candidate => candidate.provider === story.agent)
+                ?? parallelProviders.find(candidate => candidate.provider === story.agent);
+            return !provider
+                || provider.provider !== runnerAgent
+                || provider.model !== runnerSelection.model
+                || provider.reasoningEffort !== runnerSelection.reasoningEffort;
+        });
+        if (mismatchedAffinity) {
+            console.error(`Injected runner cannot truthfully execute affinity provider for story ${mismatchedAffinity.id}. Remove the affinity or use the configured provider runner.`);
+            return 2;
+        }
+    }
+    const ambiguityPolicy = opts.decisionPolicy ?? opts.onAmbiguity ?? config.loop.decisionPolicy ?? config.loop.onAmbiguity ?? 'auto';
     if (routingEnabled && (!config.routing || config.routing.workers.length === 0)) {
         console.error('Adaptive routing was requested, but no worker profiles are configured. Run yoke setup . --routing or add routing.workers to .yoke/config.yaml.');
         return 2;
@@ -167,23 +292,22 @@ export function runLoopCommand(targetDir, opts) {
     }));
     let runner = opts.runner;
     if (!runner) {
-        if (!available(runnerAgent)) {
-            console.error(`Agent CLI "${runnerAgent}" was not found on PATH. Install it, or pick another with --runner=<claude|codex|gemini>.`);
+        const requiredProviders = parallel > 1 || candidates > 1
+            ? [...new Set(loadPrd(path).filter(story => !story.passes).map(story => story.agent ?? runnerAgent))]
+            : [runnerAgent];
+        const unavailableProvider = requiredProviders.find(agent => !available(agent));
+        if (unavailableProvider) {
+            console.error(`Agent CLI "${unavailableProvider}" was not found on PATH. Install it, or pick another with --runner=<claude|codex|gemini>.`);
             return 2;
         }
         // Token reporting is part of the machine interface: in --json mode a claude
         // runner switches to stream-json so cumulative usage rides on every status.
         const runnerOpts = {
             tokenReport: opts.json === true,
-            onAmbiguity: opts.decisionPolicy ?? opts.onAmbiguity ?? config.loop.decisionPolicy ?? config.loop.onAmbiguity ?? 'auto',
+            onAmbiguity: ambiguityPolicy,
             perfCommand: config.perf?.command,
             permissions,
-            selection: {
-                model: config.runner?.model,
-                reasoningEffort: config.runner?.reasoningEffort,
-                bare: config.runner?.bare,
-                ...((routingEnabled || opts.routing === false) ? { nativeMultiAgent: false } : {}),
-            },
+            selection: runnerSelection,
         };
         runner = routingEnabled && config.routing
             ? makeAdaptiveRunner({
@@ -237,8 +361,75 @@ export function runLoopCommand(targetDir, opts) {
     if (lock.stalePid !== undefined) {
         console.warn(`Took over a stale loop lock (pid ${lock.stalePid} is gone).`);
     }
+    const reporter = opts.reporter ?? makeReporter(targetDir, { json: opts.json });
+    const buildResume = (storyId, requestId) => buildTrustedDecisionResumeState({
+        storyId,
+        requestId,
+        ...(opts.maxIterations !== undefined ? { maxIterations: opts.maxIterations } : {}),
+        agent: runnerAgent,
+        isolate: parallel > 1 || candidates > 1 || (opts.isolate ?? false),
+        reviewer: opts.reviewer,
+        review: opts.review === true || opts.reviewRunner !== undefined,
+        allowSelfReview: opts.allowSelfReview ?? false,
+        timeoutMinutes: opts.timeoutMinutes ?? config.loop.timeoutMinutes,
+        json: opts.json ?? false,
+        onAmbiguity: opts.decisionPolicy ? undefined : opts.onAmbiguity === 'resolve' || opts.onAmbiguity === 'abort' ? opts.onAmbiguity : (config.loop.decisionPolicy ? undefined : config.loop.onAmbiguity),
+        decisionPolicy: opts.decisionPolicy ?? (opts.onAmbiguity ? (opts.onAmbiguity === 'auto' || opts.onAmbiguity === 'critical' ? opts.onAmbiguity : undefined) : config.loop.decisionPolicy),
+        permissions,
+        parallel,
+        routing: routingEnabled,
+        ...(qualityOverrides.quality !== undefined ? { quality: qualityOverrides.quality } : {}),
+        ...(opts.qualityRounds !== undefined ? { qualityRounds: opts.qualityRounds } : {}),
+        ...(opts.qualityMinutes !== undefined ? { qualityMinutes: opts.qualityMinutes } : {}),
+        ...(opts.qualityPolicy ? { qualityPolicy: opts.qualityPolicy } : {}),
+        ...(opts.candidates !== undefined ? { candidates: opts.candidates } : {}),
+    });
+    const reconcileDecisionResume = () => {
+        try {
+            const pendingDecision = readPendingDecision(targetDir);
+            if (pendingDecision) {
+                writeDecisionResume(targetDir, buildResume(pendingDecision.storyId, decisionRequestId(pendingDecision)));
+            }
+            else {
+                clearDecisionResume(targetDir);
+            }
+            return undefined;
+        }
+        catch (error) {
+            reporter.blocked(`could not persist trusted decision resume state: ${error instanceof Error ? error.message : String(error)}`);
+            return 1;
+        }
+    };
+    if (parallel > 1 || candidates > 1) {
+        return runParallelLoopCommand({
+            targetDir,
+            prdPath: path,
+            maxConcurrency: parallel,
+            candidateCount: candidates,
+            maxIterations: opts.maxIterations ?? Number.POSITIVE_INFINITY,
+            runner: opts.runner,
+            runnerAgent,
+            idleMs,
+            permissions,
+            selection: runnerSelection,
+            providers: parallelProviders,
+            affinityProviders: parallelAffinityProviders,
+            onAmbiguity: ambiguityPolicy,
+            git: opts.git,
+            identity: commitIdentity,
+            verify,
+            verifyCriterion: (dir, _story, criterion) => commandsVerifier(criterion.verify, { phase: 'criterion', policy: outputPolicy })(dir),
+            requireCriterionEvidence: config.verify?.requireCriteria ?? false,
+            perf,
+            audit,
+            review,
+            reporter,
+            completion,
+            quality,
+            onCriticalDecision: decision => writeDecisionResume(targetDir, buildResume(decision.storyId, decisionRequestId(decision))),
+        }).then(code => reconcileDecisionResume() ?? code).finally(() => releaseLock(targetDir, lock.ownerToken));
+    }
     try {
-        const reporter = opts.reporter ?? makeReporter(targetDir, { json: opts.json });
         const maxIterations = opts.maxIterations ?? Number.POSITIVE_INFINITY;
         const result = runLoop({
             prdPath: path,
@@ -247,7 +438,7 @@ export function runLoopCommand(targetDir, opts) {
             git,
             commitIdentity,
             verify,
-            verifyCriterion: (dir, _story, criterion) => commandsVerifier(criterion.verify)(dir),
+            verifyCriterion: (dir, _story, criterion) => commandsVerifier(criterion.verify, { phase: 'criterion', policy: outputPolicy })(dir),
             requireCriterionEvidence: config.verify?.requireCriteria ?? false,
             completion,
             intake,
@@ -257,45 +448,12 @@ export function runLoopCommand(targetDir, opts) {
             isolate: (opts.parallel ?? 1) > 1 ? true : (opts.isolate ?? false),
             review,
             reporter,
+            ...(quality ?? {}),
+            ...(quality ? { qualityEnabled: quality.qualityEnabled, qualityMetadata: quality.qualityMetadata } : {}),
         });
-        try {
-            const pendingDecision = readPendingDecision(targetDir);
-            if (pendingDecision) {
-                writeDecisionResume(targetDir, {
-                    version: 1,
-                    storyId: pendingDecision.storyId,
-                    requestId: decisionRequestId(pendingDecision),
-                    answered: false,
-                    ...(opts.maxIterations !== undefined ? { maxIterations: opts.maxIterations } : {}),
-                    agent: runnerAgent,
-                    isolate: opts.isolate ?? false,
-                    reviewer: opts.reviewer,
-                    review: opts.review === true || opts.reviewRunner !== undefined,
-                    allowSelfReview: opts.allowSelfReview ?? false,
-                    timeoutMinutes: opts.timeoutMinutes ?? config.loop.timeoutMinutes,
-                    json: opts.json ?? false,
-                    onAmbiguity: opts.decisionPolicy
-                        ? undefined
-                        : opts.onAmbiguity === 'resolve' || opts.onAmbiguity === 'abort'
-                            ? opts.onAmbiguity
-                            : (config.loop.decisionPolicy ? undefined : config.loop.onAmbiguity),
-                    decisionPolicy: opts.decisionPolicy
-                        ?? (opts.onAmbiguity
-                            ? (opts.onAmbiguity === 'auto' || opts.onAmbiguity === 'critical' ? opts.onAmbiguity : undefined)
-                            : config.loop.decisionPolicy),
-                    permissions,
-                    parallel: opts.parallel ?? 1,
-                    routing: routingEnabled,
-                });
-            }
-            else
-                clearDecisionResume(targetDir);
-        }
-        catch (error) {
-            const reason = `could not persist trusted decision resume state: ${error.message}`;
-            reporter.blocked(reason);
-            return 1;
-        }
+        const resumeCode = reconcileDecisionResume();
+        if (resumeCode !== undefined)
+            return resumeCode;
         // In json mode stdout belongs to the NDJSON stream — route the narrative summary to stderr.
         const say = opts.json ? (line) => console.error(line) : (line) => console.log(line);
         say(`Loop ${result.status} after ${result.iterations} iteration(s): ${result.finalProgress.passed}/${result.finalProgress.total} stories pass`);