@sun-asterisk/sungen 3.2.34 → 3.3.0-alpha.2

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

@@ -12,11 +12,15 @@
  *   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
+ *   unit-arg: "<screen-name>"                # optional; fills {{unitArg}} in partials (default <unit>)
  *   ---
+ *   <!-- include: hand-back-rule -->         # REQUIRED — see command-partial-includes.ts
  *   <body with cap-fences>
  */
 import { stripCaps } from './cap-stripper';
 import { GenFile } from './generator';
+import type { AdapterKey } from './adapters';
+import { assertRequiredIncludes, expandIncludes } from './command-partial-includes';
 
 export interface CommandSource {
   id: string;   // command identity (from source filename) — drives output paths
@@ -27,7 +31,9 @@ export interface CommandSource {
   claudeTools: string;
   copilotTools: string;
   codexTrigger: string;
-  body: string; // with cap-fences
+  /** What `{{unitArg}}` renders as inside a partial — the unit placeholder the command takes. */
+  unitArg: string;
+  body: string; // with cap-fences and include directives
 }
 
 const DEFAULT_COPILOT_TOOLS = '[vscode, execute, read, edit, search, todo]';
@@ -58,23 +64,29 @@ export function parseCommandSource(text: string, id: string): CommandSource {
     claudeTools: dec('claude-tools'),
     copilotTools: raw['copilot-tools'] ? dec('copilot-tools') : DEFAULT_COPILOT_TOOLS,
     codexTrigger: dec('codex-trigger'),
+    unitArg: dec('unit-arg') || '<unit>',
     body,
   };
 }
 
 const unquote = (s: string) => s.replace(/^['"]|['"]$/g, '');
+/** The body as one assistant sees it: its own partials pulled in, then its cap-fences resolved. */
+const bodyFor = (c: CommandSource, adapter: AdapterKey, caps: string[]): string =>
+  stripCaps(expandIncludes(c.body, adapter, c.id, { unitArg: c.unitArg }), caps, `cmd:${c.id}`);
+/** A YAML single-quoted scalar: an apostrophe is written twice, or it ends the value early (#899). */
+const sq = (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}'`,
+    `description: ${sq(c.description)}`,
     `argument-hint: ${c.argumentHint}`,
     `allowed-tools: ${c.claudeTools}`,
     '---',
   ].join('\n');
-  return fm + '\n\n' + stripCaps(c.body, ['parallel-subagents'], `cmd:${c.id}`);
+  return fm + '\n\n' + bodyFor(c, 'claude', ['parallel-subagents']);
 }
 
 /** Copilot prompt file — re-derived (lenient). */
@@ -82,13 +94,13 @@ export function renderCopilotCommand(c: CommandSource): string {
   const fm = [
     '---',
     `name: sungen-${c.id}`,
-    `description: '${c.description}'`,
-    `argument-hint: '${unquote(c.argumentHint)}'`,
+    `description: ${sq(c.description)}`,
+    `argument-hint: ${sq(unquote(c.argumentHint))}`,
     `agent: 'agent'`,
     `tools: ${c.copilotTools}`,
     '---',
   ].join('\n');
-  return fm + '\n\n' + stripCaps(c.body, [], `cmd:${c.id}`);
+  return fm + '\n\n' + bodyFor(c, 'copilot', []);
 }
 
 /** Codex command-skill — command folds into a skill with an explicit trigger (decision P2). */
@@ -102,10 +114,12 @@ export function renderCodexCommand(c: CommandSource): string {
     ...(c.order != null ? [`order: ${c.order}`] : []),
     '---',
   ].join('\n');
-  return fm + '\n\n' + stripCaps(c.body, [], `cmd:${c.id}`);
+  return fm + '\n\n' + bodyFor(c, 'codex', []);
 }
 
-export function generateCommand(c: CommandSource, adapter: 'claude' | 'copilot' | 'codex'): GenFile {
+/** The build path: a command that lacks a required include never renders (fails loud). */
+export function generateCommand(c: CommandSource, adapter: AdapterKey): GenFile {
+  assertRequiredIncludes(c.body, c.id);
   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/golden-skills.test.ts

@@ -16,12 +16,14 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { parseDocument } from 'yaml';
 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 SRC_CFG = path.resolve(__dirname, '..', 'templates', 'ai-src', 'config');
 const UPDATE = process.argv.includes('--update');
 
 function lint(): string[] {
@@ -47,6 +49,18 @@ function lint(): string[] {
     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); }
   }
+  // The CLAUDE.md / copilot-instructions tables are the always-loaded index of what ships, so
+  // they must list every skill and command, with the right count (#899).
+  const skills = fs.readdirSync(SRC).filter((d) => fs.existsSync(path.join(SRC, d, 'SKILL.md')));
+  const cmds = fs.readdirSync(SRC_CMD).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, ''));
+  for (const [cfg, prefix] of [['claude.md', '/sungen:'], ['copilot.md', '/sungen-']] as const) {
+    const t = fs.readFileSync(path.join(SRC_CFG, cfg), 'utf8');
+    for (const s of skills) if (!t.includes(`| \`${s}\` |`)) errs.push(`config/${cfg}: skills table misses ${s}`);
+    const listed = (c: string) => [' ', '`'].some((end) => t.includes(`| \`${prefix}${c}${end}`));
+    for (const c of cmds) if (!listed(c)) errs.push(`config/${cfg}: workflow table misses ${prefix}${c}`);
+    const n = t.match(/## Workflow \((\d+) AI commands\)/)?.[1];
+    if (Number(n) !== cmds.length) errs.push(`config/${cfg}: says ${n} AI commands, ${cmds.length} ship`);
+  }
   return errs;
 }
 
@@ -77,6 +91,15 @@ function run() {
     else codexNames.set(m[1], f.outputPath);
   }
 
+  // The key regex in lint() accepts frontmatter a real YAML parser rejects (an unquoted ": ", an
+  // unescaped apostrophe inside '...'), and assistants then drop every field silently (#899).
+  // Parse what ships — renderers re-quote command fields, so a valid source is not enough.
+  for (const f of outputs) {
+    if (!f.content.startsWith('---')) continue;
+    const doc = parseDocument(f.content.slice(3, f.content.indexOf('\n---', 3)));
+    for (const e of doc.errors) lintErrs.push(`${f.outputPath}: frontmatter is not valid YAML — ${e.message.split('\n')[0]}`);
+  }
+
   if (UPDATE) {
     fs.rmSync(FIX, { recursive: true, force: true });
     for (const f of outputs) {

package/src/orchestrator/assets-drift.ts

@@ -2,6 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { getPackageVersion } from '../exporters/package-info';
 import { readJsonConfig, warnUnreadableConfig } from '../harness/config-file';
+import { updateCommand } from '../cli/project-sungen-invocation';
 
 /**
  * Are this project's AI assets (commands + skills under `.claude/` etc.) the ones
@@ -54,6 +55,16 @@ export function checkAssetsDrift(cwd: string): AssetsDrift | null {
   return { recordedVersion, runningVersion, changed, total };
 }
 
+/**
+ * The note's text. The update command is the one this project runs (`npx sungen` with a local install)
+ * on the channel it runs (`--alpha` / `--beta`): a plain `sungen update` would switch to stable (#939).
+ */
+export function assetsDriftNote(drift: AssetsDrift, cwd: string, paint: (cmd: string) => string = (c) => c): string {
+  return `note: this project's AI commands/skills were written by sungen ${drift.recordedVersion}, ` +
+    `you are running ${drift.runningVersion} — run ${paint(updateCommand(cwd, drift.runningVersion))} to refresh them ` +
+    '(upgrading the package alone does not).';
+}
+
 /** One line, on stderr so `--json` output stays machine-readable. */
 export function warnAssetsDrift(cwd: string): void {
   const drift = checkAssetsDrift(cwd);
@@ -61,9 +72,5 @@ export function warnAssetsDrift(cwd: string): void {
   const gray = '\x1b[90m';
   const cyan = '\x1b[36m';
   const reset = '\x1b[0m';
-  process.stderr.write(
-    `${gray}note: this project's AI commands/skills were written by sungen ${drift.recordedVersion}, ` +
-    `you are running ${drift.runningVersion} — run ${cyan}sungen update${reset}${gray} to refresh them ` +
-    `(upgrading the package alone does not).${reset}\n`,
-  );
+  process.stderr.write(`${gray}${assetsDriftNote(drift, cwd, (c) => `${cyan}${c}${reset}${gray}`)}${reset}\n`);
 }

package/src/orchestrator/claude-hooks-install.ts

@@ -0,0 +1,168 @@
+/**
+ * Install sungen's Claude Code hooks into `.claude/settings.json` — by MERGING (P0.1, takumi T1).
+ *
+ * A team commits that file, so it holds the user's own hooks, permissions and env. The installer
+ * owns exactly one thing in it: hook entries that run the sungen launcher
+ * (`.claude/hooks/sungen-hook.cjs`, matched exactly — a user's `my-sungen-hook.cjs` is not ours).
+ * Each run removes every such entry and appends the wanted ones, so a hook turned off in
+ * `qa/sungen.config.yaml`, or dropped by a later version, leaves — and nothing else does. That is
+ * also the rollback path: `sungen update` takes out sungen's entries without touching anyone's.
+ *
+ * The first change backs the file up byte for byte, and that pristine backup is never overwritten;
+ * the file keeps its own indentation; an unreadable file is never rewritten; a run that changes
+ * nothing writes nothing.
+ *
+ * Entries use EXEC FORM — `{ command: 'node', args: ['${CLAUDE_PROJECT_DIR}/…/sungen-hook.cjs', hook] }`
+ * (Claude Code ≥ 2.1.139). No shell is involved and Claude Code substitutes the placeholder itself.
+ * A shell-form `node "$CLAUDE_PROJECT_DIR/…"` runs in PowerShell on Windows without Git Bash, where
+ * that variable is empty, and since 2.1.299 a FAILING shell-form PreToolUse hook there blocks every
+ * tool call. `onFailure` is left unset: its default (continue) is the fail-open one, and versions
+ * before 2.1.295 do not know the field.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { allHooks } from '../hooks/hook-registry';
+import { configDisabledHooks } from '../hooks/hook-toggles';
+import type { SungenHook } from '../hooks/hook-result-contract';
+import { readTextFile } from '../harness/read-text';
+import { writeFileAtomic } from '../harness/write-atomic';
+
+export const LAUNCHER_REL = path.join('.claude', 'hooks', 'sungen-hook.cjs');
+/** The launcher as the hook entry names it: Claude Code substitutes the placeholder, no shell does. */
+export const LAUNCHER_ARG = '${CLAUDE_PROJECT_DIR}/.claude/hooks/sungen-hook.cjs';
+const SETTINGS_REL = path.join('.claude', 'settings.json');
+const BACKUP_SUFFIX = '.sungen-backup';
+const LAUNCHER_SRC = path.join(__dirname, 'templates', 'claude-hooks', 'sungen-hook.cjs');
+/** What marks an entry as sungen's: it runs exactly this launcher (exec form `args[0]` or a shell command). */
+const OWNED = /\.claude\/hooks\/sungen-hook\.cjs(?:["'\s]|$)/;
+
+type Settings = Record<string, unknown> & { hooks?: Record<string, unknown> };
+type Entry = { command?: unknown; args?: unknown };
+const entriesOf = (g: unknown): Entry[] | null =>
+  g && typeof g === 'object' && Array.isArray((g as { hooks?: unknown }).hooks) ? (g as { hooks: Entry[] }).hooks : null;
+const argsOf = (e: Entry): string[] => (Array.isArray(e?.args) ? e.args.filter((a): a is string => typeof a === 'string') : []);
+const isOwned = (e: Entry): boolean =>
+  (typeof e?.command === 'string' && OWNED.test(e.command)) || OWNED.test(argsOf(e)[0] ?? '');
+const keyOf = (e: Entry): string => [String(e?.command ?? ''), ...argsOf(e)].join(' ');
+
+export interface HooksInstallReport {
+  settings: 'created' | 'updated' | 'unchanged' | 'unreadable';
+  launcher: 'written' | 'unchanged' | 'removed' | 'absent';
+  /** Hooks registered after this run. */
+  installed: string[];
+  /** sungen entries no longer registered (stale, or turned off). */
+  removed: number;
+  /** The backup written THIS run (only the first change writes one). */
+  backup?: string;
+  error?: string;
+}
+
+function hookEntry(hook: SungenHook): Record<string, unknown> {
+  return { type: 'command', command: 'node', args: [LAUNCHER_ARG, hook.name], ...(hook.meta.timeout ? { timeout: hook.meta.timeout } : {}) };
+}
+
+/** Pure: every sungen-owned entry removed, the wanted hooks appended, everything else as it was. */
+export function mergeSungenHooks(settings: Settings, wanted: SungenHook[]): Settings {
+  const hooks: Record<string, unknown> = { ...(settings.hooks ?? {}) };
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue; // readSettings refuses this shape; never rewrite it here
+    const kept = groups.flatMap((g) => {
+      const entries = entriesOf(g);
+      if (!entries || !entries.some(isOwned)) return [g];
+      const rest = entries.filter((e) => !isOwned(e));
+      return rest.length ? [{ ...(g as object), hooks: rest }] : [];
+    });
+    if (kept.length || !groups.length) hooks[event] = kept; else delete hooks[event];
+  }
+  for (const hook of wanted) {
+    for (const event of hook.meta.events) {
+      const matcher = hook.meta.matchers?.[event];
+      hooks[event] = [...(Array.isArray(hooks[event]) ? hooks[event] as unknown[] : []), { ...(matcher ? { matcher } : {}), hooks: [hookEntry(hook)] }];
+    }
+  }
+  const out: Settings = { ...settings };
+  if (Object.keys(hooks).length || settings.hooks !== undefined) out.hooks = hooks;
+  return out;
+}
+
+const ownedKeys = (s: Settings): string[] => Object.values(s.hooks ?? {})
+  .flatMap((groups) => (Array.isArray(groups) ? groups : []).flatMap((g) => entriesOf(g) ?? []))
+  .filter(isOwned).map(keyOf);
+
+/** The file's own indentation (a tab, or N spaces); 2 for a file that has none yet. */
+function indentOf(raw: string): string | number {
+  const m = raw.match(/^[{[][^\S\n]*\r?\n([ \t]+)\S/);
+  if (!m) return 2;
+  return m[1].startsWith('\t') ? '\t' : m[1].length;
+}
+
+function readSettings(file: string): { settings: Settings; indent: string | number } {
+  const raw = readTextFile(file);
+  const parsed: unknown = JSON.parse(raw);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not a JSON object');
+  const hooks = (parsed as Settings).hooks;
+  if (hooks !== undefined && (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))) throw new Error('"hooks" is not an object');
+  // An event that is not a list is a shape we cannot merge into without replacing it.
+  const odd = Object.entries(hooks ?? {}).find(([, groups]) => !Array.isArray(groups));
+  if (odd) throw new Error(`"hooks.${odd[0]}" is not a list`);
+  return { settings: parsed as Settings, indent: indentOf(raw) };
+}
+
+export function installClaudeHooks(cwd: string, opts: { dryRun?: boolean } = {}): HooksInstallReport {
+  const settingsPath = path.join(cwd, SETTINGS_REL);
+  const existed = fs.existsSync(settingsPath);
+  let current: Settings = {};
+  let indent: string | number = 2;
+  if (existed) {
+    try { ({ settings: current, indent } = readSettings(settingsPath)); } catch (e) {
+      return { settings: 'unreadable', launcher: 'absent', installed: [], removed: 0, error: `${SETTINGS_REL}: ${(e as Error).message.split('\n')[0]}` };
+    }
+  }
+  const off = configDisabledHooks(cwd);
+  const wanted = off === 'all' ? [] : allHooks().filter((h) => !off.has(h.name));
+  const merged = mergeSungenHooks(current, wanted);
+  const after = ownedKeys(merged);
+  const changed = existed ? JSON.stringify(merged) !== JSON.stringify(current) : wanted.length > 0;
+  const report: HooksInstallReport = {
+    settings: !changed ? 'unchanged' : existed ? 'updated' : 'created',
+    launcher: 'absent',
+    installed: wanted.map((h) => h.name),
+    removed: ownedKeys(current).filter((k) => !after.includes(k)).length,
+  };
+
+  const launcherPath = path.join(cwd, LAUNCHER_REL);
+  const onDisk = fs.existsSync(launcherPath) ? fs.readFileSync(launcherPath, 'utf8') : null;
+  const src = wanted.length ? fs.readFileSync(LAUNCHER_SRC, 'utf8') : null;
+  if (src !== null) report.launcher = onDisk === src ? 'unchanged' : 'written';
+  else if (onDisk !== null) report.launcher = 'removed';
+  if (opts.dryRun) return report;
+
+  const writeSettings = (): void => {
+    if (!changed) return;
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    const backup = settingsPath + BACKUP_SUFFIX;
+    if (existed && !fs.existsSync(backup)) { // keep the pristine original: never overwrite it
+      fs.copyFileSync(settingsPath, backup);
+      report.backup = SETTINGS_REL + BACKUP_SUFFIX;
+    }
+    writeFileAtomic(settingsPath, `${JSON.stringify(merged, null, indent)}\n`);
+  };
+  // settings.json must never point at a launcher that is not there: install the launcher BEFORE the
+  // entries that run it, and remove it only AFTER the entries are gone.
+  if (src !== null) {
+    if (onDisk !== src) { fs.mkdirSync(path.dirname(launcherPath), { recursive: true }); writeFileAtomic(launcherPath, src); }
+    writeSettings();
+  } else {
+    writeSettings();
+    if (onDisk !== null) fs.rmSync(launcherPath, { force: true });
+  }
+  return report;
+}
+
+/** One summary line for init/update output. */
+export function describeHooksInstall(r: HooksInstallReport): string {
+  if (r.settings === 'unreadable') return `${r.error} — Claude Code hooks not installed; fix the JSON and re-run`;
+  const what = r.installed.length ? `Claude Code hooks: ${r.installed.join(', ')}` : 'Claude Code hooks: none (turned off in qa/sungen.config.yaml)';
+  const extra = [r.removed ? `${r.removed} stale removed` : '', r.backup ? `backup ${r.backup}` : ''].filter(Boolean).join(', ');
+  return `${SETTINGS_REL} (${what}${extra ? `; ${extra}` : ''})`;
+}

package/src/orchestrator/lockstep-version.ts

@@ -18,29 +18,42 @@ export function coreVersion(): string {
 /**
  * Resolve the version to install for a family package, given the running `core` version.
  *
- * Lockstep wants the EXACT `core` version. But the beta channel publishes `<core>-beta.N` before a
- * stable `<core>` ever exists — so a released core (e.g. 3.2.10) asking for `@3.2.10` hits ETARGET
- * out-of-the-box when npm only has `3.2.10-beta.2` (`sungen capability add` then fails for a fresh
- * user). Fall back on the SAME version line: prefer exact `core`, else the highest `core-beta.N`,
- * else the `beta` dist-tag as a last resort. Keeps the driver's pinned core-dep on the same line.
+ * Lockstep wants the EXACT `core` version. But the prerelease channels publish `<core>-beta.N`
+ * (beta branch) and `<core>-alpha.N` (alpha branch) before a stable `<core>` ever exists — so a
+ * released core (e.g. 3.2.10) asking for `@3.2.10` hits ETARGET out-of-the-box when npm only has
+ * `3.2.10-beta.2` (`sungen capability add` then fails for a fresh user). Fall back on the SAME
+ * version line — see `pickDriverVersion`. Keeps the driver's pinned core-dep on the same line.
  */
 export function resolveDriverVersion(pkg: string, core: string): string {
   if (core === 'latest') return 'beta';
   try {
     const out = spawnSync('npm', ['view', pkg, 'versions', '--json'], { encoding: 'utf-8', shell: true });
     if (out.status !== 0 || !out.stdout) return core; // can't query → let the exact install try/fail
-    let versions: string[] = [];
     const parsed = JSON.parse(out.stdout);
-    versions = Array.isArray(parsed) ? parsed : [parsed];
-    if (versions.includes(core)) return core; // exact exists → lockstep
-    const prefix = `${core}-beta.`;
-    const betas = versions
-      .filter((v) => typeof v === 'string' && v.startsWith(prefix))
-      .map((v) => parseInt(v.slice(prefix.length), 10))
-      .filter((n) => Number.isInteger(n));
-    if (betas.length) return `${core}-beta.${Math.max(...betas)}`; // highest same-line prerelease
-    return 'beta'; // nothing on this line → newest beta dist-tag
+    return pickDriverVersion(Array.isArray(parsed) ? parsed : [parsed], core);
   } catch {
     return core;
   }
 }
+
+/**
+ * Pick from a package's published `versions`: the exact `core`, else the highest same-line
+ * prerelease of core's OWN channel, else that channel's dist-tag. The channel is `alpha` for an
+ * alpha core and `beta` for any other (stable or beta): a stable or beta core never takes an alpha
+ * driver — alpha builds are the next big update, and an alpha driver pins an alpha core.
+ *
+ * The line is core without its prerelease suffix (as `sameVersionLine` in capabilities/discover.ts
+ * reads it), so `3.3.0-alpha.4` with no exact driver still finds `3.3.0-alpha.3`.
+ */
+export function pickDriverVersion(versions: readonly string[], core: string): string {
+  if (versions.includes(core)) return core; // exact exists → lockstep
+  const channel = /-alpha(\.|$)/.test(core) ? 'alpha' : 'beta';
+  const line = core.split('-')[0];
+  const prefix = `${line}-${channel}.`;
+  const indexes = versions
+    .filter((v) => typeof v === 'string' && v.startsWith(prefix))
+    .map((v) => parseInt(v.slice(prefix.length), 10))
+    .filter((n) => Number.isInteger(n));
+  if (indexes.length) return `${line}-${channel}.${Math.max(...indexes)}`; // highest same-line prerelease
+  return channel; // nothing on this line → newest build of core's channel
+}

package/src/orchestrator/project-initializer.ts

@@ -18,6 +18,7 @@ import {
 } from './mobile-runtime-scaffolder';
 import { emitAppiumEnvironment, runAppiumEnvironmentSetup, appiumEnvironmentRerunCommand } from './appium-environment-setup';
 import { ensureSecurityOverrides, reportSecurityOverrides } from './security-overrides';
+import { installClaudeHooks, describeHooksInstall } from './claude-hooks-install';
 import { readTextFile } from '../harness/read-text';
 
 export { MobileInitOptions };
@@ -198,6 +199,12 @@ export class ProjectInitializer {
     // Create root .mcp.json for Claude Code
     this.createClaudeMCPConfig();
 
+    // Claude Code hooks (hand-back on Stop, unit state on SessionStart, approval-path guard),
+    // merged into .claude/settings.json — only when Claude is a selected assistant.
+    if (this.agents.includes('claude')) {
+      this.createClaudeHooks();
+    }
+
     // Create .codex/config.toml for Codex CLI — only when Codex is a selected assistant
     // (`sungen init --assistant codex`), since it is Codex-specific config.
     if (this.agents.includes('codex')) {
@@ -287,6 +294,7 @@ export class ProjectInitializer {
       'specs/.auth-mobile/',   // mobile auth contract = credentials (sensitive)
       '.env.appium',           // local mobile-test env = machine paths + device/team ids (.example IS committed)
       'test-results/',
+      'test-results-free/',    // free / @impl:code runs: their own outputDir, so a compiled run cannot clear their traces (#941)
       'playwright-report/',
       '.playwright-mcp/',
       '.sungen/figma-cache/',  // raw Figma node JSON (design IP)
@@ -397,6 +405,20 @@ export class ProjectInitializer {
     );
   }
 
+  /**
+   * Merge sungen's Claude Code hooks into `.claude/settings.json` (user hooks kept, backup before
+   * any change, unreadable file left alone — see claude-hooks-install.ts). A no-op for a project
+   * without Claude.
+   */
+  private createClaudeHooks(): void {
+    if (!this.agents.includes('claude')) return;
+    const r = installClaudeHooks(this.cwd);
+    const line = describeHooksInstall(r);
+    if (r.settings === 'unreadable') this.notDoneItems.push(line);
+    else if (r.settings === 'unchanged') this.skippedItems.push(line);
+    else this.createdItems.push(line);
+  }
+
   /**
    * Create `.codex/config.toml` for Codex CLI — the Codex analog of `.mcp.json` (Claude) and
    * `.vscode/mcp.json` (Copilot), so `sungen run-test` under Codex drives the same live Playwright

package/src/orchestrator/screen-manager.ts

@@ -5,7 +5,6 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import { chromium } from '@playwright/test';
 import { readCapabilities } from '../harness/capability';
 import { testDataHeader, ensureTestDataGuideFiles } from './test-data-guide';
 import { resolveWebBaseUrl } from '../exporters/env-qa';
@@ -264,6 +263,9 @@ export class ScreenManager {
 
     let browser;
     try {
+      // Loaded here, not at module top: @playwright/test is a peerDependency a mobile project never
+      // installs, and `sungen add` loads this module on every platform (#865).
+      const { chromium } = await import('@playwright/test');
       browser = await chromium.launch();
       const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
       await page.goto(url, { waitUntil: 'networkidle', timeout: 15000 });

package/src/orchestrator/templates/ai-src/commands/add-api.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion"
 copilot-tools: "[vscode, execute, read, agent, edit, search, todo]"
 codex-trigger: "Run when the user asks to add or scaffold a NEW API area/resource or an API flow to test (REST/HTTP endpoints, not a UI screen). Step 1 of the API workflow. Do NOT use for UI screens, flows across screens, creating test cases, or running tests."
 ---
+<!-- include: hand-back-rule -->
+
 {{^cap parallel-subagents}}
 **Input**: an API area name (a resource/tag, e.g. `orders`, `users`) and the base URL:
 `/sungen-add-api orders --base-url https://api.example.com`.

package/src/orchestrator/templates/ai-src/commands/add-flow.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwr
 copilot-tools: "[vscode, execute, read, agent, edit, search, todo]"
 codex-trigger: "Run when the user asks to add a NEW cross-screen end-to-end flow. Step 1 (flow variant). Do NOT use for a single screen, creating test cases, or running tests."
 ---
+<!-- include: hand-back-rule -->
+
 {{^cap parallel-subagents}}
 **Input**: Flow name and optional starting URL (e.g., `/sungen-add-flow award-submission --path /login`).
 

package/src/orchestrator/templates/ai-src/commands/add-screen.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwr
 copilot-tools: "[vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']"
 codex-trigger: "Run when the user asks to add or scaffold a NEW screen/page to test. Step 1 of the sungen workflow. Do NOT use for flows, creating test cases, or running tests."
 ---
+<!-- include: hand-back-rule -->
+
 {{^cap parallel-subagents}}
 **Input**: Screen name and URL path (e.g., `/sungen-add-screen login /login`).
 Optionally include a Figma URL: `/sungen-add-screen login /login --figma https://www.figma.com/design/...`.

package/src/orchestrator/templates/ai-src/commands/create-data-test.md

@@ -7,6 +7,7 @@ claude-tools: "Read, Grep, Bash, Glob, Write, Edit, AskUserQuestion, Skill"
 copilot-tools: "[vscode, execute, read, agent, edit, search, todo]"
 codex-trigger: "Run when the user asks to CREATE, generate, or standardize TEST DATA / test values for a screen or flow (valid/boundary/invalid, boundary values, negative data). Uses the Data Factory driver. Not for generating the .feature scenarios themselves (that is create-test)."
 ---
+<!-- include: hand-back-rule -->
 
 **Input**: A screen or flow name (e.g., `/sungen:create-data-test login`), OR **no name** to do every unit (with a confirmation — see ALL mode). Load the `sungen-data-factory` skill for the full method.
 

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -7,22 +7,7 @@ claude-tools: "Read, Grep, Bash, Glob, Write, AskUserQuestion, Skill, mcp__playw
 copilot-tools: "[vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']"
 codex-trigger: "Run when the user asks to CREATE, generate, write, or author test cases / a .feature file for a screen or flow. Step 2 (after add-screen/add-flow, before run-test). Do NOT use for executing, running, or compiling existing tests."
 ---
-## ⛔ HARD RULE — the run's LAST action is the next-step hand-back
-
-A run is NOT finished when its files are written or its output prints. The final action of EVERY
-run — success, partial, or aborted — is the next-step hand-back.
-
-**Ask `sungen next <unit>` rather than deciding from memory.** It derives the answer from what the
-project actually holds (artifacts on disk, the audit report, the accepted viewpoint baseline, the
-compiled spec, the run results), so the hand-back stays correct even when the run ended somewhere
-unexpected — a failed install, a driver that turned out not to support this unit kind, an aborted
-repair loop. Every `sungen` command also prints `Next: sungen next …` as its own last line.
-
-This matters most exactly where it used to break. A run that ended on a command with no footer of
-its own — `sungen capability add`, a dead-end install — left the session with nothing to follow and
-it stopped mid-workflow. If a step turns out to be impossible, that is still a hand-back: say what
-blocked it, run `sungen next <unit>`, and offer what remains. Ending with a prose summary and no
-choices is a broken run.
+<!-- include: hand-back-rule -->
 
 ---
 {{#cap parallel-subagents}}
@@ -115,6 +100,19 @@ declaration instead of leaving both on record.
 
 ---
 
+## ⛔ HARD RULE — approvals and waivers are a human's, on a terminal
+
+`sungen contract approve`, `sungen journey --waive`, `sungen journey --decide` and `sungen journey --signoff` record a QA
+decision (the sign-off is the single human gate before delivery) and ask for a typed confirmation on a real terminal (TTY). Never run them, never fake the
+terminal (`script`, `expect`, a pty wrapper), and never edit `contracts.lock.yaml` or
+`qa/**/decisions/` by hand. When one is due, show the exact command and stop for the human.
+
+**Hand-written free tests (`@free` / `@impl:code`).** When the unit has free tests with recorded
+traces, write their Gherkin with `sungen contract derive --screen <name>` — deterministic, it writes
+`features/<name>.free.feature` with every scenario tagged `@free @proposed`. Do not author those
+steps yourself; you may name the scenarios and suggest VP-ids. A `@proposed` scenario is not
+counted by the audit until a QA approves it (`sungen contract approve --screen <name>`).
+
 ## Platform detection (do this FIRST)
 
 Read `qa/capabilities.yaml` and check the `platform` field — **and the verification scope** (`verification:` if set, else derived from `enabled`: `ui` always; `api`/`db` only if that driver is on). This is the project's recorded **test type**: an **E2E/UI-only** project (no `api`/`db`) must NOT get `@api`/`@query`/`@requires:api|db` verification unless the test-viewpoint explicitly asks for it — keep oracles UI-observable, and cap any in-scope API/DB-in-E2E verification at the **≤20% band** (see `sungen-tc-generation` → "Respect the project's verification scope"). `sungen audit` flags `VERIFICATION-OUT-OF-SCOPE`.

package/src/orchestrator/templates/ai-src/commands/dashboard.md

@@ -7,6 +7,8 @@ claude-tools: "Bash, Read, AskUserQuestion"
 copilot-tools: "[read, execute, edit, vscode/askQuestions]"
 codex-trigger: "Run when the user asks to OPEN or view the sungen results dashboard."
 ---
+<!-- include: hand-back-rule -->
+
 ## Role
 
 You are a **QA Reporting Engineer**. Your job is to invoke the deterministic `sungen dashboard` CLI which builds a self-contained HTML report. The HTML is shareable as-is (open via `file://`, no server required).

package/src/orchestrator/templates/ai-src/commands/delivery.md

@@ -7,6 +7,8 @@ claude-tools: "Bash, Read, Write, AskUserQuestion"
 copilot-tools: "[read, execute, edit, vscode/askQuestions]"
 codex-trigger: "Run when the user asks to EXPORT or deliver test cases for QA hand-off. Final step. Do NOT use for creating or running tests."
 ---
+<!-- include: hand-back-rule -->
+
 ## Role
 
 You are a **QA Test Delivery Engineer**. The deterministic `sungen delivery` CLI does all parsing,

package/src/orchestrator/templates/ai-src/commands/design.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Bash, Glob, Write, AskUserQuestion, Skill, mcp__playw
 copilot-tools: "[vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']"
 codex-trigger: "Run when the user asks to capture DESIGN/visual context (Figma, live page scan, mockups) for a screen. Used before create-test. Do NOT use for writing or running tests."
 ---
+<!-- include: hand-back-rule -->
+
 {{#cap parallel-subagents}}
 ## `/sungen:design` is an alias of `/sungen:create-test`
 {{/cap}}

package/src/orchestrator/templates/ai-src/commands/feedback.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Bash, Glob"
 copilot-tools: "[vscode, execute, read, search]"
 codex-trigger: "Run when the user wants to send FEEDBACK about sungen itself."
 ---
+<!-- include: hand-back-rule -->
+
 ## Role
 {{#cap parallel-subagents}}
 

package/src/orchestrator/templates/ai-src/commands/locale.md

@@ -6,6 +6,8 @@ claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwr
 copilot-tools: "[read, execute, edit, vscode/askQuestions, playwright/*]"
 codex-trigger: "Run when the user asks to bootstrap i18n/localization for a screen. Runs before run-test --env <locale>."
 ---
+<!-- include: hand-back-rule -->
+
 ## Role
 
 You are a **Senior QA Localization Engineer**. Use the `sungen-locale` skill — it contains the full phased strategy. Your job in this command is parameter parsing, context detection, and final hand-off.

package/src/orchestrator/templates/ai-src/commands/review.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Glob, Bash, Edit, Write, AskUserQuestion"
 copilot-tools: "[vscode, execute, read, edit, search, todo]"
 codex-trigger: "Run when the user asks to REVIEW or score the quality of already-generated test cases. Step 3 (between create-test and run-test). Do NOT use for creating or running tests."
 ---
+<!-- include: hand-back-rule -->
+
 {{^cap parallel-subagents}}
 **Input**: Screen or flow name (e.g., `/sungen-review admin-users`).