@sun-asterisk/sungen 3.2.33 → 3.2.34

package/src/harness/quality-gates.ts

@@ -8,6 +8,7 @@ import * as path from 'path';
 import { keywordHit } from './keyword-match';
 import { ScenarioInfo, loadScenarios, idPrefix } from './parse';
 import { parseManualComments } from '../exporters/scenario-merger';
+import { commentLinesOf, isPresencePlaceholderHybrid, keywordStepsOf } from '../exporters/manual-hybrid-oracle';
 import { readTextFile } from './read-text';
 
 // ---------- #2 Downstream-scope ----------
@@ -220,14 +221,15 @@ export function manualOracle(featureText: string): ManualOracleResult {
     //    Observable:/Oracle:/Expected: line (parseManualComments — the SAME parser the
     //    delivery exporter uses, so this gate can't drift from the exported cells).
     //    Prose paragraphs / rationale-only comments export EMPTY Steps + Expected.
+    //  • HAS a Then whose every assertion is a bare presence placeholder, with the real oracle
+    //    in the comments (#810) — the same hybrid wearing a Then (manual-hybrid-oracle.ts, the
+    //    SAME predicate as compile-time SG-W008).
     const hasGherkinSteps = /^\s*(Given|When|Then)\s/m.test(b);
+    const commentLines = commentLinesOf(b);
     let bad: boolean;
     if (hasGherkinSteps) {
-      bad = !/^\s*Then\s/m.test(b);
+      bad = !/^\s*Then\s/m.test(b) || isPresencePlaceholderHybrid(keywordStepsOf(b), commentLines);
     } else {
-      const commentLines = b.split('\n')
-        .filter((l) => /^\s*#/.test(l))
-        .map((l) => l.replace(/^\s*#\s?/, ''));
       const parsed = parseManualComments(commentLines);
       bad = !parsed.steps.length || !parsed.expected.length;
     }

package/src/harness/read-text.ts

@@ -32,3 +32,28 @@ export function readTextFile(filePath: string): string {
 export function readTextLines(filePath: string): string[] {
   return readTextFile(filePath).split('\n');
 }
+
+/**
+ * Drop HTML comments (`<!-- … -->`, multi-line too) — they are author notes and scaffold samples,
+ * never content. Newlines inside a comment are kept so every later line keeps its position (#841).
+ *
+ * Only a CLOSED comment is dropped. An unclosed `<!--` (a forgotten `-->`) stays text: dropping it
+ * to the end of the file would silently delete every declaration below it. A fenced code block is
+ * content, and so is a `<!--` written inside backticks: both are how a document SHOWS the syntax.
+ */
+export function stripHtmlComments(text: string): string {
+  // A comment body never holds another `<!--`: an opener with no `-->` before the next opener is
+  // the unclosed one, and must not reach a LATER comment's closer and eat everything between.
+  const blank = (s: string): string => s.replace(/(?<!`)<!--(?:(?!<!--)[\s\S])*?-->/g, (m) => m.replace(/[^\n]/g, ''));
+  // split() with a capture group keeps the fences at the odd indexes.
+  return text.split(/(^```[^\n]*\n[\s\S]*?^```[^\n]*$)/m).map((part, i) => (i % 2 ? part : blank(part))).join('');
+}
+
+/**
+ * `test-viewpoint.md` as every harness sensor must read it: normalised, comments removed, and
+ * '' when the unit has none. `sungen add` scaffolds its samples inside `<!-- -->`; read raw, an
+ * untouched scaffold declared VP-UI/VP-VAL/VP-LOGIC/VP-SEC and carried 12 phantom claims (#841).
+ */
+export function readViewpointText(filePath: string): string {
+  return fs.existsSync(filePath) ? stripHtmlComments(readTextFile(filePath)) : '';
+}

package/src/harness/select-by-ids.ts

@@ -0,0 +1,83 @@
+/**
+ * Select scenarios by test-case ID — backs `sungen select` and `run-test --ids` (#835).
+ *
+ * An ID means what it means everywhere else in the harness: `vpId`, the leading ID token of the
+ * scenario title (`VP-UI-001`, `MS-HP-001`, `VP0-001`). Matching is exact and case-insensitive —
+ * `VP-UI-001` never selects `VP-UI-0010` or `VP-UI-001-B` — and every ID that selects nothing
+ * runnable is reported, because the alternative is a 0-test run that reports green.
+ */
+import * as path from 'path';
+import { ScenarioInfo } from './parse';
+
+/**
+ * Escape scenario titles into one `-g` / `--mochaOpts.grep` regex. Full titles, not bare IDs:
+ * a title starts with its own ID, so it can only appear inside its own test's title — and a
+ * `@cases` row test (`<title> — <row label>`) still contains it.
+ */
+export function titlesToGrep(titles: string[]): string {
+  return titles.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+}
+
+export interface IdSelectionGroup {
+  /** Feature basename (`products`, `home-modal`) — names the spec and the result file. */
+  feature: string;
+  ids: string[];
+  titles: string[];
+  grep: string;
+}
+
+export interface IdSelection {
+  features: IdSelectionGroup[];
+  /** IDs no scenario carries, with near matches (`VP-VAL-001` → `VP-VAL-001-B`). */
+  unknown: Array<{ id: string; didYouMean: string[] }>;
+  /** IDs whose every scenario is manual, owned by a flow or waiting on a capability — nothing to run. */
+  notRunnable: Array<{ id: string; reason: string }>;
+}
+
+/** `"VP-UI-001, vp-ui-002 VP-UI-001"` → `['VP-UI-001', 'VP-UI-002']`. */
+export function parseIdList(raw: string): string[] {
+  return [...new Set(raw.split(/[\s,]+/).map((s) => s.trim().toUpperCase()).filter(Boolean))];
+}
+
+/** `VP-C-002.` → `VP-C-002`: the title token may carry trailing punctuation the user never types. */
+const idOf = (s: ScenarioInfo): string | undefined => s.vpId?.replace(/[.-]+$/, '') || undefined;
+
+function notRunnableReason(s: ScenarioInfo, enabledCaps: Set<string>): string | null {
+  if (s.deferredToFlow) return `owned by a flow${s.ownedByFlow ? ` (${s.ownedByFlow})` : ''} — run it there`;
+  if (s.featureManual) return 'its Feature is @manual — no spec is generated for it';
+  if (s.manual) return 'manual — no automated test exists';
+  // Compiled as `test.skip` while the capability is off: the run would report a skip, not a result.
+  const missing = (s.requiresCaps ?? []).filter((c) => !enabledCaps.has(c));
+  if (missing.length) return `needs capability ${missing.join(', ')} — compiled as a skip until \`sungen capability add ${missing.join(' ')}\``;
+  return null;
+}
+
+export function selectByIds(scenarios: ScenarioInfo[], ids: string[], unit: string, enabledCaps: Set<string> = new Set()): IdSelection {
+  const out: IdSelection = { features: [], unknown: [], notRunnable: [] };
+  const groups = new Map<string, IdSelectionGroup>();
+  const allIds = [...new Set(scenarios.map(idOf).filter((v): v is string => !!v))];
+
+  for (const id of ids) {
+    const hits = scenarios.filter((s) => idOf(s) === id);
+    if (hits.length === 0) {
+      const didYouMean = allIds.filter((v) => v.startsWith(`${id}-`) || id.startsWith(`${v}-`)).slice(0, 5);
+      out.unknown.push({ id, didYouMean });
+      continue;
+    }
+    const runnable = hits.filter((s) => !notRunnableReason(s, enabledCaps));
+    if (runnable.length === 0) {
+      out.notRunnable.push({ id, reason: notRunnableReason(hits[0], enabledCaps)! });
+      continue;
+    }
+    for (const s of runnable) {
+      const feature = s.sourceFile ? path.basename(s.sourceFile, '.feature') : unit;
+      const g = groups.get(feature) ?? { feature, ids: [], titles: [], grep: '' };
+      if (!g.ids.includes(id)) g.ids.push(id);
+      if (!g.titles.includes(s.name)) g.titles.push(s.name);
+      groups.set(feature, g);
+    }
+  }
+  for (const g of groups.values()) g.grep = titlesToGrep(g.titles);
+  out.features = [...groups.values()];
+  return out;
+}

package/src/harness/sensors.ts

@@ -634,6 +634,9 @@ export interface TraceResult {
   mappedToOverview: number;
   withVpCodeRatio: number;
   mappedRatio: number;
+  /** Viewpoint IDs read from test-viewpoint.md. 0 = nothing to map to, so `mappedRatio` is not a
+   *  measurement — the scenario IDs were never checked (#832). */
+  overviewIds: number;
   note: string;
 }
 
@@ -645,6 +648,24 @@ export interface TraceResult {
  */
 const unprefixed = (id: string): string => id.replace(/^(?:VP|FL)-/i, '').toUpperCase();
 
+/**
+ * The traceability note, worded from the SAME ratio the audit's TRACE finding fires on —
+ * mapped / ALL scenarios (#852). It used to compare mapped against scenarios WITH an id, so 0 of
+ * 0 (no scenario yet, or none tagged) and 2 of 2 tagged out of 10 all read "Traceable." while
+ * the audit reported `TRACE: Traceable.` for a 0–20% mapping.
+ */
+function traceNote(total: number, withCode: number, mapped: number, declared: number, exampleId?: string): string {
+  if (declared === 0) {
+    return 'No viewpoint ID found in test-viewpoint.md — the file is missing, or none of its sections declares one — so the scenario IDs were not checked. Declarations are read from a `## Priority Viewpoints` table, `### Required / Recommended / Optional` lists, and tables whose first column is a `VP-`/`FL-` ID or an ID of a family declared there (Known Issues / Traceability / References sections are skipped).';
+  }
+  if (total === 0) return 'No scenarios yet — traceability is measured once the feature has scenarios.';
+  if (mapped >= total * 0.5) return 'Traceable.';
+  const example = exampleId ? ` (e.g. \`${exampleId}-001 …\`)` : '';
+  if (withCode === 0) return `No scenario carries a viewpoint ID — start each title with one of the IDs declared in test-viewpoint.md${example}.`;
+  if (mapped < withCode * 0.5) return 'Scenario IDs do not match the viewpoint-overview ids (weak traceability — re-tag to the project viewpoint IDs).';
+  return `Only ${mapped} of ${total} scenarios carry a declared viewpoint ID — ${total - withCode} have no ID at all; tag them with the project's IDs${example}.`;
+}
+
 export function traceability(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[]): TraceResult {
   const overviewIds = new Set(viewpoints.map((v) => v.id.toUpperCase()));
   const overviewBare = new Set(viewpoints.map((v) => unprefixed(v.id)));
@@ -669,9 +690,10 @@ export function traceability(scenarios: ScenarioInfo[], viewpoints: ViewpointEnt
     mappedToOverview: mapped.length,
     withVpCodeRatio: scenarios.length ? withCode.length / scenarios.length : 0,
     mappedRatio: scenarios.length ? mapped.length / scenarios.length : 0,
-    note: withCode.length && mapped.length < withCode.length * 0.5
-      ? 'Scenario IDs do not match the viewpoint-overview ids (weak traceability — re-tag to the project viewpoint IDs).'
-      : 'Traceable.',
+    overviewIds: overviewIds.size,
+    // With no ID read there is nothing to match against: telling the author to re-tag sends them
+    // to change scenarios that may be right (#832). Name the file and the sections read instead.
+    note: traceNote(scenarios.length, withCode.length, mapped.length, overviewIds.size, viewpoints[0]?.id),
   };
 }
 
@@ -733,6 +755,31 @@ const CLAIM_RULES: ClaimRule[] = [
     hint: 'swap `contains {{v}}` for `with {{v}}` on the continuity rows. A substring match cannot distinguish "unchanged" from "changed by adding a prefix" — and if the screen genuinely renders extra text around the value, say so in the title instead of claiming exactness.',
     severity: 'warn',
   },
+  {
+    // An ORDER claim ("sorted by date descending", "ties broken by last-updated") is invisible to
+    // a presence check: `see [List] table` passes whatever order the rows are in. It sits ahead of
+    // the generic rules so "all results sorted …" is judged as an ordering claim, not an all-claim.
+    // A tiebreaker is a Tier-1 guard in the tc-generation skill, yet no rule recognised it (#810).
+    claim: 'ordering/sort',
+    title: /\b(ascending|descending|sorted|sorts|sort order|ordered by|order by|in (?:chronological|alphabetical|reverse|numeric) order|(?:newest|oldest|latest|earliest|highest|lowest) first|tie-?break(?:s|er|ers)?|ties?)\b|降順|昇順|並び順|giảm dần|tăng dần|sắp xếp/,
+    proof: /match data|is sorted|sorted (?:ascending|descending)|\brow \d+\b|\.first\.|\.last\.|\[\d+\]\.|order by/,
+    need: 'an order-sensitive assertion (`table match data:` rows in the expected order, `is sorted ascending|descending`, or positional `row N` checks)',
+    hint: 'a presence check passes in any order — assert the rows in their expected sequence (`User see [T] table match data:`), or the column sort state; a tiebreak needs two rows sharing the primary key.',
+    severity: 'fail',
+  },
+  {
+    // A LIMIT claim ("never exceeds 10", "at most 5 files") is a count claim in disguise.
+    // Ahead of 'no-side-effect', whose negation+effect pattern would otherwise swallow
+    // "never exceeds 10 records" and ask for a duplicate-count proof.
+    claim: 'limit/cap',
+    // The quantity must be ≥2 ("at most ONE order" is a no-duplicate claim — left to the rules
+    // below) and not a duration ("up to 30 seconds" is a timing claim, not a cap).
+    title: /\b(?:never exceeds?|(?:does not|doesn['’]t|not) exceed|at most|no more than|up to|capped at|caps? at|maximum of|max(?:imum)?)\s+(?:\d{2,}|[2-9]|two|three|four|five|six|seven|eight|nine|ten)\b(?!\s*(?:ms|milliseconds?|s|secs?|seconds?|mins?|minutes?|hours?|days?)\b)|\b(?:never exceeds?|(?:does not|doesn['’]t) exceed) (?:the )?(?:limit|cap|quota|maximum)\b|以内|上限|tối đa/,
+    proof: /\bcount\b|tohavecount|table with|row with \{\{|match data|is at most|\bexactly\b|field with \{\{|\berror\b|invalid|is disabled/,
+    need: 'a count/boundary assertion (count is N, `is at most`, the N+1th input rejected or truncated)',
+    hint: 'assert the boundary itself — the count at the cap, or the value/error when one more is attempted — not just that the list or field is present.',
+    severity: 'fail',
+  },
   {
     claim: 'all/every/each',
     title: /\b(all|every|each)\b/,
@@ -1025,14 +1072,16 @@ export function numericClaimGaps(scenarios: ScenarioInfo[]): Array<{ name: strin
  * The Priority-Viewpoints table is where release selection is supposed to come from. When the
  * table says a flow is `Low` and its scenario is tagged `@high`, a smoke run picks up work the QA
  * deliberately deprioritised — and nobody can tell which of the two was the decision (#622).
+ *
+ * Reads the SAME parse traceability does (`parseViewpointOverview`). It used to scan the raw text
+ * for any `| VP-… | high |` row, so one audit run "saw" an id for this check and not for
+ * traceability (#833), and a row in a Known Issues table could raise a contradiction.
  */
 export function priorityMismatches(
-  viewpointText: string, scenarios: ScenarioInfo[],
+  viewpoints: ViewpointEntry[], scenarios: ScenarioInfo[],
 ): Array<{ id: string; declared: string; tagged: string; scenario: string }> {
   const declared = new Map<string, string>();
-  for (const m of viewpointText.matchAll(/^\|\s*((?:VP|FL)[A-Z0-9._-]*)\s*\|\s*(critical|high|medium|normal|low|deferred)\s*\|/gim)) {
-    declared.set(m[1].toUpperCase(), m[2].toLowerCase());
-  }
+  for (const v of viewpoints) if (v.priorityWord) declared.set(v.id.toUpperCase(), v.priorityWord);
   if (declared.size === 0) return [];
   // `medium` and `normal` are the same rank under different names in real documents.
   const rank = (p: string): string => (p === 'medium' ? 'normal' : p);
@@ -1045,8 +1094,9 @@ export function priorityMismatches(
     if (!key) continue;
     const want = rank(declared.get(key)!);
     const got = rank(String(s.priority).toLowerCase());
-    // `critical` and `deferred` have no tag equivalent — nothing to contradict.
-    if (want === 'critical' || want === 'deferred') continue;
+    // `critical`, `deferred` and `skip` (declared not applicable, #853) have no tag equivalent —
+    // nothing to contradict.
+    if (want === 'critical' || want === 'deferred' || want === 'skip') continue;
     if (want !== got) out.push({ id: key, declared: declared.get(key)!, tagged: got, scenario: s.name });
   }
   return out;

package/src/harness/spec-branches.ts

@@ -194,7 +194,7 @@ export function sameOracleClusters(scenarios: ScenarioInfo[]): Array<{ oracle: s
     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())
+      .map((st) => `${st.text} ${st.arg ?? ''}`.toLowerCase().replace(/\s+/g, ' ').trim())   // the table is the oracle too (#817)
       .sort();
     if (asserts.length === 0) continue;
     const key = asserts.join(' ; ');

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-ledger.ts

@@ -9,8 +9,8 @@
  * 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';
 
 export interface LedgerItem { id?: string; text: string; covered: boolean }
@@ -69,7 +69,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,13 +85,26 @@ 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']);
 
 /** Extract atomic checklist items from a viewpoint file (format-tolerant). */
 export function parseViewpointItems(viewpointPath: string): { id?: string; text: string }[] {
   if (!fs.existsSync(viewpointPath)) return [];
-  const lines = readTextFile(viewpointPath).split('\n');
+  const lines = readViewpointText(viewpointPath).split('\n');
   const items: { id?: string; text: string }[] = [];
   let inFence = false;
   let inDeclarationSection = false;
@@ -96,10 +112,36 @@ export function parseViewpointItems(viewpointPath: string): { id?: string; text:
   // 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();
+  // 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;
@@ -121,6 +163,11 @@ export function parseViewpointItems(viewpointPath: string): { id?: string; text:
     if (bullet) { text = bullet[1]; lead = bullet[1]; }
     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(' — ');
@@ -349,10 +396,9 @@ 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 vpText = readViewpointText(viewpointPath);
   const rows = [...vpText
-    .matchAll(/^\|\s*((?:VP|FL)[A-Z0-9._-]*)\s*\|\s*(critical|high|medium|normal|low|deferred)\s*\|/gim)]
+    .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;

package/src/orchestrator/screen-manager.ts

@@ -9,6 +9,7 @@ import { chromium } from '@playwright/test';
 import { readCapabilities } from '../harness/capability';
 import { testDataHeader, ensureTestDataGuideFiles } from './test-data-guide';
 import { resolveWebBaseUrl } from '../exporters/env-qa';
+import { uiPatternRows } from './viewpoint-pattern-catalog';
 
 export interface ScreenOptions {
   name: string;
@@ -191,20 +192,11 @@ export class ScreenManager {
         '',
         '## UI Patterns Identified',
         '',
-        '<!-- Check applicable patterns for this screen (from sungen-viewpoint skill):',
+        '<!-- Check applicable patterns for this screen (numbered as in the sungen-viewpoint skill):',
         '',
         '| # | Pattern | Applicable? | Notes |',
         '|---|---------|-------------|-------|',
-        '| 1 | Form & Inputs | ☐ | |',
-        '| 2 | Data Table | ☐ | |',
-        '| 3 | Create / Add | ☐ | |',
-        '| 4 | Update / Edit | ☐ | |',
-        '| 5 | Delete | ☐ | |',
-        '| 6 | Search | ☐ | |',
-        '| 7 | Filter | ☐ | |',
-        '| 8 | Pagination | ☐ | |',
-        '| 9 | Modal / Dialog | ☐ | |',
-        '| 10 | List / Card | ☐ | |',
+        ...uiPatternRows(isMobile),
         '-->',
         '',
         '## Priority Viewpoints',

package/src/orchestrator/templates/ai-src/agents/discovery.md

@@ -9,7 +9,9 @@ You are a **test-design context explorer**. You run in an **isolated context** s
 ## Explore (do NOT ask the user to pick a source — read all that exist)
 - `requirements/spec.md` — primary behavior source.
 - `requirements/spec_figma.md` — Figma supplement (if present; do NOT call Figma MCP when this exists).
-- `requirements/ui/*` images — layout/visual context.
+- `requirements/ui/*` images — read **every** image (group primary vs states/variants when there are many, but open them all).
+- `requirements/ui/figma-meta.md` — Figma MCP capture: `## Components`, `## Text Content`.
+- `requirements/ui-inventory.md` — an existing Design Inventory: keep its `UI-NNN` ids.
 - Live page — only if a base URL is configured and reachable: `browser_navigate` + `browser_snapshot` for real element roles/names. Fall back gracefully if it requires login / fails.
 
 ## Cross-check
@@ -20,7 +22,13 @@ Flag any **conflicts** between sources (field names, labels, behavior, states th
 SOURCES: spec=<yes/no, completeness high|med|low> | figma=<...> | ui=<n images> | live=<reached|offline>
 PAGE TYPE: <e.g. ecommerce-list / form / auth / ...>
 RECOMMENDED ROUTE: <spec-first | source-first | ...> — authoritative source: <which>
-CONFLICTS: <list, or "none">
+CONFLICTS: <list, or "none"> — each conflict on a design item also appears in UI INVENTORY with source `conflict`
+UI INVENTORY: images read: <read>/<total> · figma-meta.md: <read|absent> · spec_figma.md: <read|absent>
+  | UI-001 | <item> | <component|column|button|field|state|annotation> | spec+design | <image> |
+  | UI-014 | <item> | column | design-only | <image> |
+  | UI-015 | <item> | column | conflict — <how spec and design disagree> | <image> |
+  → one row per item the design shows (format and id rules: `sungen-tc-generation` § Design Inventory);
+    omit the block only when the unit has no design source
 KEY FACTS (condensed):
   - Sections: <list>
   - Fields/validation: <key constraints + exact error messages>
@@ -29,4 +37,4 @@ KEY FACTS (condensed):
 ASSUMPTIONS / MISSING INFO: <what's unknown — to be marked in output>
 ```
 
-Keep it tight. Do not generate test cases — that is the orchestrator's job. Do not write files.
+Keep it tight — except UI INVENTORY, which is listed in full: it is the checklist the orchestrator writes to `ui-inventory.md`. Do not generate test cases — that is the orchestrator's job. Do not write files.

package/src/orchestrator/templates/ai-src/agents/reviewer.md

@@ -10,6 +10,8 @@ You are an **independent Senior QA Reviewer**. You did **not** write these tests
 - `qa/<screens|flows>/<name>/features/<name>.feature` — the scenarios under review.
 - `qa/<screens|flows>/<name>/requirements/test-viewpoint.md` — the viewpoint overview (priority).
 - `qa/<screens|flows>/<name>/requirements/spec.md` — source of truth for behavior.
+- `qa/<screens|flows>/<name>/requirements/ui/*` images, `ui/figma-meta.md`, `spec_figma.md` — the design, when present. Open **every** image.
+- `qa/<screens|flows>/<name>/requirements/ui-inventory.md` — the Design Inventory create-test wrote (`UI-NNN` rows).
 - `.sungen/reports/<name>-audit.json` — the deterministic findings (don't repeat them; go deeper).
 
 ## What to judge (semantic — the gate misses these)
@@ -25,6 +27,7 @@ You are an **independent Senior QA Reviewer**. You did **not** write these tests
    - **Flows self-clean.** A CRUD/auth chain deletes what it created (final `@api:delete_*`) or is `@cleanup`-tagged.
    - **Idempotency uses the DB oracle.** A "no double-charge / exactly once" claim is proven by `@concurrent` + a `@query` count, not HTTP status alone (status can lie under a race).
    - **Auth negatives** exist for protected mutations (401/403), not just the happy path.
+7. **Design ↔ Feature** (only when the unit holds design sources). Read the design yourself — do not trust the inventory to be complete. Report: items the design shows that are **missing from `ui-inventory.md`**; inventory items **mislabelled** `spec+design` that `spec.md` never names (design-only) or names differently (conflict); and `design-only`/`conflict` items whose `@ui:` scenario does not actually prove them, or whose `# UI-DEFERRED:` reason does not hold. The audit only sees what the inventory lists — you are the check on the inventory itself.
 
 ## Output (do NOT edit any file)
 Return a concise verdict:
@@ -38,6 +41,11 @@ ISSUES (most important first):
    FIX: <the exact Gherkin step(s) to add/change>
 2. ...
 
+DESIGN DIFF (omit when the unit has no design source):
+  - not inventoried: <item> (<image>)
+  - mislabelled: UI-NNN <item> — is <design-only|conflict>, not spec+design
+  - unproven: UI-NNN <item> — <why the @ui scenario / deferral does not hold>
+
 STRENGTHS: <1-2 lines, what is genuinely good>
 ```