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

package/src/decisions/human-confirmation.ts

@@ -0,0 +1,119 @@
+/**
+ * Typed human confirmation (DOS-13.4, red-team #3; review phase 03 M5).
+ *
+ * `journey --waive`, `journey --decide`, `delivery --accept-in-run` record or accept decisions that
+ * relax a gate, so a person must type a confirmation on a terminal:
+ *   - no TTY (an agent's shell, a pipe, CI) → refuse and print the exact command for a human to run;
+ *     piped stdin is not a TTY, so piping the phrase in never counts
+ *   - the prompt and the answer go through the controlling terminal (`/dev/tty`), not stdin/stderr,
+ *     so a redirected or wrapped stream neither sees nor answers it
+ *   - the phrase carries a NONCE drawn per prompt, so an answer cannot be scripted from the refusal
+ *     message: the printed command never contains it (it does not exist until the prompt is shown)
+ * This is a hard floor under Claude Code (the PreToolUse guard also denies agent writes to
+ * qa/**\/decisions/**) and a soft barrier elsewhere; git-HEAD comparison and the in-run rule remain.
+ */
+import { randomBytes } from 'crypto';
+import * as fs from 'fs';
+import * as readline from 'readline';
+import * as tty from 'tty';
+
+export interface ConfirmationIO {
+  input: NodeJS.ReadableStream & { isTTY?: boolean };
+  output: NodeJS.WritableStream;
+  /** The CLI's real terminal: prompt on `/dev/tty` (opened only when a confirmation is asked). */
+  controllingTerminal?: boolean;
+}
+
+export class HumanConfirmationRefused extends Error {
+  constructor(message: string, public readonly command?: string) {
+    super(message);
+    this.name = 'HumanConfirmationRefused';
+  }
+}
+
+/** The CLI's streams: stdin decides whether a human is there; the prompt itself uses /dev/tty. */
+export const processIO = (): ConfirmationIO => ({ input: process.stdin, output: process.stderr, controllingTerminal: true });
+export const isInteractive = (io: ConfirmationIO): boolean => io.input.isTTY === true;
+
+export function shellQuote(arg: string): string {
+  return /^[A-Za-z0-9_./:=@%+-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+export const formatCommand = (argv: string[]): string => argv.map(shellQuote).join(' ');
+
+interface Terminal { input: NodeJS.ReadableStream; output: NodeJS.WritableStream; close(): void }
+
+/** The terminal to talk to a human on, or null when there is none. */
+function openTerminal(io: ConfirmationIO): Terminal | null {
+  if (!isInteractive(io)) return null;
+  if (!io.controllingTerminal || process.platform === 'win32') return { input: io.input, output: io.output, close: () => undefined };
+  let rfd = -1;
+  let wfd = -1;
+  try {
+    rfd = fs.openSync('/dev/tty', 'r');
+    wfd = fs.openSync('/dev/tty', 'w');
+    const input = new tty.ReadStream(rfd);
+    const output = new tty.WriteStream(wfd);
+    return { input, output, close: () => { input.destroy(); output.destroy(); } };
+  } catch {
+    for (const fd of [rfd, wfd]) if (fd >= 0) { try { fs.closeSync(fd); } catch { /* already closed */ } }
+    return null;   // no controlling terminal: not a human at a keyboard
+  }
+}
+
+/** One line from the human, or null on EOF. */
+function askLine(t: Terminal, prompt: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: t.input, output: t.output, terminal: false });
+    let settled = false;
+    const done = (v: string | null): void => { if (!settled) { settled = true; resolve(v); rl.close(); } };
+    rl.on('close', () => done(null));
+    rl.question(prompt, (answer) => done(answer));
+  });
+}
+
+function refuseWithoutTty(what: string, command: string): HumanConfirmationRefused {
+  return new HumanConfirmationRefused(
+    `Refused: ${what} needs a human at a terminal to type a confirmation, and this run has no TTY.\n`
+    + `  Nothing was recorded. Run this yourself in a terminal:\n    ${command}`,
+    command,
+  );
+}
+
+/** Refuse up front, before any state is read or written, when no human is at a terminal. */
+export function requireInteractive(io: ConfirmationIO, what: string, command: string): void {
+  if (!isInteractive(io)) throw refuseWithoutTty(what, command);
+}
+
+/** A fresh, hard-to-guess suffix for one prompt. */
+export const confirmationNonce = (): string => randomBytes(3).toString('hex').toUpperCase();
+
+export async function requireTypedConfirmation(opts: {
+  what: string; phrase: string; command: string; summary: string[]; io: ConfirmationIO;
+}): Promise<void> {
+  const t = openTerminal(opts.io);
+  if (!t) throw refuseWithoutTty(opts.what, opts.command);
+  try {
+    const expected = `${opts.phrase} ${confirmationNonce()}`;
+    t.output.write(`\nAbout to ${opts.what}:\n${opts.summary.map((l) => `  ${l}`).join('\n')}\n`);
+    const answer = await askLine(t, `Type "${expected}" to confirm (anything else cancels): `);
+    if ((answer ?? '').trim() !== expected) {
+      throw new HumanConfirmationRefused(`Cancelled: the confirmation did not match the phrase shown. Nothing was recorded.`, opts.command);
+    }
+  } finally {
+    t.close();
+  }
+}
+
+/** A leftover write-ahead sentinel: the human answers REVERT or KEEP. Never answered for them. */
+export async function askMigrationChoice(opts: { detail: string; command: string; io: ConfirmationIO }): Promise<'REVERT' | 'KEEP'> {
+  const t = openTerminal(opts.io);
+  if (!t) throw refuseWithoutTty('answering an interrupted migration (REVERT or KEEP)', opts.command);
+  try {
+    t.output.write(`\n${opts.detail}\n`);
+    const answer = ((await askLine(t, 'Type REVERT (restore every file it lists) or KEEP (keep the new files): ')) ?? '').trim().toUpperCase();
+    if (answer === 'REVERT' || answer === 'KEEP') return answer;
+    throw new HumanConfirmationRefused('Cancelled: answer REVERT or KEEP. Nothing was changed.', opts.command);
+  } finally {
+    t.close();
+  }
+}

package/src/decisions/legacy-waiver-migration.ts

@@ -0,0 +1,135 @@
+/**
+ * Waivers move from `.sungen/journey/<slug>.state.json` into the decision layer (DOS-13.5, red-team
+ * #2) — without laundering an agent-forged waiver into a hash-valid decision (review H1).
+ *
+ * The state file is agent-writable, so a legacy waiver is TRUSTED only when its record equals the
+ * one committed in git HEAD (a commit went through review; a local edit did not). Per obligation,
+ * with L = the legacy waiver and D = the decision in force:
+ *   L same as D                 → nothing to do (same reason against the same evidence)
+ *   L untrusted                 → not imported, not counted; needs-you says UNTRUSTED and how to confirm it
+ *   L trusted, no D             → import L (`where: migrated`, idempotent by content id)
+ *   L trusted, newer than D     → import L superseding D — an `at` in the future never counts as newer
+ *   L trusted, not newer than D → D wins; the dual-write corrects the legacy file
+ * The import runs ONCE per unit: when nothing untrusted remains, a marker is written and from then on
+ * the legacy file is only a dual-write target (so the previous CLI still reads the waivers), never a source.
+ *
+ * plan is read-only, so the board is the same whether or not the writes succeed. commit writes under
+ * the write-ahead sentinel; only an unwritable checkout is tolerated silently — a conflict is raised.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { withMigrationSentinel } from '../basis/migration-sentinel';
+import { appendDecision, AppendResult } from './append-decision';
+import { canonicalJson, computeDecisionId } from './decision-identity';
+import { decisionsDirFor, unitDecisionScope } from './decision-file';
+import { DecisionDraft } from './decision-schema';
+import { gitUserName } from './decision-source';
+import { committedJson } from './git-head-trust';
+import { formatCommand } from './human-confirmation';
+import { readDecisions } from './read-decisions';
+import { asLegacyWaiver, effectiveWaiverEntries, isLegacyWaiver, LegacyWaiver, sameWaiver, waiverDraft } from './waiver-decisions';
+
+export interface UntrustedWaiver { obligation: string; waiver: LegacyWaiver }
+
+export interface WaiverSyncPlan {
+  scope: string | null;
+  /** obligation → waiver in force (legacy shape): what the board counts. */
+  waivers: Record<string, LegacyWaiver>;
+  untrusted: UntrustedWaiver[];
+  /** What the dual-write puts back in the legacy file: legacy key order, unknown records kept verbatim. */
+  stateWaivers: Record<string, unknown>;
+  imports: DecisionDraft[];
+  /** Write the import marker on commit: nothing untrusted is left to decide. */
+  markDone: boolean;
+}
+
+export const importMarkerPath = (projectRoot: string, slug: string): string =>
+  path.join(projectRoot, '.sungen', 'migrations', `${slug}.waivers-imported.json`);
+
+const asRecord = (v: unknown): Record<string, unknown> => (v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {});
+const newer = (w: LegacyWaiver, validFrom: string): boolean => {
+  const at = Date.parse(w.at);
+  return at > Date.parse(validFrom) && at <= Date.now();
+};
+
+export function planWaiverSync(projectRoot: string, unit: string, slug: string, statePath: string, legacy: unknown): WaiverSyncPlan {
+  const legacyWaivers = asRecord(legacy);
+  const scope = unitDecisionScope(projectRoot, unit);
+  const inForce = scope ? effectiveWaiverEntries(readDecisions(projectRoot, scope, { kind: 'waiver' }).entries) : new Map();
+  const stateWaivers: Record<string, unknown> = { ...legacyWaivers };
+  const waivers: Record<string, LegacyWaiver> = {};
+  const untrusted: UntrustedWaiver[] = [];
+  const imports: DecisionDraft[] = [];
+
+  if (scope && fs.existsSync(importMarkerPath(projectRoot, slug))) {
+    for (const [ob, d] of inForce) stateWaivers[ob] = waivers[ob] = asLegacyWaiver(d);
+    return { scope, waivers, untrusted, stateWaivers, imports, markDone: false };
+  }
+
+  const head = asRecord(asRecord(committedJson(projectRoot, statePath)).waivers);
+  for (const [ob, w] of Object.entries(legacyWaivers)) {
+    if (!isLegacyWaiver(w)) continue;                                 // unreadable record: kept in the file, never counted
+    const d = inForce.get(ob);
+    if (d && sameWaiver(asLegacyWaiver(d), w)) { waivers[ob] = w; continue; }
+    if (!(ob in head) || canonicalJson(head[ob]) !== canonicalJson(w)) { untrusted.push({ obligation: ob, waiver: w }); continue; }
+    if (d && !newer(w, d.valid_from)) { stateWaivers[ob] = waivers[ob] = asLegacyWaiver(d); continue; }
+    if (scope) imports.push(waiverDraft(ob, w, { by: 'unknown', where: 'migrated' }, d?.id));
+    waivers[ob] = w;
+  }
+  for (const [ob, d] of inForce) if (!(ob in waivers)) stateWaivers[ob] = waivers[ob] = asLegacyWaiver(d);
+  return { scope, waivers, untrusted, stateWaivers, imports, markDone: !!scope && untrusted.length === 0 };
+}
+
+/** The needs-you line for a waiver that is not in git HEAD: not counted, and how a human confirms it. */
+export function untrustedWaiverText(unit: string, slug: string, title: string, u: UntrustedWaiver): string {
+  const confirm = formatCommand(['sungen', 'journey', '--screen', unit, '--waive', u.obligation, '--reason', u.waiver.reason]);
+  return `⚠️ Waiver on "${title}" is UNTRUSTED — not counted (decision.in-run: it is in .sungen/journey/${slug}.state.json `
+    + `but not in git HEAD). If it is yours, confirm it on a terminal: ${confirm}`;
+}
+
+const UNWRITABLE = new Set(['EACCES', 'EROFS', 'ENOSPC', 'EPERM']);
+
+function writeFile(file: string, text: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text, 'utf-8');
+}
+
+/**
+ * Persist a plan: imports, the dual-written legacy file, the import marker. Returns false when the
+ * checkout cannot be written (read-only, full disk); any other failure — a decision that does not
+ * verify, a migration in progress or interrupted — is raised, never swallowed.
+ */
+export function commitWaiverSync(projectRoot: string, unit: string, slug: string, plan: WaiverSyncPlan, statePath: string, stateText: string): boolean {
+  const marker = importMarkerPath(projectRoot, slug);
+  const writeMarker = plan.markDone && !fs.existsSync(marker);
+  const markerText = (ids: string[]) => `${JSON.stringify({ schema: 1, unit, importedAt: new Date().toISOString(), imported: ids }, null, 2)}\n`;
+  try {
+    if (!plan.scope || plan.imports.length === 0) {
+      writeFile(statePath, stateText);
+      if (writeMarker) writeFile(marker, markerText([]));
+      return true;
+    }
+    const scope = plan.scope;
+    const dir = decisionsDirFor(projectRoot, scope);
+    const targets = plan.imports.map((d) => path.join(dir, `${computeDecisionId(d, scope)}.yaml`));
+    withMigrationSentinel(projectRoot, unit, slug, `import ${plan.imports.length} legacy waiver(s) into the decision layer`,
+      [statePath, ...(writeMarker ? [marker] : []), ...targets], () => {
+        const ids = plan.imports.map((d) => appendDecision(projectRoot, scope, d).entry.id);
+        writeFile(statePath, stateText);
+        if (writeMarker) writeFile(marker, markerText(ids));
+      });
+    return true;
+  } catch (err) {
+    if (UNWRITABLE.has((err as NodeJS.ErrnoException)?.code ?? '')) return false;
+    throw err;
+  }
+}
+
+/** Record a waiver given now on the CLI; supersedes the waiver in force for that obligation, if any. */
+export function recordWaiver(projectRoot: string, unit: string, obligation: string, w: LegacyWaiver): AppendResult {
+  const scope = unitDecisionScope(projectRoot, unit);
+  if (!scope) throw new Error(`Cannot record a waiver: "${unit}" does not name exactly one unit under qa/screens, qa/flows or qa/api.`);
+  const current = effectiveWaiverEntries(readDecisions(projectRoot, scope, { kind: 'waiver' }).entries).get(obligation);
+  if (current && sameWaiver(asLegacyWaiver(current), w)) return { status: 'already-recorded', entry: current, path: current.path };
+  return appendDecision(projectRoot, scope, waiverDraft(obligation, w, { by: gitUserName(projectRoot), where: 'cli' }, current?.id));
+}

package/src/decisions/read-decisions.ts

@@ -0,0 +1,61 @@
+/**
+ * Read the decisions of one scope (DOS-13.1 – 13.3). Best-effort by contract: a missing directory
+ * reads as empty, a bad file becomes a `problem` — a read-only or half-broken checkout never throws.
+ *
+ * Only entries that verify against themselves take effect; an entry whose content no longer matches
+ * its id, or whose entry_hash no longer matches the entry, is reported and ignored (trust nothing
+ * written). Computed on read, never stored:
+ *   - `superseded_by` — the latest visible entry that names this one in `supersedes`
+ *   - `stale`         — with `auditHash` given: `evidence_hash ≠ auditHash` (the waiver rule, DOS-13.5)
+ * `asOf` hides entries whose `valid_from` is later, so a later superseder does not supersede yet.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { DecisionEntry, DecisionKind } from './decision-schema';
+import { DecisionProblem, decisionsDirFor, verifyDecisionFile } from './decision-file';
+
+export interface ReadDecision extends DecisionEntry {
+  scope: string;
+  path: string;
+  superseded_by?: string;
+  stale?: boolean;
+}
+
+export interface ReadDecisionsOptions { asOf?: string; auditHash?: string; kind?: DecisionKind }
+export interface ReadDecisionsResult { entries: ReadDecision[]; problems: DecisionProblem[] }
+
+const byTime = (a: DecisionEntry, b: DecisionEntry): number =>
+  Date.parse(a.valid_from) - Date.parse(b.valid_from) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+export function readDecisions(projectRoot: string, scope: string, opts: ReadDecisionsOptions = {}): ReadDecisionsResult {
+  const problems: DecisionProblem[] = [];
+  let dir: string;
+  let names: string[];
+  try {
+    dir = decisionsDirFor(projectRoot, scope);
+    names = fs.readdirSync(dir).filter((f) => f.endsWith('.yaml')).sort();
+  } catch {
+    return { entries: [], problems };
+  }
+
+  const cutoff = opts.asOf ? Date.parse(opts.asOf) : Infinity;
+  const entries: ReadDecision[] = [];
+  for (const name of names) {
+    const file = path.join(dir, name);
+    const v = verifyDecisionFile(file, scope);
+    if (v.problem) { problems.push(v.problem); continue; }
+    if (Date.parse(v.entry.valid_from) > cutoff) continue;
+    entries.push({ ...v.entry, scope, path: file });
+  }
+  entries.sort(byTime);
+
+  const byId = new Map(entries.map((e) => [e.id, e]));
+  for (const e of entries) {
+    const target = e.supersedes ? byId.get(e.supersedes) : undefined;
+    if (target) target.superseded_by = e.id;   // ascending time: the latest superseder wins
+  }
+  if (opts.auditHash !== undefined) {
+    for (const e of entries) if (e.evidence_hash !== undefined) e.stale = e.evidence_hash !== opts.auditHash;
+  }
+  return { entries: opts.kind ? entries.filter((e) => e.kind === opts.kind) : entries, problems };
+}

package/src/decisions/viewpoint-baseline-adapter.ts

@@ -0,0 +1,74 @@
+/**
+ * The accepted viewpoint baseline, seen as decisions — read-only (DOS-11.4; storage moves in P1).
+ *
+ * `sungen audit --accept-viewpoint` records `.sungen/viewpoint-baseline.json` (harness/viewpoint-
+ * baseline.ts). Each unit in it is projected as one `viewpoint-acceptance` decision, without moving or
+ * rewriting anything: no file is written here, ever.
+ *
+ * The file is agent-writable, so a unit is projected only while its record equals the one committed
+ * in git HEAD (review H1) — otherwise it would turn a local edit into a hash-valid decision. Anything
+ * not projected is reported: an `untrusted` unit, an `invalid` unit record, an `unreadable` file.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { canonicalJson, sealDecision } from './decision-identity';
+import { DecisionProblem, PROJECT_SCOPE } from './decision-file';
+import { committedJson } from './git-head-trust';
+import { ReadDecision } from './read-decisions';
+
+/** Same location harness/viewpoint-baseline.ts writes. */
+const baselineFile = (projectRoot: string): string => path.join(projectRoot, '.sungen', 'viewpoint-baseline.json');
+const EPOCH = '1970-01-01T00:00:00.000Z';
+
+interface UnitRecord { hash: string; ids: string[]; recordedAt?: string; fileHash?: string }
+
+function isUnitRecord(v: unknown): v is UnitRecord {
+  const r = v as UnitRecord;
+  return !!r && typeof r === 'object' && typeof r.hash === 'string' && Array.isArray(r.ids) && r.ids.every((i) => typeof i === 'string');
+}
+const unitsOf = (raw: unknown): Record<string, unknown> | null => {
+  const u = (raw as { units?: unknown } | null)?.units;
+  return u && typeof u === 'object' && !Array.isArray(u) ? u as Record<string, unknown> : null;
+};
+
+function project(unit: string, r: UnitRecord, file: string): ReadDecision {
+  const at = typeof r.recordedAt === 'string' && !Number.isNaN(Date.parse(r.recordedAt)) ? new Date(r.recordedAt).toISOString() : EPOCH;
+  const entry = sealDecision({
+    kind: 'viewpoint-acceptance',
+    anchors: [],
+    text: `Accept the test-viewpoint declaration of ${unit} as the baseline`,
+    reason: 'Accepted with sungen audit --accept-viewpoint (legacy .sungen/viewpoint-baseline.json)',
+    payload: { unit, hash: r.hash, ids: r.ids, ...(typeof r.fileHash === 'string' ? { fileHash: r.fileHash } : {}) },
+    source: { by: 'unknown', where: 'legacy:viewpoint-baseline' },
+    valid_from: at,
+    visibility: 'internal',
+  }, PROJECT_SCOPE);
+  return { ...entry, scope: PROJECT_SCOPE, path: file };
+}
+
+export function viewpointAcceptanceDecisions(projectRoot: string): { entries: ReadDecision[]; problems: DecisionProblem[] } {
+  const file = baselineFile(projectRoot);
+  const entries: ReadDecision[] = [];
+  const problems: DecisionProblem[] = [];
+  if (!fs.existsSync(file)) return { entries, problems };
+  let units: Record<string, unknown> | null;
+  try {
+    units = unitsOf(JSON.parse(fs.readFileSync(file, 'utf8')));
+  } catch (err) {
+    problems.push({ path: file, code: 'unreadable', message: `viewpoint baseline cannot be read: ${err instanceof Error ? err.message : String(err)}` });
+    return { entries, problems };
+  }
+  if (!units) return { entries, problems: [{ path: file, code: 'unreadable', message: 'viewpoint baseline has no `units` mapping' }] };
+
+  const committed = unitsOf(committedJson(projectRoot, file)) ?? {};
+  for (const unit of Object.keys(units).sort()) {
+    const r = units[unit];
+    if (!isUnitRecord(r)) { problems.push({ path: file, code: 'invalid', message: `viewpoint baseline record for ${unit} is malformed; not projected` }); continue; }
+    if (!(unit in committed) || canonicalJson(committed[unit]) !== canonicalJson(r)) {
+      problems.push({ path: file, code: 'untrusted', message: `viewpoint baseline for ${unit} is not the one in git HEAD — not taken as a decision (decision.in-run); commit it through review` });
+      continue;
+    }
+    entries.push(project(unit, r, file));
+  }
+  return { entries, problems };
+}

package/src/decisions/waiver-decisions.ts

@@ -0,0 +1,56 @@
+/**
+ * Journey waivers as decisions (DOS-13.5).
+ *
+ * A waiver entry is `kind: waiver`, `payload.obligation`, `evidence_hash` = the audit hash the waiver
+ * was given against (legacy `auditHashAtWaive`). Per obligation the waiver in force is the latest
+ * (by `valid_from`) entry that nothing supersedes. Whether it COUNTS is the old rule, unchanged: only
+ * while `evidence_hash` equals the current audit hash; otherwise it is STALE and goes back to a human.
+ */
+import { DecisionDraft, DecisionEntry, DecisionSource } from './decision-schema';
+import { ReadDecision } from './read-decisions';
+
+/** The legacy shape in `.sungen/journey/<slug>.state.json` — still dual-written for one release. */
+export interface LegacyWaiver { reason: string; at: string; auditHashAtWaive: string }
+
+const norm = (s: string): string => s.normalize('NFC').replace(/\r\n?/g, '\n').trim();
+
+export function isLegacyWaiver(w: unknown): w is LegacyWaiver {
+  const x = w as LegacyWaiver;
+  return !!x && typeof x === 'object' && typeof x.reason === 'string' && norm(x.reason).length > 0
+    && typeof x.at === 'string' && !Number.isNaN(Date.parse(x.at)) && typeof x.auditHashAtWaive === 'string';
+}
+
+/** Same decision: same reason against the same evidence (the time it was recorded does not matter). */
+export function sameWaiver(a: LegacyWaiver, b: LegacyWaiver): boolean {
+  return norm(a.reason) === norm(b.reason) && a.auditHashAtWaive === b.auditHashAtWaive;
+}
+
+export function waiverDraft(obligation: string, w: LegacyWaiver, source: DecisionSource, supersedes?: string): DecisionDraft {
+  return {
+    kind: 'waiver',
+    anchors: [],
+    text: `Waive ${obligation}`,
+    reason: w.reason,
+    payload: { obligation },
+    source,
+    valid_from: w.at,
+    ...(supersedes ? { supersedes } : {}),
+    visibility: 'internal',
+    evidence_hash: w.auditHashAtWaive,
+  };
+}
+
+export function asLegacyWaiver(e: DecisionEntry): LegacyWaiver {
+  return { reason: e.reason, at: e.valid_from, auditHashAtWaive: e.evidence_hash ?? '' };
+}
+
+/** obligation → the waiver entry in force. `entries` come from readDecisions (sorted by time). */
+export function effectiveWaiverEntries(entries: ReadDecision[]): Map<string, ReadDecision> {
+  const out = new Map<string, ReadDecision>();
+  for (const e of entries) {
+    const ob = e.payload?.obligation;
+    if (e.kind !== 'waiver' || e.superseded_by || typeof ob !== 'string') continue;
+    out.set(ob, e);   // ascending time: the latest wins
+  }
+  return out;
+}

package/src/exporters/csv-exporter.ts

@@ -32,6 +32,10 @@ import { formatEnv } from './run-environment';
 export interface BuildCsvInput {
   screen: string;
   featureName: string;
+  /** The exact command that regenerates this unit (`sungen generate --flow checkout`). `screen`
+   *  is the deliverable label — the FEATURE basename, `flow/<x>` for a flow — so a note built from
+   *  it named a command that fails (#880). */
+  generateCommand?: string;
   /** URL path for the screen/flow entry point — concatenated onto baseURL
    *  when building the Test Environment column so QA can see the exact URL
    *  the test targets. */
@@ -207,7 +211,7 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
       // No execution record AND no compiled test → Manual if @manual, else genuinely not compiled.
       testResult = testcaseType === 'Manual' ? 'Pending' : 'N/A';
       if (testcaseType !== 'Manual') {
-        note = 'Scenario not compiled — re-run `sungen generate --screen ' + input.screen + '`';
+        note = `Scenario not compiled — re-run \`${input.generateCommand ?? `sungen generate --screen ${input.screen}`}\``;
       } else {
         // Why the case is manual — the `# MANUAL: …` comment — so the tester reading the
         // deliverable knows what blocks automation (#810). Empty when no reason is written.

package/src/exporters/feature-parser.ts

@@ -117,6 +117,7 @@ export function parseFeatureMetadata(featureFilePath: string): FeatureMetadata {
     referencedVars: extractReferencedVars(sc, extractTestcaseType([...parsed.tags, ...sc.tags]) === 'Manual'),
     orderedSteps: classifySteps(sc),
     comments: sc.comments,
+    hookType: sc.hookType,
   }));
 
   return {
@@ -136,6 +137,17 @@ export function isStepsBaseScenario(sc: ScenarioMetadata): boolean {
   return !!sc.stepsName;
 }
 
+/**
+ * A hook (`@beforeAll` / `@afterEach` / `@afterAll`) — setup or teardown around the tests, compiled
+ * to `test.beforeAll()` etc. Read from the scenario's OWN tag (the parser's `hookType`), never from
+ * the feature+scenario tag union. It is not a test case: counted as one, it blocked the matrix at
+ * Gate A (a hook carries no VP id, as the gherkin skill tells authors) and showed in the legacy
+ * workbook and the dashboard as a "Not compiled" row (#880).
+ */
+export function isHookScenario(sc: ScenarioMetadata): boolean {
+  return !!sc.hookType;
+}
+
 /**
  * Return true if this is the default scaffold sample scenario (not real).
  */