@sun-asterisk/sungen 3.2.32 → 3.2.34-beta.1

package/src/exporters/matrix/types.ts

@@ -147,6 +147,11 @@ export interface CoverageVariant {
   fingerprint: string;
   /** Execution result, when the run report has one for this variant. */
   result?: PlaywrightResult;
+  /** A Manual variant's result as the tester recorded it in the previous workbook, carried
+   *  BEFORE rendering so every total, roll-up, the CSV and the CLI count it (#891). */
+  manualState?: VariantState;
+  /** The Executed Date the tester recorded with it (yyyy-mm-dd, or as typed). */
+  manualDate?: string;
 }
 
 export type ItemResult = 'passed' | 'failed' | 'blocked' | 'partial' | 'not_run' | 'na';
@@ -176,8 +181,12 @@ export interface DeliveryItem {
   /** Preconditions shared by EVERY variant (the intersection) — written once here. */
   precondition: string[];
   /** Leading trigger steps shared by every variant — written once here; each
-   *  variant renders only its remaining steps (`triggerDeltas`). */
+   *  variant renders only its remaining steps (`triggerDeltas`). When nothing is shared this
+   *  holds a generated "the action differs…" note instead, which is NOT a step. */
   trigger: string[];
+  /** How many of `trigger` are real steps hoisted from the variants (0 when it is only the
+   *  note) — the variants' steps are numbered from this + 1 (#848). */
+  sharedTriggerSteps: number;
   variants: CoverageVariant[];
   /** variant ref → its precondition lines that are not on the parent. */
   preconditionDeltas: Record<string, string[]>;
@@ -253,6 +262,9 @@ export interface MatrixModel {
    * the deliverable ships to the client.
    */
   secretValues: string[];
+  /** Who ran the suite and against what — fills Test Executor / Test Environment on rows that
+   *  ran (#850). Absent when the caller has no run context (gates-only paths). */
+  runEnv?: import('../run-environment').RunEnvironment;
 }
 
 /** Complexity warning threshold (rules draft Gate I; raised for compact grouping) — echoed in the manifest. */

package/src/exporters/matrix/wording.ts

@@ -13,6 +13,8 @@
  *   Action → action, Observable → expected, Oracle → verification method.
  */
 
+import { extractUnlabeledOracle, onlyPresenceAssertions } from '../manual-hybrid-oracle';
+
 /** A step that CAPTURES a runtime value: `User remember [X] text as {{var}}`. */
 export const RUNTIME_CAPTURE = /\bremember\b/i;
 
@@ -40,8 +42,25 @@ export function runtimeVarsOf(stepTexts: string[], tags: string[]): Set<string>
 }
 
 // `[Email] field` → `Email field` (the visible label + its element type).
+// Only the DSL's own refs: a `"quoted literal"` and a `{{token}}` are data, so their
+// brackets stay (#772) — `"[DRAFT] report"`, `{{q.rows[0].id}}`. Callers render BEFORE
+// substituting values, so a value's brackets (`^[A-Za-z]{3}`) never reach this.
+// A literal opens only where a word does not end: in free text (manual procedures) `5"`
+// is an inch mark, and two of them must not shield the `[Ref]` between them.
 function deRef(text: string): string {
-  return text.replace(/\[([^\]]+)\]/g, '$1');
+  return text.replace(/(?<![\p{L}\p{N}])"[^"]*"|\{\{[^}]*\}\}|\[([^\]]+)\]/gu, (m, ref?: string) => ref ?? m);
+}
+
+/**
+ * Finish a cell rendered with `{{tokens}}` still in it, once the values are substituted
+ * (#772: render first, substitute after, so deRef never sees a value). Keeps what
+ * `sentence()` did when values went in first: a leading value is capitalised, and a
+ * value that already ends a sentence does not gain a second mark (`value..`).
+ */
+export function afterSubstitution(text: string): string {
+  if (!text) return text;
+  const s = text.charAt(0).toUpperCase() + text.slice(1);
+  return s.replace(/([.!?…"])\.$/, '$1');
 }
 
 function sentence(text: string): string {
@@ -115,7 +134,15 @@ export function renderExpected(raw: string): string {
   if (RUNTIME_CAPTURE.test(raw) && /\bas\s+\{\{/.test(raw)) return renderAction(raw);
   let s = raw.trim().replace(/^(User|The user)\s+/i, '');
 
+  // `table match data:` rows (folded in by feature-parser, #771) are the EXPECTED VALUES —
+  // `[E2E-01] Q1` is data, not a ref — so only the table's own ref is de-ref'd (#772).
+  const md = s.match(/^sees? \[([^\]]+)\]\s*table match(?:es)? data: (.+)$/i);
+  if (md) return sentence(`The ${md[1]} table shows these rows: ${md[2]}`);
+
   const rules: Array<[RegExp, (m: RegExpMatchArray) => string]> = [
+    // tab order: (#771) row 1 is the focused origin, each later row is one Tab press —
+    // its cells ARE refs, so they are de-ref'd like any step's.
+    [/^sees? tab order: (.+)$/i, (m) => `Pressing Tab moves focus in this order: ${m[1]}`],
     // expect A is (not) B — comparing two captured values (order matters: "is not" first)
     [/^expects? (.+?) is not (.+)$/i, (m) => `${m[1]} differs from ${m[2]}`],
     [/^expects? (.+?) is (.+)$/i, (m) => `${m[1]} equals ${m[2]}`],
@@ -204,7 +231,7 @@ export interface ManualProcedure {
  * review feedback §10.2(3). Continuation lines append to the previous item;
  * pre-amble (rationale/header/dividers) is skipped.
  */
-export function classifyManualComments(comments: string[]): ManualProcedure {
+export function classifyManualComments(comments: string[], thenTexts: string[] = []): ManualProcedure {
   const out: ManualProcedure = { preconditions: [], actions: [], expected: [], verification: [] };
   let last: { list: string[]; idx: number } | null = null;
 
@@ -230,5 +257,12 @@ export function classifyManualComments(comments: string[]): ManualProcedure {
       last.list[last.idx] += ' ' + line;
     }
   }
+  // #810 — an oracle written as unlabelled `Tester verifies:` prose is still the oracle: with no
+  // labelled Observable line and no Then beyond presence (`thenTexts`), export it rather than fall
+  // back to a presence-placeholder Then. A real Then stays the oracle.
+  if (!out.expected.length && onlyPresenceAssertions(thenTexts)) {
+    const prose = extractUnlabeledOracle(comments);
+    if (prose) out.expected.push(prose);
+  }
   return out;
 }

package/src/exporters/playwright-report-parser.ts

@@ -161,6 +161,7 @@ export function loadPlaywrightReport(reportPath: string): Map<string, Playwright
       errorMessages: distinct.length > 0 ? distinct : undefined,
       tracePath: trace,
       projectName: test?.projectName,
+      attempts: results.length || undefined,
     });
   }
   return result;

package/src/exporters/run-environment.ts

@@ -0,0 +1,89 @@
+/**
+ * Who ran the tests, and against what — the Test Executor / Test Environment columns of every
+ * deliverable (legacy workbook, matrix workbook) and the dashboard.
+ *
+ * One module so the surfaces cannot drift: the matrix format shipped with both cells hard-coded
+ * blank on every Auto row while the legacy exporter filled them (#850).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { resolveWebBaseUrl } from './env-qa';
+import { statusToTestResult } from './playwright-report-parser';
+import { EnvironmentInfo, PlaywrightResult } from './types';
+
+/**
+ * The executor, most explicit source first: `SUNGEN_EXECUTOR` (a CI job names the person or
+ * pipeline that ran the suite — whoever runs `sungen delivery` there is not that person), then
+ * git user.name, then `CI_USER` / `USER`.
+ */
+export function resolveExecutor(cwd: string): string {
+  const explicit = process.env.SUNGEN_EXECUTOR?.trim();
+  if (explicit) return explicit;
+  try {
+    const gitUser = execSync('git config user.name', { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (gitUser) return gitUser;
+  } catch { /* not a git checkout, or no user.name */ }
+  return process.env.CI_USER || process.env.USER || '';
+}
+
+/** baseURL + browser project from playwright.config.ts, executor from {@link resolveExecutor}. */
+export function getEnvironment(cwd: string): EnvironmentInfo {
+  let baseURL = '';
+  let projectName = 'chromium';
+  const configPath = path.join(cwd, 'playwright.config.ts');
+  if (fs.existsSync(configPath)) {
+    const c = fs.readFileSync(configPath, 'utf-8');
+    // Every config shape sungen has scaffolded: the literal `baseURL: 'x'`, the env-aware
+    // `baseURL: resolveBaseUrl('x')`, and the older `baseURL: process.env.SUNGEN_BASE_URL || 'x'`
+    // (the quoted value is the static fallback in both wrappers).
+    const baseMatch = c.match(/baseURL:\s*(?:resolveBaseUrl\(\s*|process\.env\.\w+\s*\|\|\s*)?['"]([^'"]+)['"]/);
+    if (baseMatch) baseURL = baseMatch[1];
+    const projMatch = c.match(/name:\s*['"]([^'"]+)['"]/);
+    if (projMatch) projectName = projMatch[1];
+  }
+  // SUNGEN_BASE_URL (shell > .env.qa.<SUNGEN_ENV> > .env.qa) overrides the static
+  // value — the Test Environment column must show the host the run actually hit.
+  baseURL = resolveWebBaseUrl(cwd, baseURL);
+  return { baseURL, projectName, executor: resolveExecutor(cwd) };
+}
+
+/** `https://host/path (project)` — or, on mobile (no baseURL), the bare app id `(project)`. */
+export function formatEnv(baseURL: string, featurePath: string | undefined, projectName: string): string {
+  const base = (baseURL || '').replace(/\/+$/, '');
+  const p = (featurePath || '').replace(/^\/+/, '');
+  // Join with '/' only when there is a baseURL (web). For mobile baseURL is empty
+  // and `p` is an app id (e.g. com.kngroup.media.converter) — emit it bare, no '/'.
+  const url = base && p ? `${base}/${p}` : (p || base);
+  return `${url} (${projectName})`;
+}
+
+/**
+ * The platform a result file belongs to — `<f>-test-result.<os>[.<env>].json` → `<os>`. It names
+ * the run actually being read, so it outranks `MOBILE_PLATFORM` / `SUNGEN_ENV`, and SUNGEN_ENV
+ * is usually an environment (`staging`, `ja`), not an OS. A web locale file yields its locale,
+ * which is harmless: only a dual-id mobile `Path:` (`android | ios`) reads the platform.
+ */
+export function platformOfResultFile(resultsPath: string | null | undefined): string | undefined {
+  return resultsPath ? path.basename(resultsPath).match(/-test-result\.([^.]+)\./)?.[1] : undefined;
+}
+
+/** What a run-result row needs to fill its executor/environment cells. */
+export interface RunEnvironment extends EnvironmentInfo {
+  /** The unit's `Path:` (flows: their page selector; mobile: the OS-precise app id). */
+  featurePath?: string;
+}
+
+/**
+ * The Test Executor / Test Environment cells for one result — blank unless the test actually
+ * ran (a Pending or N/A row has nobody who executed it and no environment it ran against).
+ */
+export function runCells(env: RunEnvironment | undefined, result: PlaywrightResult | undefined): { executor: string; environment: string } {
+  if (!env || !result) return { executor: '', environment: '' };
+  const outcome = statusToTestResult(result.status);
+  if (outcome === 'Pending' || outcome === 'N/A') return { executor: '', environment: '' };
+  return {
+    executor: env.executor,
+    environment: formatEnv(env.baseURL, env.featurePath, result.projectName || env.projectName),
+  };
+}

package/src/exporters/scenario-merger.ts

@@ -9,8 +9,9 @@
  */
 
 import { FeatureMetadata, OrderedStep, ScenarioMetadata, SpecFileData, SpecTest } from './types';
-import { isStepsBaseScenario, isSampleScaffoldScenario, extractTestcaseType } from './feature-parser';
+import { isStepsBaseScenario, isSampleScaffoldScenario, isHookScenario, extractTestcaseType } from './feature-parser';
 import { SCENARIO_ID } from './feature-parser';
+import { extractUnlabeledOracle, onlyPresenceAssertions } from './manual-hybrid-oracle';
 
 /**
  * Parse a @manual scenario's `# Tester verifies:` comment block into procedure vs
@@ -21,8 +22,12 @@ import { SCENARIO_ID } from './feature-parser';
  * (Setup/Action/Precondition/unlabelled) → Steps. A non-numbered line following a
  * numbered item is a continuation (e.g. a wrapped URL) and is appended to it. Pre-amble
  * lines (the `MANUAL:` rationale, the `Tester verifies:` header, separators) are ignored.
+ *
+ * `unlabeledOracle` is the prose a `Tester verifies:` header carries OUTSIDE numbered lines
+ * (#810). It is not part of `expected` — the gates judge the numbered shape — but the exporter
+ * must never drop it: when no labelled oracle line exists it becomes the Expected cell.
  */
-export function parseManualComments(comments: string[]): { steps: OrderedStep[]; expected: OrderedStep[] } {
+export function parseManualComments(comments: string[]): { steps: OrderedStep[]; expected: OrderedStep[]; unlabeledOracle: string | null } {
   const steps: OrderedStep[] = [];
   const expected: OrderedStep[] = [];
   let last: OrderedStep | null = null;
@@ -45,7 +50,31 @@ export function parseManualComments(comments: string[]): { steps: OrderedStep[];
     }
     // else: pre-amble before any numbered item (rationale / header) → skip
   }
-  return { steps, expected };
+  return { steps, expected, unlabeledOracle: extractUnlabeledOracle(comments) };
+}
+
+/**
+ * The reason a @manual scenario is manual — the text of its `# MANUAL…: <reason>` comment
+ * (`MANUAL:`, `MANUAL (2026-09-16, run-test):`, `MANUAL/ENV:` …) plus its indented continuation
+ * lines, up to the `Tester verifies:` header, a numbered item or a divider. '' when absent.
+ * Rendered in the deliverable's Note so a tester sees why the case is not automated (#810).
+ */
+export function extractManualReason(comments: string[]): string {
+  const parts: string[] = [];
+  let inReason = false;
+  for (const raw of comments) {
+    const line = raw.trim();
+    if (!inReason) {
+      const m = line.match(/^MANUAL\b[^:]*:\s*(.*)$/i);
+      if (m) { inReason = true; if (m[1].trim()) parts.push(m[1].trim()); }
+      continue;
+    }
+    // A wrapped reason continues on an INDENTED comment line (`#   automate once seeded.`); the
+    // comment list carries no line numbers, so an unindented line is a separate note, not more reason.
+    if (!line || !/^\s/.test(raw) || /^tester verifies\b/i.test(line) || /^\d+[.)]\s/.test(line) || /^[-=*_]{2,}/.test(line)) break;
+    parts.push(line);
+  }
+  return parts.join(' ').replace(/\s+/g, ' ').trim();
 }
 
 export interface MergedScenario {
@@ -84,6 +113,12 @@ export interface MergedScenario {
    * so counting them would falsely mark @manual scenarios as interleaved.
    */
   resolvedAnchorActionCount: number;
+  /**
+   * Set when this @manual scenario's oracle exists ONLY as unlabelled `Tester verifies:` prose
+   * (#810). The prose is exported verbatim into `resolvedExpected`; delivery warns so the author
+   * rewrites it as numbered `Observable:` lines.
+   */
+  unlabeledManualOracle?: string;
 }
 
 /**
@@ -104,6 +139,7 @@ export function mergeFeatureAndSpec(
   for (const scenario of feature.scenarios) {
     if (isStepsBaseScenario(scenario)) continue;       // skip @steps base scenarios
     if (isSampleScaffoldScenario(scenario)) continue;  // skip default sample
+    if (isHookScenario(scenario)) continue;            // skip @beforeAll/@afterEach/@afterAll hooks
 
     const specTest = findMatchingSpecTest(scenario, spec.tests, feature.scenarios);
     const base = scenario.extendsName ? stepsBaseByName.get(scenario.extendsName) : undefined;
@@ -147,7 +183,16 @@ export function mergeFeatureAndSpec(
     const manualParsed =
       extractTestcaseType(scenario.tags) === 'Manual' && scenario.comments?.length
         ? parseManualComments(scenario.comments)
-        : { steps: [] as OrderedStep[], expected: [] as OrderedStep[] };
+        : { steps: [] as OrderedStep[], expected: [] as OrderedStep[], unlabeledOracle: null };
+    // Never drop a manual oracle (#810): with no labelled Observable/Oracle line and no Then that
+    // checks more than presence, the unlabelled `Tester verifies:` prose IS what the case checks —
+    // export it rather than let a presence placeholder stand in for it. A real Then keeps the cell.
+    const unlabeledOracle = !manualParsed.expected.length && onlyPresenceAssertions(ownAssertions.map((s) => s.text))
+      ? manualParsed.unlabeledOracle
+      : null;
+    const manualExpected: OrderedStep[] = unlabeledOracle
+      ? [{ text: unlabeledOracle, bucket: 'then' }]
+      : manualParsed.expected;
 
     result.push({
       feature: scenario,
@@ -158,8 +203,9 @@ export function mergeFeatureAndSpec(
         ...ownActions,
         ...manualParsed.steps,
       ],
-      resolvedExpected: [...ownAssertions, ...manualParsed.expected],
+      resolvedExpected: [...ownAssertions, ...manualExpected],
       resolvedAnchorActionCount: baseLen + ownActions.length,
+      ...(unlabeledOracle ? { unlabeledManualOracle: unlabeledOracle } : {}),
     });
   }
 

package/src/exporters/test-data-resolver.ts

@@ -190,9 +190,3 @@ export function renderDynamicTokens(text: string): string {
   });
 }
 
-/**
- * Resolve the test-data file path for a given screen.
- */
-export function resolveTestDataPath(cwd: string, screen: string): string {
-  return path.join(cwd, 'qa', 'screens', screen, 'test-data', `${screen}.yaml`);
-}

package/src/exporters/types.ts

@@ -95,6 +95,9 @@ export interface ScenarioMetadata {
    * as Gherkin steps — the merger parses these into Steps/Expected for the report.
    */
   comments?: string[];
+  /** Set for a `@beforeAll` / `@afterEach` / `@afterAll` scenario — a hook the compiler emits as
+   *  `test.beforeAll()` etc., never a test case (#880). */
+  hookType?: 'beforeAll' | 'afterEach' | 'afterAll';
 }
 
 /**
@@ -134,6 +137,8 @@ export interface PlaywrightResult {
   errorMessages?: string[];
   tracePath?: string;
   projectName?: string;
+  /** How many attempts the test took (retries + 1). A pass with attempts > 1 is flaky. */
+  attempts?: number;
 }
 
 /**

package/src/exporters/xlsx-exporter.ts

@@ -113,15 +113,20 @@ export function buildApiDetailRows(
  * used by the multi-locale delivery aggregator. Pass `null` / empty string
  * to force the base (no suffix) variant.
  */
+/** Where `writeXlsx` puts a unit's workbook — shared so a reader targets the identical file. */
+export function deliverableXlsxPath(cwd: string, screen: string, locale?: string | null): string {
+  return path.join(cwd, 'qa', 'deliverables', `${deliverableBasename(screen, locale)}.xlsx`);
+}
+
 export async function writeXlsx(
   cwd: string,
   screen: string,
   wb: ExcelJS.Workbook,
   locale?: string | null,
 ): Promise<string> {
-  const outDir = path.join(cwd, 'qa', 'deliverables');
+  const outPath = deliverableXlsxPath(cwd, screen, locale);
+  const outDir = path.dirname(outPath);
   if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
-  const outPath = path.join(outDir, `${deliverableBasename(screen, locale)}.xlsx`);
   const buffer = await wb.xlsx.writeBuffer();
   const locked = await lockEmbeddedImages(Buffer.from(buffer as ArrayBuffer));
   fs.writeFileSync(outPath, locked);

package/src/generators/gherkin-parser/index.ts

@@ -154,11 +154,18 @@ export class GherkinParser {
   }
 
   /**
-   * Range-attach top-level Gherkin comments to the scenario whose body contains them.
-   * A comment belongs to scenario i when its line is after scenario i's `Scenario:` line
-   * and before scenario i+1's header (its first tag line, or its `Scenario:` line). The
-   * leading `# ` is stripped. Used to surface a @manual scenario's tester-procedure comments
+   * Attach top-level Gherkin comments to the scenario they describe. The leading `# ` is
+   * stripped. Used to surface a @manual scenario's tester procedure and `# MANUAL:` reason
    * (its only "steps") in the delivery report.
+   *
+   * A scenario owns:
+   *   • its LEADING block — the comment lines directly above its header with no blank line in
+   *     between (and any comment between its tag lines and `Scenario:`), as long as they sit
+   *     after the previous scenario's last step. `# MANUAL (…): reason` written above the tags
+   *     belongs to the scenario below it; it used to range onto the scenario ABOVE, where the
+   *     manual parser appended it to that scenario's last oracle line (#810);
+   *   • its BODY — every other comment after its `Scenario:` line and before the next
+   *     scenario's leading block / header.
    */
   private attachScenarioComments(
     doc: Messages.GherkinDocument,
@@ -167,22 +174,32 @@ export class GherkinParser {
   ): void {
     const comments = doc.comments || [];
     if (!comments.length) return;
-    const scenChildren = feature.children
-      .filter((c) => c.scenario)
-      .map((c) => c.scenario!);
+    const lineOf = new Map<number, string>(
+      comments.map((cm) => [cm.location.line, cm.text.replace(/^\s*#\s?/, '').replace(/\s+$/, '')]),
+    );
     // Same filter/order as parseScenarios → indices line up with `scenarios`.
+    const scenChildren = feature.children.filter((c) => c.scenario).map((c) => c.scenario!);
+    const background = feature.children.find((c) => c.background)?.background;
+    const headerLine = (sc: Messages.Scenario): number =>
+      Math.min(sc.location.line, ...(sc.tags || []).map((t) => t.location.line));
+
+    // Leading block of scenario i: [firstLeading, sc.location.line).
+    const leadingStart = scenChildren.map((sc, i) => {
+      const prevEnd = i > 0 ? bodyEndLine(scenChildren[i - 1]) : background ? bodyEndLine(background) : feature.location.line;
+      let first = headerLine(sc);
+      while (lineOf.has(first - 1) && first - 1 > prevEnd) first--;
+      return first;
+    });
+
     for (let i = 0; i < scenChildren.length && i < scenarios.length; i++) {
-      const startLine = scenChildren[i].location.line;
-      const next = scenChildren[i + 1];
-      let endLine = Number.POSITIVE_INFINITY;
-      if (next) {
-        const tagLines = (next.tags || []).map((t) => t.location.line);
-        endLine = Math.min(next.location.line, ...(tagLines.length ? tagLines : [next.location.line]));
-      }
-      const body = comments
-        .filter((cm) => cm.location.line > startLine && cm.location.line < endLine)
-        .map((cm) => cm.text.replace(/^\s*#\s?/, '').replace(/\s+$/, ''));
-      if (body.length) scenarios[i].comments = body;
+      const from = leadingStart[i];
+      const to = i + 1 < scenChildren.length ? leadingStart[i + 1] : Number.POSITIVE_INFINITY;
+      const own = comments
+        .map((cm) => cm.location.line)
+        .filter((line) => line >= from && line < to)
+        .sort((a, b) => a - b)
+        .map((line) => lineOf.get(line)!);
+      if (own.length) scenarios[i].comments = own;
     }
   }
 
@@ -360,3 +377,18 @@ export class GherkinParser {
     return files;
   }
 }
+
+/** Last source line a scenario/background occupies: its steps, their data tables/doc strings, examples. */
+function bodyEndLine(block: Messages.Scenario | Messages.Background): number {
+  let end = block.location.line;
+  for (const step of block.steps) {
+    end = Math.max(end, step.location.line);
+    for (const row of step.dataTable?.rows ?? []) end = Math.max(end, row.location.line);
+    if (step.docString) end = Math.max(end, step.docString.location.line + step.docString.content.split('\n').length + 1);
+  }
+  for (const ex of ('examples' in block ? block.examples : [])) {
+    end = Math.max(end, ex.location.line);
+    for (const row of [...(ex.tableHeader ? [ex.tableHeader] : []), ...ex.tableBody]) end = Math.max(end, row.location.line);
+  }
+  return end;
+}

package/src/generators/test-generator/adapters/adapter-interface.ts

@@ -5,7 +5,11 @@
 
 export interface AuthGroup {
   authRole?: string;
+  noAuth?: boolean;
   scenarios: string[];
+  /** The feature's `@afterEach`, scoped to this group — set when the feature mixes `@no-auth` with
+   *  other groups, so the hook never runs on an anonymous test's empty session (#815). */
+  afterEach?: string;
 }
 
 /**
@@ -42,7 +46,7 @@ export interface TestFileData {
   runtimeData?: boolean; // --runtime-data flag: testData.get() instead of hardcoded values
   screenName?: string; // Screen name for TestDataLoader.load()
   featureFileName?: string; // Feature file name for TestDataLoader.load()
-  isParallel?: boolean; // @parallel tag: fresh page per test (opt-out from serial default)
+  isParallel?: boolean; // !@serial: fresh page per test. Parallel is the default; @parallel only names it
   flowMode?: boolean;   // flow: cross-screen → longer per-test timeout (bug #243)
   platform?: string;    // mobile @platform:* value (mobile|android|ios) → `// sungen:platform=` marker for wdio per-OS routing
   cleanup?: { overlay?: boolean; forms?: boolean; scroll?: boolean; storage?: boolean };
@@ -65,7 +69,7 @@ export interface ScenarioData {
   scenarioName: string;
   steps: Array<{ comment?: string; code: string }>;
   authRole?: string; // Auth role for storage state
-  isParallel?: boolean; // @parallel: use fresh page from fixture
+  isParallel?: boolean; // !@serial: use fresh page from fixture
   tags?: string; // Pass-through tags for Playwright { tag: [...] }, e.g. "'@smoke', '@high'"
   casesDataset?: string; // @cases:<dataset> — emit one test() per row of the runtime dataset
   resetTier?: string; // Mobile (appium): scenario-level `@reset:` override; raises (never lowers) the feature tier for this scenario only

package/src/generators/test-generator/adapters/appium/templates/steps/actions/reinstall-app-action.hbs

@@ -2,8 +2,8 @@
 // Persistence oracles (dismissals, pins) hinge on what survives a reinstall.
 await (async () => {
   const __pkg = __resolveAppId();
-  const __caps = (driver.requestedCapabilities || {}) as Record<string, string>;
-  const __appPath = __caps['appium:app'] || __caps['app'];
+  // Same reader the reset tiers use — one place decides what "the session has a build file" means.
+  const __appPath = __appBuildPath();
   if (!__appPath) {
     throw new Error('reinstall the app: the session must install from a build file — set APP_APK (Android) / IOS_APP (iOS) so the appium:app capability is present.');
   }

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/label-value-assertion.hbs

@@ -9,12 +9,18 @@
       Flutter screen; UiSelector has no OR, hence the xpath. iOS scatters it across
       label/value, which the predicate already ORs.
 
+      SCOPE (#747): an `in [Parent] <type>` clause chains this under the parent element. The android
+      xpath must go RELATIVE (`.//`) to do so — a child xpath beginning with `//` is ABSOLUTE in
+      Appium even when chained, so keeping it would emit code that LOOKS scoped and searches the whole
+      screen, which is the same silent widening the scope clause exists to prevent. The iOS predicate
+      carries no such trap and chains as written.
+
       The expected value must stay a standalone quoted literal so the runtime-data transform
       can swap it for testData.get(...). --}}
 {
   const __expected = String('{{escapeQuotes dataValue}}').trim();
   const __sel = driver.isIOS
     ? `-ios predicate string:label == "${__expected}" OR value == "${__expected}"`
-    : `//*[@text="${__expected}" or @content-desc="${__expected}"]`;
-  await expect($(__sel)).toBeDisplayed();
+    : `{{#if parentLocator}}.{{/if}}//*[@text="${__expected}" or @content-desc="${__expected}"]`;
+  await expect({{#if parentLocator}}{{parentLocator}}.$(__sel){{else}}$(__sel){{/if}}).toBeDisplayed();
 }

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/visible-with-role-variable-assertion.hbs

@@ -1,13 +1,17 @@
 {{!-- Role variable, visible (mobile best-effort): ARIA role has no native-mobile analog — reuse
       the role→accessibility-id mapping in appium-selector.hbs (`~name`) when a static name
       exists; the resolver already folds dataValue into name when there is none, so this is only
-      the fallback for a caller that omits both. --}}
+      the fallback for a caller that omits both.
+
+      SCOPE (#747): an `in [Parent] <type>` clause chains this under the parent element. Both
+      branches locate by accessibility id / predicate, neither of which carries the absolute-xpath
+      trap the label-value twin has to work around. --}}
 {{#if name}}
-await expect($('~{{escapeQuotes name}}')).toBeDisplayed();
+await expect({{#if parentLocator}}{{parentLocator}}.$('~{{escapeQuotes name}}'){{else}}$('~{{escapeQuotes name}}'){{/if}}).toBeDisplayed();
 {{else}}
 {
   const __expected = String('{{escapeQuotes dataValue}}').trim();
   const __sel = driver.isIOS ? `-ios predicate string:label == "${__expected}" OR value == "${__expected}"` : `android=new UiSelector().text("${__expected}")`;
-  await expect($(__sel)).toBeDisplayed();
+  await expect({{#if parentLocator}}{{parentLocator}}.$(__sel){{else}}$(__sel){{/if}}).toBeDisplayed();
 }
 {{/if}}

package/src/generators/test-generator/adapters/appium/templates/test-file.hbs

@@ -502,9 +502,36 @@ describe('{{featureName}}', () => {
   // lose the escalation between them — SG-W024 already reports that shape when tiers are involved.)
   let __escalateAfter: string | null = null;
 
+  // `@known-defect` marks a scenario that is EXPECTED to be red — it asserts a live defect. The
+  // scaffolded /sungen:run-test command tells authors exactly that ("expected-red scenarios stay red;
+  // never 'fix' them"), so the ladder honours it here: such a failure is the suite working as
+  // designed, not evidence of leftover state. Arming escalation off it would make the NEXT scenario
+  // pay a harder reset for nothing — on every run, forever, because the defect is known.
+  //
+  // Read off the TITLE because `@known-defect` is a pass-through tag: appium appends it there as the
+  // `[@a @b]` suffix (which is what keeps it greppable via `--grep`), and that is how the field
+  // report shows it. Anchored to that trailing group, so a scenario merely NAMED `… known-defect …`
+  // cannot exempt itself — the same reason __tierFor refuses to strip a trailing `[Selector]` ref.
+  //
+  // Matched as a whole TAG TOKEN, never as a substring. `@known-defect-list` is a DIFFERENT tag, and
+  // reading it as this one would silently stop the next scenario's real dirty-state failure from
+  // getting the escalated reset it needs — with no log line at all, because "never armed" is not the
+  // "capped" path and prints nothing. The `:<ref>` parameter form is accepted because that is what
+  // the rest of the vocabulary does (`@manual:M10`, `@reset:data`).
+  //
+  // Caveat, inherited rather than introduced: a @cases scenario builds its title at runtime as
+  // `name — <row label>`, so a row LABEL that itself ends in `[@…]` would be read as the tag group.
+  // Same trailing-bracket ambiguity __tierFor accepts for a `[Selector]` ref.
+  function __isExpectedFail(title: string): boolean {
+    const tagGroup = title.match(/ \[@[^\]]*\]$/);
+    if (!tagGroup) return false;
+    return tagGroup[0].slice(2, -1).split(/\s+/)
+      .some((t) => t === '@known-defect' || t.startsWith('@known-defect:'));
+  }
+
   // Registered BEFORE any user @afterEach block so a throwing user hook cannot skip the bookkeeping.
   afterEach(async function () {
-    __escalateAfter = this.currentTest?.state === 'failed' ? (this.currentTest?.title ?? '') : null;
+    __escalateAfter = this.currentTest?.state === 'failed' && !__isExpectedFail(this.currentTest?.title ?? '') ? (this.currentTest?.title ?? '') : null;
   });
 
 {{#if scenarioResetTiers}}
@@ -583,9 +610,31 @@ describe('{{featureName}}', () => {
     await driver.execute('mobile: clearApp', { appId: pkg });
   }
 
-  async function __reinstallApp(pkg: string): Promise<void> {
+  /** The app's build file, when the session was given one. Absent when the app was attached BY PACKAGE. */
+  function __appBuildPath(): string | undefined {
     const caps = (driver.requestedCapabilities || {}) as Record<string, string>;
-    const appPath = caps['appium:app'] || caps['app'];
+    return caps['appium:app'] || caps['app'];
+  }
+
+  /**
+   * The strongest tier THIS SESSION can actually carry out.
+   *
+   * Reinstalling needs the app's build file, and `data` on iOS IS a reinstall (no `mobile: clearApp`
+   * outside UiAutomator2). Attaching the app by package — the common local setup — leaves no build
+   * file, so those tiers cannot run at all.
+   *
+   * This exists so ESCALATION can cap itself. Escalation is a recovery the runner CHOSE; nothing
+   * asked for it. Escalating into a tier that throws turns one failed scenario into a dead spec file,
+   * because the throw lands in `beforeEach` and mocha then skips every remaining test in the file.
+   * A DECLARED tier is never capped — that is an unmet contract and must still throw by name.
+   */
+  function __performableTier(): string {
+    if (__appBuildPath()) return 'full';
+    return driver.isIOS ? 'soft' : 'data';
+  }
+
+  async function __reinstallApp(pkg: string): Promise<void> {
+    const appPath = __appBuildPath();
     if (!appPath) {
       throw new Error(
         `reset tier needs the app's build file to reinstall — set APP_APK (Android) / IOS_APP (iOS) so the appium:app capability is present, or drop to @reset:soft.`,
@@ -637,9 +686,24 @@ describe('{{featureName}}', () => {
     // Same title ⟹ this is a retry of the scenario that just failed: keep its declared tier so a real
     // failure fails both attempts (see __escalateAfter above).
     const __escalate = __escalateAfter !== null && __escalateAfter !== (this.currentTest?.title ?? '');
-    const __tier = __escalate ? __ESCALATE[__base] : __base;
+    // Escalation caps at what this session can perform, with the DECLARED tier as the FLOOR.
+    // The cap stops a tier NOBODY ASKED FOR from throwing in this hook and taking the rest of the
+    // spec file with it. The floor stops the cap from silently WEAKENING what the feature declared:
+    // a declared tier this session cannot perform still reaches __resetApp and still throws by name,
+    // because that one IS an unmet contract.
+    const __want = __escalate ? __ESCALATE[__base] : __base;
+    const __tier = __escalate
+      ? __TIER_ORDER[Math.max(
+          __TIER_ORDER.indexOf(__base),
+          Math.min(__TIER_ORDER.indexOf(__want), __TIER_ORDER.indexOf(__performableTier())),
+        )]
+      : __want;
     if (__tier !== __base) {
       console.log(`  \u2191 reset escalated ${__base} \u2192 ${__tier} (previous scenario failed: "${__escalateAfter}")`);
+    } else if (__want !== __base) {
+      // Said per occurrence, not once per run: this names the scenario that did NOT get the stronger
+      // reset it was owed, which is a fact about THIS scenario, not just about the session.
+      console.warn(`  ! reset could not escalate ${__base} \u2192 ${__want} — this session has no app build file to reinstall from (the app was attached by package). Staying at ${__base}; set APP_APK (Android) / IOS_APP (iOS) to enable the stronger reset.`);
     }
     await __resetApp(__tier);
 {{#if backgroundSteps}}