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

package/src/cli/waiting-for-you-block.ts

@@ -1,23 +1,27 @@
 /**
  * The "Waiting for you" block (#954) — every pending human-only action of a unit, as ready-to-copy
  * commands with the reason under each. One renderer for the three places that show it: `sungen next`
- * (text) and the Stop / SessionStart hook context. Commands as the project runs sungen (`npx sungen`
- * with a local install, #939); `--json` keeps them canonical in `humanActions`. An instruction (a commit
- * through review, a `git checkout --`) is marked `✎ … (by hand, not a command)`, never shown as one to copy.
+ * (text) and the Stop / SessionStart hook context. Commands — and those inside a reason (#963) — as the
+ * project runs sungen (`npx sungen` with a local install, #939); `--json` keeps `command` canonical in
+ * `humanActions` and adds `rendered`. An instruction (a commit through review, a `git checkout --`) is
+ * marked `✎ … (by hand, not a command)`, never shown as one to copy.
  */
 import type { HumanAction } from '../graph/human-action';
-import { withProjectInvocation } from './project-sungen-invocation';
+import { withProjectInvocation, withProjectInvocationInText } from './project-sungen-invocation';
 
 export const WAITING_FOR_YOU_HEAD = '⏳ Waiting for you — a human runs these in their own terminal (in Claude Code: ! <command>); an agent never runs them:';
 
 /**
- * The block's lines (indented two spaces), or none when nothing waits for a human. `heldBy`: the title
- * of the blocking step that cut the frontier — the block is not exhaustive then, and says what holds the rest.
+ * The block's lines (indented two spaces), or none when nothing waits for a human and nothing holds the
+ * rest. `heldBy`: the title of the blocking step that cut the frontier — the block is not exhaustive then,
+ * and says what holds the rest, with that step's command (`heldByCommand`) when given (#966). A held
+ * block with no item of its own still says so, rather than vanishing (a QA read "nothing is waiting").
  */
-export function waitingForYouLines(actions: readonly HumanAction[] | undefined, projectRoot: string, heldBy?: string): string[] {
-  if (!actions?.length) return [];
+export function waitingForYouLines(actions: readonly HumanAction[] | undefined, projectRoot: string, heldBy?: string, heldByCommand?: string): string[] {
+  const holds = heldBy ? `"${heldBy}" clears${heldByCommand ? ` (the step above: ${withProjectInvocationInText(heldByCommand, projectRoot)})` : ''}` : '';
+  if (!actions?.length) return heldBy ? [`  ⏳ Waiting for you: nothing yet — more appear once ${holds}.`] : [];
   return [`  ${WAITING_FOR_YOU_HEAD}`, ...actions.flatMap((a) => [
     a.instruction ? `     ✎ ${a.command}   (by hand, not a command)` : `     ${withProjectInvocation(a.command, projectRoot)}`,
-    `       ${a.reason}`,
-  ]), ...(heldBy ? [`     More appear once "${heldBy}" clears.`] : [])];
+    `       ${withProjectInvocationInText(a.reason, projectRoot)}`,
+  ]), ...(heldBy ? [`     More appear once ${holds}.`] : [])];
 }

package/src/exporters/csv-exporter.ts

@@ -439,12 +439,12 @@ export function renderCsv(summary: ScreenSummary, rows: TestCaseRow[], specLink:
  * multi-locale delivery aggregator. Pass an empty string to force the
  * base (no suffix) variant.
  */
-export function writeCsv(cwd: string, screen: string, csvContent: string, locale?: string | null): string {
+export function writeCsv(cwd: string, screen: string, csvContent: string, locale?: string | null, opts: DeliverableFileOptions = {}): string {
   const outDir = path.join(cwd, 'qa', 'deliverables');
   if (!fs.existsSync(outDir)) {
     fs.mkdirSync(outDir, { recursive: true });
   }
-  const outPath = path.join(outDir, `${deliverableBasename(screen, locale)}.csv`);
+  const outPath = path.join(outDir, `${deliverableBasename(screen, locale, opts)}.csv`);
   fs.writeFileSync(outPath, csvContent, 'utf-8');
   return outPath;
 }
@@ -455,8 +455,16 @@ export function writeCsv(cwd: string, screen: string, csvContent: string, locale
  * locale is given (or `SUNGEN_ENV` is set and no explicit override). Pass
  * `null` / empty string to force the base variant.
  */
-export function deliverableBasename(screen: string, locale?: string | null): string {
+export function deliverableBasename(screen: string, locale?: string | null, opts: DeliverableFileOptions = {}): string {
   const effective = locale !== undefined ? locale : process.env.SUNGEN_ENV;
-  return effective ? `${screen}-testcases.${effective}` : `${screen}-testcases`;
+  return `${effective ? `${screen}-testcases.${effective}` : `${screen}-testcases`}${opts.draft ? DRAFT_MARK : ''}`;
 }
 
+/**
+ * A DRAFT render (a watermarked `--preview`) is written beside the official deliverable, never onto it
+ * (#965): `<screen>-testcases[.env].DRAFT.<ext>`. Readers of `qa/deliverables/` skip it (isDraftDeliverable).
+ */
+export interface DeliverableFileOptions { draft?: boolean }
+export const DRAFT_MARK = '.DRAFT';
+export const isDraftDeliverable = (fileName: string): boolean => /\.DRAFT\.[^.]+$/.test(fileName);
+

package/src/exporters/matrix/export.ts

@@ -169,7 +169,12 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
 
 export type MatrixFormat = 'xlsx' | 'csv' | 'both';
 
-/** Render + write the requested format(s). Caller has already enforced the gate policy. */
+/**
+ * Render + write the requested format(s). Caller has already enforced the gate policy. A draft (the
+ * matrix is not approved for official delivery: it carries the DRAFT banner) goes to its own
+ * `…-testcases.DRAFT.<ext>` and never overwrites the official file (#965); the tester's Manual results
+ * are still carried from the official workbook when it can be read.
+ */
 export async function writeMatrixDeliverables(
   paths: MatrixTargetPaths,
   model: MatrixModel,
@@ -179,23 +184,25 @@ export async function writeMatrixDeliverables(
 ): Promise<{ csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport }> {
   const out: { csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport } = {};
   const xlsx = format === 'xlsx' || format === 'both';
+  const draft = model.manifest.approvalState === 'draft';
   // Read the workbook about to be overwritten BEFORE writing anything, so the tester's Manual
   // results survive (#756) and a refusal leaves no half-written target behind.
   // A CSV-only export overwrites no workbook, so an unreadable one is no reason to refuse it — but a
   // readable one still holds the Manual results the CSV should show.
+  // A draft overwrites nothing official either, so an unreadable official workbook is no reason to refuse it.
   const prior = priorRead !== undefined ? priorRead
-    : xlsx ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit))
+    : xlsx && !draft ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit))
       : await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit)).catch(() => null);
   // Into the model first: the CSV, every cached total and roll-up, and the caller's summary
   // all read it (#891).
   applyManualCarry(model, prior);
   if (format === 'csv' || format === 'both') {
-    out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
+    out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model), undefined, { draft });
   }
   if (xlsx) {
     const wb = renderMatrixXlsx(model, getPackageVersion());
     out.manualCarry = carryManualResults(wb, model, prior);
-    out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb);
+    out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb, undefined, { draft });
   }
   return out;
 }

package/src/exporters/xlsx-exporter.ts

@@ -18,7 +18,7 @@ import ExcelJS from 'exceljs';
 import JSZip from 'jszip';
 import { ApiCatalogEntry, ApiDetailRow, ScreenSummary, TestCaseRow } from './types';
 import { getPackageVersion } from './package-info';
-import { deliverableBasename } from './csv-exporter';
+import { deliverableBasename, DeliverableFileOptions } from './csv-exporter';
 import {
   extractApiCallOrder,
   extractCasesDataset,
@@ -114,8 +114,8 @@ export function buildApiDetailRows(
  * to force the base (no suffix) variant.
  */
 /** Where `writeXlsx` puts a unit's workbook — shared so a reader targets the identical file. */
-export function deliverableXlsxPath(cwd: string, screen: string, locale?: string | null): string {
-  return path.join(cwd, 'qa', 'deliverables', `${deliverableBasename(screen, locale)}.xlsx`);
+export function deliverableXlsxPath(cwd: string, screen: string, locale?: string | null, opts: DeliverableFileOptions = {}): string {
+  return path.join(cwd, 'qa', 'deliverables', `${deliverableBasename(screen, locale, opts)}.xlsx`);
 }
 
 export async function writeXlsx(
@@ -123,8 +123,9 @@ export async function writeXlsx(
   screen: string,
   wb: ExcelJS.Workbook,
   locale?: string | null,
+  opts: DeliverableFileOptions = {},
 ): Promise<string> {
-  const outPath = deliverableXlsxPath(cwd, screen, locale);
+  const outPath = deliverableXlsxPath(cwd, screen, locale, opts);
   const outDir = path.dirname(outPath);
   if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
   const buffer = await wb.xlsx.writeBuffer();

package/src/graph/evaluate-graph.ts

@@ -84,12 +84,14 @@ export function evaluateGraph(
  * rules of its own: each offered step's node says what a person runs (its `human` hook), and a decide
  * step without one is its own command. `cut`: an open blocking node ended the walk, so only what does
  * not depend on it is offered (a hard verdict that surfaces past the cut), and the board's asks that
- * need the unit past it (sign-off, accept-in-run) wait; `heldBy` is that node's title.
+ * need the unit past it (sign-off, accept-in-run) wait; `heldBy` is that node's title and `heldByCommand`
+ * its offered step's command (#966: "More appear once …" names what to run).
  */
-export function evaluateHumanActions(nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[]): { actions: HumanAction[]; cut: boolean; heldBy?: string } {
+export function evaluateHumanActions(nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[]): { actions: HumanAction[]; cut: boolean; heldBy?: string; heldByCommand?: string } {
   const { offered, cut, cutBy } = walkFrontier(nodes, s, tcStates, {});
   const actions = offered.flatMap(({ node, step, cases }) => (node.human
     ? node.human(s, step, cases)
     : step.kind === 'decide' ? [{ command: step.command, reason: step.because, kind: 'decide' as const }] : []));
-  return { actions, cut, ...(cutBy ? { heldBy: cutBy.title } : {}) };
+  const heldByCommand = cutBy ? offered.find((o) => o.node === cutBy)?.step.command : undefined;
+  return { actions, cut, ...(cutBy ? { heldBy: cutBy.title } : {}), ...(heldByCommand ? { heldByCommand } : {}) };
 }

package/src/graph/unit-artifact-probes.ts

@@ -9,6 +9,7 @@ import { parse as parseYaml } from 'yaml';
 import { featureFilesFor } from '../harness/unit-paths';
 import { readTextFile } from '../harness/read-text';
 import { loadPlaywrightReport } from '../exporters/playwright-report-parser';
+import { isDraftDeliverable } from '../exporters/csv-exporter';
 
 /** `<f>-test-result[.<os>][.<env>].json` — a mobile run writes the OS into the name, an env run the env (#868). */
 export const RESULT_FILE = /-test-result(?:\.[^.]+)*\.json$/;
@@ -72,6 +73,7 @@ export function countFailedResults(resultFiles: string[]): number {
 
 export function hasDeliverableFor(projectRoot: string, slug: string): boolean {
   try {
-    return fs.readdirSync(path.join(projectRoot, 'qa', 'deliverables')).some((f) => f.startsWith(`${slug}-`));
+    // A `--preview` DRAFT is not a deliverable (#965).
+    return fs.readdirSync(path.join(projectRoot, 'qa', 'deliverables')).some((f) => f.startsWith(`${slug}-`) && !isDraftDeliverable(f));
   } catch { return false; }                                    // nothing exported yet
 }

package/src/harness/gates/audit-report-verification.ts

@@ -58,6 +58,8 @@ function provenanceField(r: Record<string, unknown>, key: 'sungenVersion' | 'cat
 const writtenBy = (r: Record<string, unknown>): string | null => provenanceField(r, 'sungenVersion');
 
 export interface RulesStamp { catalogHash: string | null; rulesHash: string | null }
+/** rulesProblem's answer for a report that records no rules (`provenance.catalogHash` / `rulesHash`): an older sungen wrote it. */
+export const NO_RULES_STAMP = 'audited by an older sungen, which did not record the rules it scored with';
 /** What getProvenance writes when it could not read a catalog — never a match, on either side. */
 const UNKNOWN = 'unknown';
 
@@ -67,7 +69,7 @@ const UNKNOWN = 'unknown';
  * unknown == unknown proves nothing.
  */
 export function rulesProblem(was: RulesStamp, now: RulesStamp): string | null {
-  if (!was.catalogHash || !was.rulesHash) return 'it does not say which rules scored it (no provenance.catalogHash / rulesHash)';
+  if (!was.catalogHash || !was.rulesHash) return NO_RULES_STAMP;
   if ([was.catalogHash, was.rulesHash].includes(UNKNOWN)) return 'the rules that scored it are unknown (provenance says "unknown")';
   if (!now.catalogHash || !now.rulesHash || [now.catalogHash, now.rulesHash].includes(UNKNOWN)) return 'this sungen cannot read its own rules (catalog or rules hash unknown), so it trusts no report';
   if (was.catalogHash === now.catalogHash && was.rulesHash === now.rulesHash) return null;
@@ -162,7 +164,10 @@ export function verifyAuditReport(projectRoot: string, unit: string): AuditVerif
   }
   const stale: AuditVerification['problems'] = [];
   const rules = otherRules(r);
-  if (rules) stale.push({ code: 'rules-changed', message: `${writtenBy(r) ? `written by sungen ${writtenBy(r)}, ` : ''}${rules}` });
+  // A report from before the rules stamp reads in plain words, with the one command that clears it (#966).
+  if (rules) stale.push({ code: 'rules-changed', message: rules === NO_RULES_STAMP
+    ? `audited by an older sungen${writtenBy(r) ? ` (${writtenBy(r)})` : ''} — run \`sungen audit --screen ${unit}\` once`
+    : `${writtenBy(r) ? `written by sungen ${writtenBy(r)}, ` : ''}${rules}` });
   if (r.decisionsHash !== current) stale.push({ code: 'decisions-changed', message: 'the gate-override decisions changed since this audit' });
   if (!unitDir) return result('invalid', [{ code: 'unit-unresolved', message: `"${unit}" does not name exactly one unit, so the audit's inputs cannot be checked` }]);
   if (r.inputsHash !== auditInputsHash(unitDir, unit, r.decisionsHash as string)) {

package/src/harness/next-step.ts

@@ -106,6 +106,8 @@ export interface UnitState {
    * are listed (sign-off, accept-in-run and the first contract approval wait). Absent when nothing cuts.
    */
   humanActionsHeldBy?: string;
+  /** The canonical command of that blocking step (#966) — what clears the hold. */
+  humanActionsHeldByCommand?: string;
 }
 
 export interface ReadUnitStateOptions {
@@ -188,6 +190,7 @@ export function readUnitState(
   state.humanActions = [...graph.actions, ...boardHumanActions(projectRoot, unitDir, state, graph.cut)]
     .filter((a) => !seen.has(a.command) && Boolean(seen.add(a.command)));
   if (graph.heldBy) state.humanActionsHeldBy = graph.heldBy;
+  if (graph.heldByCommand) state.humanActionsHeldByCommand = graph.heldByCommand;
   return state;
 }
 

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

@@ -10,7 +10,7 @@
  * commander's preAction, so a usage error — which never reaches an action — and `main().catch`
  * ended in silence. The state now starts the moment parsing does; the action only refines it.
  */
-import { sungenInvocation, withProjectInvocation } from '../cli/project-sungen-invocation';
+import { sungenInvocation, withProjectInvocationInText } from '../cli/project-sungen-invocation';
 import { waitingForYouLines } from '../cli/waiting-for-you-block';
 import { resolveUnitCandidates } from '../cli/resolve-unit';
 import { readUnitState, NextStep, UnitState } from '../harness/next-step';
@@ -88,10 +88,14 @@ export function attachCliHandBack(argv: string[], cwd: string): { onAction: (nam
 
 const MARK: Record<NextStep['kind'], string> = { do: '→', blocked: '⛔', optional: '○', decide: '⚖' };
 
-/** `sungen next` rendered compactly for an agent's context; 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.
+ */
 export function formatSteps(steps: NextStep[], max = 4, root?: string): string[] {
+  const asRun = (text: string): string => (root ? withProjectInvocationInText(text, root) : text);
   return steps.slice(0, max).map((st) =>
-    `  ${MARK[st.kind]} ${root ? withProjectInvocation(st.command, root) : st.command}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${st.because}`);
+    `  ${MARK[st.kind]} ${asRun(st.command)}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${asRun(st.because)}`);
 }
 
 /** The unit a session is on (a named one when it exists, else the nearest) and its derived state. */
@@ -109,6 +113,6 @@ export function run(input: HookInput, ctx: HookContext): HookResult {
   return {
     status: 'context',
     output: [`${handBackLine(found.unit.name, sungenInvocation(found.root))} — derived from what the project holds now:`, ...formatSteps(found.state.steps, 4, found.root),
-      ...waitingForYouLines(found.state.humanActions, found.root, found.state.humanActionsHeldBy)].join('\n'),
+      ...waitingForYouLines(found.state.humanActions, found.root, found.state.humanActionsHeldBy, found.state.humanActionsHeldByCommand)].join('\n'),
   };
 }

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

@@ -50,7 +50,7 @@ export const sessionStartUnitStateHook: SungenHook = {
       state.audit ? `Audit: ${state.audit.overall}/10 [${state.audit.gateStatus}] · ${state.audit.findings.length} finding(s).` : '',
       `Next (\`${sungen} next ${unit.name}\`, derived from the project state):`,
       ...formatSteps(state.steps, 4, root),
-      ...waitingForYouLines(state.humanActions, root, state.humanActionsHeldBy),
+      ...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).` : '',
     ];