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

package/src/hooks/guard-rules.ts

@@ -4,20 +4,29 @@
  *
  *   protected-approval-paths  DENY  a precise write (Edit/Write/MultiEdit, or Bash `>`, `tee`,
  *                                   `sed -i`) to a contract lock, a decision record, approval state or
- *                                   trace evidence (.sungen/trace-identity, test-results/sungen-run-record*)
+ *                                   trace evidence (.sungen/trace-identity, test-results[-free]/sungen-run-record*)
  *   protected-hook-control    ASK   the same writes to the files that control the hooks, so the
  *                                   agent cannot switch its own guard off unasked
- *   bash-protected-mention    ASK   any other Bash segment that names a protected path and does not
- *                                   start with a read-only command (cp, mv, ln, install, rm,
- *                                   bash -c, python -c, perl -i…)
+ *   bash-protected-mention    ASK   any other Bash segment that names a protected path and is not
+ *                                   read-only (cp, mv, ln, install, rm, bash -c, python -c, perl -i…);
+ *                                   a read-only one too when its output is piped into a non-read-only
+ *                                   command, or the line has command substitution or sets shell state
+ *                                   (`X=…`, export, alias, a function…); a heredoc / here-string
+ *                                   that names one; and a write target with a glob or brace (#968 — bash-read-only-segment.ts lists what counts
+ *                                   as read-only, and the accepted floor)
  *
  * A floor, not a sandbox: a path built at runtime, a symlink, or a script file that writes without
- * naming the path on the command line is out of reach by design. Each rule only matches strings,
+ * naming the path on the command line is out of reach by design (the full list of what the floor
+ * does not catch is in bash-read-only-segment.ts; release-time decision integrity is the backstop). Each rule only matches strings,
  * so each fails open (`onError: 'no-op'`); a rule that READS project state must declare `'ask'`.
  */
+import * as path from 'path';
 import type { HookContext, HookResult } from './hook-result-contract';
-import { bashSegments } from './bash-write-targets';
-import { approvalRecordPath, hookControlPath, mentionsProtectedPath, traceEvidencePath } from './guard-protected-paths';
+import { BashSegment, bashSegments } from './bash-write-targets';
+import { isReadOnlySegment, lineKeepsReadOnlyExemption, pipelineStaysReadOnly } from './bash-read-only-segment';
+import {
+  approvalRecordPath, hookControlPath, mentionsProtectedPath, mentionsProtectedText, opaqueNearProtected, traceEvidencePath,
+} from './guard-protected-paths';
 
 /** One tool call, normalized from the untrusted payload. */
 export interface GuardedCall {
@@ -76,23 +85,33 @@ export const protectedHookControl: GuardRule = {
   },
 };
 
-/** Segments that only read: they may name a protected path freely. */
-const READ_ONLY = new Set(['cat', 'ls', 'head', 'tail', 'grep', 'rg', 'wc', 'diff', 'sungen', 'sungen.js']);
-const GIT_READ_ONLY = new Set(['diff', 'log', 'show', 'status']);
-const isReadOnly = (cmd: string, words: string[]): boolean =>
-  READ_ONLY.has(cmd) || (cmd === 'git' && GIT_READ_ONLY.has(words.find((w) => !w.startsWith('-')) ?? ''));
+/** A heredoc or here-string: its body is another program's input, which the segments do not see. */
+const HEREDOC = /<</;
 
 export const bashProtectedMention: GuardRule = {
   id: 'bash-protected-mention',
   onError: 'no-op',
   check(call) {
-    if (call.tool !== 'Bash' || !call.bashCommand) return null;
-    const seg = bashSegments(call.bashCommand, call.cwd)
-      .find((s) => s.cmd && !isReadOnly(s.cmd, s.words) && s.words.some((w) => mentionsProtectedPath(w, s.dir)));
-    return seg ? {
+    const command = call.tool === 'Bash' ? call.bashCommand : undefined;
+    if (!command) return null;
+    const segs = bashSegments(command, call.cwd);
+    const lineExempt = lineKeepsReadOnlyExemption(command, segs);
+    // the command word too: zsh `for f (qa/decisions/*) …` puts the list where a command name goes
+    const names = (s: BashSegment): boolean => [s.cmdPath, ...s.words, ...s.assigns.map((a) => a.slice(a.indexOf('=') + 1))]
+      .some((w) => w !== '' && (mentionsProtectedPath(w, s.dir) || opaqueNearProtected(w)));
+    const seg = segs.find((s, i) => names(s) && !(lineExempt && isReadOnlySegment(s) && pipelineStaysReadOnly(segs, i)));
+    // a write target the shell expands (`> q*/decisions/x`, `--output=qa/{a,b}`, `> $Q/decisions/x`, a literal `\`),
+    // or a relative one after a `cd` the guard could not follow, cannot be judged by its text
+    const opaqueWrite = segs.some((s) => s.writesInUnknownDir || s.writes.some((w) => {
+      const rel = path.relative(s.dir, w);
+      return /[*?[{\\]/.test(rel) || opaqueNearProtected(rel);
+    }));
+    if (!seg && !opaqueWrite && !(HEREDOC.test(command) && mentionsProtectedText(command))) return null;
+    const what = seg ? (seg.cmd ? `\`${seg.cmd}\` command` : 'variable') : opaqueWrite ? 'write target the guard cannot resolve' : 'heredoc';
+    return {
       status: 'ask',
-      askReason: `sungen: this \`${seg.cmd}\` command names a contract lock, a decision record, approval state or a hook-control file, `
+      askReason: `sungen: this ${what} names a contract lock, a decision record, approval state or a hook-control file, `
         + 'and the guard cannot tell whether it writes it. Allow only if you asked for exactly this.',
-    } : null;
+    };
   },
 };

package/src/hooks/guard-tty-spoof-rule.ts

@@ -2,7 +2,9 @@
  * Guard rule `tty-spoof` (phase 06, M5): ASK before an agent runs a human-confirmed sungen command
  * through a terminal emulator.
  *
- * `contract approve`, `journey --waive` and `journey --decide` refuse without a TTY (DOS-13.4), and
+ * `contract approve`, `journey --waive`, `journey --decide`, `journey --signoff`, `triage --as test-defect|environment`
+ * (#928: a red classified away from the product-defect path) and `delivery --accept-in-run` (delivering past
+ * decisions recorded during the run) refuse without a TTY (DOS-13.4), and
  * an agent's Bash has none — unless it borrows one: `script`, `expect`, `unbuffer`, or a pty from
  * Python/Perl/zsh. Then the prompt sees a "terminal" and a piped phrase reads as a human typing it.
  * This rule spots the pair in the raw command (quotes included, so `bash -c "…"` and `expect -c '…'`
@@ -13,7 +15,7 @@
 import type { GuardRule } from './guard-rules';
 
 const TTY_EMULATOR = /\b(?:script|unbuffer|expect|pty|zpty|openpty|forkpty|ptyprocess)\b/i;
-const HUMAN_GATED = /\bsungen\b[\s\S]*?\b(?:contract['",\s]+approve\b|journey\b[\s\S]*?--(?:waive|decide)\b)/i;
+const HUMAN_GATED = /\bsungen\b[\s\S]*?\b(?:contract['",\s]+approve\b|journey\b[\s\S]*?--(?:waive|decide|signoff)\b|triage\b[\s\S]*?--as[\s='",]+(?:test-defect|environment)\b|delivery\b[\s\S]*?--accept-in-run\b)/i;
 
 export const ttySpoof: GuardRule = {
   id: 'tty-spoof',
@@ -23,7 +25,8 @@ export const ttySpoof: GuardRule = {
     if (!cmd || !TTY_EMULATOR.test(cmd) || !HUMAN_GATED.test(cmd)) return null;
     return {
       status: 'ask',
-      askReason: 'sungen: this runs a human-confirmed sungen action (`contract approve` / `journey --waive|--decide`) through a terminal '
+      askReason: 'sungen: this runs a human-confirmed sungen action (`contract approve` / `journey --waive|--decide|--signoff` / '
+        + '`triage --as test-defect|environment` / `delivery --accept-in-run`) through a terminal '
         + 'emulator (script / expect / unbuffer / pty). Those confirmations exist so a PERSON at a terminal decides — allow only if you '
         + 'are that person and asked for exactly this; otherwise run the command yourself in your own terminal.',
     };

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

@@ -10,23 +10,28 @@
  * 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, withProjectInvocationInText } from '../cli/project-sungen-invocation';
+import { waitingForYouLines } from '../cli/waiting-for-you-block';
 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';
 
-/** `next` IS the answer; `hook` speaks JSON to Claude Code on stdout. Neither prints a hand-back. */
-const SILENT_COMMANDS = new Set(['next', 'hook']);
+/** `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.-]+)?$/;
 
-export function handBackLine(unit?: string): string {
-  return `Next: sungen next${unit ? ` ${unit}` : ''}`;
+/** `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; actionRan: boolean }
+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 {
@@ -38,13 +43,14 @@ export function initialHandBackState(argv: string[]): CliHandBackState {
     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), actionRan: false };
+  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).
@@ -57,10 +63,11 @@ export function onCliAction(state: CliHandBackState, name: string, opts: Record<
  */
 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);
+  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` };
 }
@@ -81,10 +88,14 @@ export function attachCliHandBack(argv: string[], cwd: string): { onAction: (nam
 
 const MARK: Record<NextStep['kind'], string> = { do: '→', blocked: '⛔', optional: '○', decide: '⚖' };
 
-/** `sungen next` rendered compactly for an agent's context. */
-export function formatSteps(steps: NextStep[], max = 4): string[] {
+/**
+ * `sungen next` rendered compactly for an agent's context; commands — the step's own and those quoted in
+ * its reason (#966) — as `root` runs sungen, the way `sungen next` prints them.
+ */
+export function formatSteps(steps: NextStep[], max = 4, root?: string): string[] {
+  const asRun = (text: string): string => (root ? withProjectInvocationInText(text, root) : text);
   return steps.slice(0, max).map((st) =>
-    `  ${MARK[st.kind]} ${st.command}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${st.because}`);
+    `  ${MARK[st.kind]} ${asRun(st.command)}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${asRun(st.because)}`);
 }
 
 /** The unit a session is on (a named one when it exists, else the nearest) and its derived state. */
@@ -95,12 +106,13 @@ export function locateUnitState(ctx: HookContext, preferred?: string): { root: s
   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. */
+/** Hook core: the next steps for the session's unit (input.unit, else the nearest) as context, then what waits for a human (#954). */
 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)} — derived from what the project holds now:`, ...formatSteps(found.state.steps)].join('\n'),
+    output: [`${handBackLine(found.unit.name, sungenInvocation(found.root))} — derived from what the project holds now:`, ...formatSteps(found.state.steps, 4, found.root),
+      ...waitingForYouLines(found.state.humanActions, found.root, found.state.humanActionsHeldBy, found.state.humanActionsHeldByCommand)].join('\n'),
   };
 }

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

@@ -5,10 +5,13 @@
  * 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.
+ * 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';
 
@@ -40,14 +43,16 @@ export const sessionStartUnitStateHook: SungenHook = {
     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),
+      `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).' : '',
+      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

@@ -30,6 +30,7 @@ export const stopNextStepHook: SungenHook = {
       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/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/project-initializer.ts

@@ -294,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)

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

@@ -102,8 +102,8 @@ 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` and `sungen journey --decide` record a QA
-decision and ask for a typed confirmation on a real terminal (TTY). Never run them, never fake the
+`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.
 
@@ -111,7 +111,10 @@ terminal (`script`, `expect`, a pty wrapper), and never edit `contracts.lock.yam
 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>`).
+counted by the audit until a QA approves it (`sungen contract approve --screen <name>`). When
+two recorded tests claim one ID, `sungen contract derive` exits `1`, names both tests and writes
+nothing: stop and ask the QA to give each test its own ID (its title's leading ID, or its `@tag`).
+Never rename a test's ID — or a scenario's — yourself to get past it.
 
 ## Platform detection (do this FIRST)
 

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

@@ -237,3 +237,5 @@ sungen delivery [names...]        # matrix (default; needs the map) → XLSX onl
 Outputs: `qa/deliverables/<unit>-testcases.xlsx` (Overview + Auto + Manual + Coverage sheets) by default;
 `--format csv` writes `<unit>-testcases.csv` instead (flat, `Level` column `item|variant`),
 `--format both` writes both. Legacy mode writes the classic files instead.
+
+<!-- include: waiting-for-you -->

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

@@ -97,3 +97,5 @@ You are an **independent QA Reviewer** — you did not author these tests. You d
 5. **Trace + next** — `sungen trace --screen ${input:name}` (human-loop focus), then offer:
    - **`/sungen-run-test ${input:name}`** (Recommended) · **`/sungen-delivery ${input:name}`** · **`/sungen-create-test ${input:name}`** · Done.
 {{/cap}}
+
+<!-- include: waiting-for-you -->

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

@@ -268,7 +268,7 @@ question already.
 7. **Phase 3 — Full Run**: Run all tests. Fix only **new** failures (elements unique to `@normal`/`@low`). Max 1 attempt. Don't loop on low-priority failures.
 8. **Phase 4 — Regression**: One final full run. No more fix loops. Then run `sungen triage --screen <name>` and render its table as the results summary: every red or flaky scenario already sits in one class (`product-candidate`, `unclassified`, `test-defect`, `environment`, `blocked-capability`, `known-defect`, `flaky`) with the rule and one evidence line. You may move an `unclassified` row into a class only with a written evidence line of your own. You may never turn a `product-candidate` into a `test-defect` by editing the `.feature` or the expected value — the Gherkin is frozen; report it as a candidate bug. For each `product-candidate` you judge to be a product bug, run `sungen defect draft --screen <name> --scenario "<title>"`, fill the record's Summary, check its Expected against `spec.md`, then add `@known-defect:DEF-NNN` to that scenario's tag line (the tag-only exception above). The severity in the draft is `proposed` — confirm it with QA (`AskUserQuestion`) before the hand-back and set `severity_source: qa`. A row you judge is not a product bug stays in the summary with your reason, and gets no record. A `bare-timeout` row (`unclassified`) is never re-run inside this command — Phase 4 was the final run; offer the re-run in Next steps.
 8a. **Test Contract — every unit with a lock.** When `qa/<screens|flows|api>/<name>/contracts.lock.yaml` exists, check the suite still does what QA approved:
-   - **`@free` / `@impl:code` scenarios** (hand-written specs, not compiled): in the Phase 4 final run, run their specs with `--trace on` (`npx playwright test <their spec> --trace on`) — their trace is the only proof. The project's config needs the sungen run-record reporter; if it is missing, no trace is admissible: tell the QA, do not edit the config yourself. Then `sungen contract check --screen <name> --trace`.
+   - **`@free` / `@impl:code` scenarios** (hand-written specs, not compiled): after the Phase 4 final run, run their specs with the project's free-test config and `--trace on` (`npx playwright test -c <free-test config> --trace on`) — their trace is the only proof. That config writes to its own `outputDir: 'test-results-free'` with `trace: 'on'` and the sungen run-record reporter; never run them into `test-results/`, which the next compiled run clears (the trace is then gone and the scenario is `unproven`). If the project has no such config, no trace is admissible: tell the QA, do not write or edit the config yourself. Then `sungen contract check --screen <name> --trace`.
    - **No free tests**: `sungen contract check --screen <name>`.
    - **Exit 2 (hard)** — `oracle-weakened`, `target-changed`, `assertion-lost`, `lock-uncommitted`, `unproven` → report each finding to the QA in the results summary, with its rule. **Never** edit the `.feature`, an expected value, the lock or a decision to turn it green, and **never** run `sungen contract approve` — approving is a QA's decision, on a terminal. **Exit 0 with `review`** → list it for the QA: review blocks `sungen delivery` until QA re-approves. **Exit 1** → report the error. No lock → skip: every scenario is `proposed`, which never blocks.
 9. **Phase 8 — Serial-cascade risk check** (#414): If any scenario has many steps, a skipped test may cause downstream steps to be incorrectly skipped due to the serial-cascade sensor detecting false "not reached" conditions. When you see "test skipped" messages during Phase 3–4 runs, check if the skipped scenario is a **blockers-exist** dependency in the test ledger (`sungen ledger query --screen <name>`). If the scenario had high step count and cascade fired, offer: *"Scenarios with deep steps can trigger serial-cascade skipping. Consider parallelizing this spec with `@concurrent` tags or breaking into smaller scenarios."* Let the user decide whether to refactor (do not auto-apply parallelization).

package/src/orchestrator/templates/ai-src/partials/waiting-for-you.claude.md

@@ -0,0 +1,11 @@
+<!-- sungen:waiting-for-you v1 -->
+## Waiting for you — the commands only the QA runs
+
+Right before the hand-back question, run `sungen next {{unitArg}}` and quote its **⏳ Waiting for you**
+block **verbatim** — every command exactly as printed, each with its reason. Those commands approve,
+sign off, waive, classify a red, accept in-run decisions or re-run once the environment is up: they are
+the QA's alone, and most refuse without a person typing a confirmation. Tell the QA to run each one in
+their own terminal — in Claude Code, type `! <command>` in the prompt (a `/sungen:…` command is typed
+as is). **Never run them yourself**, and never pipe or type a confirmation into them. When `sungen next`
+prints no such block, say that nothing is waiting for the QA.
+<!-- /sungen:waiting-for-you -->

package/src/orchestrator/templates/ai-src/partials/waiting-for-you.codex.md

@@ -0,0 +1,11 @@
+<!-- sungen:waiting-for-you v1 -->
+## Waiting for you — the commands only the QA runs
+
+Right before the hand-back list, run `sungen next {{unitArg}}` and quote its **⏳ Waiting for you**
+block **verbatim** — every command exactly as printed, each with its reason. Those commands approve,
+sign off, waive, classify a red, accept in-run decisions or re-run once the environment is up: they are
+the QA's alone, and most refuse without a person typing a confirmation. Tell the QA to run each one
+themselves, in their own terminal (a slash command is typed as is). **Never run them yourself**, and
+never pipe or type a confirmation into them. When `sungen next` prints no such block, say that nothing
+is waiting for the QA.
+<!-- /sungen:waiting-for-you -->

package/src/orchestrator/templates/ai-src/partials/waiting-for-you.copilot.md

@@ -0,0 +1,11 @@
+<!-- sungen:waiting-for-you v1 -->
+## Waiting for you — the commands only the QA runs
+
+Right before the hand-back list, run `sungen next {{unitArg}}` and quote its **⏳ Waiting for you**
+block **verbatim** — every command exactly as printed, each with its reason. Those commands approve,
+sign off, waive, classify a red, accept in-run decisions or re-run once the environment is up: they are
+the QA's alone, and most refuse without a person typing a confirmation. Tell the QA to run each one
+themselves, in their own terminal (a slash command is typed as is). **Never run them yourself**, and
+never pipe or type a confirmation into them. When `sungen next` prints no such block, say that nothing
+is waiting for the QA.
+<!-- /sungen:waiting-for-you -->