@hecer/yoke 1.5.1 → 1.6.0

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,6 +5,7 @@ import { mcpServers, rtkInstruction } from '../tools.js';
 import { hasWsl } from '../wsl.js';
 import { detectGstack } from '../gstack.js';
 import { PRESERVE_SCAFFOLD } from '../preserve.js';
+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:
@@ -25,12 +26,7 @@ export function planClaude(canonDir, targetDir, wslAvailable = hasWsl(), codeGra
     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/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/PUBLISHING.md

@@ -1,6 +1,6 @@
 # Publishing channels — status & playbook
 
-Where Yoke is published, and how each channel gets updated. (Reviewed 2026-08-15.)
+Where Yoke is published, and how each channel gets updated. (Reviewed 2026-08-20.)
 
 ## Live
 
@@ -33,7 +33,7 @@ release object is created. Use this idempotent check after the version commit re
 
 ```bash
 set -euo pipefail
-VERSION=1.5.0
+VERSION=1.6.0
 TARGET=$(git rev-parse HEAD)
 git fetch --tags origin
 

package/docs/superpowers/plans/2026-08-20-automatic-ui-design-gate.md

@@ -0,0 +1,59 @@
+# Automatic UI Design Gate Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan.
+
+**Goal:** Automatically run Yoke's existing design scanner inside configured UI-project loops while preserving current behavior for non-UI and already-configured projects.
+
+**Architecture:** Add one deterministic local detector, one default-preserving config section, and a small verifier adapter over the existing scanner. Thread that verifier through the serial and parallel loop gate contracts in the same position and evidence model as existing mechanical gates.
+
+**Tech Stack:** TypeScript, Zod, Vitest, existing design scanner and loop abstractions.
+
+---
+
+## Task 1: Detect UI projects with explained evidence
+
+**Files:** `src/retrofit/ui-detect.ts`, `src/retrofit/detect.ts`, `tests/retrofit/ui-detect.test.ts`, `tests/retrofit/detect.test.ts`
+
+1. Add failing tests for supported dependencies, `.tsx`, `.jsx`, `.vue`, `.svelte`, `.astro`, an existing smoke-flow config, non-UI TypeScript, and ignored dependency/generated/fixture/Yoke directories.
+2. Implement bounded traversal of normal source roots and package manifests. Return `{ detected, signals }` with stable, human-readable signals.
+3. Attach UI evidence to Retrofit detection without changing existing agent detection semantics.
+4. Run the detector tests.
+
+## Task 2: Add default-preserving design configuration
+
+**Files:** `src/retrofit/config.ts`, `src/retrofit/command.ts`, `tests/retrofit/config.test.ts`, `tests/retrofit/integration.test.ts`
+
+1. Add failing schema tests for `mode: off|auto|on`, positive integer `max`, invalid values, and omitted design config.
+2. Add optional `design` to the config type and schema. Do not place it in the universal legacy default.
+3. During new/retrofit setup, write `{ mode: 'auto', max: 4 }` only when UI detection succeeds and no user design choice exists.
+4. Include the detector's evidence in setup output and test that an existing `off`, `on`, or custom budget is preserved.
+5. Run config and Retrofit integration tests.
+
+## Task 3: Adapt design scan results to a mechanical gate
+
+**Files:** `src/scan/gate.ts`, `src/scan/design.ts`, `src/cli.ts`, `tests/scan/gate.test.ts`, `tests/scan/design.test.ts`
+
+1. Add failing tests for pass/fail at a configured budget, stable finding names, bounded preview text, and a full artifact path for overflow details.
+2. Extract only shared result formatting from the standalone command; do not change its public output or scanner weights.
+3. Implement a verifier adapter that runs `scanDir`, returns the existing verify-result contract, and writes full findings through the existing artifact helper.
+4. Run scan tests and a CLI design-scan regression test.
+
+## Task 4: Thread the gate through serial and parallel loops
+
+**Files:** `src/loop/run-command.ts`, `src/loop/loop.ts`, `src/loop/worker-contracts.ts`, `src/loop/worker.ts`, `src/loop/parallel-command.ts`, `src/loop/parallel.ts`, `src/loop/dispatcher.ts`, `src/loop/parallel-adapters.ts`, `src/output/types.ts`, matching `tests/loop/*.test.ts`
+
+1. Add failing serial tests showing order `criteria -> verify -> design -> perf -> audit` and proving omitted or `off` design leaves the old call sequence unchanged.
+2. Add failing worker and dispatcher tests for design evidence, stage-specific failure, retry/quality-rerun behavior, and cancellation.
+3. Extend gate stage unions, callbacks, evidence, and output phases with `design`; make the verifier optional throughout.
+4. Construct the verifier in `run-command` for `on`, for detected `auto`, and never for `off` or missing config.
+5. Run all loop tests, then `rtk npm run lint`.
+
+## Task 5: Verify setup-to-loop behavior
+
+**Files:** `tests/retrofit/integration.test.ts`, `tests/loop/run-command.test.ts`
+
+1. Add an integration fixture for a detected UI project and one for a non-UI project.
+2. Prove Retrofit writes auto config only to the UI fixture and the next loop run selects the design verifier only there.
+3. Prove `mode: on` overrides failed detection and `mode: off` overrides successful detection.
+4. Run `rtk npm exec -- vitest run tests/retrofit tests/scan tests/loop`.
+

package/docs/superpowers/plans/2026-08-20-capability-skills-and-context.md

@@ -0,0 +1,51 @@
+# Capability Skills and Context Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan.
+
+**Goal:** Add the prose, domain, codebase-design, merge-resolution, and agent-writing capabilities identified in the source review, with durable terminology context and clear attribution.
+
+**Architecture:** Keep capabilities as independent Canon packages selected through the manifest. Use resource files for evaluation material, keep `.yoke/context` as the durable project source of truth, and connect prose review to documentation workflows without making style a release gate.
+
+**Tech Stack:** Markdown skill packages, TypeScript context loader, YAML manifest, Vitest, provenance audit tools.
+
+---
+
+## Task 1: Import and adapt `no-ai-slop`
+
+**Files:** `canon/skills/no-ai-slop/SKILL.md`, `canon/skills/no-ai-slop/eval.md`, `canon/ATTRIBUTION.md`, `canon/manifest.yaml`, `tests/canon/real-canon.test.ts`
+
+1. Run a read-only provenance audit on the upstream package and record unknown signals as unknown.
+2. Add failing real-Canon assertions for the package, its `eval.md` reference, auto invocation, and Peter Yang/MIT attribution.
+3. Import the upstream workflow and evaluation checklist. Adapt only the trigger wording, Yoke paths, and the precise-domain-term exception; preserve Edit and Detect modes and prohibit authorship guesses.
+4. Run the package tests and a second read-only provenance audit on the local package.
+
+## Task 2: Add the four complementary capabilities
+
+**Files:** `canon/skills/domain-modeling/SKILL.md`, `canon/skills/codebase-design/SKILL.md`, `canon/skills/resolving-merge-conflicts/SKILL.md`, `canon/skills/writing-for-agents/SKILL.md`, `canon/ATTRIBUTION.md`, `canon/manifest.yaml`, `tests/canon/real-canon.test.ts`
+
+1. Add failing assertions for all four skill ids, frontmatter, auto invocation, and source attribution where material is adapted from Matt Pocock's repository.
+2. Write `domain-modeling` around terminology discovery, scenario checks, code comparison, glossary updates, and the existing ADR threshold.
+3. Write `codebase-design` around deep modules, small interfaces, real seams, public-interface tests, and local change.
+4. Write `resolving-merge-conflicts` around current-operation discovery, commit/spec evidence, preservation of both compatible intents, scoped checks, and no implicit abort.
+5. Write `writing-for-agents` around observable outcomes, concrete paths and commands, bounded context, explicit triggers, and deduplicated durable instructions.
+6. Validate Canon and run the real-Canon tests.
+
+## Task 3: Add glossary-aware project context
+
+**Files:** `canon/context/GLOSSARY.md`, `src/retrofit/context-actions.ts`, `src/context/context.ts`, `src/context/command.ts`, `tests/retrofit/context-actions.test.ts`, `tests/context/context.test.ts`, `tests/context/command.test.ts`
+
+1. Add failing tests that Retrofit introduces `GLOSSARY.md` with `ifAbsent`, existing context is unchanged, and `CONTEXT-MAP.md` is loaded only when present.
+2. Add a concise glossary template for canonical terms, aliases, rejected terms, and concrete examples.
+3. Extend context loading and formatted prompt context with bounded glossary content and optional bounded context-map content.
+4. Extend context status output so required glossary state and optional context-map state are distinguishable.
+5. Run the context and context-action tests.
+
+## Task 4: Connect prose quality to documentation workflows
+
+**Files:** `canon/skills/document-release/SKILL.md`, `canon/roles/docs.yaml`, `CONTRIBUTING.md`, `tests/canon/real-canon.test.ts`
+
+1. Add failing assertions that documentation release guidance invokes `no-ai-slop` evaluation without turning it into a mechanical pass/fail gate.
+2. Update the skill and docs role to request minimal voice-preserving edits and explicit reporting of observed patterns.
+3. Use the new skill in Detect mode on changed prose, then Edit mode only where a listed pattern is actually present.
+4. Run Canon validation and provenance-audit the changed documentation set.
+

package/docs/superpowers/plans/2026-08-20-complete-skill-packages-and-invocation.md

@@ -0,0 +1,59 @@
+# Complete Skill Packages and Invocation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan.
+
+**Goal:** Install every Canon skill as a complete, safe resource package and preserve explicit automatic or manual invocation intent across Claude, Codex, and Gemini.
+
+**Architecture:** Extend the parsed Canon manifest with a defaulted invocation policy, enumerate package files once behind a fail-closed boundary, and make every provider planner consume the same normalized package model. Extend Retrofit actions only enough to preserve byte content and executable intent; provider-specific policy remains generated output, not Canon source.
+
+**Tech Stack:** TypeScript, Zod, YAML, Vitest, Node filesystem APIs.
+
+---
+
+## Task 1: Add invocation policy to the manifest contract
+
+**Files:** `src/canon/manifest.ts`, `tests/canon/manifest.test.ts`, `tests/canon/real-canon.test.ts`, `canon/manifest.yaml`
+
+1. Add failing tests proving omitted `invocation` parses as `auto`, `manual` parses, and unknown values fail.
+2. Add `InvocationSchema = z.enum(['auto', 'manual'])` and default `invocation` to `auto` on each skill entry.
+3. Add explicit `invocation` values to every real Canon skill and assert the real manifest has no implicit entries.
+4. Run `rtk npm exec -- vitest run tests/canon/manifest.test.ts tests/canon/real-canon.test.ts`.
+
+## Task 2: Enumerate and validate complete skill packages
+
+**Files:** `src/canon/skill-package.ts`, `src/canon/validate.ts`, `tests/canon/skill-package.test.ts`, `tests/canon/validate.test.ts`
+
+1. Write failing tests for stable relative-path ordering, nested Markdown and binary resources, executable metadata, symlink rejection, path escape rejection, unsupported node types, duplicate normalized targets, and missing relative Markdown references.
+2. Implement `enumerateSkillPackage(canonDir, skill)` returning immutable records with `relativePath`, `content: Buffer`, and `executable`.
+3. Normalize separators to `/`, resolve every candidate beneath the skill root, use `lstat` to reject links and special files, and never follow a path outside the root.
+4. Extend Canon validation to enumerate each package and validate local relative Markdown links without fetching HTTP links or validating anchors.
+5. Run `rtk npm exec -- vitest run tests/canon/skill-package.test.ts tests/canon/validate.test.ts` and `rtk npm run yoke -- validate canon`.
+
+## Task 3: Let Retrofit actions preserve package bytes and executable intent
+
+**Files:** `src/retrofit/plan.ts`, `src/retrofit/apply.ts`, `tests/retrofit/apply.test.ts`
+
+1. Add failing tests for a binary action, unchanged binary content, and executable-mode preservation where the platform supports it.
+2. Change write actions to accept `string | Uint8Array` and optional `executable`; retain string-only JSON merge and carry-preserved behavior with explicit guards.
+3. Compare and write buffers without UTF-8 conversion. Apply executable bits on non-Windows after the atomic content write.
+4. Run `rtk npm exec -- vitest run tests/retrofit/apply.test.ts`.
+
+## Task 4: Generate provider-specific skill outputs
+
+**Files:** `src/retrofit/skill-actions.ts`, `src/retrofit/planners/claude.ts`, `src/retrofit/planners/codex.ts`, `src/retrofit/planners/gemini.ts`, `tests/retrofit/planners/claude.test.ts`, `tests/retrofit/planners/codex.test.ts`, `tests/retrofit/planners/gemini.test.ts`
+
+1. Add fixtures containing nested Markdown and a binary resource, plus one manual skill.
+2. Add failing Claude tests for complete package copying and `disable-model-invocation: true` only on generated manual `SKILL.md` frontmatter.
+3. Add failing Codex tests for complete copying and generated or merged `agents/openai.yaml` with `policy.allow_implicit_invocation` matching the manifest.
+4. Add failing Gemini tests for copied resources, unchanged command generation, manual command-only behavior, and a compact auto-skill index that excludes manual skills.
+5. Implement shared action generation from the package enumerator. Ensure generated policy files cannot silently conflict with a Canon-provided file.
+6. Run all three planner test files.
+
+## Task 5: Prove backward compatibility end to end
+
+**Files:** `tests/retrofit/integration.test.ts`, `tests/canon/real-canon.test.ts`
+
+1. Add an integration test that an existing one-file skill installs byte-for-byte as before.
+2. Add an integration test that one resource-bearing skill installs its referenced resource for all three agents.
+3. Run `rtk npm exec -- vitest run tests/canon tests/retrofit` and `rtk npm run lint`.
+