@hecer/yoke 1.2.1 → 1.4.0

package/dist/agents/telemetry.js

@@ -1,4 +1,66 @@
 const finite = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+function parseJson(value) {
+    try {
+        return { ok: true, value: JSON.parse(value) };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return { ok: false };
+        throw error;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function directMachineResult(value) {
+    return isRecord(value) && value.schemaVersion === 1 ? value : undefined;
+}
+export function parseProviderResult(agent, output) {
+    const whole = parseJson(output);
+    if (whole.ok) {
+        const direct = directMachineResult(whole.value);
+        if (direct !== undefined)
+            return direct;
+    }
+    const fragments = [];
+    for (const line of output.split(/\r?\n/u)) {
+        const parsed = parseJson(line);
+        if (!parsed.ok || !isRecord(parsed.value))
+            continue;
+        const event = parsed.value;
+        switch (agent) {
+            case 'claude':
+                if (event.type === 'result' && typeof event.result === 'string')
+                    fragments.push(event.result);
+                break;
+            case 'codex': {
+                const item = isRecord(event.item) ? event.item : undefined;
+                if (event.type === 'item.completed' && item?.type === 'agent_message' && typeof item.text === 'string')
+                    fragments.push(item.text);
+                break;
+            }
+            case 'gemini':
+                if (event.type === 'message' && event.role === 'assistant' && typeof event.content === 'string')
+                    fragments.push(event.content);
+                break;
+        }
+    }
+    const joined = parseJson(fragments.join(''));
+    if (joined.ok) {
+        const direct = directMachineResult(joined.value);
+        if (direct !== undefined)
+            return direct;
+    }
+    for (const fragment of fragments.reverse()) {
+        const parsed = parseJson(fragment);
+        if (!parsed.ok)
+            continue;
+        const direct = directMachineResult(parsed.value);
+        if (direct !== undefined)
+            return direct;
+    }
+    return null;
+}
 export function parseProviderTelemetry(agent, lines) {
     let inputTokens;
     let cachedInputTokens;

package/dist/change/inbox.js

@@ -0,0 +1,279 @@
+import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { z } from 'zod';
+import { criterionCommandProblem, isAcceptanceCriterion, loadPrd, parsePrd, savePrd, validateDependencies } from '../loop/prd.js';
+import { agentInvocation, buildWatchdogInvocation, isAgentAvailable, runAgent, } from '../loop/runner.js';
+import { commitPaths } from '../loop/git.js';
+const ChangeRequestSchema = z.object({
+    version: z.literal(1),
+    id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
+    createdAt: z.string().datetime(),
+    request: z.string().min(1),
+});
+const ChangeReviewSchema = z.object({
+    version: z.literal(1),
+    changeId: z.string().min(1),
+    approved: z.boolean(),
+    summary: z.string().min(1),
+    uncovered: z.array(z.string().min(1)),
+}).superRefine((review, ctx) => {
+    if (review.approved && review.uncovered.length > 0) {
+        ctx.addIssue({ code: 'custom', path: ['approved'], message: 'approved review cannot list uncovered requirements' });
+    }
+});
+const NewStoryId = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function changesDir(targetDir) { return join(targetDir, '.yoke', 'changes'); }
+function pendingDir(targetDir) { return join(changesDir(targetDir), 'pending'); }
+function appliedDir(targetDir) { return join(changesDir(targetDir), 'applied'); }
+function requestFile(targetDir, id) { return join(pendingDir(targetDir), `${id}.json`); }
+export function proposalFile(targetDir, id) { return resolve(changesDir(targetDir), `proposal-${id}.yaml`); }
+export function reviewFile(targetDir, id) { return resolve(changesDir(targetDir), `review-${id}.json`); }
+function ensureLocalIgnore(targetDir) {
+    let exclude;
+    try {
+        const gitPath = execFileSync('git', ['rev-parse', '--git-path', 'info/exclude'], { cwd: targetDir, stdio: 'pipe' }).toString().trim();
+        exclude = isAbsolute(gitPath) ? gitPath : resolve(targetDir, gitPath);
+    }
+    catch {
+        return;
+    }
+    mkdirSync(dirname(exclude), { recursive: true });
+    const current = existsSync(exclude) ? readFileSync(exclude, 'utf8') : '';
+    if (current.split(/\r?\n/).some(line => line.trim() === '.yoke/changes/'))
+        return;
+    const prefix = current.length === 0 || current.endsWith('\n') ? '' : '\n';
+    writeFileSync(exclude, `${current}${prefix}.yoke/changes/\n`);
+}
+function prdIsCommitted(targetDir) {
+    try {
+        execFileSync('git', ['ls-files', '--error-unmatch', '--', '.yoke/prd.yaml'], { cwd: targetDir, stdio: 'pipe' });
+        return execFileSync('git', ['status', '--porcelain', '--untracked-files=no', '--', '.yoke/prd.yaml'], {
+            cwd: targetDir,
+            stdio: 'pipe',
+        }).toString().trim() === '';
+    }
+    catch {
+        return false;
+    }
+}
+export function queueChange(targetDir, request, opts = {}) {
+    const text = request.trim();
+    if (!text)
+        throw new Error('change request must not be empty');
+    const change = ChangeRequestSchema.parse({
+        version: 1,
+        id: opts.id ?? randomUUID(),
+        createdAt: (opts.now ?? (() => new Date()))().toISOString(),
+        request: text,
+    });
+    ensureLocalIgnore(targetDir);
+    mkdirSync(pendingDir(targetDir), { recursive: true });
+    const path = requestFile(targetDir, change.id);
+    if (existsSync(path))
+        throw new Error(`change ${change.id} already exists`);
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(change, null, 2)}\n`, { flag: 'wx' });
+    renameSync(temporary, path);
+    return change;
+}
+export function pendingChanges(targetDir) {
+    const dir = pendingDir(targetDir);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter(name => name.endsWith('.json'))
+        .map(name => ChangeRequestSchema.parse(JSON.parse(readFileSync(join(dir, name), 'utf8'))))
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+}
+export function buildChangePrompt(request, proposalPath, stories) {
+    return [
+        'You are planning one newly requested product change for the Yoke autonomous loop.',
+        `Change request ${request.id}: ${request.request}`,
+        '',
+        'Create an append-only proposal: add small new stories; never rewrite or delete existing stories.',
+        `Existing story IDs: ${stories.map(story => story.id).join(', ') || '(none)'}`,
+        'Every proposed story must have passes: false and 2-5 structured acceptance criteria.',
+        'Every criterion must have a stable id, behavioral text, and one or more executable verify commands.',
+        'Each criterion id must appear in every verify command; each entry must be one approved test command without shell control operators.',
+        'Use only claude, codex, or gemini if an optional agent affinity is useful.',
+        '',
+        `Write ONLY a YAML array of the NEW stories to this exact file: ${proposalPath}`,
+        'Do not edit .yoke/prd.yaml or any source file. Do not commit.',
+    ].join('\n');
+}
+export function buildChangeReviewPrompt(request, reviewPath, proposed) {
+    return [
+        'Independently review whether a proposed append-only plan fully covers one product change.',
+        `Change request ${request.id}: ${request.request}`,
+        '',
+        'Check every distinct requested outcome, edge case, and state transition against the proposed stories and their criteria.',
+        'Approve only when every distinct requested outcome has a behavioral criterion and a criterion-specific verify command.',
+        'Do not assume a broad test suite proves an outcome. List every omission in uncovered.',
+        '',
+        `Proposed stories: ${JSON.stringify(proposed, null, 2)}`,
+        '',
+        `Write ONLY JSON to this exact file: ${reviewPath}`,
+        '{"version":1,"changeId":"<exact change id>","approved":true|false,"summary":"<reason>","uncovered":["<missing outcome>"]}',
+        'Do not edit .yoke/prd.yaml, the proposal, or any source file. Do not commit.',
+    ].join('\n');
+}
+function archiveRequest(targetDir, request) {
+    mkdirSync(appliedDir(targetDir), { recursive: true });
+    renameSync(requestFile(targetDir, request.id), join(appliedDir(targetDir), `${request.id}.json`));
+    rmSync(proposalFile(targetDir, request.id), { force: true });
+    rmSync(reviewFile(targetDir, request.id), { force: true });
+}
+export function runChangeApply(targetDir, opts) {
+    let requests;
+    try {
+        requests = pendingChanges(targetDir);
+    }
+    catch (error) {
+        return { ok: false, added: 0, summary: `invalid pending request: ${error.message}` };
+    }
+    const request = requests[0];
+    if (!request)
+        return { ok: true, added: 0, summary: 'inbox empty' };
+    const prdPath = join(targetDir, '.yoke', 'prd.yaml');
+    const existingText = readFileSync(prdPath, 'utf8');
+    const existing = loadPrd(prdPath);
+    if (existing.some(story => story.sourceChange === request.id)) {
+        if (!prdIsCommitted(targetDir)) {
+            return {
+                ok: false,
+                added: 0,
+                summary: `PRD contains change ${request.id} only as uncommitted recovery state; keeping the request pending`,
+                changeId: request.id,
+            };
+        }
+        try {
+            ;
+            (opts.archive ?? archiveRequest)(targetDir, request);
+        }
+        catch (error) {
+            return {
+                ok: false, added: 0,
+                summary: `committed change ${request.id} could not be archived; keeping it pending for recovery: ${error.message}`,
+                changeId: request.id,
+            };
+        }
+        return { ok: true, added: 0, summary: `recovered applied change ${request.id}`, changeId: request.id };
+    }
+    const available = opts.isAvailable ?? isAgentAvailable;
+    if (!available(opts.runner))
+        return { ok: false, added: 0, summary: `planner CLI "${opts.runner}" is unavailable`, changeId: request.id };
+    const reviewer = opts.reviewer ?? opts.runner;
+    if (!available(reviewer))
+        return { ok: false, added: 0, summary: `reviewer CLI "${reviewer}" is unavailable`, changeId: request.id };
+    const proposal = proposalFile(targetDir, request.id);
+    const plannerDir = changesDir(targetDir);
+    mkdirSync(plannerDir, { recursive: true });
+    rmSync(proposal, { force: true });
+    const base = agentInvocation(opts.runner, buildChangePrompt(request, proposal, existing), plannerDir, opts.permissions ?? 'safe', opts.selection);
+    const invocation = buildWatchdogInvocation(base, opts.timeoutMs ?? 0);
+    const result = (opts.run ?? runAgent)(invocation);
+    if (!result.success)
+        return { ok: false, added: 0, summary: `planner failed: ${result.summary}`, changeId: request.id };
+    if (readFileSync(prdPath, 'utf8') !== existingText) {
+        return {
+            ok: false,
+            added: 0,
+            summary: 'PRD changed while the planner was running; refusing to overwrite concurrent or out-of-contract edits',
+            changeId: request.id,
+        };
+    }
+    if (!existsSync(proposal))
+        return { ok: false, added: 0, summary: `planner did not write ${basename(proposal)}`, changeId: request.id };
+    let proposed;
+    try {
+        proposed = parsePrd(proposal);
+    }
+    catch (error) {
+        return { ok: false, added: 0, summary: `invalid story proposal: ${error.message}`, changeId: request.id };
+    }
+    if (proposed.length === 0)
+        return { ok: false, added: 0, summary: 'planner proposed no stories', changeId: request.id };
+    const existingIds = new Set(existing.map(story => story.id));
+    const proposedIds = new Set();
+    for (const story of proposed) {
+        if (!NewStoryId.test(story.id)) {
+            return { ok: false, added: 0, summary: `proposed story id must be one safe path segment: ${story.id}`, changeId: request.id };
+        }
+        if (story.passes)
+            return { ok: false, added: 0, summary: `proposed story ${story.id} is already marked passed`, changeId: request.id };
+        if (existingIds.has(story.id) || proposedIds.has(story.id)) {
+            return { ok: false, added: 0, summary: `duplicate proposed story id: ${story.id}`, changeId: request.id };
+        }
+        if (story.acceptance.length < 2 || story.acceptance.length > 5) {
+            return { ok: false, added: 0, summary: `proposed story ${story.id} must have 2-5 acceptance criteria`, changeId: request.id };
+        }
+        if (story.acceptance.some(criterion => !isAcceptanceCriterion(criterion))) {
+            return { ok: false, added: 0, summary: `proposed story ${story.id} lacks executable criterion evidence`, changeId: request.id };
+        }
+        for (const criterion of story.acceptance.filter(isAcceptanceCriterion)) {
+            const problem = criterionCommandProblem(criterion);
+            if (problem)
+                return { ok: false, added: 0, summary: problem, changeId: request.id };
+        }
+        proposedIds.add(story.id);
+    }
+    const appended = proposed.map(story => ({ ...story, sourceChange: request.id }));
+    const dependencyIssues = validateDependencies([...existing, ...appended]);
+    if (dependencyIssues.length > 0) {
+        return { ok: false, added: 0, summary: `invalid combined dependency graph: ${dependencyIssues.join('; ')}`, changeId: request.id };
+    }
+    const reviewPath = reviewFile(targetDir, request.id);
+    rmSync(reviewPath, { force: true });
+    const reviewBase = agentInvocation(reviewer, buildChangeReviewPrompt(request, reviewPath, appended), plannerDir, opts.permissions ?? 'safe', reviewer === opts.runner ? opts.selection : undefined);
+    const reviewInvocation = buildWatchdogInvocation(reviewBase, opts.timeoutMs ?? 0);
+    const reviewResult = (opts.review ?? runAgent)(reviewInvocation);
+    if (!reviewResult.success) {
+        return { ok: false, added: 0, summary: `coverage review failed: ${reviewResult.summary}`, changeId: request.id };
+    }
+    if (readFileSync(prdPath, 'utf8') !== existingText) {
+        return {
+            ok: false, added: 0,
+            summary: 'PRD changed while the coverage reviewer was running; refusing to overwrite concurrent or out-of-contract edits',
+            changeId: request.id,
+        };
+    }
+    if (!existsSync(reviewPath)) {
+        return { ok: false, added: 0, summary: `coverage reviewer did not write ${basename(reviewPath)}`, changeId: request.id };
+    }
+    let coverageReview;
+    try {
+        coverageReview = ChangeReviewSchema.parse(JSON.parse(readFileSync(reviewPath, 'utf8')));
+    }
+    catch (error) {
+        return { ok: false, added: 0, summary: `invalid coverage review: ${error.message}`, changeId: request.id };
+    }
+    if (coverageReview.changeId !== request.id) {
+        return { ok: false, added: 0, summary: `coverage review targets ${coverageReview.changeId}, expected ${request.id}`, changeId: request.id };
+    }
+    if (!coverageReview.approved || coverageReview.uncovered.length > 0) {
+        const missing = coverageReview.uncovered.length > 0 ? `: ${coverageReview.uncovered.join('; ')}` : '';
+        return { ok: false, added: 0, summary: `coverage review rejected the proposal: ${coverageReview.summary}${missing}`, changeId: request.id };
+    }
+    try {
+        savePrd(prdPath, [...existing, ...appended]);
+        (opts.commit ?? ((path, change) => commitPaths(targetDir, [path], `yoke: plan change ${change.id}`)))(prdPath, request);
+    }
+    catch (error) {
+        writeFileSync(prdPath, existingText);
+        return { ok: false, added: 0, summary: `could not persist change: ${error.message}`, changeId: request.id };
+    }
+    try {
+        ;
+        (opts.archive ?? archiveRequest)(targetDir, request);
+    }
+    catch (error) {
+        return {
+            ok: false, added: appended.length,
+            summary: `planned change ${request.id} was committed but could not be archived; keeping it pending for recovery: ${error.message}`,
+            changeId: request.id,
+        };
+    }
+    return { ok: true, added: appended.length, summary: `added ${appended.length} stories from ${request.id}`, changeId: request.id };
+}

package/dist/cli.js

@@ -15,6 +15,7 @@ import { maybeNotifyUpdate, currentYokeVersion } from './update/check.js';
 import { runUpgrade } from './update/upgrade.js';
 import { printAudit, runAudit } from './audit/command.js';
 import { runSetup } from './setup/command.js';
+import { pendingChanges, queueChange } from './change/inbox.js';
 import { answerPendingDecision, answeredDecisionResumeIsValid, clearDecisionResume, decisionProcessingExists, decisionResumeMatchesCurrent, finalizeCommittedDecisionResume, formatPendingDecision, readDecisionResume, readPendingDecision, writeDecisionResume, } from './loop/decision.js';
 export { runRetrofit } from './retrofit/command.js';
 export function runValidate(canonDir) {
@@ -51,6 +52,48 @@ export function runDesignScan(targetDir, opts) {
     console.log(`${label} — ✓`);
     return 0;
 }
+export function parseQualityFlags(args) {
+    const quality = args.includes('--quality') ? true : args.includes('--no-quality') ? false : undefined;
+    const qualityUnbounded = args.includes('--quality-unbounded') || undefined;
+    const parsePositive = (flag) => {
+        const raw = args.find(arg => arg.startsWith(flag));
+        if (!raw)
+            return undefined;
+        const value = Number(raw.slice(flag.length));
+        return Number.isInteger(value) && value > 0 ? value : `Invalid ${flag.slice(0, -1)} value: ${raw}`;
+    };
+    const qualityRounds = parsePositive('--quality-rounds=');
+    if (typeof qualityRounds === 'string')
+        return { ok: false, error: qualityRounds };
+    const qualityMinutes = parsePositive('--quality-minutes=');
+    if (typeof qualityMinutes === 'string')
+        return { ok: false, error: qualityMinutes };
+    const candidates = parsePositive('--candidates=');
+    if (typeof candidates === 'string')
+        return { ok: false, error: candidates };
+    const policyArg = args.find(arg => arg.startsWith('--quality-policy='))?.slice('--quality-policy='.length);
+    if (policyArg && policyArg !== 'blocking' && policyArg !== 'advisory') {
+        return { ok: false, error: `Invalid --quality-policy value: ${policyArg} (expected blocking|advisory)` };
+    }
+    const qualityPolicy = policyArg === 'blocking' || policyArg === 'advisory' ? policyArg : undefined;
+    if (quality === true && args.includes('--no-quality'))
+        return { ok: false, error: 'Cannot use --quality with --no-quality.' };
+    if (qualityUnbounded && quality === false)
+        return { ok: false, error: 'Cannot use --quality-unbounded with --no-quality.' };
+    if (qualityUnbounded && (qualityRounds !== undefined || qualityMinutes !== undefined)) {
+        return { ok: false, error: 'Cannot use --quality-unbounded with --quality-rounds or --quality-minutes.' };
+    }
+    return {
+        ok: true,
+        options: {
+            ...(qualityUnbounded ? { quality: true, qualityUnbounded: true } : quality !== undefined ? { quality } : {}),
+            ...(qualityRounds !== undefined ? { qualityRounds } : {}),
+            ...(qualityMinutes !== undefined ? { qualityMinutes } : {}),
+            ...(qualityPolicy ? { qualityPolicy } : {}),
+            ...(candidates !== undefined ? { candidates } : {}),
+        },
+    };
+}
 export function main(argv) {
     const [cmd, ...rest] = argv;
     switch (cmd) {
@@ -115,6 +158,39 @@ export function main(argv) {
             }
             return runRetrofit(targetDir, { loop, agents, codeGraph });
         }
+        case 'change': {
+            const sub = rest[0];
+            const targetDir = rest.slice(1).find(a => !a.startsWith('-')) ?? '.';
+            if (sub === 'add') {
+                const idea = rest.find(a => a.startsWith('--idea='))?.slice('--idea='.length);
+                if (!idea?.trim()) {
+                    console.error('usage: yoke change add [dir] --idea="..."');
+                    return 1;
+                }
+                try {
+                    const request = queueChange(targetDir, idea);
+                    console.log(`Queued change ${request.id}. A running loop will turn it into new stories at the next story boundary.`);
+                    return 0;
+                }
+                catch (error) {
+                    console.error(`Could not queue change: ${error.message}`);
+                    return 1;
+                }
+            }
+            if (sub === 'status') {
+                try {
+                    const requests = pendingChanges(targetDir);
+                    console.log(requests.length === 0 ? 'No pending changes.' : requests.map(item => `${item.id}  ${item.request}`).join('\n'));
+                    return 0;
+                }
+                catch (error) {
+                    console.error(`Could not read change inbox: ${error.message}`);
+                    return 1;
+                }
+            }
+            console.log('usage: yoke change <add|status> [dir] [--idea="..."]');
+            return 1;
+        }
         case 'loop': {
             const sub = rest[0];
             const targetDir = rest.slice(1).find(a => !a.startsWith('-')) ?? '.';
@@ -183,7 +259,12 @@ export function main(argv) {
                     return 1;
                 }
                 const { version: _version, storyId: _storyId, requestId: _requestId, answered: _answered, ...resumeOptions } = resume;
-                return runLoopCommand(targetDir, resumeOptions);
+                const qualityFlags = parseQualityFlags(rest);
+                if (!qualityFlags.ok) {
+                    console.error(qualityFlags.error);
+                    return 1;
+                }
+                return runLoopCommand(targetDir, { ...resumeOptions, ...qualityFlags.options });
             }
             if (sub === 'answer') {
                 const choice = rest.find(a => a.startsWith('--choice='))?.slice('--choice='.length);
@@ -308,9 +389,14 @@ export function main(argv) {
                     console.error(`Invalid --decision-policy value: ${dpArg} (expected auto|critical)`);
                     return 1;
                 }
-                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, parallel, reviewer, review, allowSelfReview, timeoutMinutes, json, routing, onAmbiguity: oaArg, decisionPolicy: dpArg, permissions });
+                const qualityFlags = parseQualityFlags(rest);
+                if (!qualityFlags.ok) {
+                    console.error(qualityFlags.error);
+                    return 1;
+                }
+                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, parallel, reviewer, review, allowSelfReview, timeoutMinutes, json, routing, onAmbiguity: oaArg, decisionPolicy: dpArg, permissions, ...qualityFlags.options });
             }
-            console.log('usage: yoke loop <on|off|status|decision|answer|resume [--discard]|cleanup [--remove-worktrees] [--discard-stale-recovery]|run [--max=N] [--parallel=N] [--runner=<claude|codex|gemini>] [--reviewer=<claude|codex|gemini>] [--review] [--allow-self-review] [--routing|--no-routing] [--isolate] [--unsafe] [--timeout=<minutes>] [--decision-policy=<auto|critical>] [--json]> [targetDir]');
+            console.log('usage: yoke loop <on|off|status|decision|answer|resume [--discard] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=<blocking|advisory>] [--quality-unbounded] [--candidates=N]|cleanup [--remove-worktrees] [--discard-stale-recovery]|run [--max=N] [--parallel=N] [--runner=<claude|codex|gemini>] [--reviewer=<claude|codex|gemini>] [--review] [--allow-self-review] [--routing|--no-routing] [--isolate] [--unsafe] [--timeout=<minutes>] [--decision-policy=<auto|critical>] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=<blocking|advisory>] [--quality-unbounded] [--candidates=N] [--json]> [targetDir]');
             return 1;
         }
         case 'new': {
@@ -430,7 +516,7 @@ export function main(argv) {
         case 'upgrade':
             return runUpgrade();
         default:
-            console.log('usage: yoke <setup [dir] | new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=claude,codex,gemini|all] [--code-graph=graphify|serena] [--loop] | prd <draft|check> [dir] | loop <on|off|status|decision|answer|resume|run|cleanup> | context <init|status> | review [dir] [--reviewer=<claude|codex|gemini>] [--base=<ref>] [--focus="..."] | design-scan [dir] [--max=N] [--report] | flow-smoke [dir] [--url=<baseUrl>] [--label=<name>] | upgrade>');
+            console.log('usage: yoke <setup [dir] | new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=claude,codex,gemini|all] [--code-graph=graphify|serena] [--loop] | change <add|status> [dir] | prd <draft|check> [dir] | loop <on|off|status|decision|answer|resume|run|cleanup> | context <init|status> | review [dir] [--reviewer=<claude|codex|gemini>] [--base=<ref>] [--focus="..."] | design-scan [dir] [--max=N] [--report] | flow-smoke [dir] [--url=<baseUrl>] [--label=<name>] | upgrade>');
             return cmd ? 1 : 0;
     }
 }

package/dist/loop/candidate-boundaries.js

@@ -0,0 +1,43 @@
+import { posix, win32 } from 'node:path';
+import { z } from 'zod';
+const CandidateEvidenceSchema = z.object({
+    digest: z.string().min(1),
+    artifacts: z.array(z.string()),
+});
+const CandidateIdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+export function candidateConfigProblem(input) {
+    if (!Number.isInteger(input.maxCandidates) || input.maxCandidates < 1 || input.maxCandidates > 5) {
+        return 'maxCandidates must be an integer from 1 to 5';
+    }
+    if (input.candidates.length === 0)
+        return 'at least one candidate is required';
+    if (input.candidates.some(candidate => !CandidateIdSchema.safeParse(candidate.id).success)) {
+        return 'candidate ids must be non-empty safe identifiers';
+    }
+    if (new Set(input.candidates.map(candidate => candidate.id)).size !== input.candidates.length) {
+        return 'candidate ids must be unique';
+    }
+    return null;
+}
+export function parseCandidateEvidence(value) {
+    const parsed = CandidateEvidenceSchema.parse(value);
+    return { digest: parsed.digest, artifacts: [...parsed.artifacts] };
+}
+export function canonicalWorktreePath(path, platform) {
+    if (platform === 'win32') {
+        if (!/^(?:[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/][^\\/]+)/.test(path))
+            return null;
+        const normalized = win32.normalize(path).replaceAll('/', '\\').toLowerCase();
+        return trimSeparators(normalized, win32.parse(normalized).root, '\\');
+    }
+    if (!posix.isAbsolute(path))
+        return null;
+    const normalized = posix.normalize(path);
+    return trimSeparators(normalized, posix.parse(normalized).root, '/');
+}
+function trimSeparators(path, root, separator) {
+    let key = path;
+    while (key.length > root.length && key.endsWith(separator))
+        key = key.slice(0, -1);
+    return key;
+}

package/dist/loop/candidate-cleanup.js

@@ -0,0 +1,98 @@
+const stageOrder = ['cancel', 'reap', 'remove'];
+export class CandidateCleanup {
+    lifecycle;
+    onLifecycle;
+    #states = new Map();
+    constructor(lifecycle, onLifecycle) {
+        this.lifecycle = lifecycle;
+        this.onLifecycle = onLifecycle;
+    }
+    register(ownership) {
+        this.#states.set(ownership.candidateId, { ownership, materialized: false, completed: new Set(), failed: new Map(), pending: new Map() });
+    }
+    markMaterialized(candidateId) {
+        const state = this.#states.get(candidateId);
+        if (state)
+            state.materialized = true;
+    }
+    cancelNow(reason) {
+        for (const state of this.#states.values()) {
+            state.ownership.controller.abort(reason);
+            this.onLifecycle?.(state.ownership, 'cleaning', reason);
+            void this.#runStage(state, 'cancel', () => this.lifecycle.cancel(state.ownership, reason));
+        }
+    }
+    async cleanup(ownership, reason) {
+        const state = this.#states.get(ownership.candidateId);
+        if (!state)
+            return;
+        ownership.controller.abort(reason);
+        this.onLifecycle?.(ownership, 'cleaning', reason);
+        if (!await this.#runStage(state, 'cancel', () => this.lifecycle.cancel(ownership, reason)))
+            return;
+        if (!await this.#runStage(state, 'reap', () => this.lifecycle.reap(ownership)))
+            return;
+        if (await this.#runStage(state, 'remove', () => this.lifecycle.remove(ownership)))
+            this.onLifecycle?.(ownership, 'removed', reason);
+    }
+    async cleanupAll(reason, keepCandidateId) {
+        for (const state of this.#states.values()) {
+            if (state.ownership.candidateId !== keepCandidateId)
+                await this.cleanup(state.ownership, reason);
+        }
+    }
+    hasFailures() {
+        return [...this.#states.values()].some(state => state.failed.size > 0);
+    }
+    failureSummary() {
+        return this.recovery().flatMap(item => item.failedStages.map(failure => `${item.ownership.candidateId}:${failure.stage}: ${failure.summary}`)).join('; ');
+    }
+    recovery() {
+        return [...this.#states.values()].filter(state => state.failed.size > 0).map(state => ({
+            ownership: {
+                candidateId: state.ownership.candidateId,
+                coordinatorId: state.ownership.coordinatorId,
+                ownerToken: state.ownership.ownerToken,
+                storyId: state.ownership.storyId,
+                provider: { ...state.ownership.provider },
+                worktree: { ...state.ownership.worktree },
+            },
+            materialized: state.materialized,
+            completedStages: stageOrder.filter(stage => state.completed.has(stage)),
+            failedStages: stageOrder.flatMap(stage => {
+                const summary = state.failed.get(stage);
+                return summary ? [{ stage, summary }] : [];
+            }),
+            pendingStages: stageOrder.filter(stage => !state.completed.has(stage) && !state.failed.has(stage)),
+        }));
+    }
+    #runStage(state, stage, operation) {
+        if (state.completed.has(stage))
+            return Promise.resolve(true);
+        const pending = state.pending.get(stage);
+        if (pending)
+            return pending.then(() => state.completed.has(stage));
+        try {
+            const result = operation();
+            if (!(result instanceof Promise)) {
+                state.completed.add(stage);
+                state.failed.delete(stage);
+                return Promise.resolve(true);
+            }
+            const task = result.then(() => {
+                state.completed.add(stage);
+                state.failed.delete(stage);
+            }).catch(error => {
+                state.failed.set(stage, error instanceof Error ? error.message : String(error));
+            }).finally(() => {
+                state.pending.delete(stage);
+            });
+            state.pending.set(stage, task);
+            return task.then(() => state.completed.has(stage));
+        }
+        catch (error) {
+            state.failed.set(stage, error instanceof Error ? error.message : String(error));
+            return Promise.resolve(false);
+        }
+    }
+}

package/dist/loop/candidate-contracts.js

@@ -0,0 +1 @@
+export {};