@sun-asterisk/sungen 3.2.32 → 3.2.34-beta.1

package/src/harness/triage.ts

@@ -0,0 +1,127 @@
+/**
+ * `sungen triage` — classify each red or flaky scenario of a run into exactly one class, with the
+ * rule that fired and one evidence line. Deterministic and read-only; it reports, it never gates.
+ *
+ * Order (first match wins):
+ *   1. known-defect        `@known-defect` / `@known-defect:<id>` — an expected red.
+ *   2. blocked-capability  `@manual:*` / `@requires:*`, or skipped by design.
+ *   3. environment         the session or network never gave the test a usable app.
+ *   4. test-defect         the test could not reach its element or data.
+ *   5. product-candidate   an assertion whose Expected and Received both exist and differ.
+ *   6. unclassified        anything else — left for the agent or QA, with the raw first message.
+ * A `passed` scenario that needed a retry is `flaky` (green, listed separately).
+ *
+ * 5 is tested before 3 and 4 in code: a parsed Expected/Received pair that differs means the app
+ * answered, which outranks any wrapper text (a test timeout around the assertion included).
+ *
+ * A bare test timeout (no locator, no assertion) is `unclassified` too: a slow environment, a page
+ * that hangs on a product bug and a test waiting on the wrong thing all print the same line.
+ *
+ * An assertion on an element that never appeared (`Received: <element(s) not found>`) is NOT a test
+ * defect: a wrong selector and a missing message look identical, so it is left for judgment rather
+ * than hiding a possible product bug behind "fix the selector".
+ */
+import { redactSecrets } from '../exporters/api-testcase-formatter';
+import { parseExpectedReceived } from '../exporters/playwright-report-parser';
+import type { PlaywrightResult } from '../exporters/types';
+import { BARE_TIMEOUT, TRIAGE_SIGNALS } from './triage-signals';
+
+export type TriageClass =
+  | 'known-defect' | 'blocked-capability' | 'environment' | 'test-defect' | 'product-candidate' | 'unclassified' | 'flaky';
+
+export interface TriageInput {
+  unit: string;
+  title: string;
+  tags: string[];
+  result?: PlaywrightResult;
+  /** Result-file variant (`android`, `ios`, an env name) when the unit has several. */
+  variant?: string;
+}
+
+export interface TriageRow {
+  unit: string;
+  scenario: string;
+  variant?: string;
+  class: TriageClass;
+  ruleId: string;
+  evidence: string;
+  ids: string[];
+  legacy: string[];
+  defectId?: string;
+  tracePath?: string;
+  /** product-candidate only: the two halves of the assertion, for a defect draft. */
+  expected?: string;
+  received?: string;
+}
+
+const EVIDENCE_MAX = 200;
+const VIEWPOINT_ID = /\b(?:VP|FL)-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/gi;
+const ELEMENT_ABSENT = /Received:\s*<element\(s\) not found>/;
+
+/** The part of a message the run itself wrote: before `Call log:`, without `Locator:` echo lines. */
+const runHead = (m: string): string => m.split(/\n\s*Call log:/)[0].replace(/^\s*Locator:.*$/gm, '');
+
+/** Every failure message, stack frames and a leading `Error:` dropped. */
+function messagesOf(result: PlaywrightResult): string[] {
+  const raw = result.errorMessages?.length ? result.errorMessages : [result.error ?? ''];
+  return raw.map((m) => m.split(/\n\s*at\s/)[0].replace(/^Error:\s*/i, '').trim()).filter(Boolean);
+}
+
+function evidenceLine(text: string, secrets: string[]): string {
+  const flat = redactSecrets(text, secrets).replace(/\s+/g, ' ').trim();
+  return flat.length > EVIDENCE_MAX ? `${flat.slice(0, EVIDENCE_MAX - 1)}…` : flat;
+}
+
+/** Classify one scenario. Null when it needs no triage (clean pass, or never ran). */
+export function classifyScenario(input: TriageInput, secrets: string[] = []): TriageRow | null {
+  const { result, tags } = input;
+  if (!result) return null;
+  const base = {
+    unit: input.unit,
+    scenario: input.title,
+    ...(input.variant ? { variant: input.variant } : {}),
+    ids: [...new Set([input.title, ...tags].join(' ').match(VIEWPOINT_ID) ?? [])],
+    legacy: tags.filter((t) => t.startsWith('@legacy:')).map((t) => t.slice('@legacy:'.length)),
+    ...(result.tracePath ? { tracePath: result.tracePath } : {}),
+  };
+  const row = (cls: TriageClass, ruleId: string, evidence: string): TriageRow =>
+    ({ ...base, class: cls, ruleId, evidence: evidenceLine(evidence, secrets) });
+
+  if (result.status === 'passed') {
+    return (result.attempts ?? 1) > 1 ? row('flaky', 'passed-after-retry', `passed on attempt ${result.attempts}`) : null;
+  }
+  const messages = messagesOf(result);
+  const first = messages[0] ?? result.status;
+
+  const known = tags.find((t) => t === '@known-defect' || t.startsWith('@known-defect:'));
+  if (known) {
+    const r = row('known-defect', 'tag-known-defect', first);
+    const id = known.split(':')[1];
+    return id ? { ...r, defectId: id } : r;
+  }
+  if (tags.some((t) => t.startsWith('@manual'))) return row('blocked-capability', 'tag-manual', `${tags.find((t) => t.startsWith('@manual'))} — ${first}`);
+  if (tags.some((t) => t.startsWith('@requires:'))) return row('blocked-capability', 'tag-requires', `${tags.find((t) => t.startsWith('@requires:'))} — ${first}`);
+  if (result.status === 'skipped') return row('blocked-capability', 'status-skipped', 'skipped');
+
+  // An assertion with both halves decides the case even when a timeout wraps it.
+  for (const m of messages) {
+    const { expected, received } = parseExpectedReceived(m);
+    if (expected && received && !ELEMENT_ABSENT.test(m) && expected !== received) {
+      return { ...row('product-candidate', 'assertion-mismatch', `Expected ${expected} · Received ${received}`),
+        expected: evidenceLine(expected, secrets), received: evidenceLine(received, secrets) };
+    }
+  }
+  for (const s of TRIAGE_SIGNALS) {
+    // Environment signals read only what the RUN said, never the test's own selector text that a
+    // message echoes in `Locator:` / `Call log:` — `getByText('Invalid URL')` is a missing message,
+    // not a bad base URL. Test-defect signals need the call log (`waiting for …`), so they read it all.
+    const hit = messages.find((m) => s.match.test(s.class === 'environment' ? runHead(m) : m));
+    if (hit) return row(s.class, s.id, hit);
+  }
+  const absent = messages.find((m) => ELEMENT_ABSENT.test(m));
+  if (absent) return row('unclassified', 'assertion-element-absent', absent);
+  if (messages.length > 0 && messages.every((m) => BARE_TIMEOUT.test(m))) {
+    return row('unclassified', 'bare-timeout', `${first} No locator or assertion detail: a slow environment, a hanging page, or a wait in the test. Re-run once, then read the trace's last action.`);
+  }
+  return row('unclassified', 'no-signal', first);
+}

package/src/harness/ui-inventory.ts

@@ -0,0 +1,164 @@
+/**
+ * #811 — the design inventory: is every item the DESIGN shows accounted for by the suite?
+ *
+ * Design sources in `requirements/ui/` (images, `figma-meta.md`) and `requirements/spec_figma.md`
+ * were read "for visual context" and never turned into a checkable list, so a column that exists
+ * only on the design — or contradicts the spec — was missed by the author AND the reviewer, and a
+ * deliberate deferral looked exactly like an oversight.
+ *
+ * create-test now writes `requirements/ui-inventory.md`: one `UI-NNN` row per component / column /
+ * button / state / annotation, with its source (`spec+design` | `design-only` | `conflict`). An
+ * item is accounted for by a scenario tag (`@ui:UI-014`) or a reasoned deferral comment
+ * (`# UI-DEFERRED: UI-002..013 — <reason>`) — no other mention counts; ranges and `/`
+ * enumerations read the same way as spec ids (spec-coverage `citedIds`). `spec+design` items are already measured
+ * by spec-coverage, so only `design-only` / `conflict` items are reported uncovered.
+ *
+ * Advisory: findings never move the score or the gate.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { citedIds } from './spec-coverage';
+import { readTextFile } from './read-text';
+
+export type UiItemSource = 'spec+design' | 'design-only' | 'conflict';
+
+export interface UiItem {
+  id: string;
+  item: string;
+  kind: string;
+  source: UiItemSource;
+}
+
+export interface UiInventoryResult {
+  /** Design sources the unit holds: image files, figma-meta.md, spec_figma.md. */
+  designSources: string[];
+  /** `requirements/ui-inventory.md` exists. */
+  hasInventory: boolean;
+  items: UiItem[];
+  /** `images read: a/b` from the inventory header — null when the line is absent. */
+  imagesRead: { read: number; total: number } | null;
+  /** Images on disk, for comparing against `imagesRead.total`. */
+  imagesOnDisk: number;
+  covered: string[];
+  deferred: string[];
+  /** design-only / conflict items neither covered nor deferred. */
+  uncovered: UiItem[];
+}
+
+const IMAGE = /\.(png|jpe?g|webp|gif)$/i;
+
+/** Every design source in a unit's `requirements/` — what makes an inventory necessary. */
+export function designSourcesOf(reqDir: string): string[] {
+  const out: string[] = [];
+  const uiDir = path.join(reqDir, 'ui');
+  try {
+    for (const f of fs.readdirSync(uiDir).sort()) {
+      if (IMAGE.test(f) || f === 'figma-meta.md') out.push(`ui/${f}`);
+    }
+  } catch { /* no ui/ dir */ }
+  if (fs.existsSync(path.join(reqDir, 'spec_figma.md'))) out.push('spec_figma.md');
+  return out;
+}
+
+/**
+ * The Source cell, read leniently ("design only", "Spec + Design", "conflict — …"). Anything else
+ * is NOT assumed to be spec-backed: an unreadable source is reported like a design-only item, so a
+ * typo can never make an item disappear from the check.
+ */
+function sourceOf(cell: string): UiItemSource | null {
+  const c = cell.trim().toLowerCase();
+  if (/^design[\s_-]*only\b/.test(c)) return 'design-only';
+  if (/^conflict\b/.test(c)) return 'conflict';
+  if (/^spec\s*(?:\+|&|and)\s*design\b/.test(c)) return 'spec+design';
+  return null;
+}
+
+/**
+ * Parse the inventory table: any markdown row whose first cell is a `UI-<n>` id. Leading/trailing
+ * pipes are optional (GFM), and the Source cell is FOUND rather than counted — a `|` written inside
+ * the Item cell shifts the columns, and a positional read then misfiled a design-only row.
+ */
+export function parseUiInventory(text: string): { items: UiItem[]; imagesRead: UiInventoryResult['imagesRead'] } {
+  const items: UiItem[] = [];
+  for (const line of text.split('\n')) {
+    if (!line.includes('|')) continue;
+    const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+    if (!/^UI-\d+$/i.test(cells[0] ?? '')) continue;
+    // Source = the last cell that reads as one (Seen-in follows it; prose in Item never starts so).
+    let srcIdx = -1;
+    for (let i = cells.length - 1; i >= 2; i--) if (sourceOf(cells[i])) { srcIdx = i; break; }
+    const source: UiItemSource = srcIdx >= 0 ? sourceOf(cells[srcIdx])! : 'design-only';
+    const kindIdx = srcIdx >= 0 ? srcIdx - 1 : Math.min(2, cells.length - 1);
+    items.push({
+      id: cells[0].toUpperCase(),
+      item: cells.slice(1, Math.max(2, kindIdx)).join(' | '),
+      kind: cells[kindIdx] ?? '',
+      source,
+    });
+  }
+  const m = text.match(/images read:\s*(\d+)\s*\/\s*(\d+)/i);
+  return { items, imagesRead: m ? { read: Number(m[1]), total: Number(m[2]) } : null };
+}
+
+/**
+ * Ids cited on a `UI-DEFERRED` comment line — a deliberate, REASONED omission. A line that lists
+ * ids and nothing else is not a decision anyone can review, so it defers nothing.
+ */
+function deferredIds(featureText: string): Set<string> {
+  const lines = featureText.split('\n').filter((l) => {
+    if (!/^\s*#\s*UI-DEFERRED\b/i.test(l)) return false;
+    const reason = l.replace(/^\s*#\s*UI-DEFERRED\b\s*:?/i, '').replace(/\bUI-\d+(?:\s*(?:\.\.|–|—|~|\/)\s*(?:UI-)?\d+)*/gi, '');
+    return /[\p{L}]{3,}/u.test(reason);
+  });
+  return citedIds(lines.join('\n'));
+}
+
+export function uiInventoryCoverage(reqDir: string, featureText: string): UiInventoryResult {
+  const designSources = designSourcesOf(reqDir);
+  const invPath = path.join(reqDir, 'ui-inventory.md');
+  const invText = fs.existsSync(invPath) ? readTextFile(invPath) : null;
+  const { items, imagesRead } = invText ? parseUiInventory(invText) : { items: [], imagesRead: null };
+  // Coverage is the `@ui:` TAG, nothing else: a `UI-001`-shaped string elsewhere (an `@spec:UI-001`
+  // requirement in a project that numbers its FRs that way, prose, an unreasoned deferral line)
+  // must not mark a design item as proven.
+  const cites = citedIds((featureText.match(/@ui:\S+/gi) ?? []).join(' '));
+  const deferSet = deferredIds(featureText);
+  const covered: string[] = [];
+  const deferred: string[] = [];
+  const uncovered: UiItem[] = [];
+  for (const it of items) {
+    if (deferSet.has(it.id)) deferred.push(it.id);
+    else if (cites.has(it.id)) covered.push(it.id);
+    else if (it.source !== 'spec+design') uncovered.push(it);
+  }
+  return {
+    designSources,
+    hasInventory: invText !== null,
+    items,
+    imagesRead,
+    imagesOnDisk: designSources.filter((s) => IMAGE.test(s)).length,
+    covered,
+    deferred,
+    uncovered,
+  };
+}
+
+/** Advisory findings for the audit report. */
+export function uiInventoryFindings(r: UiInventoryResult): string[] {
+  const out: string[] = [];
+  if (r.designSources.length === 0) return out;
+  if (!r.hasInventory) {
+    out.push(`UI-INVENTORY-MISSING: the unit has design sources (${r.designSources.slice(0, 4).join(', ')}${r.designSources.length > 4 ? ', …' : ''}) but no \`requirements/ui-inventory.md\` — nothing shows the design was read item by item, so an item that exists only on the design (or contradicts the spec) is invisible to the gate and to review. Re-run /sungen:create-test so it writes the inventory, or write it by hand: one \`| UI-NNN | item | kind | spec+design / design-only / conflict |\` row per component, column, button, state and annotation.`);
+    return out;
+  }
+  if (r.imagesRead && r.imagesRead.read < Math.max(r.imagesRead.total, r.imagesOnDisk)) {
+    out.push(`UI-INVENTORY-INCOMPLETE: the inventory records "images read: ${r.imagesRead.read}/${r.imagesRead.total}" and the unit holds ${r.imagesOnDisk} image(s) — the unread design is not inventoried. Read the remaining images and add their items.`);
+  } else if (!r.imagesRead && r.imagesOnDisk > 0) {
+    out.push(`UI-INVENTORY-INCOMPLETE: the unit holds ${r.imagesOnDisk} image(s) but the inventory does not record "images read: N/N" — nothing shows every image was opened. Add the line after reading them all.`);
+  }
+  for (const it of r.uncovered.slice(0, 10)) {
+    out.push(`UI-ITEM-UNCOVERED: ${it.id} "${it.item}" (${it.kind}, ${it.source}) has no scenario and no deferral — ${it.source === 'conflict' ? 'the design and spec.md disagree on it; resolve which is right, then cover it' : 'it exists only on the design, outside spec.md'}. Cover it (\`@ui:${it.id}\` on the scenario that proves it), or record the decision: \`# UI-DEFERRED: ${it.id} — <reason>\`.`);
+  }
+  if (r.uncovered.length > 10) out.push(`UI-ITEM-UNCOVERED: … and ${r.uncovered.length - 10} more design-only/conflict item(s).`);
+  return out;
+}

package/src/harness/viewpoint-baseline.ts

@@ -2,6 +2,7 @@ import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import { parseViewpointOverview } from './parse';
+import { isAiDraft, removeDraftLine } from './viewpoint-draft-header';
 
 /**
  * Keep the yardstick from moving with the thing it measures.
@@ -89,7 +90,12 @@ function fingerprint(ids: string[]): string {
  */
 function fileFingerprint(viewpointPath: string): string {
   try {
-    return crypto.createHash('sha1').update(fs.readFileSync(viewpointPath)).digest('hex').slice(0, 12);
+    const bytes = fs.readFileSync(viewpointPath);
+    // `drafted-by: ai` is provenance that accept REMOVES, so it is not part of what was reviewed:
+    // counted, accepting a draft would read as the declaration changing. Every other byte stays raw.
+    const text = bytes.toString('utf-8');
+    const hashed = isAiDraft(text) ? Buffer.from(removeDraftLine(text), 'utf-8') : bytes;
+    return crypto.createHash('sha1').update(hashed).digest('hex').slice(0, 12);
   } catch { return ''; }
 }
 

package/src/harness/viewpoint-draft-header.ts

@@ -0,0 +1,55 @@
+import * as fs from 'fs';
+import { stripHtmlComments } from './read-text';
+import { writeFileAtomic } from './write-atomic';
+
+/**
+ * `drafted-by: ai` — provenance, not acceptance. The AI writes it as the first header line of a
+ * viewpoint it drafted; while it is there the file is an unreviewed draft: the audit records no
+ * baseline for it and holds the two axes measured against it. `--accept-viewpoint` removes it.
+ *
+ * Read by a line scan, not by the viewpoint parser: the key must be found in a file the parser
+ * judges nothing about, and in a QA-written file it simply is not there.
+ */
+const DRAFT_KEY = /^\s*drafted-by:\s*ai\b/i;
+/** The key is a header line: looking further down would read prose that merely mentions it. */
+const HEADER_LINES = 15;
+
+/** A line with its own terminator, so a removal keeps CRLF and a lone `\r` exactly as written. */
+const withTerminator = (raw: string): string[] => raw.match(/[^\r\n]*(?:\r\n|\r|\n)|[^\r\n]+$/g) ?? [];
+
+/** Index of the draft line in `raw`, or -1. Comments are blanked line-for-line, so indexes agree with the raw file. */
+function draftLineIndex(raw: string): number {
+  const visible = stripHtmlComments(raw.replace(/\r\n?/g, '\n')).split('\n');
+  let seen = 0;
+  for (let i = 0; i < visible.length && seen < HEADER_LINES; i++) {
+    if (visible[i].trim() === '') continue;
+    if (DRAFT_KEY.test(visible[i])) return i;
+    seen++;
+  }
+  return -1;
+}
+
+export function isAiDraft(text: string): boolean {
+  return draftLineIndex(text) >= 0;
+}
+
+/** `raw` without the one draft line; every other byte is untouched. A file with no draft line comes back as is. */
+export function removeDraftLine(raw: string): string {
+  const at = draftLineIndex(raw);
+  if (at < 0) return raw;
+  return withTerminator(raw).filter((_, i) => i !== at).join('');
+}
+
+export function viewpointFileIsAiDraft(viewpointPath: string): boolean {
+  try { return isAiDraft(fs.readFileSync(viewpointPath, 'utf-8')); } catch { return false; }
+}
+
+/** Remove the draft line from the file, atomically. True when a line was removed; throws a clear error when the write fails. */
+export function removeDraftLineFromFile(viewpointPath: string): boolean {
+  const raw = fs.readFileSync(viewpointPath, 'utf-8');
+  if (!isAiDraft(raw)) return false;
+  try { writeFileAtomic(viewpointPath, removeDraftLine(raw)); } catch (err) {
+    throw new Error(`could not remove the \`drafted-by: ai\` line from ${viewpointPath} (${err instanceof Error ? err.message : err}) — the file is unchanged; remove the line by hand`);
+  }
+  return true;
+}

package/src/harness/viewpoint-ledger.ts

@@ -9,8 +9,10 @@
  * gaps that inflate a "looks-covered" score; it does not fail the gate.
  */
 import * as fs from 'fs';
-import { ScenarioInfo } from './parse';
-import { readTextFile } from './read-text';
+import { NON_DECLARATION_SECTION, PRIORITY_WORDS, ScenarioInfo } from './parse';
+import { readViewpointText } from './read-text';
+import { keywordHit } from './keyword-match';
+import { countedAssertions } from './counted-assertions';
 
 export interface LedgerItem { id?: string; text: string; covered: boolean }
 
@@ -56,6 +58,13 @@ function claimedCount(text: string): number | 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
+/**
+ * A bullet declares only the id it STARTS with (after a `[ ]` checkbox); one further along is a
+ * citation (`… (SG-01, …)`). `- **High** VP-…` or `- Email shown — VP-…` therefore carry no id.
+ */
+const BULLET_ID = new RegExp(`^[\\s(#]*(?:\\[[ xX]\\]\\s*)?\\[?${ID_RE.source}`);
+/** A table cell that is an id and nothing else. */
+const WHOLE_ID = new RegExp(`^${ID_RE.source}$`);
 
 /**
  * Lines that DECLARE something about the checklist rather than being a checklist item —
@@ -68,7 +77,10 @@ const ID_RE = /\b([A-Z]{1,5}\d{0,2}(?:[.\-][A-Za-z0-9]+)*-?\d{0,3})\b/; // VP0.T
 const PLACEHOLDER_ITEM = /^(none\b|n\/a\b|tbd\b|no known\b|nothing\b|do not invent\b|-+$)/i;
 /** 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;
+// The word must be the WHOLE second cell: `skip` / `none` / `n/a` also open real claims
+// ("Skip link moves focus to main", "None of the optional fields block submit") — and so did
+// `high`/`low` ("High contrast mode …"), which the old word-boundary match swallowed too.
+const PRIORITY_ROW = new RegExp(`^(?:VP|FL)[A-Z0-9._-]*\\s+—\\s+[*_\`]*(?:${PRIORITY_WORDS})[*_\`.]*(?=\\s+—|\\s*$)`, 'i');
 /**
  * Whole SECTIONS that declare something ABOUT the checklist rather than listing claims to prove.
  *
@@ -81,49 +93,121 @@ const PRIORITY_ROW = /^(?:VP|FL)[A-Z0-9._-]*\s+—\s+(?:critical|high|medium|nor
  * `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 DECLARATION_SECTION = NON_DECLARATION_SECTION;   // shared with the overview parser (#833)
+/**
+ * A lead-in that introduces a manual check's PROCEDURE — `How to run VP-SEC-1:`, `Procedures:`,
+ * `Steps to reproduce:`. The list under it is how to EXECUTE a claim already declared above;
+ * counting each step as its own claim made gaps no scenario can close (8 of 13 surplus items on a
+ * field unit, #855).
+ *
+ * Deliberately narrow, because a false match HIDES claims: the lead may name one id and nothing
+ * else (`How to verify the following claims hold:` introduces claims, not steps), and a bare
+ * `Steps:` (a flow lists real step claims under it) and `Tester verifies:` (expected outcomes —
+ * exactly what the ledger counts) never qualify.
+ */
+const PROCEDURE_LEAD = /^(?:how to (?:run|test|reproduce|verify)|(?:manual )?procedures?|manual steps|steps to reproduce)(?:\s+(?:VP|FL)-[\w.-]+)?\s*:$/i;
+const LIST_ITEM = /^(?:[-*+]|\d+[.)])\s+/;
 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']);
 
+/**
+ * `decision`: a `- D4: …` line under Design Decisions. It names the spec's intent so rows can cite
+ * it; its testable part is carried by a VP row (review check 8). No scenario ever carries `D4`, so
+ * as a ledger item it stayed MISSING for good — "not tested" decisions included (phase-7 D5). The
+ * ledger skips it; the continuity, source and integrity checks still read it. Only that section
+ * declares: a QA claim labelled `D8` elsewhere stays a claim, and an id-less decision bullet stays
+ * the prose claim it always was.
+ */
+export interface ViewpointItem { id?: string; text: string; decision?: true }
+const DECISION_ID = /^D\d+$/;
+const DECISIONS_SECTION = /^(?:design decisions?|quyết định(?: thiết kế)?)\b/i;
+
 /** Extract atomic checklist items from a viewpoint file (format-tolerant). */
-export function parseViewpointItems(viewpointPath: string): { id?: string; text: string }[] {
+export function parseViewpointItems(viewpointPath: string): ViewpointItem[] {
   if (!fs.existsSync(viewpointPath)) return [];
-  const lines = readTextFile(viewpointPath).split('\n');
-  const items: { id?: string; text: string }[] = [];
+  const lines = readViewpointText(viewpointPath).split('\n');
+  const items: ViewpointItem[] = [];
   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();
+  // The level the Design Decisions section was opened at, while inside it (see `decision`).
+  let decisionsAt: number | null = null;
+  // Inside the list a PROCEDURE_LEAD introduced: the indent of the lead (-1 for a paragraph lead),
+  // whose list items — and their wrapped continuation lines — are steps. A heading, a table, a
+  // new lead, or (after a paragraph lead) a blank line once a step was read ends it: when in
+  // doubt a step stays a claim, because a swallowed claim is a gap nobody ever sees — so a LOOSE
+  // procedure (steps separated by blank lines) leaks its later steps as claims, by design.
+  // Only an INDENTED line continues a step (Markdown's continuation); unindented prose ends it.
+  let procIndent: number | null = null;
+  let procSteps = 0;
+  let prevBlank = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
     if (line.startsWith('```')) { inFence = !inFence; continue; }
-    if (inFence || !line) continue;
+    if (inFence) continue;
+    if (!line) { prevBlank = true; continue; }
+    const wasBlank = prevBlank;
+    prevBlank = false;
+    const isItem = LIST_ITEM.test(line);
+    const indent = lines[i].length - lines[i].trimStart().length;
+    if (PROCEDURE_LEAD.test(line.replace(LIST_ITEM, '').replace(/[*_`]/g, '').trim())) {
+      procIndent = isItem ? indent : -1;
+      procSteps = 0;
+      continue;
+    }
+    if (procIndent !== null) {
+      const listEnded = wasBlank && procIndent < 0 && procSteps > 0;
+      if (!listEnded && isItem && indent > procIndent) { procSteps++; continue; }          // a step
+      if (!listEnded && !isItem && !wasBlank && procSteps > 0 && indent > Math.max(procIndent, 0)
+        && !/^[#|]/.test(line) && !line.endsWith(':')) continue;                          // a step that wraps
+      procIndent = null;
+    }
     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
+      if (decisionsAt !== null && level > decisionsAt) continue; // a subsection of Design Decisions
       // 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();
+      // `Phần 4:` / `Part 4.` / `Mục 4.` number a section the same way.
+      const headText = heading[2].replace(/[*`]/g, '').replace(/^\s*(?:(?:[Pp]hần|[Pp]art|[Mm]ục|[Ss]ection)\s+)?(?:\d+|[A-Z])\s*[.):]\s*/, '').trim();
       inDeclarationSection = DECLARATION_SECTION.test(headText);
       excludedAt = inDeclarationSection ? level : null;
+      decisionsAt = DECISIONS_SECTION.test(headText) ? level : null;
       continue;
     }
     if (inDeclarationSection) continue;
     let text = '';
     let lead = '';
+    let declared: RegExpMatchArray | null = null;
     const bullet = line.match(/^(?:[-*+]|\d+[.)])\s+(.*)$/);
-    if (bullet) { text = bullet[1]; lead = bullet[1]; }
+    if (bullet) {
+      text = bullet[1]; lead = bullet[1];
+      declared = lead.replace(/[*`]/g, '').match(BULLET_ID);
+    }
     else if (line.startsWith('|')) {                       // table data row
       if (/^\|[\s|:-]+\|?$/.test(line)) continue;           // separator
+      // The row right above a `|---|` separator IS the header, whatever its words (`Skill #`,
+      // `Case #`) — structure, not a guessed word list, so a data row such as `C#` or `Issue #`
+      // is never mistaken for one (#832). The word list below still covers a separator-less table.
+      const next = (lines[i + 1] ?? '').trim();
+      if (/^\|[\s|:-]+\|?$/.test(next) && next.includes('-')) continue; // header
       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] ?? '';
+      // The lead is the row's FIRST cell, empty or not: a continuation row (`| | | case | … see SG-02 |`)
+      // declares nothing. A later cell holding an id and nothing else still declares (`| x | VP-UI-001 |`),
+      // and so does a row number followed by a cell that starts with one (`| 1 | VP-UI-001 — … |`).
+      const raw = line.replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.replace(/[*`]/g, '').trim());
+      lead = raw[0] ?? '';
+      declared = lead.match(ID_RE)
+        ?? (/^\d+\.?$/.test(lead) ? (raw[1] ?? '').match(BULLET_ID) : null)
+        ?? raw.slice(1).map((c) => c.match(WHOLE_ID)).find(Boolean) ?? null;
     } else continue;
     text = text.replace(/[*`]/g, '').trim();
     if (!text) continue;
@@ -138,15 +222,16 @@ export function parseViewpointItems(viewpointPath: string): { id?: string; text:
     // 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
+    const id = declared && /\d/.test(declared[1]) ? declared[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) });
+    items.push(decisionsAt !== null && id && DECISION_ID.test(id)
+      ? { id, text: text.slice(0, 100), decision: true }
+      : { id, text: text.slice(0, 100) });
   }
   return items;
 }
@@ -157,6 +242,7 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
   // (#622) — silently collapsing those would remove its input.
   const seen = new Set<string>();
   const items = parseViewpointItems(viewpointPath)
+    .filter((i) => !i.decision)
     .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: [] };
@@ -190,15 +276,14 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
         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));
+          const asserted = Math.max(...auto.map((s) => countedAssertions(s.stepsText)));
           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);
+      isCovered = words.length > 0 && scenarios.some((s) => words.filter((w) => keywordHit(s.haystack, w)).length >= need);
     }
     if (isCovered) covered++;
     else missing.push({ id: item.id, text: item.text });
@@ -348,13 +433,16 @@ export function viewpointIntegrity(
   }
 
   // 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)]
+  const vpText = readViewpointText(viewpointPath);
+  const words = [...vpText
+    .matchAll(new RegExp(`^\\|\\s*((?:VP|FL)[A-Z0-9._-]*)\\s*\\|\\s*(${PRIORITY_WORDS})\\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;
+  // Fold only synonyms (Medium / Med / Normal are one level). `critical` stays its own word: a
+  // Critical / High / High table is a ranking, and folding it into `high` made it read as uniform.
+  const level = (w: string): string => (/^(?:medium|med|normal)$/.test(w) ? 'normal' : w);
+  const uniformPriority = words.length >= 3 && new Set(words.map(level)).size === 1
+    ? { levels: [words[0]], rows: words.length } // the word QA wrote, not the folded key
+    : null;
 
   return { duplicateIds, danglingRefs, uniformPriority };
 }