@sun-asterisk/sungen 3.2.24-beta.2 → 3.2.24-beta.4

package/src/harness/flow-contract.ts

@@ -235,8 +235,22 @@ export function flowIdOf(s: ScenarioInfo, declaredPhases: string[]): string | nu
 }
 
 export interface InventoryResult {
-  /** Declared → the scenarios claiming it. A declared flow with none is a NAMED gap. */
-  covered: Array<{ id: string; scenarios: string[] }>;
+  /**
+   * Declared → the scenarios claiming it. A declared flow with none is a NAMED gap.
+   * `automated` is false when EVERY scenario claiming the flow is `@manual`: the flow is
+   * accounted for, but nothing runs — see `manualOnly` (#599).
+   */
+  covered: Array<{ id: string; scenarios: string[]; automated: boolean }>;
+  /**
+   * Declared `covered` and claimed only by `@manual` scenarios. `covered` used to mean three
+   * different things at once — a flow with three automated scenarios, one with a single manual
+   * procedure, and one whose oracle is still an open question all read as `covered`, and
+   * `flowCoverage` reported 100% over the mix. A reader cannot tell which flows would actually
+   * fail a regression run.
+   */
+  manualOnly: FlowDecl[];
+  /** Covered declared flows with at least one AUTOMATED scenario / flows that ought to be. */
+  automatedRatio: number;
   /** 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. */
@@ -271,9 +285,16 @@ export function flowInventory(contract: FlowContract, scenarios: ScenarioInfo[])
   }
   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)! }));
+    .map((f) => ({
+      id: f.id,
+      scenarios: byId.get(f.id)!,
+      automated: scenarios.some((sc) => flowIdOf(sc, contract.phases) === f.id && !sc.manual),
+    }));
+  const manualOnly = covered.filter((c) => !c.automated).map((c) => expected.find((f) => f.id === c.id)!);
   return {
     covered,
+    manualOnly,
+    automatedRatio: expected.length ? covered.filter((c) => c.automated).length / expected.length : 1,
     uncovered: expected.filter((f) => (byId.get(f.id) ?? []).length === 0),
     accounted: contract.flows.filter((f) => f.status !== 'covered'),
     undeclared,

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/sensors.ts

@@ -588,6 +588,19 @@ interface ClaimRule {
 
 // Ordered by specificity; the first matching rule per scenario wins.
 const CLAIM_RULES: ClaimRule[] = [
+  {
+    // A continuity claim is an EXACTNESS claim. `text contains {{v}}` passes when the UI
+    // concatenates, prefixes or truncates — which is exactly the defect "unchanged" exists to
+    // catch, so proving it with a substring proves the opposite of what the title says. Found on
+    // a real basic flow whose seven confirmation rows all used `contains` while claiming the six
+    // values "survive unchanged" (#599).
+    claim: 'unchanged/preserved',
+    title: /\b(unchanged|unmodified|un-?edited|identical|preserved|intact|verbatim|as entered|without (?:any )?(?:change|modification))\b/,
+    proof: /^(?![\s\S]*\bcontains \{\{)/,
+    need: 'exact-value assertions (`see [X] text with {{v}}` / `field with {{v}}`) for the values the title says are unchanged',
+    hint: 'swap `contains {{v}}` for `with {{v}}` on the continuity rows. A substring match cannot distinguish "unchanged" from "changed by adding a prefix" — and if the screen genuinely renders extra text around the value, say so in the title instead of claiming exactness.',
+    severity: 'warn',
+  },
   {
     claim: 'all/every/each',
     title: /\b(all|every|each)\b/,

package/src/harness/viewpoint-ledger.ts

@@ -136,3 +136,68 @@ export function browserGestureSubstitutions(
   }
   return out;
 }
+
+/**
+ * Traceability integrity of the DECLARATION itself — three ways a viewpoint document can be
+ * internally wrong while every coverage number still reads well (#599).
+ *
+ * These are cheap and deterministic, and each was found on a real generated document:
+ *
+ *  - **A reused item id.** `FL-BF-001` labelled four different atomic claims. The ledger then
+ *    counts four items while traceability sees one id, so coverage arithmetic and "which test
+ *    proves this?" both go wrong — and neither number looks suspicious.
+ *  - **A dangling scenario reference.** A `test-data` comment cited `VP-LOGIC-EF07-001` when the
+ *    suite spells it `VP-SEC-EF07-001`. Nothing breaks at runtime, so the wrong pointer survives
+ *    every refactor and quietly misleads the next maintainer.
+ *  - **A uniform priority table.** Every declared phase marked `High` is not a priority, it is a
+ *    formality: nothing can be selected for a smoke run, and the release conversation has no
+ *    input. A real ranking has at least two levels.
+ */
+export interface ViewpointIntegrity {
+  duplicateIds: Array<{ id: string; count: number; texts: string[] }>;
+  danglingRefs: Array<{ ref: string; where: string }>;
+  uniformPriority: { levels: string[]; rows: number } | null;
+}
+
+/** `VP-…`/`FL-…` ids as cited in prose — the shape scenario titles use. */
+const CITED_ID = /\b((?:VP|FL)-[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+)\b/g;
+
+export function viewpointIntegrity(
+  viewpointPath: string, scenarioIds: string[], extraSources: Array<{ label: string; text: string }> = [],
+): ViewpointIntegrity {
+  const items = parseViewpointItems(viewpointPath);
+  const byId = new Map<string, string[]>();
+  for (const it of items) {
+    if (!it.id) continue;
+    byId.set(it.id, [...(byId.get(it.id) ?? []), it.text]);
+  }
+  const duplicateIds = [...byId.entries()]
+    .filter(([, texts]) => texts.length > 1)
+    .map(([id, texts]) => ({ id, count: texts.length, texts }))
+    .sort((a, b) => b.count - a.count);
+
+  // A cited id must name a scenario that exists. Compared case-insensitively; the viewpoint's own
+  // declaration ids are NOT scenario references, so only the extra sources (test-data, spec) are
+  // scanned — a viewpoint legitimately declares ids the suite then implements.
+  const known = new Set(scenarioIds.map((s) => s.toUpperCase()));
+  const danglingRefs: Array<{ ref: string; where: string }> = [];
+  for (const src of extraSources) {
+    for (const m of src.text.matchAll(CITED_ID)) {
+      const ref = m[1].toUpperCase();
+      if (known.has(ref)) continue;
+      if (danglingRefs.some((d) => d.ref === ref && d.where === src.label)) continue;
+      danglingRefs.push({ ref: m[1], where: src.label });
+    }
+  }
+
+  // The Priority-Viewpoints table: `| <id> | <priority> | <reason> |`.
+  // `readTextFile` throws on a missing file, and a unit may legitimately have no viewpoint yet.
+  const vpText = fs.existsSync(viewpointPath) ? readTextFile(viewpointPath) : '';
+  const rows = [...vpText
+    .matchAll(/^\|\s*((?:VP|FL)[A-Z0-9._-]*)\s*\|\s*(critical|high|medium|normal|low|deferred)\s*\|/gim)]
+    .map((m) => m[2].toLowerCase());
+  const levels = [...new Set(rows)];
+  const uniformPriority = rows.length >= 3 && levels.length === 1 ? { levels, rows: rows.length } : null;
+
+  return { duplicateIds, danglingRefs, uniformPriority };
+}

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

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

@@ -719,6 +719,32 @@ missing flow. `sungen audit` then measures `flowCoverage` per DECLARED FLOW and
 `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 id per atomic CLAIM in the viewpoint.** The flow id groups; the viewpoint id identifies.
+Writing `FL-BF-001` on four different claims makes the ledger count four items while traceability
+sees one, so the coverage arithmetic and "which test proves this?" are both wrong and neither
+number looks suspicious (`VIEWPOINT-ID-REUSED`). Number them within the flow —
+`FL-BF-001`, `FL-BF-002`, … — and never cite an id no scenario carries (`TRACE-REF-DANGLING`
+checks the ids mentioned in `test-data/*.yaml` too).
+
+**Rank the priorities; do not stamp them.** A Priority-Viewpoints table where every row says
+`High` is a formality, not a priority: nothing can be selected for a smoke run and the release
+conversation has no input (`VIEWPOINT-PRIORITY-UNIFORM`). Rank by business impact and risk — the
+basic flow, data integrity and the auth/context guards are High; a recoverable back-navigation or
+a network blip is usually Normal; an exit path a screen suite already owns is Low.
+
+**A continuity claim is an EXACTNESS claim.** A title saying values are *unchanged / preserved /
+intact* must be proven with `see [X] text with {{v}}`, never `contains {{v}}`: a substring match
+passes when the UI concatenates, prefixes or truncates — exactly the defect "unchanged" exists to
+catch, so `contains` proves the opposite of the claim (`CLAIM-WEAK`). If the screen genuinely
+renders extra text around the value, change the title instead of weakening the oracle.
+
+**`status: covered` is about the DESIGN, not the evidence.** A flow whose only scenarios are
+`@manual` is accounted for and still has nothing that runs: a regression suite would not notice if
+it broke. The audit reports `FLOW-MANUAL-ONLY` and credits those flows at half in `flowCoverage`,
+so do not treat a manual procedure as equivalent to automation. Check the capability plan for a
+driver that would automate it; if none can, say so plainly in the delivery rather than letting
+`covered` imply a passing test.
+
 **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