@hecer/yoke 1.5.0 → 1.6.0

package/canon/skills/no-ai-slop/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: no-ai-slop
+description: Edit prose into clearer, more direct writing while preserving the writer's voice, or detect named AI-slop patterns without rewriting or guessing authorship. Use for documentation, release notes, product copy, or prose audits; do not trigger for code-only work.
+---
+
+# No AI slop
+
+Preserve the writer's point and voice while making the prose clearer and more alive. Remove observed
+patterns without turning distinctive writing into generic polished copy.
+
+## Choose the job
+
+**Edit (default).** Make the minimum effective edit. Return the full edited draft and a short
+**What changed** section.
+
+**Detect.** Name every pattern from this skill that appears, quote the affected line, and give a
+short fix. Do not rewrite, score the draft, or guess whether AI wrote it. Offer an edit after the
+report.
+
+If no draft was provided, ask for it. Ask one audience/format question only when the answer would
+materially change the edit. If the goal is unclear, ask what the reader should think, feel, or do.
+
+## Editing principles
+
+- Read the full draft first and identify its point plus the vocabulary, cadence, bluntness, humor,
+  uncertainty, digressions, and polish level worth preserving.
+- Make the minimum effective change. Fix observed patterns, errors, repetition, and unclear
+  passages. Leave strong sentences alone.
+- Keep the writer's meaning. Do not invent claims, examples, statistics, sources, or opinions.
+- Lead with the point when setup adds nothing. Keep setup that adds context, tension, or character.
+- Open up tangled prose without flattening its cadence. Keep clear fragments and changes in pace.
+- Prefer concrete facts, mechanisms, consequences, and judgments over abstract importance.
+- Use the portability test: a sentence that could move unchanged to another product or company is
+  probably filler unless it carries a necessary general rule.
+- Let facts and examples carry emphasis. Remove commentary that tells the reader what is important
+  when the prose already shows it.
+- Prefer direct verbs and active voice when they are clearer.
+- Preserve useful edge, strong opinions, humor, and honest uncertainty.
+- Keep the existing structure unless it hurts the piece. Report any meaningful reorganization.
+- Preserve precise technical and domain terms. A word that is empty in marketing copy can still be
+  correct in a product vocabulary. In Yoke, **coding harness** is an established, precise term; do
+  not replace it merely because "harness" is often vague elsewhere.
+
+## Words and phrases to inspect
+
+Remove these when they add no precise meaning: delve, foster, leverage, utilize, facilitate,
+empower, streamline, robust, cutting-edge, paradigm shift, game changer, tapestry, realm, beacon,
+multifaceted, meticulous, intricate, paramount, transformative, elevate, embark, supercharge,
+harness, ever-evolving.
+
+Inspect often-empty adverbs such as just, literally, honestly, simply, actually, truly,
+fundamentally, importantly, crucially, inherently, and inevitably. Keep one when it carries real
+emphasis, uncertainty, contrast, or spoken rhythm.
+
+Inspect filler such as "it's worth noting," "at the end of the day," "when it comes to," "at its
+core," "in today's world," "the reality is," "in terms of," "going forward," and "let's dive in."
+Cut it when it delays the point.
+
+The lists above are prompts for judgment, not blind replacements. Quoted examples, precise domain
+language, and the writer's recognizable voice take precedence.
+
+## Patterns to cut
+
+- **Binary contrasts:** "This is not X. It's Y." State Y directly.
+- **Throat-clearing:** "Here's the thing," "Let me be clear," or "The truth is." Start with the
+  point.
+- **Faux-insight setups:** "What most people get wrong" or "The part everyone misses." Make the
+  claim stand on evidence.
+- **Colon reveals:** a dramatic noun phrase followed by a lowercase reveal. Use a plain sentence;
+  reserve colons for lists, labels, and quotations.
+- **Superficial analysis:** trailing clauses such as "highlighting" or "underscoring" that label
+  significance instead of explaining a mechanism or consequence.
+- **Importance puffery:** "marks a pivotal moment," "plays a vital role," or "stands as a
+  testament." State the fact.
+- **Interpretive metadiscourse:** "The key point is," "As you can see," "This distinction matters,"
+  or a redundant "In other words." Delete it or add the missing support.
+- **Weasel attribution:** "experts agree," "studies show," or "widely regarded as." Name the source
+  or flag the unsupported claim.
+- **Fake-strong verbs:** prefer "is" or "has" when they are clearer; otherwise name what the thing
+  actually does.
+- **Synonym cycling:** repeat the correct term instead of rotating agent, assistant, and tool for
+  style.
+- **Negative listing:** "Not X. Not Y. Z." State Z.
+- **Dramatic fragmentation:** stacked punchy fragments or "That's it. That's the whole thing."
+- **Robotic rhythm:** repeated sentence shapes, identical paragraph structures, or forced symmetry.
+- **Rhetorical setups:** "What if I told you," "Plot twist," and self-answered question/answer pairs.
+- **Fake-profound kickers:** delete the decorative final metaphor or mic-drop line. End on the last
+  concrete point or next action.
+- **Summary-recap endings:** remove a final paragraph that merely repeats the piece.
+- **Formatting slop:** emoji headings, decorative bold, bullets that should be sentences, and
+  headings over tiny sections.
+- **Em-dash clusters:** use a comma, period, or parentheses unless the dash clearly improves the
+  sentence. Short copy usually needs none.
+
+## Workflow
+
+1. Read the whole draft and identify the point plus three to five voice signals internally.
+2. In Detect mode, return named findings with quoted lines and short fixes, then stop.
+3. In Edit mode, make the minimum useful changes.
+4. Read [eval.md](eval.md) and check the result directly. Fix each failed check.
+5. Return the full edited draft and **What changed**.
+
+This skill reports observable prose patterns. It never classifies authorship.

package/canon/skills/no-ai-slop/eval.md

@@ -0,0 +1,43 @@
+# No AI slop eval
+
+Use this after an edit. Mark each check pass or fail; fix failures before returning the draft.
+
+For Detect mode, verify that the report names each observed pattern, quotes the affected passage,
+and gives a short fix without rewriting, scoring, or claiming authorship.
+
+## Meaning and voice
+
+1. Does the edit preserve the writer's point without adding claims, examples, statistics, quotes,
+   sources, or opinions?
+2. Does it preserve distinctive vocabulary, cadence, bluntness, humor, uncertainty, digressions,
+   and level of polish?
+3. Were strong sentences left alone instead of normalized for consistency?
+4. Is the amount of cutting proportional to the observed problems?
+5. Does useful setup remain while generic throat-clearing is gone?
+6. Was structure preserved unless changing it improved comprehension?
+7. Are precise technical and domain terms unchanged, including established Yoke product language?
+
+## Clarity
+
+1. Does each generic sentence pass the portability test or carry a necessary general rule?
+2. Do concrete facts, mechanisms, examples, consequences, and direct verbs do the work?
+3. Are tangled sentences fixed while clear spoken cadence and fragments remain?
+4. Are unsupported attributions named as unsupported rather than replaced with invented sources?
+
+## Pattern check
+
+1. Are empty buzzwords, filler phrases, and inflated claims removed unless quoted or used precisely?
+2. Are binary contrasts, negative lists, rhetorical setups, and throat-clearing removed?
+3. Are faux-insight setups, colon reveals, superficial analysis, synonym cycling, dramatic fragments,
+   and robotic rhythm fixed?
+4. Is importance puffery replaced with facts, and interpretive metadiscourse removed?
+5. Are decorative kickers and recap endings gone?
+6. Does formatting follow the content instead of decorating it?
+7. Are colons grammatical and em dashes sparse?
+
+## Final read
+
+1. Would the writer recognize the edited draft as their own voice?
+2. Would it sound natural when read to a sharp colleague?
+3. Does Edit output include the full draft and **What changed**?
+4. Does Detect output stop after named, quoted, actionable findings?

package/canon/skills/resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: resolving-merge-conflicts
+description: Resolve an in-progress Git merge or rebase conflict by tracing both sides to commits and available issue or spec evidence, preserving compatible intent, and running project checks. Use only when a merge or rebase is currently conflicted.
+---
+
+# Resolving merge conflicts
+
+1. Inspect the current merge or rebase state, history, and every conflicted file.
+2. Trace both sides to their commits and available pull request, issue, specification, and test
+   evidence. Identify what each change was trying to preserve.
+3. Resolve each hunk. Preserve both intents when compatible. When they conflict, follow the current
+   operation's stated goal and report the trade-off. Do not invent unrelated behavior.
+4. Discover and run the project's scoped checks, then the broader checks justified by the merge.
+5. Stage resolved files and continue the current operation until Git reports it complete.
+
+Keep all process actions scoped to the current repository and recorded operation. Never abort a
+merge or rebase unless the user explicitly requests that destructive reversal. Stop for direction
+when the evidence cannot distinguish two materially different product behaviors.

package/canon/skills/writing-for-agents/SKILL-MECHANICS.md

@@ -0,0 +1,27 @@
+# Skill mechanics
+
+## Entrypoint
+
+`SKILL.md` needs `name` and a discriminating `description`. The description is the always-loaded
+context pointer: state the capability, real trigger branches, and a boundary only when it prevents
+likely misrouting.
+
+Keep common actions and constraints in `SKILL.md`. Put substantial conditional procedures,
+formats, or examples in linked resources, and state when the agent should load each one.
+
+## Invocation
+
+Yoke records invocation in `canon/manifest.yaml`:
+
+- `auto` allows provider-supported automatic selection and explicit user invocation.
+- `manual` excludes automatic advertising and requires explicit invocation.
+
+Choose `auto` when an agent or another workflow must discover the capability. Choose `manual` when
+only a user should select it and the cognitive cost is intentional. Provider metadata is generated
+by Retrofit; do not add provider-specific policy to a normal Canon package.
+
+## Validation
+
+The package must remain self-contained. Every relative Markdown link resolves inside the package,
+symlinks and path escapes are rejected, and resources install for every supported provider. Test
+observable routing or output behavior rather than only matching headings.

package/canon/skills/writing-for-agents/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: writing-for-agents
+description: Create or edit agent-facing instructions such as AGENTS.md, CLAUDE.md, skills, roles, and workflow documents. Use when triggers, completion criteria, context pointers, instruction hierarchy, or duplication affect whether an agent can execute the document reliably.
+---
+
+# Writing for agents
+
+Write instructions that produce a repeatable process with observable completion, while preserving
+authorization, safety rules, acceptance criteria, and precise domain language.
+
+## Context pointers
+
+A pointer names out-of-context material and states when to load it. A skill description and an
+`AGENTS.md` link serve the same routing function.
+
+- Front-load the capability or trigger.
+- Name each genuinely different branch once; remove synonymous trigger lists.
+- Keep must-have instructions behind a pointer only when its trigger is strong enough to load them.
+- Spend always-loaded context on rules needed broadly; disclose branch-specific reference material.
+
+## Information hierarchy
+
+1. Put ordered actions and their completion criteria in the main file.
+2. Co-locate definitions, rules, and caveats that an action needs.
+3. Move substantial branch-specific reference behind a named link and say when to read it.
+4. Keep each durable meaning in one source of truth. Treat scripts, config, and directory structure
+   as discoverable sources instead of copying facts that will go stale.
+
+Every step needs a checkable completion criterion. Prefer an exhaustive observable bound such as
+"every changed public interface has a passing contract test" over "review the interfaces."
+
+## Editing pass
+
+- Remove duplicated, contradictory, stale, or no-op instructions.
+- Replace vague verbs with concrete actions, paths, commands, evidence, and stopping conditions.
+- Separate durable project rules from details that belong only to the current task.
+- Phrase the desired behavior positively. Keep prohibitions for real guardrails and pair them with
+  the action the agent should take.
+- Keep examples only when they distinguish correct behavior from a likely mistake.
+- Preserve user scope: completing a workflow never grants unrelated external or destructive action.
+
+When the document is a skill, read [SKILL-MECHANICS.md](SKILL-MECHANICS.md).

package/canon/tools/serena.md

@@ -4,4 +4,8 @@ MIT, MCP-first. The alternative to graphify, selected via `yoke retrofit --code-
 
 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`.
+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
+dashboard server remains available for manual inspection, but selecting Serena no longer opens a
+browser window on every MCP startup.

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 false;
+        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);