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

package/src/hooks/hand-back-core.ts

@@ -0,0 +1,112 @@
+/**
+ * The hand-back, written once (P0.1, takumi T1). Two callers share it:
+ *
+ *   - the CLI exit (cli/index.ts only wires it): the one-line `Next: sungen next <unit>` every
+ *     command ends with — on stdout after a success, on STDERR after a failure or under --json/--grep;
+ *   - the Claude Code Stop hook (stop-next-step-hook.ts): the same pointer plus what `sungen next`
+ *     derives right now, so a session that ended without a hand-back gets one injected.
+ *
+ * #597 skipped exit code 1 ("the error is the actionable thing") and set the hand-back only in
+ * commander's preAction, so a usage error — which never reaches an action — and `main().catch`
+ * ended in silence. The state now starts the moment parsing does; the action only refines it.
+ */
+import { sungenInvocation, withProjectInvocation } from '../cli/project-sungen-invocation';
+import { resolveUnitCandidates } from '../cli/resolve-unit';
+import { readUnitState, NextStep, UnitState } from '../harness/next-step';
+import { NO_OP, HookContext, HookInput, HookResult } from './hook-result-contract';
+import { findSungenRoot, findUnit, nearestUnit, UnitRef } from './sungen-project-root';
+
+/** `hook` speaks JSON to Claude Code on stdout: it never prints a hand-back. */
+const SILENT_COMMANDS = new Set(['hook']);
+/** `next` IS the answer when it succeeds; a failed `next` answered nothing and hands back like any failure (#937). */
+const ANSWER_COMMANDS = new Set(['next']);
+const UNIT_FLAG = /^(?:--screen|-s|--flow|--area|--api)$/;
+const UNIT_FLAG_EQ = /^--(?:screen|flow|area|api)=(.+)$/;
+/** A unit id is a name or `flows/<name>` — anything else is not offered back to the operator. */
+const SAFE_UNIT = /^[\w.-]+(?:\/[\w.-]+)?$/;
+
+/** `invocation`: how the project runs sungen (`npx sungen` with a local install, #939). */
+export function handBackLine(unit?: string, invocation = 'sungen'): string {
+  return `Next: ${invocation} next${unit ? ` ${unit}` : ''}`;
+}
+
+export interface CliHandBackState { unit?: string; machine: boolean; silent: boolean; answer: boolean; actionRan: boolean }
+
+/** The default, set before commander parses — what a usage error or a fatal error hands back. */
+export function initialHandBackState(argv: string[]): CliHandBackState {
+  const args = argv.slice(2);
+  let unit: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const eq = args[i].match(UNIT_FLAG_EQ);
+    if (eq) unit ??= eq[1];
+    else if (UNIT_FLAG.test(args[i]) && args[i + 1] && !args[i + 1].startsWith('-')) unit ??= args[++i];
+  }
+  const command = args.find((a) => !a.startsWith('-')) ?? '';
+  return { unit, machine: args.includes('--json') || args.includes('--grep'), silent: SILENT_COMMANDS.has(command), answer: ANSWER_COMMANDS.has(command), actionRan: false };
+}
+
+/** commander's preAction: the action now KNOWS its unit and output mode. */
+export function onCliAction(state: CliHandBackState, name: string, opts: Record<string, unknown>, args: unknown[]): void {
+  state.actionRan = true;
+  if (SILENT_COMMANDS.has(name)) { state.silent = true; return; }
+  state.answer = ANSWER_COMMANDS.has(name);
+  const flagged = [opts.screen, opts.flow, opts.area, opts.api].find((v) => typeof v === 'string' && v) as string | undefined;
+  state.unit = flagged ?? (typeof args?.[0] === 'string' ? args[0] : undefined);
+  // `--grep` is machine output too: callers capture it with `$(…)` (#836).
+  state.machine = opts.json === true || opts.grep === true;
+}
+
+/**
+ * What to print as the process exits, or null for nothing. A positional that is not a unit on
+ * disk (`capability add mock` → `mock`) is dropped rather than offered as `sungen next mock`.
+ */
+export function exitHandBack(state: CliHandBackState, code: number, cwd: string): { stream: 'stdout' | 'stderr'; text: string } | null {
+  if (state.silent) return null;
+  if (state.answer && code === 0) return null;      // a successful `next` is the hand-back itself
+  if (!state.actionRan && code === 0) return null; // --help / --version printed what was asked
+  const unit = state.unit && SAFE_UNIT.test(state.unit) && !state.unit.split('/').includes('..')
+    && resolveUnitCandidates(state.unit, cwd).length > 0 ? state.unit : undefined;
+  const line = handBackLine(unit, sungenInvocation(findSungenRoot(cwd) ?? cwd));
+  if (code === 1) return { stream: 'stderr', text: `${line}\n` }; // after the error, one line
+  return { stream: state.machine ? 'stderr' : 'stdout', text: `\n${line}\n` };
+}
+
+/** Wire the hand-back to process exit; returns the preAction callback. Never masks the real exit. */
+export function attachCliHandBack(argv: string[], cwd: string): { onAction: (name: string, opts: Record<string, unknown>, args: unknown[]) => void } {
+  const state = initialHandBackState(argv);
+  process.on('exit', (code) => {
+    try {
+      const out = exitHandBack(state, code, cwd);
+      if (out) process[out.stream].write(out.text);
+    } catch { /* the hand-back is advice; the exit code is the contract */ }
+  });
+  return { onAction: (name, opts, args) => onCliAction(state, name, opts, args) };
+}
+
+// --- the hook-shaped core -----------------------------------------------------------------------
+
+const MARK: Record<NextStep['kind'], string> = { do: '→', blocked: '⛔', optional: '○', decide: '⚖' };
+
+/** `sungen next` rendered compactly for an agent's context; commands as `root` runs sungen. */
+export function formatSteps(steps: NextStep[], max = 4, root?: string): string[] {
+  return steps.slice(0, max).map((st) =>
+    `  ${MARK[st.kind]} ${root ? withProjectInvocation(st.command, root) : st.command}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${st.because}`);
+}
+
+/** The unit a session is on (a named one when it exists, else the nearest) and its derived state. */
+export function locateUnitState(ctx: HookContext, preferred?: string): { root: string; unit: UnitRef; state: UnitState } | null {
+  const root = findSungenRoot(ctx.cwd);
+  if (!root) return null;
+  const unit = (preferred && SAFE_UNIT.test(preferred) ? findUnit(root, preferred) : null) ?? nearestUnit(root, ctx.cwd);
+  return unit ? { root, unit, state: readUnitState(root, unit.dir, unit.name, unit.kind) } : null;
+}
+
+/** Hook core: the next steps for the session's unit (input.unit, else the nearest) as context. */
+export function run(input: HookInput, ctx: HookContext): HookResult {
+  const found = locateUnitState(ctx, typeof input.unit === 'string' ? input.unit : undefined);
+  if (!found || found.state.steps.length === 0) return NO_OP;
+  return {
+    status: 'context',
+    output: [`${handBackLine(found.unit.name, sungenInvocation(found.root))} — derived from what the project holds now:`, ...formatSteps(found.state.steps, 4, found.root)].join('\n'),
+  };
+}

package/src/hooks/hook-cli-command.ts

@@ -0,0 +1,17 @@
+/**
+ * `sungen hook <name>` — hidden: runs one Claude Code hook through the normal CLI (event JSON on
+ * stdin, decision JSON on stdout). The installed hooks call the dist entry directly for speed; this
+ * path is for debugging a hook by hand and for dev checkouts that run sungen from source.
+ * The CLI hand-back skips it, so stdout stays pure JSON.
+ */
+import { Command } from 'commander';
+
+export function registerHookCommand(program: Command): void {
+  program
+    .command('hook <name>', { hidden: true })
+    .description('Run one Claude Code hook: event JSON on stdin, decision JSON on stdout (internal)')
+    .action(async (name: string) => {
+      const { main } = await import('./claude-hook-entry');
+      await main(name);
+    });
+}

package/src/hooks/hook-registry.ts

@@ -0,0 +1,24 @@
+/**
+ * Every sungen Claude Code hook, by name. Modules load ON DEMAND: the guard runs on every Edit,
+ * Write and Bash call and must not pay for the next-step reader the Stop hook needs.
+ */
+import { HOOK_NAMES, HookName, SungenHook } from './hook-result-contract';
+
+const LOADERS: Record<HookName, () => SungenHook> = {
+  'stop-next-step': () => (require('./stop-next-step-hook') as typeof import('./stop-next-step-hook')).stopNextStepHook,
+  'session-start-unit-state': () =>
+    (require('./session-start-unit-state-hook') as typeof import('./session-start-unit-state-hook')).sessionStartUnitStateHook,
+  'pre-tool-guard': () => (require('./pre-tool-guard-hook') as typeof import('./pre-tool-guard-hook')).preToolGuardHook,
+};
+
+const isHookName = (name: string): name is HookName => (HOOK_NAMES as readonly string[]).includes(name);
+
+/** The hook with this name, or null for anything else (an unknown name is never an error). */
+export function loadHook(name: string): SungenHook | null {
+  return isHookName(name) ? LOADERS[name]() : null;
+}
+
+/** All hooks — for the installer, which reads their `meta`. */
+export function allHooks(): SungenHook[] {
+  return HOOK_NAMES.map((n) => LOADERS[n]());
+}

package/src/hooks/hook-result-contract.ts

@@ -0,0 +1,114 @@
+/**
+ * The hook contract (P0.1, takumi T1 dual-mode): one PURE core per hook, many callers.
+ *
+ *   run(input, ctx) → HookResult     no stdin read, no stdout write, no process.exit
+ *   meta { events, matchers?, timeout? }   read once at INSTALL time, never at run time
+ *
+ * The same `run` serves the Claude Code entry (claude-hook-entry.ts), the hidden `sungen hook`
+ * command, and later MCP / VS Code — so the decision logic is written once. Every caller goes
+ * through `runHook`, which owns the three properties no hook may get wrong on its own:
+ *
+ *   - kill-switch / per-hook toggle  → `no-op` before the hook runs at all
+ *   - FAIL OPEN                      → a throw becomes the hook's `onError` result (default no-op)
+ *   - shape check                    → a malformed result is `no-op`; a deny/ask without a reason
+ *                                      never blocks anyone
+ */
+import { isHookEnabled } from './hook-toggles';
+
+export const HOOK_NAMES = ['stop-next-step', 'session-start-unit-state', 'pre-tool-guard'] as const;
+export type HookName = (typeof HOOK_NAMES)[number];
+
+export type HookStatus = 'ok' | 'deny' | 'ask' | 'context' | 'no-op';
+export interface HookResult {
+  status: HookStatus;
+  /** Context text for the agent (status `context`). */
+  output?: string;
+  /** Why a tool call is refused (status `deny`). */
+  denyReason?: string;
+  /** Why the user must confirm a tool call (status `ask`). */
+  askReason?: string;
+}
+
+export type ClaudeHookEvent = 'SessionStart' | 'Stop' | 'PreToolUse';
+export interface HookMeta {
+  events: ClaudeHookEvent[];
+  /** Per-event matcher written into settings.json (e.g. `{ PreToolUse: 'Edit|Write' }`). */
+  matchers?: Partial<Record<ClaudeHookEvent, string>>;
+  /** settings.json timeout in SECONDS — Claude Code kills the hook after it (and fails open). */
+  timeout?: number;
+}
+
+/** The event payload: untrusted JSON from stdin. Each hook checks every field where it reads it. */
+export type HookInput = Record<string, unknown>;
+
+export interface HookContext {
+  /** The environment the hook sees — injected, so tests never mutate process.env. */
+  env: Record<string, string | undefined>;
+  /** Where the session runs: the payload `cwd`, else CLAUDE_PROJECT_DIR, else process.cwd(). */
+  cwd: string;
+}
+
+export interface SungenHook {
+  name: HookName;
+  meta: HookMeta;
+  /** What a throw inside `run` becomes. A hook that READS state to decide must not deny blind. */
+  onError?: HookResult;
+  /** What a payload too large to read becomes (default no-op). A guard must not treat it as a pass. */
+  onUnreadableInput?: HookResult;
+  run(input: HookInput, ctx: HookContext): HookResult;
+}
+
+export const NO_OP: HookResult = { status: 'no-op' };
+
+const nonEmpty = (v: unknown): v is string => typeof v === 'string' && v.trim().length > 0;
+
+/** A result Claude Code can act on safely; anything else is treated as `no-op`. */
+export function isValidHookResult(r: unknown): r is HookResult {
+  if (!r || typeof r !== 'object') return false;
+  const { status, output, denyReason, askReason } = r as HookResult;
+  switch (status) {
+    case 'ok': case 'no-op': return true;
+    case 'context': return nonEmpty(output);
+    case 'deny': return nonEmpty(denyReason);
+    case 'ask': return nonEmpty(askReason);
+    default: return false;
+  }
+}
+
+/** The one way to call a hook: toggles first, then the hook, failing open on any error. */
+export function runHook(hook: SungenHook, input: HookInput, ctx: HookContext): HookResult {
+  try {
+    if (!isHookEnabled(hook.name, ctx)) return NO_OP;
+    const r = hook.run(input, ctx);
+    return isValidHookResult(r) ? r : NO_OP;
+  } catch {
+    return hook.onError && isValidHookResult(hook.onError) ? hook.onError : NO_OP;
+  }
+}
+
+/** The payload could not be read (too large): the hook's declared answer, toggles still first. */
+export function runHookOnUnreadableInput(hook: SungenHook, ctx: HookContext): HookResult {
+  try {
+    if (!isHookEnabled(hook.name, ctx)) return NO_OP;
+    return hook.onUnreadableInput && isValidHookResult(hook.onUnreadableInput) ? hook.onUnreadableInput : NO_OP;
+  } catch {
+    return NO_OP;
+  }
+}
+
+/**
+ * HookResult → the stdout Claude Code reads (exit code is always 0). `deny`/`ask` exist only for
+ * PreToolUse; on any other event they degrade to no decision rather than to an invented one.
+ */
+export function toClaudeStdout(event: string, r: HookResult): string {
+  if (r.status === 'context' && nonEmpty(r.output)) {
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: r.output } });
+  }
+  if (event === 'PreToolUse' && (r.status === 'deny' || r.status === 'ask')) {
+    const reason = r.status === 'deny' ? r.denyReason : r.askReason;
+    if (nonEmpty(reason)) {
+      return JSON.stringify({ hookSpecificOutput: { hookEventName: event, permissionDecision: r.status, permissionDecisionReason: reason } });
+    }
+  }
+  return '{}';
+}

package/src/hooks/hook-toggles.ts

@@ -0,0 +1,66 @@
+/**
+ * Turning sungen's Claude Code hooks off — all of them, or one at a time.
+ *
+ *   SUNGEN_HOOKS=off                      kill-switch, every hook is a no-op
+ *   SUNGEN_HOOK_<NAME>=off                one hook (e.g. SUNGEN_HOOK_PRE_TOOL_GUARD=off)
+ *   qa/sungen.config.yaml  hooks: false   persistent, for the whole project
+ *                          hooks: { stop-next-step: false }   persistent, one hook
+ *
+ * The env forms can live in the shell or in `.claude/settings.json` → `"env": { … }` (Claude Code
+ * applies that block to the session, so hook processes inherit it). The config file is also what
+ * `sungen init` / `sungen update` read: a hook it turns off is removed from settings.json.
+ *
+ * At RUN time the config file only switches off the advisory hooks. The guard ignores it — an
+ * agent could otherwise write `hooks: false` and walk past the guard it is subject to; only the real
+ * environment switches the guard off. (An agent edit of the config file or settings.json asks the
+ * user first — see guard-rules.ts.) The human path is editing these files by hand, then
+ * `sungen update`, which removes a turned-off hook's entry from settings.json.
+ *
+ * An unreadable config file disables nothing — the hooks fail open, they never fail silent-off.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import type { HookContext, HookName } from './hook-result-contract';
+import { findSungenRoot } from './sungen-project-root';
+
+const OFF = /^(?:off|0|false|no|disabled?)$/i;
+export const KILL_SWITCH_ENV = 'SUNGEN_HOOKS';
+export const PROJECT_CONFIG = path.join('qa', 'sungen.config.yaml');
+
+/** `stop-next-step` → `SUNGEN_HOOK_STOP_NEXT_STEP`. */
+export const hookEnvVar = (name: HookName): string => `SUNGEN_HOOK_${name.toUpperCase().replace(/-/g, '_')}`;
+
+const isOff = (v: unknown): boolean => v === false || (typeof v === 'string' && OFF.test(v.trim()));
+
+export function hooksKilled(env: Record<string, string | undefined>): boolean {
+  return isOff(env[KILL_SWITCH_ENV] ?? '');
+}
+
+/** Hooks the project config turns off: `'all'`, or the names set to false. */
+export function configDisabledHooks(root: string | null): 'all' | Set<string> {
+  const off = new Set<string>();
+  if (!root) return off;
+  const file = path.join(root, PROJECT_CONFIG);
+  if (!fs.existsSync(file)) return off;
+  try {
+    // Loaded lazily: the guard runs on every tool call and most projects have no config file.
+    const { parse } = require('yaml') as typeof import('yaml');
+    const doc = parse(fs.readFileSync(file, 'utf8')) as { hooks?: unknown } | null;
+    const hooks = doc && typeof doc === 'object' ? doc.hooks : undefined;
+    if (isOff(hooks)) return 'all';
+    if (hooks && typeof hooks === 'object') {
+      for (const [name, value] of Object.entries(hooks as Record<string, unknown>)) if (isOff(value)) off.add(name);
+    }
+  } catch { /* unreadable → nothing disabled (fail open) */ }
+  return off;
+}
+
+/** Hooks the project config may switch off at run time — never the guard. */
+const CONFIG_TOGGLEABLE: ReadonlySet<HookName> = new Set<HookName>(['stop-next-step', 'session-start-unit-state']);
+
+export function isHookEnabled(name: HookName, ctx: HookContext): boolean {
+  if (hooksKilled(ctx.env) || isOff(ctx.env[hookEnvVar(name)] ?? '')) return false;
+  if (!CONFIG_TOGGLEABLE.has(name)) return true;
+  const off = configDisabledHooks(findSungenRoot(ctx.cwd));
+  return off !== 'all' && !off.has(name);
+}

package/src/hooks/pre-tool-guard-hook.ts

@@ -0,0 +1,67 @@
+/**
+ * Claude Code PreToolUse guard — approval artifacts are not the agent's to write (P0.1, takumi T4).
+ *
+ * `qa/**\/contracts.lock.yaml` and the decision records record what a HUMAN approved; they change
+ * only through the TTY path. For other assistants that is a soft barrier (git HEAD comparison,
+ * in-run flags). In Claude Code this hook makes it a hard floor — see guard-rules.ts for what each
+ * rule denies or asks, and guard-protected-paths.ts for the paths.
+ *
+ * The guard cannot be switched off by the agent it guards: `qa/sungen.config.yaml` does not disable
+ * it (only SUNGEN_HOOKS / SUNGEN_HOOK_PRE_TOOL_GUARD in the real environment do), and an agent edit
+ * of the files that control the hooks asks the user. The human path is editing those files by
+ * hand, then `sungen update`.
+ *
+ * The decision is a list of rules — the extension point. Phase 06 added two: no `sungen delivery`
+ * while the Test Contract verdict rebuilt from .feature + lock + git HEAD is not pass
+ * (guard-delivery-contract-rule.ts — it READS project state, so it declares `onError: 'ask'` and a
+ * read failure asks instead of denying blind), and ask before a human-confirmed command is run
+ * through a terminal emulator (guard-tty-spoof-rule.ts).
+ */
+import * as path from 'path';
+import { HookContext, HookMeta, HookResult, NO_OP, SungenHook } from './hook-result-contract';
+import { GuardedCall, GuardRule, bashProtectedMention, protectedApprovalPaths, protectedHookControl } from './guard-rules';
+import { deliveryContractVerdict } from './guard-delivery-contract-rule';
+import { ttySpoof } from './guard-tty-spoof-rule';
+
+export type { GuardedCall, GuardRule } from './guard-rules';
+
+export const meta: HookMeta = {
+  events: ['PreToolUse'],
+  matchers: { PreToolUse: 'Edit|Write|MultiEdit|Bash' },
+  timeout: 5,
+};
+
+/** The rules, in order (first deny wins, else first ask). */
+export const GUARD_RULES: GuardRule[] = [protectedApprovalPaths, protectedHookControl, bashProtectedMention, ttySpoof, deliveryContractVerdict];
+
+/** First deny wins; otherwise the first ask; otherwise ok. */
+export function evaluateGuard(call: GuardedCall, ctx: HookContext, rules: GuardRule[] = GUARD_RULES): HookResult {
+  let ask: HookResult | null = null;
+  for (const rule of rules) {
+    let r: HookResult | null;
+    try { r = rule.check(call, ctx); } catch {
+      if (rule.onError === 'ask') ask ??= { status: 'ask', askReason: `sungen guard (${rule.id}) could not read the project state it decides on — confirm this call yourself.` };
+      continue;
+    }
+    if (r?.status === 'deny') return r;
+    if (r?.status === 'ask') ask ??= r;
+  }
+  return ask ?? { status: 'ok' };
+}
+
+const GUARDED_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'Bash']);
+
+export const preToolGuardHook: SungenHook = {
+  name: 'pre-tool-guard',
+  meta,
+  // A payload too large to read (an agent can build one with a huge Write) is not a free pass.
+  onUnreadableInput: { status: 'ask', askReason: 'sungen guard: this tool call is too large to inspect — confirm it yourself.' },
+  run(input, ctx) {
+    const tool = typeof input.tool_name === 'string' ? input.tool_name : '';
+    if (!GUARDED_TOOLS.has(tool)) return NO_OP;
+    const ti = input.tool_input && typeof input.tool_input === 'object' ? input.tool_input as Record<string, unknown> : {};
+    const filePaths = tool !== 'Bash' && typeof ti.file_path === 'string' && ti.file_path ? [path.resolve(ctx.cwd, ti.file_path)] : [];
+    const bashCommand = tool === 'Bash' && typeof ti.command === 'string' ? ti.command : undefined;
+    return evaluateGuard({ tool, filePaths, bashCommand, cwd: ctx.cwd }, ctx);
+  },
+};

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

@@ -0,0 +1,56 @@
+/**
+ * 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, and the next steps.
+ */
+import { NO_OP, HookMeta, SungenHook } from './hook-result-contract';
+import { formatSteps, locateUnitState } from './hand-back-core';
+import { sungenInvocation } from '../cli/project-sungen-invocation';
+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),
+      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,37 @@
+/**
+ * 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.',
+        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/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');
+}