@hecer/yoke 1.2.1 → 1.4.0

package/dist/quality/reference.js

@@ -0,0 +1,187 @@
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { hasShellControlOperator as containsShellControlOperator, parseQualityCommand } from './process-command.js';
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+const DEFAULT_MAX_REDIRECTS = 3;
+export function hasShellControlOperator(command) {
+    return containsShellControlOperator(command);
+}
+export function acquireReference(input, adapters) {
+    const bytesResult = acquireBytes(input, adapters);
+    if (bytesResult.kind === 'rejected')
+        return bytesResult;
+    if (bytesResult.content.bytes.byteLength > (input.maxBytes ?? DEFAULT_MAX_BYTES)) {
+        return { kind: 'rejected', reason: 'oversize' };
+    }
+    const digest = createHash('sha256').update(bytesResult.content.bytes).digest('hex');
+    if (input.reference.digest && normalizeDigest(input.reference.digest) !== digest) {
+        return { kind: 'rejected', reason: 'digest-mismatch' };
+    }
+    const referencesDir = join(resolve(input.projectDir), '.yoke', 'references');
+    const storagePath = join(referencesDir, digest);
+    const provenance = {
+        kind: input.reference.kind,
+        source: input.reference.source,
+        acquiredAt: (input.now ?? (() => new Date().toISOString()))(),
+        ...(bytesResult.content.contentType ? { contentType: bytesResult.content.contentType } : {}),
+        byteSize: bytesResult.content.bytes.byteLength,
+        sha256: digest,
+        adapterVersion: adapters.version ?? 'unknown',
+        ...(bytesResult.content.parameters ? { parameters: bytesResult.content.parameters } : {}),
+    };
+    adapters.mkdir(storagePath);
+    adapters.writeFile(join(storagePath, 'content'), bytesResult.content.bytes);
+    adapters.writeFile(join(storagePath, 'provenance.json'), new TextEncoder().encode(JSON.stringify(provenance)));
+    return {
+        kind: 'acquired',
+        artifact: {
+            name: input.reference.name,
+            digest,
+            bytes: bytesResult.content.bytes.byteLength,
+            storagePath,
+            provenance,
+        },
+    };
+}
+function acquireBytes(input, adapters) {
+    if (input.reference.kind === 'file')
+        return acquireFile(input, adapters);
+    if (input.reference.kind === 'command')
+        return acquireCommand(input, adapters);
+    return acquireUrl(input, adapters);
+}
+function acquireFile(input, adapters) {
+    const source = input.reference.source;
+    if (containsTraversal(source))
+        return { kind: 'rejected', reason: 'path-traversal' };
+    if (isAbsolute(source))
+        return { kind: 'rejected', reason: 'outside-project' };
+    const projectRoot = resolve(input.projectDir);
+    const path = resolve(projectRoot, source);
+    if (!isInside(projectRoot, path))
+        return { kind: 'rejected', reason: 'outside-project' };
+    const canonicalRoot = adapters.realpath?.(projectRoot) ?? projectRoot;
+    const canonicalPath = adapters.realpath?.(path) ?? path;
+    if (!isInside(canonicalRoot, canonicalPath))
+        return { kind: 'rejected', reason: 'outside-project' };
+    const bytes = adapters.readFile(canonicalPath);
+    return bytes === null ? { kind: 'rejected', reason: 'missing' } : { kind: 'bytes', content: normalizeContent(bytes) };
+}
+function acquireCommand(input, adapters) {
+    if (hasShellControlOperator(input.reference.source))
+        return { kind: 'rejected', reason: 'shell-control' };
+    if (!parseQualityCommand(input.reference.source))
+        return { kind: 'rejected', reason: 'invalid-command' };
+    return { kind: 'bytes', content: normalizeContent(adapters.runCommand(input.reference.source)) };
+}
+function acquireUrl(input, adapters) {
+    let current = input.reference.source;
+    let redirects = 0;
+    const maxRedirects = input.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    for (;;) {
+        if (!URL.canParse(current))
+            return { kind: 'rejected', reason: 'invalid-url' };
+        const url = new URL(current);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return { kind: 'rejected', reason: 'unsupported-protocol' };
+        }
+        const addressResult = validateAddress(url.hostname, input.allowLocal === true, adapters);
+        if (addressResult.kind === 'rejected')
+            return addressResult;
+        const response = adapters.requestUrl(url.toString(), addressResult.addresses);
+        if (response.status >= 300 && response.status < 400) {
+            if (!response.location || !URL.canParse(response.location, url.toString())) {
+                return { kind: 'rejected', reason: 'invalid-redirect' };
+            }
+            if (redirects >= maxRedirects)
+                return { kind: 'rejected', reason: 'redirect-overflow' };
+            current = new URL(response.location, url).toString();
+            redirects += 1;
+            continue;
+        }
+        if (response.status < 200 || response.status >= 300)
+            return { kind: 'rejected', reason: 'http-status' };
+        let content = normalizeContent(response.body);
+        if (mediaType(content.contentType) === 'text/html')
+            content = htmlAsInertText(content);
+        if (content.contentType && !isAllowedUrlContentType(content.contentType)) {
+            return { kind: 'rejected', reason: 'unsupported-content-type' };
+        }
+        return { kind: 'bytes', content };
+    }
+}
+function validateAddress(hostname, allowLocal, adapters) {
+    const normalizedHostname = hostname.replace(/^\[|\]$/g, '');
+    if (!allowLocal && isPrivateAddress(normalizedHostname)) {
+        return { kind: 'rejected', reason: 'private-address' };
+    }
+    const addresses = adapters.resolveHostname(normalizedHostname);
+    if (addresses.length === 0)
+        return { kind: 'rejected', reason: 'unresolved-address' };
+    if (!allowLocal && addresses.some(isPrivateAddress)) {
+        return { kind: 'rejected', reason: 'private-address' };
+    }
+    return { kind: 'validated', addresses };
+}
+function isAllowedUrlContentType(value) {
+    const type = mediaType(value);
+    return type?.startsWith('image/') === true
+        || type === 'text/plain'
+        || type === 'application/json'
+        || type === 'application/pdf'
+        || type === 'application/octet-stream';
+}
+function mediaType(value) {
+    return value?.split(';', 1)[0]?.trim().toLowerCase();
+}
+function htmlAsInertText(content) {
+    const html = new TextDecoder().decode(content.bytes);
+    const text = html
+        .replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/giu, ' ')
+        .replace(/<!--[\s\S]*?-->/gu, ' ')
+        .replace(/<[^>]+>/gu, ' ')
+        .replace(/&nbsp;/giu, ' ')
+        .replace(/&amp;/giu, '&')
+        .replace(/&lt;/giu, '<')
+        .replace(/&gt;/giu, '>')
+        .replace(/&quot;/giu, '"')
+        .replace(/\s+/gu, ' ')
+        .trim();
+    return { bytes: new TextEncoder().encode(text), contentType: 'text/plain', ...(content.parameters ? { parameters: content.parameters } : {}) };
+}
+function containsTraversal(path) {
+    return path.split(/[\\/]+/).includes('..');
+}
+function normalizeContent(content) {
+    return content instanceof Uint8Array ? { bytes: content } : content;
+}
+function normalizeDigest(value) {
+    return value.replace(/^sha256:/i, '').toLowerCase();
+}
+function isInside(root, path) {
+    const relativePath = relative(root, path);
+    return relativePath === '' || (!relativePath.startsWith(`..${sep}`) && relativePath !== '..' && !isAbsolute(relativePath));
+}
+function isPrivateAddress(value) {
+    const address = value.toLowerCase();
+    if (address === 'localhost' || address.endsWith('.localhost') || address === '::1' || address === '::')
+        return true;
+    if (address.startsWith('fc') || address.startsWith('fd') || address.startsWith('fe80:'))
+        return true;
+    if (address.startsWith('::ffff:'))
+        return isPrivateAddress(address.slice('::ffff:'.length));
+    const octets = address.split('.');
+    if (octets.length !== 4 || octets.some(octet => !/^\d+$/.test(octet)))
+        return false;
+    const numbers = octets.map(Number);
+    if (numbers.some(number => number < 0 || number > 255))
+        return false;
+    const [first, second] = numbers;
+    return first === 0
+        || first === 10
+        || first === 127
+        || (first === 100 && second >= 64 && second <= 127)
+        || (first === 169 && second === 254)
+        || (first === 172 && second >= 16 && second <= 31)
+        || (first === 192 && second === 168);
+}

package/dist/quality/repair.js

@@ -0,0 +1,11 @@
+export function authorizeRepair(input) {
+    if (input.limits?.unbounded)
+        return { kind: 'authorized', round: input.usedRounds + 1 };
+    const maxRounds = input.limits?.maxRounds ?? 3;
+    const maxMinutes = input.limits?.maxMinutes ?? 60;
+    if (input.usedRounds >= maxRounds)
+        return { kind: 'blocked', reason: 'round-budget-exhausted' };
+    if (input.elapsedMs >= maxMinutes * 60 * 1000)
+        return { kind: 'blocked', reason: 'time-budget-exhausted' };
+    return { kind: 'authorized', round: input.usedRounds + 1 };
+}

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(),
@@ -53,17 +54,25 @@ export const YokeConfigSchema = z.object({
         suppressionsVersion: z.literal(1).optional(),
         suppressions: z.array(z.object({ ruleId: z.string().min(1), file: z.string().min(1).optional(), reason: z.string(), expires: z.string().optional() })).optional(),
     }).optional(),
-    verify: z.object({ command: z.string().min(1), retries: z.number().int().nonnegative().optional() }).optional(),
+    verify: z.object({
+        command: z.string().min(1).optional(),
+        retries: z.number().int().nonnegative().optional(),
+        requireCriteria: z.boolean().optional(),
+    }).optional(),
+    // Runs only when no open stories remain. This proves the current integrated
+    // system, without introducing release objects or a persistent stale graph.
+    completion: z.object({ command: z.string().min(1), retries: z.number().int().nonnegative().optional() }).optional(),
     // Optional performance budget gate: a benchmark command that must exit 0 for a
     // story to land (runs after verify). Benchmarks are noisy → retried like verify.
     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(),
 });
 export function defaultConfig(canonVersion) {
-    return { canonVersion, agents: [], loop: { enabled: false } };
+    return { canonVersion, agents: [], loop: { enabled: false }, verify: { requireCriteria: true } };
 }
 export function configPath(targetDir) {
     return join(targetDir, '.yoke', 'config.yaml');

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,8 @@ 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)';
 // Idempotently ensure each Yoke runtime path is gitignored. Appends only the

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;
 }