@sun-asterisk/sungen 3.3.0-alpha.6 → 3.3.0-alpha.8

package/src/cli/commands/contract-derive-command.ts

@@ -11,6 +11,7 @@ import * as path from 'path';
 import { deriveFreeFeature, DeriveResult, nothingDerived } from '../../contract/derive-free-feature';
 import { registeredTraceResolver } from '../../contract/resolve-unit-trace-identities';
 import { resolveContractUnit } from '../../contract/contract-units';
+import { withProjectInvocation } from '../project-sungen-invocation';
 
 function print(r: DeriveResult, unit: string): void {
   const L = console.log;
@@ -19,6 +20,7 @@ function print(r: DeriveResult, unit: string): void {
   L(`━━━ Contract derive: ${unit} — free tests' traces → ${rel} ━━━`);
   L('');
   if (r.note) L(`  ⚠ ${r.note}`);
+  for (const w of r.warnings ?? []) L(`  ⚠ ${w}`);
   for (const s of r.scenarios) L(`  + ${s.title}  (${s.steps} steps${s.low ? `, ${s.low} low identity` : ''}${s.opaque ? `, ${s.opaque} opaque` : ''})`);
   for (const s of r.skipped) L(`  - ${s.id}  skipped: ${s.reason}`);
   if (r.refused?.length) {
@@ -27,7 +29,7 @@ function print(r: DeriveResult, unit: string): void {
     L('    Move the value into test-data (or an env overlay) and use it from there, then derive again.');
   } else if (r.written) {
     L(`  ✓ Wrote ${rel}. Review the steps (they ARE the contract), then QA approves on a terminal:`);
-    L(`    sungen contract approve --screen ${unit}`);
+    L(`    ${withProjectInvocation(`sungen contract approve --screen ${unit}`, process.cwd())}`);
     L('  After approval, re-run the free tests (trace: "on") — a trace older than the contract proves nothing.');
   } else if (r.scenarios.length) {
     L(`  = ${rel} is already up to date.`);

package/src/cli/commands/contract.ts

@@ -28,6 +28,7 @@ import { resolveContractUnit } from '../../contract/contract-units';
 import { secretScanHits } from '../../contract/field-semantic-redaction';
 import { resolveUnitTraceIdentities } from '../../contract/resolve-unit-trace-identities';
 import { registerDeriveCommand } from './contract-derive-command';
+import { withProjectInvocationInText } from '../project-sungen-invocation';
 
 const MARK: Record<string, string> = {
   match: '✓', strengthened: '↑', proposed: '+', 'hash-changed': '⚖', 'oracle-weakened': '✗', 'target-changed': '✗', 'assertion-lost': '✗',
@@ -44,7 +45,8 @@ function generateCommand(unit: { name: string; dir: string }): string {
 }
 
 function printVerdict(v: ContractVerdict, reportFile: string, generate: string): void {
-  const L = console.log;
+  // The approve / --accept-opaque / generate lines as this project runs sungen (#963).
+  const L = (line: string): void => console.log(withProjectInvocationInText(line, process.cwd()));
   const head = v.verdict === 'pass' ? '✓ PASS' : v.verdict === 'review'
     ? '⚖ REVIEW — changed, not weaker. Exit 0 here, but review blocks `sungen delivery` until QA re-approves' : '✗ FAIL';
   L('');
@@ -124,7 +126,8 @@ export function registerContractCommand(program: Command): void {
         console.log(`\n✓ Approved ${r.approved.length} scenario(s)${r.removed.length ? `, removed ${r.removed.length}` : ''} → ${path.relative(process.cwd(), r.lockPath)} (decision ${r.decisionId})`);
         console.log('  Commit the lock and the decision through review: until they are in git HEAD, `sungen contract check` reports contract.lock-uncommitted.\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.exit(1);
       }
     });

package/src/cli/commands/delivery.ts

@@ -17,6 +17,7 @@ import { mergeFeatureAndSpec } from '../../exporters/scenario-merger';
 import {
   buildTestCaseRows,
   buildSummary,
+  deliverableBasename,
   renderCsv,
   writeCsv,
 } from '../../exporters/csv-exporter';
@@ -41,11 +42,16 @@ import { MatrixFinding } from '../../exporters/matrix/types';
 import { applyManualCarry, ManualCarryReport, PriorManualResults, readPriorManualResults } from '../../exporters/matrix/carry-manual-results';
 import { formatTestOutcome, resultTotals } from '../../exporters/matrix/result-totals';
 import { readCapabilities } from '../../harness/capability';
+import { splitFeatureBlocks } from '../../contract/free-feature-blocks';
 import { processIO } from '../../decisions/human-confirmation';
 import { DeliveryDecisionGate } from '../../harness/gates/delivery-decision-gate';
 import { runDeliveryDecisionStep } from '../../harness/gates/delivery-decision-step';
 import { deliverableGateOverrides, InRunAcceptance } from '../../harness/gates/gate-override-report';
 import { ChecklistUnit, renderChecklist, unitChecklist } from '../../harness/gates/delivery-checklist';
+import { withProjectInvocationInText } from '../project-sungen-invocation';
+import { freeRunCommand, freeRunHasResults, generatedSubdir, plainRunCommand } from '../run-command-hints';
+import { isHandWritten } from '../../harness/parse';
+import { FREE_RUN_DIR } from '../../contract/trace/trace-run-record';
 
 const COLOR = {
   reset: '\x1b[0m',
@@ -101,14 +107,30 @@ function makeTarget(screen: string, featureBaseName: string, kind: UnitKind): De
 }
 
 /**
- * List all `.feature` files inside a screen/flow/api unit as separate targets.
- * Returns empty array when the directory has no features yet.
+ * A derived `*.free.feature` none of whose scenarios QA has approved yet (every one still `@proposed`):
+ * a proposal, not a delivery unit — counted as one, it ended in "Not exported" (#939). Approving a
+ * scenario drops its tag (`contract approve`), and from then on the file is a unit like any other.
+ */
+function proposalOnly(featureFile: string): boolean {
+  if (!featureFile.endsWith('.free.feature')) return false;
+  try {
+    // No scenario block at all (empty, or not Gherkin) is not a proposal: it stays listed and the preflight names it.
+    const blocks = splitFeatureBlocks(fs.readFileSync(featureFile, 'utf8'));
+    return blocks.length > 0 && blocks.every((b) => b.proposed);
+  } catch {
+    return false;   // unreadable: listed, so the preflight names the problem
+  }
+}
+
+/**
+ * List all `.feature` files inside a screen/flow/api unit as separate targets — a proposal-only
+ * free feature excepted. Returns empty array when the directory has no features yet.
  */
 function listFeatureTargets(cwd: string, screen: string, kind: UnitKind): DeliveryTarget[] {
   const featuresDir = path.join(cwd, 'qa', qaParent(kind), screen, 'features');
   if (!fs.existsSync(featuresDir)) return [];
   return fs.readdirSync(featuresDir)
-    .filter((f) => f.endsWith('.feature'))
+    .filter((f) => f.endsWith('.feature') && !proposalOnly(path.join(featuresDir, f)))
     .map((f) => makeTarget(screen, f.slice(0, -'.feature'.length), kind))
     .sort((a, b) => a.featureBaseName.localeCompare(b.featureBaseName));
 }
@@ -169,8 +191,7 @@ function qaDir(cwd: string, target: DeliveryTarget): string {
 // dashboard snapshot builder loads the identical contract (shared + unit merge).
 
 function generatedDir(cwd: string, target: DeliveryTarget): string {
-  const sub = target.kind === 'flow' ? path.join('flows', target.screen) : target.kind === 'api' ? path.join('api', target.screen) : target.screen;
-  return path.join(cwd, 'specs', 'generated', sub);
+  return path.join(cwd, generatedSubdir(target.kind, target.screen));
 }
 
 // ----------------------------------------------------------------------------
@@ -233,6 +254,9 @@ export function runPreflight(cwd: string, target: DeliveryTarget): PreflightChec
   const selectorsFile = path.join(base, 'selectors', `${target.featureBaseName}.yaml`);
   const specFile = path.join(genBase, `${target.featureBaseName}.spec.ts`);
   const resultsFile = resolveResultsPath(cwd, target);
+  // A derived `*.free.feature` is implemented by hand-written tests (DOS-14.8): no selectors, never compiled,
+  // run with the project's free-test config into its own outputDir — so its hints are that run's (#964).
+  const free = isHandWritten([], featureFile);
 
   const featureOk = checkFeatureReal(featureFile);
   // test-data is only REQUIRED when the feature actually references a
@@ -243,9 +267,9 @@ export function runPreflight(cwd: string, target: DeliveryTarget): PreflightChec
     ? checkTestDataHasVars(testDataFile)
     : true;
   // API units have no DOM → no selectors; the catalog (apis.yaml) is the contract. N/A, not missing.
-  const selectorsOk = target.kind === 'api' ? true : checkSelectorsHasEntries(selectorsFile, target.featureBaseName);
-  const specOk = fs.existsSync(specFile);
-  const resultsOk = resultsFile !== null;
+  const selectorsOk = target.kind === 'api' || free ? true : checkSelectorsHasEntries(selectorsFile, target.featureBaseName);
+  const specOk = free || fs.existsSync(specFile);
+  const resultsOk = free ? freeRunHasResults(cwd) : resultsFile !== null;
 
   const label = target.isFlow ? `flow/${target.featureBaseName}` : target.featureBaseName;
   const missing: string[] = [];
@@ -267,13 +291,15 @@ export function runPreflight(cwd: string, target: DeliveryTarget): PreflightChec
     missing.push(`compiled .spec.ts missing (optional — needed to run): ${path.relative(cwd, specFile)}`);
     suggestions.push(`sungen generate --${target.kind === 'flow' ? 'flow' : target.kind === 'api' ? 'api' : 'screen'} ${target.screen}`);
   }
-  if (!resultsOk) {
+  if (!resultsOk && free) {
+    missing.push(`free-test results missing (optional): ${FREE_RUN_DIR}/`);
+    suggestions.push(freeRunCommand(cwd));
+  } else if (!resultsOk) {
     const env = process.env.SUNGEN_ENV;
     const envSuffix = env ? `.${env}` : '';
     missing.push(`test-result${envSuffix}.json missing (optional)`);
     const genRel = path.relative(cwd, genBase);
-    const envPrefix = env ? `SUNGEN_ENV=${env} ` : '';
-    suggestions.push(`${envPrefix}PLAYWRIGHT_JSON_OUTPUT_NAME=${genRel}/${target.featureBaseName}-test-result.json npx playwright test ${genRel}/${target.featureBaseName}.spec.ts`);
+    suggestions.push(plainRunCommand(genRel, target.featureBaseName, env));
   }
 
   return {
@@ -731,11 +757,13 @@ async function exportMatrixTarget(
   // counted, so this line, the workbook's totals and the summary table all agree (#891). A file
   // that cannot be read is reported where it matters — when it would be overwritten.
   const format = opts.format ?? 'xlsx';
+  // A draft (DRAFT banner) is written to its own `…-testcases.DRAFT.<ext>`, never onto the official file (#965).
+  const draft = model.manifest.approvalState === 'draft';
   let prior: PriorManualResults | null = null;
   let priorError: Error | null = null;
   try { prior = await readPriorManualResults(deliverableXlsxPath(cwd, paths.unit)); }
-  // A CSV-only export overwrites no workbook, so an unreadable one only means "nothing to carry".
-  catch (e) { if (format !== 'csv') priorError = e as Error; }
+  // A CSV-only export or a draft overwrites no official workbook, so an unreadable one only means "nothing to carry".
+  catch (e) { if (format !== 'csv' && !draft) priorError = e as Error; }
   applyManualCarry(model, prior);
   model.gateOverrides = deliverableGateOverrides(decisions?.overridesFor(qaDir(cwd, target)) ?? [], hasReview(model.findings), decisions?.acceptedInRun);
 
@@ -785,6 +813,9 @@ async function exportMatrixTarget(
   const failed = model.items.reduce((a, i) => a + i.resultCounts.failed, 0);
   const written = [xlsxPath, csvPath].filter((p): p is string => !!p).map((p) => path.relative(cwd, p));
   for (const rel of written) log(`  ${COLOR.green}→ ${rel}${COLOR.reset}`);
+  if (draft) {
+    log(`  ${COLOR.yellow}draft only — not a deliverable:${COLOR.reset} it carries the DRAFT banner, and the official ${deliverableBasename(paths.unit)} file was neither written nor changed.`);
+  }
   if (manualCarry) printManualCarry(manualCarry);
   return {
     label: paths.label,
@@ -912,7 +943,8 @@ async function printDeliveryChecklist(cwd: string, targets: DeliveryTarget[], ac
   const rows: Array<{ label: string; boxes: Awaited<ReturnType<typeof unitChecklist>> }> = [];
   for (const u of units.values()) rows.push({ label: u.label, boxes: await unitChecklist(cwd, u, accepted) });
   log('');
-  for (const line of renderChecklist(rows)) log(line);
+  // Each box's fix command as this project runs sungen (#963).
+  for (const line of renderChecklist(rows)) log(withProjectInvocationInText(line, cwd));
 }
 
 // ----------------------------------------------------------------------------
@@ -931,7 +963,7 @@ export function registerDeliveryCommand(program: Command): void {
     .option('--full', 'Alias of --legacy')
     .option('--check', 'Matrix gates only — validate the delivery map, write nothing')
     .option('--approve [ids]', 'Approve proposed groups (all, or a comma-separated id list) + stamp fingerprints')
-    .option('--preview', 'Render the matrix despite review-required findings (DRAFT watermark)')
+    .option('--preview', 'Render the matrix despite review-required findings — a DRAFT (watermarked) written to <unit>-testcases.DRAFT.*, never onto the official file')
     .option('--format <format>', 'Matrix output format: xlsx (default) | csv | both', 'xlsx')
     .option('--accept-in-run', 'Deliver despite gate-overrides/waivers/approvals recorded during the run (decision.in-run) — a human confirms on a terminal')
     .action(async (names: string[], options: {
@@ -1025,7 +1057,8 @@ export function registerDeliveryCommand(program: Command): void {
         }
         if (options.approve === undefined) {
           const gate = await runDeliveryDecisionStep({
-            projectRoot: cwd, acceptInRun: !!options.acceptInRun, io: processIO(), log,
+            // The accept-in-run command and its refusal as this project runs sungen (#963).
+            projectRoot: cwd, acceptInRun: !!options.acceptInRun, io: processIO(), log: (line) => log(withProjectInvocationInText(line, cwd)),
             // --preview / --check soften only the matrix export; --legacy has no draft mode, so it always needs one.
             requireTrustedAudit: !!(options.legacy || options.full) || (!options.preview && !options.check),
             refs: toExport.map((t) => ({ label: t.isFlow ? `flow/${t.featureBaseName}` : t.featureBaseName, unitName: t.screen, unitDir: qaDir(cwd, t), resultsPath: resolveResultsPath(cwd, t) })),

package/src/cli/commands/gate.ts

@@ -3,6 +3,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { runGate, renderGate, GatePhase } from '../../harness/journey';
 import { findUnitDir } from '../resolve-unit';
+import { withProjectInvocationInText } from '../project-sungen-invocation';
 
 
 const PHASES: GatePhase[] = ['create', 'run', 'deliver'];
@@ -24,7 +25,7 @@ export function registerGateCommand(program: Command): void {
 
         const verdict = runGate(process.cwd(), name, phase);
         if (options.json) console.log(JSON.stringify(verdict, null, 2));
-        else console.log(renderGate(verdict));
+        else console.log(withProjectInvocationInText(renderGate(verdict), process.cwd()));   // waive / sign-off hints as the project runs sungen (#963)
 
         // Exit 2 on HALT — usable in CI / the orchestration loop to block the next phase.
         process.exit(verdict.status === 'halt' ? 2 : 0);

package/src/cli/commands/generate.ts

@@ -8,6 +8,7 @@ import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities, writeCapabilities, driverMeta, loadDriverCatalog } from '../../harness/capability';
 import { isHandWritten } from '../../harness/parse';
+import { generatedSubdir, plainRunCommand } from '../run-command-hints';
 
 /**
  * Find .feature files recursively in a directory
@@ -255,8 +256,18 @@ export function registerGenerateCommand(program: Command): void {
           if (shown.length < ddWarnings.length) console.log(`   … and ${ddWarnings.length - shown.length} more (run with -v to list all)`);
         }
 
-        const nextStep = platform === 'mobile' ? 'npm run test:mobile' : 'npx playwright test --ui';
-        console.log(`Next step: ${nextStep}\n`);
+        // Never the interactive `--ui` (#939): an agent cannot drive it, and run-test is what records the results.
+        const unit = screenName || flowName || apiName;
+        const nextStep = platform === 'mobile' ? 'npm run test:mobile' : unit ? `/sungen:run-test ${unit}` : 'npx playwright test';
+        console.log(`Next step: ${nextStep}`);
+        // The plain run writes each feature's results where `sungen next` and `sungen delivery` read them (#964) —
+        // a bare `npx playwright test` wrote them to the config's default file, which neither reads.
+        if (platform !== 'mobile' && unit) {
+          const genRel = generatedSubdir(apiName ? 'api' : flowName ? 'flow' : 'screen', unit);
+          console.log('   or the plain run — it writes the results file `sungen next` and `sungen delivery` read:');
+          for (const f of featureFiles) console.log(`     ${plainRunCommand(genRel, path.basename(f, '.feature'))}`);
+        }
+        console.log('');
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);
         process.exit(1);

package/src/cli/commands/journey.ts

@@ -5,6 +5,7 @@ import { reportSlug } from '../../harness/unit-paths';
 import { findUnitDir } from '../resolve-unit';
 import { answerPendingMigration, decideWithConfirmation, DECIDE_KINDS, signoffWithConfirmation, waiveWithConfirmation } from '../../decisions/confirmed-decision-commands';
 import { processIO } from '../../decisions/human-confirmation';
+import { withProjectInvocationInText } from '../project-sungen-invocation';
 
 const collect = (value: string, previous: string[]): string[] => [...previous, value];
 
@@ -77,12 +78,13 @@ export function registerJourneyCommand(program: Command): void {
           console.log(JSON.stringify(report, null, 2));
         } else {
           console.log('');
-          console.log(board);
+          console.log(withProjectInvocationInText(board, process.cwd()));
           console.log(`  Board: ${written ? path.relative(process.cwd(), written) : '(not written — read-only checkout)'}`);
           console.log('');
         }
       } 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.exit(1);
       }
     });

package/src/cli/commands/next.ts

@@ -9,9 +9,13 @@
  *   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); 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).
+ *                                     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';
@@ -22,7 +26,10 @@ 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 } from '../project-sungen-invocation';
+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 }> {
@@ -38,15 +45,24 @@ function allUnits(cwd: string): Array<{ name: string; kind: UnitState['kind']; d
   return out;
 }
 
-/** Steps as text, each `sungen …` command as this project runs it (#939); `--json` keeps them canonical. */
+/** 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} ${withProjectInvocation(st.command, cwd)}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}`);
-    console.log(`     ${st.because}`);
+    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('');
@@ -61,7 +77,7 @@ function render(s: UnitState, cwd: string): 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'} — ${s.auditNotCounted.reason}`);
+  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}`);
@@ -69,6 +85,8 @@ function render(s: UnitState, cwd: string): void {
   L('');
   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. */
@@ -99,6 +117,8 @@ function caseView(s: UnitState, cwd: string, unitDir: string, id: string, json:
   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('');
 }
 
@@ -136,7 +156,8 @@ export function registerNextCommand(program: Command): void {
           });
         }
         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, cwd);

package/src/cli/commands/triage.ts

@@ -1,6 +1,7 @@
 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';
@@ -47,7 +48,7 @@ export function registerTriageCommand(program: Command): void {
     .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) | test-defect | environment (a human types a confirmation on a TTY)')
+    .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(async (o: TriageOptions) => {
@@ -82,11 +83,12 @@ export function registerTriageCommand(program: Command): void {
         }
         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    sungen triage --${unit.kind === 'api' ? 'api' : 'screen'} ${name} --case <id> --as product|test-defect|environment --reason "…"`);
+          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

@@ -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';
@@ -70,9 +72,11 @@ export function registerUpdateCommand(program: Command): void {
       '--tag <dist-tag>',
       '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(

package/src/cli/index.ts

@@ -45,6 +45,7 @@ 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.
@@ -60,6 +61,8 @@ async function main() {
   // 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')
@@ -130,6 +133,7 @@ registerSetupMobileEnvCommand(program);
   // 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

@@ -8,6 +8,9 @@
  *
  *   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
@@ -27,6 +30,23 @@ export function withProjectInvocation(command: string, projectRoot: string): str
   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];

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
+  }
+}