@sun-asterisk/sungen 3.2.31 → 3.2.33

package/src/orchestrator/project-initializer.ts

@@ -16,6 +16,9 @@ import {
   writeMobileCapabilities,
   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 };
 
@@ -93,13 +96,21 @@ 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[];
   private force: boolean;
   private mobile: MobileInitOptions;
 
-  constructor(private baseUrl: string, opts: { agents?: AdapterKey[]; force?: boolean; enabled?: boolean; mobileOnly?: boolean; appPackage?: string; appActivity?: string; appApk?: string; androidUdid?: string; iosBundleId?: string; iosDevice?: string; iosVersion?: string } = {}) {
+  constructor(private baseUrl: string, opts: { agents?: AdapterKey[]; force?: boolean; enabled?: boolean; mobileOnly?: boolean; appPackage?: string; appActivity?: string; appApk?: string; androidUdid?: string; iosBundleId?: string; iosDevice?: string; iosVersion?: string; skipEnvSetup?: boolean } = {}) {
     this.baseCwd = process.cwd();
     this.cwd = this.baseCwd;
     this.agents = opts.agents && opts.agents.length ? opts.agents : (['claude'] as AdapterKey[]);
@@ -114,6 +125,8 @@ export class ProjectInitializer {
       iosBundleId: opts.iosBundleId,
       iosDevice: opts.iosDevice,
       iosVersion: opts.iosVersion,
+      // `--skip-env-setup`: emit appium-environment/ but do not run it (CI, or the manual path).
+      skipEnvSetup: opts.skipEnvSetup ?? false,
     };
   }
 
@@ -132,6 +145,7 @@ export class ProjectInitializer {
       : this.baseCwd;
     this.createdItems = [];
     this.skippedItems = [];
+    this.notDoneItems = [];
 
     console.log(`🚀 Initializing Sungen ${this.mobileOnly ? 'mobile-only ' : ''}project...\n`);
 
@@ -436,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;
       }
     }
@@ -484,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:');
@@ -500,6 +529,8 @@ export class ProjectInitializer {
       console.log(`  ${stepIndex++}. cd ${projectName}`);
     }
     if (this.mobileOnly) {
+      console.log(`  ${stepIndex++}. Open a NEW terminal if the environment setup wrote your shell profile (PATH / JAVA_HOME / ANDROID_HOME)`);
+      console.log(`  ${stepIndex++}. Environment not ready, or a new machine? Re-run: ${appiumEnvironmentRerunCommand()}  (idempotent)`);
       console.log(`  ${stepIndex++}. Fill in .env.appium with your device/app details (see .env.appium.example)`);
       console.log(`  ${stepIndex++}. Create your first screen: sungen add --screen <name>`);
       console.log(`  ${stepIndex++}. Use AI (Copilot/Claude) to generate Gherkin + selectors from the live app`);
@@ -642,8 +673,17 @@ export class ProjectInitializer {
     this.createdItems.push(...result.created);
     this.skippedItems.push(...result.skipped);
 
+    // appium-environment/ provisioning bundle — emitted BEFORE the driver install so it lands even when
+    // npm is offline, run AFTER it so its Appium step finds the project-local CLI. One summary line, not 17.
+    const env = emitAppiumEnvironment(this.cwd);
+    if (env.created.length > 0) this.createdItems.push(`appium-environment/ (${env.created.length} files)`);
+    else this.skippedItems.push('appium-environment/');
+
     // Best-effort driver install — non-fatal so offline init still scaffolds.
     installMobileDriver(this.cwd);
+
+    // Provision JDK / Android SDK / Xcode CLT / env vars / platform drivers — non-fatal by contract.
+    runAppiumEnvironmentSetup(this.cwd, { skip: this.mobile.skipEnvSetup });
   }
 
   /**
@@ -671,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
@@ -682,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 {
@@ -691,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);
@@ -711,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

@@ -124,8 +124,14 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-E027` | A selectors.yaml entry declares a **`type:` that is not a selector type** — `type: 'testId'` (capital I), `'xpth'`, `'rol'`, `'test-id'`. YAML is untyped at run time, so this used to compile clean and resolve through the strategy switch's `default:` as `getByPlaceholder('<the value>')`: a locator that cannot match, surfacing much later as a timeout naming placeholder text nobody wrote. Reported once per entry, naming the entry key and the nearest valid spelling; every step using that entry now compiles to a `throw` | Fix the spelling in selectors.yaml. Valid types: `placeholder`, `role`, `testid`, `label`, `text`, `locator`, `id`, `upload`, `page`, `column`, `frame`, `table`, and the mobile strategies `accessibility-id`, `xpath`, `android-uiautomator`, `ios-predicate`, `css`. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
 | `SG-W030` | A selectors.yaml **`expanded.class`/`expanded.attribute`** value carries a character a class or attribute name cannot — whitespace, a quote, a backslash, `$`, `{`, `}`. The value is pasted into the generated spec (string literal, regex, `classList` argument) and selectors.yaml is often generated from the page under test, so it is refused and the field dropped: the step falls back to driving and asserting `aria-expanded`. Reported once per entry and field. The checked/selected signal is refused outright instead of warned about, because dropping it leaves the step with no state to read at all | Use the plain class or attribute name (Tailwind arbitrary values such as `bg-[#eff6ff]` or `!mt-0` are accepted); never paste a selector fragment or quoted text into the field |
 | `SG-E031` | A selectors.yaml **`checked:`/`selected:` declaration the compiler refuses**: the two spellings disagree (`checked.class` and `selected.class` with different values), a class token or attribute name carries whitespace / a quote / a backslash, or one entry declares both a `class` and an `attribute`. Every one of them is silent at run time — the generated matcher tests a single token, so the step would simply time out blaming your component — and an entry declaring two signals lets an action drive one while the assertion after it reads the other. Refused, not dropped: with no signal the step is back on the *"has no on/off state to set"* failure the declaration exists to remove | Declare ONE spelling and ONE of `class` / `attribute`, as a single plain token: `checked: { class: 'is-checked' }`, `selected: { class: 'border-link' }`, or `checked: { attribute: 'data-checked' }`. This is a selectors.yaml-only fix, allowed inside the run-test auto-fix loop |
-
-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` and `SG-E027` 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).
+| `SG-W032` | A step carries the row filter **`in [T] table with {{v}}`** but the pattern that compiled it dropped the clause, so the generated code runs against the WHOLE table. `Then User see [Status] text in [Job Table] table with {{job_title}}` asserts on every `.status` in the table and passes on a row the sentence never named. The `table-*` family (positioned rows included) resolves its own container and is not flagged, nor is the two-`with` form, which scopes the row correctly, nor a step that WRITES — a write needs a value, so its `with {{v}}` IS that value and `fill [Search] field in [T] table with {{v}}` is an ordinary container-scoped write | Rewrite with the two-`with` form: `User see [Status] text with <expected> in [Job Row] row with {{job_title}}`. Point the second `[…]` at a ROW entry in selectors.yaml, not at the table entry — a filter applied to the table narrows nothing |
+| `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`, `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

@@ -154,6 +154,7 @@ two content-filtered queries can hit different rows if the table re-renders in b
 #    dropdown | select | combobox → tag probed at runtime (toHaveValue native, toHaveText custom trigger)
 # 5. State: User see [T] button is disabled | checkbox is checked | dialog with {{v}} is hidden
 # 6. Attribute (toHaveAttribute): User see [T] image | link with {{v}}
+#    WHICH attribute comes from the entry's `attribute:` — any name, not just href/src
 # 7. Count: User see [T] row with {{count}}
 # 8. Page: User see [T] page | page with {{url}}   ← `with` also asserts the query string
 #    NEVER a state: `page is hidden` / `page is empty` … are NOT step forms (see Pattern 8 below)
@@ -291,7 +292,22 @@ job table:
   value: 'div.job-list'
   rows: 'div.job-row'        # what EVERY row matches — NOT a row label's entry
 ```
-Two different keys, two meanings: `rows:` on the table = every row (the shape); a `type: locator` entry on a **row label** = ONE positioned row (`tbody tr:first-child`). A shape put on a row label fails at run time with a `toHaveCount(1)` message that points back here. A CSS-located table with no `rows:` gets `SG-W016`. On a shaped table `table row {{n}}` counts from the first data row (no header offset).
+Two different keys, two meanings: `rows:` on the table = every row (the shape); a `type: locator` entry on a **row label** = ONE positioned row (`tbody tr:first-child`). A shape put on a row label fails at run time with a `toHaveCount(1)` message that points back here. A table located by CSS — or by a role that holds no rows, such as `role: list` or `role: region` — with no `rows:` gets `SG-W016`. On a shaped table `table row {{n}}` counts from the first data row (no header offset).
+
+**A shaped row has no CELLS either, so the two cell-reading steps need one more declaration.** `see [Col] column with {{v}}` reaches the cell through `getByRole('cell')`, and `table match data:` reads its header row from `thead tr` and addresses cells as `td, th` — a `<div>` row has none of those. Name the cell on the column:
+```yaml
+job table:
+  type: locator
+  value: 'div.job-list'
+  rows: 'div.job-row'
+  columns:
+    title:
+      index: 0
+      header: 'Title'
+      elements:
+        cell: { type: locator, value: '.job-title' }   # relative to ONE row
+```
+With it, `see [Title] column with {{v}}` compiles to `tableRow.locator('.job-title')` and `table match data:` stops reading `thead` altogether — the header-to-column mapping is then known at compile time, so there is nothing left to race with. Without it on a shaped table, `see [Col] column` warns (`SG-W034`) and `table match data:` is refused outright (`SG-E035`) rather than waiting out every timeout against a header row that will never exist.
 
 ### Browser storage `[web]`
 
@@ -556,6 +572,7 @@ award:
 | `page` | relative URL | — | navigation |
 | `upload` | — | — | file inputs |
 | `frame` | iframe selector | — | iframes |
+| `id` | `#the-id` (a bare `the-id` also works) | — | an element whose only stable handle is its DOM id |
 
 Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `columns` `checked` `selected`
 
@@ -569,6 +586,39 @@ when the state differs, then assert it; `is checked` / `is unchecked` / `is sele
 the same entry (`is focused`, …) keep their native matchers. The value must be ONE plain class token or
 attribute name — whitespace, a quote or a backslash is refused at compile time, naming the entry.
 
+`attribute:` names the attribute an `image`/`link` assertion reads, and it takes ANY attribute name
+straight from the YAML — nothing is hardcoded to `href`/`src`. To assert several attributes of ONE
+element, declare several keys with the SAME locator and different `attribute:`; each key is then a
+separate reference in the Gherkin:
+```yaml
+job link:            # the link's TEXT
+  type: locator
+  value: 'a.job-link'
+job link href:       # the same element, its href
+  type: locator
+  value: 'a.job-link'
+  attribute: href
+job link target:
+  type: locator
+  value: 'a.job-link'
+  attribute: target
+```
+
+**A `page` value that is an ABSOLUTE URL now anchors the HOST as well as the path.** `value:
+'https://admin.example.com/jobs'` means "that path on that host": `see [X] page`, `is on [X] page`
+and `should remain on` all fail on `https://admin-stg.example.com/jobs`. Before, only `wait for [X]
+page` checked the host and the assertions matched the path on any host at all — so an assertion
+naming one environment silently passed in another. If the page is the same in every environment,
+declare it **relative** (`value: '/jobs'`) and let `baseURL` supply the host; keep the absolute form
+for a destination that really is on another host.
+
+`anchor:` is a `page` entry's rendered-content proof: `Then User see [X] page` asserts the URL AND
+that the anchor element is present, so a route guard that leaves the URL alone cannot pass it. Three
+things it does NOT do, each verified rather than assumed: it is read only by the `Then`-side page
+assertion, so `Given User is on [X] page` ignores it; the `should see route` / `should remain on`
+forms ignore it too — they compile through the route assertion, which is never handed an anchor; and
+nothing warns when a page entry declares one and no step asserts that page.
+
 `scope` (e.g. `scope: dialog`) is `[web]`-effective only — no Appium template reads `inDialog`, so
 on mobile a dialog-scoped ref still resolves against the whole screen (`SG-W021`).
 
@@ -580,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) |
@@ -645,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).
@@ -724,7 +783,9 @@ npx playwright test --grep "@smoke|@high"    # smoke OR high
 | Serial (default) | `test.describe.serial()` | Shared | `beforeAll` (1 goto) | Skip remaining |
 | `@parallel` | `test.describe()` | Fresh per test | `beforeEach` (N goto) | Continue |
 
-**`@parallel` is required** when a feature has multiple auth groups (e.g., `@auth:user` + `@no-auth` scenarios). Serial mode uses one shared browser context and cannot mix auth roles. The compiler will error if `@parallel` is missing in this case.
+**Multiple auth groups need the default isolation.** A feature mixing `@auth:user` with `@no-auth` compiles as-is — features are parallel by default, and `@parallel` only names that default. What breaks it is `@serial`: one shared browser context cannot carry two different sessions, so the compiler errors and asks you to drop `@serial` or split the feature.
+
+`@no-auth` is a demand for an **empty** session, not merely the absence of `@auth:`. Its scenarios compile into their own `test.describe('no-auth')` with an inline empty `storageState`, so they stay signed out even when `playwright.config.ts` sets a global one. An untagged scenario is different again: it inherits whatever that config says.
 
 ### `@flow` tag (E2E cross-screen testing)
 
@@ -806,6 +867,7 @@ dashboard:
 | Assertion clause the pattern drops | `Then User see [Code] text matches "<format>"` compiling to a bare `toBeVisible()` | Use the exact supported phrasing for the clause (see the `matches` / `contains` / `has text` forms above). A clause that gets swallowed leaves an assertion that passes whatever the element says, so the step is rejected with `SG-E023` instead. If the step still compiles bare, you are on an older global sungen — run `npx sungen` |
 | Mobile lifecycle step with no app id | `When User restart the app` in a feature whose `Path:` carries only a route | Declare the app id on the Feature: `Path: com.example.app/.MainActivity \| com.example.app`. The lifecycle steps resolve the app from `Path`; without it the whole spec would die at runtime, so the step is rejected with `SG-E024`. For a mobile unit `--path` carries the APP ID, `--reach` carries the navigation recipe |
 | Missing target type | `fill [email] with {{v}}` | `fill [email] field with {{v}}` |
+| Asserting a cell with the row filter | `Then User see [Status] text in [Job Table] table with {{v}}` | The single `with` is read as the EXPECTED VALUE, not as a row filter, so the assertion runs against the WHOLE table and can pass on a row the sentence never named. Use the two-`with` form — `Then User see [Status] text with <expected> in [Job Row] row with {{v}}` — pointing the second `[…]` at a ROW entry, not at the table entry (a filter applied to the table narrows nothing). Warned with `SG-W032`. A `fill` is NOT flagged: a write needs a value, so its `with {{v}}` is that value and the step is an ordinary container-scoped write |
 | Background with scope | `Background: ... And User is on [X] dialog` | Use `@steps` + `@extend` for scope-dependent flows |
 | `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
 | Literal URL navigate | `User navigate to "/dashboard"` | `User is on [Dashboard] page` (add page selector in `selectors.yaml`) |

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: