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

package/package.json

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

package/src/cli/commands/audit.ts

@@ -51,7 +51,9 @@ function render(r: AuditReport): void {
     // axis read as a contradiction.
     const inv = r.flowInventory;
     if (inv) {
-      L(`      flows: ${inv.covered.length}/${inv.covered.length + inv.uncovered.length} declared covered → flowCoverage ${(inv.ratio * 100).toFixed(0)}%`
+      const auto = inv.covered.filter((c) => c.automated).length;
+      L(`      flows: ${inv.covered.length}/${inv.covered.length + inv.uncovered.length} declared covered, ${auto} with automated evidence`
+        + (inv.manualOnly.length ? ` (manual-only: ${inv.manualOnly.map((f) => f.id).join(', ')})` : '')
         + (inv.accounted.length ? `   (${inv.accounted.map((f) => `${f.id}=${f.status}`).join(', ')})` : ''));
     }
     L(`      handoffs asserted: ${fq.handoffs.asserted}/${fq.handoffs.total}${fq.offGoal.length ? `   ⚠ off-goal scenarios: ${fq.offGoal.length} (${fq.offGoalCategories.join(', ')})` : ''}`);

package/src/harness/audit.ts

@@ -25,7 +25,7 @@ import { getProvenance, Provenance } from './provenance';
 import { specCoverage, SpecCoverageResult, parseSpecClauses, restatedRequirementSources } from './spec-coverage';
 import { downstreamScope, manualOracle, readText, DownstreamResult, ManualOracleResult,
   negativeSideEffect, sourceBacked, crossArtifactOwnership, isolationRisk, serialCascadeRisk } from './quality-gates';
-import { viewpointLedger, parseViewpointItems, browserGestureSubstitutions, LedgerResult } from './viewpoint-ledger';
+import { viewpointLedger, parseViewpointItems, browserGestureSubstitutions, viewpointIntegrity, LedgerResult } from './viewpoint-ledger';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { contextRouter } from '../capabilities/context-router';
@@ -304,6 +304,15 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   //     what a create-test run did, silently dropping the performance viewpoint on
   //     the way. While the declaration is unconfirmed, neither axis is evidence.
   const viewpointMoved = viewpointBaseline.status === 'changed';
+  // #618 — is there a YARDSTICK at all? `atomicLedger` and `traceability` are both measured
+  // against test-viewpoint.md, and four more sensors read it (the ledger, the declaration-integrity
+  // checks, the browser-gesture check, the continuity check). When the file is absent every one of
+  // them goes quiet — and worse, the checks that DERIVE from it keep talking: scenarios read as
+  // unsourceable because half their source contract is missing, `trace.mappedRatio` is 0 because
+  // there is nothing to map to, and the calibration axis reports a manufactured 0% that then trips
+  // SCORE-INFLATED-BY-BREADTH with advice nobody can act on. One absent file produced nine
+  // misleading findings and not one naming the file. So: say it once, and stop concluding.
+  const hasYardstick = ledger.hasViewpoint && (viewpoints.length > 0 || ledger.total > 0);
   //  4. A flow with a contract is measured on ITS coverage: journey phases (HP/ER/EH
   //     automated) — not a screen's page-type themes. Same weight, same criticality,
   //     so a flow can finally EARN the coverage axis instead of always losing it to
@@ -315,7 +324,11 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // "weakest: flowCoverage 100% — fix it to lift the number", which is not fixable advice (#595).
   const axisDefs: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean; byDesign?: boolean }> = [
     flowScored
-      ? { key: 'flowCoverage', value: inventory ? Math.min(inventory.ratio, flowQ.phaseRatio) : flowQ.phaseRatio, weight: 0.22, applicable: true, critical: true }
+      // A declared flow claimed only by @manual scenarios is ACCOUNTED FOR but nothing runs, so
+      // it cannot count the same as an automated one — `covered` was collapsing three very
+      // different states into one number (#599). Half credit: the design work is real, the
+      // regression evidence is not.
+      ? { key: 'flowCoverage', value: inventory ? Math.min((inventory.ratio + inventory.automatedRatio) / 2, flowQ.phaseRatio) : flowQ.phaseRatio, weight: 0.22, applicable: true, critical: true }
       : { key: 'coverage', value: coverage, weight: 0.22, applicable: !!gate.pageType && gate.themesTotal > 0, critical: true },
     { key: 'specFR', value: specRatio, weight: 0.15, applicable: spec.hasSpec && spec.frTotal > 0, critical: true },
     { key: 'atomicLedger', value: ledger.ratio, weight: 0.13, applicable: ledger.hasViewpoint && ledger.total > 0 && !viewpointMoved, critical: true },
@@ -416,6 +429,27 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     if (!flowQ.contract!.minimalGuarantee) {
       findings.push('FLOW-GUARANTEE-MISSING: the contract declares no `minimalGuarantee:` — the postcondition that must hold in EVERY flow, including failure ("no second account for the same email", "no verification mail on a rejected submit"). Exception/guard scenarios have nothing to assert against without it; add it (and `successGuarantee:` for the goal-reached side).');
     }
+    // #599 — integrity of the DECLARATION itself: three ways it can be internally wrong while
+    // every coverage number still reads well.
+    {
+      const testDataDir = path.join(screenDir, 'test-data');
+      const extra: Array<{ label: string; text: string }> = [];
+      try {
+        for (const f of fs.readdirSync(testDataDir).filter((x) => x.endsWith('.yaml'))) {
+          extra.push({ label: `test-data/${f}`, text: readTextFile(path.join(testDataDir, f)) ?? '' });
+        }
+      } catch { /* api units and fresh scaffolds carry none */ }
+      const vi = viewpointIntegrity(viewpointPath, scenarios.map((sc) => sc.vpId ?? '').filter(Boolean), extra);
+      for (const d of vi.duplicateIds.slice(0, 4)) {
+        findings.push(`VIEWPOINT-ID-REUSED: "${d.id}" labels ${d.count} different claims (${d.texts.map((t) => `"${t.slice(0, 44)}…"`).join(' · ')}). The ledger then counts ${d.count} items while traceability sees ONE id, so both the coverage arithmetic and "which test proves this?" go wrong — and neither number looks suspicious. Give each atomic claim its own id; several ids may share a flow.`);
+      }
+      for (const d of vi.danglingRefs.slice(0, 5)) {
+        findings.push(`TRACE-REF-DANGLING: ${d.where} cites "${d.ref}", which no scenario carries. Nothing breaks at runtime, so a wrong pointer survives every refactor and quietly misleads the next maintainer. Fix the reference, or the scenario id it was meant to name.`);
+      }
+      if (vi.uniformPriority) {
+        findings.push(`VIEWPOINT-PRIORITY-UNIFORM: all ${vi.uniformPriority.rows} rows of the Priority Viewpoints table are "${vi.uniformPriority.levels[0]}". That is a formality, not a priority: nothing can be selected for a smoke run and the release conversation has no input. Rank by business impact and risk — the basic flow and the data-integrity guards are not the same bet as an exit path a screen suite already covers.`);
+      }
+    }
     // #595 — a viewpoint item naming a browser-level gesture, answered with an in-app control.
     for (const g of browserGestureSubstitutions(viewpointPath, scenarios).slice(0, 4)) {
       findings.push(`VIEWPOINT-GESTURE-SUBSTITUTED: the viewpoint asks for "${g.gesture}" ("${g.item.slice(0, 80)}…") but the suite exercises an in-app control instead. They are different mechanisms — an app button runs the screen's own re-hydrate logic, browser history does not, and a defect that only shows on history navigation lives in exactly that gap. The step vocabulary has no reload/back step (#593), so defer it with \`@manual\` naming the gesture rather than substituting silently.`);
@@ -436,6 +470,9 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       for (const f of inventory.uncovered) {
         findings.push(`FLOW-UNCOVERED: declared flow ${f.id}${f.branchFrom ? ` (branches from ${f.branchFrom})` : ''} has status \`covered\` but no scenario carries its id — write it, or change its status to \`deferred\` / \`pending-clarification\` / \`out-of-scope\` WITH a reason. Silence is the one option the inventory removes.`);
       }
+      if (inventory.manualOnly.length > 0) {
+        findings.push(`FLOW-MANUAL-ONLY: ${inventory.manualOnly.length} declared flow(s) are claimed only by @manual scenarios — ${inventory.manualOnly.map((f) => f.id).join(', ')}. They are accounted for, but NOTHING RUNS for them: a regression run would not notice if any of these broke. \`status: covered\` says the flow was thought about; it does not say the suite can catch a regression in it, so flowCoverage credits them at half. Either automate them (check the capability plan for a driver that would) or say plainly in the delivery that this flow's evidence is a manual procedure.`);
+      }
       for (const u of inventory.undeclared.slice(0, 6)) {
         findings.push(`FLOW-UNDECLARED: "${u.scenario}" claims flow id ${u.id}, which the contract's inventory does not declare — a phase id invented for one scenario inflates the flow count without adding branch coverage. Either declare ${u.id} as a real flow (branch point + own outcome), or fold the scenario into the flow it actually belongs to.`);
       }
@@ -537,7 +574,13 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   } else if (balance.imbalanced && !flowScored) {
     findings.push(`BALANCE: ${balance.note} Stop expanding secondary viewpoints until business-core gaps are filled.`);
   }
-  if (trace.mappedRatio < 0.5) {
+  if (!hasYardstick) {
+    const lost = [
+      'atomicLedger', 'traceability',
+      ...(unsourced.length ? [`${unsourced.length} scenario(s) could not be traced to a source`] : []),
+    ];
+    findings.push(`VIEWPOINT-MISSING: \`requirements/test-viewpoint.md\` ${ledger.hasViewpoint ? 'declares no viewpoints' : 'does not exist'}, so this unit has no yardstick. Two scored axes are excluded (atomicLedger, traceability) and four sensors cannot run: the atomic ledger, the declaration-integrity checks (reused ids, dangling refs, uniform priority), the browser-gesture check and the two-way continuity check. Nothing here is a pass — it is unmeasured [${lost.join(', ')}]. A flow contract does NOT substitute: the contract declares the use case, the viewpoint declares the CLAIMS the suite is scored against, and only the second is independent of what was generated. Author it (\`sungen add-flow\` scaffolds a template), then \`sungen audit --screen ${screenName} --accept-viewpoint\`.`);
+  } else if (trace.mappedRatio < 0.5) {
     findings.push(`TRACE: ${trace.note}`);
   }
   // (UNIVERSAL viewpoint-gap finding now emitted by the `ui` gate sensor — see the gate block below.)
@@ -637,7 +680,10 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       findings.push(`FLOW-EXHAUSTIVE-INPUTS: ${c.scenarios.length} same-shape scenarios differ only in data (${c.scenarios.slice(0, 3).join(' | ')}${c.scenarios.length > 3 ? ' …' : ''}) — a system-test flow uses REPRESENTATIVE inputs (one valid + one that triggers the exception branch); the full EP/boundary matrix belongs to the owning screen (or a @cases dataset there). Keep one representative per branch here.`);
     }
   }
-  for (const u of unsourced.slice(0, 6)) {
+  // Reported per scenario only when BOTH halves of the source contract exist. With no viewpoint,
+  // "doesn't trace to any FR / viewpoint item" is true by construction for anything that does not
+  // happen to cite an FR — the count is folded into VIEWPOINT-MISSING instead of six accusations.
+  for (const u of (hasYardstick ? unsourced : []).slice(0, 6)) {
     findings.push(`UNSOURCEABLE-SCENARIO: "${u}" doesn't trace to any FR / viewpoint item — link it to a source, or tag it @exploration (not part of the official suite).`);
   }
 
@@ -669,7 +715,10 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   for (const a of scored) axes[a.key] = Math.round(a.value * 100) / 100;
   // Measured but not weighted: they drive findings, not the headline.
   axes.manualOracle = Math.round(manualCompleteness * 100) / 100;
-  axes.taxonomy = taxonomyMismatch ? 0 : Math.round(trace.mappedRatio * 100) / 100;
+  // Only a real mismatch scores 0. Without a yardstick `trace.mappedRatio` is 0 because there is
+  // nothing to map to, and reporting that as the weakest axis sent authors to "raise taxonomy" —
+  // an axis that was never measured.
+  if (hasYardstick) axes.taxonomy = taxonomyMismatch ? 0 : Math.round(trace.mappedRatio * 100) / 100;
   const notApplicable = axisDefs.filter((a) => !a.applicable).map((a) => a.key);
   const weakestEntry = Object.entries(axes).sort((a, b) => a[1] - b[1])[0];
   const weakest = { axis: weakestEntry[0], value: weakestEntry[1] };

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

@@ -18,6 +18,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { reportSlug, featureFilesFor } from './unit-paths';
 import { readTextFile } from './read-text';
+import { checkAssetsDrift } from '../orchestrator/assets-drift';
 
 export interface NextStep {
   /** The command to run, as the operator would type it. */
@@ -47,6 +48,13 @@ export interface UnitState {
     findings: string[];
     viewpointBaselineStatus?: string;
   };
+  /**
+   * The project's AI commands/skills were written by a different sungen build. This belongs in
+   * "what to do next" because it silently voids every fix that ships as an INSTRUCTION: a HARD
+   * RULE added to `create-test` reaches nobody until `sungen update` runs, and the existing
+   * warning is one grey stderr line at the top of every command (#620).
+   */
+  assetsDrift?: { recordedVersion: string; runningVersion: string };
   steps: NextStep[];
 }
 
@@ -63,7 +71,7 @@ function readJson(p: string): Record<string, unknown> | null {
 function countScenarios(unitDir: string, unit: string): number {
   let n = 0;
   for (const f of featureFilesFor(unitDir, unit)) {
-    const text = readTextFile(f) ?? '';
+    const text = fs.existsSync(f) ? readTextFile(f) : '';
     n += (text.match(/^\s*Scenario(?: Outline)?:/gm) ?? []).length;
   }
   return n;
@@ -84,9 +92,12 @@ export function readUnitState(
   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');
+  // `readTextFile` throws on a missing file, and every path here is legitimately absent at some
+  // point in a unit's life — the resolver exists to report exactly that, so it must not crash on it.
+  const read = (p: string): string => (fs.existsSync(p) ? readTextFile(p) : '');
+  const selectorText = selectorFiles.map((f) => read(path.join(selectorsDir, f))).join('\n');
   const contractPath = path.join(req, 'flow-contract.yaml');
-  const contractText = readTextFile(contractPath) ?? '';
+  const contractText = read(contractPath);
 
   const specDirs = [
     path.join(projectRoot, 'specs', 'generated', 'flows', unit),
@@ -125,6 +136,12 @@ export function readUnitState(
     selectorsArePlaceholder: selectorFiles.length > 0
       && (/TODO|PLACEHOLDER|REPLACE ME/i.test(selectorText) || selectorText.trim().length < 40),
     compiled, hasResults, hasDeliverable,
+    assetsDrift: (() => {
+      const d = checkAssetsDrift(projectRoot);
+      return d && d.recordedVersion !== d.runningVersion
+        ? { recordedVersion: d.recordedVersion, runningVersion: d.runningVersion }
+        : undefined;
+    })(),
     audit: audit
       ? {
         overall: typeof score.overall === 'number' ? score.overall : 0,
@@ -163,6 +180,29 @@ export function deriveSteps(s: UnitState): NextStep[] {
     });
     return out;
   }
+  // Stale AI assets come FIRST, because they invalidate the advice below: a HARD RULE added to
+  // `create-test` reaches nobody until `sungen update` runs, so the run that follows will repeat
+  // whatever the old instructions said. Upgrading the package alone does not refresh them, and the
+  // existing warning is one grey stderr line among a command's whole output (#620).
+  if (s.assetsDrift) {
+    out.push({
+      kind: 'do',
+      command: 'sungen update',
+      because: `this project's AI commands/skills were written by sungen ${s.assetsDrift.recordedVersion} and you are running ${s.assetsDrift.runningVersion} — upgrading the package does NOT refresh them, so any rule added since ${s.assetsDrift.recordedVersion} is not in effect for the next run`,
+    });
+  }
+  // The yardstick. `atomicLedger` and `traceability` are measured against test-viewpoint.md and
+  // four sensors read it, so its absence is not cosmetic — and it can go missing from a unit that
+  // already HAS a spec (a run deleted it), which the "no source at all" branch above never sees.
+  if (!s.hasViewpoint) {
+    out.push({
+      kind: 'blocked',
+      command: s.kind === 'flow'
+        ? `sungen add-flow --flow ${s.unit} --path <start-url>    # repairs the missing scaffold; never overwrites`
+        : `write qa/screens/${s.unit}/requirements/test-viewpoint.md`,
+      because: 'requirements/test-viewpoint.md is missing — it is the yardstick `atomicLedger` and `traceability` are measured against, and four sensors read it, so the audit reports VIEWPOINT-MISSING and those axes are excluded. A flow contract does not substitute: it declares the use case, the viewpoint declares the claims',
+    });
+  }
   if (s.kind === 'flow' && !s.hasContract) {
     out.push({
       kind: 'blocked',

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/flow-manager.ts

@@ -59,8 +59,26 @@ export class FlowManager {
     const testDataPath = path.join(testDataDir, `${flowName}.yaml`);
 
     if (fs.existsSync(flowDir)) {
-      console.error(`Error: Flow "${options.name}" already exists at ${flowDir}`);
-      process.exit(1);
+      // Refusing outright left no way back when a REQUIREMENT file went missing: a run deleted
+      // `requirements/test-viewpoint.md`, `add-flow` said "already exists", and the only remaining
+      // route was writing the scaffold by hand. The viewpoint is the yardstick two scored axes are
+      // measured against, so losing it silently costs real coverage evidence (#620).
+      //
+      // Repair CREATES ONLY WHAT IS MISSING — it never overwrites, so a filled spec or viewpoint is
+      // safe. Anything already present is reported as skipped.
+      const restored = this.restoreMissingScaffolds(options, flowName, isMobile, {
+        requirementsDir, featuresDir, selectorsDir, testDataDir, requirementsUiDir,
+        featurePath, selectorPath, testDataPath,
+      });
+      if (restored.length === 0) {
+        console.error(`Error: Flow "${options.name}" already exists at ${flowDir} — and every scaffold file is present, so there is nothing to repair.`);
+        process.exit(1);
+      }
+      console.log(`Flow "${options.name}" already exists — restored ${restored.length} missing file(s):`);
+      for (const f of restored) console.log(`  + ${path.relative(this.cwd, f)}`);
+      console.log('');
+      console.log('Nothing else was touched: repair only creates what is absent, never overwrites.');
+      return;
     }
 
     console.log(`Creating flow: ${options.name}\n`);
@@ -172,6 +190,38 @@ export class FlowManager {
       .replace(/-+/g, '-');
   }
 
+  /**
+   * Re-create only the scaffold files that are ABSENT from an existing flow.
+   *
+   * The requirement files are not decoration: `requirements/test-viewpoint.md` is the yardstick
+   * `atomicLedger` and `traceability` are measured against, and four sensors read it. When a run
+   * removed it, `add-flow` refused ("already exists") and there was no CLI route back — so the
+   * yardstick stayed gone and the audit's two viewpoint axes stayed excluded (#620).
+   *
+   * Never overwrites: a filled spec or viewpoint is an INPUT the QA owns.
+   */
+  private restoreMissingScaffolds(
+    options: FlowOptions, flowName: string, isMobile: boolean,
+    paths: {
+      requirementsDir: string; featuresDir: string; selectorsDir: string; testDataDir: string;
+      requirementsUiDir: string; featurePath: string; selectorPath: string; testDataPath: string;
+    },
+  ): string[] {
+    const restored: string[] = [];
+    for (const d of [paths.featuresDir, paths.selectorsDir, paths.testDataDir, paths.requirementsUiDir]) {
+      if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+    }
+    const ensure = (file: string, body: () => string): void => {
+      if (fs.existsSync(file)) return;
+      fs.writeFileSync(file, body(), 'utf-8');
+      restored.push(file);
+    };
+    ensure(path.join(paths.requirementsDir, 'spec.md'), () => this.generateSpecTemplate(options, flowName, isMobile));
+    ensure(path.join(paths.requirementsDir, 'test-viewpoint.md'), () => this.generateViewpointTemplate(options));
+    ensure(paths.featurePath, () => this.generateFeatureTemplate(options, flowName, isMobile));
+    return restored;
+  }
+
   private generateSpecTemplate(options: FlowOptions, flowName: string, isMobile: boolean): string {
     if (isMobile) {
       return `# ${options.name} Flow Specification

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

@@ -64,6 +64,23 @@ 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.
 
+**The contract does NOT replace `test-viewpoint.md` — author BOTH.** They answer different
+questions and only one of them is a yardstick:
+
+| | declares | scored against it |
+|---|---|---|
+| `flow-contract.yaml` | the USE CASE — actor · trigger · goal · precondition · both guarantees · the flow inventory | `flowCoverage` |
+| `test-viewpoint.md` | the CLAIMS the suite must prove — cross-screen concerns, edge cases, design decisions, open questions, priorities | `atomicLedger` · `traceability` |
+
+If `requirements/test-viewpoint.md` is missing, **write it before generating** (`add-flow` scaffolds
+a template; a run that deletes or replaces it has removed the yardstick). Without it two scored
+axes are excluded and four sensors cannot run at all — the atomic ledger, the
+declaration-integrity checks, the browser-gesture check and the two-way continuity check — so the
+audit reports `VIEWPOINT-MISSING` and the result is *unmeasured*, not passing. And the reason the
+contract cannot stand in: the viewpoint is the one artifact that must stay **independent of what
+you generated**. That is why a filled one is an INPUT you never rewrite, and why authoring it
+FIRST — from the spec, before the scenarios exist — is the only order that keeps it honest.
+
 ---
 
 ## Platform detection (do this FIRST)

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