@hecer/yoke 1.5.1 → 1.6.1

package/canon/skills/yoke-retrofit/SKILL.md

@@ -1,26 +1,26 @@
----
-name: yoke-retrofit
-description: Use when asked to "retrofit", "yoke this project", or set up the Yoke harness in a project — runs the shared setup wizard and configures the same behavior for Claude, Codex, and Gemini.
----
-
-# Yoke Retrofit
-
-Set up or update Yoke through the shared `yoke setup` contract.
-
-1. Inspect the project and identify the current host (`claude`, `codex`, or `gemini`).
-2. Ask these setup questions one at a time and give a direct recommendation:
-   - target agents (recommend the current host; use `all` for deliberately cross-agent projects),
-   - code-graph tool,
-   - autonomous loop on/off,
-   - default runner (recommend the current host),
-   - decision mode: `auto` or `critical`.
-3. Recommend the code graph based on this project:
-   - **Serena** is LSP-accurate and best for large typed codebases or systematic symbol refactors where a missed reference is costly. It needs a language server per language.
-   - **graphify** is fast and multimodal, and is best for exploration, migration, onboarding, or mixed code and document repositories. Its graph is an index and can become stale.
-4. Apply the answers without a second round of prompts:
-   `yoke setup . --yes --host=<host> --agent=<agents> --code-graph=<choice> --runner=<runner> --decision-policy=<auto|critical> --loop|--no-loop`.
-   A human who runs `yoke setup .` directly receives the same five terminal questions.
-5. Show the generated report and backup paths. Existing files are backed up under `.yoke/backup/`; settings are merged where supported.
-6. If an old generated `CLAUDE.md` or `GEMINI.md` contained project-specific instructions, restore them inside its `<!-- yoke:preserve:start -->` / `<!-- yoke:preserve:end -->` block. Preserve blocks survive every later retrofit.
-
-The generated harness includes the provider-neutral `yoke-workflow` skill. It owns the planning questions, approved-plan handoff, autonomous stories, and critical-decision resume flow.
+---
+name: yoke-retrofit
+description: Use when asked to "retrofit", "yoke this project", or set up the Yoke harness in a project — runs the shared setup wizard and configures the same behavior for Claude, Codex, and Gemini.
+---
+
+# Yoke Retrofit
+
+Set up or update Yoke through the shared `yoke setup` contract.
+
+1. Inspect the project and identify the current host (`claude`, `codex`, or `gemini`).
+2. Ask these setup questions one at a time and give a direct recommendation:
+   - target agents (recommend the current host; use `all` for deliberately cross-agent projects),
+   - code-graph tool,
+   - autonomous loop on/off,
+   - default runner (recommend the current host),
+   - decision mode: `auto` or `critical`.
+3. Recommend the code graph based on this project:
+   - **Serena** is LSP-accurate and best for large typed codebases or systematic symbol refactors where a missed reference is costly. It needs a language server per language.
+   - **graphify** is fast and multimodal, and is best for exploration, migration, onboarding, or mixed code and document repositories. Its graph is an index and can become stale.
+4. Apply the answers without a second round of prompts:
+   `yoke setup . --yes --host=<host> --agent=<agents> --code-graph=<choice> --runner=<runner> --decision-policy=<auto|critical> --loop|--no-loop`.
+   A human who runs `yoke setup .` directly receives the same five terminal questions.
+5. Show the generated report and backup paths. Existing files are backed up under `.yoke/backup/`; settings are merged where supported.
+6. If an old generated `CLAUDE.md` or `GEMINI.md` contained project-specific instructions, restore them inside its `<!-- yoke:preserve:start -->` / `<!-- yoke:preserve:end -->` block. Preserve blocks survive every later retrofit.
+
+The generated harness includes the provider-neutral `yoke-workflow` skill. It owns the planning questions, approved-plan handoff, autonomous stories, and critical-decision resume flow.

package/canon/skills/yoke-workflow/SKILL.md

@@ -1,20 +1,20 @@
----
-name: yoke-workflow
-description: Use when the user asks Yoke to plan and build a feature, run stories autonomously, continue a Yoke loop, or only interrupt for major decisions.
----
-
-# Yoke Workflow
-
-Provide the same interaction contract in Claude, Codex, and Gemini.
-
-1. Read `.yoke/config.yaml`. If it is missing, offer `yoke setup . --host=<current-agent>` and run the setup flow before planning.
-2. Plan before starting the loop. Inspect the project, then ask one focused question at a time only where the answer changes product behavior, scope, architecture, security, data ownership, external cost, or an irreversible choice. Include a recommended answer. Resolve routine implementation details yourself.
-3. Summarize the agreed design in `.yoke/plan.md`, including goals, non-goals, constraints, and decisions. Use the `authoring-prd` skill to turn it into small stories with testable acceptance criteria. Run `yoke prd check .`.
-4. Ask once for approval of the complete plan and story set. Do not begin implementation before that approval.
-5. If `loop.enabled` is true, run the stories without routine follow-up questions using the configured runner. Prefer `yoke loop run . --max=5 --isolate`, report status after each batch, and continue until complete or genuinely blocked.
-6. Respect `loop.decisionPolicy`:
-   - `auto`: choose the most suitable option from the plan, current code, and established conventions. Record the interpretation and continue.
-   - `critical`: routine ambiguity is still resolved automatically. If the loop reports a pending critical decision, run `yoke loop decision .`, present its options and recommendation to the user, ask exactly that question, then run `yoke loop answer . --choice=<id> --rationale="<answer>"`. The answer command records the decision and resumes the same story.
-7. Never ask whether to run tests, review, commit, or continue to the next approved story. Those are part of the approved workflow.
-
-The user's configured commit identity is authoritative. Do not add an AI co-author unless `commit.allowCoAuthors` explicitly permits it.
+---
+name: yoke-workflow
+description: Use when the user asks Yoke to plan and build a feature, run stories autonomously, continue a Yoke loop, or only interrupt for major decisions.
+---
+
+# Yoke Workflow
+
+Provide the same interaction contract in Claude, Codex, and Gemini.
+
+1. Read `.yoke/config.yaml`. If it is missing, offer `yoke setup . --host=<current-agent>` and run the setup flow before planning.
+2. Plan before starting the loop. Inspect the project, then ask one focused question at a time only where the answer changes product behavior, scope, architecture, security, data ownership, external cost, or an irreversible choice. Include a recommended answer. Resolve routine implementation details yourself.
+3. Summarize the agreed design in `.yoke/plan.md`, including goals, non-goals, constraints, and decisions. Use the `authoring-prd` skill to turn it into small stories with testable acceptance criteria. Run `yoke prd check .`.
+4. Ask once for approval of the complete plan and story set. Do not begin implementation before that approval.
+5. If `loop.enabled` is true, run the stories without routine follow-up questions using the configured runner. Prefer `yoke loop run . --max=5 --isolate`, report status after each batch, and continue until complete or genuinely blocked.
+6. Respect `loop.decisionPolicy`:
+   - `auto`: choose the most suitable option from the plan, current code, and established conventions. Record the interpretation and continue.
+   - `critical`: routine ambiguity is still resolved automatically. If the loop reports a pending critical decision, run `yoke loop decision .`, present its options and recommendation to the user, ask exactly that question, then run `yoke loop answer . --choice=<id> --rationale="<answer>"`. The answer command records the decision and resumes the same story.
+7. Never ask whether to run tests, review, commit, or continue to the next approved story. Those are part of the approved workflow.
+
+The user's configured commit identity is authoritative. Do not add an AI co-author unless `commit.allowCoAuthors` explicitly permits it.

package/canon/tools/codex-rtk-hook.mjs

@@ -1,36 +1,36 @@
 import { spawnSync } from 'node:child_process'
-import { resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-function rtkCheck(command) {
-  const result = spawnSync('rtk', ['hook', 'check', command], { encoding: 'utf8', timeout: 3000 })
-  return result.status === 0 ? result.stdout.trim() : ''
-}
-
-export function rewriteHookInput(input, check = rtkCheck) {
-  if (input?.tool_name !== 'Bash' && input?.toolName !== 'Bash') return null
-  const toolInput = input.tool_input ?? input.toolInput
-  const command = toolInput?.command
-  if (typeof command !== 'string' || command.trim() === '') return null
-  const rewritten = check(command)
-  if (!rewritten || rewritten === command) return null
-  return {
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      updatedInput: { ...toolInput, command: rewritten },
-    },
-  }
-}
-
-async function main() {
-  let raw = ''
-  for await (const chunk of process.stdin) raw += chunk
-  try {
-    const output = rewriteHookInput(JSON.parse(raw))
-    if (output) process.stdout.write(JSON.stringify(output))
-  } catch {
-    // Compression is an optimization. Malformed input must never block Codex.
-  }
-}
-
-if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) await main()
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+function rtkCheck(command) {
+  const result = spawnSync('rtk', ['hook', 'check', command], { encoding: 'utf8', timeout: 3000 })
+  return result.status === 0 ? result.stdout.trim() : ''
+}
+
+export function rewriteHookInput(input, check = rtkCheck) {
+  if (input?.tool_name !== 'Bash' && input?.toolName !== 'Bash') return null
+  const toolInput = input.tool_input ?? input.toolInput
+  const command = toolInput?.command
+  if (typeof command !== 'string' || command.trim() === '') return null
+  const rewritten = check(command)
+  if (!rewritten || rewritten === command) return null
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      updatedInput: { ...toolInput, command: rewritten },
+    },
+  }
+}
+
+async function main() {
+  let raw = ''
+  for await (const chunk of process.stdin) raw += chunk
+  try {
+    const output = rewriteHookInput(JSON.parse(raw))
+    if (output) process.stdout.write(JSON.stringify(output))
+  } catch {
+    // Compression is an optimization. Malformed input must never block Codex.
+  }
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) await main()

package/canon/tools/graphify.md

@@ -1,3 +1,3 @@
-# Tool: graphify (code-graph)
-
-MIT, multimodal code/doc graph. Wired as an MCP server for all three agents (stdio). Prefer symbol/graph lookups over reading whole files. Caveat: heuristic edges (INFERRED/AMBIGUOUS) and a static index that can go stale — rebuild on significant changes.
+# Tool: graphify (code-graph)
+
+MIT, multimodal code/doc graph. Wired as an MCP server for all three agents (stdio). Prefer symbol/graph lookups over reading whole files. Caveat: heuristic edges (INFERRED/AMBIGUOUS) and a static index that can go stale — rebuild on significant changes.

package/canon/tools/playwright-mcp.md

@@ -1,3 +1,3 @@
-# Tool: Playwright MCP (browser / dogfooding)
-
-Microsoft Playwright MCP, Apache-2.0. Wired as an MCP server for all three agents — the only browser tool with native MCP parity across Claude/Codex/Gemini. Used for QA, dogfooding user flows, screenshots, and deploy verification.
+# Tool: Playwright MCP (browser / dogfooding)
+
+Microsoft Playwright MCP, Apache-2.0. Wired as an MCP server for all three agents — the only browser tool with native MCP parity across Claude/Codex/Gemini. Used for QA, dogfooding user flows, screenshots, and deploy verification.

package/canon/tools/rtk.md

@@ -1,7 +1,7 @@
-# Tool: rtk (token compression)
-
-Per-agent wiring (generated by Baustein B):
-
-- **Claude Code:** PreToolUse hook auto-rewrites commands (`git status` → `rtk git status`). On Windows this needs WSL; otherwise fall back to instruction mode (this file injected into CLAUDE.md telling the agent to prefix commands with `rtk`).
-- **Codex CLI:** inject `RTK.md` / AGENTS.md instruction.
-- **Gemini CLI:** no hook system — register rtk as an MCP tool or inject the GEMINI.md instruction.
+# Tool: rtk (token compression)
+
+Per-agent wiring (generated by Baustein B):
+
+- **Claude Code:** PreToolUse hook auto-rewrites commands (`git status` → `rtk git status`). On Windows this needs WSL; otherwise fall back to instruction mode (this file injected into CLAUDE.md telling the agent to prefix commands with `rtk`).
+- **Codex CLI:** inject `RTK.md` / AGENTS.md instruction.
+- **Gemini CLI:** no hook system — register rtk as an MCP tool or inject the GEMINI.md instruction.

package/canon/tools/serena.md

@@ -1,9 +1,9 @@
-# Tool: Serena (code-graph, LSP-accurate)
-
-MIT, MCP-first. The alternative to graphify, selected via `yoke retrofit --code-graph=serena`. Serena uses real language servers (LSP) for symbol-accurate, cross-file retrieval and refactoring (`find_symbol`, `find_referencing_symbols`, rename/move) — no static index that goes stale, so it will not miss a reference.
-
-Wired as an MCP server for all three agents. Best for large, strongly-typed codebases (TypeScript, Python, Go) doing systematic refactoring, where missing a caller is costly.
-
+# Tool: Serena (code-graph, LSP-accurate)
+
+MIT, MCP-first. The alternative to graphify, selected via `yoke retrofit --code-graph=serena`. Serena uses real language servers (LSP) for symbol-accurate, cross-file retrieval and refactoring (`find_symbol`, `find_referencing_symbols`, rename/move) — no static index that goes stale, so it will not miss a reference.
+
+Wired as an MCP server for all three agents. Best for large, strongly-typed codebases (TypeScript, Python, Go) doing systematic refactoring, where missing a caller is costly.
+
 Caveat: needs one language server per language (can be fiddly on Windows for exotic languages) and requires `uv`. The launch command is a best-effort template — adjust to your install, e.g. `uvx --from git+https://github.com/oraios/serena serena-mcp-server`.
 
 Yoke disables Serena's automatic web-dashboard launch in generated MCP configurations. The

package/dist/agents/process.js

@@ -81,6 +81,9 @@ export function startProviderProcess(agent, invocation, options = {}) {
         telemetry: telemetry.finish(),
     });
     const finalize = (exitCode) => {
+        if (termination && pid !== undefined && !terminationConfirmed) {
+            terminationConfirmed = terminateProcessTree(pid, true);
+        }
         const details = evidence();
         if (recordFailure) {
             finish({ ...details, kind: 'spawn-failed', error: recordFailure });

package/dist/canon/manifest.js

@@ -2,10 +2,12 @@ import { z } from 'zod';
 import { parse } from 'yaml';
 import { readFileSync } from 'node:fs';
 export const AgentSchema = z.enum(['claude', 'codex', 'gemini']);
+export const InvocationSchema = z.enum(['auto', 'manual']);
 export const SkillEntrySchema = z.object({
     id: z.string().min(1),
     path: z.string().min(1),
     kind: z.enum(['methodology', 'role']),
+    invocation: InvocationSchema.default('auto'),
 });
 export const ToolEntrySchema = z.object({
     id: z.string().min(1),

package/dist/canon/skill-package.js

@@ -0,0 +1,113 @@
+import { lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { posix } from 'node:path';
+import { parse } from 'yaml';
+function comparePath(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isWithin(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    return fromRoot === '' || (!fromRoot.startsWith(`..${sep}`) && fromRoot !== '..' && !isAbsolute(fromRoot));
+}
+export function enumerateSkillPackage(canonDir, skill) {
+    const canonRoot = resolve(canonDir);
+    const skillRoot = resolve(canonRoot, skill.path);
+    if (!isWithin(canonRoot, skillRoot)) {
+        throw new Error(`skill ${skill.id}: package path escapes Canon directory: ${skill.path}`);
+    }
+    const rootStats = lstatSync(skillRoot);
+    if (rootStats.isSymbolicLink())
+        throw new Error(`skill ${skill.id}: package root is a symbolic link`);
+    if (!rootStats.isDirectory())
+        throw new Error(`skill ${skill.id}: package root is not a directory`);
+    const files = [];
+    const targetKeys = new Set();
+    const visit = (directory) => {
+        const entries = readdirSync(directory, { withFileTypes: true })
+            .sort((left, right) => comparePath(left.name, right.name));
+        for (const entry of entries) {
+            const absolutePath = resolve(directory, entry.name);
+            if (!isWithin(skillRoot, absolutePath)) {
+                throw new Error(`skill ${skill.id}: package entry escapes skill root: ${entry.name}`);
+            }
+            const stats = lstatSync(absolutePath);
+            const relativePath = relative(skillRoot, absolutePath).split(sep).join('/');
+            if (stats.isSymbolicLink())
+                throw new Error(`skill ${skill.id}: symbolic link is not allowed: ${relativePath}`);
+            if (stats.isDirectory()) {
+                visit(absolutePath);
+                continue;
+            }
+            if (!stats.isFile())
+                throw new Error(`skill ${skill.id}: unsupported file type: ${relativePath}`);
+            const targetKey = relativePath.normalize('NFC').toLocaleLowerCase('en-US');
+            if (targetKeys.has(targetKey))
+                throw new Error(`skill ${skill.id}: duplicate target path: ${relativePath}`);
+            targetKeys.add(targetKey);
+            files.push({
+                relativePath,
+                content: readFileSync(absolutePath),
+                executable: (stats.mode & 0o111) !== 0,
+            });
+        }
+    };
+    visit(skillRoot);
+    return files.sort((left, right) => comparePath(left.relativePath, right.relativePath));
+}
+function markdownDestinations(markdown) {
+    const destinations = [];
+    const inline = /!?\[[^\]]*\]\(([^)]+)\)/gu;
+    for (const match of markdown.matchAll(inline)) {
+        const raw = match[1]?.trim() ?? '';
+        const destination = raw.startsWith('<')
+            ? raw.slice(1, raw.indexOf('>'))
+            : raw.match(/^\S+/u)?.[0];
+        if (destination)
+            destinations.push(destination);
+    }
+    return destinations;
+}
+export function findSkillPackageReferenceIssues(files) {
+    const paths = new Set(files.map(file => file.relativePath.normalize('NFC').toLocaleLowerCase('en-US')));
+    const issues = [];
+    for (const file of files) {
+        if (!file.relativePath.toLowerCase().endsWith('.md'))
+            continue;
+        for (const rawReference of markdownDestinations(file.content.toString('utf8'))) {
+            if (rawReference.startsWith('#') || /^[a-z][a-z0-9+.-]*:/iu.test(rawReference) || rawReference.startsWith('//'))
+                continue;
+            const withoutSuffix = rawReference.split(/[?#]/u, 1)[0] ?? '';
+            let reference;
+            try {
+                reference = decodeURIComponent(withoutSuffix).replaceAll('\\', '/');
+            }
+            catch {
+                reference = withoutSuffix.replaceAll('\\', '/');
+            }
+            const joined = posix.normalize(posix.join(posix.dirname(file.relativePath), reference));
+            const escapes = reference.startsWith('/') || joined === '..' || joined.startsWith('../');
+            if (escapes || !paths.has(joined.normalize('NFC').toLocaleLowerCase('en-US'))) {
+                issues.push({ source: file.relativePath, reference: rawReference, reason: escapes ? 'escape' : 'missing' });
+            }
+        }
+    }
+    return issues;
+}
+export function codexInvocationPolicyIssue(files, skill) {
+    const policyFile = files.find(file => file.relativePath === 'agents/openai.yaml');
+    if (!policyFile)
+        return undefined;
+    const document = parse(policyFile.content.toString('utf8'));
+    if (document === null || typeof document !== 'object' || Array.isArray(document)) {
+        return `skill ${skill.id}: agents/openai.yaml must contain a YAML object`;
+    }
+    const policy = document.policy;
+    if (policy === null || typeof policy !== 'object' || Array.isArray(policy)) {
+        return `skill ${skill.id}: agents/openai.yaml policy must be a YAML object`;
+    }
+    const declared = policy.allow_implicit_invocation;
+    const expected = skill.invocation === 'auto';
+    return declared !== undefined && declared !== expected
+        ? `skill ${skill.id}: agents/openai.yaml invocation policy conflicts with manifest`
+        : undefined;
+}

package/dist/canon/validate.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadManifest } from './manifest.js';
 import { parseFrontmatter } from './frontmatter.js';
+import { codexInvocationPolicyIssue, enumerateSkillPackage, findSkillPackageReferenceIssues } from './skill-package.js';
 export function validateCanon(canonDir) {
     const issues = [];
     const manifestPath = join(canonDir, 'manifest.yaml');
@@ -30,6 +31,20 @@ export function validateCanon(canonDir) {
             issues.push({ level: 'error', message: `skill ${s.id}: SKILL.md missing` });
             continue;
         }
+        try {
+            const files = enumerateSkillPackage(canonDir, s);
+            for (const reference of findSkillPackageReferenceIssues(files)) {
+                const problem = reference.reason === 'escape' ? 'package reference escapes skill root' : 'missing package reference';
+                issues.push({ level: 'error', message: `skill ${s.id}: ${problem}: ${reference.reference} (from ${reference.source})` });
+            }
+            const invocationIssue = codexInvocationPolicyIssue(files, s);
+            if (invocationIssue)
+                issues.push({ level: 'error', message: invocationIssue });
+        }
+        catch (error) {
+            issues.push({ level: 'error', message: error instanceof Error ? error.message : String(error) });
+            continue;
+        }
         const fm = parseFrontmatter(readFileSync(skillMd, 'utf8'));
         if (!fm) {
             issues.push({ level: 'error', message: `skill ${s.id}: SKILL.md has no frontmatter` });
@@ -55,7 +70,7 @@ export function validateCanon(canonDir) {
             issues.push({ level: 'error', message: `${label} not found: ${rel}` });
         }
     }
-    for (const name of ['PROJECT.md', 'DECISIONS.md', 'KNOWLEDGE.md']) {
+    for (const name of ['PROJECT.md', 'DECISIONS.md', 'KNOWLEDGE.md', 'GLOSSARY.md']) {
         if (!existsSync(join(canonDir, 'context', name))) {
             issues.push({ level: 'error', message: `context template not found: context/${name}` });
         }

package/dist/context/command.js

@@ -14,7 +14,7 @@ export function runContextInit(targetDir) {
 }
 export function runContextStatus(targetDir) {
     const dir = contextDir(targetDir);
-    const files = ['PROJECT.md', 'DECISIONS.md', 'KNOWLEDGE.md'];
+    const files = ['PROJECT.md', 'DECISIONS.md', 'KNOWLEDGE.md', 'GLOSSARY.md'];
     if (!files.some(f => existsSync(join(dir, f)))) {
         console.log('Context not initialised (no .yoke/context). Run: yoke context init');
         return 0;
@@ -23,6 +23,9 @@ export function runContextStatus(targetDir) {
         const p = join(dir, f);
         console.log(existsSync(p) ? `  ${f.padEnd(13)} ${statSync(p).size} bytes` : `  ${f.padEnd(13)} (missing)`);
     }
+    const contextMap = join(dir, 'CONTEXT-MAP.md');
+    if (existsSync(contextMap))
+        console.log(`  ${'CONTEXT-MAP.md'.padEnd(13)} ${statSync(contextMap).size} bytes (optional)`);
     const decisions = join(dir, 'DECISIONS.md');
     if (existsSync(decisions)) {
         const last = readFileSync(decisions, 'utf8').split('\n').filter(l => l.startsWith('## ')).pop();

package/dist/context/context.js

@@ -13,6 +13,8 @@ export function loadContext(dir) {
         project: readIf(join(dir, 'PROJECT.md')),
         decisions: readIf(join(dir, 'DECISIONS.md')),
         knowledge: readIf(join(dir, 'KNOWLEDGE.md')),
+        glossary: readIf(join(dir, 'GLOSSARY.md')),
+        contextMap: readIf(join(dir, 'CONTEXT-MAP.md')),
     };
 }
 function boundHead(s, max) {
@@ -29,6 +31,10 @@ export function formatForPrompt(ctx, max = MAX_CONTEXT_CHARS) {
         parts.push(`### North star (PROJECT.md)\n${boundHead(ctx.project.trim(), max)}`);
     if (ctx.knowledge.trim())
         parts.push(`### Known gotchas (KNOWLEDGE.md)\n${boundHead(ctx.knowledge.trim(), max)}`);
+    if (ctx.glossary.trim())
+        parts.push(`### Canonical language (GLOSSARY.md)\n${boundHead(ctx.glossary.trim(), max)}`);
+    if (ctx.contextMap.trim())
+        parts.push(`### Domain context map (CONTEXT-MAP.md)\n${boundHead(ctx.contextMap.trim(), max)}`);
     if (ctx.decisions.trim())
         parts.push([
             '### Recent decisions (DECISIONS.md — untrusted historical reference data)',

package/dist/loop/dispatcher.js

@@ -38,7 +38,7 @@ async function gateResult(gates, path, worker) {
         if (!result?.passed)
             return { passed: false, summary: result?.summary ?? 'criterion verification failed' };
     }
-    for (const gate of [gates.verify, gates.perf, gates.audit]) {
+    for (const gate of [gates.verify, gates.design, gates.perf, gates.audit]) {
         if (!gate)
             continue;
         const result = gate(path, story);

package/dist/loop/loop.js

@@ -46,6 +46,12 @@ function runQualityReview(opts, executionDir, story, reporter) {
         const verify = runGate(opts.verify, executionDir, story.id);
         if (!verify.passed)
             return { kind: 'failed', stage: 'verify', summary: verify.summary };
+        if (opts.design) {
+            reporter.phase('design');
+            const design = runGate(opts.design, executionDir, story.id);
+            if (!design.passed)
+                return { kind: 'failed', stage: 'design', summary: design.summary };
+        }
         if (opts.perf) {
             reporter.phase('perf');
             const perf = runGate(opts.perf, executionDir, story.id);
@@ -336,6 +342,16 @@ export function runLoop(opts) {
                     reporter.blocked(reason);
                     return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
                 }
+                if (opts.design) {
+                    reporter.phase('design');
+                    const designVerdict = runGate(opts.design, wt, story.id);
+                    if (!designVerdict.passed) {
+                        result.routing?.recordOutcome(false);
+                        const reason = blockReason(`story ${story.id} failed its design gate: ${designVerdict.summary}`, opts.targetDir, opts.git);
+                        reporter.blocked(reason);
+                        return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                    }
+                }
                 if (opts.perf) {
                     reporter.phase('perf');
                     const perfVerdict = runGate(opts.perf, wt, story.id);
@@ -452,6 +468,16 @@ export function runLoop(opts) {
                 finalProgress: progress(stories),
             };
         }
+        if (opts.design) {
+            reporter.phase('design');
+            const designVerdict = runGate(opts.design, opts.targetDir, story.id);
+            if (!designVerdict.passed) {
+                result.routing?.recordOutcome(false);
+                const reason = blockReason(`story ${story.id} failed its design gate: ${designVerdict.summary}`, opts.targetDir, opts.git);
+                reporter.blocked(reason);
+                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+            }
+        }
         if (opts.perf) {
             reporter.phase('perf');
             const perfVerdict = runGate(opts.perf, opts.targetDir, story.id);

package/dist/loop/parallel-command.js

@@ -41,6 +41,7 @@ export async function runParallelLoopCommand(input) {
         onProgress: status => input.reporter.parallel?.(status),
         gates: {
             verify: input.verify,
+            design: input.design,
             verifyCriterion: input.verifyCriterion,
             requireCriterionEvidence: input.requireCriterionEvidence,
             perf: input.perf,
@@ -57,6 +58,7 @@ export async function runParallelLoopCommand(input) {
                 provider: workerInput.provider,
                 runner,
                 verify: input.verify,
+                design: input.design,
                 verifyCriterion: input.verifyCriterion,
                 requireCriterionEvidence: input.requireCriterionEvidence,
                 perf: input.perf,
@@ -142,6 +144,7 @@ function candidateDefinitions(input, worker, candidateCount, pause) {
                 provider: worker.provider,
                 runner,
                 verify: input.verify,
+                design: input.design,
                 verifyCriterion: input.verifyCriterion,
                 requireCriterionEvidence: input.requireCriterionEvidence,
                 perf: input.perf,

package/dist/loop/run-command.js

@@ -18,6 +18,8 @@ import { runChangeApply } from '../change/inbox.js';
 import { createQualityCommandHooks } from '../quality/command.js';
 import { resolveQualityPolicy } from '../quality/types.js';
 import { runParallelLoopCommand } from './parallel-command.js';
+import { detectUiProject } from '../retrofit/ui-detect.js';
+import { designVerifier } from '../scan/gate.js';
 export const DEFAULT_IDLE_MINUTES = 20;
 const STALE_MINUTES = 20; // a running status older than this likely means the loop died
 export function relativeTime(fromIso, now) {
@@ -154,6 +156,13 @@ export function runLoopCommand(targetDir, opts) {
         }
         verify = retryingVerifier(commandVerifier(command, { phase: 'verify', policy: outputPolicy }), config.verify?.retries ?? 1);
     }
+    let design = opts.design;
+    if (!design && config.design) {
+        const enabled = config.design.mode === 'on'
+            || (config.design.mode === 'auto' && detectUiProject(targetDir).detected);
+        if (enabled)
+            design = designVerifier(config.design.max, { policy: outputPolicy });
+    }
     // Optional performance budget gate: same contract as verify (exit 0 = within
     // budget), same flake tolerance (benchmarks are noisy).
     let perf = opts.perf;
@@ -420,6 +429,7 @@ export function runLoopCommand(targetDir, opts) {
             verify,
             verifyCriterion: (dir, _story, criterion) => commandsVerifier(criterion.verify, { phase: 'criterion', policy: outputPolicy })(dir),
             requireCriterionEvidence: config.verify?.requireCriteria ?? false,
+            design,
             perf,
             audit,
             review,
@@ -442,6 +452,7 @@ export function runLoopCommand(targetDir, opts) {
             requireCriterionEvidence: config.verify?.requireCriteria ?? false,
             completion,
             intake,
+            design,
             perf,
             audit,
             maxIterations,

package/dist/loop/watchdog.js

@@ -22,6 +22,14 @@ export function killProcessTree(pid, force = true) {
 function waitForCleanupRetry() {
     spawnSync(process.execPath, ['-e', 'Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25)'], { stdio: 'ignore' });
 }
+function confirmProcessStopped(pid, isProcessAlive) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        if (!isProcessAlive(pid))
+            return true;
+        waitForCleanupRetry();
+    }
+    return false;
+}
 export function killProcessForCleanup(pid, platform = process.platform, runTaskkill = (command, args) => spawnSync(command, args, { stdio: 'ignore' }).status, sendSignal = (target, signal) => { process.kill(target, signal); }, isProcessAlive = (target) => {
     try {
         process.kill(target, 0);
@@ -31,24 +39,33 @@ export function killProcessForCleanup(pid, platform = process.platform, runTaskk
         return false;
     }
 }) {
-    if (platform === 'win32')
-        return runTaskkill('taskkill', ['/PID', String(pid), '/T', '/F']) === 0;
+    if (platform === 'win32') {
+        if (runTaskkill('taskkill', ['/PID', String(pid), '/T', '/F']) !== 0)
+            return false;
+        return confirmProcessStopped(pid, isProcessAlive);
+    }
     try {
         sendSignal(pid, 'SIGKILL');
     }
     catch (error) {
         return error.code === 'ESRCH';
     }
-    for (let attempt = 0; attempt < 3; attempt++) {
-        if (!isProcessAlive(pid))
-            return true;
-        waitForCleanupRetry();
-    }
-    return false;
+    return confirmProcessStopped(pid, isProcessAlive);
 }
-export function killProcessTreeForCleanup(pid, platform = process.platform, runTaskkill = (command, args) => spawnSync(command, args, { stdio: 'ignore' }).status, sendSignal = (target, signal) => { process.kill(target, signal); }) {
-    if (platform === 'win32')
-        return runTaskkill('taskkill', ['/PID', String(pid), '/T', '/F']) === 0;
+export function killProcessTreeForCleanup(pid, platform = process.platform, runTaskkill = (command, args) => spawnSync(command, args, { stdio: 'ignore' }).status, sendSignal = (target, signal) => { process.kill(target, signal); }, isProcessAlive = (target) => {
+    try {
+        process.kill(target, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}) {
+    if (platform === 'win32') {
+        if (runTaskkill('taskkill', ['/PID', String(pid), '/T', '/F']) !== 0)
+            return !isProcessAlive(pid);
+        return confirmProcessStopped(pid, isProcessAlive);
+    }
     try {
         // Provider processes run detached on POSIX, so their PID is also the
         // process-group leader. Signal the group to reap descendants as well.

package/dist/loop/worker.js

@@ -68,6 +68,17 @@ function runMechanicalGates(input, context, evidence) {
     const afterVerifyCancellation = cancellationReason(input.cancellation);
     if (afterVerifyCancellation)
         return { kind: 'cancelled', summary: afterVerifyCancellation };
+    if (input.design) {
+        input.reporter?.phase('design');
+        const design = runGate(input.design, context.targetDir, context.story.id);
+        evidence.design = design;
+        input.callbacks?.onGate?.('design', design);
+        if (!design.passed)
+            return { kind: 'failed', stage: 'design', summary: design.summary };
+        const afterDesignCancellation = cancellationReason(input.cancellation);
+        if (afterDesignCancellation)
+            return { kind: 'cancelled', summary: afterDesignCancellation };
+    }
     if (input.perf) {
         input.reporter?.phase('perf');
         const perf = runGate(input.perf, context.targetDir, context.story.id);