@sun-asterisk/sungen 3.2.32 → 3.2.33

package/src/orchestrator/assets-drift.ts

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getPackageVersion } from '../exporters/package-info';
+import { readJsonConfig, warnUnreadableConfig } from '../harness/config-file';
 
 /**
  * Are this project's AI assets (commands + skills under `.claude/` etc.) the ones
@@ -27,12 +28,16 @@ export function checkAssetsDrift(cwd: string): AssetsDrift | null {
   const manifestPath = path.join(cwd, '.sungen', 'manifest.json');
   if (!fs.existsSync(manifestPath)) return null;   // not a sungen project (yet)
 
-  let manifest: { version?: string; managed?: Record<string, string> };
-  try {
-    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-  } catch {
-    return null;                                    // unreadable → say nothing
+  const read = readJsonConfig<{ version?: string; managed?: Record<string, string> }>(manifestPath);
+  if (read.state === 'unreadable') {
+    // This function IS the drift alarm. Staying silent on a broken manifest disables the only
+    // warning that a project's .claude/ assets have gone stale — and a truncated manifest is the
+    // likeliest way to get one (it is written non-atomically by `ai-skills/writer.ts`).
+    warnUnreadableConfig(manifestPath, read.error, 'stale-assets drift cannot be checked — re-run `sungen init` to rewrite it');
+    return null;
   }
+  if (read.state === 'absent') return null;
+  const manifest = read.value;
   const recordedVersion = manifest.version ?? '';
   const runningVersion = getPackageVersion();
   const managed = manifest.managed ?? {};

package/src/orchestrator/project-deps-sync.ts

@@ -2,6 +2,7 @@ import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { resolveDriverVersion } from './lockstep-version';
+import { ensureSecurityOverrides, reportSecurityOverrides } from './security-overrides';
 
 /**
  * Project-local sync of the sungen package family after a global `sungen update`.
@@ -143,8 +144,29 @@ export function syncProjectSungenDeps(cwd: string, core: string, dryRun: boolean
   }
   for (const s of plan.skipped) console.log(`   – skipped  ${s.pkg} — ${s.why}`);
 
+  // A project scaffolded before #764 carries no security overrides, and npm will never pick them up
+  // from sungen's own manifest — `sungen update` is the one pass that can put them there. Write them
+  // before any install below, since npm reads `overrides` when it resolves.
+  const overridePlan = ensureSecurityOverrides(path.join(cwd, 'package.json'), dryRun);
+  reportSecurityOverrides(overridePlan, dryRun);
+
   if (!plan.specs.length) {
-    console.log(`   ✓ already on ${core}: ${plan.found.map((f) => f.pkg).join(', ')}\n`);
+    console.log(`   ✓ already on ${core}: ${plan.found.map((f) => f.pkg).join(', ')}`);
+    // Family already in lockstep, so nothing would re-resolve — but freshly written overrides only
+    // reach the tree through a resolution pass. Run one.
+    if (overridePlan?.add.length) {
+      if (dryRun) {
+        console.log('   [dry-run] would run: npm install  (re-resolve under the new security overrides)\n');
+        return true;
+      }
+      console.log('   📦 npm install  (re-resolving under the new security overrides)');
+      const r = spawnSync('npm', ['install'], { cwd, stdio: 'inherit', shell: true });
+      if (r.status !== 0) {
+        console.warn('⚠️  Overrides were written to package.json but `npm install` failed — run it by hand.\n');
+        return false;
+      }
+    }
+    console.log('');
     return true;
   }
 

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/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/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.

package/src/orchestrator/templates/ai-src/skills/sungen-error-mapping/SKILL.md

@@ -128,8 +128,10 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W034` | A `see [X] column with {{v}}` step runs inside a table whose rows are declared with a **`rows:` shape**, so the row is not an ARIA row and holds no ARIA cells — but the assertion's only other way to reach a cell is `getByRole('cell')`, which matches nothing there. `columns.<col>.index` cannot rescue it: it indexes that same empty set. Before this the step failed as a timeout blaming the app. Not reported on a real `<table>`, where the role fallback is correct | Name the cell on the column: `columns: { title: { index: 0, header: 'Title', elements: { cell: { type: locator, value: '.job-title' } } } }`. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
 | `SG-E035` | **`table match data:` on a table declared with a `rows:` shape** and no matching `columns:` entries. The assertion reads its header row from `thead tr` and addresses cells as `td, th`; a <div> list has neither — forever, not as a render race — so the step could only wait out every timeout and fail on an empty header row. Refused at compile time, naming the columns it needs | Declare each DataTable column on the table entry with the selector that matches its cell inside a row: `columns: { title: { index: 0, header: 'Title', elements: { cell: { type: locator, value: '.job-title' } } } }`. Declaring columns also removes the runtime header read on a real `<table>`. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
 | `SG-W036` | A **`remember [X] … as {{v}}` capture through a `locator`/`css` selector with no `nth:`**. A capture reads ONE element and the step takes the FIRST match — the right default, and what the documented `nth: 0` workaround asked for after Playwright's strict mode turned a list-shaped selector into a hard failure naming the count. But the first of many is a decision: if the selector describes every item in a list, the captured value is the first row's. Not reported for testid/label/placeholder/role+name/text entries, which name a particular thing | Declare the index (`nth: 0`) to say the first one is meant, or narrow the selector to the single element. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
+| `SG-W037` | A **`type: page` entry saying something about the QUERY that the compiler cannot use**. Two causes: the entry's `value` carries a `?`/`#`, which is DROPPED (a page value is the path only — the pattern is matched against `u.pathname`, which never holds a query), or `query:` declares something other than `any`, which is ignored rather than read as permissive so a typo cannot quietly switch off the bare-page assertion. Both used to be silent, and the first is the trap: an author who hit "a bare `see [X] page` requires NO query" reaches for the query in the value, gets byte-identical output, and no hint why | To assert the query, declare it on the STEP (`see [X] page with {{v}}`). If the query is generated at run time — `/admins/detail?id=<the row just clicked>`, which no literal can express — add `query: any` to the entry: the query is then not part of that page's identity. selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
+| `SG-E038` | A **`{{var}}` the compiler cannot resolve** — the feature has no test-data file of its own, the key is absent, or it holds a list/map where a value was needed. This used to emit the PLACEHOLDER TEXT as the value: `fill [Partner Customer ID] field with {{valid_partner_id}}` compiled to `fill('${valid_partner_id}')`, typing those 20 literal characters into the app with `generate` exiting 0. A field with no format validation accepts the string, the server sees an unknown user, and the scenario fails at the assertion it was written to fail at — a suite that looks correct while feeding the system garbage. Every run also shares the SAME literal, so a scenario needing a fresh user silently reuses one. The step now compiles to a `throw` naming the ref and the file | Add the key to the file the message names. Note a feature resolves `{{var}}` against a data file named after **itself** — `qa/screens/<screen>/test-data/<feature>.yaml` — so the second `.feature` in a screen directory needs its own data file, not the screen-named one. `sungen data crosscheck` reports the same gap before you compile |
 
-A diagnostic never changes generation's own exit code — `sungen generate --strict` turns any collected diagnostic into a non-zero exit for CI gates. They are not all inert, though: **`SG-W001`, `SG-W011`, `SG-E020`, `SG-E021`, `SG-W020`, `SG-E023`, `SG-E024`, `SG-E025`, `SG-E026`, `SG-E027` and `SG-E035` additionally compile the offending step to a runtime `throw`, and `SG-E031` refuses the whole file** — a step that reads as a check and silently checks nothing is worse than one that fails loudly. Generation always COMPLETES: the rest of the scenario and the rest of the file still compile. `SG-E022` is the odd one out — it blames the compiler, not your `.feature`, and throws nothing (the file is written so you can inspect it).
+A diagnostic never changes generation's own exit code — `sungen generate --strict` turns any collected diagnostic into a non-zero exit for CI gates. They are not all inert, though: **`SG-W001`, `SG-W011`, `SG-E020`, `SG-E021`, `SG-W020`, `SG-E023`, `SG-E024`, `SG-E025`, `SG-E026`, `SG-E027`, `SG-E035` and `SG-E038` additionally compile the offending step to a runtime `throw`, and `SG-E031` refuses the whole file** — a step that reads as a check and silently checks nothing is worse than one that fails loudly. Generation always COMPLETES: the rest of the scenario and the rest of the file still compile. `SG-E022` is the odd one out — it blames the compiler, not your `.feature`, and throws nothing (the file is written so you can inspect it).
 
 ### Runtime error → `Test data "<key>" references ${QA_*} but the environment variable is not set`
 

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -630,6 +630,7 @@ on mobile a dialog-scoped ref still resolves against the whole screen (`SG-W021`
 |---|---|
 | `@spec:<id>` | **Traceability**: this scenario proves requirement `<id>` from `requirements/spec.md` (`@spec:FR-003`). Repeatable — a scenario may prove several. Read by `sungen audit` (requirement coverage) and by delivery (the Coverage sheet's requirement table). Without it the link is only inferred from wording and cannot survive an edit. |
 | `@manual` | Skip in generation |
+| `@known-defect` | The scenario is EXPECTED to be red — it asserts a live defect. It still runs and still reports as failed (never skipped, never "fixed"), and it stays a pass-through tag so `--grep @known-defect` selects it. **`[mobile]`** Its failure does NOT escalate the next scenario's `@reset:` tier: a red that was designed in is not evidence of leftover state |
 | `@auth:role` | Use auth storage state for role |
 | `@no-auth` | Disable inherited auth |
 | `@steps:name` | Define reusable step block (base scenario) |
@@ -695,6 +696,14 @@ Rules that matter when generating:
   relaunch does not undo a half-written local DB. One rung, one scenario, and never from `none`.
   A **retry** of the failed scenario is NOT escalated — it re-runs at its declared tier, so a
   state-dependent failure fails both attempts and is reported honestly instead of passing on attempt 2.
+  A scenario tagged **`@known-defect`** escalates nothing either: its red was designed in, so making
+  the next scenario pay a harder reset for it buys nothing, on every run, forever.
+- **Escalation never picks a tier this session cannot perform.** Reinstalling needs the app's build
+  file, so when the app is attached by package the ladder caps at `data` (Android) / `soft` (iOS) and
+  says it capped, instead of throwing. Nothing asked for the escalated tier, and the throw would land
+  in `beforeEach` — a hook failure, which skips every remaining scenario in the FILE. The cap never
+  goes BELOW the declared tier: a tier you asked for that the session cannot do still throws by name,
+  because that one is an unmet contract rather than a recovery the runner chose.
 - **`SUNGEN_RESET_TIER=data` raises the floor for a whole run** without regenerating specs — CI can run
   stricter than local dev. It never lowers a declared tier.
 - **`data`/`full` on iOS reinstall the app**, because `mobile: clearApp` is Android-only (UiAutomator2).

package/src/orchestrator/templates/ai-src/skills/sungen-selector-keys/SKILL.md

@@ -128,7 +128,10 @@ back to the feature's own path (or `/<ref>/`) and warns `SG-W013`: a test that r
 
 If the label is used by only ONE type, the base key (no suffix) is fine — suffix only on collision.
 
-Type aliases (normalized automatically):
+Type aliases (normalized automatically). The suffix and the step may use **different spellings of
+the same type** — `confirm--modal` resolves for `[Confirm] dialog` and `confirm--dialog` resolves
+for `[Confirm] modal`. Prefer the normalized suffix for consistency; either is found.
+
 | Gherkin type | Normalized suffix |
 |---|---|
 | title, label, caption, message | `text` |
@@ -143,6 +146,15 @@ Type aliases (normalized automatically):
 | column | `columnheader` |
 | list-item | `listitem` |
 
+When the step names a type from this table, only a key whose suffix is a spelling of that type is
+used — `[Confirm] dialog` will not fall back to an unrelated `confirm--popup` entry. It reports the
+keys it looked for, so the fix is to add one of them.
+
+A bare `[Confirm]` keeps the older, looser fallback and matches any `confirm--*` entry, because with
+no type there is nothing to match a suffix against. So does a `[Ref]` followed by a word that is not
+an element type at all — `Then User see [Quick Panel] is hidden` reads `is` as that word. This is
+what keeps state-clause steps working on a label whose keys are all suffixed.
+
 ## Nth-Suffixed Keys
 
 When targeting a specific occurrence by index, add `--N` suffix:

package/src/orchestrator/templates/specs-locale-fixture.ts

@@ -42,18 +42,30 @@ interface LocaleInjection {
 
 let cached: LocaleInjection | null | undefined;
 
+/**
+ * Absent config → null, and locale injection is simply off (the documented no-op).
+ *
+ * A config that EXISTS but does not parse is a different thing and must not read the same way: the
+ * header above tells you to hand-edit this file, and a trailing comma would otherwise turn a
+ * `SUNGEN_ENV=ja` run into a base-locale run that asserts base-locale strings — green, and wrong.
+ * We warn rather than throw, because the injection is genuinely optional and failing every test on
+ * it would be a larger change than the fault warrants; the line names the file and the consequence.
+ */
 function loadLocaleConfig(): LocaleInjection | null {
   if (cached !== undefined) return cached;
+  const cfgPath = path.join(__dirname, 'locale-config.json');
+  if (!fs.existsSync(cfgPath)) {
+    cached = null;
+    return null;
+  }
   try {
-    const cfgPath = path.join(__dirname, 'locale-config.json');
-    if (!fs.existsSync(cfgPath)) {
-      cached = null;
-      return null;
-    }
-    const parsed = JSON.parse(fs.readFileSync(cfgPath, 'utf-8')) as LocaleInjection;
-    cached = parsed;
-    return parsed;
-  } catch {
+    cached = JSON.parse(fs.readFileSync(cfgPath, 'utf-8')) as LocaleInjection;
+    return cached;
+  } catch (e) {
+    console.error(
+      `⚠️  ${cfgPath}: unreadable (${e instanceof Error ? e.message.split('\n')[0] : String(e)}) — ` +
+      `locale state is NOT injected, so this SUNGEN_ENV run behaves as the base locale.`,
+    );
     cached = null;
     return null;
   }

package/src/orchestrator/templates/specs-url-assert.ts

@@ -46,6 +46,16 @@ export interface UrlExpectation {
   declared?: string;
   /** The test-data key behind `declared`, so a failure can name what an author must go fix. */
   dataRef?: string;
+  /**
+   * The page selector declared `query: any` — the query string is not part of this page's identity,
+   * so SILENCE from the step stops meaning "there must be no query" (#748).
+   *
+   * Emitted only for a page whose entry says so. The default stays strict: a bare page means a bare
+   * page, which is the #464 assertion and the reason a filter regression cannot read as green.
+   * It is the no-`dataRef` branch alone that this relaxes — a step that declares `with {{v}}` still
+   * asserts every param it names, on this page as on any other.
+   */
+  ignoreQuery?: boolean;
 }
 
 /**
@@ -113,8 +123,14 @@ function locationMatches(pathname: RegExp, hostname: RegExp | undefined, u: URL)
  *                      tracking/UTM param the test never cared about cannot turn it red.
  *                      A declared fragment is asserted too; a declared value carrying no query
  *                      at all constrains the path only (the compiler warns: SG-W014).
+ *
+ * `query: any` on the page's selector entry overrides the FIRST rule only (#748): silence then
+ * means "the query is not mine to judge" instead of "there must be none". It is the escape hatch
+ * for a page whose query is generated at run time — `/admins/detail?id=<the row just clicked>` —
+ * which the strict rule makes unassertable and `with {{v}}` cannot express, since that asserts a
+ * literal. The second rule is untouched: declare params and they are still all checked.
  */
-export function urlMatches({ pathname, hostname, declared, dataRef }: UrlExpectation): (u: URL) => boolean {
+export function urlMatches({ pathname, hostname, declared, dataRef, ignoreQuery }: UrlExpectation): (u: URL) => boolean {
   return (u: URL): boolean => {
     if (!locationMatches(pathname, hostname, u)) return false;
 
@@ -123,7 +139,13 @@ export function urlMatches({ pathname, hostname, declared, dataRef }: UrlExpecta
     // undefined, and they mean opposite things: the first is a real assertion (a bare page must be
     // bare), the second is broken test-data. Only the generator knows which, and it says so by
     // emitting `dataRef` exactly when the step carried a `with {{v}}`.
-    if (!dataRef) return u.search === '';
+    // `query: any` on the page entry (#748): the query is not part of this page's identity, so
+    // silence from the step is not an assertion about it. Without this there is NO way to express
+    // "this path, whatever the query" — `with {{v}}` asserts a LITERAL value, and a detail page
+    // keyed by `?id=<the row just clicked>` has no literal to declare. Checked before the bare-page
+    // rule, never instead of the declared-value rule below: a step that names params still asserts
+    // them here exactly as anywhere else.
+    if (!dataRef) return ignoreQuery ? true : u.search === '';
 
     // Silence is the whole bug class this assertion exists to kill, so an unusable declared value
     // is an ERROR, not a quiet verdict. Returning false would read as "the app is wrong"; these

package/src/orchestrator/templates/wdio.conf.ts

@@ -48,6 +48,14 @@ function evidenceSlug(s: string): string {
     .slice(0, 80) || 'unnamed';
 }
 
+/**
+ * True only in the launcher process. `@wdio/runner` re-parses this very config inside EVERY worker
+ * it spawns, so anything logged at module scope prints once per spec unless it is gated. WDIO's own
+ * "am I a worker" test is this env var (`@wdio/local-runner` sets it when spawning; `@wdio/utils`
+ * reads it) — reuse it rather than inventing a second signal.
+ */
+const IS_LAUNCHER = !process.env.WDIO_WORKER_ID;
+
 /**
  * Auto-select MOBILE specs and classify each by its target OS (dual-target routing).
  *
@@ -82,7 +90,12 @@ function classifyMobileSpecs(root: string): Array<{ file: string; platform: stri
     .filter((full) => {
       try {
         return fs.readFileSync(full, 'utf-8').includes('@wdio/globals');
-      } catch {
+      } catch (e) {
+        // A spec listed by readdir that cannot be read cannot be classified, so it is excluded.
+        // Excluding it SILENTLY is the fault: WDIO only fails the run when the spec list is
+        // EMPTY ("No specs found to run"), so dropping one spec out of ten leaves a green suite
+        // containing a test that never executed. Name it, and let the count below show the shortfall.
+        if (IS_LAUNCHER) console.warn(`[sungen] could not read ${full} — EXCLUDED from this run: ${(e as Error).message}`);
         return false;
       }
     })
@@ -98,6 +111,16 @@ const androidSpecs = specEntries.filter((e) => e.platform !== 'ios').map((e) =>
 const iosSpecs = specEntries.filter((e) => e.platform !== 'android').map((e) => e.file);
 const mobileSpecs = specEntries.map((e) => e.file); // union — top-level fallback
 
+// What DISCOVERY found — a mobile suite is only trustworthy if you can see how many specs it
+// resolved: WDIO fails loudly on an EMPTY list but says nothing when the list is merely short,
+// which is exactly what a dropped spec looks like.
+//
+// Two things this number is not. It is not an error on 0: WDIO already exits 1 there
+// ("No specs found to run"), and a `--shard` that legitimately receives none must still return 0.
+// And under `--shard` it is the PRE-SHARD total, because ConfigParser slices `specs` down to the
+// shard's portion only after this file has finished evaluating.
+if (IS_LAUNCHER) console.log(`[sungen] specs: ${specEntries.length} mobile spec(s) — android ${androidSpecs.length}, ios ${iosSpecs.length}`);
+
 // App under test — env overrides the init-configured defaults.
 const APP_PACKAGE = process.env.APP_PACKAGE || '__APP_PACKAGE__';
 const APP_ACTIVITY = process.env.APP_ACTIVITY || '__APP_ACTIVITY__';