@sun-asterisk/sungen 3.2.2-beta.9 → 3.2.3-beta.3

package/src/orchestrator/ai-skills/adapters.ts

@@ -0,0 +1,52 @@
+/**
+ * Adapter table — one row per assistant. Adding a new assistant = one row here,
+ * zero new content files (the whole point of the single-source migration).
+ *
+ * Output paths preserve the EXACT existing Claude/Copilot conventions (decision 4A) so the
+ * golden-regression net stays byte-identical for Claude. Codex is additive (`.agents/skills/`).
+ */
+
+export type AdapterKey = 'claude' | 'copilot' | 'codex';
+
+export interface Adapter {
+  key: AdapterKey;
+  /** capability tags this adapter owns; cap-fences resolve against this */
+  caps: string[];
+  /** output path for a `kind: skill` unit, given the skill dir name + relative file */
+  skillPath: (skillDir: string, file: string) => string;
+  /** output path for a `kind: command` unit; null => commands render as skills */
+  commandPath: ((name: string) => string) | null;
+  /**
+   * When commandPath is null (Codex), a command renders into the skill tree. This computes
+   * the skill dir for a command, and a backing skill whose name collides gets a `-guide`
+   * suffix (the flat-namespace collision found during spike prep: delivery/dashboard/locale).
+   */
+  commandAsSkillDir?: (name: string) => string;
+  /** Codex needs an explicit trigger prefixed onto the command-skill description */
+  commandTriggerPrefix?: boolean;
+}
+
+export const ADAPTERS: Record<AdapterKey, Adapter> = {
+  claude: {
+    key: 'claude',
+    caps: ['parallel-subagents'],
+    skillPath: (dir, file) => `.claude/skills/${dir}/${file}`,
+    commandPath: (name) => `.claude/commands/sungen/${name}.md`,
+  },
+  copilot: {
+    key: 'copilot',
+    caps: [],
+    skillPath: (dir, file) => `.github/skills/${dir}/${file}`,
+    commandPath: (name) => `.github/prompts/sungen-${name}.prompt.md`,
+  },
+  codex: {
+    key: 'codex',
+    caps: [],
+    skillPath: (dir, file) => `.agents/skills/${dir}/${file}`,
+    commandPath: null, // commands become skills
+    commandAsSkillDir: (name) => `.agents/skills/sungen-${name}`,
+    commandTriggerPrefix: true,
+  },
+};
+
+export const ALL_ADAPTERS: AdapterKey[] = ['claude', 'copilot', 'codex'];

package/src/orchestrator/ai-skills/build.ts

@@ -0,0 +1,103 @@
+/**
+ * buildOutputs — the single entry point init/update call (decision 1A).
+ * Produces the full [outputPath, content, class] set for the selected adapters from the
+ * canonical source. Pure: never touches disk.
+ *
+ * class:
+ *   'managed' — skill/command files; sungen owns them, always overwritten (version-managed)
+ *   'config'  — CLAUDE.md / copilot-instructions.md / AGENTS.md; user-customizable,
+ *               skip-if-exists unless --force (decision 2)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { stripCaps } from './cap-stripper';
+import { ADAPTERS, AdapterKey } from './adapters';
+import { parseCommandSource, generateCommand } from './commands';
+
+export type FileClass = 'managed' | 'config';
+export interface BuiltFile {
+  outputPath: string;
+  content: string;
+  cls: FileClass;
+}
+
+const SRC_SKILLS = path.resolve(__dirname, '..', 'templates', 'ai-src', 'skills');
+const SRC_CMDS = path.resolve(__dirname, '..', 'templates', 'ai-src', 'commands');
+const SRC_AGENTS = path.resolve(__dirname, '..', 'templates', 'ai-src', 'agents');
+const SRC_CONFIG = path.resolve(__dirname, '..', 'templates', 'ai-src', 'config');
+
+// Config files per adapter: [source file under ai-src/config, outputPath].
+const CONFIG: Record<AdapterKey, { src: string; out: string }> = {
+  claude: { src: 'claude.md', out: 'CLAUDE.md' },
+  copilot: { src: 'copilot.md', out: '.github/copilot-instructions.md' },
+  codex: { src: 'codex.md', out: 'AGENTS.md' },
+};
+
+function commandIds(): Set<string> {
+  if (!fs.existsSync(SRC_CMDS)) return new Set();
+  return new Set(fs.readdirSync(SRC_CMDS).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, '')));
+}
+
+/** Build every output file for the given adapters. */
+export function buildOutputs(adapters: AdapterKey[]): BuiltFile[] {
+  const out: BuiltFile[] = [];
+  const cmdIds = commandIds();
+
+  for (const key of adapters) {
+    const adapter = ADAPTERS[key];
+
+    // --- Skills ---
+    if (fs.existsSync(SRC_SKILLS)) {
+      for (const skillDir of fs.readdirSync(SRC_SKILLS)) {
+        const dirPath = path.join(SRC_SKILLS, skillDir);
+        if (!fs.statSync(dirPath).isDirectory()) continue;
+        // Codex flat namespace: a skill whose name collides with a command becomes <dir>-guide.
+        // Both the output dir AND the SKILL.md `name:` frontmatter must change, or Codex would
+        // discover two skills with the same `name` (breaking $name + description selection).
+        const bare = skillDir.replace(/^sungen-/, '');
+        const collide = key === 'codex' && cmdIds.has(bare);
+        const outDir = collide ? `${skillDir}-guide` : skillDir;
+        for (const file of fs.readdirSync(dirPath)) {
+          if (!file.endsWith('.md')) continue;
+          let raw = fs.readFileSync(path.join(dirPath, file), 'utf8');
+          if (collide && file === 'SKILL.md') {
+            raw = raw.replace(/^(name:\s*)sungen-[^\n]*/m, `$1sungen-${bare}-guide`);
+          }
+          out.push({
+            outputPath: adapter.skillPath(outDir, file),
+            content: stripCaps(raw, adapter.caps, `${skillDir}/${file}`),
+            cls: 'managed',
+          });
+        }
+      }
+    }
+
+    // --- Commands ---
+    if (fs.existsSync(SRC_CMDS)) {
+      for (const f of fs.readdirSync(SRC_CMDS)) {
+        if (!f.endsWith('.md')) continue;
+        const id = f.replace(/\.md$/, '');
+        const src = parseCommandSource(fs.readFileSync(path.join(SRC_CMDS, f), 'utf8'), id);
+        const g = generateCommand(src, key);
+        out.push({ outputPath: g.outputPath, content: g.content, cls: 'managed' });
+      }
+    }
+
+    // --- Agents (Claude-only sub-agents; Copilot runs them inline, Codex has no equivalent) ---
+    if (key === 'claude' && fs.existsSync(SRC_AGENTS)) {
+      for (const f of fs.readdirSync(SRC_AGENTS)) {
+        if (!f.endsWith('.md')) continue;
+        const role = f.replace(/\.md$/, '');
+        const raw = fs.readFileSync(path.join(SRC_AGENTS, f), 'utf8');
+        out.push({ outputPath: `.claude/agents/sungen-${role}.md`, content: stripCaps(raw, adapter.caps, `agents/${f}`), cls: 'managed' });
+      }
+    }
+
+    // --- Config (skip-unless-force) ---
+    const cfg = CONFIG[key];
+    const content = fs.readFileSync(path.join(SRC_CONFIG, cfg.src), 'utf8');
+    out.push({ outputPath: cfg.out, content, cls: 'config' });
+  }
+
+  return out;
+}

package/src/orchestrator/ai-skills/cap-stripper.ts

@@ -0,0 +1,85 @@
+/**
+ * Cap-fence stripper for single-source AI skill templates.
+ *
+ * A single source body may contain capability-fenced blocks that are kept or dropped
+ * per target adapter:
+ *
+ *   {{#cap parallel-subagents}}   ... kept only if the adapter HAS the cap ...   {{/cap}}
+ *   {{^cap parallel-subagents}}   ... kept only if the adapter LACKS the cap ... {{/cap}}
+ *
+ * Fence lines must be on their own line. Nesting is forbidden. Unknown cap tags and
+ * unclosed fences FAIL LOUD (decision 5A) so a typo can never silently delete content.
+ *
+ * Blank lines left where a block is removed are normalized (no run of 3+ blank lines),
+ * so the diff-regression golden net stays quiet (decision 3A).
+ */
+
+// Central list of valid capability tags. Adding a capability = adding it here.
+// Measured divergence (2026-06-27) shows essentially one axis today.
+export const VALID_CAPS = ['parallel-subagents'] as const;
+export type Cap = (typeof VALID_CAPS)[number];
+
+const OPEN_POS = /^\s*\{\{#cap\s+([a-z0-9-]+)\s*\}\}\s*$/;
+const OPEN_NEG = /^\s*\{\{\^cap\s+([a-z0-9-]+)\s*\}\}\s*$/;
+const CLOSE = /^\s*\{\{\/cap\}\}\s*$/;
+
+export class CapFenceError extends Error {}
+
+/**
+ * Render `body` for an adapter that owns `caps`.
+ * @param body      raw single-source body (frontmatter already removed)
+ * @param caps      capability tags the target adapter has
+ * @param skillName for error messages
+ */
+export function stripCaps(body: string, caps: readonly string[], skillName = '<unknown>'): string {
+  const has = (tag: string) => caps.includes(tag);
+  const out: string[] = [];
+  let open: { tag: string; keep: boolean; line: number } | null = null;
+
+  const lines = body.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const mPos = line.match(OPEN_POS);
+    const mNeg = line.match(OPEN_NEG);
+    const mClose = CLOSE.test(line);
+
+    if (mPos || mNeg) {
+      if (open) {
+        throw new CapFenceError(
+          `${skillName}: nested cap fence at line ${i + 1} (already inside {{#cap ${open.tag}}} from line ${open.line}); nesting is forbidden`,
+        );
+      }
+      const tag = (mPos ? mPos[1] : mNeg![1]);
+      if (!VALID_CAPS.includes(tag as Cap)) {
+        throw new CapFenceError(
+          `${skillName}: unknown cap tag "${tag}" at line ${i + 1} (valid: ${VALID_CAPS.join(', ')})`,
+        );
+      }
+      // positive: keep when adapter HAS cap; negative: keep when adapter LACKS cap
+      open = { tag, keep: mPos ? has(tag) : !has(tag), line: i + 1 };
+      continue; // fence line itself is never emitted
+    }
+
+    if (mClose) {
+      if (!open) {
+        throw new CapFenceError(`${skillName}: stray {{/cap}} at line ${i + 1} with no open fence`);
+      }
+      open = null;
+      continue; // fence line itself is never emitted
+    }
+
+    if (open) {
+      if (open.keep) out.push(line);
+      // dropped block: skip the line
+      continue;
+    }
+    out.push(line);
+  }
+
+  if (open) {
+    throw new CapFenceError(`${skillName}: unclosed {{#cap ${open.tag}}} opened at line ${open.line}`);
+  }
+
+  // Normalize: collapse 3+ consecutive blank lines (left by removed blocks) to one.
+  return out.join('\n').replace(/\n{3,}/g, '\n\n');
+}

package/src/orchestrator/ai-skills/commands.ts

@@ -0,0 +1,112 @@
+/**
+ * Command generator. Commands diverge per-adapter in BOTH frontmatter shape and body
+ * (measured 2026-06-27: all 10 pairs differ, create-test by 123 lines). Claude output must
+ * be byte-identical (gate); Copilot/Codex are re-derived from the canonical source (lenient).
+ *
+ * Source: templates/ai-src/commands/<name>.md
+ *   ---
+ *   name: create-test
+ *   description: "<canonical Claude description>"
+ *   argument-hint: "[screen-name]"
+ *   order: 20
+ *   claude-tools: "Read, Grep, ..."          # verbatim allowed-tools line for Claude
+ *   codex-trigger: "Run when the user asks to ..."   # explicit trigger for Codex (P2 mitigation)
+ *   copilot-tools: "[vscode, execute, ...]"  # optional; default used if absent
+ *   ---
+ *   <body with cap-fences>
+ */
+import { stripCaps } from './cap-stripper';
+import { GenFile } from './generator';
+
+export interface CommandSource {
+  id: string;   // command identity (from source filename) — drives output paths
+  name: string; // frontmatter `name:` value; '' means the original had no name line
+  description: string;
+  argumentHint: string; // raw, e.g. "[screen-name]"
+  order?: number;
+  claudeTools: string;
+  copilotTools: string;
+  codexTrigger: string;
+  body: string; // with cap-fences
+}
+
+const DEFAULT_COPILOT_TOOLS = '[vscode, execute, read, edit, search, todo]';
+
+/** Parse a source command file into a CommandSource. */
+export function parseCommandSource(text: string, id: string): CommandSource {
+  const end = text.indexOf('\n---', 3);
+  const raw: Record<string, string> = {};
+  for (const line of text.slice(3, end).trim().split('\n')) {
+    const m = line.match(/^([a-zA-Z_-]+):\s*(.*)$/);
+    if (m) raw[m[1]] = m[2];
+  }
+  // JSON-encoded fields decode losslessly; argument-hint is kept VERBATIM so Claude output
+  // reproduces the original quoting (some commands quote it, some don't).
+  const dec = (k: string): string => {
+    const v = raw[k];
+    if (v == null) return '';
+    if (v.startsWith('"')) { try { return JSON.parse(v); } catch { /* fall through */ } }
+    return v.replace(/^['"]|['"]$/g, '');
+  };
+  const body = text.slice(end + 4).replace(/^\n+/, '');
+  return {
+    id,
+    name: raw['name'] != null ? dec('name') : '',
+    description: dec('description'),
+    argumentHint: raw['argument-hint'] || '', // verbatim
+    order: raw.order ? Number(raw.order) : undefined,
+    claudeTools: dec('claude-tools'),
+    copilotTools: raw['copilot-tools'] ? dec('copilot-tools') : DEFAULT_COPILOT_TOOLS,
+    codexTrigger: dec('codex-trigger'),
+    body,
+  };
+}
+
+const unquote = (s: string) => s.replace(/^['"]|['"]$/g, '');
+
+/** Claude command file — MUST reproduce the exact existing format (byte-identical gate). */
+export function renderClaudeCommand(c: CommandSource): string {
+  const fm = [
+    '---',
+    ...(c.name ? [`name: ${c.name}`] : []), // some commands (locale) omit name
+    `description: '${c.description}'`,
+    `argument-hint: ${c.argumentHint}`,
+    `allowed-tools: ${c.claudeTools}`,
+    '---',
+  ].join('\n');
+  return fm + '\n\n' + stripCaps(c.body, ['parallel-subagents'], `cmd:${c.id}`);
+}
+
+/** Copilot prompt file — re-derived (lenient). */
+export function renderCopilotCommand(c: CommandSource): string {
+  const fm = [
+    '---',
+    `name: sungen-${c.id}`,
+    `description: '${c.description}'`,
+    `argument-hint: '${unquote(c.argumentHint)}'`,
+    `agent: 'agent'`,
+    `tools: ${c.copilotTools}`,
+    '---',
+  ].join('\n');
+  return fm + '\n\n' + stripCaps(c.body, [], `cmd:${c.id}`);
+}
+
+/** Codex command-skill — command folds into a skill with an explicit trigger (decision P2). */
+export function renderCodexCommand(c: CommandSource): string {
+  const desc = c.codexTrigger ? `${c.codexTrigger}` : c.description;
+  const fm = [
+    '---',
+    `name: sungen-${c.id}`,
+    `description: ${JSON.stringify(desc)}`,
+    `kind: command`,
+    ...(c.order != null ? [`order: ${c.order}`] : []),
+    '---',
+  ].join('\n');
+  return fm + '\n\n' + stripCaps(c.body, [], `cmd:${c.id}`);
+}
+
+export function generateCommand(c: CommandSource, adapter: 'claude' | 'copilot' | 'codex'): GenFile {
+  if (adapter === 'claude') return { outputPath: `.claude/commands/sungen/${c.id}.md`, content: renderClaudeCommand(c) };
+  if (adapter === 'copilot') return { outputPath: `.github/prompts/sungen-${c.id}.prompt.md`, content: renderCopilotCommand(c) };
+  return { outputPath: `.agents/skills/sungen-${c.id}/SKILL.md`, content: renderCodexCommand(c) };
+}

package/src/orchestrator/ai-skills/generator.ts

@@ -0,0 +1,47 @@
+/**
+ * Single-source generator (decision 1A).
+ *
+ * Produces an in-memory list of [outputPath, content] pairs from canonical source skill
+ * files, for the selected adapters. `init` and `update` consume this list and keep their own
+ * write semantics — this module never touches disk.
+ *
+ * Source layout (canonical = Claude content, decision 2):
+ *   templates/ai-src/skills/<skillDir>/<file>.md   (kind: skill, possibly multi-file)
+ *   templates/ai-src/commands/<name>.md            (kind: command)  [wired in a later step]
+ *
+ * Each source file may contain cap-fences ({{#cap}} / {{^cap}}) for per-adapter deltas.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { stripCaps } from './cap-stripper';
+import { ADAPTERS, AdapterKey } from './adapters';
+
+export interface GenFile {
+  outputPath: string; // repo-relative
+  content: string;
+}
+
+/** Render all skill units under `srcSkillsDir` for one adapter. */
+export function generateSkills(srcSkillsDir: string, adapterKey: AdapterKey): GenFile[] {
+  const adapter = ADAPTERS[adapterKey];
+  const out: GenFile[] = [];
+  if (!fs.existsSync(srcSkillsDir)) return out;
+
+  for (const skillDir of fs.readdirSync(srcSkillsDir)) {
+    const dirPath = path.join(srcSkillsDir, skillDir);
+    if (!fs.statSync(dirPath).isDirectory()) continue;
+    for (const file of fs.readdirSync(dirPath)) {
+      if (!file.endsWith('.md')) continue;
+      const raw = fs.readFileSync(path.join(dirPath, file), 'utf8');
+      const content = stripCaps(raw, adapter.caps, `${skillDir}/${file}`);
+      out.push({ outputPath: adapter.skillPath(skillDir, file), content });
+    }
+  }
+  return out;
+}
+
+/** Render for several adapters at once. */
+export function generate(srcSkillsDir: string, adapters: AdapterKey[]): GenFile[] {
+  return adapters.flatMap((a) => generateSkills(srcSkillsDir, a));
+}

package/src/orchestrator/ai-skills/golden-skills.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Golden regression net for the single-source generator.
+ *
+ * Compares generated output for all adapters against committed fixtures under
+ * tests/golden/ai-skills/fixtures/. The fixtures were frozen from output that was proven
+ * byte-identical to the original per-assistant templates (see git history: the prior
+ * ai-instructions-based golden). From now on the fixtures ARE the contract — any change to
+ * a source skill/command must be reflected with `--update`, making every output change a
+ * reviewable diff.
+ *
+ *   tsx .../golden-skills.test.ts            # verify
+ *   tsx .../golden-skills.test.ts --update   # re-freeze fixtures after an intentional change
+ *
+ * Also runs source lint (decision 6A): required frontmatter + unique-ish command order,
+ * and a Codex flat-namespace collision check.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { buildOutputs } from './build';
+import { parseCommandSource } from './commands';
+
+const FIX = path.resolve(__dirname, '..', '..', '..', 'tests', 'golden', 'ai-skills', 'fixtures');
+const SRC = path.resolve(__dirname, '..', 'templates', 'ai-src', 'skills');
+const SRC_CMD = path.resolve(__dirname, '..', 'templates', 'ai-src', 'commands');
+const UPDATE = process.argv.includes('--update');
+
+function lint(): string[] {
+  const errs: string[] = [];
+  const fmKeys = (t: string): Set<string> => {
+    const s = new Set<string>();
+    if (!t.startsWith('---')) return s;
+    for (const l of t.slice(3, t.indexOf('\n---', 3)).split('\n')) { const m = l.match(/^([a-zA-Z_-]+):/); if (m) s.add(m[1]); }
+    return s;
+  };
+  for (const dir of fs.existsSync(SRC) ? fs.readdirSync(SRC) : []) {
+    const dp = path.join(SRC, dir);
+    if (!fs.statSync(dp).isDirectory()) continue;
+    const f = path.join(dp, 'SKILL.md');
+    if (!fs.existsSync(f)) continue;
+    const k = fmKeys(fs.readFileSync(f, 'utf8'));
+    if (!k.has('name')) errs.push(`${dir}/SKILL.md: missing frontmatter name`);
+    if (!k.has('description')) errs.push(`${dir}/SKILL.md: missing frontmatter description`);
+  }
+  const seen = new Map<string, string>();
+  for (const f of fs.existsSync(SRC_CMD) ? fs.readdirSync(SRC_CMD) : []) {
+    const c = parseCommandSource(fs.readFileSync(path.join(SRC_CMD, f), 'utf8'), f.replace(/\.md$/, ''));
+    if (!c.description) errs.push(`commands/${f}: missing description`);
+    if (c.order != null) { const k = String(c.order); if (seen.has(k)) { /* allowed: parallel entrypoints */ } else seen.set(k, f); }
+  }
+  return errs;
+}
+
+function run() {
+  // Guardrail: the retired per-assistant folder must never come back. Skills are authored
+  // ONCE in ai-src/. If a dev recreates ai-instructions/, fail loud with a pointer.
+  const legacyDir = path.resolve(__dirname, '..', 'templates', 'ai-instructions');
+  if (fs.existsSync(legacyDir)) {
+    console.error('GOLDEN FAILED — templates/ai-instructions/ exists again.');
+    console.error('  Author skills/commands in templates/ai-src/ ONLY (see ai-src/README.md).');
+    console.error('  The per-assistant duplicates are generated from ai-src by ai-skills/build.ts.');
+    process.exit(1);
+  }
+
+  const lintErrs = lint();
+  // stripCaps throws on unknown cap tag / unclosed fence, so buildOutputs validates fences.
+  const outputs = buildOutputs(['claude', 'copilot', 'codex']);
+
+  // Codex has ONE flat .agents/skills/ namespace — every discovered SKILL.md `name:` must be
+  // unique, or `$name`/description selection is ambiguous (regression guard for the command vs
+  // backing-skill collision: dashboard/delivery/locale must be <name> vs <name>-guide).
+  const codexNames = new Map<string, string>();
+  for (const f of outputs) {
+    if (!f.outputPath.startsWith('.agents/skills/') || !f.outputPath.endsWith('/SKILL.md')) continue;
+    const m = f.content.match(/^name:\s*(\S+)/m);
+    if (!m) continue;
+    if (codexNames.has(m[1])) lintErrs.push(`codex duplicate skill name "${m[1]}" (${f.outputPath} & ${codexNames.get(m[1])})`);
+    else codexNames.set(m[1], f.outputPath);
+  }
+
+  if (UPDATE) {
+    fs.rmSync(FIX, { recursive: true, force: true });
+    for (const f of outputs) {
+      const abs = path.join(FIX, f.outputPath);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, f.content);
+    }
+    console.log(`✓ froze ${outputs.length} fixtures -> tests/golden/ai-skills/fixtures/`);
+    if (lintErrs.length) { console.error('source lint errors:'); lintErrs.forEach((e) => console.error('  ✗ ' + e)); process.exit(1); }
+    return;
+  }
+
+  let pass = 0; const mismatches: string[] = []; const missing: string[] = [];
+  const expectedPaths = new Set(outputs.map((f) => f.outputPath));
+  for (const f of outputs) {
+    const abs = path.join(FIX, f.outputPath);
+    if (!fs.existsSync(abs)) { missing.push(f.outputPath); continue; }
+    if (fs.readFileSync(abs, 'utf8') === f.content) pass++;
+    else mismatches.push(f.outputPath);
+  }
+  // fixtures present but no longer generated => stale
+  const stale: string[] = [];
+  const walk = (d: string, base = '') => {
+    if (!fs.existsSync(d)) return;
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const rel = path.join(base, e.name);
+      if (e.isDirectory()) walk(path.join(d, e.name), rel);
+      else if (!expectedPaths.has(rel)) stale.push(rel);
+    }
+  };
+  walk(FIX);
+
+  console.log(`GOLDEN — source lint: ${lintErrs.length === 0 ? 'PASS' : lintErrs.length + ' error(s)'}`);
+  lintErrs.forEach((e) => console.log('   ✗ ' + e));
+  console.log(`GOLDEN — fixtures: ${pass}/${outputs.length} match | mismatch ${mismatches.length} | missing ${missing.length} | stale ${stale.length}`);
+  [...mismatches.map((m) => 'MISMATCH ' + m), ...missing.map((m) => 'MISSING ' + m), ...stale.map((s) => 'STALE ' + s)].forEach((x) => console.log('   ✗ ' + x));
+
+  if (lintErrs.length || mismatches.length || missing.length || stale.length) {
+    console.error('GOLDEN FAILED — run with --update if the change was intentional, then review the diff.');
+    process.exit(1);
+  }
+  console.log('✓ GOLDEN PASS — all adapter output matches frozen fixtures.');
+}
+
+run();

package/src/orchestrator/ai-skills/resolve-assistants.ts

@@ -0,0 +1,18 @@
+import { AdapterKey, ALL_ADAPTERS } from './adapters';
+
+/**
+ * Resolve `--assistant` CLI values to adapter keys.
+ * Empty -> ['claude'] (decision T5: never silently install all into a single-assistant repo).
+ * 'all' -> every adapter. Unknown values throw.
+ */
+export function resolveAssistants(input: string[] | undefined): AdapterKey[] {
+  if (!input || input.length === 0) return ['claude'];
+  const set = new Set<AdapterKey>();
+  for (const raw of input) {
+    const v = raw.toLowerCase().trim();
+    if (v === 'all') { ALL_ADAPTERS.forEach((a) => set.add(a)); continue; }
+    if (v === 'claude' || v === 'copilot' || v === 'codex') { set.add(v); continue; }
+    throw new Error(`Unknown --assistant "${raw}" (valid: claude, copilot, codex, all)`);
+  }
+  return [...set];
+}

package/src/orchestrator/ai-skills/writer.ts

@@ -0,0 +1,92 @@
+/**
+ * applyOutputs — write a BuiltFile[] to disk with the agreed semantics (decisions 2, T2).
+ *
+ *   managed (skills/commands): ALWAYS overwritten (version-managed, no rollback)
+ *   config  (CLAUDE.md/AGENTS.md/copilot-instructions): skip-if-exists unless `force`
+ *   orphans: managed files written last run but not this run are DELETED (manifest-derived,
+ *            replaces the hand-curated STALE list — decision T2)
+ *   detect-and-warn: if a managed file on disk was hand-edited since we wrote it, warn
+ *   dry-run: report adds/overwrites/skips/deletes/warnings without touching disk
+ *
+ * Manifest: <cwd>/.sungen/manifest.json = { version, managed: { <path>: <sha256> } }
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { BuiltFile } from './build';
+
+export interface ApplyOptions { force?: boolean; dryRun?: boolean; version: string }
+export interface ApplyReport {
+  created: string[]; overwritten: string[]; skippedConfig: string[];
+  deletedOrphans: string[]; handEditWarnings: string[];
+}
+
+const MANIFEST_REL = path.join('.sungen', 'manifest.json');
+const sha = (s: string) => crypto.createHash('sha256').update(s).digest('hex');
+
+interface Manifest { version: string; managed: Record<string, string> }
+
+function readManifest(cwd: string): Manifest {
+  const p = path.join(cwd, MANIFEST_REL);
+  if (!fs.existsSync(p)) return { version: '', managed: {} };
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return { version: '', managed: {} }; }
+}
+
+export function applyOutputs(cwd: string, outputs: BuiltFile[], opts: ApplyOptions): ApplyReport {
+  const r: ApplyReport = { created: [], overwritten: [], skippedConfig: [], deletedOrphans: [], handEditWarnings: [] };
+  const prev = readManifest(cwd);
+  const newManaged: Record<string, string> = {};
+
+  const write = (rel: string, content: string) => {
+    if (opts.dryRun) return;
+    const abs = path.join(cwd, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, 'utf8');
+  };
+
+  for (const f of outputs) {
+    const abs = path.join(cwd, f.outputPath);
+    const exists = fs.existsSync(abs);
+
+    if (f.cls === 'config') {
+      if (exists && !opts.force) { r.skippedConfig.push(f.outputPath); continue; }
+      (exists ? r.overwritten : r.created).push(f.outputPath);
+      write(f.outputPath, f.content);
+      continue;
+    }
+
+    // managed: always overwrite, but warn if hand-edited since our last write
+    if (exists) {
+      const current = fs.readFileSync(abs, 'utf8');
+      const recorded = prev.managed[f.outputPath];
+      if (recorded && sha(current) !== recorded && sha(current) !== sha(f.content)) {
+        r.handEditWarnings.push(f.outputPath);
+      }
+      if (current !== f.content) r.overwritten.push(f.outputPath);
+    } else {
+      r.created.push(f.outputPath);
+    }
+    write(f.outputPath, f.content);
+    newManaged[f.outputPath] = sha(f.content);
+  }
+
+  // Orphan cleanup: managed files we wrote last time but not now.
+  for (const oldPath of Object.keys(prev.managed)) {
+    if (newManaged[oldPath]) continue;
+    r.deletedOrphans.push(oldPath);
+    if (!opts.dryRun) {
+      const abs = path.join(cwd, oldPath);
+      if (fs.existsSync(abs)) fs.rmSync(abs, { force: true });
+      // prune now-empty skill dir
+      const dir = path.dirname(abs);
+      try { if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) fs.rmdirSync(dir); } catch { /* ignore */ }
+    }
+  }
+
+  if (!opts.dryRun) {
+    const mPath = path.join(cwd, MANIFEST_REL);
+    fs.mkdirSync(path.dirname(mPath), { recursive: true });
+    fs.writeFileSync(mPath, JSON.stringify({ version: opts.version, managed: newManaged }, null, 2));
+  }
+  return r;
+}