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

package/dist/hooks/hand-back-core.js

@@ -98,9 +98,13 @@ function attachCliHandBack(argv, cwd) {
 }
 // --- the hook-shaped core -----------------------------------------------------------------------
 const MARK = { do: '→', blocked: '⛔', optional: '○', decide: '⚖' };
-/** `sungen next` rendered compactly for an agent's context; commands as `root` runs sungen. */
+/**
+ * `sungen next` rendered compactly for an agent's context; commands — the step's own and those quoted in
+ * its reason (#966) — as `root` runs sungen, the way `sungen next` prints them.
+ */
 function formatSteps(steps, max = 4, root) {
-    return steps.slice(0, max).map((st) => `  ${MARK[st.kind]} ${root ? (0, project_sungen_invocation_1.withProjectInvocation)(st.command, root) : st.command}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${st.because}`);
+    const asRun = (text) => (root ? (0, project_sungen_invocation_1.withProjectInvocationInText)(text, root) : text);
+    return steps.slice(0, max).map((st) => `  ${MARK[st.kind]} ${asRun(st.command)}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${asRun(st.because)}`);
 }
 /** The unit a session is on (a named one when it exists, else the nearest) and its derived state. */
 function locateUnitState(ctx, preferred) {
@@ -118,7 +122,7 @@ function run(input, ctx) {
     return {
         status: 'context',
         output: [`${handBackLine(found.unit.name, (0, project_sungen_invocation_1.sungenInvocation)(found.root))} — derived from what the project holds now:`, ...formatSteps(found.state.steps, 4, found.root),
-            ...(0, waiting_for_you_block_1.waitingForYouLines)(found.state.humanActions, found.root, found.state.humanActionsHeldBy)].join('\n'),
+            ...(0, waiting_for_you_block_1.waitingForYouLines)(found.state.humanActions, found.root, found.state.humanActionsHeldBy, found.state.humanActionsHeldByCommand)].join('\n'),
     };
 }
 //# sourceMappingURL=hand-back-core.js.map

package/dist/hooks/hand-back-core.js.map

@@ -1 +1 @@
-{"version":3,"file":"hand-back-core.js","sourceRoot":"","sources":["../../src/hooks/hand-back-core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hand-back-core.js","sourceRoot":"","sources":["../../src/hooks/hand-back-core.ts"],"names":[],"mappings":"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"}

package/dist/hooks/session-start-unit-state-hook.js

@@ -50,7 +50,7 @@ exports.sessionStartUnitStateHook = {
             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):`,
             ...(0, hand_back_core_1.formatSteps)(state.steps, 4, root),
-            ...(0, waiting_for_you_block_1.waitingForYouLines)(state.humanActions, root, state.humanActionsHeldBy),
+            ...(0, waiting_for_you_block_1.waitingForYouLines)(state.humanActions, root, state.humanActionsHeldBy, state.humanActionsHeldByCommand),
             input.source === 'compact' ? 'Context was compacted: re-read the unit\'s files before acting on them.' : '',
             others > 0 ? `Working on another unit? Ask \`${sungen} next <unit>\` (or \`${sungen} next\` for all).` : '',
         ];

package/dist/hooks/session-start-unit-state-hook.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-start-unit-state-hook.js","sourceRoot":"","sources":["../../src/hooks/session-start-unit-state-hook.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session-start-unit-state-hook.js","sourceRoot":"","sources":["../../src/hooks/session-start-unit-state-hook.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.3.0-alpha.7",
+  "version": "3.3.0-alpha.8",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -40,8 +40,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.3.0-alpha.7",
-    "@sungen/driver-ui": "3.3.0-alpha.7",
+    "@sungen/driver-data-factory": "3.3.0-alpha.8",
+    "@sungen/driver-ui": "3.3.0-alpha.8",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/case-triage-hint.ts

@@ -0,0 +1,31 @@
+/**
+ * `sungen next <unit> --case <id>` for a red that needs triage (#966): how to classify it, as commands.
+ * When a blocking unit step (a stale audit, say) holds the frontier, the case's own triage step is not
+ * offered — the view said "needs triage" and named nothing to run. Now it lists, after the steps:
+ *
+ *   held by a step above   sungen triage (every red of the run) · /sungen:run-test --ids <id> (re-run, which
+ *                          triages its own run) · the by-hand `--case <id> --as …` form
+ *   triage step offered    the by-hand form only (the step above already names `sungen triage`)
+ * Commands as this project runs sungen (#939, #963).
+ */
+import type { TestCaseState } from '../graph/test-case-state-shape';
+import type { NextStep, UnitState } from '../harness/next-step';
+import { withProjectInvocation } from './project-sungen-invocation';
+
+export function caseTriageLines(s: UnitState, tc: TestCaseState, steps: readonly NextStep[], cwd: string): string[] {
+  const flag = s.kind === 'api' ? '--api' : '--screen';
+  const byHand = [
+    `    → ${withProjectInvocation(`sungen triage ${flag} ${s.unit} --case ${tc.id} --as product|test-defect|environment --reason "…"`, cwd)}`,
+    "       by hand — test-defect and environment are a human's call, typed on a terminal; product anyone may record",
+  ];
+  if (steps.some((st) => st.nodeId === 'tc.triage')) return ['  or classify it by hand:', ...byHand];
+  const one = steps.length === 1;
+  return [
+    steps.length ? `  then, once the step${one ? '' : 's'} above clear${one ? 's' : ''}, classify this red:` : '  classify this red:',
+    `    → ${withProjectInvocation(`sungen triage ${flag} ${s.unit}`, cwd)}`,
+    '       classifies every red of the latest run',
+    `    → /sungen:run-test ${s.unit}${tc.unstableId ? '' : ` --ids ${tc.id}`}`,
+    '       or re-run it first — run-test triages its own run',
+    ...byHand,
+  ];
+}

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;
@@ -28,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';
@@ -47,6 +48,10 @@ 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',
@@ -186,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));
 }
 
 // ----------------------------------------------------------------------------
@@ -250,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
@@ -260,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[] = [];
@@ -284,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 {
@@ -748,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);
 
@@ -802,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,
@@ -929,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));
 }
 
 // ----------------------------------------------------------------------------
@@ -948,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: {
@@ -1042,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
@@ -257,8 +258,16 @@ export function registerGenerateCommand(program: Command): void {
 
         // 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}   (or the plain run: npx playwright test)` : 'npx playwright test';
-        console.log(`Next step: ${nextStep}\n`);
+        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

@@ -10,8 +10,10 @@
  *                                     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}]` (#954); every older
- *                                     field is kept. stdout is the payload alone (#660, #836)
+ *                                     `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).
  */
@@ -24,8 +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 }> {
@@ -41,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('');
@@ -64,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}`);
@@ -72,7 +85,7 @@ function render(s: UnitState, cwd: string): void {
   L('');
   renderSteps(s.steps, cwd);
   L('');
-  const waiting = waitingForYouLines(s.humanActions, cwd, s.humanActionsHeldBy);
+  const waiting = waitingForYouLines(s.humanActions, cwd, s.humanActionsHeldBy, s.humanActionsHeldByCommand);
   if (waiting.length) { for (const line of waiting) L(line); L(''); }
 }
 
@@ -104,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('');
 }
 
@@ -141,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/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
+  }
+}