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

package/src/harness/audit.ts

@@ -15,6 +15,7 @@ import { featureFilesFor } from './unit-paths';
 import {
   loadCatalog, viewpointGate, assertionDepth, dataThemesFor, depthThresholdFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
   automatableManual, flowCoveredThemes, flowRegressionDepth, oracleStrength, declaredPageType,
+  numericClaimGaps, priorityMismatches,
   GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult, ClaimProofResult, TaxonomyResult, Catalog, AutomatableManualResult, FlowDepthResult, OracleStrengthResult,
 } from './sensors';
 import { loadFlowScenarios } from './flow-check';
@@ -303,7 +304,22 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   //     that rewrites that file scores them 100% by construction — which is exactly
   //     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';
+  const adoptedPostHoc = viewpointBaseline.status === 'new' && scenarios.length > 0;
+  // `changed` was the only untrusted state, but `new` alongside an EXISTING suite is the same
+  // problem seen earlier: the yardstick is being introduced against scenarios that already exist,
+  // so it can only measure what their author already thought of. One field run wrote the file
+  // after generating the suite and said so in its own header — and both axes still read 100%,
+  // because a first audit records the baseline silently (#622). Untrusted until a human accepts it.
+  const viewpointMoved = viewpointBaseline.status === 'changed' || adoptedPostHoc;
+  // #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
@@ -565,7 +581,16 @@ 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 (adoptedPostHoc) {
+    findings.push(`VIEWPOINT-ADOPTED-POST-HOC: this is the first audit of \`requirements/test-viewpoint.md\` and the suite ALREADY has ${scenarios.length} scenarios, so the yardstick is being introduced against tests that already exist. A declaration written after the suite can only measure what its author already thought of — and if it was derived FROM the suite, \`atomicLedger\` and \`traceability\` read 100% by construction while anything dropped along the way stops being missing from anything. Both axes are held as unverified until you review the claims (add what you care about, delete what you do not) and confirm: \`sungen audit --screen ${screenName} --accept-viewpoint\`.`);
+  }
+  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.)
@@ -643,6 +668,31 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   if (depth.deferredBusinessCritical > 0 && depth.deferredBusinessCritical >= depth.businessCriticalTotal) {
     findings.push(`DEPTH-DEFERRED: businessDepth ${businessDepth.toFixed(2)} is computed over only ${depth.businessCriticalTotal} on-screen scenario(s); ${depth.deferredBusinessCritical} business-critical scenario(s) are deferred to @manual (excluded from the ratio). Automate them in a flow and verify with \`sungen flow-check\` — this ratio is NOT "all business depth covered".`);
   }
+  // #622 — a claim that names a count, proved by fewer assertions than it names. The count sits
+  // in the viewpoint CLAIM, so both the title-level and the claim-level shape are checked.
+  for (const g of ledger.partial.slice(0, 5)) {
+    findings.push(`CLAIM-PARTIAL: claim ${g.id ?? ''} names ${g.claimed} but its scenario asserts ${g.asserted} value(s) — "${g.text.slice(0, 70)}". Mapping a claim to a scenario id proves it is ADDRESSED, not that the oracle demonstrates it: assert all ${g.claimed}, use a \`see all …\` set assertion, or narrow the claim to what is actually proven.`);
+  }
+  for (const g of numericClaimGaps(scenarios).slice(0, 3)) {
+    findings.push(`CLAIM-PARTIAL: "${g.name}" claims ${g.claimed} ${g.noun} but asserts ${g.asserted} value(s) — assert all ${g.claimed}, or say in the title what the scenario actually proves.`);
+  }
+  // #622 — the priority table is where release selection comes from; a tag that contradicts it
+  // means nobody can tell which of the two was the decision.
+  {
+    const pm = priorityMismatches(hasYardstick ? (readText(viewpointPath) ?? '') : '', scenarios);
+    const byId = new Map<string, { declared: string; tagged: string; n: number }>();
+    for (const m of pm) {
+      const cur = byId.get(m.id) ?? { declared: m.declared, tagged: m.tagged, n: 0 };
+      cur.n++;
+      byId.set(m.id, cur);
+    }
+    for (const [id, v] of [...byId.entries()].slice(0, 5)) {
+      findings.push(`PRIORITY-CONTRADICTED: the viewpoint declares ${id} as "${v.declared}" but ${v.n} of its scenario(s) are tagged @${v.tagged}. A smoke run selects on the tag, so it picks up work the declaration deprioritised — reconcile them, and if the tag is right, fix the declaration rather than leaving both on record.`);
+    }
+  }
+  if (ledger.manualOnly.length > 0) {
+    findings.push(`VIEWPOINT-ITEM-MANUAL-ONLY: ${ledger.manualOnly.length} viewpoint claim(s) are carried only by @manual scenarios — ${ledger.manualOnly.slice(0, 4).map((m) => m.id).join(', ')}${ledger.manualOnly.length > 4 ? ', …' : ''}. The claim is ADDRESSED (a procedure exists) but nothing runs for it, so a regression would not notice it breaking. \`atomicLedger\` counts them, because the design work is real — the delivery must not report them as automated coverage.`);
+  }
   if (ledger.hasViewpoint && ledger.missing.length) {
     const sample = ledger.missing.slice(0, 6).map((m) => m.id || `"${m.text}"`).join(', ');
     findings.push(`VIEWPOINT-ITEM-MISSING: ${ledger.missing.length}/${ledger.total} atomic viewpoint items have no covering scenario (${(ledger.ratio * 100).toFixed(0)}% covered) — e.g. ${sample}. Cover each item or mark it deferred/spec-gap.`);
@@ -665,7 +715,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).`);
   }
 
@@ -697,7 +750,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/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

@@ -843,3 +843,71 @@ export function claimProof(scenarios: ScenarioInfo[], focus = 'functional'): Cla
 
   return { total: measured.length, withClaims, proven, unproven, ratio, focus, threshold, verdict };
 }
+
+// ---------- Numeric claims, and priority that disagrees with the declaration ----------
+
+const NUMBER_WORDS: Record<string, number> = {
+  two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+};
+
+/**
+ * A title that names a COUNT, proved by fewer assertions than it claims.
+ *
+ * "restores all **six** buffered values" asserted four fields; "all **seven** confirmation rows
+ * are read-only" checked two. Exact id mapping made both read as covered, and `claimProof` had no
+ * rule for it — a claim can be mapped to a scenario and still be only partly proven, which is the
+ * gap between "declared coverage" and "coverage an oracle demonstrates" (#622).
+ *
+ * Counting is the whole point here: the number is in the title, so the check is arithmetic rather
+ * than semantic. A `see all …` assertion is exempt — it proves a set in one step, which is the
+ * stronger shape, not a weaker one.
+ */
+export function numericClaimGaps(scenarios: ScenarioInfo[]): Array<{ name: string; claimed: number; asserted: number; noun: string }> {
+  const out: Array<{ name: string; claimed: number; asserted: number; noun: string }> = [];
+  for (const s of scenarios) {
+    if (s.manual) continue;                                  // a procedure counts by hand
+    if (/\bsee all\b/.test(s.stepsText)) continue;            // a set proved in one assertion
+    const m = s.name.toLowerCase().match(/\b(?:all\s+)?(two|three|four|five|six|seven|eight|nine|ten|[2-9]|10)\s+([a-z][a-z-]{2,})/);
+    if (!m) continue;
+    const claimed = NUMBER_WORDS[m[1]] ?? Number(m[1]);
+    if (!Number.isFinite(claimed) || claimed < 2) continue;
+    // Only value-bearing assertions count: `see [X] … with/contains {{v}}`. A visibility check
+    // does not demonstrate one of N values.
+    const asserted = (s.stepsText.match(/\bsee \[[^\]]+\][^|]*?\b(?:with|contains) \{\{/g) ?? []).length;
+    if (asserted > 0 && asserted < claimed) out.push({ name: s.name, claimed, asserted, noun: m[2] });
+  }
+  return out;
+}
+
+/**
+ * A scenario whose priority tag contradicts the priority its viewpoint declares.
+ *
+ * The Priority-Viewpoints table is where release selection is supposed to come from. When the
+ * table says a flow is `Low` and its scenario is tagged `@high`, a smoke run picks up work the QA
+ * deliberately deprioritised — and nobody can tell which of the two was the decision (#622).
+ */
+export function priorityMismatches(
+  viewpointText: string, scenarios: ScenarioInfo[],
+): Array<{ id: string; declared: string; tagged: string; scenario: string }> {
+  const declared = new Map<string, string>();
+  for (const m of viewpointText.matchAll(/^\|\s*((?:VP|FL)[A-Z0-9._-]*)\s*\|\s*(critical|high|medium|normal|low|deferred)\s*\|/gim)) {
+    declared.set(m[1].toUpperCase(), m[2].toLowerCase());
+  }
+  if (declared.size === 0) return [];
+  // `medium` and `normal` are the same rank under different names in real documents.
+  const rank = (p: string): string => (p === 'medium' ? 'normal' : p);
+  const out: Array<{ id: string; declared: string; tagged: string; scenario: string }> = [];
+  for (const s of scenarios) {
+    const id = (s.vpId ?? '').toUpperCase();
+    if (!id) continue;
+    // The most specific declared row that prefixes this id.
+    const key = [...declared.keys()].filter((k) => id.startsWith(k)).sort((a, b) => b.length - a.length)[0];
+    if (!key) continue;
+    const want = rank(declared.get(key)!);
+    const got = rank(String(s.priority).toLowerCase());
+    // `critical` and `deferred` have no tag equivalent — nothing to contradict.
+    if (want === 'critical' || want === 'deferred') continue;
+    if (want !== got) out.push({ id: key, declared: declared.get(key)!, tagged: got, scenario: s.name });
+  }
+  return out;
+}

package/src/harness/viewpoint-ledger.ts

@@ -20,6 +20,39 @@ export interface LedgerResult {
   covered: number;
   ratio: number;
   missing: { id?: string; text: string }[];
+  /**
+   * Items whose id is carried ONLY by `@manual` scenarios. Accounted for — a documented
+   * procedure exists — but nothing runs, so a regression would not notice. Counted as covered
+   * (the claim IS addressed) and reported separately, the same split `FLOW-MANUAL-ONLY` makes
+   * for declared flows (#622).
+   */
+  manualOnly: { id?: string; text: string }[];
+  /**
+   * Items whose CLAIM names a count that the scenario carrying its id does not fully assert —
+   * "restores all six buffered values" proved on four fields. Exact id mapping shows a claim is
+   * ADDRESSED; it says nothing about whether the oracle demonstrates all of it (#622).
+   */
+  partial: { id?: string; text: string; claimed: number; asserted: number }[];
+}
+
+const NUMBER_WORDS: Record<string, number> = {
+  two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+};
+
+/** The count a claim names, when it names one: "all six values", "seven rows", "3 items". */
+function claimedCount(text: string): number | null {
+  // A digit after `step`/`screen`/`phase` is an ORDINAL, not a quantity — "the buffer exists at
+  // step 4" claims nothing about four of anything. And the counted thing has to be a noun: a
+  // function word after the number means the number was not counting.
+  const FUNCTION_WORD = /^(and|the|is|are|was|were|of|or|in|on|at|to|for|with|that|which|but|not|has|have|its)$/;
+  for (const m of text.toLowerCase().matchAll(/(\w+\s+)?\b(?:all\s+)?(two|three|four|five|six|seven|eight|nine|ten|[2-9]|10)\s+([a-z][a-z-]{2,})/g)) {
+    const before = (m[1] ?? '').trim();
+    if (/^(step|steps|screen|screens|phase|phases|page|pages|tier|round|part|section|version|mail_0?)$/.test(before)) continue;
+    if (FUNCTION_WORD.test(m[3])) continue;
+    const n = NUMBER_WORDS[m[2]] ?? Number(m[2]);
+    if (Number.isFinite(n) && n >= 2) return n;
+  }
+  return null;
 }
 
 const ID_RE = /\b([A-Z]{1,5}\d{0,2}(?:[.\-][A-Za-z0-9]+)*-?\d{0,3})\b/; // VP0.Title, VP7-002, MS-HP-001, TV-01
@@ -74,16 +107,43 @@ export function parseViewpointItems(viewpointPath: string): { id?: string; text:
 export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[], featureText: string): LedgerResult {
   const items = parseViewpointItems(viewpointPath);
   if (!fs.existsSync(viewpointPath) || items.length === 0) {
-    return { hasViewpoint: fs.existsSync(viewpointPath), total: 0, covered: 0, ratio: 1, missing: [] };
+    return { hasViewpoint: fs.existsSync(viewpointPath), total: 0, covered: 0, ratio: 1, missing: [], manualOnly: [], partial: [] };
   }
   const featLower = featureText.toLowerCase();
   const missing: { id?: string; text: string }[] = [];
+  const manualOnly: { id?: string; text: string }[] = [];
+  const partial: { id?: string; text: string; claimed: number; asserted: number }[] = [];
   let covered = 0;
 
   for (const item of items) {
-    let isCovered = false;
-    if (item.id && featLower.includes(item.id.toLowerCase())) isCovered = true;
-    else {
+    // WHEN AN ITEM DECLARES AN ID, THAT ID IS THE CONTRACT. It used to fall through to word
+    // matching when the id was absent from the suite, so an item whose id nobody carried was
+    // still counted covered on two shared non-generic words with ANY scenario. Two claims written
+    // deliberately WITHOUT a scenario were both scored covered — one on
+    // "confirmation"/"buffered", the other on "name"/"blocked". `atomicLedger 100%` then meant
+    // "no claim is more than two words away from some scenario", which is not a coverage
+    // statement at all, and the ledger could never report the gap it exists to report (#622).
+    //
+    // Word matching survives only where there is nothing better: a prose claim with no id.
+    let isCovered: boolean;
+    if (item.id) {
+      isCovered = featLower.includes(item.id.toLowerCase());
+      if (isCovered) {
+        // An id carried only by @manual scenarios is ADDRESSED but not RUNNING.
+        const carriers = scenarios.filter((s) => (s.vpId ?? '').toLowerCase() === item.id!.toLowerCase()
+          || s.haystack.includes(item.id!.toLowerCase()));
+        if (carriers.length > 0 && carriers.every((s) => s.manual)) manualOnly.push({ id: item.id, text: item.text });
+        // The count is in the CLAIM, not in the scenario title — so this is the only place both
+        // halves are in hand. `see all …` proves a set in one step and is exempt.
+        const n = claimedCount(item.text);
+        const auto = carriers.filter((s) => !s.manual);
+        if (n !== null && auto.length > 0 && !auto.some((s) => /\bsee all\b/.test(s.stepsText))) {
+          const asserted = Math.max(...auto.map((s) =>
+            (s.stepsText.match(/\bsee \[[^\]]+\][^|]*?\b(?:with|contains) \{\{/g) ?? []).length));
+          if (asserted > 0 && asserted < n) partial.push({ id: item.id, text: item.text, claimed: n, asserted });
+        }
+      }
+    } else {
       const words = [...new Set((item.text.toLowerCase().match(/[a-z][a-z-]{3,}/g) || []).filter((w) => !GENERIC.has(w)))];
       const need = Math.min(2, words.length);
       isCovered = words.length > 0 && scenarios.some((s) => words.filter((w) => s.haystack.includes(w)).length >= need);
@@ -92,7 +152,10 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
     else missing.push({ id: item.id, text: item.text });
   }
 
-  return { hasViewpoint: true, total: items.length, covered, ratio: items.length ? covered / items.length : 1, missing };
+  return {
+    hasViewpoint: true, total: items.length, covered,
+    ratio: items.length ? covered / items.length : 1, missing, manualOnly, partial,
+  };
 }
 
 /**

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,46 @@ 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.
+
+**If you find yourself writing it AFTER the suite, stop and say so.** That is not a neutral
+ordering choice: a yardstick derived from the scenarios reads 100% by construction, and anything
+dropped along the way stops being missing from anything. `sungen audit` now reports
+`VIEWPOINT-ADOPTED-POST-HOC` on the first sighting of a viewpoint alongside an existing suite and
+holds `atomicLedger` + `traceability` as unverified until a human accepts it — so the honest move
+is to write the claims from `spec.md` and the contract, mark plainly that they are a draft for QA
+review, and let the QA revise before `--accept-viewpoint`.
+
+**When you give a claim an id, a scenario must carry that id.** The id is the contract: a claim
+whose id no scenario carries is reported MISSING, and word overlap will not rescue it. Several
+scenarios may prove one claim, and a claim carried only by `@manual` scenarios is `ADDRESSED` but
+not running (`VIEWPOINT-ITEM-MANUAL-ONLY`) — do not let the delivery read it as automated coverage.
+
+**A claim that names a count must be proved that many times.** "restores all six buffered values"
+asserted on four fields is `CLAIM-PARTIAL`: mapping a claim to a scenario shows it is addressed,
+not that the oracle demonstrates it. Assert all of them, use one `see all …` set assertion, or
+narrow the claim to what is actually proven.
+
+**Priority comes from the declaration.** A scenario tagged `@high` under a viewpoint row that says
+`Low` is `PRIORITY-CONTRADICTED` — a smoke run selects on the tag, so it picks up work the QA
+deliberately deprioritised. Inherit the declared priority; if the tag is right, fix the
+declaration instead of leaving both on record.
+
 ---
 
 ## Platform detection (do this FIRST)