@sun-asterisk/sungen 3.2.35 → 3.3.0-alpha.10

package/src/hooks/session-start-unit-state-hook.ts

@@ -0,0 +1,59 @@
+/**
+ * Claude Code SessionStart hook — a new, resumed or compacted session starts knowing where the unit
+ * stands (P0.1, takumi T1).
+ *
+ * After `/clear` or a context compaction the agent has lost the thread: it re-derives the state
+ * from memory, or worse, re-runs work that is already done. This injects what `sungen next`
+ * derives for the session's unit (the one cwd sits in, else the most recently active): what the
+ * project already holds — stated as "do not redo" — the audit verdict, the next steps, and what waits
+ * for a human (#954).
+ */
+import { NO_OP, HookMeta, SungenHook } from './hook-result-contract';
+import { formatSteps, locateUnitState } from './hand-back-core';
+import { sungenInvocation } from '../cli/project-sungen-invocation';
+import { waitingForYouLines } from '../cli/waiting-for-you-block';
+import { listUnits } from './sungen-project-root';
+import type { UnitState } from '../harness/next-step';
+
+export const meta: HookMeta = {
+  events: ['SessionStart'],
+  matchers: { SessionStart: 'startup|resume|clear|compact' },
+  timeout: 10,
+};
+
+/** What the unit already holds, in workflow order. */
+function held(s: UnitState): string {
+  const items = [
+    s.hasSpec && 'spec', s.hasViewpoint && 'test-viewpoint',
+    s.kind === 'flow' && s.hasContract && (s.hasFlowInventory ? 'flow contract + inventory' : 'flow contract'),
+    s.scenarioCount > 0 && `${s.scenarioCount} scenario(s)`,
+    s.hasSelectors && !s.selectorsArePlaceholder && 'selectors',
+    s.compiled && 'compiled spec',
+    s.hasResults && `run results${s.failedCount ? ` (${s.failedCount} failed)` : ''}`,
+    s.hasDeliverable && 'deliverable',
+  ].filter(Boolean);
+  return items.length ? items.join(' · ') : 'nothing yet';
+}
+
+export const sessionStartUnitStateHook: SungenHook = {
+  name: 'session-start-unit-state',
+  meta,
+  run(input, ctx) {
+    const found = locateUnitState(ctx);
+    if (!found) return NO_OP;
+    const { root, unit, state } = found;
+    const others = listUnits(root).length - 1;
+    const sungen = sungenInvocation(root);
+    const lines = [
+      `[sungen] Unit in progress: ${unit.name} (${unit.kind})${others > 0 ? ` — the project holds ${others} other unit(s)` : ''}.`,
+      `Already done — do not redo: ${held(state)}.`,
+      state.audit ? `Audit: ${state.audit.overall}/10 [${state.audit.gateStatus}] · ${state.audit.findings.length} finding(s).` : '',
+      `Next (\`${sungen} next ${unit.name}\`, derived from the project state):`,
+      ...formatSteps(state.steps, 4, root),
+      ...waitingForYouLines(state.humanActions, root, state.humanActionsHeldBy, state.humanActionsHeldByCommand),
+      input.source === 'compact' ? 'Context was compacted: re-read the unit\'s files before acting on them.' : '',
+      others > 0 ? `Working on another unit? Ask \`${sungen} next <unit>\` (or \`${sungen} next\` for all).` : '',
+    ];
+    return { status: 'context', output: lines.filter(Boolean).join('\n') };
+  },
+};

package/src/hooks/stop-next-step-hook.ts

@@ -0,0 +1,38 @@
+/**
+ * Claude Code Stop hook — a turn that ran sungen work never ends without the next step (P0.1).
+ *
+ * A slash command has no CLI exit, so the CLI's `Next: sungen next …` footer cannot reach a session
+ * that ends inside `/sungen:create-test`; the hand-back rule in the command template is only an
+ * instruction. This makes it deterministic for Claude Code: when the turn that just ended ran
+ * sungen and did not hand back (no AskUserQuestion after the last sungen call), the hand-back core's
+ * answer is injected as context and Claude continues once to present it.
+ *
+ * Loop-safe: `stop_hook_active` (Claude Code is already continuing because of a stop hook) is a
+ * no-op, and so is anything the hook cannot read — a missing transcript, a non-sungen directory.
+ */
+import { NO_OP, HookMeta, SungenHook } from './hook-result-contract';
+import { run as handBackCore } from './hand-back-core';
+import { summarizeTurn } from './claude-transcript-turn';
+
+export const meta: HookMeta = { events: ['Stop'], timeout: 10 };
+
+export const stopNextStepHook: SungenHook = {
+  name: 'stop-next-step',
+  meta,
+  run(input, ctx) {
+    if (input.stop_hook_active === true) return NO_OP;
+    const turn = summarizeTurn(input.transcript_path);
+    if (!turn || !turn.sungenActivity || turn.askedAfter) return NO_OP;
+    const core = handBackCore({ unit: turn.lastUnit }, ctx);
+    if (core.status !== 'context') return NO_OP;
+    return {
+      status: 'context',
+      output: [
+        '[sungen] This turn ran sungen work but ended without the next-step hand-back.',
+        'Hand back now: present these steps to the user with AskUserQuestion and stop — do not run them yourself.',
+        ...(/Waiting for you/.test(core.output) ? ['Quote the "Waiting for you" block verbatim: the user runs those commands in their own terminal (`! <command>`); never run them.'] : []),
+        core.output,
+      ].join('\n'),
+    };
+  },
+};

package/src/hooks/sungen-project-root.ts

@@ -0,0 +1,80 @@
+/**
+ * Where the sungen project is, and which unit a session is working on — read cheaply off disk.
+ *
+ * A hook runs from wherever Claude Code's shell happens to be, and in a monorepo the sungen project
+ * can sit below the repository root. So a project root is found by walking UP from a start path to
+ * the nearest directory holding `qa/` plus a sungen marker (`.sungen/` or `qa/capabilities.yaml`);
+ * the marker keeps an unrelated `~/qa/` folder higher up from being mistaken for a project.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { reportSlug } from '../harness/unit-paths';
+
+export type UnitKind = 'screen' | 'flow' | 'api';
+export interface UnitRef { name: string; kind: UnitKind; dir: string }
+
+const KIND_DIRS: Array<[string, UnitKind]> = [['screens', 'screen'], ['flows', 'flow'], ['api', 'api']];
+const isDir = (p: string): boolean => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+const mtime = (p: string): number => { try { return fs.statSync(p).mtimeMs; } catch { return 0; } };
+
+export function isSungenRoot(dir: string): boolean {
+  return isDir(path.join(dir, 'qa'))
+    && (isDir(path.join(dir, '.sungen')) || fs.existsSync(path.join(dir, 'qa', 'capabilities.yaml')));
+}
+
+/** The nearest sungen project at or above `start`, or null outside one. */
+export function findSungenRoot(start: string): string | null {
+  let dir = path.resolve(start);
+  for (let i = 0; i < 40; i++) {
+    if (isSungenRoot(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/** Every unit directory the project holds (`qa/api/flows` is a container, not a unit). */
+export function listUnits(root: string): UnitRef[] {
+  const out: UnitRef[] = [];
+  for (const [sub, kind] of KIND_DIRS) {
+    let entries: fs.Dirent[] = [];
+    try { entries = fs.readdirSync(path.join(root, 'qa', sub), { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (!e.isDirectory() || (kind === 'api' && e.name === 'flows')) continue;
+      out.push({ name: e.name, kind, dir: path.join(root, 'qa', sub, e.name) });
+    }
+  }
+  return out;
+}
+
+/** The unit with this name, when exactly one directory holds it (an ambiguous name is no answer). */
+export function findUnit(root: string, name: string): UnitRef | null {
+  const hits = listUnits(root).filter((u) => u.name === name);
+  return hits.length === 1 ? hits[0] : null;
+}
+
+/**
+ * The unit a session is most likely on: the one `cwd` sits inside, else the one with the most
+ * recent activity — its ledger, its audit report, or its directory, whichever moved last.
+ */
+export function nearestUnit(root: string, cwd: string): UnitRef | null {
+  const units = listUnits(root);
+  const rel = path.relative(root, path.resolve(cwd)).split(path.sep);
+  if (rel[0] === 'qa' && rel.length >= 3) {
+    const inside = units.find((u) => u.dir === path.join(root, 'qa', rel[1], rel[2]));
+    if (inside) return inside;
+  }
+  let best: UnitRef | null = null;
+  let bestAt = -1;
+  for (const u of units) {
+    const slug = reportSlug(u.name);
+    const at = Math.max(
+      mtime(path.join(root, '.sungen', 'ledger', `${slug}.jsonl`)),
+      mtime(path.join(root, '.sungen', 'reports', `${slug}-audit.json`)),
+      mtime(u.dir),
+    );
+    if (at > bestAt) { best = u; bestAt = at; }
+  }
+  return best;
+}

package/src/index.ts

@@ -20,8 +20,7 @@ export type { ResolvedAppProfile } from './generators/test-generator/app-profile
 export type { MappedStep } from './generators/test-generator/step-mapper';
 // The shared "nothing honest to compile" step body. Exported for the driver SPI: a pattern that
 // must refuse (SG-W017 and siblings) emits THIS rather than shipping a one-sided refusal template,
-// which would fail the adapter-parity gate and push playwright off its refusal-only floor (1 — the
-// `date-picker-unsupported` refusal both adapters ship for the resolver-based fill-input pattern, #907).
+// which would fail the adapter-parity gate and push playwright off its refusal-only floor of 0.
 export { unsupportedStepCode } from './generators/test-generator/patterns/unsupported-step-code';
 export type { ParsedStep } from './generators/gherkin-parser';
 export { getPathCode, inferPath, resolvePathVariables } from './generators/test-generator/utils/path-inference';

package/src/orchestrator/ai-skills/command-partial-includes.ts

@@ -0,0 +1,72 @@
+/**
+ * Per-assistant partials for command templates (P0.1, root cause c).
+ *
+ * A command pulls a shared block in with an explicit directive on its own line:
+ *
+ *   <!-- include: hand-back-rule -->
+ *
+ * and each assistant gets its OWN twin file — `templates/ai-src/partials/<name>.<adapter>.md` —
+ * chosen here by file name, never by branching inside the content (Claude asks with
+ * AskUserQuestion; Copilot/Codex have no such tool and end with a numbered list instead).
+ *
+ * Fails loud, like cap-fences: an unknown partial, a twin missing for one assistant, or a command
+ * without a REQUIRED include throws — a typo can never ship a command that silently lacks the rule.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import type { AdapterKey } from './adapters';
+
+const PARTIALS_DIR = path.resolve(__dirname, '..', 'templates', 'ai-src', 'partials');
+
+/** Every command must include these. The hand-back rule is the reason this module exists. */
+export const REQUIRED_INCLUDES = ['hand-back-rule'] as const;
+
+const DIRECTIVE = /^[ \t]*<!--\s*include:\s*([a-z0-9-]+)\s*-->[ \t]*$/;
+
+export class PartialError extends Error {}
+
+/** Partial names a body includes, in order of appearance. */
+export function includesOf(body: string): string[] {
+  const out: string[] = [];
+  for (const line of body.split('\n')) {
+    const m = line.match(DIRECTIVE);
+    if (m) out.push(m[1]);
+  }
+  return out;
+}
+
+/** Throws when a command lacks a required include — the build-time gate. */
+export function assertRequiredIncludes(body: string, commandId: string): void {
+  const have = new Set(includesOf(body));
+  const missing = REQUIRED_INCLUDES.filter((name) => !have.has(name));
+  if (missing.length > 0) {
+    throw new PartialError(
+      `commands/${commandId}.md: missing required <!-- include: ${missing.join(' -->, <!-- include: ')} --> `
+      + '(every command carries the next-step hand-back rule; see ai-skills/command-partial-includes.ts)',
+    );
+  }
+}
+
+function readPartial(name: string, adapter: AdapterKey, commandId: string): string {
+  const file = path.join(PARTIALS_DIR, `${name}.${adapter}.md`);
+  if (!fs.existsSync(file)) {
+    throw new PartialError(`commands/${commandId}.md: <!-- include: ${name} --> has no partials/${name}.${adapter}.md`);
+  }
+  // A trailing newline is the file's, not the block's: the directive line's own break follows it.
+  return fs.readFileSync(file, 'utf8').replace(/\n+$/, '');
+}
+
+/**
+ * Replace each directive line with the adapter's partial, substituting `{{var}}` placeholders from
+ * `vars`. A placeholder with no value is an authoring error and fails loud.
+ */
+export function expandIncludes(body: string, adapter: AdapterKey, commandId: string, vars: Record<string, string>): string {
+  return body.split('\n').map((line) => {
+    const m = line.match(DIRECTIVE);
+    if (!m) return line;
+    return readPartial(m[1], adapter, commandId).replace(/\{\{(\w+)\}\}/g, (_all, key: string) => {
+      if (!(key in vars)) throw new PartialError(`partials/${m[1]}.${adapter}.md: unknown placeholder {{${key}}}`);
+      return vars[key];
+    });
+  }).join('\n');
+}

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,11 +64,15 @@ 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, "''")}'`;
 
@@ -76,7 +86,7 @@ export function renderClaudeCommand(c: CommandSource): string {
     `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). */
@@ -90,7 +100,7 @@ export function renderCopilotCommand(c: CommandSource): string {
     `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). */
@@ -104,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/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