@hecer/yoke 1.3.0 → 1.4.0

package/dist/quality/runner.js

@@ -0,0 +1,66 @@
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseProviderResult } from '../agents/telemetry.js';
+import { storyPathSegment } from '../loop/prd.js';
+import { reduceComparisons } from './verdict.js';
+export function runQualityCritic(input) {
+    const segment = input.evidenceScope ? `${input.evidenceScope}-round-${input.round}` : `round-${input.round}`;
+    const root = join(input.targetDir, '.yoke', 'proof', storyPathSegment(input.storyId), 'quality', segment);
+    input.mkdir(root);
+    const first = input.firstLabel();
+    const second = first === 'A' ? 'B' : 'A';
+    const attemptPrefix = input.attemptIdPrefix ?? String(input.round);
+    const normalRequest = request(input, `${attemptPrefix}-normal`, first);
+    const swappedRequest = request(input, `${attemptPrefix}-swapped`, second);
+    const normal = input.invoke(structuredClone(normalRequest));
+    if (!normal.ok)
+        return { kind: 'infrastructure', summary: normal.summary };
+    const swapped = input.invoke(structuredClone(swappedRequest));
+    if (!swapped.ok)
+        return { kind: 'infrastructure', summary: swapped.summary };
+    if (normal.actualModel && swapped.actualModel && normal.actualModel !== swapped.actualModel)
+        return { kind: 'infrastructure', summary: `critic model changed between comparisons: ${normal.actualModel} -> ${swapped.actualModel}` };
+    const actualModel = normal.actualModel ?? swapped.actualModel ?? input.model;
+    if (!actualModel)
+        return { kind: 'infrastructure', summary: 'critic did not report its model and no explicit model was configured' };
+    const expected = {
+        normal: expectation(normalRequest),
+        swapped: expectation(swappedRequest),
+        provenance: { provider: input.provider, model: actualModel },
+    };
+    input.writeFile(join(root, 'normal.verdict.json'), JSON.stringify({ provider: input.provider, model: actualModel, raw: normal.output }));
+    input.writeFile(join(root, 'swapped.verdict.json'), JSON.stringify({ provider: input.provider, model: actualModel, raw: swapped.output }));
+    const reduction = reduceComparisons({
+        expected,
+        normal: parseProviderResult(input.provider, normal.output),
+        swapped: parseProviderResult(input.provider, swapped.output),
+    });
+    return input.policy === 'advisory' ? { kind: 'skipped', summary: 'advisory comparison recorded' } : reduction;
+}
+function request(input, attemptId, candidateLabel) {
+    const issued = {
+        permissions: 'read-only',
+        attemptId,
+        candidateLabel,
+        referenceLabel: candidateLabel === 'A' ? 'B' : 'A',
+        trustedRubric: input.rubric,
+        reference: { ...input.reference, artifact: input.reference.artifact ?? 'reference.bin' },
+        candidate: {
+            digests: [...input.candidate.digests],
+            artifacts: input.candidate.artifacts ? [...input.candidate.artifacts] : input.candidate.digests.map((_, index) => `candidate-${index + 1}.bin`),
+        },
+    };
+    return { ...issued, promptDigest: digest(JSON.stringify(issued)), rubricDigest: digest(input.rubric) };
+}
+function expectation(request) {
+    return {
+        attemptId: request.attemptId,
+        candidateDigests: [...request.candidate.digests],
+        referenceDigest: request.reference.digest,
+        promptDigest: request.promptDigest,
+        rubricDigest: request.rubricDigest,
+    };
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}

package/dist/quality/types.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+const QualityPolicySchema = z.enum(['blocking', 'advisory']);
+const QualityAgentSchema = z.enum(['claude', 'codex', 'gemini']);
+const RelativePathSchema = z.string().min(1).refine(value => !/^(?:[A-Za-z]:[\\/]|[\\/])/.test(value) && !value.split(/[\\/]+/).includes('..'), 'path must stay within the project');
+const QualityReferenceSchema = z.object({
+    name: z.string().min(1),
+    source: z.string().min(1),
+    kind: z.enum(['url', 'file', 'command']),
+    digest: z.string().min(1).optional(),
+}).superRefine((value, context) => {
+    if (value.kind === 'file' && !RelativePathSchema.safeParse(value.source).success)
+        context.addIssue({ code: 'custom', path: ['source'], message: 'file reference must stay within the project' });
+});
+const QualityCandidateSchema = z.union([
+    z.object({ kind: z.enum(['screenshots', 'files']), paths: z.array(RelativePathSchema).min(1) }),
+    z.object({ kind: z.enum(['command-output', 'benchmark']), command: z.string().min(1) }),
+]);
+export const ProjectQualityDefaultsSchema = z.object({
+    enabled: z.boolean().default(false),
+    policy: QualityPolicySchema.default('blocking'),
+    maxRounds: z.number().int().positive().default(3),
+    maxMinutes: z.number().int().positive().default(60),
+    consistencyChecks: z.literal(2).default(2),
+    maxParallelCandidates: z.number().int().positive().default(2),
+    criticAgent: QualityAgentSchema.optional(),
+    criticModel: z.string().min(1).optional(),
+    criticReasoningEffort: z.string().min(1).optional(),
+    repairAgent: QualityAgentSchema.optional(),
+    repairModel: z.string().min(1).optional(),
+    repairReasoningEffort: z.string().min(1).optional(),
+    critic: z.object({
+        agent: QualityAgentSchema.optional(),
+        model: z.string().min(1).optional(),
+        reasoningEffort: z.string().min(1).optional(),
+    }).optional(),
+    repair: z.object({
+        agent: QualityAgentSchema.optional(),
+        model: z.string().min(1).optional(),
+        reasoningEffort: z.string().min(1).optional(),
+    }).optional(),
+});
+export const StoryQualityDeclarationSchema = z.object({
+    reference: QualityReferenceSchema,
+    candidate: QualityCandidateSchema,
+    rubric: z.string().min(1),
+    policy: QualityPolicySchema.optional(),
+});
+export function resolveQualityPolicy(input) {
+    const overrides = input.overrides;
+    const unbounded = overrides?.qualityUnbounded === true;
+    const enabled = input.declaration !== undefined && (unbounded || (overrides?.quality ?? input.defaults?.enabled ?? false));
+    const policy = overrides?.qualityPolicy ?? input.declaration?.policy ?? input.defaults?.policy ?? 'blocking';
+    const maxRounds = overrides?.qualityRounds ?? input.defaults?.maxRounds ?? 3;
+    const maxMinutes = overrides?.qualityMinutes ?? input.defaults?.maxMinutes ?? 60;
+    return {
+        enabled,
+        policy,
+        limits: unbounded ? { unbounded: true } : { maxRounds, maxMinutes },
+    };
+}

package/dist/quality/verdict.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+export const QualityLabelSchema = z.enum(['A', 'B']);
+const DigestSchema = z.string().min(1);
+const ComparedArtifactSchema = z.object({ label: QualityLabelSchema, digest: DigestSchema });
+const ProvenanceSchema = z.object({
+    provider: z.string().min(1),
+    model: z.string().min(1),
+    promptDigest: DigestSchema,
+    rubricDigest: DigestSchema,
+    referenceDigest: DigestSchema,
+    candidateDigest: DigestSchema,
+});
+export const QualityVerdictSchema = z.object({
+    schemaVersion: z.literal(1),
+    attemptId: z.string().min(1),
+    winner: z.enum(['candidate', 'reference']),
+    biggestGap: z.string().min(1),
+    evidence: z.array(z.string().min(1)).min(1),
+    confidence: z.enum(['high', 'medium', 'low']),
+    candidate: ComparedArtifactSchema,
+    reference: ComparedArtifactSchema,
+    provenance: ProvenanceSchema,
+}).superRefine((value, context) => {
+    if (value.candidate.label === value.reference.label) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: 'candidate and reference labels must differ' });
+    }
+    if (value.candidate.digest !== value.provenance.candidateDigest || value.reference.digest !== value.provenance.referenceDigest) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: 'artifact digests must match provenance' });
+    }
+});
+const CandidatePairVerdictSchema = z.object({
+    schemaVersion: z.literal(1),
+    attemptId: z.string().min(1),
+    winner: QualityLabelSchema,
+    evidence: z.array(z.string().min(1)).min(1),
+    confidence: z.enum(['high', 'medium', 'low']),
+    left: ComparedArtifactSchema,
+    right: ComparedArtifactSchema,
+    provenance: z.object({
+        leftDigest: DigestSchema,
+        rightDigest: DigestSchema,
+        provider: z.string().min(1),
+        model: z.string().min(1),
+        promptDigest: DigestSchema,
+        rubricDigest: DigestSchema,
+    }),
+}).superRefine((value, context) => {
+    if (value.left.label === value.right.label) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: 'candidate labels must differ' });
+    }
+    if (value.left.digest !== value.provenance.leftDigest || value.right.digest !== value.provenance.rightDigest) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: 'candidate digests must match provenance' });
+    }
+});
+export function assignBlindLabels(selectCandidateLabel) {
+    const candidate = selectCandidateLabel();
+    return { candidate, reference: candidate === 'A' ? 'B' : 'A' };
+}
+export function reduceComparisons(input) {
+    const normal = QualityVerdictSchema.safeParse(input.normal);
+    const swapped = QualityVerdictSchema.safeParse(input.swapped);
+    if (!normal.success || !swapped.success)
+        return { kind: 'inconsistent', reason: 'invalid-verdict' };
+    if (normal.data.attemptId === swapped.data.attemptId)
+        return { kind: 'inconsistent', reason: 'not-fresh' };
+    if (normal.data.attemptId !== input.expected.normal.attemptId || swapped.data.attemptId !== input.expected.swapped.attemptId) {
+        return { kind: 'inconsistent', reason: 'attempt-mismatch' };
+    }
+    if (normal.data.candidate.label === swapped.data.candidate.label || normal.data.reference.label === swapped.data.reference.label) {
+        return { kind: 'inconsistent', reason: 'labels-not-swapped' };
+    }
+    if (normal.data.candidate.digest !== swapped.data.candidate.digest || normal.data.reference.digest !== swapped.data.reference.digest) {
+        return { kind: 'inconsistent', reason: 'digest-mismatch' };
+    }
+    if (!input.expected.normal.candidateDigests.includes(normal.data.candidate.digest)
+        || !input.expected.swapped.candidateDigests.includes(swapped.data.candidate.digest)
+        || normal.data.reference.digest !== input.expected.normal.referenceDigest
+        || swapped.data.reference.digest !== input.expected.swapped.referenceDigest) {
+        return { kind: 'inconsistent', reason: 'digest-mismatch' };
+    }
+    if (normal.data.provenance.provider !== input.expected.provenance.provider
+        || swapped.data.provenance.provider !== input.expected.provenance.provider
+        || normal.data.provenance.model !== input.expected.provenance.model
+        || swapped.data.provenance.model !== input.expected.provenance.model
+        || normal.data.provenance.promptDigest !== input.expected.normal.promptDigest
+        || swapped.data.provenance.promptDigest !== input.expected.swapped.promptDigest
+        || normal.data.provenance.rubricDigest !== input.expected.normal.rubricDigest
+        || swapped.data.provenance.rubricDigest !== input.expected.swapped.rubricDigest) {
+        return { kind: 'inconsistent', reason: 'provenance-mismatch' };
+    }
+    if (normal.data.winner !== swapped.data.winner)
+        return { kind: 'inconsistent', reason: 'winner-disagrees' };
+    if (normal.data.winner === 'reference') {
+        return { kind: 'lose', reason: 'reference-selected', biggestGap: normal.data.biggestGap, evidence: normal.data.evidence };
+    }
+    if (normal.data.confidence === 'low' || swapped.data.confidence === 'low') {
+        return { kind: 'lose', reason: 'low-confidence', biggestGap: normal.data.biggestGap, evidence: normal.data.evidence };
+    }
+    return {
+        kind: 'pass',
+        candidateDigest: normal.data.candidate.digest,
+        referenceDigest: normal.data.reference.digest,
+    };
+}
+export function reduceCandidatePairComparisons(input) {
+    const normal = CandidatePairVerdictSchema.safeParse(input.normal);
+    const swapped = CandidatePairVerdictSchema.safeParse(input.swapped);
+    if (!normal.success || !swapped.success)
+        return { kind: 'inconsistent', reason: 'invalid-verdict' };
+    const normalMismatch = candidatePairMismatch(normal.data, input.expected.normal);
+    if (normalMismatch)
+        return { kind: 'inconsistent', reason: normalMismatch };
+    const swappedMismatch = candidatePairMismatch(swapped.data, input.expected.swapped);
+    if (swappedMismatch)
+        return { kind: 'inconsistent', reason: swappedMismatch };
+    if (normal.data.confidence === 'low' || swapped.data.confidence === 'low') {
+        return { kind: 'inconsistent', reason: 'low-confidence' };
+    }
+    const normalWinner = normal.data.winner === normal.data.left.label
+        ? { candidateId: input.expected.normal.candidateIds.left, digest: input.expected.normal.request.left.digest }
+        : { candidateId: input.expected.normal.candidateIds.right, digest: input.expected.normal.request.right.digest };
+    const swappedWinner = swapped.data.winner === swapped.data.left.label
+        ? { candidateId: input.expected.swapped.candidateIds.left, digest: input.expected.swapped.request.left.digest }
+        : { candidateId: input.expected.swapped.candidateIds.right, digest: input.expected.swapped.request.right.digest };
+    return normalWinner.candidateId === swappedWinner.candidateId && normalWinner.digest === swappedWinner.digest
+        ? { kind: 'selected', winnerCandidateId: normalWinner.candidateId, winnerDigest: normalWinner.digest, normal: normal.data, swapped: swapped.data }
+        : { kind: 'inconsistent', reason: 'winner-disagrees' };
+}
+function candidatePairMismatch(verdict, expected) {
+    if (verdict.attemptId !== expected.request.attemptId)
+        return 'attempt-mismatch';
+    if (verdict.left.label !== expected.request.left.label || verdict.right.label !== expected.request.right.label)
+        return 'label-mismatch';
+    if (verdict.left.digest !== expected.request.left.digest || verdict.right.digest !== expected.request.right.digest)
+        return 'digest-mismatch';
+    if (verdict.provenance.provider !== expected.provenance.provider
+        || verdict.provenance.model !== expected.provenance.model
+        || verdict.provenance.promptDigest !== expected.provenance.promptDigest
+        || verdict.provenance.rubricDigest !== expected.provenance.rubricDigest)
+        return 'provenance-mismatch';
+    return null;
+}

package/dist/retrofit/config.js

@@ -2,7 +2,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { parse, stringify } from 'yaml';
 import { z } from 'zod';
-const AgentSchema = z.enum(['claude', 'codex', 'gemini']);
+import { AgentSchema, PermissionProfileSchema } from '../agents/contracts.js';
+import { ProjectQualityDefaultsSchema } from '../quality/types.js';
 const CodeGraphSchema = z.enum(['graphify', 'serena']);
 const SmokeFlowSchema = z.object({ name: z.string().min(1), path: z.string().min(1), landmark: z.string().optional() });
 const SmokeSchema = z.object({ baseUrl: z.string().min(1), flows: z.array(SmokeFlowSchema).min(1) });
@@ -30,7 +31,7 @@ export const YokeConfigSchema = z.object({
         model: z.string().min(1).optional(),
         reasoningEffort: z.string().min(1).optional(),
         bare: z.boolean().optional(),
-        permissions: z.enum(['safe', 'unsafe', 'read-only']).optional(),
+        permissions: PermissionProfileSchema.optional(),
     }).optional(),
     routing: z.object({
         enabled: z.boolean(),
@@ -66,6 +67,7 @@ export const YokeConfigSchema = z.object({
     perf: z.object({ command: z.string().min(1), retries: z.number().int().nonnegative().optional() }).optional(),
     codeGraph: CodeGraphSchema.optional(),
     smoke: SmokeSchema.optional(),
+    quality: ProjectQualityDefaultsSchema.optional(),
     // Opt-in: upgrade yoke at loop START when a newer version is cached (never mid-run).
     update: z.object({ auto: z.boolean() }).optional(),
 });

package/dist/retrofit/gitignore.js

@@ -11,6 +11,8 @@ export const YOKE_IGNORE_LINES = [
     '.yoke/loop.lock.*.tmp',
     '.yoke/loop.pause',
     '.yoke/runner.pid',
+    '.yoke/provider-processes/',
+    '.yoke/claims/',
     '.yoke/ambiguity.md',
     '.yoke/decision-request.yaml',
     '.yoke/pending-decision.yaml',
@@ -19,6 +21,7 @@ export const YOKE_IGNORE_LINES = [
     '.yoke/decision-*.yaml.*.tmp',
     '.yoke/story-durations.json',
     '.yoke/proof/',
+    '.yoke/references/',
     '.yoke/changes/',
 ];
 const HEADER = '# Yoke runtime artifacts (managed by yoke retrofit)';

package/dist/review/command.js

@@ -1,9 +1,8 @@
-import { agentInvocation, buildStandaloneReviewPrompt, buildWatchdogInvocation, runReviewAgent, isAgentAvailable, } from '../loop/runner.js';
+import { agentInvocation, buildStandaloneReviewPrompt, buildWatchdogInvocation, runCapturedAgent, repositoryFingerprint, isAgentAvailable, } from '../loop/runner.js';
+import { parseProviderResult } from '../agents/telemetry.js';
 import { resolveIdleMs } from '../loop/run-command.js';
-import { existsSync, mkdirSync, rmSync, rmdirSync } from 'node:fs';
-import { join } from 'node:path';
 import { loadConfig } from '../retrofit/config.js';
-import { readReviewVerdict, reviewVerdictPath } from './verdict.js';
+import { parseReviewVerdict } from './verdict.js';
 // Resolve to the first available agent, preferring a *second* model so the review
 // is genuinely cross-model. claude last => a Claude-only box degrades to self-review.
 const RESOLUTION_ORDER = ['codex', 'gemini', 'claude'];
@@ -33,51 +32,41 @@ export function runReview(targetDir, opts = {}) {
     const scope = opts.base
         ? `the diff ${opts.base}..HEAD`
         : 'the uncommitted working-tree changes (working tree + staged)';
-    const verdictPath = reviewVerdictPath(targetDir);
-    const yokeDir = join(targetDir, '.yoke');
-    const createdYokeDir = !existsSync(yokeDir);
-    mkdirSync(yokeDir, { recursive: true });
-    rmSync(verdictPath, { force: true });
-    const prompt = buildStandaloneReviewPrompt(scope, opts.focus, verdictPath);
+    const prompt = buildStandaloneReviewPrompt(scope, opts.focus, undefined, reviewer);
     const idleMs = resolveIdleMs(opts.timeoutMinutes, undefined);
     // Pass the *agent* invocation to the runner so callers (and tests) see the
     // reviewer command. The default runner adds the watchdog wrapper before exec;
     // an injected run() gets the raw invocation.
-    const inv = agentInvocation(reviewer, prompt, targetDir, 'safe');
+    const inv = agentInvocation(reviewer, prompt, targetDir, 'read-only');
     const say = opts.json ? console.error : console.log;
     say(`Reviewing ${scope} with ${reviewer}...`);
-    const run = opts.run ?? ((i) => runReviewAgent(buildWatchdogInvocation(i, idleMs)));
+    const before = repositoryFingerprint(targetDir);
+    const run = opts.run ?? ((i) => runCapturedAgent(reviewer, buildWatchdogInvocation(i, idleMs)));
     const processResult = run(inv);
-    let verdict;
-    try {
-        verdict = readReviewVerdict(verdictPath);
-    }
-    catch (error) {
-        say(`✗ ${reviewer} produced no valid verdict (${error.message})${processResult.success ? '' : `; process: ${processResult.summary}`}`);
-        if (createdYokeDir) {
-            try {
-                rmdirSync(yokeDir);
-            }
-            catch { }
-        }
+    if (repositoryFingerprint(targetDir) !== before) {
+        say(`✗ ${reviewer} modified the repository during a read-only review`);
         return 1;
     }
-    if (createdYokeDir) {
-        try {
-            rmdirSync(yokeDir);
+    try {
+        const actualModel = opts.run ? undefined : processResult.tokens?.model;
+        if (!opts.run && processResult.success && !actualModel)
+            throw new Error('review provider did not report its model');
+        const verdict = parseReviewVerdict(parseProviderResult(reviewer, processResult.output), { provider: reviewer, ...(actualModel ? { model: actualModel } : {}) });
+        if (opts.json)
+            console.log(JSON.stringify({ reviewer, process: processResult, verdict }));
+        if (!processResult.success) {
+            say(`✗ ${reviewer} process failed (${processResult.summary}); verdict: ${verdict.summary}`);
+            return 1;
         }
-        catch { }
-    }
-    if (opts.json)
-        console.log(JSON.stringify({ reviewer, process: processResult, verdict }));
-    if (!processResult.success) {
-        say(`✗ ${reviewer} process failed (${processResult.summary}); verdict: ${verdict.summary}`);
+        if (verdict.approved) {
+            say(`✓ ${reviewer} approved: ${verdict.summary}`);
+            return 0;
+        }
+        say(`✗ ${reviewer} rejected: ${verdict.summary}`);
         return 1;
     }
-    if (verdict.approved) {
-        say(`✓ ${reviewer} approved: ${verdict.summary}`);
-        return 0;
+    catch (error) {
+        say(`✗ ${reviewer} produced no valid verdict (${error.message})${processResult.success ? '' : `; process: ${processResult.summary}`}`);
+        return 1;
     }
-    say(`✗ ${reviewer} rejected: ${verdict.summary}`);
-    return 1;
 }

package/dist/review/verdict.js

@@ -1,21 +1,49 @@
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { z } from 'zod';
+import { AgentSchema, PermissionProfileSchema } from '../agents/contracts.js';
 export const ReviewFindingSchema = z.object({
+    id: z.string().min(1).optional(),
     severity: z.enum(['blocking', 'warning', 'info']),
     message: z.string().min(1),
     file: z.string().min(1).optional(),
     line: z.number().int().positive().optional(),
+    actionable: z.boolean().optional(),
+    suggestedFix: z.string().min(1).optional(),
+    evidence: z.array(z.string().min(1)).optional(),
 });
 export const ReviewVerdictSchema = z.object({
+    schemaVersion: z.literal(1),
     approved: z.boolean(),
     summary: z.string().min(1),
     findings: z.array(ReviewFindingSchema),
+    provenance: z.object({
+        provider: AgentSchema,
+        model: z.string().min(1),
+        role: z.literal('review'),
+        promptVersion: z.literal(1),
+        permissions: PermissionProfileSchema,
+    }),
 });
+export function parseReviewVerdict(value, expected) {
+    const result = ReviewVerdictSchema.safeParse(value);
+    if (!result.success)
+        throw new Error(`Review verdict is invalid: ${result.error.message}`);
+    if (expected && result.data.provenance.provider !== expected.provider)
+        throw new Error(`Review verdict provider mismatch: expected ${expected.provider}, received ${result.data.provenance.provider}`);
+    if (expected?.model && result.data.provenance.model !== expected.model)
+        throw new Error(`Review verdict model mismatch: expected ${expected.model}, received ${result.data.provenance.model}`);
+    return result.data;
+}
+export function selectRepairFinding(verdict) {
+    if (verdict.approved)
+        return null;
+    return verdict.findings.find(candidate => candidate.severity === 'blocking' && (candidate.actionable ?? true)) ?? null;
+}
 export function reviewVerdictPath(targetDir) {
     return resolve(join(targetDir, '.yoke', 'review-verdict.json'));
 }
-export function readReviewVerdict(path) {
+export function readReviewVerdict(path, expected) {
     if (!existsSync(path))
         throw new Error(`Review verdict is missing: ${path}`);
     try {
@@ -26,20 +54,23 @@ export function readReviewVerdict(path) {
         catch (error) {
             throw new Error(`Review verdict is malformed JSON: ${error.message}`);
         }
-        const result = ReviewVerdictSchema.safeParse(value);
-        if (!result.success)
-            throw new Error(`Review verdict is invalid: ${result.error.message}`);
-        return result.data;
+        return parseReviewVerdict(value, expected);
     }
     finally {
         rmSync(path, { force: true });
     }
 }
-export function formatReviewContract(path) {
+export function formatReviewStdoutContract(provider) {
+    return [
+        'Return exactly one JSON object as your final response. Do not write any file.',
+        `{"schemaVersion":1,"approved":boolean,"summary":"non-empty string","findings":[],"provenance":{"provider":"${provider}","model":"provider-reported model","role":"review","promptVersion":1,"permissions":"read-only"}}`,
+    ].join('\n');
+}
+export function formatReviewContract(path, provider) {
     return [
         `Write your final verdict to this absolute path: ${path}`,
         'The file must contain exactly one JSON object with this contract:',
-        '{"approved":boolean,"summary":"non-empty string","findings":[{"severity":"blocking|warning|info","message":"non-empty string","file":"optional path","line":1}]}',
+        `{"schemaVersion":1,"approved":boolean,"summary":"non-empty string","findings":[{"id":"optional id","severity":"blocking|warning|info","message":"non-empty string","file":"optional path","line":1,"actionable":true,"suggestedFix":"optional repair","evidence":["optional evidence reference"]}],"provenance":{"provider":"${provider ?? 'claude|codex|gemini'}","model":"provider-reported model","role":"review","promptVersion":1,"permissions":"safe"}}`,
         'Set approved=false when any blocking finding exists. Create the file even when the process also exits non-zero.',
     ].join('\n');
 }

package/docs/MIGRATING-TO-1.4.md

@@ -0,0 +1,70 @@
+# Migrating to Yoke 1.4
+
+Yoke 1.4 adds dependency-aware parallel workers, isolated candidate selection, and a reference-driven quality gauntlet. Existing projects remain serial and skip quality comparison unless you opt in.
+
+Upgrade and refresh generated harness files:
+
+```bash
+npm install -g @hecer/yoke@1.4.0
+yoke retrofit .
+```
+
+## Parallel execution
+
+Run dependency-ready stories concurrently with an explicit worker limit:
+
+```bash
+yoke loop run . --isolate --parallel=3
+```
+
+Parallel runs use isolated worktrees, leased claims, and a FIFO integration queue. Every candidate must pass its worker gates and the merged result must pass the project gates again. Adaptive routing is disabled during parallel and multi-candidate runs so each worker has one auditable provider identity.
+
+Use `--candidates=N` to produce and mechanically gate multiple implementations before an identity-blind comparison selects the winner. Candidate mode supports up to five candidates.
+
+## Reference-driven quality
+
+Quality remains disabled by default. A story must declare a trusted reference, candidate artifacts, and a rubric:
+
+```yaml
+quality:
+  reference: { name: approved-home, source: design/home.png, kind: file }
+  candidate: { kind: screenshots, paths: [.yoke/proof/STORY-1/home.png] }
+  rubric: Match the approved layout, hierarchy, spacing, and states.
+  policy: blocking
+```
+
+Project defaults can bound critic and repair work:
+
+```yaml
+quality:
+  enabled: false
+  policy: blocking
+  maxRounds: 3
+  maxMinutes: 60
+  consistencyChecks: 2
+  maxParallelCandidates: 2
+  critic: { agent: codex, model: gpt-5.6-sol }  # model required for --candidates
+  repair: { agent: claude }
+```
+
+Enable it for one run with:
+
+```bash
+yoke loop run . --quality
+```
+
+`consistencyChecks` is fixed at `2`: Yoke runs the swapped-label pair needed to detect identity-sensitive critic output. Advisory mode records both verdicts without blocking; blocking mode permits bounded repairs and reruns all mechanical gates.
+
+## Cleanup behavior
+
+`yoke loop cleanup` now retains Yoke-created worktrees by default so failed candidates remain inspectable. Remove them explicitly when no longer needed:
+
+```bash
+yoke loop cleanup . --remove-worktrees
+```
+
+Cleanup still reaps only provider processes recorded for the current project and removes stale loop locks. It never kills providers by machine-wide process name.
+
+## Review verdicts
+
+Review verdict files now require `schemaVersion: 1` and provenance containing the provider, provider-reported model, review role, prompt version, and permission profile. Custom reviewer integrations must emit the contract printed in the reviewer prompt. Legacy verdict files without this envelope fail closed.

package/docs/PUBLISHING.md

@@ -1,6 +1,6 @@
 # Publishing channels — status & playbook
 
-Where Yoke is published, and how each channel gets updated. (Reviewed 2026-07-30.)
+Where Yoke is published, and how each channel gets updated. (Reviewed 2026-08-15.)
 
 ## Live
 
@@ -14,12 +14,26 @@ Where Yoke is published, and how each channel gets updated. (Reviewed 2026-07-30
 
 ## GitHub release (required, not just a tag)
 
+Before the release commit, update every user-facing version and README statistic, then require the
+same checks npm will run:
+
+```bash
+npm run docs:update
+npm run docs:check
+npm run prepublishOnly
+```
+
+`docs:update` synchronizes the README's package version, test count, skill count, and supported
+agents from `package.json`, Vitest discovery, and `canon/manifest.yaml`. The version must also be
+kept in sync in `package-lock.json`, `canon/manifest.yaml`, `.claude-plugin/plugin.json`,
+`.codex-plugin/plugin.json`, and `gemini-extension.json`.
+
 A pushed tag appears under **Tags**, but GitHub only shows an entry under **Releases** after a
 release object is created. Use this idempotent check after the version commit reaches `main`:
 
 ```bash
 set -euo pipefail
-VERSION=1.1.0
+VERSION=1.4.0
 TARGET=$(git rev-parse HEAD)
 git fetch --tags origin