@sun-asterisk/sungen 3.2.24 → 3.2.26

package/src/orchestrator/lockstep-version.ts

@@ -0,0 +1,46 @@
+import { spawnSync } from 'child_process';
+
+/**
+ * Lockstep version resolution for the sungen package family.
+ *
+ * Core (`@sun-asterisk/sungen`) and every capability driver (`@sungen/driver-*`) are published
+ * together, so a project must hold ONE version line across all of them: a driver built against
+ * core 3.2.24 loading against core 3.2.20 is a silent-breakage class we refuse to ship. Both
+ * `sungen capability add` (first install) and `sungen update` (project sync) resolve the target
+ * version through here so they can never disagree.
+ */
+
+/** The running CLI's (core) version — family packages install in lockstep with it (not `@latest`). */
+export function coreVersion(): string {
+  try { return require('../../package.json').version || 'latest'; } catch { return 'latest'; }
+}
+
+/**
+ * Resolve the version to install for a family package, given the running `core` version.
+ *
+ * Lockstep wants the EXACT `core` version. But the beta channel publishes `<core>-beta.N` before a
+ * stable `<core>` ever exists — so a released core (e.g. 3.2.10) asking for `@3.2.10` hits ETARGET
+ * out-of-the-box when npm only has `3.2.10-beta.2` (`sungen capability add` then fails for a fresh
+ * user). Fall back on the SAME version line: prefer exact `core`, else the highest `core-beta.N`,
+ * else the `beta` dist-tag as a last resort. Keeps the driver's pinned core-dep on the same line.
+ */
+export function resolveDriverVersion(pkg: string, core: string): string {
+  if (core === 'latest') return 'beta';
+  try {
+    const out = spawnSync('npm', ['view', pkg, 'versions', '--json'], { encoding: 'utf-8', shell: true });
+    if (out.status !== 0 || !out.stdout) return core; // can't query → let the exact install try/fail
+    let versions: string[] = [];
+    const parsed = JSON.parse(out.stdout);
+    versions = Array.isArray(parsed) ? parsed : [parsed];
+    if (versions.includes(core)) return core; // exact exists → lockstep
+    const prefix = `${core}-beta.`;
+    const betas = versions
+      .filter((v) => typeof v === 'string' && v.startsWith(prefix))
+      .map((v) => parseInt(v.slice(prefix.length), 10))
+      .filter((n) => Number.isInteger(n));
+    if (betas.length) return `${core}-beta.${Math.max(...betas)}`; // highest same-line prerelease
+    return 'beta'; // nothing on this line → newest beta dist-tag
+  } catch {
+    return core;
+  }
+}

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

@@ -0,0 +1,175 @@
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolveDriverVersion } from './lockstep-version';
+
+/**
+ * Project-local sync of the sungen package family after a global `sungen update`.
+ *
+ * `sungen update` used to run `npm install -g @sun-asterisk/sungen@<channel>` and stop there. That
+ * left every PROJECT-local copy behind, and a project always has them: `sungen capability add <x>`
+ * installs `@sungen/driver-<x>` as a devDependency pinned to the core version of the day, and each
+ * driver declares `@sun-asterisk/sungen` as a dependency — so a local core lands in the project's
+ * node_modules too, along with the `sungen` bin link. The lockfile then pins all of it. Result after
+ * an update: global 3.2.24, project still 3.2.20, and `npx sungen` inside the project silently
+ * running the OLD compiler — with drivers built against a core that is no longer the one loading
+ * them.
+ *
+ * So the update also reconciles the project: every family package declared (or physically present)
+ * in the project is reinstalled on the running core's version line.
+ */
+
+/** Family = core + every capability driver. These MUST share one version line in a project. */
+const CORE_PKG = '@sun-asterisk/sungen';
+const isFamily = (name: string): boolean => name === CORE_PKG || name.startsWith('@sungen/driver-');
+
+/** Declared specs pointing at a checkout, not the registry — a workspace/dogfood link we must not clobber. */
+const isLocalSpec = (spec: string): boolean =>
+  /^(file:|link:|workspace:|portal:|\.{1,2}\/|\/)/.test(spec) || spec.startsWith('git+') || spec.startsWith('github:');
+
+export interface FamilyPkg {
+  pkg: string;
+  /** Range in package.json dependencies/devDependencies, or null when only present transitively. */
+  declared: string | null;
+  /** Version actually resolved in the project tree, or null when absent. `link` = symlinked. */
+  installed: string | null;
+}
+
+export interface DepSyncPlan {
+  /** `npm install -D` specs to run. Empty when nothing needs to change. */
+  specs: string[];
+  /** Family packages found in the project, for reporting. */
+  found: FamilyPkg[];
+  /** Packages deliberately left alone, with the reason. */
+  skipped: Array<{ pkg: string; why: string }>;
+  /** Set when there is no project to sync at all (no package.json / no family packages). */
+  noop?: string;
+}
+
+/** Read a package.json, returning null when missing or malformed. */
+function readJson(file: string): Record<string, any> | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Version of `pkg` as installed in the project tree, or null. Symlinked (workspace) → `link`. */
+function installedVersion(cwd: string, pkg: string): string | null {
+  const dir = path.join(cwd, 'node_modules', ...pkg.split('/'));
+  try {
+    if (fs.lstatSync(dir).isSymbolicLink()) return 'link';
+  } catch {
+    return null;
+  }
+  return readJson(path.join(dir, 'package.json'))?.version ?? null;
+}
+
+/**
+ * Decide what the project needs so its family packages sit on `core`'s version line.
+ *
+ * Pure apart from reading the project tree and (for stale packages) asking npm which versions exist
+ * on that line — no installs, so `--dry-run` and the tests can plan without side effects.
+ */
+export function planProjectDepSync(
+  cwd: string,
+  core: string,
+  resolve: (pkg: string, core: string) => string = resolveDriverVersion,
+): DepSyncPlan {
+  const pkgJson = readJson(path.join(cwd, 'package.json'));
+  if (!pkgJson) {
+    return { specs: [], found: [], skipped: [], noop: 'no package.json here — nothing project-local to sync' };
+  }
+
+  const declaredAll: Record<string, string> = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
+  const names = new Set(Object.keys(declaredAll).filter(isFamily));
+
+  // A transitively-installed core (pulled in by a driver) is the copy that owns the project's `sungen`
+  // bin link, so it must be reconciled even though nothing declares it.
+  if (!names.has(CORE_PKG) && installedVersion(cwd, CORE_PKG)) names.add(CORE_PKG);
+
+  if (!names.size) {
+    return {
+      specs: [],
+      found: [],
+      skipped: [],
+      noop: 'no sungen packages installed in this project — the global update is all that was needed',
+    };
+  }
+
+  const found: FamilyPkg[] = [...names].sort().map((pkg) => ({
+    pkg,
+    declared: declaredAll[pkg] ?? null,
+    installed: installedVersion(cwd, pkg),
+  }));
+
+  const specs: string[] = [];
+  const skipped: Array<{ pkg: string; why: string }> = [];
+
+  for (const entry of found) {
+    if (entry.declared && isLocalSpec(entry.declared)) {
+      skipped.push({ pkg: entry.pkg, why: `declared as ${entry.declared} (local checkout, not the registry)` });
+      continue;
+    }
+    if (entry.installed === 'link') {
+      skipped.push({ pkg: entry.pkg, why: 'symlinked (workspace or npm link)' });
+      continue;
+    }
+    if (entry.installed === core) continue; // already on the running core's exact version
+    specs.push(`${entry.pkg}@${resolve(entry.pkg, core)}`);
+  }
+
+  return { specs, found, skipped };
+}
+
+/**
+ * Reconcile the project's sungen family packages with the running core version.
+ *
+ * Runs ONE `npm install -D` for every stale package so the lockfile is rewritten in a single
+ * resolution pass. Best-effort by design: a failure here (offline, private registry, no write
+ * permission) must not fail `sungen update` — the global install already succeeded, and the user
+ * gets the exact command to finish the job by hand.
+ *
+ * @returns true when the project ended up in sync (or needed nothing), false when the install failed
+ */
+export function syncProjectSungenDeps(cwd: string, core: string, dryRun: boolean): boolean {
+  const plan = planProjectDepSync(cwd, core);
+
+  console.log('🔗 Syncing project-local sungen packages...');
+  if (plan.noop) {
+    console.log(`   – ${plan.noop}\n`);
+    return true;
+  }
+  for (const s of plan.skipped) console.log(`   – skipped  ${s.pkg} — ${s.why}`);
+
+  if (!plan.specs.length) {
+    console.log(`   ✓ already on ${core}: ${plan.found.map((f) => f.pkg).join(', ')}\n`);
+    return true;
+  }
+
+  for (const f of plan.found) {
+    if (!plan.specs.some((s) => s.startsWith(`${f.pkg}@`))) continue;
+    const wasTransitive = f.declared ? '' : '  (was transitive — pinning explicitly)';
+    console.log(`   • ${f.pkg}  ${f.installed ?? '(not installed)'} → ${core}${wasTransitive}`);
+  }
+
+  const cmd = `npm install -D ${plan.specs.join(' ')}`;
+  if (dryRun) {
+    console.log(`   [dry-run] would run: ${cmd}\n`);
+    return true;
+  }
+
+  console.log(`   📦 ${cmd}`);
+  const r = spawnSync('npm', ['install', '-D', ...plan.specs], { cwd, stdio: 'inherit', shell: true });
+  if (r.status !== 0) {
+    console.warn(
+      `⚠️  Project-local sync failed — the GLOBAL sungen is now ${core}, but this project still holds\n` +
+      '   older copies, so `npx sungen` here would keep running the old compiler. Finish manually:\n' +
+      `       ${cmd}\n`,
+    );
+    return false;
+  }
+  console.log(`   ✓ project-local packages on ${core}\n`);
+  return true;
+}

package/src/orchestrator/project-initializer.ts

@@ -656,9 +656,12 @@ export class ProjectInitializer {
 
     // 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
+    // from the generated specs/api.ts — installed up front so an `encoding: xml`
+    // catalog entry works without a mid-suite MODULE_NOT_FOUND.
     const requiredDeps = this.mobileOnly
-      ? ['@types/node', 'yaml', 'ajv', 'ajv-formats']
-      : ['@playwright/test', '@types/node', 'yaml', 'ajv', 'ajv-formats'];
+      ? ['@types/node', 'yaml', 'ajv', 'ajv-formats', 'fast-xml-parser']
+      : ['@playwright/test', '@types/node', 'yaml', 'ajv', 'ajv-formats', 'fast-xml-parser'];
 
     let missingDeps: string[] = requiredDeps;
     try {

package/src/orchestrator/templates/ai-src/commands/add-flow.md

@@ -88,6 +88,22 @@ qa/flows/${input:flow}/
 
 ### 1a. Define the flow's BOUNDARY, then its screens
 
+**FIRST: look for a boundary the project has already decided.** Before applying the generic
+checklist, search the spec/docs tree for a document that defines the flows —
+`*System_Test*.md`, `*Flow*.md`, `BF-*`, a flow inventory, a test-plan section listing flows. If
+one exists, **its boundary wins**: use the flows and scope it declares rather than re-deriving them
+from a single user story.
+
+This is not a preference, it is where a whole run went wrong. A project whose `System_Test_Flows.md`
+defined `BF-B0 = Dashboard` as one flow covering six regions got a boundary re-derived from one
+user story instead, narrowing the scope to "view dashboard" and pushing six of eleven requirements
+out of the flow **before generation started**. Every later step — coverage map, audit, delivery —
+then ran correctly on the wrong scope, and no gate could see it, because each of them measures
+against the boundary rather than questioning it.
+
+Apply the generic ISTQB checklist below only when NO project-specific boundary document exists.
+
+
 > QA teams often call this level **System Test** — same thing: one fully-integrated business
 > journey verified against the spec. Use whichever name the team knows; the boundary rules
 > below are the ISTQB system-test design rules.

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

@@ -64,6 +64,15 @@ restated from screen specs the project does not hold, say so: the audit reports
 `SPEC-RESTATED-UNVERIFIED` because `specFR 100%` over a hand-copied list certifies the copy, not
 the source.
 
+**The viewpoint carries BOTH classification axes.** `VP-LOGIC / VP-VAL / VP-SEC / VP-NAV` classify
+by TECHNICAL RISK; `BF / AF / EF` classify by BUSINESS BRANCH. They answer different questions and
+neither replaces the other — a reviewer needs to see both, so use the compound id
+(`VP-SEC-EF02-001`) and give the viewpoint a section per flow as well as its priority table by
+theme. And restate the use case's `successGuarantee` / `minimalGuarantee` at the top of the
+viewpoint (a one-line quote of the contract is enough): every Exception Flow's own outcome is
+written against the minimal guarantee, and a reader of the viewpoint alone cannot check that if the
+anchor is only in another file.
+
 **The contract does NOT replace `test-viewpoint.md` — author BOTH.** They answer different
 questions and only one of them is a yardstick:
 

package/src/orchestrator/templates/ai-src/commands/delivery.md

@@ -158,8 +158,15 @@ requirements:
 saying "proven by DI-SEC-CSRF" is prose — nothing detects it when that scenario later changes. If a
 scenario in THIS feature proves the requirement, **add `@spec:<id>` to that scenario** so the trace
 is real, then drop the override (it derives as `covered` on its own). Use `covered_elsewhere` only
-when another suite proves it, and name that suite; `not_applicable` when the spec itself excludes
-the requirement.
+when another suite proves it, and name that suite.
+
+**`not_applicable` is the narrowest status — do not reach for it because it needs no extra
+information.** It means the requirement belongs to a different feature or module and will NEVER be
+covered by this flow. Anything you intend to cover later — a next batch, a follow-up flow, work
+deferred for time — is `planned`, and the note must say WHICH batch or flow. A field review hit
+exactly this: six requirements narrowed out of scope were marked `not_applicable`, and the reviewer
+read that as a permanent, deliberate exclusion and had to go back and ask. `planned` costs one more
+sentence and answers the question before it is asked.
 
 Then validate and fix any ERROR findings:
 

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

@@ -91,6 +91,11 @@ Stop here for mobile — do not continue to the web path.
 Parse from `$ARGUMENTS`:
 - **name** — screen or flow name. If missing, ask the user.
 - **`--env <locale>`** — optional. Sets `SUNGEN_ENV=<locale>` for the test run so the runtime test-data resolver merges `<name>.<locale>.yaml` over the base, and `playwright.config.ts` writes results to `<name>-test-result.<locale>.json`. Accept `--locale <locale>` as an alias. The value can also be a plain ENVIRONMENT name (`dev`, `uat`, `stg`): the same overlay applies to test-data AND `.env.qa.<env>` overlays `.env.qa` (secrets, API/DB datasource URLs); when `SUNGEN_BASE_URL` is declared there, the web baseURL switches too — no config edit, no recompile.
+- **`--change-only`** — re-run only the scenarios a selectors / test-data / feature edit obliges, then merge
+  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.
 - **`--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.
@@ -153,6 +158,53 @@ If the unit is **api-first**, skip every selector/capture phase (an API test has
 5. **Integrity + trace** — `sungen script-check --area <name>` (1:1; on DRIFT re-`generate --area`, never hand-edit the spec) + `sungen trace --area <name>` (process map + HUMAN-LOOP FOCUS). Report + offer next steps.
 {{/cap}}
 
+## Scope gate — ask BEFORE running, only when there is a real choice
+
+Run this immediately after platform detection, before Pre-run. It decides WHAT to run; skipping it
+is how a QA ends up re-running 100 cases to re-check 3, or worse, re-running 3 and losing the 97.
+
+```bash
+[ -x ./bin/sungen.js ] && ./bin/sungen.js changed --screen <name> --json || npx sungen changed --screen <name> --json
+```
+
+Read `summary.selected`, `summary.total`, `all`, and `reasons`, then follow this table exactly:
+
+| 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. |
+| `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. |
+
+**Close EVERY accepted run by recording the baseline** — full runs included, not just subsets:
+
+```bash
+[ -x ./bin/sungen.js ] && ./bin/sungen.js changed --screen <name> --record || npx sungen changed --screen <name> --record
+```
+
+Without this the first run leaves no baseline, so the next invocation reports `no previous run
+recorded` and runs everything again — the narrowing never starts. Record it after the run whose
+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.
+
+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:
+
+- **`Chạy N case đã đổi` (Recommended)** — description: names the N scenarios (truncate past 3 with
+  "…và K case khác") and states that the previous results are preserved by the merge, so the report
+  stays complete.
+- **`Chạy full M case`** — description: slower, and states WHEN it is the right call — before a
+  delivery/hand-off, or when the APP under test changed.
+
+That second reason matters and must be said: the selection fingerprints **the QA's files only**
+(feature, selectors, test-data, project config). It cannot see the app under test. If the build
+changed, nothing in `qa/` moved, `changed` reports "nothing changed", and only a full run tells you
+anything. Never present the changed set as proof the rest still passes — it is proof only that the
+rest was not re-examined.
+
+Do not add a third option. "Show me more detail" is not a choice — the detail is printed above the
+question already.
+
 ## Pre-run (phased — per `sungen-selector-fix` skill)
 
 1. Verify `<base>/<name>/` has `.feature` + `test-data.yaml`. **If the feature has `@query` steps**, check the resolved datasource `engine` in `qa/datasources.yaml` — unsupported engine → follow the `sungen-gherkin-syntax` skill § "Unsupported DB engine — fallback" before compiling (do not attempt a direct connect).
@@ -253,6 +305,22 @@ PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/flows/<name>/<name>-test-result.json
 
 **DO NOT** pass `--reporter=...` flag — it overrides the reporters from `playwright.config.ts` and disables the JSON reporter that `sungen delivery` depends on.
 
+**Re-running a SUBSET (fix-and-retry, or a partially edited spec) when the per-target result file already exists:** the JSON reporter would OVERWRITE it and lose every result you didn't re-run. Write the subset's report to a temp file and MERGE it instead — same title wins, everything else is kept:
+
+```bash
+# re-run just the failed cases (or -g "<scenario title>") into a temp report…
+PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<name>/subset-tmp.json \
+  npx playwright test specs/generated/<name>/<name>.spec.ts --last-failed
+
+# …then fold it into the existing per-target file (delivery reads the merged result)
+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.
+
+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).
+
 ```bash
 # ❌ Wrong — --reporter flag disables the config's JSON reporter
 {{#cap parallel-subagents}}
@@ -281,6 +349,47 @@ If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter over
 `sungen delivery` reads per-feature `<basename>-test-result[.env].json` files (one per feature in the screen) and writes one CSV/XLSX per feature (e.g. `home-testcases.csv` + `home-modal-testcases.csv`). When `--env <locale>` was used here, run delivery with the same locale (`/sungen-delivery <name> --env <locale>`) so it picks the matching `*-test-result.<locale>.json` files and produces `*-testcases.<locale>.csv` / `.xlsx`.
 {{/cap}}
 
+
+## `--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:
+
+```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)
+
+# 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
+
+# 5. record the new baseline — ONLY after a run you accept
+npx sungen changed --screen <name> --record
+```
+
+**Selection rules** (deterministic, computed by `sungen changed`): a scenario re-runs when its own
+steps/tags changed, when a selectors.yaml key it references changed, or when a test-data key it
+binds changed. A `Background` edit re-runs everything, because the Background runs before every
+scenario. An edit that cannot be attributed — an unparseable YAML, a file that is not a key
+mapping, or no baseline yet — selects **every** scenario and says so. That bias is deliberate:
+over-running costs minutes, under-running reports a scenario green that never re-ran after the
+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.
+
 ## Next steps
 
 After showing results, use `AskUserQuestion` to offer next steps:

package/src/orchestrator/templates/ai-src/config/claude.md

@@ -80,7 +80,7 @@ qa/deliverables/<name>-testcases.xlsx  # Styled workbook for client hand-off
 
 ## Test Data
 
-`{{variable}}` references in `.feature` map to keys in `test-data/<screen>.yaml`. Data is loaded **at runtime** — the same generated `.spec.ts` works across environments without recompiling.
+`{{variable}}` references in `.feature` map to keys in `test-data/<screen>.yaml`. They belong in slots that take a value (`with {{v}}`, `as {{v}}`, `contains {{v}}`) — never inside a `[Target]`, which is a selector key matched literally. Data is loaded **at runtime** — the same generated `.spec.ts` works across environments without recompiling.
 
 **Environment overrides**: `SUNGEN_ENV=staging npx playwright test` merges `<screen>.staging.yaml` on top of `<screen>.yaml`. Create `<screen>.<env>.yaml` for environment-specific values (different credentials, URLs, test users).
 

package/src/orchestrator/templates/ai-src/config/copilot.md

@@ -80,7 +80,7 @@ qa/deliverables/<name>-testcases.xlsx  # Styled workbook for client hand-off
 
 ## Test Data
 
-`{{variable}}` references in `.feature` map to keys in `test-data/<screen>.yaml`. Data is loaded **at runtime** — the same generated `.spec.ts` works across environments without recompiling.
+`{{variable}}` references in `.feature` map to keys in `test-data/<screen>.yaml`. They belong in slots that take a value (`with {{v}}`, `as {{v}}`, `contains {{v}}`) — never inside a `[Target]`, which is a selector key matched literally. Data is loaded **at runtime** — the same generated `.spec.ts` works across environments without recompiling.
 
 **Environment overrides**: `SUNGEN_ENV=staging npx playwright test` merges `<screen>.staging.yaml` on top of `<screen>.yaml`. Create `<screen>.<env>.yaml` for environment-specific values (different credentials, URLs, test users).
 

package/src/orchestrator/templates/ai-src/skills/sungen-api-design/SKILL.md

@@ -84,6 +84,41 @@ A flow (`create → login → delete`) is a **Functional integration** test, **n
 
 Fixture path resolves cwd-relative/absolute first, else `qa/fixtures/<path>` (drop sample files there, reference by name from `test-data`). An empty resolved file param omits the part → use for missing-file `@cases` error rows. `files:`/`bodyFile:` are mutually exclusive. A **`GET`/`HEAD` entry may carry no body at all** (no `body:`/`files:`/`bodyFile:`) — HTTP forbids it and the catalog lint refuses it; put the inputs in the path or `query`, or use `POST`. **Automate the upload success case with `@api`** — don't defer it to `@manual`.
 
+## XML APIs (`encoding: xml`)
+
+For services that accept/return XML (OTA/SOAP-style backends). Works with ANY XML shape — attributes, namespaces, CDATA, nesting.
+
+**Send** — the body is a raw string template (YAML block scalar); declared `params:` bind as `:name` tokens:
+```yaml
+stock_check:
+  method: POST
+  path: /agent-api
+  encoding: xml
+  params: [agent_code, signature, item_code]
+  body: |
+    <?xml version="1.0" encoding="UTF-8" ?>
+    <request>
+      <method>StockCheck</method>
+      <agent_code>:agent_code</agent_code>
+      <signature>:signature</signature>
+      <item_code>:item_code</item_code>
+    </request>
+```
+Only DECLARED params bind (namespace prefixes like `soapenv:Envelope` are never touched). Bound values are XML-escaped (`& < > " '`) so data can't corrupt the document; wrap a token as `<![CDATA[:param]]>` to bind raw. Content-Type defaults to `application/xml` (override via `headers:`).
+
+**Read** — a response whose Content-Type contains `xml` (never `html`) parses to an object for `{{name.body.<path>}}`; a missing/octet-stream Content-Type is sniffed only when the body starts with `<?xml`. Charset comes from the Content-Type, else the XML declaration, else UTF-8 (Shift_JIS responses decode correctly). Mapping:
+
+| XML | Bound value |
+|---|---|
+| `<error_code>01000001</error_code>` | `{{r.body.response.error_code}}` = `"01000001"` (always strings — no numeric coercion, leading zeros survive) |
+| `<smok></smok>` / `<smok/>` | `""` |
+| `<shop id="7">` | `{{r.body.response.shop.@_id}}` = `"7"` (attributes keep an `@_` prefix) |
+| `<soapenv:Body>` | key stays `soapenv:Body` (`{{r.body.soapenv:Envelope.soapenv:Body...}}`) |
+| `<memo><![CDATA[x & y]]></memo>` | plain text `x & y`; `&amp;`-style entities decode (the 5 predefined only) |
+| repeated `<item>` | declare `arrayPaths: [r.items.item]` (dot path INCLUDING the root element) — then 1 item and N items are BOTH arrays and `[0]` access never breaks. Without it, one item is an object and two are an array. |
+
+Caveats: an element literally named `count`/`first`/`last`/`length` under an array parent is shadowed by the path helper's own accessors; parse failure keeps the raw string body (same as any non-JSON response); the 5 predefined entities decode even inside response CDATA sections (a deliberate deviation from strict XML — assert the decoded form). Field metadata / `matches schema` / OpenAPI import for XML are not supported yet. The project needs the `fast-xml-parser` dev dependency (new projects get it from `sungen init`; older ones: `npm install --save-dev fast-xml-parser` — generate warns when it's missing).
+
 ## Per-endpoint knobs & auth patterns
 - **Timeout** — a slow endpoint can override the datasource default (15s) with `timeout_ms: 30000` on its catalog entry (else the datasource `timeout_ms` applies).
 - **OAuth2 (pure API, no browser)** — no new grammar; it's `@api` chaining. Call the token endpoint, bind the token, thread it into later calls' `Bearer :token` header:
@@ -95,6 +130,20 @@ Fixture path resolves cwd-relative/absolute first, else `qa/fixtures/<path>` (dr
   ```
   The token endpoint is a normal catalog entry (`POST /oauth/token`, form/JSON body); `list_orders` carries `headers: { authorization: "Bearer :token" }`. For a browser-authorized session instead, use `@hybrid` + `@auth:<role>`.
 - **Pagination** — use query params (`?page=:page&limit=:limit`, imported into `params`) + assert the page shape with plain field access (`{{list.body.next_page_token}}`, `{{list.body.items.length}}`); no special primitive needed.
+- **Download an absolute URL from a response** (export/report endpoints returning a `body.url` on blob storage): declare a catalog entry whose `path:` is EXACTLY one token, and thread the URL as its param — this is the only supported syntax:
+  ```yaml
+  download_export:
+    method: GET
+    path: ":url"
+    params: [url]
+  ```
+  ```gherkin
+  @api:export_report @api:download_export(url={{export_report.body.url}})
+  Scenario: VP-API-FLOW exported file is downloadable
+    Then expect {{export_report.status}} is 200
+    And expect {{download_export.status}} is 200
+  ```
+  The bound value must be an ABSOLUTE http(s) URL — an empty string, a relative path, or any other scheme (`file:`, `data:`, `mailto:`) fails the run loudly, so a broken export returning `{"url": ""}` can never false-pass. Presigned query escapes survive verbatim; a non-JSON body (CSV/text) is kept as text for `expect {{download_export.body}}` assertions. A catalog entry may also declare a literal absolute `path: "https://…"` (its `:params` bind with normal encoding). **Security:** when the REQUEST URL's origin differs from the datasource `base_url`, none of the datasource headers are sent (auth/tenant defaults must not leak to another origin) — a cross-origin download that needs a header must declare it in the entry's own `headers:`. This boundary applies to the initial request only: a same-origin request that REDIRECTS to another origin still carries the datasource headers (fetch auto-strips only `authorization`/`cookie`/`proxy-authorization` cross-origin) — prefer binding the final URL over following an API-origin redirect. The 15s default timeout may be short for large files (`timeout_ms:` on the entry).
 
 ## Rules
 - **No HTTP, no selectors** — only `.feature` + the reviewed `apis.yaml` + `test-data`.

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

@@ -77,6 +77,7 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 |---|---|---|
 | strict mode violation | Multiple elements match | Add `nth: 0`, `exact: true`, or more specific `name` |
 | strict mode violation on `see`/`hover [X] item\|option\|cell with {{v}}` (dynamic list) | Older builds didn't filter the locator by the value | Since 3.2.13 `see`/`hover ... with {{v}}` on list-member roles filters by `hasText` like `click` (existence/hover the matching item) — keep the step data-driven, don't add per-item selectors. Update sungen if still unfiltered |
+| strict mode violation on a filtered list step whose value is a PREFIX of sibling texts (e.g. `1:00` also inside `11:00`) | The `hasText` filter matches by SUBSTRING by default (case-insensitive, like Playwright), so several members match | Add `exact: true` to the selector YAML entry — it anchors the filter to the full text and is honored for `type: locator` entries too |
 | Timeout / not found | Element doesn't exist or name wrong | Re-snapshot → copy exact accessible name. Check iframe/dialog scope |
 | Element is not an input | Wrong element type targeted | Change `type` or `value` to match actual element |
 | not a select | Custom dropdown, not native `<select>` | Set the widget variant: `variant: radix-select`/`antd-select` (built-in recipes), a custom recipe name from `qa/app.yaml`, or project-wide `widgets.select` in `qa/app.yaml` |
@@ -86,7 +87,7 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 
 | Code | Meaning | Fix |
 |---|---|---|
-| `SG-W001` | Step matched no pattern — compiled to a no-op `// TODO` (the test runs weaker than it reads) | Rephrase to a documented pattern (`sungen-gherkin-syntax`) or tag `@manual` with a reason |
+| `SG-W001` | Step matched no pattern — sungen has no step form for the sentence. Compiles to `throw new Error("[sungen] …")` naming the step (it emitted a no-op `// TODO` before the unsupported-step gate, which let the scenario PASS asserting nothing) | Rephrase to a documented pattern (`sungen-gherkin-syntax`) or tag `@manual` with a reason. There is no silent fallback — the test goes red until one of those two is done |
 | `SG-W002` | A step's `{{value}}` was parsed but never used in the generated code | The step form isn't the one you think — check the pattern's exact syntax |
 | `SG-W003` | `{ name }` filter defaulted from the Gherkin reference on a name-from-content role (toast/alert/status) | Add explicit `name:` or opt out with `name: null` |
 | `SG-W005` | `qa/app.yaml` unknown key / unknown preset / unparseable | Fix the key, or `extends: native\|radix\|antd` |
@@ -95,14 +96,23 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W008` | `@manual` scenario incomplete in either direction: (a) HAS Gherkin steps but NO `Then` — a dangling `When` is invalid Gherkin, comments can NOT substitute; (b) documentation-style (NO steps) but its comments lack numbered action lines and/or a labeled oracle line — prose paragraphs / rationale-only comments export EMPTY Steps + Expected cells | Two valid shapes only: complete the Gherkin with a `Then`, or write the FULL procedure in the `# Tester verifies:` block as NUMBERED lines — action steps first (`1. <action>`), then labeled `Observable:`/`Oracle:`/`Expected:` lines (the number is what fills Steps, the label is what fills Expected results) |
 | `SG-W009` | test-data references `${QA_<NAME>}` (a SECRET env ref) but the name is declared in neither `.env.qa` nor `.env.qa.example` — the test throws "environment variable not set" the moment the key is used. (Only the `${QA_*}` shape is checked; any other `${...}` is literal data and never flagged.) | Add `QA_<NAME>=<value>` to `.env.qa` (gitignored) and list the NAME in `.env.qa.example` (the committed checklist). See `qa/TEST-DATA-GUIDE.md` |
 | `SG-W010` | A row step's `[Ref]` looks POSITIONAL (`First…`/`Last…`/`Top…`/`nth`) but has no selectors.yaml entry — the label is display-only, so the step checks existence ANYWHERE in the table; an ordering/sort-stability rule would pass even when the row moved | Declare the row in selectors.yaml (a `type: locator` value RELATIVE to the table, e.g. `first contact row:` → `value: 'tbody tr:first-child'`) — the step then asserts `toContainText` on that exact row. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
-| `SG-W011` | A storage assertion written as `expect … in local/session storage` — `expect` steps only read `{{response}}` refs, so this compiles to a silent no-op | Rewrite using the supported grammar: `User see [KEY] in local storage exists/…` |
+| `SG-W011` | A storage assertion written as `expect … in local/session storage` — `expect` steps only read `{{response}}` refs, so this matches no pattern. Compiles to a `throw` (was a silent no-op) | Rewrite using the supported grammar: `User see [KEY] in local storage exists/…` |
 | `SG-W012` | A mock-install step written AFTER a navigation step in the same block — `page.route()` registered after `goto()` misses every request fired during page load | Move the mock-install step before the navigation, or into `Background` |
 | `SG-W013` | A page assertion (`see [X] page` / `is on [X] page`) whose `[Ref]` has no `type: page` selector entry (or collides with a non-page entry) — the step falls back to the feature's own path (or `/<ref>/`) instead of `X`'s real URL, so the anchored assertion can never pass | Declare a `type: page` entry for `[Ref]` with its real URL; if the key collides with another type, disambiguate with a `--type` suffix (`sungen-selector-keys` § Collision rule) |
 | `SG-W014` | `[X] page with {{v}}` where `{{v}}`'s base test-data value carries no query and no fragment — the step checks the PATH only, asserting less than it reads as | Informational — pass a value like `?q=…` if you meant to assert a query, or drop `with {{v}}` for a bare page |
+| `SG-W015` | `see [X] card/item with {{n}}` where `{{n}}`'s test-data value is a **bare number** — this compiles to a TEXT assertion (`toHaveText('3')`), NOT a count. An author reaching for "3 cards are shown" gets an assertion that can only pass if the card's TEXT is literally the digit: a wrong test with no error. Scoped to container-ish element types (`card`/`item`/`option` + plurals); a text element asserting a numeric readout (`[Row Quantity] text with 4`) stays silent | For a COUNT use a form that has count semantics: `see [Ref] row with {{n}}` / `see [T] table with {{n}}`, or a list `should have count`. If the number really is the element's text, assert it on a **text/label** element instead |
 | `SG-E020` | A step matched a pattern, but the **active adapter ships no template** for it (e.g. a web-only step compiled under `platform: mobile`). The feature file still generates — that one step compiles to `throw new Error("[sungen] …")` naming the step, feature, pattern, template and adapter, so the failure is loud and traceable rather than a crashed build | Rephrase to a step the target adapter actually ships (see `sungen-gherkin-syntax` Platform Support section / `sungen-mobile-gestures`), or tag the scenario `@manual` with the platform reason |
+| `SG-E021` | The step carries a trailing **state clause** (`… is hidden`) that the pattern which matched it does not assert — the clause would be SILENTLY DROPPED. Worst shape in this table: it does not weaken an assertion, it can INVERT one. `see [X] page is hidden` matched `page-assertion` (priority 13) ahead of `is-hidden` (11), so the step compiled to `toHaveURL(...)` — asserting the page IS displayed, and passing. Also fires on `wait for [X] is checked` (a wait honours only `hidden`/`visible`/`disabled`/`enabled`; everything else silently fell back to `visible`) and on `row`/`column in [T] table … is <state>` for any state but `hidden` | Move the state onto the element that has it: `Then User see [X] checkbox is checked`. For a page, assert the page you expect (`Then User see [Other] page`) or a marker element (`Then User see [Banner] is hidden`). If sungen cannot express the check, tag the scenario `@manual`. The diagnostic names the pattern that swallowed the clause — that name tells you which form you actually hit |
 | `SG-W020` | The matched pattern **declares `platforms`** (today: `@mock`) and the active platform isn't among them. Caught before template lookup, so the diagnostic can name the native alternative directly | Drop `@mock` from a mobile unit (there is no Mock Driver on Appium) — use `@api`/`@query` or a `@manual` note instead |
 | `SG-W021` | `use dialog` / `User is on [X] dialog` scope under the **mobile** adapter — the scope is recorded but no Appium template reads `inDialog`, so every following step resolves against the whole screen, not just the dialog | Don't rely on `scope: dialog`/`use dialog` for disambiguation on mobile — give the element inside the dialog its own unique accessibility-id/testid instead |
 | `SG-W022` | `Then User see [X] page` under the **mobile** adapter — a native app has no URL, so the step compiles to a bare COMMENT: it reads as an assertion, checks nothing, and the scenario passes whatever is on screen. Worse than a hard failure, because nothing ever goes red. (Its `is on [X] page` twin throws via `route-assertion`; `Given User is on [X] page` is the app-LAUNCH directive and correctly emits nothing) | Assert something actually on the screen — `Then User see [Some Header] text` / a screen-marker accessibility-id — instead of a page/URL check, or tag the scenario `@manual` |
+| `SG-W023` | A mobile **setup** step that emitted NO executable code, so a declared PRECONDITION is never established. `Given the user is logged out` matches `user-not-logged-in` → the `clear-auth` template, which on Appium is a bare COMMENT: mobile auth lives in the keychain/prefs, not in cookies, so no per-step action can clear it. The scenario then runs against whatever the PREVIOUS scenario left signed in and passes regardless — the same false-pass class as `SG-W022`, arriving through setup instead of assertion. Deliberately NOT a `throw` (an unestablished precondition weakens setup, it does not INVERT an assertion) | Declare a feature-level reset tier — `@reset:data` on the Feature — so each scenario starts from a wiped data layer; app state is reset in the `beforeEach` hook, not mid-scenario by a step. For BACKEND state (`database is empty`) the remedy is different: reset through a test API/script, or bind a `@query:` precondition, the same way the web adapter has to |
+| `SG-W024` | Two or more scenarios in one feature **share a name** and at least ONE carries a `@reset:` tag. The generated per-scenario tier lookup is keyed on the scenario NAME (a `@cases` title is built at runtime, so no compile-time key can match the rendered title), so every same-named scenario resolves to the SAME tier — including one that declared none, which then silently runs at its namesake's tier: a `@reset:none` chain broken, or a reinstall nobody asked for. Counted over EVERY scenario rather than the tagged subset, because the untagged twin is the one that gets the wrong tier and has no tag to be counted by | **Rename** the scenarios so each title is unique. Reported rather than resolved by precedence on purpose — two tests genuinely sharing one title cannot be told apart by a name-keyed lookup, so a rename is the only honest fix (silently picking a winner would be the same silent-discard shape as `SG-W021`) |
+| `SG-E022` | The **generated spec file itself** is not parseable JS/TS, so NOTHING in it runs — Playwright reports one `SyntaxError` and every scenario in the unit is lost. A compiler self-check (`@babel/parser`) on the emitted code, added after a field report where the runtime-data marker post-processor mis-paired quote delimiters across two literals and the user only found out at `npx playwright test`. Reported, never thrown — the file is still written so you keep the artifact to inspect. **Unlike every other code in this table this one blames the COMPILER, not your `.feature`** | Nothing to fix in the Gherkin — this should be impossible. **Report it** with the `.feature` (and the step) the file was generated from, attaching the unparseable `.spec.ts`. Check first that you are running the project-local compiler (`npx sungen`), not an older global one |
+| `SG-E023` | The step carries an **assertion clause** (`matches "…"`, `contains`, `has text`) but the generated code is a BARE VISIBILITY check — the clause was swallowed by a catch-all and the test would pass whatever the element says. The sibling of `SG-E021`, for the clauses that are not states: `SG-E021` closed the state case declaratively, but a dropped `matches`/`contains`/`has text` still slid through (reproduced live: a `matches "<format>"` step compiled by an older sungen lost the assertion entirely, emitted no warning, and left a `toBeVisible()` that passed whatever the label said). Four separate defects arrived this way, so the step now compiles to a runtime `throw`. Deliberately narrow — fires only on the bare-visibility shape, so a pattern that genuinely consumed the clause (`is-hidden`, `contains`, `matches-format`, the state family, or a `filter({ hasText })` on a list member) is untouched | Either the phrasing is not the supported one for that clause — check the exact form in `sungen-gherkin-syntax` — or this sungen predates the step: verify you are running the project-local compiler (`npx sungen`), not an older global one |
+| `SG-E024` | A mobile **app-lifecycle** step (`User restart the app` / `User reinstall the app`) in a feature that declares no `Path:` app id. The lifecycle templates resolve the target app through `__resolveAppId()`, a helper the appium test-file template emits ONLY when the id is present, so the spec used to compile clean and then die at runtime with `ReferenceError: __resolveAppId is not defined` — taking the WHOLE spec down, not the one step, because the failure lands in a before hook. (Field case: a mobile unit scaffolded with the nav recipe in `--path` instead of `--reach`, so `Path` never carried an app id.) Now refused at compile time as a `throw` naming the missing line | Add the app id under the `Feature` line: `Path: com.example.app/.MainActivity \| com.example.app`. For a mobile unit `--path` carries the **APP ID** and `--reach` carries the navigation recipe — if the nav recipe ended up in `--path`, that is the mistake |
+
+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` and `SG-E024` additionally compile the offending step to a runtime `throw`** — 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`
 
@@ -123,7 +133,8 @@ The scenario uses a SECRET test-data key whose `QA_*` variable is missing in thi
 ### Assertion type rule
 
 Sungen picks assertion based on element type:
-- **Input** (`field`, `textarea`, `search`, `dropdown`, `slider`) → `toHaveValue()`
+- **Input** (`field`, `textarea`, `search`, `slider`) → `toHaveValue()`
+- **Dropdown** (`dropdown`, `select`, `combobox`) → runtime tag probe: `toHaveValue()` on a native `<select>`/input, `toHaveText()` on a `<button role="combobox">` trigger (Radix/shadcn, MUI). Pin one branch with `variant: native` or an `assertValue` recipe in `qa/app.yaml`.
 - **Text** (everything else: `message`, `heading`, `label`, `row`) → `toHaveText()`
 - **Partial** (`contains` keyword) → `toContainText()`