@sun-asterisk/sungen 3.2.18 → 3.2.19

package/src/harness/flow-check.ts

@@ -11,6 +11,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { featureFilesFor } from './unit-paths';
 import { loadScenarios } from './parse';
 import { parseScenarios } from './capability-plan';
 import { readTextFile } from './read-text';
@@ -29,8 +30,9 @@ export interface FlowCheckReport {
 function listDirs(p: string): string[] {
   return fs.existsSync(p) ? fs.readdirSync(p, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) : [];
 }
-function featurePath(base: string, kind: 'screens' | 'flows', name: string): string {
-  return path.join(base, 'qa', kind, name, 'features', `${name}.feature`);
+/** Every `.feature` of the unit — a unit is a directory, so a sub-feature counts too. */
+function featurePaths(base: string, kind: 'screens' | 'flows', name: string): string[] {
+  return featureFilesFor(path.join(base, 'qa', kind, name), name);
 }
 function featureTags(fp: string): string[] {
   if (!fs.existsSync(fp)) return [];
@@ -57,7 +59,7 @@ export interface FlowScenario { flow: string; name: string; haystack: string; de
 export function loadFlowScenarios(cwd: string): FlowScenario[] {
   const out: FlowScenario[] = [];
   for (const f of listDirs(path.join(cwd, 'qa', 'flows'))) {
-    for (const s of loadScenarios(featurePath(cwd, 'flows', f))) {
+    for (const s of featurePaths(cwd, 'flows', f).flatMap(loadScenarios)) {
       out.push({ flow: f, name: s.name, haystack: s.haystack, deep: s.hasDataAssertion });
     }
   }
@@ -74,7 +76,7 @@ export function buildFlowCheck(cwd: string, onlyFlow?: string): FlowCheckReport
   // A. Deferral integrity (screens).
   const deferrals: Deferral[] = [];
   for (const sc of screens) {
-    for (const s of parseScenarios(featurePath(cwd, 'screens', sc))) {
+    for (const s of featurePaths(cwd, 'screens', sc).flatMap(parseScenarios)) {
       // A deferral is the first-class `@deferred:flow` tag (H6) OR the legacy `@manual` + a
       // "deferred to a flow" comment (back-compat). Either marks a cross-screen case owned by a flow.
       const isDeferral = s.deferredToFlow || (s.manual && /deferred to a flow/i.test(s.reason));
@@ -98,9 +100,9 @@ export function buildFlowCheck(cwd: string, onlyFlow?: string): FlowCheckReport
   // B. Run-test contract (per flow).
   const contracts: Contract[] = [];
   for (const f of flows) {
-    const fp = featurePath(cwd, 'flows', f);
-    const parallel = featureTags(fp).some((t) => /^@parallel$/i.test(t));
-    const scs = loadScenarios(fp);
+    const fps = featurePaths(cwd, 'flows', f);
+    const parallel = fps.flatMap(featureTags).some((t) => /^@parallel$/i.test(t));
+    const scs = fps.flatMap(loadScenarios);
     let cartStateCount = 0;
     for (const s of scs) {
       const h = s.haystack;

package/src/harness/flow-plan.ts

@@ -9,6 +9,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { featureFilesFor } from './unit-paths';
 import { parse as parseYaml } from 'yaml';
 import { MANUAL_REASONS, inferReasonCode } from './capability-plan';
 import { buildFlowCheck, Contract } from './flow-check';
@@ -78,9 +79,9 @@ export interface FlowPlan {
 }
 
 export function buildFlowPlan(cwd: string, flow: string): FlowPlan {
-  const featurePath = path.join(cwd, 'qa', 'flows', flow, 'features', `${flow}.feature`);
-  const selectorsPath = path.join(cwd, 'qa', 'flows', flow, 'selectors', `${flow}.yaml`);
-  const scenarios = parseFlowScenarios(featurePath);
+  const flowDir = path.join(cwd, 'qa', 'flows', flow);
+  const selectorsPath = path.join(flowDir, 'selectors', `${flow}.yaml`);
+  const scenarios = featureFilesFor(flowDir, flow).flatMap(parseFlowScenarios);
   const keys = selectorKeys(selectorsPath);
 
   // Legs = distinct screen namespaces.

package/src/harness/manifest.ts

@@ -11,7 +11,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { createHash } from 'crypto';
-import { featureBasename, reportSlug } from './unit-paths';
+import { featureFilesFor, reportSlug } from './unit-paths';
 import { readTextFile } from './read-text';
 
 export interface SpecSection { name: string; hash: string }
@@ -99,13 +99,13 @@ function parseFeatureSections(featurePath: string): { scenario: string; vpCode?:
 
 export function buildManifest(screenDir: string, screenName: string): Manifest {
   const specPath = path.join(screenDir, 'requirements', 'spec.md');
-  const featurePath = path.join(screenDir, 'features', `${featureBasename(screenName)}.feature`);
+  const featureFiles = featureFilesFor(screenDir, screenName);
   const specSections = parseSpecSections(specPath);
   const specMap: Record<string, string> = {};
   for (const s of specSections) specMap[s.name] = s.hash;
 
   const specNames = Object.keys(specMap);
-  const featScenarios = parseFeatureSections(featurePath);
+  const featScenarios = featureFiles.flatMap(parseFeatureSections);
   const entries: ManifestEntry[] = featScenarios.map((f) => {
     const matched = matchSection(f.section, specNames);
     return {

package/src/harness/parse.ts

@@ -8,6 +8,7 @@
 import * as fs from 'fs';
 import { GherkinParser, ParsedScenario, ParsedStep } from '../generators/gherkin-parser';
 import { readTextFile } from './read-text';
+import { featureFilesFor } from './unit-paths';
 
 export type Priority = 'high' | 'normal' | 'low' | 'unknown';
 
@@ -175,7 +176,12 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
 
     if (last === 'Then') {
       thenCount++;
-      if (/\{\{|contains|match data|toHaveText/i.test(step.text)) hasData = true;
+      // Storage assertions count as data-bearing: 4 of the 5 shapes carry no {{ref}}
+      // (`exists`, `does not exist`, `is not empty`, `key matching "…"`), yet they
+      // assert persisted state — without this they'd be scored `shallow`, penalizing
+      // exactly the checks the review encourages. `tab order` is a STRUCTURAL
+      // assertion (a data table of focus stops) with the same no-{{ref}} property.
+      if (/\{\{|contains|match data|toHaveText|in (local|session) storage|tab order/i.test(step.text)) hasData = true;
     }
   }
 
@@ -211,3 +217,24 @@ export function loadScenarios(featurePath: string): ScenarioInfo[] {
     .filter((s) => !s.stepsName && !s.hookType) // skip @steps/@hook blocks
     .map(classifyScenario);
 }
+
+/**
+ * Scenarios of a WHOLE unit — every `.feature` in its features/ directory, not just the
+ * canonical one. Sub-features created by `add --feature` used to be invisible to every
+ * sensor; the score they produced was a subset presented as the whole.
+ */
+export function loadUnitScenarios(unitDir: string, unit: string): ScenarioInfo[] {
+  return featureFilesFor(unitDir, unit).flatMap(loadScenarios);
+}
+
+/**
+ * Raw Gherkin of a WHOLE unit, concatenated in `featureFilesFor` order — the input for the
+ * text-level sensors (isolation risk, serial cascade, manual oracle, …). Missing files
+ * contribute nothing, so a unit with no features yields '' exactly as before.
+ */
+export function readUnitFeatureText(unitDir: string, unit: string): string {
+  return featureFilesFor(unitDir, unit)
+    .filter((p) => fs.existsSync(p))
+    .map((p) => readTextFile(p))
+    .join('\n');
+}

package/src/harness/script-check.ts

@@ -15,8 +15,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { loadScenarios, ScenarioInfo } from './parse';
-import { featureBasename } from './unit-paths';
+import { loadUnitScenarios, ScenarioInfo } from './parse';
+import { featureFilesFor } from './unit-paths';
 import { readTextFile } from './read-text';
 
 export interface ScriptCheckResult {
@@ -120,7 +120,12 @@ function specSubdir(dir: string, name: string, kind: UnitKind): string {
   return kind === 'flow' ? path.join(dir, 'flows', name) : kind === 'api' ? path.join(dir, 'api', name) : path.join(dir, name);
 }
 
-function findSpec(dir: string, name: string, kind: UnitKind): string | null {
+/**
+ * EVERY compiled spec of the unit. A unit compiles to one `.spec.ts` per `.feature`, so
+ * taking only the first hit checked a multi-feature screen against a fraction of its own
+ * compiled output — every sub-feature scenario then read as MISSING in spec.
+ */
+function findSpecs(dir: string, name: string, kind: UnitKind): string[] {
   // Screens compile to  <dir>/<name>/<feature>.spec.ts
   // Flows   compile to  <dir>/flows/<name>/<feature>.spec.ts
   // Api     compile to  <dir>/api/<name>/<feature>.spec.ts
@@ -137,37 +142,45 @@ function findSpec(dir: string, name: string, kind: UnitKind): string | null {
     }
   };
   const scoped = specSubdir(dir, name, kind);
-  if (!fs.existsSync(scoped)) return null; // no spec for this target (e.g. not compiled yet)
+  if (!fs.existsSync(scoped)) return []; // no spec for this target (e.g. not compiled yet)
   walk(scoped);
-  return hits[0] ?? null;
+  return hits.sort((a, b) => a.localeCompare(b, 'en'));
 }
 
 export async function runScriptCheck(screenDir: string, screenName: string, kind: UnitKind): Promise<ScriptCheckResult> {
-  const featurePath = path.join(screenDir, 'features', `${featureBasename(screenName)}.feature`);
-  const scenarios = loadScenarios(featurePath);
+  const featureFiles = featureFilesFor(screenDir, screenName);
+  const scenarios = loadUnitScenarios(screenDir, screenName);
   const automated = scenarios.filter((s) => !s.manual);
   const manual = scenarios.filter((s) => s.manual);
 
-  const committedSpec = findSpec(path.join(process.cwd(), 'specs', 'generated'), screenName, kind);
+  const committedSpecs = findSpecs(path.join(process.cwd(), 'specs', 'generated'), screenName, kind);
+  // Representative path for the report; the checks below read ALL of them.
+  const committedSpec = committedSpecs[0] ?? null;
 
   const findings: string[] = [];
   let specTitles: string[] = [];
   let specSrc = '';
   if (committedSpec) {
-    specSrc = readTextFile(committedSpec);
-    specTitles = extractTestTitles(specSrc);
+    specSrc = committedSpecs.map((p) => readTextFile(p)).join('\n');
+    specTitles = committedSpecs.flatMap((p) => extractTestTitles(readTextFile(p)));
   } else {
     findings.push('No generated spec found under specs/generated/ — run `sungen generate` / `/sungen:run-test` first.');
   }
 
   // A. Structural 1:1
-  // A @cases scenario emits ONE source test() inside a per-row loop, titled
-  // `<name> — ${__row.__label}` — match that literal title, not the bare name.
-  const expectedTitle = (s: ScenarioInfo) => (s.casesDataset ? `${s.name} — ${'${'}__row.__label}` : s.name);
-  const specTitleSet = new Set(specTitles);
-  const expectedSet = new Set(automated.map(expectedTitle));
-  const missingInSpec = automated.filter((s) => !specTitleSet.has(expectedTitle(s))).map((s) => s.name);
-  const extraInSpec = specTitles.filter((t) => !expectedSet.has(t));
+  // A @cases scenario emits ONE source test() inside a per-row loop. Its title
+  // appears in the spec as `'<name> — ' + __row.__label` (CONCAT — what
+  // scenario.hbs emits today; the extracted literal is `<name> —`) or as the
+  // legacy template form `<name> — ${__row.__label}`. This check used to expect
+  // ONLY the template form, so on the current codegen every @cases scenario was
+  // reported MISSING (+ its test EXTRA) despite compiling and running fine.
+  // Canonicalize the extracted title to the bare scenario name so both shapes
+  // (and plain titles) compare on the same footing.
+  const canonSpecTitle = (t: string) => t.replace(/\s*—(\s*\$\{__row\.__label\})?$/, '');
+  const specTitleSet = new Set(specTitles.map(canonSpecTitle));
+  const expectedSet = new Set(automated.map((s) => s.name));
+  const missingInSpec = automated.filter((s) => !specTitleSet.has(s.name)).map((s) => s.name);
+  const extraInSpec = specTitles.filter((t) => !expectedSet.has(canonSpecTitle(t)));
   const countMatch = committedSpec ? automated.length === specTitles.length : false;
   if (committedSpec && !countMatch) {
     findings.push(`Count mismatch: ${automated.length} automated scenarios vs ${specTitles.length} test() blocks.`);
@@ -192,25 +205,32 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
       const gen = kind === 'api'
         ? new CodeGenerator({ framework, runtimeData: true })
         : new CodeGenerator({ framework, screenName, runtimeData: true, flowMode: kind === 'flow' });
-      await gen.generateAllTests(qaSourceDir, tmp, [featurePath]);
-      const fresh = findSpec(tmp, screenName, kind);
-      if (fresh) {
-        const a = normalize(specSrc);
+      await gen.generateAllTests(qaSourceDir, tmp, featureFiles);
+      // Pair each committed spec with its regenerated twin by filename — one `.feature`
+      // compiles to one `.spec.ts`, so a multi-feature unit has several of each.
+      const freshByName = new Map(findSpecs(tmp, screenName, kind).map((p) => [path.basename(p), p]));
+      const multi = committedSpecs.length > 1;
+      for (const committed of committedSpecs) {
+        const fresh = freshByName.get(path.basename(committed));
+        if (!fresh) continue;
+        const a = normalize(readTextFile(committed));
         const b = normalize(readTextFile(fresh));
-        if (a !== b) {
-          drift = 'drift';
-          // collect a few differing lines
-          const al = a.split('\n'), bl = b.split('\n');
-          const max = Math.max(al.length, bl.length);
-          for (let i = 0, shown = 0; i < max && shown < 6; i++) {
-            if (al[i] !== bl[i]) {
-              driftHunks.push(`  L${i + 1}\n    committed: ${(al[i] ?? '∅').trim().slice(0, 100)}\n    expected : ${(bl[i] ?? '∅').trim().slice(0, 100)}`);
-              shown++;
-            }
+        if (a === b) continue;
+        drift = 'drift';
+        // collect a few differing lines
+        const al = a.split('\n'), bl = b.split('\n');
+        const max = Math.max(al.length, bl.length);
+        const where = multi ? `${path.basename(committed)} ` : '';
+        for (let i = 0, shown = 0; i < max && shown < 6 && driftHunks.length < 6; i++) {
+          if (al[i] !== bl[i]) {
+            driftHunks.push(`  ${where}L${i + 1}\n    committed: ${(al[i] ?? '∅').trim().slice(0, 100)}\n    expected : ${(bl[i] ?? '∅').trim().slice(0, 100)}`);
+            shown++;
           }
-          findings.push('DRIFT: committed spec differs from a fresh regenerate → spec was hand-edited or the .feature changed without `sungen generate`. The test code no longer reflects the Gherkin.');
         }
       }
+      if (drift === 'drift') {
+        findings.push('DRIFT: committed spec differs from a fresh regenerate → spec was hand-edited or the .feature changed without `sungen generate`. The test code no longer reflects the Gherkin.');
+      }
       fs.rmSync(tmp, { recursive: true, force: true });
     } catch (e) {
       findings.push(`Drift check skipped (regenerate failed): ${e instanceof Error ? e.message : e}`);

package/src/harness/secret-scan.ts

@@ -37,15 +37,19 @@ function scanText(text: string, file: string): SecretHit[] {
   return hits;
 }
 
-/** Scan a screen/flow dir's test-data/*.yaml for likely real secrets. */
+/** Scan a unit dir's committed yaml sinks for likely real secrets: test-data/*.yaml,
+ *  mock/*.yaml (mock response bodies are a credential magnet — pasted DevTools
+ *  responses carry real tokens), and api/*.yaml (endpoint catalogs carry headers). */
 export function scanTestDataSecrets(baseDir: string): SecretHit[] {
-  const tdDir = path.join(baseDir, 'test-data');
-  if (!fs.existsSync(tdDir)) return [];
   const hits: SecretHit[] = [];
-  for (const f of fs.readdirSync(tdDir)) {
-    if (!/\.ya?ml$/i.test(f)) continue;
-    const p = path.join(tdDir, f);
-    try { hits.push(...scanText(fs.readFileSync(p, 'utf-8'), path.join('test-data', f))); } catch { /* ignore */ }
+  for (const sub of ['test-data', 'mock', 'api']) {
+    const dir = path.join(baseDir, sub);
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir)) {
+      if (!/\.ya?ml$/i.test(f)) continue;
+      const p = path.join(dir, f);
+      try { hits.push(...scanText(fs.readFileSync(p, 'utf-8'), path.join(sub, f))); } catch { /* ignore */ }
+    }
   }
   return hits;
 }

package/src/harness/sensors.ts

@@ -279,8 +279,12 @@ export interface AutomatableManualResult {
 
 // Genuine-judgment markers (M6/M8/M9 territory): visual/responsive/a11y/mock/network/
 // external/empty-state — these legitimately stay @manual (or need a future driver).
+// `focus order` is no longer a judgment marker — `Then User see tab order:` automates
+// it deterministically. `keyboard` is NARROWED (keyboard-only navigation / focus traps
+// still need a human or AT), not removed: a scenario merely mentioning the keyboard is
+// automatable, a keyboard-ONLY audit is not.
 const JUDGMENT_MARKER =
-  /\b(visual|responsive|layout|breakpoint|mobile|tablet|viewport|accessib|a11y|keyboard|screen reader|focus order|\baria\b|empty[- ]?(state|product|list|category|cart)|no[- ]?result|missing (image|product|data)|placeholder|fallback|slow|failing|offline|network|loading|spinner|external|new tab|video tutorial|email|mailbox|download|payment gateway|exploratory|not worth)\b/;
+  /\b(visual|responsive|layout|breakpoint|mobile|tablet|viewport|accessib|a11y|keyboard[- ]only|keyboard trap|screen reader|\baria\b|empty[- ]?(state|product|list|category|cart)|no[- ]?result|missing (image|product|data)|placeholder|fallback|slow|failing|offline|network|loading|spinner|external|new tab|video tutorial|email|mailbox|download|payment gateway|exploratory|not worth)\b/;
 
 /**
  * Automatable-@manual (TQ-2) — a `@manual` scenario whose steps are fully DSL-expressible
@@ -637,7 +641,10 @@ const CLAIM_RULES: ClaimRule[] = [
   {
     claim: 'independent/separate',
     title: /\b(independent|separate|isolat(ed|es)|per[- ]tab|two tabs|each tab)\b/,
-    proof: /\bcontext\b|tab a|tab b|second (tab|context)/,
+    // A storage `does not exist` check on the OTHER tenant's key proves isolation
+    // ("the other shop's token is not exposed"). Only the absence shape counts — a
+    // positive `exists` check looks the same whether or not the claim holds.
+    proof: /\bcontext\b|tab a|tab b|second (tab|context)|does not exist/,
     need: 'a multi-context proof (tab A vs tab B)',
     hint: 'independence across tabs/contexts is rarely DSL-expressible — mark @manual with a clear setup/action/oracle.',
     severity: 'warn',
@@ -653,7 +660,7 @@ const CLAIM_RULES: ClaimRule[] = [
   {
     claim: 'announces/aria',
     title: /\b(announce[sd]?|aria|screen[- ]reader|programmatically associated)\b/,
-    proof: /aria|role|@manual|describedby|is focused/,
+    proof: /aria|role|@manual|describedby|is focused|tab order/,
     need: 'an aria/role assertion (or @manual with a screen-reader oracle)',
     hint: 'ARIA announcement is usually not DSL-expressible — assert aria attributes if possible, else @manual with an NVDA/VoiceOver oracle.',
     severity: 'warn',
@@ -668,7 +675,11 @@ const CLAIM_RULES: ClaimRule[] = [
     // authoritative recall layer for the residue this can't judge structurally.
     claim: 'negative-claim/absence',
     title: /(\bno\b|\bnot\b|n['’]t\b|\bnever\b|\bwithout\b|\bcannot\b|prevent|block|avoid|reject|disabl|\bdeny\b|denies|\bkhông\b|\bchưa\b)/i,
-    proof: /is hidden|are hidden|is empty|no longer|not complete|disabl|invalid|rejected|\berror\b|\bcount\b|row with \{\{|table with|\bremember\b|\bexactly\b|tohavecount/i,
+    // `does not exist` covers the storage-absence shape — the broad "any storage
+    // assertion" alternative would let a positive `exists` silence a negative claim.
+    // `tab order` proves "focus never lands on X"-style claims (the table enumerates
+    // exactly where focus goes).
+    proof: /is hidden|are hidden|is empty|no longer|not complete|disabl|invalid|rejected|\berror\b|\bcount\b|row with \{\{|table with|\bremember\b|\bexactly\b|tohavecount|does not exist|tab order/i,
     need: 'a proof of the ABSENCE — a contrast/empty/hidden/error/count assertion, or @manual with an oracle',
     hint: 'a negative claim ("no / not / không …") is not proven by a positive `see [X]` that looks the same whether or not the claim holds. Assert the contrast (state hidden/empty, error shown, count unchanged), or mark @manual.',
     severity: 'warn',

package/src/harness/trace.ts

@@ -13,7 +13,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { reportSlug } from './unit-paths';
+import { featureFilesFor, reportSlug } from './unit-paths';
 import { segmentRuns, latestRunEvents, LedgerEvent } from './ledger';
 import { readTextFile } from './read-text';
 
@@ -96,7 +96,7 @@ export function buildTrace(screenDir: string, screenName: string): TraceReport {
   const scRaw = readJson(path.join(process.cwd(), '.sungen', 'reports', `${reportSlug(screenName)}-script-check.json`));
   const drift = scRaw ? scRaw.drift : null;
 
-  const manual = parseManual(path.join(screenDir, 'features', `${screenName}.feature`));
+  const manual = featureFilesFor(screenDir, screenName).flatMap(parseManual);
 
   // Bottlenecks
   const bottlenecks: string[] = [];

package/src/harness/unit-paths.ts

@@ -1,14 +1,51 @@
 /**
  * Unit-path helpers (api-flow fix). A unit id may be a bare name (`orders`, `login`) or a nested
- * api-flow id (`flows/<flow>`). Two derivations the harness/CLI need:
+ * api-flow id (`flows/<flow>`). Three derivations the harness/CLI need:
  *  - featureBasename: the `.feature` filename — the LAST path segment (`flows/x` → `x`), so
  *    `<dir>/features/<basename>.feature` resolves (the bug: the full id looked for
  *    `features/flows/x.feature` → 0 scenarios).
+ *  - featureFilesFor: EVERY `.feature` file of the unit — a unit is a directory, not a file.
  *  - reportSlug: a flat key for `.sungen/reports/<slug>-*.json` + `.sungen/ledger/<slug>.jsonl`
  *    (`flows/x` → `flows-x`), so artifacts never nest under a `flows/` subdir and read/write agree.
- * Bare names (no slash) are unchanged by both → no regression for screens/flows/areas.
+ * Bare names (no slash) are unchanged by all three → no regression for screens/flows/areas.
  */
+import * as fs from 'fs';
 import * as path from 'path';
 
 export const featureBasename = (unit: string): string => path.basename(unit);
 export const reportSlug = (unit: string): string => unit.replace(/[\\/]+/g, '-');
+
+/**
+ * Every `.feature` file belonging to one unit, in a stable order.
+ *
+ * A unit is a DIRECTORY of features, not one file. `sungen add --screen x --feature y`
+ * scaffolds `x-y.feature` beside `x.feature`, and `--path` without `--feature` names the
+ * file after the URL segment — so `<unit>.feature` may be one of several, or absent
+ * entirely. `generate` and `delivery` have always enumerated the directory; the harness
+ * read the single canonical name and scored only that file, silently dropping every
+ * sub-feature from coverage/depth/traceability with no warning.
+ *
+ * Order: the canonical `<unit>.feature` first so report ordering stays put when a
+ * sub-feature is added later, then the rest alphabetically. Falls back to the canonical
+ * path when the directory is missing or empty, so callers keep the "file not found"
+ * behaviour (and error text) they already have.
+ */
+export function featureFilesFor(unitDir: string, unit: string): string[] {
+  const dir = path.join(unitDir, 'features');
+  const canonicalName = `${featureBasename(unit)}.feature`;
+  const canonical = path.join(dir, canonicalName);
+
+  let names: string[];
+  try {
+    names = fs.readdirSync(dir).filter((f) => f.endsWith('.feature'));
+  } catch {
+    return [canonical]; // no features/ dir — let the caller report the missing file
+  }
+  if (names.length === 0) return [canonical];
+
+  names.sort((a, b) => a.localeCompare(b, 'en'));
+  return [
+    ...names.filter((n) => n === canonicalName),
+    ...names.filter((n) => n !== canonicalName),
+  ].map((n) => path.join(dir, n));
+}

package/src/index.ts

@@ -20,6 +20,7 @@ export type { ResolvedAppProfile } from './generators/test-generator/app-profile
 export type { MappedStep } from './generators/test-generator/step-mapper';
 export type { ParsedStep } from './generators/gherkin-parser';
 export { getPathCode, inferPath, resolvePathVariables } from './generators/test-generator/utils/path-inference';
+export { LIST_MEMBER_ROLES } from './generators/test-generator/utils/selector-resolver';
 
 // --- Precondition-annotation override grammar (shared by the @query / @api driver codegen) ---
 export { parseQueryOverrides } from './harness/annotation-overrides';

package/src/orchestrator/screen-manager.ts

@@ -8,6 +8,7 @@ import * as path from 'path';
 import { chromium } from '@playwright/test';
 import { readCapabilities } from '../harness/capability';
 import { testDataHeader, ensureTestDataGuideFiles } from './test-data-guide';
+import { resolveWebBaseUrl } from '../exporters/env-qa';
 
 export interface ScreenOptions {
   name: string;
@@ -304,8 +305,12 @@ export class ScreenManager {
     if (!fs.existsSync(configPath)) return null;
 
     const content = fs.readFileSync(configPath, 'utf-8');
-    const match = content.match(/baseURL:\s*['"]([^'"]+)['"]/);
-    return match ? match[1] : null;
+    // Both config shapes: legacy literal and env-aware resolveBaseUrl('x') wrapper.
+    const match = content.match(/baseURL:\s*(?:resolveBaseUrl\(\s*)?['"]([^'"]+)['"]/);
+    if (!match) return null;
+    // SUNGEN_BASE_URL (shell > .env.qa.<SUNGEN_ENV> > .env.qa) overrides the static
+    // value — screenshots must capture the same host the tests will run against.
+    return resolveWebBaseUrl(this.cwd, match[1]);
   }
 
   private validateScreenName(name: string): void {

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

@@ -1,7 +1,7 @@
 ---
 name: dashboard
 description: "Build a single-file HTML dashboard with test cases + pass/fail results, history trends, compare runs, and CSV/XLSX export."
-argument-hint: "[screen-name...] (omit for all)"
+argument-hint: "[screen-name...] [--env <env>] (omit names for all)"
 order: 60
 claude-tools: "Bash, Read, AskUserQuestion"
 copilot-tools: "[read, execute, edit, vscode/askQuestions]"
@@ -16,6 +16,7 @@ You are a **QA Reporting Engineer**. Your job is to invoke the deterministic `su
 Parse **screens** from `$ARGUMENTS`:
 - If empty → CLI will include **all** screens and flows.
 - If provided → pass them through.
+- **`--env <env>`** — optional (accept `--locale` as an alias). Pass through as `sungen dashboard --env <env>`: the dashboard is built for that environment/locale only — it picks the `<name>-test-result.<env>.json` files, and Trends/Compare only see history snapshots of the same env (a dev run never blends into the uat trend line). Omit → the base environment.
 
 ## Steps
 

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

@@ -61,7 +61,7 @@ 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.
+- **`--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.
 - **`--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.

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

@@ -172,6 +172,8 @@ The CLI reads the **per-target result file first** (co-located with `.spec.ts`),
 | Test Environment | `playwright.config.ts` baseURL + project name |
 | Note | Error message + trace path (for failed tests) |
 
+**Runtime-secret redaction (all cells, all unit kinds):** a failed test's error message carries the RESOLVED `${QA_*}` credential (runtime substituted it before asserting), and cell content can too. The exporter builds a per-unit denylist — env vars referenced as `${QA_*}` in the unit's test data whose NAME looks sensitive (`QA_ADMIN_PASSWORD` yes; `QA_BASE_URL`, `QA_ADMIN_EMAIL` no) — resolving values from shell/CI env > `.env.qa.<SUNGEN_ENV>` > `.env.qa`, and erases every occurrence (`***`) from Note, dashboard errorMessage, Steps, Expected results and Test Data. Value-based only: fake demo values (`password123`), error-message strings (`Password is required`) and element names (`[Password]`) stay readable. If a sensitive ref can't be resolved while the run has failures, delivery prints a "redaction coverage incomplete" warning — set the variable in the env before exporting. `sungen delivery` also runs the same secret scan as `generate` and warns if test-data holds a literal token-shaped value.
+
 ---
 
 ## XLSX sheets — Overview + Auto / Manual split

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

@@ -62,7 +62,7 @@ User click [T] button and dismiss [Cancel] alert  # compiler registers the liste
 User click [OK | Cancel] alert                    # two-step form: must come BEFORE the trigger
 User fill [T] alert with {{v}}
 User see [message text] alert
-User press Escape key | Enter on [T] field
+User press Escape key | [Enter] key | Tab key 5 times | Enter on [T] field
 User wait for N seconds | [T] page
 User wait for [T] TYPE is visible | hidden | enabled | disabled     # ANY reference (v3.3)
 User wait for [T] TYPE with {{v}}                                    # until it shows the value
@@ -103,9 +103,15 @@ two content-filtered queries can hit different rows if the table re-renders in b
 # 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}}
 # 7. Count: User see [T] row with {{count}}
-# 8. Page: User see [T] page
+# 8. Page: User see [T] page | page with {{url}}   ← `with` also asserts the query string
 ```
 
+**Pattern 8 — assert the query, not just the path.** Bare `see [T] page` only checks the base path,
+so a search/filter test PASSES when the query string is wrong or gone entirely. When the URL carries
+state worth proving, pass it: `Then User see [Search] page with {{search_query}}` compiles to the
+path assertion PLUS `expect(page.url()).toContain(<value>)`. Same for `Then User is on [T] page with
+{{v}}`. A dynamic segment in the selector value (`/users/:id/profile`) wildcards to `[^/]+` on its own.
+
 ### Collection / all-card (P5)
 
 ```
@@ -142,6 +148,49 @@ first contact row:
 ```
 → compiles to `expect(table.locator('tbody tr:first-child')).toContainText(v)` — the exact row must hold the value — and still enters row scope for `[Col] column` checks.
 
+### Browser storage (web)
+
+```
+Then User see [KEY] in local storage exists
+Then User see [KEY] in local storage does not exist
+Then User see [KEY] in local storage is not empty
+Then User see [KEY] in local storage has length {{n}}
+Then User see key matching "PATTERN" in local storage      # regex over key names
+# same five forms with `session storage`
+```
+
+`[KEY]` is a **storage key, not a selector** — never add it to selectors.yaml. It may embed `{{vars}}`: `[{{exclusive_code}}_ACCESS_TOKEN]`. The check runs inside the browser and returns only a boolean, so a failure message never contains the stored value (safe for tokens). There is deliberately no `equals {{expected}}` form. ⚠️ `expect [KEY] in local storage …` is NOT valid (`expect` reads `{{response}}` refs only) — the compiler warns SG-W011.
+
+### Tab order (web only)
+
+```
+Then User see tab order:
+    | Ref |
+    | [Station Dropdown] |
+    | [Departure Date] |
+    | [Search Button] button |
+```
+
+Focuses row 1 (the pinned origin — there is no separate `focus [X]` step) and asserts it actually HOLDS focus (a non-focusable ref fails loudly), then presses Tab per following row and asserts it receives focus. Cell refs ARE selector references (resolved via selectors.yaml; optional element type after the ref). Requires the `| Ref |` header and ≥2 element rows — a missing header or single row is a compile error, never an empty pass. A mismatch reports the expected ref + the actual focused element (shadow-DOM-aware tag/role/name). Limitations: web only (no Appium); declare tab order OUTSIDE `use dialog`/frame scope (cell locators render page-rooted — put `scope: dialog` on the selector ENTRIES if the elements live in a dialog); focus traps / dynamic comboboxes / `tabindex=-1` reordering / WebKit differences may need `@manual` keyboard-only audits — those stay legitimate manuals.
+
+### Network mocking (optional Mock Driver — `sungen capability add mock`)
+
+```gherkin
+@mock
+Scenario: search shows the error state on server failure
+  Given [reservations-check-500] mock is active        # install a NAMED catalog entry
+  When User click [Search] button
+  Then User see [Error Toast] message
+  And User see [reservations-check-500] mock called {{n}} times   # exact count; "called 1 time" also valid
+```
+
+`[name]` is a **catalog reference, not a selector** — entries live in `qa/screens/<name>/mock/mocks.yaml` (`method`, `url` glob or `re:` regex, `status`, optional `headers`/`body`/`delay_ms`; a `"{{var}}"` body reads test-data at runtime). No inline `[GET /path]` forms. Rules:
+- **Fail-on-unmocked (default):** once a scenario has any mock, unmatched fetch/XHR requests FAIL the test (documents/assets still load). Opt out per scenario with `@mock:passthrough`.
+- **Mocks that must intercept page-load requests go in Background, BEFORE the navigation step** — installing after a navigation warns SG-W012 (load-time requests were not intercepted).
+- No `abort` entry (a network error is not a timeout) — simulate timeouts with a large `delay_ms`.
+- mocks.yaml is committed: credentials in bodies must be `${QA_*}` refs, never pasted DevTools responses (the secret scan covers `mock/*.yaml`).
+- Web only. Requires the driver: without it, `@mock` is a hard compile error pointing at `sungen capability add mock`.
+
 ### Database verification (optional Data Driver)
 
 Read-only DB-state checks. **Prefer named queries** — SQL lives in `qa/screens/<screen>/database/queries.yaml` (reviewed once, parameterized). Invoke with the `@query:<name>` annotation; it binds the result rows to `{{name}}`, then assert with `expect`:

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

@@ -55,6 +55,12 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
 1. **Confirm with the user**: *"Generate selectors from the live page via Playwright MCP now?"* — offer **Yes, scan live page** / **Skip (use existing selectors.yaml)** / **Cancel**.
 {{/cap}}
 2. **Collect references**: parse the `.feature` file for every `[Reference]` element + its type (e.g. `[Submit] button`, `[Email] field`). Deduplicate.
+
+   ⛔ **Non-selector bracket refs — never hunt the DOM for these, never write a selectors.yaml entry:**
+   - `[KEY] in local storage …` / `[KEY] in session storage …` — a **storage key**, checked via `page.evaluate`, not an element (the key may embed `{{vars}}`, e.g. `[{{code}}_ACCESS_TOKEN]`).
+   - Bracket refs consumed by other non-DOM step families (`@mock` route refs) follow the same rule: if the step's grammar does not target a UI element, the bracket content is NOT a selector.
+   Writing a fabricated entry for these breaks the real step (the pattern parses the bracket itself) and pollutes selectors.yaml.
+   ✅ **Tab-order table cells ARE selector refs** — each `| [Ref] |` row under `Then User see tab order:` resolves through selectors.yaml like any element (verify them once; they are the same refs the scenario's other steps use — don't double-count them as new elements).
 3. **Ensure page selector**: if missing, ask user for URL path and write it first.
 4. **Navigate**:
    - Read `baseURL` from `playwright.config.ts`.

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

@@ -254,6 +254,12 @@ success toast:
 
 Use this for every toast/alert/spinner content assertion. Do NOT fall back to `type: locator, value: '[role="status"]'` — `name: null` keeps role semantics.
 
+**List-member roles need no opt-out.** For `option`, `listitem` and `cell` the compiler never defaults
+the name at all — those name themselves from their content, and the value being asserted is already
+carried by `.filter({ hasText })`. Omit `name:` and the locator comes out as `getByRole('option')`.
+Declare `name:` only when the DOM really does expose an accessible name worth filtering on; an
+explicit one is always honoured.
+
 ### Types requiring YAML entry (no auto-infer)
 
 These types need explicit `selectors.yaml` entries: