@sun-asterisk/sungen 3.2.32 → 3.2.34

package/dist/orchestrator/security-overrides-catalog.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECURITY_OVERRIDES = void 0;
+/**
+ * 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.
+ */
+exports.SECURITY_OVERRIDES = [
+    {
+        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',
+    },
+];
+//# sourceMappingURL=security-overrides-catalog.js.map

package/dist/orchestrator/security-overrides-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-overrides-catalog.js","sourceRoot":"","sources":["../../src/orchestrator/security-overrides-catalog.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;;AAWH;;;;GAIG;AACU,QAAA,kBAAkB,GAAuB;IACpD;QACE,GAAG,EAAE,MAAM;QACX,KAAK,EAAE,SAAS;QAChB,yFAAyF;QACzF,sFAAsF;QACtF,GAAG,EAAE,sGAAsG;KAC5G;IACD;QACE,GAAG,EAAE,QAAQ;QACb,KAAK,EAAE,SAAS;QAChB,mGAAmG;QACnG,GAAG,EAAE,oFAAoF;KAC1F;IACD;QACE,GAAG,EAAE,sBAAsB;QAC3B,KAAK,EAAE,QAAQ;QACf,GAAG,EAAE,6GAA6G;KACnH;IACD;QACE,GAAG,EAAE,qBAAqB;QAC1B,KAAK,EAAE,QAAQ;QACf,gGAAgG;QAChG,+FAA+F;QAC/F,iGAAiG;QACjG,iGAAiG;QACjG,4EAA4E;QAC5E,GAAG,EAAE,mLAAmL;KACzL;CACF,CAAC"}

package/dist/orchestrator/security-overrides.d.ts

@@ -0,0 +1,51 @@
+import { 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 declare function planSecurityOverrides(pkgJson: Record<string, any>): OverridePlan;
+/**
+ * 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 declare function ensureSecurityOverrides(packageJsonPath: string, dryRun?: boolean): OverridePlan | null;
+/** Print what `ensureSecurityOverrides` did, in the voice the surrounding commands already use. */
+export declare function reportSecurityOverrides(plan: OverridePlan | null, dryRun?: boolean): void;
+//# sourceMappingURL=security-overrides.d.ts.map

package/dist/orchestrator/security-overrides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-overrides.d.ts","sourceRoot":"","sources":["../../src/orchestrator/security-overrides.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEpF;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,GAAG,EAAE,gBAAgB,EAAE,CAAC;IACxB,gGAAgG;IAChG,QAAQ,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE,qGAAqG;IACrG,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,wFAAwF;IACxF,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,YAAY,CAuBhF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,YAAY,GAAG,IAAI,CA2BpG;AAeD,mGAAmG;AACnG,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,EAAE,MAAM,UAAQ,GAAG,IAAI,CAgCvF"}

package/dist/orchestrator/security-overrides.js

@@ -0,0 +1,165 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECURITY_OVERRIDES = void 0;
+exports.planSecurityOverrides = planSecurityOverrides;
+exports.ensureSecurityOverrides = ensureSecurityOverrides;
+exports.reportSecurityOverrides = reportSecurityOverrides;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const security_overrides_catalog_1 = require("./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.
+ */
+var security_overrides_catalog_2 = require("./security-overrides-catalog");
+Object.defineProperty(exports, "SECURITY_OVERRIDES", { enumerable: true, get: function () { return security_overrides_catalog_2.SECURITY_OVERRIDES; } });
+/**
+ * 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.
+ */
+function planSecurityOverrides(pkgJson) {
+    const current = pkgJson.overrides && typeof pkgJson.overrides === 'object' ? pkgJson.overrides : {};
+    const add = [];
+    const existing = [];
+    for (const entry of security_overrides_catalog_1.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
+ */
+function ensureSecurityOverrides(packageJsonPath, dryRun = false) {
+    let pkgJson;
+    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 = 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) {
+    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. */
+function reportSecurityOverrides(plan, dryRun = false) {
+    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_catalog_1.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`);
+    }
+}
+//# sourceMappingURL=security-overrides.js.map

package/dist/orchestrator/security-overrides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-overrides.js","sourceRoot":"","sources":["../../src/orchestrator/security-overrides.ts"],"names":[],"mappings":"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"}

package/dist/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/dist/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/dist/orchestrator/templates/ai-src/commands/create-test.md

@@ -224,7 +224,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 
    **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 +242,7 @@ 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.
 
    Summarize what you found in requirements and present to the user.
 

package/dist/orchestrator/templates/ai-src/commands/review.md

@@ -51,7 +51,7 @@ You are an **independent QA Reviewer** — you did not author these tests. You d
 1. **Enumerate feature files** — glob `<base>/<name>/features/*.feature` (main + any sub-features). If none → `/sungen:create-test` first.
 2. **Run the harness (source of truth) — do NOT re-score with a separate rubric:**
    - `sungen audit --screen <name>` (Bash) → gate status, business-weighted score, findings, gaps (coverage / assertion-depth / balance / duplicate / traceability).
-   - **`sungen-reviewer`** sub-agent (Task tool, `subagent_type: sungen-reviewer`) → semantic verdict the gate can't see (do steps prove the title, observable Then, @manual justified). Copilot/no-sub-agents: apply the `sungen-reviewer` criteria inline.
+   - **`sungen-reviewer`** sub-agent (Task tool, `subagent_type: sungen-reviewer`) → semantic verdict the gate can't see (do steps prove the title, observable Then, @manual justified) and, when the unit holds design sources (`requirements/ui/*`, `ui/figma-meta.md`, `spec_figma.md`), the **Design ↔ Feature diff** against `ui-inventory.md`. Copilot/no-sub-agents: apply the `sungen-reviewer` criteria inline.
    - `sungen script-check --screen <name>` (Bash) → is the generated spec a 1:1 of the Gherkin (only if a spec exists; flags hand-edit / stale drift).
 3. **Unified scorecard** — present ONE report per feature, anchored on the harness signals (the `sungen-tc-review` 7 dimensions are a *presentation layer* over these, not a competing score):
 {{/cap}}
@@ -63,7 +63,7 @@ You are an **independent QA Reviewer** — you did not author these tests. You d
 1. **Enumerate** `<base>/${input:name}/features/*.feature`. If none → `/sungen-create-test` first.
 2. **Run the harness (source of truth) — no separate rubric:**
    - `sungen audit --screen ${input:name}` → gate, business-weighted score, findings, gaps.
-   - Apply the **`sungen-reviewer` criteria inline** → semantic verdict (do steps prove the title? observable Then? business-critical depth? @manual justified?).
+   - Apply the **`sungen-reviewer` criteria inline** → semantic verdict (do steps prove the title? observable Then? business-critical depth? @manual justified?) and, when `requirements/ui/*` / `ui/figma-meta.md` / `spec_figma.md` exist, read them and diff the design against `ui-inventory.md` and the `.feature` (criterion 7).
    - `sungen script-check --screen ${input:name}` → spec is 1:1 with the Gherkin (flags hand-edit / stale drift; only if a spec exists).
 3. **Unified scorecard** per feature, anchored on harness signals (the `sungen-tc-review` 7 dimensions are a presentation layer, not a competing score):
 {{/cap}}

package/dist/orchestrator/templates/ai-src/commands/run-test.md

@@ -1,7 +1,7 @@
 ---
 name: run-test
 description: "Generate selectors + auth state (Playwright MCP for web / Appium MCP for mobile), compile, and run tests — auto-fixes selectors on failure"
-argument-hint: "[screen-name] [--env <locale>] [--ios|--android|--both]"
+argument-hint: "[screen-name] [--ids <ID,…>] [--env <locale>] [--ios|--android|--both]"
 order: 40
 claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_run_code, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state, mcp__appium-mcp__select_device, mcp__appium-mcp__appium_session_management, mcp__appium-mcp__generate_locators, mcp__appium-mcp__appium_get_page_source, mcp__appium-mcp__appium_find_element, mcp__appium-mcp__appium_gesture, mcp__appium-mcp__appium_screenshot, mcp__appium-mcp__appium_set_value"
 copilot-tools: "[read, execute, edit, vscode/askQuestions, playwright/*, appium/*]"
@@ -85,6 +85,13 @@ Stop here for mobile — do not continue to the web path.
 > QA finding → report it, let it FAIL** (it may be a real bug). The live page is NOT the oracle;
 > never hand-edit the generated `.spec.ts` either. See `sungen-error-mapping` § "HARD RULE".
 > (A `password > 8` test that fails on 6 chars is a bug to report, not a `>= 6` edit.)
+>
+> **Blocked by missing seed data / capability** (the run cannot create the state the scenario
+> needs)? Keep every Given/When/Then; add only a tag — `@requires:<cap>` when a driver exists,
+> else `@manual:M1` with a `# MANUAL (<date>, run-test): <reason>` comment inside the scenario —
+> and list each downgrade in the run summary for QA. Never replace the assertion with a presence
+> placeholder and park the oracle in a comment (`SG-W008`). See `sungen-error-mapping` § "Fails
+> because the environment lacks the DATA or CAPABILITY".
 
 ## Parameters
 
@@ -95,7 +102,9 @@ Parse from `$ARGUMENTS`:
   the result over the previous run's file instead of replacing it. Passing it also **skips the scope gate**:
   the flag IS the answer, so asking again would be noise. Without the flag the gate asks — but only when the
   selection is narrower than the whole unit (see the table). Either way a subset run must follow the merge
-  order below; the backup has to exist BEFORE the run, because the report filename is fixed.
+  flow below — web writes the subset to a temp report, mobile backs the fixed-name file up BEFORE the run.
+- **`--ids <ID,…>`** — run exactly these test-case IDs (`VP-UI-001,VP-UI-002`) and merge the result
+  over the previous run's file — see the `--ids` section below. Skips the scope gate, like `--change-only`.
 - **`--ios`**, **`--android`**, **`--both`** (mobile only) — optional. Sets `MOBILE_PLATFORM` for the test run. Default: `android` if not specified. Parsed into `MOBILE_PLATFORM=<value>` and used in WebdriverIO test runs.
 
 If `--env` is passed but no value follows, ask the user which locale to use.
@@ -172,6 +181,7 @@ Read `summary.selected`, `summary.total`, `all`, and `reasons`, then follow this
 | Situation | What to do |
 |---|---|
 | `--change-only` was passed | **Do NOT ask.** Run the changed set, print the list + reasons for the record, follow the merge flow below. |
+| `--ids` was passed | **Do NOT ask, and do not run `sungen changed` at all.** The user named the cases — follow the `--ids` section below. |
 | `all: true` | **Do NOT ask** — there is nothing to choose. Print the reason (`no previous run recorded`, `the Background changed`, `project config changed`, `git reports …`) and run the FULL suite. |
 | `selected == 0` | **Do NOT ask.** Say plainly that nothing changed since the last recorded run, and use `AskUserQuestion` to offer: re-run the full suite anyway / stop here. |
 | `0 < selected < total` | **ASK** — this is the only case with two honest answers. |
@@ -187,6 +197,10 @@ recorded` and runs everything again — the narrowing never starts. Record it af
 results you accept (a full run, or a subset once merged), and NOT after a run you are about to
 redo: leaving the baseline where it is keeps the same scenarios selected on the next attempt.
 
+**Never record after an `--ids` run.** The user's IDs need not cover what an edit changed;
+recording would mark every changed scenario as re-run, and the next `--change-only` would skip the
+ones this run never touched.
+
 When you ask, first PRINT the selection so the choice is informed — one line per scenario with its
 reason, exactly as `sungen changed` renders it — then `AskUserQuestion` with two options:
 
@@ -257,7 +271,7 @@ question already.
 6. **Phase 2 — Priority Wave**: Run all `@high` scenarios. Fix only failures from this wave. Max 2 attempts. Shared selectors fixed here cascade to later phases.
 7. **Phase 3 — Full Run**: Run all tests. Fix only **new** failures (elements unique to `@normal`/`@low`). Max 1 attempt. Don't loop on low-priority failures.
 8. **Phase 4 — Regression**: One final full run. Report results. No more fix loops.
-9. **Phase 8 — Serial-cascade risk check** (#414): If any scenario has many steps, a skipped test may cause downstream steps to be incorrectly skipped due to the serial-cascade sensor detecting false "not reached" conditions. When you see "test skipped" messages during Phase 3–4 runs, check if the skipped scenario is a **blockers-exist** dependency in the test ledger (`sungen ledger query --screen <name>`). If the scenario had high step count and cascade fired, offer: *"Scenarios with deep steps can trigger serial-cascade skipping. Consider parallelizing this spec with `@concurrent` tags or breaking into smaller scenarios. See `sungen-selector-fix` § Phase 8."* Let the user decide whether to refactor (do not auto-apply parallelization).
+9. **Phase 8 — Serial-cascade risk check** (#414): If any scenario has many steps, a skipped test may cause downstream steps to be incorrectly skipped due to the serial-cascade sensor detecting false "not reached" conditions. When you see "test skipped" messages during Phase 3–4 runs, check if the skipped scenario is a **blockers-exist** dependency in the test ledger (`sungen ledger query --screen <name>`). If the scenario had high step count and cascade fired, offer: *"Scenarios with deep steps can trigger serial-cascade skipping. Consider parallelizing this spec with `@concurrent` tags or breaking into smaller scenarios."* Let the user decide whether to refactor (do not auto-apply parallelization).
 {{#cap parallel-subagents}}
 9. **Integrity check & trace (always run after the final run).**
    - `sungen script-check --screen <name>` — verify the generated spec is a **1:1** of the Gherkin (every non-@manual scenario ↔ one `test()`, no drift). If it reports **DRIFT** (spec hand-edited or stale), re-run `sungen generate --screen <name>` so the spec matches the feature, then re-run — **never hand-edit the generated spec** (auto-fix must edit `selectors.yaml`, not the `.spec.ts`).
@@ -325,7 +339,7 @@ sungen results merge --screen <name> specs/generated/<name>/subset-tmp.json
 rm specs/generated/<name>/subset-tmp.json
 ```
 
-`--screen` takes the FEATURE basename — for a multi-feature screen (`home.spec.ts` + `home-modal.spec.ts`), each feature has its own result file: merge `home-modal`'s subset with `--screen home-modal`. If the previous run had zero failures, `--last-failed` runs nothing and writes no JSON — use `-g "<scenario title>"` to pick the cases instead.
+`--screen` takes the FEATURE basename — for a multi-feature screen (`home.spec.ts` + `home-modal.spec.ts`), each feature has its own result file: merge `home-modal`'s subset with `--screen home-modal`. If the previous run had zero failures, `--last-failed` finds no tests: Playwright prints "No tests found", exits 1, and still writes a zero-test report — don't merge it; use `-g "<scenario title>"` to pick the cases instead. `--last-failed` reads the failures of the *previous run only*, so any run in between replaces the list.
 
 For a locale run (`SUNGEN_ENV=vi`), the config appends `.vi` before `.json` to WHATEVER `PLAYWRIGHT_JSON_OUTPUT_NAME` says — the temp report lands at `subset-tmp.vi.json`; merge that file into the matching `<name>-test-result.vi.json` explicitly: `sungen results merge specs/generated/<name>/<name>-test-result.vi.json specs/generated/<name>/subset-tmp.vi.json`. A scenario RENAMED by a spec edit leaves its old-title result in the file — the merge warns and keeps it (delivery builds rows from the feature, so it never renders).
 
@@ -360,29 +374,33 @@ If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter over
 
 ## `--change-only` — re-run just what an edit obliges, without losing the rest
 
-The JSON reporter names its file for the unit + platform + env ONLY, so **any** subset run
-overwrites the full run's results. Re-running 3 cases of a 100-case screen used to throw away the
-97 that still passed, which is why a partial run had to be followed by a full one.
-
-Two commands close that, and the order matters — the backup must exist BEFORE the run, because by
-the time the run finishes the old file is already gone:
+A per-target result file holds the whole unit, so a subset run must never replace it: re-running 3
+cases of a 100-case screen used to throw away the 97 that still passed. The subset is MERGED in
+instead — on web via a temp report, on mobile via a backup taken BEFORE the run (the WDIO reporter
+always writes the fixed-name file, so by the time the run finishes the old one is gone):
 
 ```bash
 # 1. what does the edit oblige?  (empty output = nothing to run, do NOT fall through to a full run)
 npx sungen changed --screen <name>            # human-readable, with the reason per scenario
 GREP=$(npx sungen changed --screen <name> --grep)
 
+# MOBILE — the WDIO reporter always writes the canonical per-OS file, so back it up first:
 # 2. keep the previous results BEFORE the runner overwrites them
 cp specs/generated/<name>/<name>-test-result.<os>.json /tmp/<name>.prev.json
-
 # 3. run only the selected scenarios
 SUNGEN_SPECS='./specs/generated/<name>/<name>.spec.ts' npm run test:mobile -- --mochaOpts.grep "$GREP"
-#   web:  npx playwright test specs/generated/<name>/<name>.spec.ts -g "$GREP"
-
 # 4. merge the subset back over the kept results (same title → new wins, others kept)
 npx sungen results merge /tmp/<name>.prev.json specs/generated/<name>/<name>-test-result.<os>.json \
   -o specs/generated/<name>/<name>-test-result.<os>.json
 
+# WEB — Playwright writes its report to PLAYWRIGHT_JSON_OUTPUT_NAME (else test-results/results.json),
+# never to the per-target file by itself: write the subset to a temp report and merge THAT in (#837).
+# With --env <x>: prefix BOTH commands with SUNGEN_ENV=<x>; the config then writes subset-tmp.<x>.json.
+PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<name>/subset-tmp.json \
+  npx playwright test specs/generated/<name>/<name>.spec.ts -g "$GREP"
+npx sungen results merge --screen <name> specs/generated/<name>/subset-tmp.json   # --env x → subset-tmp.x.json
+rm specs/generated/<name>/subset-tmp*.json
+
 # 5. record the new baseline — ONLY after a run you accept
 npx sungen changed --screen <name> --record
 ```
@@ -398,6 +416,45 @@ change that broke it.
 **Without `--change-only`** the full run still writes the file wholesale, which is correct — a full
 run IS the complete picture. Merging only matters for subsets.
 
+## `--ids` — run a chosen list of test-case IDs
+
+The user names the cases (`--ids VP-UI-001,VP-UI-002`). `sungen select` resolves them —
+deterministic, exact ID match, grouped per feature — and refuses anything it cannot run:
+
+```bash
+npx sungen select --screen <name> --ids <ID,…>          # human-readable
+npx sungen select --screen <name> --ids <ID,…> --json   # what you act on
+```
+
+**Exit 1 = do not run.** Report every entry of `unknown` (with its `didYouMean`), `notRunnable`
+(manual / owned by a flow — with the reason) and `notCompiled` (→ `sungen generate` first), then
+use `AskUserQuestion` to offer: run the valid IDs only / correct the list. Never fall back to a
+full run, and never run with an empty grep.
+
+Then, **for each entry of `features`** (a multi-feature screen has one spec and one result file per
+feature), with `<spec>` = its `spec`, `<f>` = its `feature`, `<dir>` = the spec's directory and
+`GREP` = its `grep`:
+
+```bash
+# WEB — write the subset to a temp report, then merge it into <f>'s per-target file.
+# With --env <x>: prefix BOTH commands with SUNGEN_ENV=<x>; the config then writes subset-tmp.<x>.json.
+PLAYWRIGHT_JSON_OUTPUT_NAME=<dir>/subset-tmp.json npx playwright test <spec> -g "$GREP"
+npx sungen results merge --screen <f> <dir>/subset-tmp.json      # --env x → <dir>/subset-tmp.x.json
+rm <dir>/subset-tmp*.json
+
+# MOBILE — the reporter always writes <dir>/<f>-test-result.<android|ios>[.<env>].json: back it up first
+# (with --env <x> every <f>-test-result.<os>.json below is <f>-test-result.<os>.<x>.json)
+cp <dir>/<f>-test-result.<os>.json /tmp/<f>.prev.json
+SUNGEN_SPECS='./<spec>' npm run test:mobile -- --mochaOpts.grep "$GREP"
+npx sungen results merge /tmp/<f>.prev.json <dir>/<f>-test-result.<os>.json -o <dir>/<f>-test-result.<os>.json
+```
+
+With no previous result file (first run of the unit, or of this `--env`) there is nothing to merge
+into — `results merge --screen` says so and exits 1: on web run with
+`PLAYWRIGHT_JSON_OUTPUT_NAME=<dir>/<f>-test-result.json`, on mobile skip the backup and the merge.
+With `--both`, back up and merge each OS's file. **Do NOT run `sungen changed --record`** (see the
+scope gate). Report the per-ID outcome, plus the IDs that were refused.
+
 ## Next steps
 
 After showing results, use `AskUserQuestion` to offer next steps:

package/dist/orchestrator/templates/ai-src/skills/sungen-capture/mode-local.md

@@ -6,7 +6,7 @@ Use **pre-existing images** in `requirements/ui/` as visual context. No network,
 
 ### 1. List available images
 
-Glob `requirements/ui/*.{png,jpg,jpeg,webp,gif}` and report count + filenames. Filter out metadata files (e.g. `figma-meta.md` written by mode figma-mcp) — those are read by `tc-generation` separately, not treated as images here.
+Glob `requirements/ui/*.{png,jpg,jpeg,webp,gif}` and report count + filenames. Filter out metadata files (e.g. `figma-meta.md` written by mode figma-mcp) — those are read by `tc-generation` (§ Design Inventory) separately, not treated as images here.
 
 ### 2. Handle empty folder
 
@@ -21,7 +21,7 @@ If no images found:
 
 ### 3. Read images for context
 
-Use the `Read` tool on each image — Claude Code reads PNG/JPG/WebP directly as visual context. For large sets (>10 images), ask which are primary and which are states/variants to avoid loading too much at once.
+Use the `Read` tool on **each** image — Claude Code reads PNG/JPG/WebP directly. For large sets (>10 images), ask which are primary and which are states/variants so they can be grouped — but still read them all: every image feeds the Design Inventory (`sungen-tc-generation` § Design Inventory), and the inventory records `images read: N/N`.
 
 ### 4. Summarize
 

package/dist/orchestrator/templates/ai-src/skills/sungen-delivery/SKILL.md

@@ -93,6 +93,20 @@ every variant is N/A) and never a bare state word. **`N/A` leaves the denominato
 and actual result share one column `P`; the header row is frozen; ISO dates; landscape print with
 repeated header rows.
 
+**Re-running delivery keeps the tester's Manual results** (#756, since 3.2.33). Before overwriting,
+the CLI reads the existing workbook's **Manual** sheet and carries each variant's `L`–`P` cells into
+the new one by `VP-…` ref, verbatim. A hidden `_sungen_manual` sheet stamps each case's fingerprint,
+so a result recorded against an older procedure is reset to `Pending` with the previous result
+moved into Note. Relay the CLI's `Manual results:` lines to the user: `reset to Pending` means those
+cases must be run again by hand; `not carried` names results whose case left the feature. The
+**Auto** sheet is not carried (the run report owns its Result), and rows a tester added by hand
+have no ref and are not carried. Never tell the user to copy or rename the file to protect manual
+results. A second `not carried` line names a duplicated row (only the first copy is kept) — tell
+the user to merge it by hand. If the CLI prints `not written: cannot read …` (locked or damaged) or
+`not written: … has no "Manual" sheet` (renamed), the unit was deliberately NOT written to protect
+the results: ask the user to close the file or rename the sheet back to `Manual`, or move the file
+aside. Never delete, rename or move it yourself.
+
 `Coverage` sheet — requirement coverage table (every FR/TR/NFR id with an explicit status),
 target × category grid with explicit `—` gaps, dispositions, manifest. CSV mirrors the same model
 flat with a `Level` column (`item`/`variant`) + a requirement-coverage appendix.