@hecer/yoke 1.2.1 → 1.4.0

package/dist/loop/parallel-command.js

@@ -0,0 +1,287 @@
+import { existsSync, rmSync } from 'node:fs';
+import { createDispatcher } from './dispatcher.js';
+import { consumeDecisionRequest } from './decision.js';
+import { pauseFilePath } from './loop.js';
+import { makeParallelAdapters } from './parallel-adapters.js';
+import { loadPrd, progress } from './prd.js';
+import { makeAsyncRunner } from './runner.js';
+import { runStoryWorker } from './worker.js';
+export async function runParallelLoopCommand(input) {
+    const adapters = makeParallelAdapters(input.targetDir, input.identity, input.git);
+    if (!adapters.git.isClean(input.targetDir)) {
+        input.reporter.blocked('target working tree is not clean');
+        return 1;
+    }
+    let pauseConsumed = false;
+    const pause = () => {
+        if (pauseConsumed)
+            return true;
+        const path = pauseFilePath(input.targetDir);
+        if (!existsSync(path))
+            return false;
+        rmSync(path, { force: true });
+        pauseConsumed = true;
+        return true;
+    };
+    const dispatcher = createDispatcher({
+        targetDir: input.targetDir,
+        prdPath: input.prdPath,
+        stories: loadPrd(input.prdPath),
+        maxConcurrency: input.maxConcurrency,
+        maxIterations: input.maxIterations,
+        providers: input.providers,
+        affinityProviders: input.affinityProviders,
+        worktrees: adapters.worktrees,
+        git: adapters.git,
+        ...(input.candidateCount && input.candidateCount > 1 ? {
+            candidateCount: input.candidateCount,
+            candidateCoordinator: workerInput => candidateCoordinatorInput(input, adapters, workerInput, pause),
+        } : {}),
+        pause,
+        onProgress: status => input.reporter.parallel?.(status),
+        gates: {
+            verify: input.verify,
+            verifyCriterion: input.verifyCriterion,
+            requireCriterionEvidence: input.requireCriterionEvidence,
+            perf: input.perf,
+            audit: input.audit,
+            qualityReview: (path, story, worker) => integrationGate(input, path, story, integratorReporter(input.reporter, worker)),
+            integrationPhase: (worker, phase) => reportIntegrator(input.reporter, worker, phase),
+        },
+        worker: workerInput => {
+            const runner = input.runner ?? asyncRunner(input, workerInput.provider, workerInput.cancellation.signal, workerInput.ownerToken);
+            const result = runStoryWorker({
+                story: workerInput.story,
+                worktree: workerInput.worktree.path,
+                baseCommit: workerInput.worktree.baseCommit,
+                provider: workerInput.provider,
+                runner,
+                verify: input.verify,
+                verifyCriterion: input.verifyCriterion,
+                requireCriterionEvidence: input.requireCriterionEvidence,
+                perf: input.perf,
+                audit: input.audit,
+                qualityPreflight: input.quality?.qualityPreflight,
+                qualityStage: input.quality?.qualityStage,
+                repair: input.quality?.repair,
+                repairLimits: input.quality?.repairLimits,
+                qualityMetadata: input.quality?.qualityMetadata,
+                qualityEnabled: input.quality?.qualityEnabled,
+                review: input.review,
+                cancellation: workerInput.cancellation,
+                beforeGates: context => {
+                    const decision = consumeDecisionRequest(context.targetDir, input.targetDir, context.story.id);
+                    if (!decision)
+                        return null;
+                    input.onCriticalDecision?.(decision);
+                    return decision.question;
+                },
+                pause,
+                reporter: workerReporter(input.reporter, workerInput),
+            });
+            return Promise.resolve(result);
+        },
+    });
+    const result = await dispatcher.run();
+    const finalProgress = progress(loadPrd(input.prdPath));
+    if (result.status === 'complete' && input.completion) {
+        const gate = input.completion(input.targetDir);
+        if (!gate.passed) {
+            input.reporter.blocked(gate.summary);
+            return 1;
+        }
+    }
+    if (result.status === 'complete')
+        input.reporter.complete(finalProgress);
+    else if (result.status === 'paused')
+        input.reporter.paused(finalProgress);
+    else if (result.status === 'cap-reached')
+        input.reporter.capReached(finalProgress);
+    else
+        input.reporter.blocked(result.reason ?? `parallel dispatcher ${result.status}`);
+    return result.status === 'complete' ? 0 : result.status === 'paused' ? 3 : 1;
+}
+function candidateCoordinatorInput(input, adapters, worker, pause) {
+    const quality = input.quality;
+    const candidateCount = input.candidateCount;
+    if (!quality || !candidateCount)
+        throw new Error('candidate dispatch requires quality hooks and a candidate count');
+    const candidateIds = Array.from({ length: candidateCount }, (_, index) => `candidate-${index + 1}`);
+    const comparison = quality.candidateComparison(worker.story, candidateIds);
+    const reporter = workerReporter(input.reporter, worker);
+    return {
+        story: worker.story,
+        baseCommit: worker.worktree.baseCommit,
+        maxCandidates: candidateCount,
+        candidates: candidateDefinitions(input, worker, candidateCount, pause),
+        coordinatorId: `${worker.dispatcherId}:${worker.story.id}:${worker.ownerToken}`,
+        ownerToken: candidateId => `${worker.ownerToken}-${candidateId}`,
+        lifecycle: adapters.candidates(worker),
+        evidence: comparison.evidence,
+        stageEvidence: comparison.stageEvidence,
+        judgeProvenance: comparison.judgeProvenance,
+        onSelecting: () => reporter.phase('selecting-candidate'),
+        onLifecycle: (candidate, state, reason) => candidateReporter(input.reporter, worker, candidate, state, reason),
+        judge: request => comparison.judge(request),
+        recordResult: comparison.recordResult,
+        recordElimination: comparison.recordElimination,
+        recordSelection: comparison.recordSelection,
+        signal: worker.cancellation.signal,
+        pause,
+    };
+}
+function candidateDefinitions(input, worker, candidateCount, pause) {
+    const quality = input.quality;
+    return Array.from({ length: candidateCount }, (_, index) => {
+        const candidateId = `candidate-${index + 1}`;
+        const qualityRoundBase = (index + 1) * 10_000;
+        const runner = input.runner ?? asyncRunner(input, worker.provider, undefined, `${worker.ownerToken}-${candidateId}`);
+        return {
+            id: candidateId,
+            worker: {
+                provider: worker.provider,
+                runner,
+                verify: input.verify,
+                verifyCriterion: input.verifyCriterion,
+                requireCriterionEvidence: input.requireCriterionEvidence,
+                perf: input.perf,
+                audit: input.audit,
+                ...(quality ? {
+                    qualityPreflight: quality.qualityPreflight,
+                    qualityStage: (context, round, attempt) => quality.qualityStage(context, qualityRoundBase + round, attempt),
+                    repair: quality.repair,
+                    repairLimits: quality.repairLimits,
+                    qualityMetadata: quality.qualityMetadata,
+                    qualityEnabled: quality.qualityEnabled,
+                } : {}),
+                review: input.review,
+                beforeGates: context => {
+                    if (pause())
+                        return 'candidate coordination paused';
+                    const decision = consumeDecisionRequest(context.targetDir, input.targetDir, context.story.id);
+                    if (!decision)
+                        return null;
+                    input.onCriticalDecision?.(decision);
+                    return decision.question;
+                },
+                pause,
+                reporter: workerReporter(input.reporter, worker),
+                reporterFor: (candidate) => workerReporter(input.reporter, worker, candidate),
+            },
+            runnerFor: cancellation => input.runner ?? asyncRunner(input, worker.provider, cancellation.signal, `${worker.ownerToken}-${candidateId}`),
+        };
+    });
+}
+function workerReporter(reporter, worker, candidate) {
+    const attribution = {
+        story: worker.story.id,
+        storyTitle: worker.story.title,
+        provider: worker.provider.provider,
+        ...(worker.provider.model ? { model: worker.provider.model } : {}),
+        ...(candidate ? { candidateId: candidate.candidateId, worktree: candidate.worktree.path } : {}),
+    };
+    return {
+        phase: phase => {
+            if (reporter.parallelWorker)
+                reporter.parallelWorker({ ...attribution, phase });
+            else
+                reporter.phase(phase);
+        },
+        quality: quality => {
+            if (reporter.parallelWorker)
+                reporter.parallelWorker({ ...attribution, quality });
+            else
+                reporter.quality(quality);
+        },
+        addTokens: usage => reporter.addTokens(usage),
+    };
+}
+function candidateReporter(reporter, worker, candidate, state, reason) {
+    if (!reporter.parallelWorker)
+        return;
+    reporter.parallelWorker({
+        story: worker.story.id,
+        storyTitle: worker.story.title,
+        provider: candidate.provider.provider,
+        ...(candidate.provider.model ? { model: candidate.provider.model } : {}),
+        candidateId: candidate.candidateId,
+        worktree: candidate.worktree.path,
+        lifecycle: state,
+        ...(reason ? { reason } : {}),
+    });
+}
+function integratorReporter(reporter, worker) {
+    const attribution = {
+        story: worker.story.id,
+        storyTitle: worker.story.title,
+        provider: worker.provider.provider,
+        ...(worker.provider.model ? { model: worker.provider.model } : {}),
+    };
+    return {
+        phase: phase => reportIntegrator(reporter, worker, phase),
+        quality: quality => {
+            if (reporter.parallelIntegrator)
+                reporter.parallelIntegrator({ ...attribution, quality });
+            else
+                reporter.quality(quality);
+        },
+    };
+}
+function reportIntegrator(reporter, worker, phase) {
+    if (reporter.parallelIntegrator) {
+        reporter.parallelIntegrator(phase
+            ? { story: worker.story.id, storyTitle: worker.story.title, provider: worker.provider.provider, ...(worker.provider.model ? { model: worker.provider.model } : {}), phase }
+            : null);
+        return;
+    }
+    if (phase)
+        reporter.phase(phase);
+}
+function asyncRunner(input, provider, signal, workerId) {
+    const { model: _globalModel, reasoningEffort: _globalReasoningEffort, ...selection } = input.selection;
+    const runner = makeAsyncRunner(provider.provider, {
+        onAmbiguity: input.onAmbiguity,
+        permissions: input.permissions,
+        selection: {
+            ...selection,
+            ...(provider.model ? { model: provider.model } : {}),
+            ...(provider.reasoningEffort ? { reasoningEffort: provider.reasoningEffort } : {}),
+        },
+        process: { idleTimeoutMs: input.idleMs, signal, workerId },
+    });
+    return async (context) => providerProcessResultToAgentResult(provider.provider, context.story.id, await runner(context).completion);
+}
+export function providerProcessResultToAgentResult(agent, storyId, result) {
+    const tokens = result.telemetry.tokens;
+    const telemetry = tokens ? { tokens } : {};
+    switch (result.kind) {
+        case 'succeeded': return { success: true, summary: `${agent} implemented ${storyId}`, ...telemetry };
+        case 'cancelled': return { success: false, summary: result.reason, ...telemetry };
+        case 'timed-out': return { success: false, summary: result.reason, ...telemetry };
+        case 'spawn-failed': return { success: false, summary: result.error, ...telemetry };
+        case 'failed': return { success: false, summary: `${agent} exited ${result.exitCode ?? 'without a code'}`, ...telemetry };
+        default: return assertNever(result);
+    }
+}
+function reviewGate(review, path, story) {
+    if (!review)
+        return { passed: true, summary: 'integrated gates passed' };
+    const result = review({ targetDir: path, story });
+    return { passed: result.success && result.reviewOutcome?.kind !== 'rejected', summary: result.summary };
+}
+function assertNever(value) { throw new Error(`unexpected provider result: ${String(value)}`); }
+function integrationGate(input, path, story, reporter) {
+    const context = { targetDir: path, story };
+    const qualityEnabled = input.quality?.qualityEnabled(story) ?? false;
+    if (qualityEnabled)
+        reporter.phase('comparing');
+    const preflight = qualityEnabled ? input.quality?.qualityPreflight(context) : undefined;
+    if (preflight?.kind === 'blocked')
+        return { passed: false, summary: preflight.summary };
+    const quality = qualityEnabled ? input.quality?.qualityStage(context, 10_000, 'integration') : undefined;
+    if (quality && quality.kind !== 'pass' && quality.kind !== 'skipped')
+        return { passed: false, summary: quality.summary };
+    if (input.review)
+        reporter.phase('reviewing');
+    return reviewGate(input.review, path, story);
+}

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,19 +1,80 @@
+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),
+    verify: z.array(z.string().min(1)).min(1),
+});
+export function criterionCommandProblem(criterion) {
+    const normalizedId = criterion.id.toLowerCase().replace(/[^a-z0-9]/g, '');
+    for (const raw of criterion.verify) {
+        const command = raw.trim();
+        if (/(?:[&;|<>`\r\n]|\$\()/.test(command)) {
+            return `criterion ${criterion.id} must use one single test command without shell control operators`;
+        }
+        const isTestCommand = /^(?:(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+(?:test|check|verify)(?::[A-Za-z0-9._-]+)?|npx\s+(?:vitest|jest|playwright|cypress)|(?:vitest|jest|pytest|phpunit)|python\s+-m\s+pytest|cargo\s+test|go\s+test|dotnet\s+test|mvn(?:w)?\s+test|gradle(?:w)?\s+test|bundle\s+exec\s+(?:rspec|rails\s+test)|bin\/rails\s+test|vendor\/bin\/phpunit|mix\s+test|swift\s+test|xcodebuild\s+test)(?:\s|$)/i.test(command);
+        if (!isTestCommand)
+            return `criterion ${criterion.id} must use an approved test command`;
+        const normalizedCommand = command.toLowerCase().replace(/[^a-z0-9]/g, '');
+        if (!normalizedCommand.includes(normalizedId)) {
+            return `criterion ${criterion.id} must target its criterion id in every verify command`;
+        }
+    }
+    return null;
+}
 export const StorySchema = z.object({
+    // Existing projects may already use human-readable IDs. Keep loading them;
+    // every filesystem use goes through storyPathSegment instead.
     id: z.string().min(1),
     title: z.string().min(1),
     priority: z.number(),
-    acceptance: z.array(z.string().min(1)),
+    // String criteria remain readable for existing projects. New strict projects
+    // use structured criteria so Yoke can execute proof for each outcome instead
+    // of trusting an unrelated green test suite.
+    acceptance: z.array(z.union([z.string().min(1), AcceptanceCriterionSchema])),
     passes: z.boolean(),
     needs: z.array(z.string().min(1)).optional(),
     area: z.string().min(1).optional(),
     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);
+    if (structured.length > 0 && (structured.length < 2 || structured.length > 5)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['acceptance'],
+            message: 'structured stories must have 2-5 structured acceptance criteria',
+        });
+    }
+    if (new Set(ids).size !== ids.length) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['acceptance'],
+            message: 'structured criterion ids must be unique within a story',
+        });
+    }
 });
+export function storyPathSegment(id) {
+    return `story-${createHash('sha256').update(id, 'utf8').digest('hex')}`;
+}
+export function isAcceptanceCriterion(value) {
+    return typeof value !== 'string';
+}
+export function acceptanceText(value) {
+    return typeof value === 'string' ? value : value.text;
+}
 const PrdSchema = z.array(StorySchema);
+export function parsePrd(file) {
+    return PrdSchema.parse(parse(readFileSync(file, 'utf8')));
+}
 export function loadPrd(file) {
-    const stories = PrdSchema.parse(parse(readFileSync(file, 'utf8')));
+    const stories = parsePrd(file);
     const issues = validateDependencies(stories);
     if (issues.length)
         throw new Error(`Invalid PRD dependency graph:\n${issues.join('\n')}`);

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() { },
 };