@hecer/yoke 1.3.0 → 1.5.0

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.5.0
 TARGET=$(git rev-parse HEAD)
 git fetch --tags origin