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

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,9 +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 }
 
@@ -57,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 —
@@ -69,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.
  *
@@ -82,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;
@@ -139,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;
 }
@@ -158,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: [] };
@@ -191,8 +276,7 @@ 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 });
         }
       }
@@ -349,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 };
 }

package/src/harness/viewpoint-mode.ts

@@ -0,0 +1,49 @@
+/**
+ * Which create-test mode a unit's test-viewpoint.md calls for — the table in create-test.md,
+ * computed so the agent reads it from `sungen viewpoint scan` instead of inferring it.
+ *
+ *   mode 2 (AI drafts / re-reviews its draft): file missing · untouched scaffold · first line
+ *          `drafted-by: ai` · VP rows exist but none has a Kỳ vọng
+ *   mode 1 (review only, never edit): anything else — a QA-written file, with or without VP ids
+ *
+ * "Untouched scaffold" is checked on RAW lines against the template the scaffold is written from:
+ * apart from the first `# ` line (the title), every non-blank line must be a template line —
+ * comments included, so a QA note inside `<!-- -->` or under its own `# ` heading makes the file
+ * the QA's (owner decision 2026-10-14: a QA file is never overwritten). Every doubt falls to
+ * mode 1: a scaffold from an older sungen (other template lines) or an unreadable template.
+ */
+import { isAiDraft } from './viewpoint-draft-header';
+import { viewpointScaffold } from '../orchestrator/viewpoint-scaffold';
+
+export type ViewpointMode = 1 | 2;
+
+/** Trimmed non-blank lines without the title (the first `# ` line), BOM and CRLF ignored. */
+function bodyLines(text: string): string[] {
+  const lines = text.replace(/^/, '').replace(/\r\n?/g, '\n').split('\n').map((l) => l.trim()).filter(Boolean);
+  const title = lines.findIndex((l) => l.startsWith('# '));
+  if (title >= 0) lines.splice(title, 1);
+  return lines;
+}
+
+let templateLines: Set<string> | null = null;
+function isUntouchedScaffold(raw: string): boolean {
+  if (!templateLines) {
+    try {
+      templateLines = new Set([false, true].flatMap((mobile) => bodyLines(viewpointScaffold('', mobile))));
+    } catch {
+      return false;   // no template to compare with → treat the file as the QA's
+    }
+  }
+  const known = templateLines;
+  return bodyLines(raw).every((l) => known.has(l));
+}
+
+/** `raw` is the file as written (null when missing); `rows` are its VP rows from the scan. */
+export function viewpointMode(raw: string | null, rows: { hasExpected: boolean }[]): { mode: ViewpointMode; reason: string } {
+  if (raw === null) return { mode: 2, reason: 'file missing' };
+  if (isAiDraft(raw)) return { mode: 2, reason: 'drafted-by: ai (re-review)' };
+  if (rows.length > 0) {
+    return rows.some((r) => r.hasExpected) ? { mode: 1, reason: 'QA-written' } : { mode: 2, reason: 'VP rows without Kỳ vọng' };
+  }
+  return isUntouchedScaffold(raw) ? { mode: 2, reason: 'untouched scaffold' } : { mode: 1, reason: 'QA-written, no VP ids' };
+}

package/src/harness/viewpoint-priority.ts

@@ -0,0 +1,38 @@
+/**
+ * One reading of a priority — a viewpoint row's cell or a scenario's tag.
+ *
+ * The overview parser, the ledger's uniform-priority check and PRIORITY-CONTRADICTED each read a
+ * priority their own way (`/high/i` substrings, raw words, a one-off medium→normal), so the same
+ * row could be `Medium` to one and `Unknown` to another — `Med`, which QA writes, was `Unknown`.
+ * The vocabulary is `high | normal | low`; `critical`, `medium` and `med` are read as aliases.
+ */
+export type PriorityLevel = 'high' | 'normal' | 'low' | 'deferred' | 'skip' | 'unknown';
+
+const WORD: Record<string, PriorityLevel> = {
+  critical: 'high', high: 'high',
+  medium: 'normal', med: 'normal', normal: 'normal',
+  low: 'low', deferred: 'deferred',
+};
+/** "Declared not applicable" — one level, so every consumer checks one word. */
+const NOT_APPLICABLE = /^(?:skip(?:ped)?|n\/a|none|not applicable)$/;
+
+/**
+ * A priority cell or tag → its level. The whole cell being a word is the clean case; otherwise the
+ * overview has always read prose by SUBSTRING in precedence order (`High — complex form`,
+ * `Medium-High`), and keeps doing so. The substring words stay unbounded for `high|medium|low`
+ * (existing behaviour); the newer `critical|normal|med` need word boundaries (`Medical` is not `Med`).
+ */
+export function parsePriority(cell: string): PriorityLevel {
+  const w = cell.replace(/[*_`]/g, '').replace(/\.+$/, '').trim().toLowerCase();
+  if (WORD[w]) return WORD[w];
+  if (NOT_APPLICABLE.test(w)) return 'skip';
+  if (/high|\bcritical\b/.test(w)) return 'high';
+  if (/medium|\bnormal\b|\bmed\b/.test(w)) return 'normal';
+  if (/low/.test(w)) return 'low';
+  return 'unknown';
+}
+
+/** The public `ViewpointEntry.priority` spelling of a level — the exported type is unchanged. */
+export function toEntryPriority(level: PriorityLevel): 'High' | 'Medium' | 'Low' | 'Unknown' {
+  return level === 'high' ? 'High' : level === 'normal' ? 'Medium' : level === 'low' ? 'Low' : 'Unknown';
+}

package/src/harness/viewpoint-review-open.ts

@@ -0,0 +1,51 @@
+/**
+ * VIEWPOINT-REVIEW-OPEN (info) — the audit's one line about `requirements/viewpoint-review.md`.
+ *
+ * create-test reviews test-viewpoint.md with the sungen-viewpoint checklist and writes each point a
+ * QA should look at as a table row whose last cell is `[ ]`; the QA ticks it `[x]` or deletes the
+ * row. While rows stay unticked the audit says how many, once. Advisory only: no score, no gate, no
+ * baseline effect. A missing or unreadable file says nothing — the review is optional input.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { stripHtmlComments } from './read-text';
+
+export const VIEWPOINT_REVIEW_FILE = 'viewpoint-review.md';
+
+const SEPARATOR = /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/;
+/** A table separator, not a `---` rule under a row. */
+const isSeparator = (line: string): boolean => SEPARATOR.test(line) && line.includes('|');
+const UNTICKED = /^\[\s?\]$/;
+
+/** The last cell of a markdown table row, or null for a line that is not one. */
+function lastCell(line: string): string | null {
+  const t = line.trim();
+  if (!t.startsWith('|') || !t.endsWith('|') || t.length < 2) return null;
+  const cells = t.slice(1, -1).split(/(?<!\\)\|/);
+  return cells[cells.length - 1].trim();
+}
+
+/** Body rows whose last cell is `[ ]`. The header row (`… | [ ] |` above `|---|`) is not a point. */
+export function openReviewPoints(text: string): number {
+  const lines = stripHtmlComments(text.replace(/\r\n?/g, '\n')).split('\n');
+  let open = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (isSeparator(lines[i]) || isSeparator(lines[i + 1] ?? '')) continue;
+    const last = lastCell(lines[i]);
+    if (last !== null && UNTICKED.test(last)) open++;
+  }
+  return open;
+}
+
+/** The info finding for one unit's `requirements/` directory; empty when nothing is open. */
+export function viewpointReviewOpenFindings(requirementsDir: string): string[] {
+  let text: string;
+  try {
+    text = fs.readFileSync(path.join(requirementsDir, VIEWPOINT_REVIEW_FILE), 'utf-8');
+  } catch {
+    return [];
+  }
+  const open = openReviewPoints(text);
+  if (open === 0) return [];
+  return [`VIEWPOINT-REVIEW-OPEN (info): ${open} open point(s) in requirements/${VIEWPOINT_REVIEW_FILE} — the checklist review of test-viewpoint.md is waiting for QA. QA: fix the viewpoint where you agree, then tick the row \`[x]\` or delete it. Not scored; an agent does not tick rows for the QA.`];
+}