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

package/src/harness/viewpoint-scan-refs.ts

@@ -0,0 +1,154 @@
+/**
+ * Building blocks of `sungen viewpoint scan` (viewpoint-scan.ts): the markdown table walker, the
+ * item-reference reader and the item universe. Pure, read-only, format-tolerant by design — a
+ * QA-written file is never judged here, only its ids and item numbers are read.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { readTextFile, stripHtmlComments } from './read-text';
+import { parseUiInventory } from './ui-inventory';
+import { parseSpecClauses } from './spec-coverage';
+
+export interface TableRow {
+  /** 1-based line in the (comment-stripped, newline-preserving) text. */
+  line: number;
+  raw: string;
+  /** Cells with `**`, backticks and edge spaces removed. */
+  cells: string[];
+  /** The table's header cells; null for a table with no separator line. */
+  header: string[] | null;
+  /** Text of every heading enclosing the row (outermost first) — where a `# MANUAL/ENV` mark may sit. */
+  section: string;
+}
+
+const SEPARATOR = /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/;
+const splitCells = (line: string): string[] => line.trim().replace(/^\|/, '').replace(/\|$/, '')
+  .split(/(?<!\\)\|/).map((c) => c.replace(/\*\*|`/g, '').trim());
+
+/** Every body row of every markdown table, with its header and enclosing headings. */
+export function tableRows(text: string): TableRow[] {
+  const lines = text.split('\n');
+  const out: TableRow[] = [];
+  const headings: string[] = [];   // index = level − 1
+  let header: string[] | null = null;
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const h = raw.match(/^(#{1,6})\s+(.*)$/);
+    if (h) { headings.length = h[1].length - 1; headings[h[1].length - 1] = h[2]; header = null; continue; }
+    if (!raw.includes('|')) { header = null; continue; }
+    if (SEPARATOR.test(raw)) continue;
+    if (i + 1 < lines.length && SEPARATOR.test(lines[i + 1])) { header = splitCells(raw); continue; }
+    out.push({ line: i + 1, raw, cells: splitCells(raw), header, section: headings.join(' ') });
+  }
+  return out;
+}
+
+const NUM = String.raw`(?<!\d)\d{1,3}(?:\.\d{1,3})*(?![\d])`;
+const LIST = new RegExp(`(?:\\bitems?|項目|(?<![\\w-])UI[\\s-]*#?|#)\\s*(${NUM}(?:\\s*(?:[-–—~〜～,;&/]|(?<![\\p{L}\\p{N}])(?:và|and)(?![\\p{L}\\p{N}]))\\s*${NUM})*)`, 'giu');
+
+/** `009` → `9`, `4.03` → `4.3`; null when the text is not a plain (dotted) number. */
+export function normRef(s: string): string | null {
+  const t = s.replace(/[[\]§#]/g, '').trim();
+  return /^\d+(\.\d+)*$/.test(t) ? t.split('.').map((p) => String(Number(p))).join('.') : null;
+}
+
+/**
+ * The refs strictly between `a` and `b` (normalised): `4`–`6` → `5`, `5.4`–`5.8` → `5.5 … 5.7`.
+ * Only the last level steps, so both ends need the same prefix; `5.4–6.2` or `3–5.2` cannot be
+ * enumerated without the item list and give nothing.
+ */
+function between(a: string, b: string): string[] {
+  const pa = a.split('.');
+  const pb = b.split('.');
+  if (pa.length !== pb.length || pa.slice(0, -1).join('.') !== pb.slice(0, -1).join('.')) return [];
+  const lo = Number(pa[pa.length - 1]);
+  const hi = Number(pb[pb.length - 1]);
+  if (!(hi > lo && hi - lo < 200)) return [];
+  const prefix = pa.slice(0, -1).map((p) => `${p}.`).join('');
+  return Array.from({ length: hi - lo - 1 }, (_, k) => `${prefix}${lo + 1 + k}`);
+}
+
+/**
+ * Item numbers a cell cites: `item 9`, `item 2, 3, 7`, `item 4–6`, `item 5.4–5.8`, `項目 4.3〜4.6`, `UI #9`,
+ * `UI-009`, `[9]`, `§4.3.2`. Prose (`Auth guard`), message codes (`M02`) and question ids
+ * (`Q-01`) are not refs.
+ */
+export function extractRefs(text: string): string[] {
+  const refs = new Set<string>();
+  const add = (s: string): void => { const r = normRef(s); if (r) refs.add(r); };
+  for (const m of text.matchAll(LIST)) {
+    let prev: string | null = null;
+    let range = false;
+    for (const tok of m[1].matchAll(new RegExp(`(${NUM})|([-–—~〜～])`, 'g'))) {
+      if (tok[2]) { range = prev !== null; continue; }
+      const n = normRef(tok[1]);
+      if (!n) continue;
+      if (range && prev) for (const r of between(prev, n)) refs.add(r);
+      refs.add(n); prev = n; range = false;
+    }
+  }
+  for (const m of text.matchAll(/\[(\d{1,3})\]/g)) add(m[1]);
+  for (const m of text.matchAll(/§\s*(\d{1,3}(?:\.\d{1,3})*)/g)) add(m[1]);
+  return [...refs];
+}
+
+export type ItemSource = 'spec-ids' | 'spec-table' | 'spec-ids+spec-table' | 'ui-inventory' | 'none';
+export interface UniverseItem { ref: string; name: string }
+/** Every list a citation could point at, each in its own notation. */
+export interface ItemUniverses { specIds: UniverseItem[]; specTable: UniverseItem[]; inventory: UniverseItem[] }
+
+const NO_COL = /^(no\.?|#|stt|№|番号)$/i;
+const TYPE_COL = /種別|\b(type|kind)\b|loại/i;
+const NAME_COL = /item|name|tên|項目|名|field|label|trường|thành phần|component/i;
+
+/**
+ * The unit's lists, by where each id is DECLARED: requirement ids spec.md declares (`**FR-BC-03**:`),
+ * the spec's item table (`No` + name + type columns), and ui-inventory ids (`UI-NNN`). An id's shape
+ * says nothing about which list it belongs to — `item 9` on a mockup and `UI-009` in the inventory
+ * number different things.
+ */
+export function itemUniverses(reqDir: string): ItemUniverses {
+  const read = (f: string): string | null => {
+    const p = path.join(reqDir, f);
+    return fs.existsSync(p) ? stripHtmlComments(readTextFile(p)) : null;
+  };
+  const out: ItemUniverses = { specIds: [], specTable: [], inventory: [] };
+  const spec = read('spec.md');
+  if (spec) {
+    out.specIds = parseSpecClauses(path.join(reqDir, 'spec.md')).frs.map((f) => ({ ref: f.id, name: f.text.slice(0, 80) }));
+    for (const row of tableRows(spec)) {
+      const h = row.header;
+      const no = h?.findIndex((c) => NO_COL.test(c)) ?? -1;
+      const type = h?.findIndex((c) => TYPE_COL.test(c)) ?? -1;
+      const name = h?.findIndex((c, i) => i !== no && i !== type && NAME_COL.test(c)) ?? -1;
+      if (no < 0 || type < 0 || name < 0) continue;
+      const ref = normRef(row.cells[no] ?? '');
+      if (ref) out.specTable.push({ ref, name: row.cells[name] ?? '' });
+    }
+  }
+  const inv = read('ui-inventory.md');
+  if (inv) {
+    out.inventory = parseUiInventory(inv).items.flatMap((i) => {
+      const ref = normRef(i.id.replace(/^UI-/i, ''));
+      return ref ? [{ ref, name: i.item }] : [];
+    });
+  }
+  return out;
+}
+
+/**
+ * The list(s) the viewpoint actually cites — a list nobody cites says nothing about gaps. The spec's
+ * ids and its item table, each when cited (both when both are: the notations cannot collide, and
+ * dropping one would under-report); the table also when nothing is cited at all (then every item is
+ * uncited, which is true); the inventory only when the viewpoint writes `UI-NNN`; else none.
+ */
+export function citedUniverse(u: ItemUniverses, cited: ReadonlySet<string>, writesInventoryIds: boolean): { source: ItemSource; items: UniverseItem[] } {
+  const hits = (items: UniverseItem[]): boolean => items.some((i) => cited.has(i.ref));
+  const ids = hits(u.specIds);
+  const table = u.specTable.length > 0 && (cited.size === 0 || hits(u.specTable));
+  if (ids && table) return { source: 'spec-ids+spec-table', items: [...u.specIds, ...u.specTable] };
+  if (ids) return { source: 'spec-ids', items: u.specIds };
+  if (table) return { source: 'spec-table', items: u.specTable };
+  if (writesInventoryIds && hits(u.inventory)) return { source: 'ui-inventory', items: u.inventory };
+  return { source: 'none', items: [] };
+}

package/src/harness/viewpoint-scan.ts

@@ -0,0 +1,111 @@
+/**
+ * `sungen viewpoint scan` — the code half of reviewing a QA-written test-viewpoint.md.
+ *
+ * It does set arithmetic on ids and nothing else: which VP rows exist, what each cites, which spec
+ * items nobody cites, which ids no scenario carries. It never judges meaning, never edits the file,
+ * and feeds no audit finding, score or baseline.
+ *
+ * A VP row is a markdown table row whose FIRST cell is a full id (`VP-UI-001`, `FL-LOGIN-3`).
+ * Priority-table rows (`VP-LOGIN (Auth)`), bullets and appendix text are not rows. This is
+ * deliberately NOT `parseViewpointItems` (viewpoint-ledger.ts), which also reads id-less rows.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { readViewpointText, readTextFile } from './read-text';
+import { featureFilesFor } from './unit-paths';
+import { tableRows, extractRefs, itemUniverses, citedUniverse, ItemSource } from './viewpoint-scan-refs';
+import { viewpointMode, ViewpointMode } from './viewpoint-mode';
+
+export interface VpRow {
+  id: string;
+  line: number;
+  /** Item numbers the row cites (normalised: `009` → `9`), and spec-declared ids it cites (`FR-BC-03`). */
+  refs: string[];
+  /** `# MANUAL/ENV` or `@manual` on the row or an enclosing heading. */
+  manual: boolean;
+  /** The Kỳ vọng / Expected cell has text (best effort when the table has no such header). */
+  hasExpected: boolean;
+}
+
+export interface ViewpointScan {
+  /** The create-test mode this file calls for (viewpoint-mode.ts): 2 = AI drafts, 1 = review only. */
+  mode: ViewpointMode;
+  modeReason: string;
+  vpRows: VpRow[];
+  /** Distinct VP ids among `vpRows` — a reused id is several rows but one id. */
+  distinctIds: number;
+  rowsWithoutExpected: string[];
+  manualRows: string[];
+  itemSource: ItemSource;
+  /** Spec/inventory items no VP row cites — a hint for the review, not a verdict. */
+  uncitedItems: { ref: string; name: string }[];
+  /** VP ids no feature file mentions; null when the unit has no feature file yet. */
+  withoutScenario: string[] | null;
+  /** Why `vpRows` is empty, else null. */
+  note: string | null;
+}
+
+const VP_ID = /^(VP|FL)-[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\d+$/;
+const MANUAL = /\bMANUAL\/ENV\b|@manual\b/i;
+const EXPECTED_COL = /kỳ vọng|kết quả mong đợi|expected|期待/i;
+/** Whole-word match (Unicode-aware: `\b` fails on `ồ`) so `Resource` / `Datasource` are not a source column. */
+const SOURCE_COL = /(?<![\p{L}\p{N}])(?:nguồn|source|tham chiếu|ref|出典|根拠)(?![\p{L}\p{N}])/iu;
+const PRIORITY = /^(critical|high|med(?:ium)?|low|cao|trung bình|thấp)$/i;
+const BLANK = /^[\s\-–—…]*$/;
+const SPEC_ID = /(?<![\w-])[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+[A-Z]?(?![\w-])/gi;
+export const NO_VP_IDS_NOTE = 'file has no VP ids; review falls back to AI-only';
+
+/**
+ * VP rows of one viewpoint text (already comment-stripped, as `readViewpointText` returns it).
+ * `specIds`: the requirement ids spec.md declares — only those count as spec citations.
+ */
+export function scanViewpointText(text: string, specIds: ReadonlySet<string> = new Set()): VpRow[] {
+  const rows: VpRow[] = [];
+  for (const r of tableRows(text)) {
+    const id = r.cells[0];
+    if (!VP_ID.test(id)) continue;
+    const exp = r.header?.findIndex((c) => EXPECTED_COL.test(c)) ?? -1;
+    const src = r.header?.findIndex((c) => SOURCE_COL.test(c)) ?? -1;
+    const cites = src > 0 ? r.cells[src] ?? '' : r.cells.slice(1).join(' | ');
+    rows.push({
+      id,
+      line: r.line,
+      refs: [...extractRefs(cites), ...[...cites.matchAll(SPEC_ID)].map((m) => m[0].toUpperCase()).filter((id) => specIds.has(id))],
+      manual: MANUAL.test(r.raw) || MANUAL.test(r.section),
+      // Without a Kỳ vọng header: any later cell with text that is neither a priority word nor a ref.
+      hasExpected: exp > 0
+        ? !BLANK.test(r.cells[exp] ?? '')
+        : r.cells.slice(2).some((c) => !BLANK.test(c) && !PRIORITY.test(c) && extractRefs(c).length === 0),
+    });
+  }
+  return rows;
+}
+
+/** Scan one unit directory (`qa/screens/<n>`, `qa/flows/<n>`, …); `unit` names its feature files. */
+export function scanViewpointUnit(unitDir: string, unit: string): ViewpointScan {
+  const reqDir = path.join(unitDir, 'requirements');
+  const vpPath = path.join(reqDir, 'test-viewpoint.md');
+  const vpText = readViewpointText(vpPath);
+  const universes = itemUniverses(reqDir);
+  const vpRows = scanViewpointText(vpText, new Set(universes.specIds.map((i) => i.ref)));
+  const { mode, reason } = viewpointMode(fs.existsSync(vpPath) ? readTextFile(vpPath) : null, vpRows);
+  const cited = new Set(vpRows.flatMap((r) => r.refs));
+  const { source, items } = citedUniverse(universes, cited, /(?<![\w-])UI-\d{1,3}\b/i.test(vpText));
+  const features = featureFilesFor(unitDir, unit).filter((f) => fs.existsSync(f));
+  // Same rule as the ledger (viewpoint-ledger.ts): an id is carried when the feature text contains it.
+  const featureText = features.map((f) => readTextFile(f).toLowerCase()).join('\n');
+
+  return {
+    mode,
+    modeReason: reason,
+    vpRows,
+    distinctIds: new Set(vpRows.map((r) => r.id)).size,
+    rowsWithoutExpected: vpRows.filter((r) => !r.hasExpected).map((r) => r.id),
+    manualRows: vpRows.filter((r) => r.manual).map((r) => r.id),
+    itemSource: source,
+    uncitedItems: items.filter((i) => !cited.has(i.ref)),
+    withoutScenario: features.length === 0 ? null : vpRows.filter((r) => !featureText.includes(r.id.toLowerCase())).map((r) => r.id),
+    note: vpRows.length > 0 ? null
+      : fs.existsSync(vpPath) ? NO_VP_IDS_NOTE : 'requirements/test-viewpoint.md is missing',
+  };
+}

package/src/orchestrator/flow-manager.ts

@@ -8,6 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { readCapabilities } from '../harness/capability';
 import { testDataHeader, ensureTestDataGuideFiles } from './test-data-guide';
+import { viewpointScaffold } from './viewpoint-scaffold';
 
 export interface FlowOptions {
   name: string;
@@ -143,7 +144,7 @@ export class FlowManager {
     fs.writeFileSync(specPath, this.generateSpecTemplate(options, flowName, isMobile), 'utf-8');
 
     const viewpointPath = path.join(requirementsDir, 'test-viewpoint.md');
-    fs.writeFileSync(viewpointPath, this.generateViewpointTemplate(options), 'utf-8');
+    fs.writeFileSync(viewpointPath, viewpointScaffold(`${options.name} Flow`, isMobile), 'utf-8');
 
     console.log(`Created files:`);
     console.log(`  ${path.relative(this.cwd, featurePath)}`);
@@ -217,7 +218,7 @@ export class FlowManager {
       restored.push(file);
     };
     ensure(path.join(paths.requirementsDir, 'spec.md'), () => this.generateSpecTemplate(options, flowName, isMobile));
-    ensure(path.join(paths.requirementsDir, 'test-viewpoint.md'), () => this.generateViewpointTemplate(options));
+    ensure(path.join(paths.requirementsDir, 'test-viewpoint.md'), () => viewpointScaffold(`${options.name} Flow`, isMobile));
     ensure(paths.featurePath, () => this.generateFeatureTemplate(options, flowName, isMobile));
     return restored;
   }
@@ -287,57 +288,6 @@ export class FlowManager {
 `;
   }
 
-  private generateViewpointTemplate(options: FlowOptions): string {
-    return [
-      `# ${options.name} Flow — Test Viewpoints`,
-      '',
-      '## Edge Cases',
-      '',
-      '<!-- Sample — replace with actual edge cases for this flow:',
-      '- Network drops between screen transitions — should resume or show error?',
-      '- Session expires mid-flow — should redirect to login and preserve progress?',
-      '- Browser back button at step 3 — should return to step 2 with data intact?',
-      '- Complete flow twice rapidly — should prevent duplicate submissions',
-      '-->',
-      '',
-      '## Known Issues',
-      '',
-      '<!-- Sample — replace with actual known issues:',
-      '- [BUG-001] Form data lost if user navigates away and returns',
-      '- [BUG-002] Confirmation page shows stale data on slow connections',
-      '-->',
-      '',
-      '## Design Decisions',
-      '',
-      '<!-- Sample — replace with actual design decisions:',
-      '- Flow requires completing all steps in order (no skip)',
-      '- Draft is auto-saved at each step transition',
-      '- Cancel at any step discards the entire flow',
-      '-->',
-      '',
-      '## Cross-Screen Concerns',
-      '',
-      '<!-- Sample — replace with actual cross-screen concerns:',
-      '- Auth role must remain consistent across all screens',
-      '- Data entered in step 1 must be visible in confirmation (step 3)',
-      '- Error in step 2 should allow returning to step 1 without re-entering data',
-      '-->',
-      '',
-      '## Priority Viewpoints',
-      '',
-      '<!-- Rate importance for this flow (High / Medium / Low / Skip):',
-      '',
-      '| VP | Priority | Reason |',
-      '|---|----------|--------|',
-      '| VP-UI | Medium | Standard forms across screens |',
-      '| VP-VAL | High | Cross-screen validation rules |',
-      '| VP-LOGIC | High | Multi-step business logic, state transitions |',
-      '| VP-SEC | Medium | Auth must persist, role-based access at each screen |',
-      '-->',
-      '',
-    ].join('\n');
-  }
-
   private generateFeatureTemplate(options: FlowOptions, flowName: string, isMobile: boolean): string {
     const description = options.description || `complete the ${options.name} flow`;
 

package/src/orchestrator/screen-manager.ts

@@ -5,10 +5,10 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import { chromium } from '@playwright/test';
 import { readCapabilities } from '../harness/capability';
 import { testDataHeader, ensureTestDataGuideFiles } from './test-data-guide';
 import { resolveWebBaseUrl } from '../exporters/env-qa';
+import { viewpointScaffold } from './viewpoint-scaffold';
 
 export interface ScreenOptions {
   name: string;
@@ -158,68 +158,11 @@ export class ScreenManager {
       fs.writeFileSync(specPath, this.generateSpecTemplate(options, screenName), 'utf-8');
     }
 
-    // Generate requirements test-viewpoint.md (only on first screen creation)
+    // Generate requirements test-viewpoint.md (only on first screen creation): the QA template,
+    // samples inside comments, so an untouched file declares nothing (see viewpoint-scaffold.ts).
     const viewpointPath = path.join(requirementsDir, 'test-viewpoint.md');
     if (!fs.existsSync(viewpointPath)) {
-      fs.writeFileSync(viewpointPath, [
-        `# ${options.name} — Test Viewpoints`,
-        '',
-        '## Edge Cases',
-        '',
-        '<!-- Sample — replace with actual edge cases for this screen:',
-        '- Paste emoji into text fields (e.g., 🎉👋) — should accept or sanitize?',
-        '- Input 10,000+ characters into free text — truncate or reject?',
-        '- Double-click Submit rapidly — should only create 1 record',
-        '- Browser back button after successful submit — should not re-submit',
-        '-->',
-        '',
-        '## Known Issues',
-        '',
-        '<!-- Sample — replace with actual known issues:',
-        '- [BUG-001] Date picker does not work on Safari < 16',
-        '- [BUG-002] File upload silently fails for files > 20MB (no error shown)',
-        '- Search does not handle Vietnamese accents correctly ("Nguyên" ≠ "Nguyen")',
-        '-->',
-        '',
-        '## Design Decisions',
-        '',
-        '<!-- Sample — replace with actual design decisions:',
-        '- Show all validation errors at once (not one at a time) — per UX review',
-        '- Cancel button resets form completely (no draft saving)',
-        '- Anonymous mode hides sender name but keeps department visible',
-        '-->',
-        '',
-        '## UI Patterns Identified',
-        '',
-        '<!-- Check applicable patterns for this screen (from 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 | ☐ | |',
-        '-->',
-        '',
-        '## Priority Viewpoints',
-        '',
-        '<!-- Rate importance for this screen (High / Medium / Low / Skip):',
-        '',
-        '| VP | Priority | Reason |',
-        '|---|----------|--------|',
-        '| VP-UI | High | Complex form with many states |',
-        '| VP-VAL | High | 14 validation rules from spec |',
-        '| VP-LOGIC | Medium | Standard CRUD, no complex business rules |',
-        '| VP-SEC | Low | Internal tool, basic auth only |',
-        '-->',
-        '',
-      ].join('\n'), 'utf-8');
+      fs.writeFileSync(viewpointPath, viewpointScaffold(options.name, isMobile), 'utf-8');
     }
 
     // Auto-screenshot: capture page only when --capture is set and not mobile (requires --path)
@@ -272,6 +215,9 @@ export class ScreenManager {
 
     let browser;
     try {
+      // Loaded here, not at module top: @playwright/test is a peerDependency a mobile project never
+      // installs, and `sungen add` loads this module on every platform (#865).
+      const { chromium } = await import('@playwright/test');
       browser = await chromium.launch();
       const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
       await page.goto(url, { waitUntil: 'networkidle', timeout: 15000 });

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>
 ```