@sun-asterisk/sungen 3.2.24-beta.1 → 3.2.24-beta.3

package/src/harness/flow-contract.ts

@@ -27,6 +27,21 @@ import { parse as parseYaml } from 'yaml';
 import { ScenarioInfo } from './parse';
 import { readTextFile } from './read-text';
 
+/** One declared flow of the use case: a branch point, its own steps, its own outcome. */
+export interface FlowDecl {
+  /** The flow id as the use-case document numbers it — `BF`, `AF01`, `EF03`. */
+  id: string;
+  /** Where it leaves the basic flow (`BF step 2`). Omitted for the basic flow itself. */
+  branchFrom?: string;
+  /** Its OWN outcome/postcondition — what is different about where this flow ends. */
+  outcome?: string;
+  status: 'covered' | 'deferred' | 'pending-clarification' | 'out-of-scope';
+  /** Why, for anything other than `covered` — a deferral with no reason is a silent gap. */
+  reason?: string;
+}
+
+const FLOW_STATUSES = new Set(['covered', 'deferred', 'pending-clarification', 'out-of-scope']);
+
 export interface FlowContract {
   goal: string;
   actor?: string;
@@ -43,6 +58,18 @@ export interface FlowContract {
   /** Journey phases this flow declares. Default [HP, ER, EH]; UI is allowed but
    *  never demanded (presentation is the balance axis's business, not coverage's). */
   phases: string[];
+  /**
+   * The use case's declared flow inventory — the answer to "how many flows does this use
+   * case HAVE?". `phases:` alone cannot answer it: a phase is present as soon as ONE
+   * scenario carries it, so a fifteen-flow use case with three scenarios reported full
+   * phase coverage. With an inventory, coverage is measured per DECLARED FLOW and a flow
+   * nobody wrote is a named gap instead of a silent absence (#595).
+   *
+   * `status` is what keeps a gap honest: every flow ends up `covered`, `deferred`,
+   * `pending-clarification` (an open question for the BA — the behaviour is not agreed yet,
+   * so no scenario can be right) or `out-of-scope`. Absent → `covered` is expected.
+   */
+  flows?: FlowDecl[];
   /** The mutated collection (cart, order, application …) — enables regression dims. */
   stateful?: string;
   budgets?: Record<string, number>;
@@ -117,6 +144,23 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
       successGuarantee: raw.successGuarantee !== undefined ? String(raw.successGuarantee) : (raw.success_guarantee !== undefined ? String(raw.success_guarantee) : undefined),
       minimalGuarantee: raw.minimalGuarantee !== undefined ? String(raw.minimalGuarantee) : (raw.minimal_guarantee !== undefined ? String(raw.minimal_guarantee) : undefined),
       phases,
+      flows: Array.isArray(raw.flows)
+        ? (raw.flows as Array<Record<string, unknown>>)
+            .filter((f) => f && typeof f === 'object' && f.id)
+            .map((f) => {
+              const status = String(f.status ?? 'covered').toLowerCase();
+              if (!FLOW_STATUSES.has(status)) {
+                errors.push(`flows[${String(f.id)}].status "${status}" is not one of covered|deferred|pending-clarification|out-of-scope`);
+              }
+              return {
+                id: String(f.id).toUpperCase(),
+                branchFrom: f.branchFrom !== undefined ? String(f.branchFrom) : (f.branch_from !== undefined ? String(f.branch_from) : undefined),
+                outcome: f.outcome !== undefined ? String(f.outcome) : undefined,
+                status: (FLOW_STATUSES.has(status) ? status : 'covered') as FlowDecl['status'],
+                reason: f.reason !== undefined ? String(f.reason) : undefined,
+              };
+            })
+        : undefined,
       stateful: raw.stateful !== undefined ? String(raw.stateful).toLowerCase() : undefined,
       budgets: (raw.budgets && typeof raw.budgets === 'object') ? raw.budgets as Record<string, number> : undefined,
       external: Array.isArray(raw.external)
@@ -130,7 +174,9 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
         : undefined,
       golden: raw.golden === true,
     },
-    errors: [],
+    // Shape errors found while reading the inventory (a bad `status:`) are REPORTED with the
+    // contract, not swallowed — the contract is still usable, the typo is not silently ignored.
+    errors,
   };
 }
 
@@ -145,6 +191,22 @@ function touchesOutcome(s: ScenarioInfo, outcomeScreen: string): boolean {
   return namespacesInOrder(s).includes(outcomeScreen);
 }
 
+/**
+ * Does the scenario ARRIVE at the outcome, as opposed to merely naming it?
+ *
+ * A guard scenario asserts the outcome screen is *absent* (`[Complete:Title] header is hidden`)
+ * — the strongest thing it can say — so "the outcome namespace appears somewhere in the steps"
+ * counts it as reaching a screen it exists to prove unreachable.
+ */
+function reachesOutcome(s: ScenarioInfo, outcomeScreen: string): boolean {
+  // Per STEP, from the structured list — `stepsText` is one space-joined blob, so any negation
+  // anywhere in the scenario would suppress every positive assertion in it.
+  const steps = (s.steps ?? []).map((st) => st.text.toLowerCase());
+  if (steps.length === 0) return touchesOutcome(s, outcomeScreen);
+  return steps.some((t) => t.includes(`[${outcomeScreen}`)
+    && !/\b(is hidden|is not visible|does not exist|is absent|no longer)\b/.test(t));
+}
+
 /** Phase of a scenario: its declared phase token (FL-HP-001 / VP-FLOW-ER-02 / MS-EH-005)
  *  when present, else vocabulary detection. */
 export function phaseOf(s: ScenarioInfo, declared: string[]): string | null {
@@ -163,6 +225,101 @@ export function phaseOf(s: ScenarioInfo, declared: string[]): string | null {
   return null;
 }
 
+/** The flow id a scenario claims: the `AF02`/`EF11`/`BF` segment of its viewpoint id. */
+export function flowIdOf(s: ScenarioInfo, declaredPhases: string[]): string | null {
+  const tokens = new Set(declaredPhases.map(phaseToken));
+  for (const seg of (s.vpId ?? '').toUpperCase().split('-')) {
+    if (tokens.has(phaseToken(seg))) return seg;
+  }
+  return null;
+}
+
+export interface InventoryResult {
+  /** Declared → the scenarios claiming it. A declared flow with none is a NAMED gap. */
+  covered: Array<{ id: string; scenarios: string[] }>;
+  /** Declared `covered` but nothing written — the silent-absence case, now named. */
+  uncovered: FlowDecl[];
+  /** Declared with a non-covered status, carried into the report so it stays visible. */
+  accounted: FlowDecl[];
+  /** A scenario's flow id that the inventory never declares — an id invented for one
+   *  assertion (an "EF" that is really a success postcondition, an "AF" that is really a
+   *  content check on the basic path). */
+  undeclared: Array<{ id: string; scenario: string }>;
+  /** Covered declared flows / declared flows that OUGHT to be covered. */
+  ratio: number;
+}
+
+/**
+ * Coverage per DECLARED FLOW, which is not the same question as coverage per phase.
+ *
+ * A phase is "covered" the moment one scenario carries it, so a use case decomposed into
+ * fifteen flows reported `BF=✓ AF=✓ EF=✓ → 100%` on three scenarios. Reviewers reading the
+ * suite counted the flows instead and got a very different number (#595). When the contract
+ * declares its inventory, this measures the thing the reviewer measures — and every gap is
+ * named, which is what makes "no silent missing flow" checkable rather than aspirational.
+ */
+export function flowInventory(contract: FlowContract, scenarios: ScenarioInfo[]): InventoryResult | null {
+  if (!contract.flows || contract.flows.length === 0) return null;
+  const byId = new Map<string, string[]>();
+  const undeclared: Array<{ id: string; scenario: string }> = [];
+  const declaredIds = new Set(contract.flows.map((f) => f.id));
+  for (const s of scenarios) {
+    const id = flowIdOf(s, contract.phases);
+    if (!id) continue;
+    if (!declaredIds.has(id)) { undeclared.push({ id, scenario: s.name }); continue; }
+    byId.set(id, [...(byId.get(id) ?? []), s.name]);
+  }
+  const expected = contract.flows.filter((f) => f.status === 'covered');
+  const covered = expected.filter((f) => (byId.get(f.id) ?? []).length > 0)
+    .map((f) => ({ id: f.id, scenarios: byId.get(f.id)! }));
+  return {
+    covered,
+    uncovered: expected.filter((f) => (byId.get(f.id) ?? []).length === 0),
+    accounted: contract.flows.filter((f) => f.status !== 'covered'),
+    undeclared,
+    ratio: expected.length ? covered.length / expected.length : 1,
+  };
+}
+
+/**
+ * A phase id used for something that is not that kind of flow.
+ *
+ * Two shapes, both seen on a real suite that the phase check scored 100%:
+ *   - an `EF` scenario that REACHES the contract outcome. An exception flow is blocked by
+ *     definition; one that completes the journey is a success-path postcondition wearing an
+ *     exception's id ("the buffer does not survive a finalized registration").
+ *   - an `AF` scenario with no branch: it walks the basic path and asserts extra content on
+ *     it. An alternate flow needs a point where the actor does something else; without one it
+ *     is an assertion belonging to the basic flow ("the shared component renders the new-email
+ *     copy").
+ * Both inflate the flow count while adding no branch coverage, which is exactly what makes a
+ * suite look complete to the harness and thin to a reviewer.
+ */
+export function misfiledPhases(
+  contract: FlowContract, scenarios: ScenarioInfo[], basicPhase: string,
+): Array<{ scenario: string; id: string; why: string }> {
+  const out: Array<{ scenario: string; id: string; why: string }> = [];
+  const outcome = contract.outcome.screen;
+  for (const s of scenarios) {
+    const id = flowIdOf(s, contract.phases);
+    if (!id || phaseToken(id) === phaseToken(basicPhase)) continue;
+    const ph = phaseToken(id);
+    if (ph === 'EF' && reachesOutcome(s, outcome)) {
+      // An error-then-recover flow legitimately ends at the outcome — it is the recovery that
+      // is being proven, and a guard flow is blocked rather than "failed". Only a scenario with
+      // no failure and no block at all is misfiled.
+      const failed = /\b(error|invalid|duplicate|reject|fail|denied|blocked|expired|refuse|unauthenticat|unauthoriz|redirect|guard|without (?:a |an |the )?\w+|not skippable|forces? \w+ to restart)\w*/i.test(s.haystack);
+      if (!failed) {
+        out.push({ scenario: s.name, id, why: `reaches the outcome screen [${outcome}] and nothing in it fails — this is a success-path postcondition, not an exception flow` });
+      }
+    }
+    if (ph === 'AF' && !/\b(back|cancel|return|instead|abandon|second tab|another tab|skip|leave|exit|retry|edit)\w*/i.test(s.haystack)) {
+      out.push({ scenario: s.name, id, why: 'no branch point — it walks the basic path and asserts extra content on it, so the assertion belongs to the basic flow' });
+    }
+  }
+  return out;
+}
+
 /**
  * Verify the suite against the contract. Deterministic; a flow without a contract
  * returns hasContract:false and neutral values (the audit reports the checklist).

package/src/harness/next-step.ts

@@ -0,0 +1,237 @@
+/**
+ * "What now?" — one deterministic resolver over the project's own state.
+ *
+ * The next step used to be hardcoded per command, and only two of twenty-nine printed one at
+ * all. So a run that ended anywhere else ended in silence: `sungen capability add mock`
+ * finished with a blank line, the operator's agent had nothing telling it what remained, and the
+ * whole session stopped mid-workflow (#597).
+ *
+ * Hardcoding it in the other twenty-seven would repeat the mistake in bulk. What decides the
+ * next step is not which command just ran — it is what the project now HOLDS: the artifacts on
+ * disk, the audit report in `.sungen/reports/`, the accepted viewpoint baseline, the compiled
+ * spec, the run results. So this reads that state and derives the answer, and every command ends
+ * by pointing here. One place to be right, one place to test.
+ *
+ * Deterministic and read-only: same project state → same answer, no network, no writes.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { reportSlug, featureFilesFor } from './unit-paths';
+import { readTextFile } from './read-text';
+
+export interface NextStep {
+  /** The command to run, as the operator would type it. */
+  command: string;
+  /** Why it is next — stated so an agent can weigh it, not just obey it. */
+  because: string;
+  /** `blocked` steps are not runnable yet; they name what to resolve first. */
+  kind: 'do' | 'blocked' | 'optional';
+}
+
+export interface UnitState {
+  unit: string;
+  kind: 'screen' | 'flow' | 'api';
+  hasSpec: boolean;
+  hasViewpoint: boolean;
+  hasContract: boolean;
+  hasFlowInventory: boolean;
+  scenarioCount: number;
+  hasSelectors: boolean;
+  selectorsArePlaceholder: boolean;
+  compiled: boolean;
+  hasResults: boolean;
+  hasDeliverable: boolean;
+  audit?: {
+    overall: number;
+    gateStatus: string;
+    findings: string[];
+    viewpointBaselineStatus?: string;
+  };
+  steps: NextStep[];
+}
+
+const exists = (p: string): boolean => fs.existsSync(p);
+
+function readJson(p: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(readTextFile(p)) as Record<string, unknown>;
+  } catch {
+    return null;                                    // absent or unreadable — treated as "not run"
+  }
+}
+
+function countScenarios(unitDir: string, unit: string): number {
+  let n = 0;
+  for (const f of featureFilesFor(unitDir, unit)) {
+    const text = readTextFile(f) ?? '';
+    n += (text.match(/^\s*Scenario(?: Outline)?:/gm) ?? []).length;
+  }
+  return n;
+}
+
+/**
+ * Everything the resolver needs, read from disk. `unitId` is the catalog id
+ * (`<screen>` · `flows/<f>` · `api/<a>`); `unitDir` is its directory.
+ */
+export function readUnitState(
+  projectRoot: string, unitDir: string, unit: string, kind: UnitState['kind'],
+): UnitState {
+  const req = path.join(unitDir, 'requirements');
+  const slug = reportSlug(unit);
+  const audit = readJson(path.join(projectRoot, '.sungen', 'reports', `${slug}-audit.json`));
+  const selectorsDir = path.join(unitDir, 'selectors');
+  let selectorFiles: string[] = [];
+  try {
+    selectorFiles = fs.readdirSync(selectorsDir).filter((f) => f.endsWith('.yaml'));
+  } catch { /* api units carry no selectors */ }
+  const selectorText = selectorFiles.map((f) => readTextFile(path.join(selectorsDir, f)) ?? '').join('\n');
+  const contractPath = path.join(req, 'flow-contract.yaml');
+  const contractText = readTextFile(contractPath) ?? '';
+
+  const specDirs = [
+    path.join(projectRoot, 'specs', 'generated', 'flows', unit),
+    path.join(projectRoot, 'specs', 'generated', unit),
+  ];
+  const compiled = specDirs.some((d) => {
+    try {
+      return fs.readdirSync(d).some((f) => f.endsWith('.spec.ts'));
+    } catch { return false; }
+  });
+  const hasResults = specDirs.some((d) => {
+    try {
+      return fs.readdirSync(d).some((f) => f.endsWith('-test-result.json'));
+    } catch { return false; }
+  });
+  let hasDeliverable = false;
+  try {
+    hasDeliverable = fs.readdirSync(path.join(projectRoot, 'qa', 'deliverables'))
+      .some((f) => f.startsWith(`${slug}-`));
+  } catch { /* nothing exported yet */ }
+
+  const score = (audit?.score ?? {}) as { overall?: number };
+  const baseline = (audit?.viewpointBaseline ?? {}) as { status?: string };
+  const state: UnitState = {
+    unit, kind,
+    hasSpec: exists(path.join(req, 'spec.md')),
+    hasViewpoint: exists(path.join(req, 'test-viewpoint.md')),
+    hasContract: exists(contractPath),
+    // A contract WITHOUT `flows:` can only be scored per phase, which is a materially weaker
+    // claim — so it is part of the state, not a detail.
+    hasFlowInventory: /^\s*flows:\s*$/m.test(contractText),
+    scenarioCount: countScenarios(unitDir, unit),
+    hasSelectors: selectorFiles.length > 0,
+    // A scaffolded selector file exists but resolves nothing; treating it as "done" is what
+    // makes a run look further along than it is.
+    selectorsArePlaceholder: selectorFiles.length > 0
+      && (/TODO|PLACEHOLDER|REPLACE ME/i.test(selectorText) || selectorText.trim().length < 40),
+    compiled, hasResults, hasDeliverable,
+    audit: audit
+      ? {
+        overall: typeof score.overall === 'number' ? score.overall : 0,
+        gateStatus: String(audit.gateStatus ?? 'UNKNOWN'),
+        findings: Array.isArray(audit.findings) ? (audit.findings as string[]) : [],
+        viewpointBaselineStatus: baseline.status,
+      }
+      : undefined,
+    steps: [],
+  };
+  state.steps = deriveSteps(state);
+  return state;
+}
+
+/** The finding codes worth naming in a next step — each maps to a specific repair. */
+const REPAIRABLE = [
+  'FLOW-CONTRACT-MISSING', 'FLOW-INVENTORY-MISSING', 'FLOW-UNCOVERED', 'FLOW-UNDECLARED',
+  'FLOW-PHASE-MISFILED', 'FLOW-GUARANTEE-MISSING', 'FLOW-OUTCOME-UNPROVEN', 'CONTINUITY-ONE-SIDED',
+  'SPEC-RESTATED-UNVERIFIED', 'VIEWPOINT-GESTURE-SUBSTITUTED', 'SPEC-UNCOVERED', 'TRIGGER-UNCOVERED',
+  'VIEWPOINT-ITEM-MISSING', 'MANUAL-CODE-MISSING', 'MANUAL-AUTOMATABLE', 'DEPTH-DEFERRED',
+];
+
+/**
+ * The ordered answer. Earliest unmet precondition first, so the list reads as a path rather than
+ * a menu — and a `blocked` step names what to resolve instead of pretending it can run.
+ */
+export function deriveSteps(s: UnitState): NextStep[] {
+  const out: NextStep[] = [];
+  const design = s.kind === 'api' ? `/sungen:create-test ${s.unit}` : `/sungen:create-test ${s.unit}`;
+
+  if (!s.hasSpec && !s.hasViewpoint) {
+    out.push({
+      kind: 'blocked',
+      command: `write qa/${s.kind === 'screen' ? 'screens' : s.kind === 'flow' ? 'flows' : 'api'}/${s.unit}/requirements/spec.md`,
+      because: 'the unit has neither a spec nor a test-viewpoint, so there is nothing to generate FROM — generation without a source invents behaviour',
+    });
+    return out;
+  }
+  if (s.kind === 'flow' && !s.hasContract) {
+    out.push({
+      kind: 'blocked',
+      command: `author requirements/flow-contract.yaml, then ${design}`,
+      because: 'a flow with no contract is scored as a generic screen against page-type themes a journey cannot have (FLOW-CONTRACT-MISSING)',
+    });
+    return out;
+  }
+  if (s.scenarioCount === 0) {
+    out.push({ kind: 'do', command: design, because: 'no scenarios exist yet' });
+    return out;
+  }
+  if (s.kind === 'flow' && !s.hasFlowInventory) {
+    out.push({
+      kind: 'do',
+      command: `add \`flows:\` to requirements/flow-contract.yaml, then sungen audit --screen ${s.unit}`,
+      because: 'without the inventory, coverage is measured per PHASE — and a phase counts as covered as soon as one scenario carries it, so the number cannot tell you a flow is missing',
+    });
+  }
+  if (!s.audit) {
+    out.push({ kind: 'do', command: `sungen audit --screen ${s.unit}`, because: 'the suite has never been measured' });
+    return out;
+  }
+  if (s.audit.viewpointBaselineStatus === 'changed') {
+    out.push({
+      kind: 'do',
+      command: `sungen audit --screen ${s.unit} --accept-viewpoint`,
+      because: 'test-viewpoint.md changed since the accepted baseline, so the ledger and traceability axes are not evidence until you confirm the new declaration',
+    });
+  }
+  const repair = s.audit.findings
+    .map((f) => f.split(':')[0].trim())
+    .filter((code) => REPAIRABLE.includes(code));
+  if (repair.length > 0) {
+    out.push({
+      kind: 'do',
+      command: `repair, then sungen audit --screen ${s.unit}`,
+      because: `${repair.length} finding(s) name a specific repair: ${[...new Set(repair)].slice(0, 4).join(', ')}`,
+    });
+  }
+  if (s.audit.gateStatus === 'FAIL') {
+    out.push({
+      kind: 'blocked',
+      command: `repair the gate, then sungen audit --screen ${s.unit}`,
+      because: `the viewpoint gate is FAIL at ${s.audit.overall}/10 — running tests against a design that fails its own gate measures the wrong thing`,
+    });
+    return out;
+  }
+  if (s.kind !== 'api' && (!s.hasSelectors || s.selectorsArePlaceholder)) {
+    out.push({
+      kind: 'do',
+      command: `/sungen:run-test ${s.unit}`,
+      because: s.hasSelectors
+        ? 'the selector file is still a placeholder, so nothing resolves against a live page'
+        : 'no selectors exist yet — run-test generates them from the live page, compiles and auto-fixes',
+    });
+    return out;
+  }
+  if (!s.compiled) {
+    out.push({ kind: 'do', command: `sungen generate --${s.kind === 'flow' ? 'flow' : 'screen'} ${s.unit}`, because: 'the suite has not been compiled to a spec yet' });
+    return out;
+  }
+  if (!s.hasResults) {
+    out.push({ kind: 'do', command: `/sungen:run-test ${s.unit}`, because: 'the compiled spec has never been run, so every case is Pending' });
+    return out;
+  }
+  if (!s.hasDeliverable) {
+    out.push({ kind: 'do', command: `/sungen:delivery ${s.unit}`, because: 'results exist but have not been exported to the Test Case & Coverage Matrix' });
+  }
+  out.push({ kind: 'optional', command: `/sungen:create-test ${s.unit}`, because: 'extend coverage — the next tier, or the flows the inventory still lists as pending' });
+  return out;
+}

package/src/harness/spec-coverage.ts

@@ -202,3 +202,41 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
 
   return { hasSpec: true, frTotal: frs.length, frCovered, uncoveredMust, inferredOnly, triggerGaps, verdict };
 }
+
+/**
+ * A flow's requirement list that is a HAND RESTATEMENT of the screen specs it traverses.
+ *
+ * A flow spec typically cites its requirements as belonging elsewhere — "ST_AUTH_002 FR-001",
+ * "restated here in flow terms". That restatement is lossy by construction, and nothing checked
+ * it: on a real run the flow spec restated two of the screens' FRs, `specFR` read **2/2 = 100%**,
+ * and the guard clause the flow most needed (a double-submit rule in one of those screen specs)
+ * had never entered the system at all. The axis was certifying complete coverage of a
+ * hand-truncated universe — a worse failure than a missing scenario, because the number said the
+ * opposite.
+ *
+ * So: name the source documents the flow says its requirements come from, and say plainly which
+ * of them the project does not hold. Whether the restatement is complete is then a question
+ * someone can answer, instead of one nothing was asking.
+ */
+export function restatedRequirementSources(specText: string, availableUnits: string[]): {
+  restated: boolean; sources: string[]; missing: string[];
+} {
+  // "these ... originate in the SCREEN specs", "restated here", "per ST_AUTH_002 FR-001".
+  const restated = /\brestate[sd]?\b|\boriginate[sd]? in\b|\bderived from the (?:screen|per-screen) spec/i.test(specText);
+  // External document ids carrying their own requirement number: `ST_AUTH_002 FR-001`,
+  // `SCR-1-SYS-0001.FR-3`. Two+ segments and an uppercase head, so a bare `FR-001` (the flow's
+  // own) never matches.
+  // A citation may name SEVERAL documents at once — "ST_AUTH_002/ST_AUTH_004 FR-001" — so match
+  // the whole slash/comma-joined run and split it. Capturing only the token adjacent to the
+  // requirement number silently dropped every sibling.
+  const DOC = '[A-Z][A-Z0-9]*(?:[_-][A-Z0-9]+)+';
+  const cite = new RegExp(`\\b((?:${DOC})(?:\\s*[/,]\\s*(?:${DOC}))*)[\\s.]+(?:FR|NFR|BR)-\\d+`, 'g');
+  const sources = [...new Set(
+    [...specText.matchAll(cite)].flatMap((m) => m[1].split(/\s*[/,]\s*/)).map((x) => x.trim()).filter(Boolean),
+  )];
+  if (!restated && sources.length === 0) return { restated: false, sources: [], missing: [] };
+  const norm = (x: string): string => x.toLowerCase().replace(/[^a-z0-9]/g, '');
+  const have = availableUnits.map(norm);
+  const missing = sources.filter((src) => !have.some((u) => u.includes(norm(src)) || norm(src).includes(u)));
+  return { restated, sources, missing };
+}

package/src/harness/viewpoint-ledger.ts

@@ -94,3 +94,45 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
 
   return { hasViewpoint: true, total: items.length, covered, ratio: items.length ? covered / items.length : 1, missing };
 }
+
+/**
+ * A viewpoint item that names a BROWSER-LEVEL gesture, met by an in-app control instead.
+ *
+ * "Browser back button from Basic Info Confirmation to Basic Info — values must be restored"
+ * was answered with `User click [Confirmation:Back] button`. Those are different mechanisms: an
+ * app button runs the screen's own re-hydrate logic, browser history does not, and a defect
+ * that only appears on history navigation lives exactly in the gap. The ledger counted the item
+ * covered because the words matched, so the substitution was invisible (#595).
+ *
+ * The language has no reload/back step at all (#593), so the honest outcome is a `@manual`
+ * deferral naming the gesture — not a silent swap.
+ */
+const BROWSER_GESTURES: Array<{ gesture: string; re: RegExp; appSubstitute: RegExp }> = [
+  { gesture: 'browser back', re: /\bbrowser(?:'s)?[ -]?(?:back|history)\b|\bhistory[ -]back\b/i,
+    appSubstitute: /\bclick \[[^\]]*back[^\]]*\]/i },
+  { gesture: 'browser reload/refresh', re: /\b(?:page |browser )?(?:reload|refresh)(?:ing|ed|es)?\b/i,
+    appSubstitute: /\bis on \[[^\]]+\] page\b/i },
+  { gesture: 'closing and reopening the tab', re: /\bclos(?:e|ing) (?:and reopen\w*\s*)?the tab\b|\breopen\w* the tab\b/i,
+    appSubstitute: /\bis on \[[^\]]+\] page\b/i },
+];
+
+export function browserGestureSubstitutions(
+  viewpointPath: string, scenarios: ScenarioInfo[],
+): Array<{ gesture: string; item: string }> {
+  const out: Array<{ gesture: string; item: string }> = [];
+  // Judged PER SCENARIO, not over the whole file: a @manual scenario elsewhere that merely
+  // mentions the gesture in passing (explaining a tooling limit) silenced the check for an
+  // item that an automated scenario had quietly substituted.
+  const deferred = scenarios.filter((s) => s.manual).map((s) => s.haystack);
+  const automated = scenarios.filter((s) => !s.manual).map((s) => s.haystack);
+  for (const item of parseViewpointItems(viewpointPath)) {
+    for (const g of BROWSER_GESTURES) {
+      if (!g.re.test(item.text)) continue;
+      // A @manual scenario whose own subject IS the gesture is the honest answer.
+      if (deferred.some((h) => g.re.test(h))) break;
+      if (automated.some((h) => g.appSubstitute.test(h))) out.push({ gesture: g.gesture, item: item.text });
+      break;
+    }
+  }
+  return out;
+}

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -9,12 +9,20 @@ codex-trigger: "Run when the user asks to CREATE, generate, write, or author tes
 ---
 ## ⛔ HARD RULE — the run's LAST action is the next-step hand-back
 
-A create-test run is NOT finished when the files are written or the audit prints. The final
-action of EVERY run — success, partial, or aborted — is the next-step hand-back
-({{#cap parallel-subagents}}an `AskUserQuestion` offering the next actions{{/cap}}{{^cap parallel-subagents}}a numbered list of next-action choices{{/cap}};
-see "Finish — always hand the next step back" at the end of this file). Ending with a prose
-summary and no choices is a broken run: the operator is left guessing. This holds no matter
-how long the generation/repair loop ran.
+A run is NOT finished when its files are written or its output prints. The final action of EVERY
+run — success, partial, or aborted — is the next-step hand-back.
+
+**Ask `sungen next <unit>` rather than deciding from memory.** It derives the answer from what the
+project actually holds (artifacts on disk, the audit report, the accepted viewpoint baseline, the
+compiled spec, the run results), so the hand-back stays correct even when the run ended somewhere
+unexpected — a failed install, a driver that turned out not to support this unit kind, an aborted
+repair loop. Every `sungen` command also prints `Next: sungen next …` as its own last line.
+
+This matters most exactly where it used to break. A run that ended on a command with no footer of
+its own — `sungen capability add`, a dead-end install — left the session with nothing to follow and
+it stopped mid-workflow. If a step turns out to be impossible, that is still a hand-back: say what
+blocked it, run `sungen next <unit>`, and offer what remains. Ending with a prose summary and no
+choices is a broken run.
 
 ---
 {{#cap parallel-subagents}}
@@ -42,8 +50,19 @@ plus **both** postconditions: `successGuarantee` (true when the goal is reached)
 `minimalGuarantee` (what must still hold when the journey FAILS). Exception flows assert against
 the second one; with no `minimalGuarantee` they can only prove "an error appeared"
 (`FLOW-GUARANTEE-MISSING`). Then declare `phases:` — `[BF, AF, EF]` for a use-case decomposition
-(the first phase is the Basic Flow) — and enumerate flows with the step × risk matrix in the
-`sungen-tc-generation` skill.
+(the first phase is the Basic Flow). Then enumerate the use case's flows with the step × risk
+matrix in the `sungen-tc-generation` skill and **write them into the contract's `flows:`
+inventory**, each with a `status:` (`covered` / `deferred` / `pending-clarification` /
+`out-of-scope`) and a `reason:` for anything but `covered`. Without the inventory, coverage can
+only be measured per phase — and a phase counts as covered as soon as ONE scenario carries it, so
+a fifteen-flow use case scores 100% on three scenarios (`FLOW-INVENTORY-MISSING`, and the top mark
+is withheld).
+
+A risk the specs do NOT settle is `pending-clarification` with the question written down — never a
+scenario asserting invented behaviour, and never a silent omission. If the flow's requirements are
+restated from screen specs the project does not hold, say so: the audit reports
+`SPEC-RESTATED-UNVERIFIED` because `specFR 100%` over a hand-copied list certifies the copy, not
+the source.
 
 ---
 

package/src/orchestrator/templates/ai-src/commands/run-test.md

@@ -27,6 +27,12 @@ inside the run, not reasons to stop and hand the work back.
   install command as the hand-back.
 - Ending this run follows the same law as create-test: the LAST action is the next-step
   hand-back (the AskUserQuestion in "After showing results"), no matter how the run went.
+  **Ask `sungen next <unit>` rather than deciding from memory** — it derives the answer from what
+  the project now holds, so the hand-back stays correct even when the run ended somewhere
+  unexpected (a failed install, a driver that does not support this unit kind, an aborted repair
+  loop). Every `sungen` command also prints `Next: sungen next …` as its own last line. A step
+  that turns out to be impossible is still a hand-back: say what blocked it, run
+  `sungen next <unit>`, and offer what remains.
 
 ---
 

package/src/orchestrator/templates/ai-src/skills/sungen-tc-generation/SKILL.md

@@ -690,6 +690,42 @@ core, AF→behaviour, EF→validation/security) and traces them to the viewpoint
 `FL-EF` priority rows. Declare `phases: [BF, AF, EF]` in the contract; the FIRST phase is the
 Basic Flow and is the one that must reach `outcome`.
 
+**Declare the flow INVENTORY, not just the phases.** `phases: [BF, AF, EF]` says which
+vocabulary the suite uses; it cannot say how many flows the use case has — a phase counts as
+covered the moment ONE scenario carries it, so a fifteen-flow use case with three scenarios
+reported full phase coverage while a reviewer counting flows read it as a third done. List every
+flow in the contract, and give each one a status:
+
+```yaml
+flows:
+  - id: BF
+    outcome: "The successGuarantee — verified, recorded, signed in"
+    status: covered
+  - id: AF02
+    branchFrom: "BF step 4, before submitting"
+    outcome: "Re-enters BF at step 4 with the buffer restored"
+    status: covered
+  - id: EF08
+    branchFrom: "BF step 1, the control tapped twice"
+    outcome: "One request, one record"
+    status: pending-clarification      # the spec is silent — ASK, never assume a guard
+    reason: "The guard lives in ST_AUTH_001's spec, which this project does not hold."
+```
+
+Four statuses, and **silence is not one of them**: `covered` · `deferred` · `pending-clarification`
+(the behaviour is not agreed yet, so no scenario can be right) · `out-of-scope` (another suite owns
+it). Anything but `covered` needs a `reason:` — a deferral nobody can audit is the same as a
+missing flow. `sungen audit` then measures `flowCoverage` per DECLARED FLOW and reports
+`FLOW-UNCOVERED` (declared, nobody wrote it), `FLOW-UNDECLARED` (a scenario claiming a flow id the
+inventory never declares), `FLOW-STATUS-UNREASONED` and `FLOW-INVENTORY-MISSING`.
+
+**One flow, one id — a viewpoint is not a flow.** Several scenarios may prove one flow: give them
+the same flow id and different sequence numbers (`VP-VAL-EF01-001`, `VP-VAL-EF01-002`), never a
+fresh flow id per assertion. Two shapes the audit reports as `FLOW-PHASE-MISFILED`: an `EF` that
+reaches the outcome with nothing failing (that is a success-path postcondition, so it belongs to
+the BF), and an `AF` with no branch point (it walks the basic path asserting extra content — also
+the BF's). Both inflate the flow count while adding no branch coverage.
+
 **Declare once, then declare only the differences.** Actor · Trigger · Goal · Precondition ·
 `successGuarantee` · `minimalGuarantee` are use-case-level: they live in `flow-contract.yaml`
 and are never repeated per flow. Each flow in `test-viewpoint.md` then states only three things: