@hecer/yoke 1.3.0 → 1.4.0

package/dist/loop/dispatcher.js

@@ -0,0 +1,334 @@
+import { randomUUID } from 'node:crypto';
+import { join, relative } from 'node:path';
+import { appendDecision, contextDir } from '../context/context.js';
+import { acquireClaim, heartbeatClaim, releaseClaim, requestClaimCancellation } from './claims.js';
+import { coordinateCandidates } from './candidates.js';
+import { MergeQueue } from './merge-queue.js';
+import { isAcceptanceCriterion, loadPrd, progress, savePrd } from './prd.js';
+import { readyStories } from './scheduler.js';
+import { createWorkerCleanup } from './worker-cleanup.js';
+function defaultClaims(targetDir, clock) {
+    return {
+        acquire: input => acquireClaim(targetDir, input.story.id, input.dispatcherId, {
+            dispatcherId: input.dispatcherId,
+            ownerToken: input.ownerToken,
+            ...(!input.candidateRace ? {
+                baseCommit: input.worktree.baseCommit,
+                worktree: input.worktree.path,
+                provider: input.provider.provider,
+                model: input.provider.model,
+            } : {}),
+            role: 'implementation',
+            now: clock(),
+        }) !== null,
+        heartbeat: input => { heartbeatClaim(targetDir, input.story.id, input.ownerToken, { now: clock() }); },
+        release: input => releaseClaim(targetDir, input.story.id, input.ownerToken, { now: clock() }),
+        cancel: (input, reason) => { requestClaimCancellation(targetDir, input.story.id, input.ownerToken, reason, { now: clock() }); },
+    };
+}
+async function gateResult(gates, path, worker) {
+    const { story } = worker;
+    const criteria = story.acceptance.filter(isAcceptanceCriterion);
+    if (criteria.length === 0 && gates.requireCriterionEvidence)
+        return { passed: false, summary: 'missing criterion evidence' };
+    if (criteria.length > 0 && !gates.verifyCriterion)
+        return { passed: false, summary: 'criterion verifier is not configured' };
+    for (const criterion of criteria) {
+        const result = gates.verifyCriterion?.(path, story, criterion);
+        if (!result?.passed)
+            return { passed: false, summary: result?.summary ?? 'criterion verification failed' };
+    }
+    for (const gate of [gates.verify, gates.perf, gates.audit]) {
+        if (!gate)
+            continue;
+        const result = gate(path, story);
+        if (!result.passed)
+            return result;
+    }
+    return gates.qualityReview?.(path, story, worker) ?? { passed: true, summary: 'integrated gates passed' };
+}
+export function createDispatcher(options) {
+    const dispatcherId = options.dispatcherId ?? randomUUID();
+    const ids = options.id ?? randomUUID;
+    const clock = options.clock ?? (() => new Date());
+    const claims = options.claims ?? defaultClaims(options.targetDir, clock);
+    const queue = new MergeQueue();
+    const active = new Map();
+    const queued = new Map();
+    const areas = new Set();
+    const integrated = [];
+    const reopened = [];
+    const failed = [];
+    const failureReasons = new Map();
+    const integrationBlocks = [];
+    let iterations = 0;
+    let providerIndex = 0;
+    let paused = false;
+    let cancellationReason;
+    const reportProgress = () => options.onProgress?.({
+        dispatcherId,
+        maxConcurrency: options.maxConcurrency,
+        activeWorkers: active.size,
+        queuedCandidates: queued.size,
+        integrated: integrated.length,
+        reopened: reopened.length,
+        iteration: iterations,
+        progress: progress(options.stories),
+        workers: [...active.values()].map(worker => ({
+            story: worker.input.story.id,
+            storyTitle: worker.input.story.title,
+            provider: worker.input.provider.provider,
+            ...(worker.input.provider.model ? { model: worker.input.provider.model } : {}),
+            phase: 'implementing',
+        })),
+    });
+    const providerFor = (story) => {
+        if (story.agent) {
+            const configured = options.affinityProviders?.find(provider => provider.provider === story.agent)
+                ?? options.providers?.find(provider => provider.provider === story.agent);
+            return { ...(configured ?? { provider: story.agent }), provider: story.agent, role: 'implementation' };
+        }
+        const configured = options.providers?.[providerIndex++ % (options.providers?.length ?? 1)] ?? { provider: 'claude' };
+        return { ...configured, role: 'implementation' };
+    };
+    const cleanupWorker = createWorkerCleanup({
+        cleanupProcess: options.worktrees.cleanupProcess,
+        removeWorktree: input => options.worktrees.remove(input),
+        releaseClaim: input => {
+            if (claims.release(input) === false)
+                throw new Error('claim release failed');
+        },
+    });
+    const cleanup = (input) => {
+        if (input.story.area)
+            areas.delete(input.story.area);
+        cleanupWorker(input);
+    };
+    const releaseCandidateClaim = (input) => {
+        if (input.story.area)
+            areas.delete(input.story.area);
+        if (claims.release(input) === false)
+            throw new Error('claim release failed');
+    };
+    const persistPass = (input) => {
+        if (!options.prdPath)
+            return;
+        const path = join(input.worktree.path, relative(options.targetDir, options.prdPath));
+        const next = loadPrd(options.prdPath).map(story => story.id === input.story.id ? { ...story, passes: true } : story);
+        savePrd(path, next);
+        appendDecision(contextDir(input.worktree.path), { storyId: input.story.id, title: input.story.title, summary: `${input.story.id} integrated` });
+    };
+    const enqueue = (input, result) => {
+        let reason = 'integrated verification failed';
+        const task = queue.enqueue({
+            storyId: input.story.id,
+            rebase: async () => {
+                if (cancellationReason)
+                    throw new Error(cancellationReason);
+                if (!options.git.isClean(options.targetDir))
+                    throw new Error('target working tree is not clean');
+                const rebase = await options.git.rebase(input);
+                if (rebase.kind === 'reopen') {
+                    reason = rebase.reason;
+                    throw new Error(reason);
+                }
+                return rebase.expectedHead;
+            },
+            verify: async () => {
+                if (cancellationReason) {
+                    reason = cancellationReason;
+                    return false;
+                }
+                const gate = await gateResult(options.gates, input.worktree.path, input);
+                reason = gate.summary;
+                return gate.passed;
+            },
+            integrate: async (expectedHead) => {
+                if (cancellationReason)
+                    throw new Error(cancellationReason);
+                options.gates.integrationPhase?.(input, 'committing');
+                persistPass(input);
+                await options.git.commit(input);
+                await options.git.integrate(input, expectedHead);
+            },
+            postIntegrateVerify: () => {
+                if (!options.git.isClean(options.targetDir))
+                    throw new Error('target working tree is not clean after integration');
+            },
+        }).then(merge => {
+            switch (merge.status) {
+                case 'integrated':
+                    input.story.passes = true;
+                    integrated.push(input.story.id);
+                    result.routing.recordOutcome?.(true);
+                    return;
+                case 'integrated-but-blocked':
+                    input.story.passes = true;
+                    integrated.push(input.story.id);
+                    integrationBlocks.push(merge.reason);
+                    result.routing.recordOutcome?.(true);
+                    return;
+                case 'reopened':
+                    reopened.push(input.story.id);
+                    result.routing.recordOutcome?.(false);
+                    return;
+                default: {
+                    const unexpected = merge;
+                    throw new Error(`unexpected merge result: ${String(unexpected)}`);
+                }
+            }
+        }).finally(() => {
+            queued.delete(input.story.id);
+            options.gates.integrationPhase?.(input, undefined);
+            cleanup(input);
+            reportProgress();
+        });
+        queued.set(input.story.id, task);
+        reportProgress();
+    };
+    const launch = (story) => {
+        const provider = providerFor(story);
+        const ownerToken = ids();
+        const worktree = options.worktrees.create({ story, dispatcherId, ownerToken, provider });
+        const controller = new AbortController();
+        const candidateRace = Boolean(options.candidateCount && options.candidateCount > 1 && options.candidateCoordinator);
+        const input = { story, worktree, provider, cancellation: { signal: controller.signal }, dispatcherId, ownerToken, ...(candidateRace ? { candidateRace: true } : {}) };
+        if (!claims.acquire(input)) {
+            options.worktrees.remove(input);
+            return;
+        }
+        iterations += 1;
+        if (story.area)
+            areas.add(story.area);
+        const candidateDispatch = candidateRace;
+        const task = (candidateDispatch && options.candidateCoordinator
+            ? Promise.resolve(options.candidateCoordinator(input)).then(coordinateCandidates).then(result => ({ source: 'candidates', result }))
+            : options.worker(input).then(result => ({ source: 'worker', result }))).then(async (outcome) => {
+            active.delete(story.id);
+            claims.heartbeat(input);
+            if (outcome.source === 'candidates') {
+                switch (outcome.result.kind) {
+                    case 'winner': {
+                        const winnerInput = {
+                            ...input,
+                            worktree: outcome.result.winner.worktree,
+                            provider: outcome.result.winner.provider,
+                        };
+                        enqueue(winnerInput, outcome.result.winner.result);
+                        return;
+                    }
+                    case 'paused':
+                        paused = true;
+                        releaseCandidateClaim(input);
+                        reportProgress();
+                        return;
+                    case 'cancelled':
+                        releaseCandidateClaim(input);
+                        reportProgress();
+                        return;
+                    case 'blocked':
+                        failed.push(story.id);
+                        failureReasons.set(story.id, outcome.result.summary);
+                        if (outcome.result.reason !== 'cleanup-error' && !outcome.result.recovery?.length)
+                            releaseCandidateClaim(input);
+                        reportProgress();
+                        return;
+                    default: {
+                        const unexpected = outcome.result;
+                        throw new Error(`unexpected candidate coordinator result: ${String(unexpected)}`);
+                    }
+                }
+            }
+            const result = outcome.result;
+            if (result.kind === 'paused') {
+                if (result.reason === 'decision')
+                    cancel(`critical decision required for story ${input.story.id}: ${result.summary}`);
+                else
+                    paused = true;
+                cleanup(input);
+                reportProgress();
+                return;
+            }
+            if (result.kind !== 'candidate') {
+                failed.push(story.id);
+                failureReasons.set(story.id, result.summary);
+                cleanup(input);
+                reportProgress();
+                return;
+            }
+            if (cancellationReason || paused || options.pause?.()) {
+                paused = true;
+                result.routing.recordOutcome?.(false);
+                cleanup(input);
+                reportProgress();
+                return;
+            }
+            enqueue(input, result);
+        }, error => {
+            active.delete(story.id);
+            failed.push(story.id);
+            failureReasons.set(story.id, error instanceof Error ? error.message : String(error));
+            try {
+                cleanup(input);
+            }
+            catch (cleanupError) {
+                reportProgress();
+                throw new AggregateError([error, cleanupError], `worker ${story.id} and cleanup failed`);
+            }
+            reportProgress();
+            if (!(error instanceof Error))
+                throw error;
+        });
+        active.set(story.id, { input, controller, task });
+        reportProgress();
+    };
+    const cancel = (reason) => {
+        if (cancellationReason)
+            return;
+        cancellationReason = reason;
+        for (const worker of active.values()) {
+            claims.cancel?.(worker.input, reason);
+            worker.controller.abort(reason);
+        }
+    };
+    const run = async () => {
+        for (;;) {
+            if (options.pause?.())
+                paused = true;
+            if (!paused && !cancellationReason && integrationBlocks.length === 0 && iterations < options.maxIterations) {
+                const busy = new Set([...active.keys(), ...queued.keys(), ...failed]);
+                const slots = Math.max(0, options.maxConcurrency - active.size);
+                const ready = readyStories(options.stories, { activeAreas: areas }).filter(story => !busy.has(story.id)).slice(0, slots);
+                for (const story of ready) {
+                    if (!story.area || !areas.has(story.area))
+                        launch(story);
+                }
+            }
+            if (active.size > 0) {
+                await Promise.race([...active.values()].map(worker => worker.task));
+                continue;
+            }
+            if (queued.size > 0) {
+                await Promise.race(queued.values());
+                continue;
+            }
+            if (cancellationReason)
+                return { status: 'cancelled', reason: cancellationReason, iterations, integrated, reopened, failed };
+            if (paused)
+                return { status: 'paused', iterations, integrated, reopened, failed };
+            if (integrationBlocks.length > 0)
+                return { status: 'blocked', reason: integrationBlocks[0], iterations, integrated, reopened, failed };
+            if (options.stories.every(story => story.passes))
+                return { status: 'complete', iterations, integrated, reopened, failed };
+            if (failed.length > 0) {
+                const storyId = failed[0];
+                const detail = storyId ? failureReasons.get(storyId) : undefined;
+                return { status: 'blocked', ...(storyId && detail ? { reason: `worker ${storyId} failed: ${detail}` } : {}), iterations, integrated, reopened, failed };
+            }
+            if (iterations >= options.maxIterations)
+                return { status: 'cap-reached', iterations, integrated, reopened, failed };
+            return { status: 'blocked', iterations, integrated, reopened, failed };
+        }
+    };
+    return { run, cancel };
+}

package/dist/loop/loop.js

@@ -6,6 +6,7 @@ import { appendDecision, contextDir } from '../context/context.js';
 import { noopReporter } from './reporter.js';
 import { consumeDecisionRequest } from './decision.js';
 import { writeCriterionEvidence } from './evidence.js';
+import { runQualityRepairLoop } from '../quality/loop.js';
 function blockReason(base, targetDir, git) {
     let dirty = false;
     try {
@@ -16,11 +17,93 @@ function blockReason(base, targetDir, git) {
         ? `${base} (working tree has uncommitted changes from the blocked story — review/clean before re-running)`
         : base;
 }
+function reviewOutcome(result) {
+    if (result.reviewOutcome)
+        return result.reviewOutcome;
+    if (result.success) {
+        return { kind: 'approved', verdict: { approved: true, summary: result.summary, findings: [] } };
+    }
+    return { kind: 'malformed', summary: result.summary };
+}
+function repairBlockReason(outcome, story, targetDir, git) {
+    if (outcome.kind === 'approved' || outcome.kind === 'paused' || outcome.kind === 'cancelled')
+        return null;
+    const detail = outcome.summary ? `: ${outcome.summary}` : '';
+    const stage = outcome.reason === 'gate-failed' ? ` (${outcome.stage})` : '';
+    return blockReason(`story ${story.id} repair blocked${stage}: ${outcome.reason}${detail}`, targetDir, git);
+}
+function runQualityReview(opts, executionDir, story, reporter) {
+    const qualityAssessment = opts.qualityEnabled?.(story) === false ? undefined : opts.qualityStage;
+    const reviewAssessment = opts.review;
+    if (!qualityAssessment && !reviewAssessment)
+        return null;
+    const qualityMetadata = opts.qualityMetadata?.({ targetDir: executionDir, story });
+    const rerunGates = () => {
+        const criteria = runCriterionGates(opts, executionDir, story);
+        if (!criteria.passed)
+            return { kind: 'failed', stage: 'criterion', summary: criteria.summary };
+        reporter.phase('verifying');
+        const verify = runGate(opts.verify, executionDir, story.id);
+        if (!verify.passed)
+            return { kind: 'failed', stage: 'verify', summary: verify.summary };
+        if (opts.perf) {
+            reporter.phase('perf');
+            const perf = runGate(opts.perf, executionDir, story.id);
+            if (!perf.passed)
+                return { kind: 'failed', stage: 'perf', summary: perf.summary };
+        }
+        if (opts.audit) {
+            reporter.phase('audit');
+            const audit = runGate(opts.audit, executionDir, story.id);
+            if (!audit.passed)
+                return { kind: 'failed', stage: 'audit', summary: audit.summary };
+        }
+        return { kind: 'passed' };
+    };
+    return runQualityRepairLoop({
+        quality: qualityAssessment
+            ? round => {
+                reporter.phase('comparing');
+                return qualityAssessment({ targetDir: executionDir, story }, round);
+            }
+            : undefined,
+        review: reviewAssessment
+            ? () => {
+                reporter.phase('reviewing');
+                return reviewOutcome(reviewAssessment({ targetDir: executionDir, story }));
+            }
+            : undefined,
+        repair: request => {
+            reporter.phase('repairing');
+            if (!opts.repair)
+                return { kind: 'blocked', summary: 'repair callback is not configured' };
+            const result = opts.repair({ targetDir: executionDir, story }, request);
+            return result.success ? { kind: 'repaired' } : { kind: 'blocked', summary: result.summary };
+        },
+        rerunGates,
+        limits: opts.repairLimits,
+        pause: () => consumePause(opts.targetDir),
+        onStatus: status => {
+            if (qualityMetadata)
+                reporter.quality({ ...status, ...qualityMetadata });
+        },
+    });
+}
 // 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.
 export function pauseFilePath(targetDir) {
     return join(targetDir, '.yoke', 'loop.pause');
 }
+function consumePause(targetDir) {
+    const file = pauseFilePath(targetDir);
+    if (!existsSync(file))
+        return false;
+    try {
+        unlinkSync(file);
+    }
+    catch { /* consumed best-effort — pausing still wins */ }
+    return true;
+}
 // Abort channel for an agent that hits genuinely undecidable acceptance criteria
 // (only instructed to use it under loop.onAmbiguity: abort). Honoured whenever
 // present: without this check, an agent that stopped without changes would sail
@@ -125,12 +208,7 @@ export function runLoop(opts) {
         }
         // Intake is work at a story boundary. Cap, pause, and clean-tree safety must
         // win before a planner is allowed to edit and commit the PRD.
-        const pauseFile = pauseFilePath(opts.targetDir);
-        if (existsSync(pauseFile)) {
-            try {
-                unlinkSync(pauseFile);
-            }
-            catch { /* consumed best-effort — pausing still wins */ }
+        if (consumePause(opts.targetDir)) {
             reporter.paused(progress(stories));
             return { status: 'paused', iterations, finalProgress: progress(stories) };
         }
@@ -199,6 +277,15 @@ export function runLoop(opts) {
             return { status: 'blocked', iterations, reason: stl.reason, finalProgress: progress(stories) };
         }
         reporter.storyStart({ id: story.id, title: story.title }, iterations + 1, progress(stories));
+        if (opts.qualityPreflight && opts.qualityEnabled?.(story) !== false) {
+            reporter.phase('quality-preflight');
+            const preflight = opts.qualityPreflight({ targetDir: opts.targetDir, story });
+            if (preflight.kind === 'blocked') {
+                const reason = blockReason(`story ${story.id} quality preflight: ${preflight.summary}`, opts.targetDir, opts.git);
+                reporter.blocked(reason);
+                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+            }
+        }
         if (opts.isolate) {
             const wt = join(opts.targetDir, '.yoke', 'worktrees', storyPathSegment(story.id));
             const wtPrd = join(wt, relative(opts.targetDir, opts.prdPath));
@@ -272,12 +359,15 @@ export function runLoop(opts) {
                 const summary = result.success
                     ? result.summary
                     : `${result.summary} (runner exited non-zero but verify is green)`;
-                if (opts.review) {
-                    reporter.phase('reviewing');
-                    const reviewResult = opts.review({ targetDir: wt, story });
-                    if (!reviewResult.success) {
+                const repairOutcome = runQualityReview(opts, wt, story, reporter);
+                if (repairOutcome) {
+                    if (repairOutcome.kind === 'paused') {
+                        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);
-                        const reason = blockReason(`story ${story.id} rejected in review: ${reviewResult.summary}`, opts.targetDir, opts.git);
                         reporter.blocked(reason);
                         return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
                     }
@@ -385,12 +475,15 @@ export function runLoop(opts) {
         const summary = result.success
             ? result.summary
             : `${result.summary} (runner exited non-zero but verify is green)`;
-        if (opts.review) {
-            reporter.phase('reviewing');
-            const reviewResult = opts.review({ targetDir: opts.targetDir, story });
-            if (!reviewResult.success) {
+        const repairOutcome = runQualityReview(opts, opts.targetDir, story, reporter);
+        if (repairOutcome) {
+            if (repairOutcome.kind === 'paused') {
+                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);
-                const reason = blockReason(`story ${story.id} rejected in review: ${reviewResult.summary}`, opts.targetDir, opts.git);
                 reporter.blocked(reason);
                 return {
                     status: 'blocked',

package/dist/loop/merge-queue.js

@@ -3,14 +3,20 @@ export class MergeQueue {
     enqueue(job) {
         const run = async () => {
             try {
-                await job.rebase();
-                if (!await job.verify())
-                    return { storyId: job.storyId, integrated: false, reason: 'integrated-tree verification failed' };
-                await job.integrate();
-                return { storyId: job.storyId, integrated: true };
+                const prepared = await job.rebase();
+                if (!await job.verify(prepared))
+                    return { storyId: job.storyId, status: 'reopened', integrated: false, reason: 'integrated-tree verification failed' };
+                await job.integrate(prepared);
+                try {
+                    await job.postIntegrateVerify?.(prepared);
+                    return { storyId: job.storyId, status: 'integrated', integrated: true };
+                }
+                catch (error) {
+                    return { storyId: job.storyId, status: 'integrated-but-blocked', integrated: true, reason: error instanceof Error ? error.message : String(error) };
+                }
             }
             catch (error) {
-                return { storyId: job.storyId, integrated: false, reason: error.message };
+                return { storyId: job.storyId, status: 'reopened', integrated: false, reason: error instanceof Error ? error.message : String(error) };
             }
         };
         const result = this.tail.then(run, run);