@sun-asterisk/sungen 3.2.24 → 3.2.26

package/src/harness/spec-branches.ts

@@ -0,0 +1,346 @@
+/**
+ * Mutually-exclusive branches declared in the spec, and whether each one has a scenario (#630).
+ *
+ * A field report hit the same gap three times in three different flows, in three different
+ * shapes: an `### Exception Flow A` heading left entirely blank; a decision table
+ * (`DEC-003_EmptyStateCascade`) whose three arms produced ONE covered arm and two
+ * scenarios verifying that same arm under different names; and a pseudocode block with two
+ * attention-hint branches where only the first got a case.
+ *
+ * The narrative rule already existed — "AND condition → test each branch failing independently",
+ * "business rule → 1 behavioural TC per rule". It was missed anyway, three times. So the
+ * reviewers' own conclusion is the design here: what works is an ENFORCED enumeration, the way
+ * `Viewpoint items` are enumerated and completeness-checked, not another sentence of guidance.
+ *
+ * Deliberately conservative. A branch is only claimed when the spec makes the enumeration
+ * explicit — a named heading, a table that declares conditions and outcomes, or an if/else
+ * cascade — because a false "you missed a branch" costs more trust than it buys coverage.
+ */
+import { ScenarioInfo } from './parse';
+
+export interface SpecBranch {
+  /** Stable id for the message: the block name plus the arm. */
+  id: string;
+  /** The distinctive token the suite is expected to cite. */
+  label: string;
+  kind: 'exception-flow' | 'alternative-flow' | 'decision-arm' | 'pseudocode-arm';
+  /** Where it was found, so the author can go and read it. */
+  source: string;
+}
+
+/**
+ * CamelCase identifiers only — an outcome LABEL (`StateNoItems`, `HintPrimary`).
+ *
+ * SCREAMING_SNAKE was in this pattern and produced two false branches on a real spec:
+ * `DEFAULT_FILTER` from `conditions !== DEFAULT_FILTER` and `MESSAGE_READ` from a permission check.
+ * Those are OPERANDS inside a condition, not arms of it — a constant names a value, an outcome
+ * names a result. Shape alone cannot tell them apart, so the shape that only outcomes use is the
+ * one to match (#651 follow-up).
+ */
+const IDENTIFIER = /\b([A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)+)\b/g;
+
+/**
+ * Code references are not branch labels. A table cell citing
+ * `src/components/molecules/HomeBoard/AlertPanel.tsx` yielded four "branches" —
+ * AlertPanel, TaskPanel, FeaturedList, HomeBoard — none of which is a branch at all.
+ * Backticked spans and anything path-shaped go before identifiers are read.
+ */
+function withoutCodeRefs(text: string): string {
+  return text
+    .replace(/`[^`]*`/g, ' ')                                  // inline code spans
+    .replace(/\[[^\]]*\]\([^)]*\)/g, ' ')                       // markdown links
+    .replace(/\S*\/\S*/g, ' ')                                 // any path-like token
+    .replace(/\b\w+\.(?:tsx?|jsx?|vue|py|rb|go|java|kt|swift|md|ya?ml|json)\b/gi, ' ');
+}
+/** A named decision/rule block: `DEC-003_Foo`, `BR-001_Bar`, `ALG-002`. */
+const NAMED_BLOCK = /\b((?:DEC|BR|ALG|RULE|DISC)-\d+)(?:_([A-Za-z0-9]+))?\b/;
+
+const HEADING = /^(#{1,6})\s+(.*)$/;
+
+/**
+ * Split a markdown document into `{ heading, lines }` sections, so a table or fence can be
+ * attributed to the block that names it.
+ */
+function sections(text: string): Array<{ heading: string; lines: string[] }> {
+  const out: Array<{ heading: string; lines: string[] }> = [{ heading: '', lines: [] }];
+  for (const raw of text.split('\n')) {
+    const h = raw.match(HEADING);
+    if (h) out.push({ heading: h[2].replace(/[*`]/g, '').trim(), lines: [] });
+    else out[out.length - 1].lines.push(raw);
+  }
+  return out;
+}
+
+/** Does this table declare CONDITIONS mapping to OUTCOMES (a decision table)? */
+function isDecisionTable(header: string[], sectionHeading: string): boolean {
+  const cells = header.map((c) => c.toLowerCase());
+  // A Given/When/Then table is a list of TEST CASES, not a decision to enumerate — each row is
+  // already a case. It matched on `when`+`then` and turned a real spec's test-case table into
+  // five phantom branches (#651 follow-up).
+  const isGherkinTable = cells.some((c) => /\bgiven\b/.test(c)) && cells.some((c) => /\bwhen\b/.test(c))
+    && cells.some((c) => /\bthen\b/.test(c));
+  const isTestCaseTable = cells.some((c) => /test[- ]?id|tc[- ]?id|case[- ]?id/.test(c));
+  if (isGherkinTable || isTestCaseTable) return false;
+  const hasCondition = cells.some((c) => /condition|case|when|input|state|flag|criteria|nhánh|điều kiện/.test(c));
+  const hasOutcome = cells.some((c) => /outcome|result|then|display|shows?|expected|action|behaviou?r|kết quả/.test(c));
+  // A block the spec itself NAMES as a decision counts even if its columns are worded oddly.
+  return (hasCondition && hasOutcome) || /\b(?:DEC|decision|cascade|matrix)\b/i.test(sectionHeading);
+}
+
+export function specBranches(specText: string): SpecBranch[] {
+  const out: SpecBranch[] = [];
+  const seen = new Set<string>();
+  const push = (b: SpecBranch): void => {
+    const k = `${b.id}|${b.label}`;
+    if (seen.has(k)) return;
+    seen.add(k);
+    out.push(b);
+  };
+
+  for (const sec of sections(specText)) {
+    // 1. An `### Exception Flow A` / `### Alternative Flow 2` heading IS one branch. Unambiguous.
+    const flowH = sec.heading.match(/^(exception|alternative|alternate)\s+flow\s*([A-Z0-9][\w-]*)?/i);
+    if (flowH) {
+      const label = sec.heading;
+      push({
+        id: label, label,
+        kind: /^exception/i.test(flowH[1]) ? 'exception-flow' : 'alternative-flow',
+        source: `heading "${sec.heading}"`,
+      });
+      continue;
+    }
+
+    const named = sec.heading.match(NAMED_BLOCK);
+    const blockName = named ? named[0] : sec.heading;
+
+    // 2. A decision table: each data row is one arm. Matched on the identifier the row names.
+    const rows = sec.lines.filter((l) => l.trim().startsWith('|') && !/^\|[\s|:-]+\|?$/.test(l.trim()));
+    if (rows.length >= 3) {                       // header + at least two arms
+      const header = rows[0].split('|').map((c) => c.trim()).filter(Boolean);
+      if (isDecisionTable(header, sec.heading)) {
+        for (const row of rows.slice(1)) {
+          const ids = [...withoutCodeRefs(row).matchAll(IDENTIFIER)].map((m) => m[1]);
+          // Only an identifier is distinctive enough to look for in a suite; a prose condition
+          // would match half the feature file.
+          for (const id of ids) push({ id: `${blockName}:${id}`, label: id, kind: 'decision-arm', source: `decision table under "${sec.heading}"` });
+        }
+      }
+    }
+
+    // 3. An if/elif/else cascade in a fenced block: each arm that NAMES an outcome identifier.
+    let inFence = false;
+    let fence: string[] = [];
+    for (const l of sec.lines) {
+      if (l.trim().startsWith('```')) {
+        if (inFence) {
+          const body = fence.join('\n');
+          const arms = (body.match(/\b(?:else\s+if|elif|if|else)\b/g) ?? []).length;
+          if (arms >= 2) {
+            for (const m of withoutCodeRefs(body).matchAll(IDENTIFIER)) {
+              push({ id: `${blockName}:${m[1]}`, label: m[1], kind: 'pseudocode-arm', source: `pseudocode under "${sec.heading}"` });
+            }
+          }
+          fence = [];
+        }
+        inFence = !inFence;
+        continue;
+      }
+      if (inFence) fence.push(l);
+    }
+  }
+  return out;
+}
+
+/**
+ * Branches with no scenario citing them. A citation counts anywhere in the feature text —
+ * title, steps or a comment — because an author who deliberately excludes a branch writes the
+ * reason as a comment, and that is an accounting, not a gap.
+ */
+const GENERIC_WORD = new Set([
+  'flow', 'exception', 'alternative', 'alternate', 'the', 'and', 'with', 'without', 'when', 'then',
+  'user', 'visitor', 'screen', 'page', 'from', 'that', 'this', 'case', 'gate', 'step',
+]);
+
+export function unenumeratedBranches(branches: SpecBranch[], featureText: string): SpecBranch[] {
+  const hay = featureText.toLowerCase();
+  return branches.filter((b) => {
+    // An IDENTIFIER is precise — require it verbatim. A HEADING is prose the author will
+    // rephrase ("Exception Flow A — drawer confirm gate" becomes "closing the drawer without
+    // confirming"), so match on its distinctive words instead: demanding the heading verbatim
+    // would report a branch that is covered under a better name.
+    if (b.kind === 'decision-arm' || b.kind === 'pseudocode-arm') return !hay.includes(b.label.toLowerCase());
+    const words = [...new Set((b.label.toLowerCase().match(/[a-z][a-z-]{3,}/g) ?? []))]
+      .filter((w) => !GENERIC_WORD.has(w));
+    if (words.length === 0) return !hay.includes(b.label.toLowerCase());
+    const hits = words.filter((w) => hay.includes(w)).length;
+    return hits < Math.min(2, words.length);
+  });
+}
+
+/**
+ * Scenarios whose assertions are IDENTICAL — "N cases" in a coverage sheet that verify one arm N
+ * times. The field report's decision table produced exactly this: two cases under different
+ * names, both asserting the same message, reported as two covered branches.
+ *
+ * Compares only the assertion side: two scenarios may legitimately share setup and differ in
+ * what they prove, but if what they PROVE is identical they are one test.
+ */
+export function sameOracleClusters(scenarios: ScenarioInfo[]): Array<{ oracle: string; scenarios: string[] }> {
+  const byOracle = new Map<string, string[]>();
+  for (const s of scenarios) {
+    if (s.manual) continue;                     // a procedure's oracle is prose
+    const asserts = [...(s.steps ?? [])]
+      .filter((st) => st.bucket === 'then')
+      .map((st) => st.text.toLowerCase().replace(/\s+/g, ' ').trim())
+      .sort();
+    if (asserts.length === 0) continue;
+    const key = asserts.join(' ; ');
+    byOracle.set(key, [...(byOracle.get(key) ?? []), s.name]);
+  }
+  return [...byOracle.entries()]
+    .filter(([, names]) => names.length > 1)
+    .map(([oracle, names]) => ({ oracle: oracle.slice(0, 100), scenarios: names }))
+    .sort((a, b) => b.scenarios.length - a.scenarios.length);
+}
+
+/**
+ * A "denied → hidden" scenario with no "allowed → shown" counterpart (#630).
+ *
+ * Two security cases proved that chat content is hidden when `MESSAGE_READ` is denied. If the code
+ * hid it unconditionally — ignoring the permission entirely — both still pass. The deny side alone
+ * cannot distinguish "the guard works" from "the feature is broken for everyone", so the pair is
+ * the test, exactly as `min-1 / min / max / max+1` is the test for a boundary.
+ *
+ * The mirror of the negative-claim rule the skill already has, on the other side.
+ */
+const DENY_SHAPE = /\b(?:denied|deny|denies|forbidden|not authoriz\w*|unauthoriz\w*|no permission|without (?:the )?(?:permission|right|access|flag)|permission (?:is )?off|flag (?:is )?off|revoked|restricted)\b/i;
+const HIDDEN_SHAPE = /\b(?:is hidden|are hidden|not (?:visible|shown|displayed)|blocked|masked|redacted|does not (?:show|render|appear))\b/i;
+const ALLOW_SHAPE = /\b(?:granted|allowed|permitted|authoriz\w*|has (?:the )?(?:permission|right|access)|permission (?:is )?on|flag (?:is )?on|with (?:the )?(?:permission|right|access))\b/i;
+
+export function permissionPairGaps(
+  scenarios: ScenarioInfo[],
+): Array<{ scenario: string; subject: string[] }> {
+  const denies = scenarios.filter((s) => DENY_SHAPE.test(s.haystack) && HIDDEN_SHAPE.test(s.haystack));
+  if (denies.length === 0) return [];
+  const allows = scenarios.filter((s) => ALLOW_SHAPE.test(s.haystack) && !HIDDEN_SHAPE.test(s.stepsText));
+  // Words only — the scenario ID is stripped first, because `[a-z][a-z-]{4,}` happily matches
+  // `fl-er-` and an id fragment can never appear in the counterpart's title, so demanding it made
+  // the pair impossible to find.
+  const distinctive = (s: ScenarioInfo): string[] =>
+    [...new Set((s.name.replace(/^\S+\s*/, '').toLowerCase().match(/[a-z]{5,}/g) ?? []))]
+      .filter((w) => !GENERIC_WORD.has(w) && !/denied|denies|hidden|permission|scenario/.test(w));
+  const out: Array<{ scenario: string; subject: string[] }> = [];
+  for (const d of denies) {
+    const subject = distinctive(d);
+    // The counterpart has to be about the SAME thing — two shared distinctive words, the same
+    // bar the ledger's prose matching uses.
+    const paired = allows.some((a) => subject.filter((w) => a.haystack.includes(w)).length >= Math.min(2, subject.length));
+    if (!paired) out.push({ scenario: d.name, subject: subject.slice(0, 4) });
+  }
+  return out;
+}
+
+/**
+ * Scenarios blocked on test data that is still a placeholder (#630).
+ *
+ * A deliverable reported "Pending" for a case whose design was finished and whose only blocker was
+ * an unseeded ENV-BOUND value — indistinguishable, on the report, from a case with an unresolved
+ * design problem. One is a data task, the other is test work; they should not read the same.
+ */
+const SEED_PLACEHOLDER = /^(?:TODO[_-]?SEED\w*|TODO|TBD|<[^>]+>|REPLACE[_-]?ME|FILL[_-]?ME|CHANGE[_-]?ME|XXX+)$/i;
+
+export function awaitingSeedData(
+  testDataText: string, scenarios: ScenarioInfo[],
+): Array<{ key: string; scenarios: string[] }> {
+  // One placeholder key is ONE data task, however many files or lines mention it — a real project
+  // reported the same key three times because its overlays each declare it (#651 follow-up).
+  const placeholders = [...new Set(
+    [...testDataText.matchAll(/^\s*([A-Za-z0-9_.-]+)\s*:\s*["']?([^"'\n#]+?)["']?\s*(?:#.*)?$/gm)]
+      .filter((m) => SEED_PLACEHOLDER.test(m[2].trim()))
+      .map((m) => m[1]),
+  )];
+  if (placeholders.length === 0) return [];
+  return placeholders
+    .map((key) => ({
+      key,
+      scenarios: scenarios.filter((s) => s.stepsText.includes(`{{${key.toLowerCase()}`)
+        || new RegExp(`\\{\\{[a-z0-9_.-]*\\.${key.toLowerCase()}\\}\\}`).test(s.stepsText)).map((s) => s.name),
+    }))
+    .filter((p) => p.scenarios.length > 0);
+}
+
+/**
+ * The fixed risk catalog for a multi-screen journey, reconciled against the flow (#651 F1-7).
+ *
+ * `SPEC-BRANCH-UNCOVERED` enforces the branches a spec DECLARES. This is the other half, and the
+ * one a field report asked for explicitly: the risks a spec is often SILENT about, which a
+ * reviewer notices and a generator does not. Their words — *"cả 2 flow đều thiếu 2-3 nhóm trong
+ * danh sách này, không phải vì không áp dụng mà vì không có bước bắt buộc rà lại checklist đó
+ * trước khi coi flow 'đủ'"*.
+ *
+ * The same families as the step × risk matrix in `sungen-tc-generation`, so guidance and gate
+ * cannot drift apart. A family counts as CONSIDERED when it is mentioned anywhere the author
+ * reasons: a declared flow's branch point, outcome or reason; a scenario; or the viewpoint. That
+ * makes "we thought about it and it does not apply" a one-line answer — the accounting the flow
+ * inventory already asks for — rather than a scenario nobody needs.
+ */
+export interface RiskFamily {
+  id: string;
+  label: string;
+  /** What the author writes when they HAVE considered it. */
+  re: RegExp;
+  /** Why it bites on a multi-screen journey specifically. */
+  why: string;
+}
+
+export const MULTI_SCREEN_RISKS: RiskFamily[] = [
+  { id: 'double-submit', label: 'double submit / double activation',
+    re: /\b(?:double[- ]?(?:submit|click|tap|activation)|twice|two taps?|idempoten\w*|re-?submit|duplicate request)\b/i,
+    why: 'a second activation before the first response is the classic way one journey creates two records' },
+  { id: 'concurrency', label: 'two tabs / two devices at once',
+    re: /\b(?:two tabs?|second tab|another tab|multi[- ]?tab|two devices|second device|concurrent\w*|simultaneous\w*|race)\b/i,
+    why: 'a journey that buffers state client-side behaves differently when two of it run at once' },
+  { id: 'client-buffer', label: 'client-side buffer kept / lost',
+    re: /\b(?:session ?storage|local ?storage|buffer\w*|draft|unsaved|re-?hydrat\w*|restore[sd]?)\b/i,
+    why: 'state held between two steps must be proved BOTH ways — it survives a legitimate return, and it is lost when the spec says it is' },
+  { id: 'server-error', label: 'a mid-journey server error',
+    re: /\b(?:server error|5\d{2}\b|network (?:error|drop|failure)|offline|timeout|unavailable|fails? server-?side|retry)\b/i,
+    why: 'the interesting question is what survives the failure, not that an error appeared' },
+  { id: 'abandonment', label: 'abandonment / TTL of partial state',
+    re: /\b(?:abandon\w*|lapse[sd]?|expir\w*|ttl\b|stale|cleanup|24 ?h|dormant|never (?:completed|finished))\b/i,
+    why: 'a journey stopped halfway leaves state somebody owns; a flow test is where that becomes visible' },
+  { id: 'direct-access', label: 'direct URL access to a later step',
+    re: /\b(?:direct(?:ly)? access|deep[- ]?link|without (?:a |an |the )?(?:context|session|prior)|guard|not skippable|redirect\w*)\b/i,
+    why: 'every step after the first is reachable by URL, and only a journey test can check the guard' },
+  { id: 'auth-transition', label: 'where the session begins',
+    re: /\b(?:authenticat\w*|unauthenticat\w*|signed[- ]in|logged[- ]in|session (?:is )?(?:established|created|begins)|auto[- ]?login)\b/i,
+    why: 'the step where an actor stops being anonymous is a boundary no single screen owns' },
+  { id: 'escape-hatch', label: 'a documented way out of the journey',
+    re: /\b(?:cancel|back to top|exit|leave[sd]? the (?:journey|flow)|opt[- ]?out|skip|dismiss)\b/i,
+    why: 'a designed-for exit is an alternate flow with its own outcome, not an error' },
+  { id: 'side-effect-order', label: 'ordering of a delayed side effect',
+    re: /\b(?:mail|email|notification|webhook|queue|async|delayed|eventual\w*|dispatch\w*|side[- ]effect)\b/i,
+    why: 'a journey that triggers an out-of-band effect is where its ordering and its absence both matter' },
+];
+
+export function unconsideredRisks(
+  contract: FlowContractLike, scenarios: ScenarioInfo[], viewpointText: string,
+): RiskFamily[] {
+  // Everywhere the author reasons about the journey. A mention in ANY of them is consideration —
+  // the check asks "did you think about this?", not "did you write a scenario for it?".
+  const corpus = [
+    viewpointText,
+    ...scenarios.map((s) => s.haystack),
+    ...(contract.flows ?? []).flatMap((f) => [f.id, f.branchFrom ?? '', f.outcome ?? '', f.reason ?? '']),
+    contract.minimalGuarantee ?? '', contract.successGuarantee ?? '', contract.precondition ?? '',
+  ].join('\n').toLowerCase();
+  return MULTI_SCREEN_RISKS.filter((r) => !r.re.test(corpus));
+}
+
+/** The slice of the contract this needs — kept structural so the module stays import-light. */
+export interface FlowContractLike {
+  flows?: Array<{ id: string; branchFrom?: string; outcome?: string; reason?: string }>;
+  minimalGuarantee?: string;
+  successGuarantee?: string;
+  precondition?: string;
+}

package/src/harness/spec-coverage.ts

@@ -206,7 +206,7 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
 /**
  * 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",
+ * A flow spec typically cites its requirements as belonging elsewhere — "SCREEN_A_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)
@@ -221,12 +221,12 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
 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".
+  // "these ... originate in the SCREEN specs", "restated here", "per SCREEN_A_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`,
+  // External document ids carrying their own requirement number: `SCREEN_A_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
+  // A citation may name SEVERAL documents at once — "SCREEN_A_002/SCREEN_A_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]+)+';

package/src/harness/viewpoint-baseline.ts

@@ -35,11 +35,18 @@ export interface ViewpointBaseline {
   added?: string[];
   removed?: string[];
   recordedAt?: string;
+  /**
+   * The recorded ids came from an EARLIER parser and the file itself is untouched, so the two
+   * id sets cannot be compared. Not a change — and not a confirmation either.
+   */
+  reparsed?: boolean;
+  /** sha1 of the file's own bytes — the only fingerprint a parser upgrade cannot move. */
+  fileHash?: string;
 }
 
 interface BaselineFile {
   version: 1;
-  units: Record<string, { hash: string; ids: string[]; recordedAt: string }>;
+  units: Record<string, { hash: string; ids: string[]; recordedAt: string; fileHash?: string }>;
 }
 
 function baselinePath(projectRoot: string): string {
@@ -71,6 +78,21 @@ function fingerprint(ids: string[]): string {
   return crypto.createHash('sha1').update(ids.join('\n')).digest('hex').slice(0, 12);
 }
 
+/**
+ * Fingerprint the FILE, not the parse.
+ *
+ * The baseline compared the ids the CURRENT parser extracts against the ids the parser
+ * recorded — so improving the parser looked exactly like the author rewriting the declaration.
+ * A real project upgrading across versions was told its viewpoint "no longer declares what it
+ * did", had two axes withheld and its score capped, over a file nobody had touched. The bytes
+ * are the one thing only an edit can move (#657).
+ */
+function fileFingerprint(viewpointPath: string): string {
+  try {
+    return crypto.createHash('sha1').update(fs.readFileSync(viewpointPath)).digest('hex').slice(0, 12);
+  } catch { return ''; }
+}
+
 /**
  * Compare the unit's current test-viewpoint declaration to the recorded baseline.
  * Read-only — recording is the caller's decision, so an audit stays a measurement
@@ -85,12 +107,23 @@ export function checkViewpointBaseline(
   if (!fs.existsSync(viewpointPath)) return { status: 'absent', hash: '', ids: [] };
   const ids = parseViewpointOverview(viewpointPath).map((v) => v.id).sort();
   const hash = fingerprint(ids);
+  const fileHash = fileFingerprint(viewpointPath);
   if (ids.length === 0) return { status: 'absent', hash: '', ids: [] };
 
   const file = readBaselineFile(projectRoot);
   const recorded = file.units[unitId];
-  if (!recorded) return { status: 'new', hash, ids };
-  if (recorded.hash === hash) return { status: 'unchanged', hash, ids, recordedAt: recorded.recordedAt };
+  if (!recorded) return { status: 'new', hash, ids, fileHash };
+  if (recorded.hash === hash) return { status: 'unchanged', hash, ids, fileHash, recordedAt: recorded.recordedAt };
+  // Same bytes, different parse — the parser moved, the declaration did not.
+  if (recorded.fileHash && fileHash && recorded.fileHash === fileHash) {
+    return { status: 'unchanged', hash, ids, fileHash, reparsed: true, recordedAt: recorded.recordedAt };
+  }
+  // A baseline recorded before file fingerprinting cannot distinguish the two, and every
+  // project upgrading across that boundary would be accused once. Re-baseline instead of
+  // accusing, and say why: the alternative is a certain false alarm for everyone.
+  if (!recorded.fileHash) {
+    return { status: 'unchanged', hash, ids, fileHash, reparsed: true, recordedAt: recorded.recordedAt };
+  }
 
   const before = new Set(recorded.ids ?? []);
   const now = new Set(ids);
@@ -98,6 +131,7 @@ export function checkViewpointBaseline(
     status: 'changed',
     hash,
     ids,
+    fileHash,
     added: ids.filter((i) => !before.has(i)),
     removed: (recorded.ids ?? []).filter((i) => !now.has(i)),
     recordedAt: recorded.recordedAt,
@@ -108,21 +142,22 @@ export function checkViewpointBaseline(
 export function acceptViewpointBaseline(
   projectRoot: string,
   unitId: string,
-  current: { hash: string; ids: string[] },
+  current: { hash: string; ids: string[]; fileHash?: string },
 ): void {
   const file = readBaselineFile(projectRoot);
   file.units[unitId] = {
     hash: current.hash,
     ids: current.ids,
     recordedAt: new Date().toISOString(),
+    ...(current.fileHash ? { fileHash: current.fileHash } : {}),
   };
   writeBaselineFile(projectRoot, file);
 }
 
 /** Read the declaration without recording anything (used by `--accept-viewpoint`). */
-export function readViewpointDeclaration(viewpointPath: string): { hash: string; ids: string[] } | null {
+export function readViewpointDeclaration(viewpointPath: string): { hash: string; ids: string[]; fileHash: string } | null {
   if (!fs.existsSync(viewpointPath)) return null;
   const ids = parseViewpointOverview(viewpointPath).map((v) => v.id).sort();
   if (ids.length === 0) return null;
-  return { hash: fingerprint(ids), ids };
+  return { hash: fingerprint(ids), ids, fileHash: fileFingerprint(viewpointPath) };
 }

package/src/harness/viewpoint-ledger.ts

@@ -69,6 +69,19 @@ const PLACEHOLDER_ITEM = /^(none\b|n\/a\b|tbd\b|no known\b|nothing\b|do not inve
 /** A priority-DECLARATION row: `| VP-LOGIC | High | <reason prose> |`. The category id and its
  *  priority are consumed by the traceability + balance axes; the reason is rationale. */
 const PRIORITY_ROW = /^(?:VP|FL)[A-Z0-9._-]*\s+—\s+(?:critical|high|medium|normal|low|deferred)\b/i;
+/**
+ * Whole SECTIONS that declare something ABOUT the checklist rather than listing claims to prove.
+ *
+ * The row-shape filter above only caught a Priority row that happened to look like one, so a
+ * project that fenced its prose still had its `Known Issues` TABLE rows counted as uncovered
+ * claims (PC-06/07/08/10 in a field report) — and one id listed in both `Known Issues` and
+ * `Deferred` was counted as two separate gaps (#630). Excluding by section covers rows and prose
+ * uniformly, which is what the row filter could never do.
+ *
+ * `Design Decisions` deliberately stays IN: "values are buffered between step 3 and 4, a reload
+ * loses them" is a real claim, and it is what the continuity check reads.
+ */
+const DECLARATION_SECTION = /^(?:known issues?|open questions?|deferred|out of scope|viewpoint grouping|traceability|metadata|scope|journey phases?|revision history|references?|sources?|changelog)\b/i;
 const GENERIC = new Set(['display', 'shown', 'value', 'field', 'input', 'page', 'screen', 'button', 'link', 'text', 'check', 'verify', 'should', 'with', 'when', 'then', 'user', 'this', 'that', 'each', 'item', 'items']);
 
 /** Extract atomic checklist items from a viewpoint file (format-tolerant). */
@@ -77,26 +90,60 @@ export function parseViewpointItems(viewpointPath: string): { id?: string; text:
   const lines = readTextFile(viewpointPath).split('\n');
   const items: { id?: string; text: string }[] = [];
   let inFence = false;
+  let inDeclarationSection = false;
+  // The level an excluded section was opened at. A SUBSECTION inherits it: `### Optional`
+  // nested under `## 8. Traceability Index` used to re-open the section and hand its rows
+  // back as claims, because exclusion was recomputed from scratch at every heading.
+  let excludedAt: number | null = null;
   for (const raw of lines) {
     const line = raw.trim();
     if (line.startsWith('```')) { inFence = !inFence; continue; }
     if (inFence || !line) continue;
-    if (/^#{1,6}\s/.test(line)) continue;                 // markdown heading
+    const heading = line.match(/^(#{1,6})\s+(.*)$/);
+    if (heading) {
+      const level = heading[1].length;
+      if (excludedAt !== null && level > excludedAt) continue;   // still inside the excluded section
+      // A heading both ends the previous section and decides whether this one declares or claims.
+      // Strip an ordinal prefix ("## 5. Known Issues", "## 8. Viewpoint Grouping") before
+      // testing. The regex anchors at the start, so a NUMBERED heading matched nothing and
+      // every excluded section leaked its rows back in as claims — a real viewpoint numbers
+      // its sections, so in practice the exclusion list was doing nothing at all (#657).
+      const headText = heading[2].replace(/[*`]/g, '').replace(/^\s*(?:\d+|[A-Z])\s*[.):]\s*/, '').trim();
+      inDeclarationSection = DECLARATION_SECTION.test(headText);
+      excludedAt = inDeclarationSection ? level : null;
+      continue;
+    }
+    if (inDeclarationSection) continue;
     let text = '';
+    let lead = '';
     const bullet = line.match(/^(?:[-*+]|\d+[.)])\s+(.*)$/);
-    if (bullet) text = bullet[1];
+    if (bullet) { text = bullet[1]; lead = bullet[1]; }
     else if (line.startsWith('|')) {                       // table data row
       if (/^\|[\s|:-]+\|?$/.test(line)) continue;           // separator
       const cells = line.split('|').map((c) => c.trim()).filter(Boolean);
       if (/^(vp|id|viewpoint|priority|reason|no\.?|category|item|trigger|#|pattern|applicable|notes|field|constraint|code|description|status|step|flow|ref|level|question|screen|actor|branches from|own steps|component|thành phần|trường|bước)$/i.test(cells[0] || '')) continue; // header
       text = cells.join(' — ');
+      lead = cells[0] ?? '';
     } else continue;
     text = text.replace(/[*`]/g, '').trim();
     if (!text) continue;
     if (PLACEHOLDER_ITEM.test(text)) continue;   // "None on file yet" is not a claim
     if (PRIORITY_ROW.test(text)) continue;       // priority declaration, not a checklist item
-    const idM = text.match(ID_RE);
+    // WHICH id a row declares is decided by its LEAD — the first table cell, or the start of
+    // the bullet. Ids further along are references ("KHÔNG kiểm nội dung — đã test ở VP-X-001"),
+    // and a well-formed claim cites its neighbours all the time. Reading the whole row instead
+    // made a citation look like a second declaration of somebody else's id.
+    const leadClean = lead.replace(/[*`]/g, '').trim();
+    // Several ids IN THE LEAD is an index line, not a claim — `- VP-A-001, VP-A-002, VP-A-003`
+    // under a grouping section. It declares nothing; it points at things declared elsewhere.
+    const leadIds = new Set((leadClean.match(new RegExp(ID_RE.source, 'g')) || []).filter((x) => /\d/.test(x)));
+    if (leadIds.size > 1) continue;
+    const idM = leadClean.match(ID_RE) ?? text.match(ID_RE);
     const id = idM && /\d/.test(idM[1]) ? idM[1] : undefined; // require a digit so prose words aren't IDs
+    // A row keyed by a bare GROUP prefix ("VP-LOGIC — transitions — High — why the flow exists")
+    // declares a family and its priority, not a checklist item: nothing can "cover" it, and
+    // demanding coverage sends the author looking for a test that was never meant to exist.
+    if (/^VP-[A-Z]+\s*(?:—|-|\||$)/.test(leadClean) && !/\d/.test(leadClean)) continue;
     const words = (text.toLowerCase().match(/[a-z][a-z-]{3,}/g) || []).filter((w) => !GENERIC.has(w));
     if (!id && words.length < 2) continue;                 // not substantive enough to track
     items.push({ id, text: text.slice(0, 100) });
@@ -105,7 +152,12 @@ export function parseViewpointItems(viewpointPath: string): { id?: string; text:
 }
 
 export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[], featureText: string): LedgerResult {
-  const items = parseViewpointItems(viewpointPath);
+  // A literally repeated line is ONE claim. Deduped here rather than in the parser, because
+  // `viewpointIntegrity` needs the raw list to report an id that labels SEVERAL DIFFERENT claims
+  // (#622) — silently collapsing those would remove its input.
+  const seen = new Set<string>();
+  const items = parseViewpointItems(viewpointPath)
+    .filter((i) => { const k = `${i.id ?? ''}|${i.text}`; if (seen.has(k)) return false; seen.add(k); return true; });
   if (!fs.existsSync(viewpointPath) || items.length === 0) {
     return { hasViewpoint: fs.existsSync(viewpointPath), total: 0, covered: 0, ratio: 1, missing: [], manualOnly: [], partial: [] };
   }
@@ -170,19 +222,39 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
  * 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 }> = [
+const BROWSER_GESTURES: Array<{ gesture: string; re: RegExp; appSubstitute: RegExp; platform?: string }> = [
   { gesture: 'browser back', re: /\bbrowser(?:'s)?[ -]?(?:back|history)\b|\bhistory[ -]back\b/i,
-    appSubstitute: /\bclick \[[^\]]*back[^\]]*\]/i },
+    appSubstitute: /\bclick \[[^\]]*back[^\]]*\]/i, platform: 'web' },
   { gesture: 'browser reload/refresh', re: /\b(?:page |browser )?(?:reload|refresh)(?:ing|ed|es)?\b/i,
-    appSubstitute: /\bis on \[[^\]]+\] page\b/i },
+    appSubstitute: /\bis on \[[^\]]+\] page\b/i, platform: 'web' },
   { 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 },
+    appSubstitute: /\bis on \[[^\]]+\] page\b/i, platform: 'web' },
+
+  // The same class on mobile, where the vocabulary is different but the trap is identical: an
+  // in-app control is not the OS gesture. Android's hardware/system back does not run the
+  // screen's own handler unless the app wires it, and backgrounding can destroy an Activity that
+  // an in-app navigation never touches — so a defect that only appears on the OS path lives
+  // exactly in the substitution (#626). The check was web-only, so mobile flows were silent about
+  // the very risk it exists to catch.
+  { gesture: 'the OS/hardware back gesture', platform: 'mobile',
+    re: /\b(?:hardware|system|os|device|android|physical)[ -]?back\b|\bback (?:gesture|button|swipe)\b|\bswipe[ -]back\b/i,
+    appSubstitute: /\b(?:tap|click) \[[^\]]*back[^\]]*\]/i },
+  { gesture: 'backgrounding and resuming the app', platform: 'mobile',
+    re: /\b(?:background(?:ing|ed)?|foreground(?:ing|ed)?|app switcher|recent apps|minimi[sz]|resum(?:e|ing)|kill(?:ed|ing)? the app|force[ -]stop|process death)\b/i,
+    appSubstitute: /\b(?:tap|click) \[[^\]]+\]|is on \[[^\]]+\] screen\b/i },
+  { gesture: 'rotating the device', platform: 'mobile',
+    re: /\b(?:rotat(?:e|ing|ion)|landscape|portrait|orientation change)\b/i,
+    appSubstitute: /\bis on \[[^\]]+\] screen\b/i },
 ];
 
 export function browserGestureSubstitutions(
-  viewpointPath: string, scenarios: ScenarioInfo[],
+  viewpointPath: string, scenarios: ScenarioInfo[], platform?: string,
 ): Array<{ gesture: string; item: string }> {
   const out: Array<{ gesture: string; item: string }> = [];
+  // A gesture only applies where its platform does: "reload" means nothing on a native app, and
+  // "backgrounding" means nothing in a browser tab. An unknown platform checks everything, which
+  // is how the web-only set behaved before.
+  const applies = (g: { platform?: string }): boolean => !platform || !g.platform || g.platform === platform;
   // 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.
@@ -190,6 +262,7 @@ export function browserGestureSubstitutions(
   const automated = scenarios.filter((s) => !s.manual).map((s) => s.haystack);
   for (const item of parseViewpointItems(viewpointPath)) {
     for (const g of BROWSER_GESTURES) {
+      if (!applies(g)) continue;
       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;

package/src/index.ts

@@ -20,6 +20,7 @@ export type { ResolvedAppProfile } from './generators/test-generator/app-profile
 export type { MappedStep } from './generators/test-generator/step-mapper';
 export type { ParsedStep } from './generators/gherkin-parser';
 export { getPathCode, inferPath, resolvePathVariables } from './generators/test-generator/utils/path-inference';
+export { formatToRegexSource, formatToRegexLiteral, hasFormatToken } from './generators/test-generator/utils/format-pattern';
 export { LIST_MEMBER_ROLES } from './generators/test-generator/utils/selector-resolver';
 
 // --- Precondition-annotation override grammar (shared by the @query / @api driver codegen) ---