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

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

@@ -2,7 +2,7 @@
  * 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` and `journey --signoff` 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 +13,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)/i;
 
 export const ttySpoof: GuardRule = {
   id: 'tty-spoof',
@@ -23,7 +23,7 @@ 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`) 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,27 @@
  * 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';
 
-/** `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 +42,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 +62,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 +87,10 @@ 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 as `root` runs sungen. */
+export function formatSteps(steps: NextStep[], max = 4, root?: string): string[] {
   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]} ${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. */
@@ -101,6 +107,6 @@ export function run(input: HookInput, ctx: HookContext): HookResult {
   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)].join('\n'),
   };
 }

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

@@ -9,6 +9,7 @@
  */
 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';
 
@@ -40,14 +41,15 @@ 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),
       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/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.
 

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).