@hecer/yoke 1.5.1 → 1.6.1

package/dist/prd/command.js

@@ -5,23 +5,23 @@ import { acceptanceText, criterionCommandProblem, isAcceptanceCriterion, loadPrd
 import { agentInvocation, buildWatchdogInvocation, runAgent, isAgentAvailable, } from '../loop/runner.js';
 import { resolveIdleMs } from '../loop/run-command.js';
 import { detectHostAgent, resolveRunnerAgent } from '../agents/host.js';
-export const PRD_TEMPLATE = `# Yoke PRD — the loop picks the lowest-priority open story each iteration.
-# Story format (see canon/loop/prd.schema.md):
-# - id: STORY-1
-#   title: scaffold the project with a runnable test suite
-#   priority: 1
-#   needs: []             # optional story IDs that must pass first
-#   area: foundation      # optional collision domain for parallel runs
-#   agent: codex          # optional claude|codex|gemini affinity
-#   acceptance:
-#     - id: suite-runs
-#       text: "the project test suite can run"
-#       verify: ["npm run test:suite-runs"]
-#     - id: scaffold-starts
-#       text: "the scaffolded application starts"
-#       verify: ["npm run test:scaffold-starts"]
-#   passes: false
-[]
+export const PRD_TEMPLATE = `# Yoke PRD — the loop picks the lowest-priority open story each iteration.
+# Story format (see canon/loop/prd.schema.md):
+# - id: STORY-1
+#   title: scaffold the project with a runnable test suite
+#   priority: 1
+#   needs: []             # optional story IDs that must pass first
+#   area: foundation      # optional collision domain for parallel runs
+#   agent: codex          # optional claude|codex|gemini affinity
+#   acceptance:
+#     - id: suite-runs
+#       text: "the project test suite can run"
+#       verify: ["npm run test:suite-runs"]
+#     - id: scaffold-starts
+#       text: "the scaffolded application starts"
+#       verify: ["npm run test:scaffold-starts"]
+#   passes: false
+[]
 `;
 export const MAX_PLANNING_BRIEF_CHARS = 20_000;
 export const MAX_PLANNING_BRIEF_BYTES = MAX_PLANNING_BRIEF_CHARS * 4;

package/dist/retrofit/apply.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { mergeJson } from './merge-json.js';
 import { carryPreserved } from './preserve.js';
@@ -10,13 +10,17 @@ export function applyActions(actions, targetDir, opts) {
         let backedUp;
         let content = action.content;
         let reason = action.reason;
+        if (action.merge && typeof action.content !== 'string') {
+            throw new Error(`yoke: binary content cannot be merged: ${action.target}`);
+        }
         if (existsSync(dest)) {
             if (action.ifAbsent) {
                 results.push({ target: action.target, status: 'unchanged', reason: `${action.reason} (exists, left untouched)` });
                 continue;
             }
-            const current = readFileSync(dest, 'utf8');
+            const currentBytes = readFileSync(dest);
             if (action.merge) {
+                const current = currentBytes.toString('utf8');
                 let parsedCurrent;
                 try {
                     parsedCurrent = JSON.parse(current);
@@ -37,11 +41,18 @@ export function applyActions(actions, targetDir, opts) {
                 results.push({ target: action.target, status: 'merged', backedUp, reason: action.reason });
                 continue;
             }
-            // Carry user content marked with yoke preserve markers into the new file.
-            content = carryPreserved(current, action.content);
-            if (content !== action.content)
-                reason = `${action.reason} (preserve block kept)`;
-            if (current === content) {
+            if (typeof action.content === 'string') {
+                const current = currentBytes.toString('utf8');
+                // Carry user content marked with yoke preserve markers into the new file.
+                content = carryPreserved(current, action.content);
+                if (content !== action.content)
+                    reason = `${action.reason} (preserve block kept)`;
+                if (current === content) {
+                    results.push({ target: action.target, status: 'unchanged', reason: action.reason });
+                    continue;
+                }
+            }
+            else if (currentBytes.equals(Buffer.from(action.content))) {
                 results.push({ target: action.target, status: 'unchanged', reason: action.reason });
                 continue;
             }
@@ -55,6 +66,10 @@ export function applyActions(actions, targetDir, opts) {
         }
         mkdirSync(dirname(dest), { recursive: true });
         writeFileSync(dest, content);
+        if (action.executable !== undefined && process.platform !== 'win32') {
+            const currentMode = statSync(dest).mode;
+            chmodSync(dest, action.executable ? currentMode | 0o111 : currentMode & ~0o111);
+        }
         results.push({ target: action.target, status, backedUp, reason });
     }
     return results;

package/dist/retrofit/command.js

@@ -31,8 +31,11 @@ export function runRetrofit(targetDir, opts) {
         agents: mergedAgents,
         loop: { ...existing?.loop, enabled: opts.loop },
         codeGraph,
+        ...(existing?.design
+            ? { design: existing.design }
+            : detection.ui.detected ? { design: { mode: 'auto', max: 4 } } : {}),
     };
     saveConfig(targetDir, config);
-    console.log(formatReport(applied, { loopEnabled: config.loop.enabled, detectedAgents: detection.agents }));
+    console.log(formatReport(applied, { loopEnabled: config.loop.enabled, detectedAgents: detection.agents, ui: detection.ui }));
     return 0;
 }

package/dist/retrofit/config.js

@@ -80,6 +80,10 @@ export const YokeConfigSchema = z.object({
     // 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(),
+    design: z.object({
+        mode: z.enum(['off', 'auto', 'on']),
+        max: z.number().int().positive().default(4),
+    }).optional(),
     codeGraph: CodeGraphSchema.optional(),
     smoke: SmokeSchema.optional(),
     quality: ProjectQualityDefaultsSchema.optional(),

package/dist/retrofit/context-actions.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-const CONTEXT_FILES = ['PROJECT.md', 'DECISIONS.md', 'KNOWLEDGE.md'];
+const CONTEXT_FILES = ['PROJECT.md', 'DECISIONS.md', 'KNOWLEDGE.md', 'GLOSSARY.md'];
 export function baseContextActions(canonDir) {
     return CONTEXT_FILES.map(name => {
         let content;

package/dist/retrofit/detect.js

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { detectUiProject } from './ui-detect.js';
 export function detectProject(targetDir) {
     const has = (...parts) => existsSync(join(targetDir, ...parts));
     const agents = [];
@@ -13,5 +14,6 @@ export function detectProject(targetDir) {
         agents,
         hasAgentsMd: has('AGENTS.md'),
         hasYokeConfig: has('.yoke', 'config.yaml'),
+        ui: detectUiProject(targetDir),
     };
 }

package/dist/retrofit/planners/claude.js

@@ -5,32 +5,28 @@ import { mcpServers, rtkInstruction } from '../tools.js';
 import { hasWsl } from '../wsl.js';
 import { detectGstack } from '../gstack.js';
 import { PRESERVE_SCAFFOLD } from '../preserve.js';
-const GSTACK_COMPOSE = `## Composed tools (gstack detected)
-
-This project also has [gstack](https://github.com/garrytan/gstack) installed. For capabilities Yoke does not ship, prefer gstack's skills:
-
-- Live-browser QA → \`/qa\`
-- Security audit → \`/cso\`
-- Ship / deploy → \`/ship\`, \`/land-and-deploy\`
+import { skillPackageActions } from '../skill-actions.js';
+const GSTACK_COMPOSE = `## Composed tools (gstack detected)
+
+This project also has [gstack](https://github.com/garrytan/gstack) installed. For capabilities Yoke does not ship, prefer gstack's skills:
+
+- Live-browser QA → \`/qa\`
+- Security audit → \`/cso\`
+- Ship / deploy → \`/ship\`, \`/land-and-deploy\`
 `;
-const claudeMd = (rtkNote, composeNote) => `# Project Instructions
-
-This project uses the Yoke harness. Baseline instructions:
-
-@AGENTS.md
-${rtkNote ? `\n${rtkNote}\n` : ''}${composeNote ? `\n${composeNote}\n` : ''}
-${PRESERVE_SCAFFOLD}
+const claudeMd = (rtkNote, composeNote) => `# Project Instructions
+
+This project uses the Yoke harness. Baseline instructions:
+
+@AGENTS.md
+${rtkNote ? `\n${rtkNote}\n` : ''}${composeNote ? `\n${composeNote}\n` : ''}
+${PRESERVE_SCAFFOLD}
 `;
 export function planClaude(canonDir, targetDir, wslAvailable = hasWsl(), codeGraph = 'graphify', gstackDetected = detectGstack(targetDir)) {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const actions = [];
     for (const skill of manifest.skills) {
-        actions.push({
-            kind: 'write',
-            target: `.claude/skills/${skill.id}/SKILL.md`,
-            content: readFileSync(join(canonDir, skill.path, 'SKILL.md'), 'utf8'),
-            reason: `skill: ${skill.id}`,
-        });
+        actions.push(...skillPackageActions(canonDir, skill, 'claude'));
     }
     actions.push({
         kind: 'write',

package/dist/retrofit/planners/codex.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadManifest } from '../../canon/manifest.js';
 import { mcpServers, rtkInstruction } from '../tools.js';
+import { skillPackageActions } from '../skill-actions.js';
 function tomlMcp(codeGraph) {
     const servers = mcpServers(codeGraph);
     // Codex reads MCP servers from ~/.codex/config.toml. This project-level file is a
@@ -16,17 +17,12 @@ function tomlMcp(codeGraph) {
 export function planCodex(canonDir, _targetDir, codeGraph = 'graphify') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const baseline = readFileSync(join(canonDir, 'AGENTS.md'), 'utf8');
-    const actions = manifest.skills.map(skill => ({
-        kind: 'write',
-        target: `.agents/skills/${skill.id}/SKILL.md`,
-        content: readFileSync(join(canonDir, skill.path, 'SKILL.md'), 'utf8'),
-        reason: `skill: ${skill.id}`,
-    }));
+    const actions = manifest.skills.flatMap(skill => skillPackageActions(canonDir, skill, 'codex'));
     const roles = [
         ['implementer', 'Implementation specialist for one scoped story.', 'workspace-write', 'Implement only the assigned scope. Use tests first, run verification, and do not review or commit your own work.'],
         ['reviewer', 'Read-only reviewer for correctness and acceptance criteria.', 'read-only', 'Review observed diffs and test evidence. Do not modify files. Return only findings grounded in evidence.'],
         ['security', 'Read-only security reviewer for changed code.', 'read-only', 'Inspect changed code for exploitable security regressions. Do not modify files and avoid speculative findings.'],
-        ['docs', 'Documentation specialist for release and API consistency.', 'workspace-write', 'Update only documentation required by the assigned change. Verify commands and version references against the repository.'],
+        ['docs', 'Documentation specialist for release and API consistency.', 'workspace-write', 'Update only documentation required by the assigned change. Verify commands and version references against the repository. Use no-ai-slop Detect mode before prose edits, preserve the writer\'s voice, and apply only observed fixes.'],
     ];
     actions.push({
         kind: 'write',

package/dist/retrofit/planners/gemini.js

@@ -4,6 +4,7 @@ import { loadManifest } from '../../canon/manifest.js';
 import { parseFrontmatter } from '../../canon/frontmatter.js';
 import { mcpServers, rtkInstruction } from '../tools.js';
 import { PRESERVE_SCAFFOLD } from '../preserve.js';
+import { skillPackageActions } from '../skill-actions.js';
 function tomlString(s) {
     return '"""\n' + s.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"') + '\n"""';
 }
@@ -12,10 +13,18 @@ export function planGemini(canonDir, _targetDir, codeGraph = 'graphify') {
     const actions = [];
     // GEMINI.md: baseline + rtk instruction (Gemini has no rewrite hook).
     const baseline = readFileSync(join(canonDir, 'AGENTS.md'), 'utf8');
+    const autoSkillIndex = manifest.skills
+        .filter(skill => skill.invocation === 'auto')
+        .map(skill => {
+        const source = readFileSync(join(canonDir, skill.path, 'SKILL.md'), 'utf8');
+        const description = String(parseFrontmatter(source)?.description ?? skill.id).replace(/\s+/gu, ' ').trim();
+        return `- \`/${skill.id}\` — ${description}`;
+    })
+        .join('\n');
     actions.push({
         kind: 'write',
         target: 'GEMINI.md',
-        content: `${baseline}\n${rtkInstruction()}\n\n${PRESERVE_SCAFFOLD}\n`,
+        content: `${baseline}\n${rtkInstruction()}\n\n## Yoke automatic skills\n\nUse the matching command when its capability is relevant:\n\n${autoSkillIndex}\n\n${PRESERVE_SCAFFOLD}\n`,
         reason: 'baseline + rtk instruction (no hook on Gemini)',
     });
     // One TOML slash command per skill.
@@ -33,6 +42,7 @@ export function planGemini(canonDir, _targetDir, codeGraph = 'graphify') {
             content: `description = "${description.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"\nprompt = ${tomlString(prompt)}\n`,
             reason: `gemini command: ${skill.id}`,
         });
+        actions.push(...skillPackageActions(canonDir, skill, 'gemini'));
     }
     // settings.json: MCP servers + read AGENTS.md as context.
     actions.push({

package/dist/retrofit/preserve.js

@@ -1,7 +1,7 @@
 export const PRESERVE_START = '<!-- yoke:preserve:start -->';
 export const PRESERVE_END = '<!-- yoke:preserve:end -->';
-export const PRESERVE_SCAFFOLD = `${PRESERVE_START}
-<!-- Project-specific instructions go here. Yoke keeps this block across retrofits. -->
+export const PRESERVE_SCAFFOLD = `${PRESERVE_START}
+<!-- Project-specific instructions go here. Yoke keeps this block across retrofits. -->
 ${PRESERVE_END}`;
 /**
  * Extract the inner content of every balanced preserve-marker pair, in order.

package/dist/retrofit/report.js

@@ -8,6 +8,11 @@ export function formatReport(applied, meta) {
     }
     lines.push('');
     lines.push(`Detected agents: ${meta.detectedAgents.length ? meta.detectedAgents.join(', ') : 'none'}`);
+    if (meta.ui) {
+        lines.push(meta.ui.detected
+            ? `UI project: detected (${meta.ui.signals.join('; ')})`
+            : 'UI project: not detected');
+    }
     lines.push(`Summary: ${count('created')} created, ${count('overwritten')} overwritten, ${count('merged')} merged, ${count('unchanged')} unchanged`);
     lines.push(`Loop: ${meta.loopEnabled ? 'enabled' : 'disabled'}`);
     return lines.join('\n');

package/dist/retrofit/skill-actions.js

@@ -0,0 +1,66 @@
+import { parse, stringify } from 'yaml';
+import { enumerateSkillPackage } from '../canon/skill-package.js';
+const roots = {
+    claude: '.claude/skills',
+    codex: '.agents/skills',
+    gemini: '.gemini/skills',
+};
+function manualClaudeSkill(content, skill) {
+    const source = content.toString('utf8');
+    const match = source.match(/^(---\r?\n)([\s\S]*?)(\r?\n---)/u);
+    if (!match)
+        throw new Error(`skill ${skill.id}: cannot adapt manual invocation without frontmatter`);
+    const newline = match[1].includes('\r\n') ? '\r\n' : '\n';
+    const frontmatter = match[2];
+    const adapted = /(?:^|\r?\n)disable-model-invocation:/u.test(frontmatter)
+        ? frontmatter.replace(/(^|\r?\n)disable-model-invocation:\s*[^\r\n]*/u, `$1disable-model-invocation: true`)
+        : `${frontmatter}${newline}disable-model-invocation: true`;
+    return `${match[1]}${adapted}${match[3]}${source.slice(match[0].length)}`;
+}
+function codexPolicy(skill, existing) {
+    const allow = skill.invocation === 'auto';
+    const document = existing ? parse(existing.content.toString('utf8')) : {};
+    if (document === null || typeof document !== 'object' || Array.isArray(document)) {
+        throw new Error(`skill ${skill.id}: agents/openai.yaml must contain a YAML object`);
+    }
+    const record = document;
+    const policy = record.policy;
+    if (policy !== undefined && (typeof policy !== 'object' || policy === null || Array.isArray(policy))) {
+        throw new Error(`skill ${skill.id}: agents/openai.yaml policy must be a YAML object`);
+    }
+    const policyRecord = (policy ?? {});
+    const declared = policyRecord.allow_implicit_invocation;
+    if (declared !== undefined && declared !== allow) {
+        throw new Error(`skill ${skill.id}: agents/openai.yaml invocation policy conflicts with manifest`);
+    }
+    return stringify({ ...record, policy: { ...policyRecord, allow_implicit_invocation: allow } });
+}
+function portableContent(file) {
+    const text = file.content.toString('utf8');
+    return !text.includes('\0') && Buffer.from(text, 'utf8').equals(file.content) ? text : file.content;
+}
+export function skillPackageActions(canonDir, skill, provider) {
+    const files = enumerateSkillPackage(canonDir, skill);
+    const policyPath = 'agents/openai.yaml';
+    const existingPolicy = provider === 'codex' ? files.find(file => file.relativePath === policyPath) : undefined;
+    const actions = files
+        .filter(file => provider !== 'codex' || file.relativePath !== policyPath)
+        .map(file => ({
+        kind: 'write',
+        target: `${roots[provider]}/${skill.id}/${file.relativePath}`,
+        content: provider === 'claude' && skill.invocation === 'manual' && file.relativePath === 'SKILL.md'
+            ? manualClaudeSkill(file.content, skill)
+            : portableContent(file),
+        executable: file.executable,
+        reason: `skill: ${skill.id} (${file.relativePath})`,
+    }));
+    if (provider === 'codex') {
+        actions.push({
+            kind: 'write',
+            target: `${roots.codex}/${skill.id}/${policyPath}`,
+            content: codexPolicy(skill, existingPolicy),
+            reason: `skill invocation policy: ${skill.id}`,
+        });
+    }
+    return actions;
+}

package/dist/retrofit/ui-detect.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { parse } from 'yaml';
+const UI_DEPENDENCIES = new Set([
+    '@angular/core', '@astrojs/react', '@astrojs/svelte', '@astrojs/vue',
+    '@sveltejs/kit', '@vitejs/plugin-react', '@vitejs/plugin-react-swc',
+    '@vitejs/plugin-vue', '@vitejs/plugin-vue-jsx', 'astro', 'next', 'nuxt',
+    'react', 'react-dom', 'svelte', 'vue',
+]);
+const UI_EXTENSIONS = new Set(['.tsx', '.jsx', '.vue', '.svelte', '.astro']);
+const SOURCE_ROOTS = ['src', 'app', 'pages', 'components', 'web', 'frontend'];
+const IGNORED_DIRECTORIES = new Set([
+    '.git', '.next', '.nuxt', '.svelte-kit', '.yoke', '__fixtures__', 'build',
+    'coverage', 'dist', 'fixtures', 'node_modules', 'test', 'tests',
+]);
+function packageSignals(targetDir) {
+    const file = join(targetDir, 'package.json');
+    if (!existsSync(file))
+        return [];
+    try {
+        const pkg = JSON.parse(readFileSync(file, 'utf8'));
+        const names = new Set();
+        for (const key of ['dependencies', 'devDependencies', 'peerDependencies']) {
+            const section = pkg[key];
+            if (section && typeof section === 'object' && !Array.isArray(section)) {
+                for (const name of Object.keys(section))
+                    if (UI_DEPENDENCIES.has(name))
+                        names.add(name);
+            }
+        }
+        return [...names].sort().map(name => `dependency: ${name}`);
+    }
+    catch {
+        return [];
+    }
+}
+function sourceSignals(targetDir) {
+    const signals = [];
+    let visited = 0;
+    const visit = (directory) => {
+        if (visited >= 10_000)
+            return;
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            if (visited++ >= 10_000)
+                return;
+            if (entry.isDirectory()) {
+                if (!IGNORED_DIRECTORIES.has(entry.name))
+                    visit(join(directory, entry.name));
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const extension = entry.name.slice(entry.name.lastIndexOf('.')).toLowerCase();
+            if (UI_EXTENSIONS.has(extension)) {
+                signals.push(`source: ${relative(targetDir, join(directory, entry.name)).replaceAll('\\', '/')}`);
+            }
+        }
+    };
+    for (const root of SOURCE_ROOTS) {
+        const directory = join(targetDir, root);
+        if (existsSync(directory))
+            visit(directory);
+    }
+    return signals.sort();
+}
+function hasSmokeFlows(targetDir) {
+    const file = join(targetDir, '.yoke', 'config.yaml');
+    if (!existsSync(file))
+        return false;
+    try {
+        const document = parse(readFileSync(file, 'utf8'));
+        return Array.isArray(document?.smoke?.flows) && document.smoke.flows.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function detectUiProject(targetDir) {
+    const signals = [...packageSignals(targetDir), ...sourceSignals(targetDir)];
+    if (hasSmokeFlows(targetDir))
+        signals.push('config: smoke flows');
+    return { detected: signals.length > 0, signals };
+}

package/dist/scan/gate.js

@@ -0,0 +1,36 @@
+import { relative } from 'node:path';
+import { compactCommandOutput } from '../output/compact.js';
+import { writeOutputArtifact } from '../output/artifact.js';
+import { DEFAULT_OUTPUT_POLICY } from '../output/types.js';
+import { scanDir } from './design.js';
+export function designVerifier(max, options = {}) {
+    return (targetDir) => {
+        const { findings, score } = scanDir(targetDir);
+        const label = `design ${score <= max ? 'passed' : 'failed'}: score ${score} (${findings.length} tell${findings.length === 1 ? '' : 's'}), budget ${max}`;
+        if (score <= max)
+            return { passed: true, summary: label };
+        const raw = findings.map(finding => {
+            const file = relative(targetDir, finding.file).replaceAll('\\', '/');
+            return `${file}:${finding.line}  ${finding.tell} — ${finding.hint}\n  ${finding.text}`;
+        }).join('\n');
+        const policy = options.policy ?? DEFAULT_OUTPUT_POLICY;
+        const compacted = compactCommandOutput(raw, { previewBytes: policy.previewBytes });
+        const parts = [label];
+        if (compacted.preview)
+            parts.push(compacted.preview);
+        if (compacted.originalBytes > policy.artifactThresholdBytes) {
+            try {
+                const artifact = (options.artifactWriter ?? writeOutputArtifact)(targetDir, raw, {
+                    phase: 'design',
+                    storyId: process.env.YOKE_STORY,
+                });
+                parts.push(artifact.marker);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                parts.push(`[artifact unavailable: ${message.replace(/[\u0000-\u001F\u007F]/gu, ' ').slice(0, 240)}]`);
+            }
+        }
+        return { passed: false, summary: parts.join('\n') };
+    };
+}

package/docs/MIGRATING-TO-1.0.md

@@ -1,33 +1,33 @@
-# Migrating to Yoke 1.0
-
-Yoke 1.0 changes unsafe implicit behavior into explicit policy.
-
-## Runner permissions
-
-The default is `runner.permissions: safe`. Automation that intentionally requires a full
-sandbox bypass must pass `--unsafe` or configure `runner.permissions: unsafe`. Use
-`read-only` for planning and probing.
-
-## Reviews
-
-Reviewers write `.yoke/review-verdict.json`; Yoke validates and consumes it. The reviewer must
-differ from the implementer unless `--allow-self-review` is explicit. CI can add `--json`.
-
-## Commit ownership
-
-Yoke resolves identity before implementation. Configure it when Git has no identity:
-
-```yaml
-commit:
-  authorName: HECer
-  authorEmail: hec_er@web.de
-  allowCoAuthors: false
-```
-
-## PRDs, audit, and cleanup
-
-Existing PRDs remain valid. Optional `needs`, `area`, and `agent` fields add dependencies,
-collision domains, and affinity. Enable the story audit gate with `audit.enabled: true` and
-version suppressions with `suppressionsVersion: 1`.
-
-`yoke loop cleanup` now reports retained worktrees. Add `--remove-worktrees` for deletion.
+# Migrating to Yoke 1.0
+
+Yoke 1.0 changes unsafe implicit behavior into explicit policy.
+
+## Runner permissions
+
+The default is `runner.permissions: safe`. Automation that intentionally requires a full
+sandbox bypass must pass `--unsafe` or configure `runner.permissions: unsafe`. Use
+`read-only` for planning and probing.
+
+## Reviews
+
+Reviewers write `.yoke/review-verdict.json`; Yoke validates and consumes it. The reviewer must
+differ from the implementer unless `--allow-self-review` is explicit. CI can add `--json`.
+
+## Commit ownership
+
+Yoke resolves identity before implementation. Configure it when Git has no identity:
+
+```yaml
+commit:
+  authorName: HECer
+  authorEmail: hec_er@web.de
+  allowCoAuthors: false
+```
+
+## PRDs, audit, and cleanup
+
+Existing PRDs remain valid. Optional `needs`, `area`, and `agent` fields add dependencies,
+collision domains, and affinity. Enable the story audit gate with `audit.enabled: true` and
+version suppressions with `suppressionsVersion: 1`.
+
+`yoke loop cleanup` now reports retained worktrees. Add `--remove-worktrees` for deletion.

package/docs/MIGRATING-TO-1.1.md

@@ -1,27 +1,27 @@
-# Migrating to Yoke 1.1
-
-Yoke 1.1 makes Claude, Codex, and Gemini share the same setup, planning, runner-selection, and decision behavior.
-
-Run the setup wizard once in an existing project:
-
-```bash
-npx @hecer/yoke@1.1.0 setup .
-```
-
-It preserves existing Yoke configuration and asks for target agents, code graph, loop state, default runner, and decision mode. A non-interactive agent can apply explicit choices with `--yes`.
-
-The new config fields are optional and backward-compatible:
-
-```yaml
-runner:
-  agent: codex
-  permissions: safe
-loop:
-  enabled: true
-  timeoutMinutes: 30
-  decisionPolicy: critical  # auto | critical
-```
-
-`loop.onAmbiguity: resolve|abort` and `--on-ambiguity=` still work. Prefer `decisionPolicy` for new projects: `auto` resolves routine choices without asking; `critical` pauses only for high-impact decisions and continues after `yoke loop answer`. Resume restores the original isolation, review, runner, permissions, timeout, and policy flags instead of silently weakening the run. If the restart cannot begin, `yoke loop resume` retries from the request-bound state stored under Git's private state directory.
-
-Restart an already-open Codex task after retrofit if it does not discover the newly generated `.agents/skills/yoke-workflow/SKILL.md`.
+# Migrating to Yoke 1.1
+
+Yoke 1.1 makes Claude, Codex, and Gemini share the same setup, planning, runner-selection, and decision behavior.
+
+Run the setup wizard once in an existing project:
+
+```bash
+npx @hecer/yoke@1.1.0 setup .
+```
+
+It preserves existing Yoke configuration and asks for target agents, code graph, loop state, default runner, and decision mode. A non-interactive agent can apply explicit choices with `--yes`.
+
+The new config fields are optional and backward-compatible:
+
+```yaml
+runner:
+  agent: codex
+  permissions: safe
+loop:
+  enabled: true
+  timeoutMinutes: 30
+  decisionPolicy: critical  # auto | critical
+```
+
+`loop.onAmbiguity: resolve|abort` and `--on-ambiguity=` still work. Prefer `decisionPolicy` for new projects: `auto` resolves routine choices without asking; `critical` pauses only for high-impact decisions and continues after `yoke loop answer`. Resume restores the original isolation, review, runner, permissions, timeout, and policy flags instead of silently weakening the run. If the restart cannot begin, `yoke loop resume` retries from the request-bound state stored under Git's private state directory.
+
+Restart an already-open Codex task after retrofit if it does not discover the newly generated `.agents/skills/yoke-workflow/SKILL.md`.