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

package/src/cli/commands/next.ts

@@ -3,12 +3,33 @@
  *
  * The next step is derived from what the project HOLDS, not from which command just ran, so a
  * session cannot lose the thread by finishing somewhere that has no footer of its own (#597).
+ *
+ *   sungen next [unit]                every unit (or one), unit-level steps; test-case work folds
+ *                                     into one line per node ("N test case(s) …")
+ *   sungen next <unit> --case <id>    one test case: its state, and its steps after the blocking
+ *                                     unit steps before them (OES-10.3)
+ *   --json                            the same, machine-readable; steps add nodeId, granularity,
+ *                                     testCase?, gates?; the unit adds `results` (#942) and
+ *                                     `humanActions: [{command, reason, kind, rendered}]` (#954) —
+ *                                     `command` canonical, `rendered` as this project runs it (#963),
+ *                                     and `humanActionsHeldBy[Command]` when a blocking step holds them (#966);
+ *                                     every older field is kept. stdout is the payload alone (#660, #836)
+ * The text names the run the results come from and warns when they are older than the suite (#942),
+ * and ends with "Waiting for you": every pending human-only command, with why (#954).
  */
 import { Command } from 'commander';
 import * as fs from 'fs';
 import * as path from 'path';
-import { readUnitState, UnitState } from '../../harness/next-step';
+import { CLI_GIT_TIMEOUT_MS, headSnapshot } from '../../contract/contract-git';
+import { testCaseStatusLabel } from '../../graph/test-case-satisfied';
+import { testCaseStates } from '../../graph/test-case-states';
+import { describeResultsRun } from '../../graph/unit-results-freshness';
+import { deriveSteps, NextStep, readUnitState, UnitState } from '../../harness/next-step';
 import { resolveUnit, resolveUnitCandidates, AmbiguousUnitError } from '../resolve-unit';
+import { withProjectInvocation, withProjectInvocationInText } from '../project-sungen-invocation';
+import { waitingForYouLines } from '../waiting-for-you-block';
+import { caseTriageLines } from '../case-triage-hint';
+import { testCaseNeed } from '../../graph/test-case-satisfied';
 
 /** Every unit the project holds, so `sungen next` with no argument still answers. */
 function allUnits(cwd: string): Array<{ name: string; kind: UnitState['kind']; dir: string }> {
@@ -24,7 +45,25 @@ function allUnits(cwd: string): Array<{ name: string; kind: UnitState['kind']; d
   return out;
 }
 
-function render(s: UnitState): void {
+/** Steps as text, each `sungen …` command — the reason's too (#963) — as this project runs it (#939); `--json` keeps them canonical. */
+function renderSteps(steps: NextStep[], cwd: string): void {
+  for (const st of steps) {
+    const mark = st.kind === 'blocked' ? '⛔' : st.kind === 'optional' ? '○' : st.kind === 'decide' ? '⚖' : '→';
+    console.log(`  ${mark} ${withProjectInvocationInText(st.command, cwd)}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}`);
+    console.log(`     ${withProjectInvocationInText(st.because, cwd)}`);
+  }
+}
+
+/**
+ * `--json`: each human action keeps its canonical `command` and adds `rendered` — the line a human runs in
+ * this project (`npx sungen …` with a local install; an instruction unchanged), as the text shows it (#963).
+ */
+function withRenderedHumanActions(s: UnitState, cwd: string): UnitState {
+  if (!s.humanActions) return s;
+  return { ...s, humanActions: s.humanActions.map((a) => ({ ...a, rendered: a.instruction ? a.command : withProjectInvocation(a.command, cwd) })) };
+}
+
+function render(s: UnitState, cwd: string): void {
   const L = console.log;
   L('');
   L(`━━━ Next steps: ${s.unit} (${s.kind}) ━━━`);
@@ -38,12 +77,48 @@ function render(s: UnitState): void {
   ].filter(Boolean);
   L(`  state: ${held.length ? held.join(' · ') : '(nothing yet)'}`);
   if (s.audit) L(`  audit: ${s.audit.overall}/10 [${s.audit.gateStatus}] · ${s.audit.findings.length} finding(s)`);
+  else if (s.auditNotCounted) L(`  audit: ${s.auditNotCounted.state === 'stale' ? 'stale' : 'not trusted'} — ${withProjectInvocationInText(s.auditNotCounted.reason, cwd)}`);
+  if (s.results) {
+    L(`  results: ${s.results.files.length} file${s.results.files.length === 1 ? '' : 's'}, ${describeResultsRun(s.results)}`);
+    if (s.results.warning) L(`  ⚠ ${s.results.warning}`);
+  }
   L('');
-  for (const st of s.steps) {
-    const mark = st.kind === 'blocked' ? '⛔' : st.kind === 'optional' ? '○' : st.kind === 'decide' ? '⚖' : '→';
-    L(`  ${mark} ${st.command}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}`);
-    L(`     ${st.because}`);
+  renderSteps(s.steps, cwd);
+  L('');
+  const waiting = waitingForYouLines(s.humanActions, cwd, s.humanActionsHeldBy, s.humanActionsHeldByCommand);
+  if (waiting.length) { for (const line of waiting) L(line); L(''); }
+}
+
+/** `--case <id>`: the case's state and its frontier. Exits 1 when the case cannot be found. */
+function caseView(s: UnitState, cwd: string, unitDir: string, id: string, json: boolean): void {
+  let cases = s.testCases;
+  if (!cases) {
+    try { cases = testCaseStates(cwd, s.unit, { unitDir }); } catch (e) {
+      throw new Error(`the test cases of ${s.unit} could not be read: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+  const tc = cases.find((c) => c.id === id);
+  if (!tc) {
+    const known = cases.slice(0, 8).map((c) => c.id).join(', ');
+    throw new Error(`no test case "${id}" in ${s.unit}${known ? ` — known: ${known}${cases.length > 8 ? ', …' : ''}` : ' (it holds no scenario)'}`);
   }
+  const steps = deriveSteps({ ...s, testCases: cases }, { testCase: id });
+  if (json) { console.log(JSON.stringify({ unit: s.unit, kind: s.kind, testCase: tc, steps }, null, 2)); return; }
+  const L = console.log;
+  L('');
+  L(`━━━ Next steps: ${s.unit} › ${tc.id} (${s.kind}) ━━━`);
+  L('');
+  L(`  test case: ${tc.title}${tc.unstableId ? '   (no VP-id — this id changes when the title does)' : ''}`);
+  L(`  where:     ${tc.file}#L${tc.lines[0]}-L${tc.lines[1]}`);
+  L(`  status:    ${testCaseStatusLabel(tc)} · result ${tc.result}${tc.mocked && tc.result === 'passed' ? ' (mocked)' : ''}${tc.stale ? ` · stale: ${tc.stale}` : ''}${tc.triage ? ` · triage ${tc.triage.class}${tc.triage.ruleId === 'manual' ? ` (by hand, ${tc.triage.decision})` : ''}` : ''}`);
+  if (tc.contract) L(`  contract:  ${tc.contract.class}${tc.contract.uncommitted ? ' · lock entry not committed' : ''}${tc.contract.lowIdentity ? ' · low target identity' : ''}`);
+  if (tc.anchors.length) L(`  anchors:   ${tc.anchors.map((a) => `${a.anchor} (${a.change})`).join(', ')}`);
+  for (const f of tc.findings) L(`  finding:   ${f.code} [${f.confidence.label} ${f.confidence.score}] ${f.citation}`);
+  L('');
+  if (steps.length) renderSteps(steps, cwd);
+  else L(`  ✓ nothing to do for this test case — ${testCaseStatusLabel(tc)}`);
+  // "needs triage" names how to classify the red, even while a unit step holds its own step back (#966).
+  if (testCaseNeed(tc) === 'triage') for (const line of caseTriageLines(s, tc, steps, cwd)) L(line);
   L('');
 }
 
@@ -51,10 +126,13 @@ export function registerNextCommand(program: Command): void {
   program
     .command('next [unit]')
     .description('What to do next for a unit (or every unit), derived from the project state')
+    .option('--case <id>', 'One test case of the unit (its VP-id): its state and its next steps')
     .option('--json', 'Machine-readable output')
-    .action((unit: string | undefined, o: { json?: boolean }) => {
+    .action((unit: string | undefined, o: { json?: boolean; case?: string }) => {
       try {
         const cwd = process.cwd();
+        if (o.case && !unit) throw new Error('--case needs a unit: sungen next <unit> --case <id>');
+        const gitSnapshot = headSnapshot(cwd, CLI_GIT_TIMEOUT_MS);
         let states: UnitState[];
         if (unit) {
           const resolved = resolveUnit(unit, cwd);
@@ -62,7 +140,9 @@ export function registerNextCommand(program: Command): void {
             console.error(`Error: no unit named "${unit}" under qa/screens, qa/flows or qa/api.`);
             process.exit(1);
           }
-          states = [readUnitState(cwd, resolved.dir, unit, resolved.kind)];
+          const state = readUnitState(cwd, resolved.dir, unit, resolved.kind, { gitSnapshot });
+          if (o.case) { caseView(state, cwd, resolved.dir, o.case, Boolean(o.json)); return; }
+          states = [state];
         } else {
           const units = allUnits(cwd);
           if (units.length === 0) {
@@ -72,14 +152,15 @@ export function registerNextCommand(program: Command): void {
           // A name in two places is ambiguous; report it rather than answering for one of them.
           states = units.map((u) => {
             if (resolveUnitCandidates(u.name, cwd).length > 1) throw new AmbiguousUnitError(u.name, resolveUnitCandidates(u.name, cwd));
-            return readUnitState(cwd, u.dir, u.name, u.kind);
+            return readUnitState(cwd, u.dir, u.name, u.kind, { gitSnapshot });
           });
         }
         if (o.json) {
-          console.log(JSON.stringify(states.length === 1 ? states[0] : states, null, 2));
+          const out = states.map((s) => withRenderedHumanActions(s, cwd));
+          console.log(JSON.stringify(out.length === 1 ? out[0] : out, null, 2));
           return;
         }
-        for (const s of states) render(s);
+        for (const s of states) render(s, cwd);
       } catch (e) {
         console.error(`Error: ${e instanceof Error ? e.message : e}`);
         process.exit(1);

package/src/cli/commands/triage.ts

@@ -1,15 +1,44 @@
 import { Command } from 'commander';
 import * as path from 'path';
 import { resolveUnit } from '../resolve-unit';
+import { withProjectInvocation, withProjectInvocationInText } from '../project-sungen-invocation';
+import { processIO } from '../../decisions/human-confirmation';
+import { manualClassifications } from '../../graph/manual-triage-decisions';
+import { testCaseStates } from '../../graph/test-case-states';
 import { triageUnit, writeTriageReport } from '../../harness/triage-unit';
+import { classifyRedCase } from '../../harness/triage-manual-classification';
 import type { TriageClass } from '../../harness/triage';
 
 /** Display order: what needs a decision first, green last. */
 const ORDER: TriageClass[] = ['product-candidate', 'unclassified', 'test-defect', 'environment', 'blocked-capability', 'known-defect', 'flaky'];
 
+interface TriageOptions { screen?: string; api?: string; area?: string; json?: boolean; case?: string; as?: string; reason?: string }
+
+/** The classifications by hand in force for the unit (they win over the automatic class of the same red). */
+function printManual(cwd: string, unitDir: string, name: string): void {
+  const inForce = testCaseStates(cwd, name, { unitDir, auditFindings: [] }).filter((c) => c.triage?.ruleId === 'manual');
+  if (!inForce.length) return;
+  const why = new Map(manualClassifications(cwd, unitDir).map((m) => [m.decision, m]));
+  console.log(`\n  classified by hand (${inForce.length}) — these win over the automatic class`);
+  for (const c of inForce) {
+    const m = why.get(c.triage!.decision ?? '');
+    console.log(`    • ${c.id} → ${c.triage!.class}${m ? ` (${m.decision}, by ${m.by}): ${m.reason}` : ''}`);
+  }
+}
+
+/** `--case <id> --as <class> --reason "…"`: record one classification by hand (harness/triage-manual-classification.ts). */
+async function classifyByHand(cwd: string, name: string, o: TriageOptions): Promise<void> {
+  if (!o.case || !o.as) throw new Error(o.as ? '--as needs --case <id>' : '--case needs --as product|test-defect|environment and --reason "…"');
+  const r = await classifyRedCase({ projectRoot: cwd, unit: name, caseId: o.case, as: o.as, reason: o.reason, io: processIO() });
+  if (o.json) { console.log(JSON.stringify({ status: r.status, caseId: r.caseId, class: r.class, path: path.relative(cwd, r.path), entry: r.entry }, null, 2)); return; }
+  console.log(`\n${r.status === 'created' ? '✓ Recorded' : '= Already recorded'} ${r.entry.id}: ${r.caseId} → ${r.class} (classified by hand) → ${path.relative(cwd, r.path)}`);
+  console.log('  It holds until the case runs again. Commit it through review with the run it judged.\n');
+}
+
 /**
  * `sungen triage` — classify every red or flaky scenario of the latest run (see harness/triage.ts).
- * Reports, never gates: always exits 0 once the unit is found.
+ * Reports, never gates: always exits 0 once the unit is found. With `--case --as` it records one
+ * classification by hand instead (exit 1 when refused or invalid).
  */
 export function registerTriageCommand(program: Command): void {
   program
@@ -18,14 +47,18 @@ export function registerTriageCommand(program: Command): void {
     .option('-s, --screen <name>', 'Screen or flow name')
     .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
     .option('--area <name>', 'Alias of --api')
+    .option('--case <id>', 'Classify one red test case by hand (its VP-id) — with --as and --reason')
+    .option('--as <class>', 'product (anyone may record it) | test-defect | environment (test-defect and environment: a human types a confirmation on a TTY)')
+    .option('--reason <text>', 'Why the red is that class (mandatory with --as)')
     .option('--json', 'Output the raw JSON report')
-    .action((o: { screen?: string; api?: string; area?: string; json?: boolean }) => {
+    .action(async (o: TriageOptions) => {
       try {
         const name = o.screen || o.api || o.area;
         if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
         const cwd = process.cwd();
         const unit = resolveUnit(name, cwd);
         if (!unit) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+        if (o.case || o.as) { await classifyByHand(cwd, name, o); return; }
 
         const report = triageUnit(cwd, unit);
         if (report.resultFiles.length === 0) {
@@ -48,9 +81,14 @@ export function registerTriageCommand(program: Command): void {
             L(`      ${r.ruleId}: ${r.evidence}`);
           }
         }
+        printManual(cwd, unit.dir, name);
+        if (report.rows.some((r) => r.class === 'unclassified')) {
+          L(`\n  Unclassified: read the evidence (trace, error), then classify by hand:\n    ${withProjectInvocation(`sungen triage --${unit.kind === 'api' ? 'api' : 'screen'} ${name} --case <id> --as product|test-defect|environment --reason "…"`, cwd)}`);
+        }
         L(`\n  Report: ${path.relative(cwd, saved)}\n`);
       } catch (error) {
-        console.error('Error:', error instanceof Error ? error.message : error);
+        // A refusal names the command a human runs instead: as this project runs sungen (#963).
+        console.error('Error:', error instanceof Error ? withProjectInvocationInText(error.message, process.cwd()) : error);
         process.exitCode = 1;
       }
     });

package/src/cli/commands/update.ts

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -26,7 +26,9 @@ import { syncProjectSungenDeps } from '../../orchestrator/project-deps-sync';
  *
  * The public `--skip-npm-install` flag is still available for users who
  * already installed the binary by other means (CI pipelines, corporate
- * mirror, manual download) and only want to refresh the project AI assets.
+ * mirror, manual download). It skips only step 1: the project sync still
+ * re-pins package.json (security overrides included) and runs `npm install`
+ * there — `--skip-project` skips that (#939).
  */
 
 const SKIP_NPM_ENV = 'SUNGEN_UPDATE_SKIP_NPM';
@@ -41,7 +43,7 @@ export function registerUpdateCommand(program: Command): void {
   program
     .command('update')
     .description(
-      'Reinstall @sun-asterisk/sungen (stable by default, --beta for prerelease) + refresh AI rules, commands, skills',
+      'Reinstall @sun-asterisk/sungen (stable by default, --beta / --alpha for prerelease) + refresh AI rules, commands, skills',
     )
     .option('--dry-run', 'Show what would be updated without making changes')
     .option(
@@ -56,13 +58,25 @@ export function registerUpdateCommand(program: Command): void {
       'Switch to the BETA channel (installs @beta — prerelease builds for testing)',
       false,
     )
+    // `--beta --alpha` is ambiguous: commander refuses it while parsing — one usage-error line, exit 1,
+    // before the action (and any npm install) runs — rather than settling it by flag order.
+    .addOption(
+      new Option(
+        '--alpha',
+        'Switch to the ALPHA channel (installs @alpha — early builds of the next big update, ahead of beta)',
+      )
+        .default(false)
+        .conflicts('beta'),
+    )
     .option(
       '--tag <dist-tag>',
-      'Install a specific npm dist-tag (e.g. latest, beta, next). Overrides --beta.',
+      'Install a specific npm dist-tag (e.g. latest, beta, alpha, next). Overrides --beta / --alpha.',
     )
+    // #939: it skips only the GLOBAL install — the project is still synced, so the help says so.
     .option(
       '--skip-npm-install',
-      'Skip the global npm install step (refresh project AI assets only)',
+      'Skip the global npm install step. The project is still synced: its sungen packages are re-pinned in package.json '
+        + '(security `overrides` included) and `npm install` runs in the project — add --skip-project to skip that too',
       false,
     )
     .option(
@@ -70,16 +84,14 @@ export function registerUpdateCommand(program: Command): void {
       'Skip reinstalling the project-local sungen packages (AI assets only — leaves node_modules stale)',
       false,
     )
-    .action(async (options: { dryRun?: boolean; beta?: boolean; tag?: string; skipNpmInstall?: boolean; skipProject?: boolean; assistant?: string[]; force?: boolean }) => {
+    .action(async (options: { dryRun?: boolean; beta?: boolean; alpha?: boolean; tag?: string; skipNpmInstall?: boolean; skipProject?: boolean; assistant?: string[]; force?: boolean }) => {
       try {
         const skipNpm =
           Boolean(options.skipNpmInstall) || process.env[SKIP_NPM_ENV] === '1';
         const skipProject =
           Boolean(options.skipProject) || process.env[SKIP_PROJECT_ENV] === '1';
 
-        // Channel resolution via npm dist-tags. Default `latest` = official/stable.
-        // `--beta` → beta channel; running plain `sungen update` later switches back to stable.
-        const channel = options.tag || (options.beta ? 'beta' : 'latest');
+        const channel = resolveUpdateChannel(options);
 
         if (!skipNpm) {
           reinstallSungen(channel);
@@ -106,6 +118,13 @@ export function registerUpdateCommand(program: Command): void {
         // …and move the old `trace: 'on-first-retry'` default, which never records a trace off CI.
         const { installTraceMode } = require('../../orchestrator/trace-mode-install');
         installTraceMode(process.cwd(), options.dryRun ?? false);
+        // Claude Code hooks: re-merged into .claude/settings.json (user hooks kept); sungen entries a
+        // newer version dropped, or qa/sungen.config.yaml turned off, are removed.
+        if (resolveAssistants(options.assistant).includes('claude')) {
+          const { installClaudeHooks, describeHooksInstall } = require('../../orchestrator/claude-hooks-install');
+          const hooks = installClaudeHooks(process.cwd(), { dryRun: options.dryRun ?? false });
+          console.log(`${hooks.settings === 'unreadable' ? '⚠️ ' : '🪝'} ${options.dryRun ? '[dry-run] ' : ''}${describeHooksInstall(hooks)}\n`);
+        }
       } catch (error) {
         console.error('❌ Update failed:', error);
         process.exit(1);
@@ -113,6 +132,18 @@ export function registerUpdateCommand(program: Command): void {
     });
 }
 
+/**
+ * The npm dist-tag `sungen update` installs. `latest` = official/stable (the default, and how a
+ * plain `sungen update` switches back); `--beta` / `--alpha` pick a prerelease channel (each branch
+ * auto-publishes to the dist-tag of its name); `--tag` names any dist-tag and wins over both.
+ * `--beta` with `--alpha` never reaches here — the option definition refuses the pair.
+ */
+export function resolveUpdateChannel(o: { tag?: string; beta?: boolean; alpha?: boolean }): string {
+  if (o.tag) return o.tag;
+  if (o.alpha) return 'alpha';
+  return o.beta ? 'beta' : 'latest';
+}
+
 function reinstallSungen(channel: string): void {
   const spec = `@sun-asterisk/sungen@${channel}`;
   const label = channel === 'latest' ? 'stable (latest)' : `${channel} channel`;
@@ -139,7 +170,7 @@ function printCurrentVersion(channel: string): void {
     spawnSync('sungen', ['--version'], { stdio: 'inherit', shell: true });
   }
   if (channel === 'latest') {
-    console.log('   Channel: stable. To try prereleases:  sungen update --beta');
+    console.log('   Channel: stable. To try prereleases:  sungen update --beta  (or --alpha for the next big update)');
   } else {
     console.log(`   Channel: ${channel} (prerelease). To return to stable:  sungen update`);
   }

package/src/cli/index.ts

@@ -44,12 +44,25 @@ import { registerLoginCommand } from './commands/login';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { warnAssetsDrift } from '../orchestrator/assets-drift';
+import { attachCliHandBack } from '../hooks/hand-back-core';
+import { attachJsonErrorOnExit, commandSupportsJson } from './json-error-on-exit';
+import { registerHookCommand } from '../hooks/hook-cli-command';
 
 // Read version from package.json so `--version` never drifts from the released version.
 const { version } = require('../../package.json') as { version: string };
 
 async function main() {
+  // #597 + P0.1 — the hand-back, once, for EVERY command, and from the moment parsing starts: a
+  // usage error never reaches an action, and `main().catch` exits from outside one. It hangs off
+  // process exit (not postAction) because several commands exit with a MEANINGFUL code that skips
+  // commander's hooks (`depth-lint` → 2). It points at `sungen next` instead of restating a step,
+  // so it cannot drift from the project state. A failure prints it on stderr after the error;
+  // `--json`/`--grep` keep it off stdout (#836); `hook` never prints one, `next` only when it fails (#937). The line and
+  // those rules live in the hook core (src/hooks/hand-back-core.ts) — this file only wires it.
+  const handBack = attachCliHandBack(process.argv, process.cwd());
   const program = new Command();
+  // #939: a failed `--json` command prints {"error":{code,message}} on stdout (json-error-on-exit.ts).
+  const jsonErrors = attachJsonErrorOnExit(process.argv, (args) => commandSupportsJson(program, args));
 
   program
     .name('sungen')
@@ -97,6 +110,10 @@ registerSetupMobileEnvCommand(program);
   registerIngestCommand(program);
   registerEvalCommand(program);
   registerLoginCommand(program);
+  // Test Contract (DOS-14). Registered inline (typed require, still loaded eagerly like every command)
+  // so the phase that added it touches ONE line of this file — no import-block edit to merge-conflict.
+  (require('./commands/contract') as typeof import('./commands/contract')).registerContractCommand(program);
+  registerHookCommand(program); // hidden: Claude Code hooks, JSON on stdout
 
   // Capability-contributed CLI commands (Capability SPI): drivers own their authoring commands
   // (e.g. @sungen/driver-api → `sungen api import`). Discover, then register each.
@@ -108,38 +125,15 @@ registerSetupMobileEnvCommand(program);
   // Every command warns once when the project's AI assets came from a different
   // build — `update` is the only thing that refreshes them, and nothing used to
   // say so (stderr, so `--json` output stays parseable).
-  program.hook('preAction', () => { warnAssetsDrift(process.cwd()); });
-
-  // #597 — the hand-back, once, for EVERY command. It used to be hardcoded per command and only
-  // two of twenty-nine printed one, so a run that finished anywhere else finished in silence:
-  // `capability add` ended with a blank line and the session stopped mid-workflow. Adding a
-  // footer to the other twenty-seven would repeat the mistake in bulk.
-  //
-  // It hangs off `process.on('exit')` rather than a postAction hook because several commands
-  // exit with a MEANINGFUL code (`depth-lint` returns 2 when there are deepen candidates) and
-  // `process.exit` skips commander's hooks entirely — a postAction version printed for `audit`
-  // and silently not for `depth-lint`, which is the same class of gap all over again.
-  //
-  // It points at `sungen next` instead of restating a step, so it can never drift from the real
-  // project state. Skipped on a hard error (code 1): there the error message is the actionable
-  // thing, and burying it under a footer helps nobody. `--json` keeps stdout parseable.
-  let handBack: { unit?: string; json: boolean } | null = null;
+  // `hook` speaks only JSON to Claude Code — no drift warning there.
   program.hook('preAction', (_thisCommand, actionCommand) => {
-    if (actionCommand.name() === 'next') return;            // `next` IS the answer
-    const opts = actionCommand.opts() as Record<string, unknown>;
-    const unit = [opts.screen, opts.flow, opts.area].find((v) => typeof v === 'string' && v)
-      ?? (typeof actionCommand.args?.[0] === 'string' ? actionCommand.args[0] : undefined);
-    // `--grep` is machine output too: callers capture it with `$(…)`, and a footer on stdout
-    // became part of the regex — the last alternative of `changed --grep` silently matched
-    // nothing, so `--change-only` skipped its last scenario (#836).
-    handBack = { unit: unit as string | undefined, json: opts.json === true || opts.grep === true };
+    if (actionCommand.name() !== 'hook') warnAssetsDrift(process.cwd());
   });
-  process.on('exit', (code) => {
-    if (!handBack || code === 1) return;
-    const line = `\nNext: sungen next${handBack.unit ? ` ${handBack.unit}` : ''}`;
-    // stderr under --json / --grep so the hand-back never lands in the captured payload.
-    if (handBack.json) process.stderr.write(`${line}\n`);
-    else process.stdout.write(`${line}\n`);
+
+  // The action knows its unit and output mode; the hand-back default above is refined here.
+  program.hook('preAction', (_thisCommand, actionCommand) => {
+    handBack.onAction(actionCommand.name(), actionCommand.opts() as Record<string, unknown>, actionCommand.args);
+    jsonErrors.onAction();
   });
 
   await program.parseAsync(process.argv);

package/src/cli/json-error-on-exit.ts

@@ -0,0 +1,72 @@
+/**
+ * `--json` failures speak JSON too (#939 item 7). A command that supports `--json` and fails used to
+ * print its error on stderr and NOTHING on stdout, so a caller parsing stdout got an empty string. Now,
+ * when such a command exits non-zero without having written stdout, the exit prints one object:
+ *
+ *   {"error":{"code":"command-failed" | "usage-error","message":"<the error it printed>"}}
+ *
+ *   command-failed  the action ran and failed (`next nope --json`)
+ *   usage-error     commander refused the arguments before any action ran (`audit --json --bogus`)
+ * The human error stays on stderr, unchanged. A command that printed its own JSON keeps it, whatever
+ * its exit code (`contract check --json` exits 2 with the verdict); a command without `--json` is never
+ * touched — commander's own "unknown option '--json'" is its usage error, not a JSON caller's.
+ * Like the hand-back, it hangs off process exit: commands exit from inside their actions.
+ */
+import type { Command } from 'commander';
+
+export type JsonErrorCode = 'command-failed' | 'usage-error';
+export interface JsonError { error: { code: JsonErrorCode; message: string } }
+
+const ANSI = /\u001b\[[0-9;]*m/g;
+const ERROR_LINE = /^(?:Error|error|Fatal error|❌[^:]*):\s*/;
+const MAX_CAPTURE = 64 * 1024;
+
+/** The error object for what the command printed on stderr: from its first error line on, the hand-back dropped. */
+export function jsonErrorPayload(stderr: string, actionRan: boolean, exitCode: number): JsonError {
+  const lines = stderr.replace(ANSI, '').split('\n').map((l) => l.trimEnd()).filter((l) => l && !/^Next: /.test(l));
+  const at = lines.findIndex((l) => ERROR_LINE.test(l));
+  const picked = at >= 0 ? lines.slice(at) : lines.slice(-1);
+  const message = picked.join('\n').replace(ERROR_LINE, '').trim() || `exited with code ${exitCode}`;
+  return { error: { code: actionRan ? 'command-failed' : 'usage-error', message } };
+}
+
+/** The (sub)command `args` name, walked down from `program`, defines `--json`. */
+export function commandSupportsJson(program: Command, args: string[]): boolean {
+  let cmd: Command = program;
+  for (const a of args) {
+    if (a.startsWith('-')) continue;
+    const sub = cmd.commands.find((c) => c.name() === a || c.aliases().includes(a));
+    if (!sub) break;
+    cmd = sub;
+  }
+  return cmd !== program && cmd.options.some((o) => o.long === '--json');
+}
+
+/**
+ * Wire it to process exit for `argv` (a no-op without `--json`). `supportsJson` is asked at exit, once
+ * every command is registered; `onAction` marks that an action ran (a failure then is not a usage error).
+ */
+export function attachJsonErrorOnExit(argv: string[], supportsJson: (args: string[]) => boolean): { onAction: () => void } {
+  const args = argv.slice(2);
+  if (!args.includes('--json')) return { onAction: () => undefined };
+  let wroteStdout = false;
+  let stderr = '';
+  let actionRan = false;
+  const writeOut = process.stdout.write.bind(process.stdout);
+  const writeErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = ((chunk: unknown, ...rest: unknown[]) => {
+    if (String(chunk).length) wroteStdout = true;
+    return (writeOut as (...a: unknown[]) => boolean)(chunk, ...rest);
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: unknown, ...rest: unknown[]) => {
+    if (stderr.length < MAX_CAPTURE) stderr += String(chunk);
+    return (writeErr as (...a: unknown[]) => boolean)(chunk, ...rest);
+  }) as typeof process.stderr.write;
+  process.on('exit', (code) => {
+    try {
+      if (code === 0 || wroteStdout || !supportsJson(args)) return;
+      writeOut(`${JSON.stringify(jsonErrorPayload(stderr, actionRan, code))}\n`);
+    } catch { /* the exit code is the contract; this object is a courtesy */ }
+  });
+  return { onAction: () => { actionRan = true; } };
+}

package/src/cli/project-sungen-invocation.ts

@@ -0,0 +1,59 @@
+/**
+ * How a hint names sungen inside a project (#939, items 1–2).
+ *
+ * A project that installs its own sungen (`npm i -D @sun-asterisk/sungen`) runs it with `npx sungen`;
+ * a bare `sungen` is whatever global install the machine has — in the field test an older 3.2.24-beta
+ * beside the project's 3.3.0-alpha. And `sungen update` without a flag switches to the stable
+ * channel, so on an alpha or beta install the update hint must keep the channel it runs on.
+ *
+ *   sungenInvocation(root)          'npx sungen' when <root>/node_modules/@sun-asterisk/sungen exists, else 'sungen'
+ *   withProjectInvocation(cmd, root) a canonical `sungen …` command as this project runs it
+ *   withProjectInvocationInText(text, root)
+ *                                   every `sungen …` command inside printed text (a refusal, a hint, a
+ *                                   step's reason) as this project runs it (#963); prose mentions stay
+ *   updateCommand(root, version?)   `<invocation> update` plus `--alpha` / `--beta` (`--tag <id>` for another prerelease)
+ *
+ * Only the project root itself is looked at — where `npm i` puts a QA project's install — so a
+ * monorepo checkout above a fixture does not turn its hints into `npx`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getPackageVersion } from '../exporters/package-info';
+
+export function sungenInvocation(projectRoot: string): string {
+  return fs.existsSync(path.join(projectRoot, 'node_modules', '@sun-asterisk', 'sungen', 'package.json')) ? 'npx sungen' : 'sungen';
+}
+
+/** `sungen audit --screen x` → `npx sungen audit --screen x` in a project with its own install; anything else unchanged. */
+export function withProjectInvocation(command: string, projectRoot: string): string {
+  const inv = sungenInvocation(projectRoot);
+  return inv !== 'sungen' && /^sungen\b/.test(command) ? `${inv}${command.slice('sungen'.length)}` : command;
+}
+
+/**
+ * A `sungen` that starts a command inside text: at the start of a line (after indentation), after a
+ * backtick or `(`, after ": ", "run " or "then " — and followed by a subcommand or an option. A prose
+ * mention ("written by sungen 3.3.0", "an older sungen", "sungen: …") is none of these.
+ */
+const COMMAND_IN_TEXT = /(^[ \t]*|[`(]|:[ \t]+|\b(?:[Rr]un|then)[ \t]+)sungen(?= [a-z-])/gm;
+
+/**
+ * Printed text (a refusal, a hint, a step's reason) with every `sungen …` command in it as this project
+ * runs sungen (#963): the human-only commands a QA copies from a refusal must run the project's own
+ * install, not an older global one. Text for machines (`--json`) stays canonical; this is for the screen.
+ */
+export function withProjectInvocationInText(text: string, projectRoot: string): string {
+  const inv = sungenInvocation(projectRoot);
+  return inv === 'sungen' ? text : text.replace(COMMAND_IN_TEXT, (_m, before: string) => `${before}${inv}`);
+}
+
+/** The `sungen update` flag that keeps the channel of `version` (its prerelease id); '' for stable. */
+export function updateChannelFlag(version: string = getPackageVersion()): string {
+  const id = version.match(/^\d+\.\d+\.\d+-([0-9A-Za-z-]+)/)?.[1];
+  if (!id) return '';
+  return id === 'alpha' || id === 'beta' ? ` --${id}` : ` --tag ${id}`;
+}
+
+export function updateCommand(projectRoot: string, version: string = getPackageVersion()): string {
+  return `${sungenInvocation(projectRoot)} update${updateChannelFlag(version)}`;
+}

package/src/cli/run-command-hints.ts

@@ -0,0 +1,47 @@
+/**
+ * The run commands sungen suggests, each writing its results where the reader that asks for them
+ * looks (#964). A hint whose results nobody reads leaves a passing run invisible: the plain
+ * `npx playwright test` wrote `test-result.json` at the project root, which `sungen next` never reads.
+ *
+ *   generatedSubdir(kind, unit)      `specs/generated/<unit>` · `…/flows/<flow>` · `…/api/<area>` — where
+ *                                    `generate` writes a unit's specs and `next` / `delivery` read its results
+ *   plainRunCommand(genRel, feature) one compiled feature's spec with the JSON reporter pointed at
+ *                                    `<genRel>/<feature>-test-result.json` (graph/unit-artifact-probes RESULT_FILE)
+ *   freeRunCommand(cwd)              hand-written @free / impl:code tests: the project's free-test config, which
+ *                                    writes into its own outputDir `test-results-free/` (#941)
+ *   freeRunHasResults(cwd)           that run left its results (or a sungen run record) there
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { FREE_RUN_DIR } from '../contract/trace/trace-run-record';
+
+export type RunUnitKind = 'screen' | 'flow' | 'api';
+
+export function generatedSubdir(kind: RunUnitKind, unit: string): string {
+  return path.posix.join('specs', 'generated', ...(kind === 'flow' ? ['flows'] : kind === 'api' ? ['api'] : []), unit);
+}
+
+/** `[SUNGEN_ENV=<env> ]PLAYWRIGHT_JSON_OUTPUT_NAME=<genRel>/<feature>-test-result.json npx playwright test <genRel>/<feature>.spec.ts` */
+export function plainRunCommand(genRel: string, featureBaseName: string, env?: string): string {
+  return `${env ? `SUNGEN_ENV=${env} ` : ''}PLAYWRIGHT_JSON_OUTPUT_NAME=${genRel}/${featureBaseName}-test-result.json npx playwright test ${genRel}/${featureBaseName}.spec.ts`;
+}
+
+const FREE_CONFIG = /^playwright\.free\.config\.(?:ts|mts|cts|js|mjs|cjs)$/;
+
+/** The free run: `npx playwright test -c <playwright.free.config.*>` when the project has one, else what that config holds. */
+export function freeRunCommand(cwd: string): string {
+  let config: string | undefined;
+  try { config = fs.readdirSync(cwd).find((f) => FREE_CONFIG.test(f)); } catch { /* no project dir: the generic form */ }
+  return config
+    ? `npx playwright test -c ${config}`
+    : `run the hand-written tests with the project's free-test config (outputDir '${FREE_RUN_DIR}', trace: 'on', the sungen run-record reporter — "Free tests" in the sungen docs)`;
+}
+
+/** The free run left its JSON results or a sungen run record in `test-results-free/`. */
+export function freeRunHasResults(cwd: string): boolean {
+  try {
+    return fs.readdirSync(path.join(cwd, FREE_RUN_DIR)).some((f) => f === 'results.json' || /^sungen-run-record.*\.json$/.test(f));
+  } catch {
+    return false;   // never run
+  }
+}