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

package/src/orchestrator/project-initializer.ts

@@ -17,6 +17,8 @@ import {
   installMobileDriver,
 } from './mobile-runtime-scaffolder';
 import { emitAppiumEnvironment, runAppiumEnvironmentSetup, appiumEnvironmentRerunCommand } from './appium-environment-setup';
+import { ensureSecurityOverrides, reportSecurityOverrides } from './security-overrides';
+import { readTextFile } from '../harness/read-text';
 
 export { MobileInitOptions };
 
@@ -94,6 +96,14 @@ export class ProjectInitializer {
   private cwd: string;
   private createdItems: string[] = [];
   private skippedItems: string[] = [];
+  /**
+   * Actions the user asked for that could NOT be performed. Kept apart from `skippedItems`:
+   * that list renders under "Already exists", which is a statement of fact about the project —
+   * printing "package.json scripts (invalid JSON)" under it tells the user the opposite of what
+   * happened. An action that was not done needs its own heading, or the init summary reads as a
+   * clean success while `npm test` is missing.
+   */
+  private notDoneItems: string[] = [];
   /** set by createCodexMCPConfig when the project isn't Codex-trusted (config would never load) */
   private codexTrustWarning = false;
   private agents: AdapterKey[];
@@ -135,6 +145,7 @@ export class ProjectInitializer {
       : this.baseCwd;
     this.createdItems = [];
     this.skippedItems = [];
+    this.notDoneItems = [];
 
     console.log(`🚀 Initializing Sungen ${this.mobileOnly ? 'mobile-only ' : ''}project...\n`);
 
@@ -439,9 +450,17 @@ export class ProjectInitializer {
 
     if (existed) {
       try {
-        config = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-      } catch {
-        this.skippedItems.push(`${displayName} (invalid JSON, skipped)`);
+        // via readTextFile: a UTF-8 BOM is the one thing `JSON.parse` rejects that every other tool
+        // reading this file ignores, and it is invisible in an editor. A config the rest of the
+        // toolchain loads fine must not cost the user their MCP servers here.
+        config = JSON.parse(readTextFile(filePath));
+      } catch (e) {
+        // Anything still unparseable is genuinely broken. Say WHERE — "is not valid JSON" alone
+        // leaves the user to find a missing comma in a file they did not know was the problem.
+        this.notDoneItems.push(
+          `${displayName} (${(e as Error).message.split('\n')[0]}) — MCP servers not registered; `
+          + `fix the JSON and re-run \`sungen init\``,
+        );
         return;
       }
     }
@@ -487,6 +506,13 @@ export class ProjectInitializer {
       });
     }
 
+    if (this.notDoneItems.length > 0) {
+      console.log('\n⚠ Not done — needs your attention:');
+      this.notDoneItems.forEach(item => {
+        console.log(`  ✗ ${item}`);
+      });
+    }
+
     if (this.codexTrustWarning) {
       console.log('\n⚠ Codex: this project is not trusted yet, so .codex/config.toml (the MCP browser');
       console.log('  config for run-test) will be SILENTLY IGNORED by Codex. To fix, either:');
@@ -685,6 +711,13 @@ export class ProjectInitializer {
     // Ensure standard scripts exist in package.json
     this.ensurePackageScripts(packageJsonPath);
 
+    // Pin the transitive packages that would otherwise make `npm audit` red here. This MUST happen
+    // before the install below: npm reads `overrides` at resolution time, so a lockfile written
+    // first would already hold the vulnerable versions. See security-overrides.ts for why the pins
+    // cannot simply live in sungen's own manifest.
+    const overridePlan = ensureSecurityOverrides(packageJsonPath);
+    reportSecurityOverrides(overridePlan);
+
     // Mobile-only drops @playwright/test (no web runner needed). `ajv`/`ajv-formats` back the API
     // Driver's `expect {{name.body}} matches schema [Ref]` (loaded lazily; harmless if unused).
     // fast-xml-parser: the API driver's XML request/response support lazy-requires it
@@ -696,7 +729,7 @@ export class ProjectInitializer {
 
     let missingDeps: string[] = requiredDeps;
     try {
-      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+      const packageJson = JSON.parse(readTextFile(packageJsonPath));
       const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
       missingDeps = requiredDeps.filter(d => !deps[d]);
     } catch {
@@ -705,6 +738,12 @@ export class ProjectInitializer {
 
     if (missingDeps.length === 0) {
       console.log('✓ All dependencies already installed\n');
+      // Nothing to install means nothing re-resolves, so overrides just written would sit in
+      // package.json while the lockfile keeps the vulnerable tree. Re-resolve once so they land.
+      if (overridePlan?.add.length) {
+        console.log('📦 Re-resolving the tree so the new security overrides take effect...\n');
+        execSync('npm install', execOpts);
+      }
     } else {
       console.log(`📦 Installing ${missingDeps.join(', ')}...\n`);
       execSync(`npm install -D ${missingDeps.join(' ')}`, execOpts);
@@ -725,8 +764,17 @@ export class ProjectInitializer {
   private ensurePackageScripts(packageJsonPath: string): void {
     let packageJson: Record<string, any>;
     try {
-      packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-    } catch {
+      // via readTextFile: a package.json carrying a UTF-8 BOM is one npm reads without complaint,
+      // so it must not be treated as unparseable here. That was the trigger that actually reached
+      // this catch — genuinely broken JSON aborts `npm install` a few lines below instead.
+      packageJson = JSON.parse(readTextFile(packageJsonPath));
+    } catch (e) {
+      // Returning here used to add nothing and say nothing, so init reported success and the user
+      // met `npm error Missing script: "test"` later with nothing pointing back to this run.
+      this.notDoneItems.push(
+        `package.json scripts (${(e as Error).message.split('\n')[0]}) — `
+        + `fix the JSON and re-run \`sungen init\`, or add the scripts by hand`,
+      );
       return;
     }
 

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/security-overrides-catalog.ts

@@ -0,0 +1,69 @@
+/**
+ * npm `overrides` a sungen project needs in order to pass `npm audit`.
+ *
+ * Why this lives in the CLI instead of in `packages/core/package.json`: npm honours `overrides`
+ * ONLY in the root `package.json` of the project doing the installing. A block declared by a
+ * DEPENDENCY is inert — it is not read, not merged, and not carried in the published tarball. So
+ * the monorepo root can (and does) pin these for itself while every consumer of the published
+ * packages still resolves the vulnerable versions. Repo green, install red, and nobody working in
+ * the repo ever sees what a consumer sees. Issue #764.
+ *
+ * Sungen already writes to the consuming project's `package.json` (standard scripts on `init`,
+ * family version pinning on `update`), so the overrides go in on the same two passes. That makes
+ * the fix reachable the ordinary way: a new project is clean from its first install, an existing
+ * one becomes clean on the next `sungen update`.
+ *
+ * Every entry below is here because NOTHING ELSE CLEARS IT — the offending package is either at its
+ * latest published version already, or is hard-pinned by an unmaintained parent. Bumping sungen's
+ * own declared ranges does not move any of them: `@sungen/driver-mobile` is already on the newest
+ * appium (3.x) and webdriverio (9.x), and npm's own `fix available` for that chain is a DOWNGRADE
+ * to appium 1.22.3 / webdriverio 8.14.6, not a fix.
+ *
+ * Measured on a clean-room install of the published 3.2.32 family (2026-09-23): 25 findings
+ * (12 moderate, 13 high) without this block, 0 with it.
+ */
+
+export interface SecurityOverride {
+  /** Package to pin, as it appears in `overrides`. */
+  pkg: string;
+  /** Range to pin it to — the lowest published version clear of the advisory. */
+  range: string;
+  /** Advisory + the path that drags the vulnerable copy in, so a reader can re-check the entry. */
+  why: string;
+}
+
+/**
+ * The pinned set. Keep it MINIMAL: an entry earns its place only while a clean install is red
+ * without it. When an upstream finally ships a fix inside its own declared range, delete the entry
+ * rather than raising it — a stale override silently holds a whole subtree back.
+ */
+export const SECURITY_OVERRIDES: SecurityOverride[] = [
+  {
+    pkg: 'uuid',
+    range: '^11.1.1',
+    // exceljs 4.4.0 IS the latest (published 2024-12-20) and hard-declares "uuid": "^8.3.0".
+    // There is no newer exceljs to bump to, which is why npm reports fixAvailable: false.
+    why: 'GHSA-w5hq-g745-h8pq (moderate) — uuid@8.3.2 via exceljs@4.4.0, which is unmaintained and pins ^8.3.0',
+  },
+  {
+    pkg: 'morgan',
+    range: '^1.12.1',
+    // @appium/base-driver pins the exact version "1.11.0", so no resolution reaches 1.12.x on its own.
+    why: 'GHSA-jxfw-x594-9x9m (moderate) — morgan@1.11.0 exact-pinned by @appium/base-driver',
+  },
+  {
+    pkg: 'serialize-javascript',
+    range: '^7.1.2',
+    why: 'GHSA-5c6j-r48x-rmvq (high) + GHSA-qj8w-gfj5-8c6v (moderate) — serialize-javascript@6.0.2 via mocha (^6.0.2)',
+  },
+  {
+    pkg: '@puppeteer/browsers',
+    range: '^3.2.3',
+    // The vulnerable package is extract-zip, whose latest (2.0.1) IS the flagged version — there is
+    // nothing to pin it to. @puppeteer/browsers 3.x dropped extract-zip for modern-tar, so the pin
+    // goes on the parent instead. @wdio/utils asks for ^2.2.0 but imports only install, canDownload,
+    // resolveBuildId, detectBrowserPlatform, Browser, ChromeReleaseChannel and computeExecutablePath
+    // — all seven still exported by 3.2.3, verified against @wdio/utils@9.32.0.
+    why: 'GHSA-jmr9-qjv8-65gv + GHSA-7pqw-9j4j-h8q3 (high) — extract-zip@2.0.1 via @puppeteer/browsers@2.x ← @wdio/utils; extract-zip has no fixed release, 3.x replaced it with modern-tar',
+  },
+];

package/src/orchestrator/security-overrides.ts

@@ -0,0 +1,149 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { SECURITY_OVERRIDES, SecurityOverride } from './security-overrides-catalog';
+
+/**
+ * Merge the security-override catalog into a consuming project's `package.json`.
+ *
+ * The catalog itself — which packages, which ranges, and why each one cannot be cleared any other
+ * way — lives in `security-overrides-catalog.ts`. That is the file to edit when an advisory moves;
+ * this one holds only the merge, the write and the reporting, which do not change when it does.
+ */
+
+export { SECURITY_OVERRIDES } from './security-overrides-catalog';
+export type { SecurityOverride } from './security-overrides-catalog';
+
+export interface OverridePlan {
+  /** Entries missing from the project, to be written. */
+  add: SecurityOverride[];
+  /** Entries the project already pins itself — left untouched, reported so the user can judge. */
+  existing: Array<{ pkg: string; declared: string; wanted: string }>;
+  /** Set when the pins were needed but the write failed — `add` is then empty, nothing was applied. */
+  writeFailed?: boolean;
+  /** Lockfile of a package manager that ignores `overrides`, when the project has one. */
+  foreignLockfile?: 'yarn' | 'pnpm';
+}
+
+/**
+ * Decide what a project's `overrides` block is missing. Pure — no I/O, so the tests and `--dry-run`
+ * can plan without touching anything.
+ *
+ * A pin the project already declares is NEVER rewritten, even when it differs from ours. Someone who
+ * typed a range into their own `package.json` had a reason (a private mirror, a pinned fork, a
+ * downgrade forced by another tool), and silently overwriting it would be the more surprising bug.
+ * It is reported instead, so a still-vulnerable pin is visible rather than swallowed.
+ */
+export function planSecurityOverrides(pkgJson: Record<string, any>): OverridePlan {
+  const current: Record<string, unknown> =
+    pkgJson.overrides && typeof pkgJson.overrides === 'object' ? pkgJson.overrides : {};
+
+  const add: SecurityOverride[] = [];
+  const existing: OverridePlan['existing'] = [];
+
+  for (const entry of SECURITY_OVERRIDES) {
+    const declared = current[entry.pkg];
+    if (typeof declared === 'string') {
+      if (declared !== entry.range) existing.push({ pkg: entry.pkg, declared, wanted: entry.range });
+      continue;
+    }
+    // A nested override object ({ "uuid": { ".": "^11" } }) is a deliberate, more specific shape —
+    // treat it as the project's own decision and leave it alone.
+    if (declared !== undefined) {
+      existing.push({ pkg: entry.pkg, declared: JSON.stringify(declared), wanted: entry.range });
+      continue;
+    }
+    add.push(entry);
+  }
+
+  return { add, existing };
+}
+
+/**
+ * Write the missing overrides into a project's `package.json`.
+ *
+ * Best-effort by design, exactly like the rest of the project-file touching in `init` / `update`: an
+ * unreadable or malformed `package.json` means we skip silently rather than fail the command the
+ * user actually ran. The audit gate is not worth losing a scaffold over.
+ *
+ * Must run BEFORE the project's `npm install`, or the first resolution pass writes a lockfile that
+ * already pins the vulnerable versions.
+ *
+ * @param dryRun plan only — report what would change and write nothing
+ * @returns the plan that was applied, or null when there was no `package.json` to apply it to
+ */
+export function ensureSecurityOverrides(packageJsonPath: string, dryRun = false): OverridePlan | null {
+  let pkgJson: Record<string, any>;
+  try {
+    pkgJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+
+  const plan = planSecurityOverrides(pkgJson);
+  plan.foreignLockfile = detectForeignLockfile(path.dirname(packageJsonPath));
+
+  if (plan.add.length && !dryRun) {
+    const overrides: Record<string, unknown> =
+      pkgJson.overrides && typeof pkgJson.overrides === 'object' ? pkgJson.overrides : {};
+    for (const entry of plan.add) overrides[entry.pkg] = entry.range;
+    pkgJson.overrides = overrides;
+    try {
+      fs.writeFileSync(packageJsonPath, JSON.stringify(pkgJson, null, 2) + '\n', 'utf-8');
+    } catch {
+      // Read-only checkout, root-owned file, read-only container mount. `sungen update` in
+      // particular has ALREADY reinstalled globally by the time it gets here, so throwing would
+      // abandon the AI-rules refresh and the family sync over a hardening step. Report and move on.
+      return { add: [], existing: plan.existing, foreignLockfile: plan.foreignLockfile, writeFailed: true };
+    }
+  }
+
+  return plan;
+}
+
+/**
+ * npm is the only package manager that reads a top-level `overrides` block. Yarn wants
+ * `resolutions`, pnpm wants `pnpm.overrides` — so on those projects the block we write is inert and
+ * the install stays vulnerable. We do NOT guess at the equivalent field (getting a resolutions
+ * pattern subtly wrong is worse than not writing one), but silence would be the same class of bug
+ * as #764 itself: a fix that looks applied and is not. So: say so.
+ */
+function detectForeignLockfile(dir: string): 'yarn' | 'pnpm' | undefined {
+  if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn';
+  return undefined;
+}
+
+/** Print what `ensureSecurityOverrides` did, in the voice the surrounding commands already use. */
+export function reportSecurityOverrides(plan: OverridePlan | null, dryRun = false): void {
+  if (!plan) return;
+
+  if (plan.writeFailed) {
+    console.warn(
+      '⚠️  Could not write the security overrides into package.json (read-only file?). Nothing else\n' +
+      '   failed. Add this block by hand to keep `npm audit` clean:\n' +
+      `       "overrides": ${JSON.stringify(Object.fromEntries(SECURITY_OVERRIDES.map((o) => [o.pkg, o.range])), null, 2).replace(/\n/g, '\n       ')}\n`,
+    );
+    return;
+  }
+
+  if (plan.add.length) {
+    const verb = dryRun ? '[dry-run] would add' : 'Added';
+    console.log(`🔒 ${verb} ${plan.add.length} security override(s) to package.json — npm honours these only here, not from sungen's own manifest:`);
+    for (const entry of plan.add) console.log(`   • ${entry.pkg}@${entry.range}  — ${entry.why}`);
+    console.log('');
+  }
+
+  if (plan.existing.length) {
+    console.log('🔒 Left your own overrides alone (sungen never rewrites a pin you declared):');
+    for (const e of plan.existing) console.log(`   – ${e.pkg}: ${e.declared}  (sungen would use ${e.wanted})`);
+    console.log('   If `npm audit` still flags one of these, raise it by hand.\n');
+  }
+
+  if (plan.foreignLockfile && (plan.add.length || plan.existing.length)) {
+    const field = plan.foreignLockfile === 'pnpm' ? '"pnpm": { "overrides": … }' : '"resolutions"';
+    console.warn(
+      `⚠️  This project has a ${plan.foreignLockfile} lockfile. ${plan.foreignLockfile} ignores npm's "overrides" —\n` +
+      `   mirror the block into ${field} as well, or the pins do nothing here.\n`,
+    );
+  }
+}

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

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -64,7 +64,8 @@ restated from screen specs the project does not hold, say so: the audit reports
 `SPEC-RESTATED-UNVERIFIED` because `specFR 100%` over a hand-copied list certifies the copy, not
 the source.
 
-**The viewpoint carries BOTH classification axes.** `VP-LOGIC / VP-VAL / VP-SEC / VP-NAV` classify
+**A viewpoint you draft (mode 2, step 3) carries BOTH classification axes** — on a QA-written one
+(mode 1) a missing axis or guarantee line is a row in `viewpoint-review.md`, not an edit. `VP-LOGIC / VP-VAL / VP-SEC / VP-NAV` classify
 by TECHNICAL RISK; `BF / AF / EF` classify by BUSINESS BRANCH. They answer different questions and
 neither replaces the other — a reviewer needs to see both, so use the compound id
 (`VP-SEC-EF02-001`) and give the viewpoint a section per flow as well as its priority table by
@@ -81,8 +82,8 @@ questions and only one of them is a yardstick:
 | `flow-contract.yaml` | the USE CASE — actor · trigger · goal · precondition · both guarantees · the flow inventory | `flowCoverage` |
 | `test-viewpoint.md` | the CLAIMS the suite must prove — cross-screen concerns, edge cases, design decisions, open questions, priorities | `atomicLedger` · `traceability` |
 
-If `requirements/test-viewpoint.md` is missing, **write it before generating** (`add-flow` scaffolds
-a template; a run that deletes or replaces it has removed the yardstick). Without it two scored
+If `requirements/test-viewpoint.md` is missing or still the scaffold, **draft it before generating**
+(mode 2, step 3 — `add-flow` scaffolds the template; a run that deletes or replaces it has removed the yardstick). Without it two scored
 axes are excluded and four sensors cannot run at all — the atomic ledger, the
 declaration-integrity checks, the browser-gesture check and the two-way continuity check — so the
 audit reports `VIEWPOINT-MISSING` and the result is *unmeasured*, not passing. And the reason the
@@ -95,8 +96,8 @@ ordering choice: a yardstick derived from the scenarios reads 100% by constructi
 dropped along the way stops being missing from anything. `sungen audit` now reports
 `VIEWPOINT-ADOPTED-POST-HOC` on the first sighting of a viewpoint alongside an existing suite and
 holds `atomicLedger` + `traceability` as unverified until a human accepts it — so the honest move
-is to write the claims from `spec.md` and the contract, mark plainly that they are a draft for QA
-review, and let the QA revise before `--accept-viewpoint`. **You never run `--accept-viewpoint` yourself** — `sungen next` lists it as a `⚖ decide` step for exactly this reason: an agent accepting the yardstick it wrote in the same session makes `atomicLedger` and `traceability` read 100% against its own checklist, and the Exception Flow it forgot stops being missing from anything. Present the acceptance to the QA (`AskUserQuestion`) with what the file declares, and stop.
+is to write the claims from `spec.md` and the contract, mark the file `drafted-by: ai` (its first
+line), and let the QA revise before `--accept-viewpoint`. **You never run `--accept-viewpoint` yourself** — `sungen next` lists it as a `⚖ decide` step for exactly this reason: an agent accepting the yardstick it wrote in the same session makes `atomicLedger` and `traceability` read 100% against its own checklist, and the Exception Flow it forgot stops being missing from anything. Present the acceptance to the QA in the hand-back (`AskUserQuestion`) with what the file declares — never as a question mid-run.
 
 **When you give a claim an id, a scenario must carry that id.** The id is the contract: a claim
 whose id no scenario carries is reported MISSING, and word overlap will not rescue it. Several
@@ -110,8 +111,9 @@ narrow the claim to what is actually proven.
 
 **Priority comes from the declaration.** A scenario tagged `@high` under a viewpoint row that says
 `Low` is `PRIORITY-CONTRADICTED` — a smoke run selects on the tag, so it picks up work the QA
-deliberately deprioritised. Inherit the declared priority; if the tag is right, fix the
-declaration instead of leaving both on record.
+deliberately deprioritised. Inherit the declared priority; if the tag is right, the declaration is
+what is wrong — fix it in your own draft (mode 2), or report it in `viewpoint-review.md` for the QA
+(mode 1). Never leave both on record silently.
 
 ---
 
@@ -205,26 +207,15 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
    **Screen requirements** — check `<base>/${input:name}/requirements/`:
 {{/cap}}
    - If `spec.md` exists → read it as PRIMARY source (sections, fields, validation rules, business rules, states).
+   - `test-viewpoint.md` → **Viewpoint — review or draft** below, once every source is read. No question here.
 {{#cap parallel-subagents}}
-   - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), use `AskUserQuestion` to ask:
-     - **Fill test-viewpoint.md first** — I'll help you identify edge cases, known issues, and design decisions for this screen before generating tests
-     - **Continue without it** — generate tests from spec and other sources only
-
-   **A filled `test-viewpoint.md` is an INPUT — never an output.** Do NOT rewrite, re-order, or replace its viewpoint declarations as part of generating tests. It is the yardstick two scored axes measure the suite against (`traceability`, `atomicLedger`): rewrite it to match what you just generated and both read 100% by construction, while any viewpoint you quietly dropped stops being missing from anything. If the declared taxonomy genuinely does not fit the screen, **report the mismatch and ask** — propose the diff (ids added / removed and why) and let the QA decide. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and stops scoring both axes when this file moves, so an unannounced rewrite lowers the score rather than raising it.
 
    **Context discovery (prefer an isolated agent).** Reading all sources here can flood this context. **Claude Code:** spawn the **`sungen-discovery`** sub-agent (Task tool, `subagent_type: sungen-discovery`) to read spec/figma/ui/live in isolation and return a **compact discovery report** (sources, completeness, conflicts, recommended route, key facts); use that report instead of pasting raw sources. **Copilot / no sub-agents:** do the reading inline as below.
 {{/cap}}
-{{^cap parallel-subagents}}
-   - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), ask:
-     - **1) Fill test-viewpoint.md first** — identify edge cases, known issues, and design decisions before generating tests
-     - **2) Continue without it** — generate tests from spec and other sources only
-
-   **A filled `test-viewpoint.md` is an INPUT — never an output.** Do NOT rewrite, re-order, or replace its viewpoint declarations while generating tests. It is the yardstick two scored axes measure the suite against (`traceability`, `atomicLedger`): rewrite it to match what you just generated and both read 100% by construction, while any viewpoint you quietly dropped stops being missing from anything. If the declared taxonomy genuinely does not fit the screen, **report the mismatch and ask** — propose the diff (ids added / removed and why) and let the QA decide. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and stops scoring both axes when this file moves.
-{{/cap}}
 
    **Auto-detect visual source** — do NOT ask the user to pick a source. Instead, check what already exists and use it:
    1. If `spec_figma.md` exists → read it as Figma supplement (PAT flow already completed during `add-screen`). Do NOT call any `mcp__figma__*` tool.
-   2. If `ui/` has images (`.png`, `.jpg`, etc.) → read them for visual context (layout, element positions, states).
+   2. If `ui/` has images (`.png`, `.jpg`, etc.) or `ui/figma-meta.md` → read **all** of them; they feed the Design Inventory (below), not just visual context.
 {{#cap parallel-subagents}}
    3. If neither exists → use `AskUserQuestion` to ask: *"No visual source found. Pick one:"* — then invoke the **`sungen-capture`** skill with the matching **mode** (read only that mode's file):
       - **Figma PAT** — ask for URL, run `sungen add --screen <screen> --figma '<url>'` via Bash, then `sungen-capture` **mode figma-pat**
@@ -242,7 +233,19 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 
    (When `spec_figma.md` exists, that is also `sungen-capture` **mode figma-pat**; when `ui/` images exist, that is **mode local**.)
 
-   **Cross-check**: if both `spec.md` and visual sources exist, flag any discrepancies (missing fields, different labels) before moving on. When `spec_figma.md` is present, follow the Figma supplement rules in `sungen-tc-generation` skill (reading order, Text Inventory, conflict handling).
+   **Cross-check + Design Inventory**: when the unit holds any design source (`ui/` images, `ui/figma-meta.md`, `spec_figma.md`), follow `sungen-tc-generation` § **Design Inventory** (reading order, one `UI-NNN` row per item, `spec+design` / `design-only` / `conflict`) and **write `requirements/ui-inventory.md`** before generating — from the discovery report's UI INVENTORY block when a sub-agent read the sources. Every `design-only` / `conflict` item must then be covered (`@ui:UI-NNN`) or deferred with a reason (`# UI-DEFERRED: UI-NNN — <reason>`) in the `.feature`; `sungen audit` reports `UI-ITEM-UNCOVERED` otherwise. Show the user the conflicts and design-only items — they are decisions, not details.
+
+   **Viewpoint — review or draft (no question asked).** Run `sungen viewpoint scan --screen <name> --json` (a flow: `--flow <name>`). It reads ids and item numbers only. Its `mode` (1 or 2) and `modeReason` name the row below — follow them; the table explains them:
+
+   | `requirements/test-viewpoint.md` | Mode | You |
+   |---|---|---|
+   | missing; nothing but the scaffold (headings, `<…>` placeholders, empty tables); or ONE OR MORE VP rows and every one of them lacks a `Kỳ vọng` | **2 — draft** | Write it from `sungen-viewpoint/viewpoint-template.md`, first line `drafted-by: ai`, keeping any row already there. Each row answers "test CÁI GÌ" and "kỳ vọng ra sao"; where the spec states the expected result, write it; only what the spec leaves open becomes a closed question in mục 5, never an invented expectation; every accepted-input class the spec names (whitelist, value list, conversion) gets an "accepted, no error" row, citing the list by name; a VP that needs a real device, account or time is `# MANUAL/ENV`. Then scan again. |
+   | first line `drafted-by: ai` | **2 — re-review** | Your draft, not yet accepted: you may revise it, from the spec and the review. |
+   | anything else — QA-written, with or without VP ids (a scaffold from an older sungen reads as this row too: delete the file to have it drafted) | **1 — review only** | Never edit it. Generate from it as written; a gap is reported, not filled. |
+
+   Then review it with `sungen-viewpoint/review-checklist.md` and the scan JSON (mode 2: fix your draft until only QA decisions remain) and write `requirements/viewpoint-review.md`, overwritten each run. Mode 2 also runs `sungen audit --screen <name> --no-baseline` before generating. Keep the review's row count for the hand-back.
+
+   **A filled `test-viewpoint.md` is an INPUT — never an output.** Do NOT rewrite, re-order, or replace its viewpoint declarations as part of generating tests — your own draft included: a draft is revised from the spec, never from the scenarios. It is the yardstick two scored axes measure the suite against (`traceability`, `atomicLedger`): rewrite it to match what you just generated and both read 100% by construction, while any viewpoint you quietly dropped stops being missing from anything. If the declared taxonomy genuinely does not fit the screen, **report the mismatch in `viewpoint-review.md`** — the diff (ids added / removed and why) — and let the QA decide. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and stops scoring both axes when this file moves, so an unannounced rewrite lowers the score rather than raising it.
 
    Summarize what you found in requirements and present to the user.
 
@@ -284,6 +287,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
      - **BALANCE** → stop expanding secondary viewpoints; add business-core scenarios first.
      - **TRACE** → align `VP-` ids with the viewpoint-overview.
    - Stop when the gate PASSes and findings clear, **or** the budget is exhausted → report residual gaps honestly (never fake a pass).
+   - **Repair never edits a QA-written viewpoint (mode 1).** A finding whose fix is an edit to `test-viewpoint.md` becomes a row in `viewpoint-review.md` for the QA when it cites one of the file's VP ids (the checklist's audit rule; anything else goes in the hand-back); in a mode-2 draft, fix the draft.
 
 5.6. **Record (reuse + observability).** Build the manifest and report usage:
    - `sungen manifest --screen <name>` — fingerprints for next-run change detection. On a **re-run**, start the whole command by `sungen manifest --screen <name> --diff` and only regenerate scenarios whose spec section changed (keep/regenerate/retire).
@@ -297,7 +301,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
    > **No parallel fan-out here.** Copilot has no sub-agents, so generation is sequential (the Claude Code variant fans out one `sungen-generator` per viewpoint group and merges). Same output, no speedup.
 5.3. **Standardize field test-data — Data Factory (when the unit has input fields).** For each input field, author the field-map `qa/data-factory/<name>.fields.yaml` (field → catalog `type` + real `constraints` + `errorMap`), then run `sungen data lint --screen ${input:name}` and `sungen data gen --screen ${input:name}` per the **`sungen-data-factory`** skill. `data gen` **MERGES** into `test-data.yaml` (replaces only its field keys, preserves the rest), so it is safe here. Weave the standardized boundary/invalid sets into `@cases` with `CHK-*` trace. Then `… data validate` (values correct) + `… data crosscheck` (testcase↔data agree); for a stateful precondition, `… data state --scaffold <name>` to auto-draft → fill entities + confirm with QA → `… data state`, weave the `@manual:data-setup` `Background` (works spec+viewpoint only). **Same standard as `/sungen:create-data-test`, applied inline — do NOT run that command separately afterwards.** No input fields (navigation/list) → skip.
 5.4. **Depth self-check (deterministic — BEFORE the audit).** Run `sungen depth-lint --screen ${input:name}`. It splits every shallow business-critical scenario into **DEEPEN IN PLACE** (add a real value assertion — the printed `template` is a theme-keyed hint, apply judgment to the actual claim; never fake one onto a visibility/behavior scenario) and **CROSS-SCREEN** (route to a flow / tag `@manual:Mx` + reason — removes it from the depth denominator honestly). Act on both, re-run until `deepen` is empty (or only honest over-counts remain), THEN gate. Lifts first-pass `businessDepth` mechanically instead of via 2–3 repair rounds.
-5.5. **Quality gate & repair (harness — always run).** Per `sungen-harness-audit`: run `sungen audit --screen ${input:name}` (structural), THEN do an **independent semantic review inline** using the `sungen-reviewer` criteria (does each scenario's steps PROVE its title/viewpoint? observable Thens? business-critical assertion depth?). Merge both sets of issues; if gate FAILs / findings exist, repair (budget 3) and re-audit — GATE missing theme → generate it (cross-screen → **automate it in the flow** via `/sungen:add-flow`, NOT a full `@manual` screen duplicate — `sungen audit` flags an automatable `@manual` as `MANUAL-AUTOMATABLE`; reserve `@manual:Mx` for true judgment/missing-capability); DEPTH → add data assertions; BALANCE → add business-core first; TRACE → align VP ids. Never fake a pass.
+5.5. **Quality gate & repair (harness — always run).** Per `sungen-harness-audit`: run `sungen audit --screen ${input:name}` (structural), THEN do an **independent semantic review inline** using the `sungen-reviewer` criteria (does each scenario's steps PROVE its title/viewpoint? observable Thens? business-critical assertion depth?). Merge both sets of issues; if gate FAILs / findings exist, repair (budget 3) and re-audit — GATE missing theme → generate it (cross-screen → **automate it in the flow** via `/sungen:add-flow`, NOT a full `@manual` screen duplicate — `sungen audit` flags an automatable `@manual` as `MANUAL-AUTOMATABLE`; reserve `@manual:Mx` for true judgment/missing-capability); DEPTH → add data assertions; BALANCE → add business-core first; TRACE → align VP ids. Never fake a pass. Repair never edits a QA-written viewpoint (mode 1): a finding whose fix is an edit to `test-viewpoint.md` and cites one of its VP ids becomes a row in `viewpoint-review.md`; in a mode-2 draft, fix the draft.
 5.6. **Record.** `sungen manifest --screen ${input:name}`. Ledger **each phase** (not just repair) — pick one `runId` at the start and pass it so `trace`/`ledger report` show THIS run, not a mix: `sungen ledger record --screen ${input:name} --run <runId> --step <discovery|viewpoint|gherkin|audit|repair:N> --ms <elapsed>`. On re-run, start with `sungen manifest --screen ${input:name} --diff` and only regenerate changed sections.
 6. **Converge — show the trace.** Run `sungen trace --screen ${input:name}` and present: process map (phases + repair rounds), bottlenecks, **HUMAN-LOOP FOCUS** (@manual to verify), audit score + gate + residual gaps. Then offer next steps based on which tier was just generated:
 {{/cap}}
@@ -363,9 +367,13 @@ Do not stop after writing the files. Close every run with, in this order:
 1. **The traceability check below** — an untagged requirement becomes an uncovered gap at delivery.
 2. **The harness result in one line** — score, gate verdict, and the axis the `SCORE-CAPPED` finding
    names (that finding is the single answer to "how do I raise the score").
-3. **`AskUserQuestion` with the next actions** — never end with prose alone. Offer
+3. **The viewpoint review in one line** — `Viewpoint review: N điểm cần QA xem` (N = the `[ ]` rows
+   of `requirements/viewpoint-review.md`).
+4. **`AskUserQuestion` with the next actions** — never end with prose alone. Offer
    `/sungen:run-test <name>` (recommended once the tiers are written), re-running `create-test` to
-   extend, and "Done for now". A run that ends without this leaves the operator guessing.
+   extend, "Mở viewpoint-review.md" when N > 0, and "Done for now". After a mode-2 draft also list
+   the decision `sungen audit --screen <name> --accept-viewpoint` — for the QA to run once the draft
+   is reviewed; you never run it yourself. A run that ends without this leaves the operator guessing.
 
 ### Requirement traceability