@sun-asterisk/sungen 3.2.32 → 3.2.33

package/src/exporters/locale-variants.ts

@@ -34,7 +34,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { parse as parseYaml } from 'yaml';
+import { readYamlConfig, warnUnreadableConfig } from '../harness/config-file';
 
 export interface LocaleVariant {
   /** Result-file suffix as found on disk ('' = base). */
@@ -65,23 +65,29 @@ export interface LocaleConfig {
 
 export const DEFAULT_BASE_LOCALE = 'en';
 
-/** Read the i18n declaration from qa/capabilities.yaml (absent → no locales, base 'en'). */
+/**
+ * Read the i18n declaration from qa/capabilities.yaml (absent → no locales, base 'en').
+ *
+ * An unreadable file previously took the same path as an absent one — the `existsSync` check sat
+ * INSIDE the try, so a parse error fell through to the same "undeclared" return. Every declared
+ * locale then dropped out of the deliverable with no line anywhere saying why.
+ */
 export function readLocaleConfig(cwd: string): LocaleConfig {
-  try {
-    const p = path.join(cwd, 'qa', 'capabilities.yaml');
-    if (fs.existsSync(p)) {
-      const parsed = parseYaml(fs.readFileSync(p, 'utf-8')) as
-        { locales?: unknown; base_locale?: unknown } | null;
-      const locales = Array.isArray(parsed?.locales)
-        ? parsed!.locales!.filter((l): l is string => typeof l === 'string' && l.length > 0)
-        : [];
-      const baseLocale = typeof parsed?.base_locale === 'string' && parsed.base_locale
-        ? parsed.base_locale
-        : DEFAULT_BASE_LOCALE;
-      return { baseLocale, locales };
-    }
-  } catch { /* malformed yaml → behave as undeclared */ }
-  return { baseLocale: DEFAULT_BASE_LOCALE, locales: [] };
+  const p = path.join(cwd, 'qa', 'capabilities.yaml');
+  const read = readYamlConfig<{ locales?: unknown; base_locale?: unknown } | null>(p);
+  if (read.state === 'absent') return { baseLocale: DEFAULT_BASE_LOCALE, locales: [] };
+  if (read.state === 'unreadable') {
+    warnUnreadableConfig(p, read.error, 'no locale variants are discovered — the deliverable covers the base locale only');
+    return { baseLocale: DEFAULT_BASE_LOCALE, locales: [] };
+  }
+  const parsed = read.value;
+  const locales = Array.isArray(parsed?.locales)
+    ? parsed!.locales!.filter((l): l is string => typeof l === 'string' && l.length > 0)
+    : [];
+  const baseLocale = typeof parsed?.base_locale === 'string' && parsed.base_locale
+    ? parsed.base_locale
+    : DEFAULT_BASE_LOCALE;
+  return { baseLocale, locales };
 }
 
 const OS_SUFFIX = /^(android|ios)(\.|$)/;

package/src/exporters/matrix/build.ts

@@ -19,7 +19,7 @@ import {
 import { getCasesDatasetRows, resolveResultVariants } from '../result-variants';
 import { renderDynamicTokens } from '../test-data-resolver';
 import { maskCredentialValue } from '../sensitive-key';
-import { classifyManualComments, renderAction, renderExpected, renderPrecondition, renderSetupInstruction, runtimeVarsOf } from './wording';
+import { afterSubstitution, classifyManualComments, renderAction, renderExpected, renderPrecondition, renderSetupInstruction, runtimeVarsOf } from './wording';
 import { scenarioFingerprint, combinedFingerprint, mapContentFingerprint } from './fingerprint';
 import {
   CoverageVariant,
@@ -251,10 +251,16 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       verification: manual?.verification.map((t) => sentenceOf(t)) ?? [],
     };
 
-    /** Render the display cells for one data context (vars resolved first). */
+    /**
+     * Render the display cells for one data context. Steps are worded FIRST and values
+     * substituted AFTER (#772): wording strips the DSL's `[Ref]` brackets, and a value
+     * such as `^[A-Za-z]{3}` or `[E2E-01] title` must never be mistaken for one.
+     * Preconditions (rendered at build time above) already went in this order.
+     */
     const renderCells = (vars: Record<string, string>): { trigger: string[]; oracle: string[]; precondition: string[]; verification: string[] } => {
       const sub = (s: string): string => substituteDisplayVars(s, vars, runtimeVars);
-      const preconditionOut = precondition.map(sub);
+      const fill = (rendered: string): string => afterSubstitution(sub(rendered));
+      const preconditionOut = precondition.map(fill);
       const verificationOut = base.verification.map(sub);
       if (procedureProfile === 'sequence' && !manual) {
         // Ordered flow (review B-03): keep the event order — actions stay numbered in
@@ -266,9 +272,9 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
         const trigger: string[] = [];
         const oracle: string[] = [];
         steps.forEach((s, i) => {
-          if (i > lastActionIdx) oracle.push(renderExpected(sub(s.text)));           // trailing Then block
-          else if (s.bucket === 'then') trigger.push(`Verify: ${renderExpected(sub(s.text))}`);
-          else if (s.bucket === 'when') trigger.push(renderAction(sub(s.text)));
+          if (i > lastActionIdx) oracle.push(fill(renderExpected(s.text)));           // trailing Then block
+          else if (s.bucket === 'then') trigger.push(`Verify: ${fill(renderExpected(s.text))}`);
+          else if (s.bucket === 'when') trigger.push(fill(renderAction(s.text)));
           // leading given steps already live in the precondition
         });
         return { trigger, oracle, precondition: preconditionOut, verification: verificationOut };
@@ -277,8 +283,8 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       // Method/API/Header/Body lines are already reader-facing, not step DSL).
       const trigger = apiCallsAreTrigger
         ? apiRequestLines.map(sub)
-        : rawTrigger.map((s) => renderAction(sub(s)));
-      const oracle = rawOracle.map((s) => renderExpected(sub(s)));
+        : rawTrigger.map((s) => fill(renderAction(s)));
+      const oracle = rawOracle.map((s) => fill(renderExpected(s)));
       return {
         // A pure-render check (Given + Then only) is checked on page load — say so
         // in words instead of a placeholder token (review §10.3).

package/src/exporters/matrix/carry-manual-results.ts

@@ -0,0 +1,229 @@
+/**
+ * Carry a tester's hand-entered Manual results across a `sungen delivery` re-run (#756).
+ *
+ * The matrix workbook is rebuilt from scratch on every run, and a manual variant has no
+ * run-report entry, so its Result cell renders `Pending` and M–P render blank. Without
+ * this step the re-run overwrote the file and the tester's record was gone.
+ *
+ * Before the new workbook is written, the existing file's Manual sheet is read, and each
+ * variant sub-row's L–P cells (Test Result, Executed Date, Test Executor, Test Environment,
+ * Note) are carried into the new workbook by `v.ref` — column A.
+ *
+ * A result is only true of the procedure it was executed against, so every write stamps
+ * `ref → fingerprint` into a veryHidden sheet. The next run carries a result only while the
+ * stamp still matches; a changed procedure resets it to `Pending` and keeps the previous
+ * values in Note. Spec: docs/spec/delivery-coverage-matrix-spec.md §8.4.
+ *
+ * Manual sheet only: on Auto the run report is the source of truth for Result.
+ */
+
+import * as fs from 'fs';
+import * as ExcelJS from 'exceljs';
+import { MatrixModel } from './types';
+import { HEADER_ROW, RESULT_COL } from './render-testcase-sheet';
+
+const MANUAL_SHEET = 'Manual';
+/** veryHidden: Excel's UI cannot unhide it, so a tester cannot edit the guard by accident. */
+export const STAMP_SHEET = '_sungen_manual';
+/** L..P — the tester-owned columns of a variant sub-row. */
+const CARRIED_COLS = [RESULT_COL, RESULT_COL + 1, RESULT_COL + 2, RESULT_COL + 3, RESULT_COL + 4];
+const NOTE_INDEX = 4;
+const RESET_MARKER = '[sungen] Procedure changed since this result was recorded';
+
+interface CarriedCell { value: ExcelJS.CellValue; numFmt?: string }
+
+interface PriorRow { cells: CarriedCell[] }
+
+export interface PriorManualResults {
+  rows: Map<string, PriorRow>;
+  /** Later copies of a ref already read — only the first is carried, so these are reported. */
+  duplicates: { ref: string; result: string }[];
+  /** `ref → fingerprint` from the stamp sheet; null when the file predates #756. */
+  stamps: Map<string, string> | null;
+}
+
+export interface ManualCarryReport {
+  /** Carried with a matching fingerprint. */
+  carried: number;
+  /** Carried from a file with no stamp — no drift check was possible. */
+  unchecked: number;
+  /** Result reset to Pending because the procedure changed. */
+  reset: string[];
+  /** Prior rows with an entry that no longer match any manual variant. */
+  notPlaced: { ref: string; result: string }[];
+  /** Prior rows with an entry that repeat a ref above them — not carried. */
+  duplicates: { ref: string; result: string }[];
+}
+
+function isFormula(v: ExcelJS.CellValue): boolean {
+  return typeof v === 'object' && v !== null && ('formula' in v || 'sharedFormula' in v);
+}
+
+function cellText(v: ExcelJS.CellValue): string {
+  if (v === null || v === undefined) return '';
+  if (v instanceof Date) return isNaN(v.getTime()) ? '' : v.toISOString().slice(0, 10);
+  if (typeof v === 'object') {
+    if ('richText' in v) return v.richText.map((r) => r.text).join('').trim();
+    if ('text' in v) return String(v.text).trim();
+    if ('result' in v) return cellText(v.result as ExcelJS.CellValue);
+  }
+  return String(v).trim();
+}
+
+/**
+ * ExcelJS reads a formula's text result under a date format as an Invalid Date. Drop that
+ * cached result — Excel recomputes it on open — instead of writing NaN back into the file.
+ */
+function readable(v: ExcelJS.CellValue): ExcelJS.CellValue {
+  if (isFormula(v)) {
+    const { result, ...formula } = v as ExcelJS.CellFormulaValue;
+    if (result instanceof Date && isNaN(result.getTime())) return formula as ExcelJS.CellValue;
+  }
+  return v;
+}
+
+/** A row still at the rendered default carries nothing. */
+function isUntouched(cells: CarriedCell[]): boolean {
+  const [result, ...rest] = cells.map((c) => cellText(c.value));
+  return (result === '' || result === 'Pending') && rest.every((t) => t === '');
+}
+
+/**
+ * Variant sub-rows of a Manual sheet, in row order: `[ref, row]`. Either signal is enough:
+ * the renderer puts variants on outline level 1, and a parent's Result is a roll-up formula.
+ * Outline levels are lost by some spreadsheet tools on save, and a tester can paste a
+ * formula into a variant's Result, so relying on one alone would hide the row silently.
+ */
+function variantRows(ws: ExcelJS.Worksheet): [string, ExcelJS.Row][] {
+  const out: [string, ExcelJS.Row][] = [];
+  for (let r = HEADER_ROW + 1; r <= ws.rowCount; r++) {
+    const row = ws.getRow(r);
+    const ref = cellText(row.getCell(1).value);
+    if (ref && (row.outlineLevel === 1 || !isFormula(row.getCell(RESULT_COL).value))) out.push([ref, row]);
+  }
+  return out;
+}
+
+/**
+ * Read the Manual results of the workbook about to be overwritten. Returns null when there is
+ * no such file. A file that exists but cannot be read THROWS: overwriting it would destroy the
+ * very record this step exists to keep.
+ */
+export async function readPriorManualResults(file: string): Promise<PriorManualResults | null> {
+  if (!fs.existsSync(file)) return null;
+  const wb = new ExcelJS.Workbook();
+  try {
+    await wb.xlsx.readFile(file);
+  } catch (e) {
+    throw new Error(
+      `cannot read ${file} to carry its Manual results (${(e as Error).message}). ` +
+      'Close it in Excel, or move it aside to start a fresh workbook, then re-run.',
+    );
+  }
+
+  // Every workbook sungen writes has a Manual sheet, even an empty one. Without it the
+  // tester's results cannot be located — carrying nothing would look like a clean run.
+  const ws = wb.getWorksheet(MANUAL_SHEET);
+  if (!ws) {
+    throw new Error(
+      `${file} has no "${MANUAL_SHEET}" sheet, so its Manual results cannot be carried. ` +
+      `Rename the sheet back to "${MANUAL_SHEET}", or move the file aside to start a fresh workbook, then re-run.`,
+    );
+  }
+
+  const rows = new Map<string, PriorRow>();
+  const duplicates: PriorManualResults['duplicates'] = [];
+  for (const [ref, row] of variantRows(ws)) {
+    const cells = CARRIED_COLS.map((c) => {
+      const cell = row.getCell(c);
+      return { value: readable(cell.value), ...(cell.numFmt ? { numFmt: cell.numFmt } : {}) };
+    });
+    if (!rows.has(ref)) rows.set(ref, { cells });
+    else if (!isUntouched(cells)) duplicates.push({ ref, result: cellText(cells[0].value) || '(no result)' });
+  }
+
+  const stampWs = wb.getWorksheet(STAMP_SHEET);
+  let stamps: Map<string, string> | null = null;
+  if (stampWs) {
+    stamps = new Map();
+    stampWs.eachRow((row, n) => {
+      if (n > 1) stamps!.set(cellText(row.getCell(1).value), cellText(row.getCell(2).value));
+    });
+  }
+  return { rows, duplicates, stamps };
+}
+
+/**
+ * Note for a reset row: what was invalidated, then whatever the tester had written. A note
+ * that is a hyperlink (evidence, a defect ticket) stays one — only its text gains the marker.
+ */
+function resetNote(prior: CarriedCell[]): ExcelJS.CellValue {
+  const [result, date, executor] = prior.map((c) => cellText(c.value));
+  const was = [result, date, executor].filter(Boolean).join(' · ');
+  const header = `${RESET_MARKER} — previous: ${was}. Re-run required.`;
+  const note = prior[NOTE_INDEX].value;
+  const own = cellText(note);
+  if (typeof note === 'object' && note !== null && 'hyperlink' in note) {
+    return { ...note, text: `${header}\n${own}` };
+  }
+  return own ? `${header}\n${own}` : header;
+}
+
+/**
+ * Carry `prior` into the freshly rendered `wb`, then stamp every manual variant's fingerprint.
+ * Only the Manual sheet's variant sub-rows are touched.
+ */
+export function carryManualResults(
+  wb: ExcelJS.Workbook,
+  model: MatrixModel,
+  prior: PriorManualResults | null,
+): ManualCarryReport {
+  const report: ManualCarryReport = { carried: 0, unchecked: 0, reset: [], notPlaced: [], duplicates: prior?.duplicates ?? [] };
+  const fingerprints = new Map(
+    model.items.flatMap((i) => i.variants).filter((v) => v.mode === 'manual').map((v) => [v.ref, v.fingerprint]),
+  );
+
+  const ws = wb.getWorksheet(MANUAL_SHEET);
+  const placed = new Set<string>();
+  if (ws && prior) {
+    for (const [ref, row] of variantRows(ws)) {
+      const before = prior.rows.get(ref);
+      if (!before) continue;
+      placed.add(ref);
+      if (isUntouched(before.cells)) continue;
+
+      const stamped = prior.stamps?.get(ref);
+      // Only a recorded result is a claim about the procedure. A row with no result (a
+      // blocker note, or one already reset) is carried as-is, so a second procedure
+      // change does not stack a second marker on it.
+      const hasResult = !['', 'Pending'].includes(cellText(before.cells[0].value));
+      if (stamped !== undefined && stamped !== fingerprints.get(ref) && hasResult) {
+        row.getCell(RESULT_COL).value = 'Pending';
+        row.getCell(CARRIED_COLS[NOTE_INDEX]).value = resetNote(before.cells);
+        report.reset.push(ref);
+        continue;
+      }
+
+      CARRIED_COLS.forEach((c, i) => {
+        const cell = row.getCell(c);
+        cell.value = before.cells[i].value;
+        if (before.cells[i].numFmt) cell.numFmt = before.cells[i].numFmt!;
+      });
+      if (stamped === undefined) report.unchecked++;
+      else report.carried++;
+    }
+  }
+
+  if (prior) {
+    for (const [ref, before] of prior.rows) {
+      if (!placed.has(ref) && !isUntouched(before.cells)) {
+        report.notPlaced.push({ ref, result: cellText(before.cells[0].value) || '(no result)' });
+      }
+    }
+  }
+
+  const stampWs = wb.addWorksheet(STAMP_SHEET, { state: 'veryHidden' });
+  stampWs.addRow(['ref', 'fingerprint']);
+  for (const [ref, fp] of fingerprints) stampWs.addRow([ref, fp]);
+  return report;
+}

package/src/exporters/matrix/export.ts

@@ -16,7 +16,8 @@ import { loadPlaywrightReport } from '../playwright-report-parser';
 import { mergeFeatureAndSpec } from '../scenario-merger';
 import { getPackageVersion } from '../package-info';
 import { writeCsv } from '../csv-exporter';
-import { writeXlsx } from '../xlsx-exporter';
+import { deliverableXlsxPath, writeXlsx } from '../xlsx-exporter';
+import { carryManualResults, ManualCarryReport, readPriorManualResults } from './carry-manual-results';
 import { loadPerfConfig, perfVerdict } from '../../harness/perf';
 import { loadDeliveryMap, writeDeliveryMap } from './map-loader';
 import { mapContentFingerprint } from './fingerprint';
@@ -163,13 +164,18 @@ export async function writeMatrixDeliverables(
   paths: MatrixTargetPaths,
   model: MatrixModel,
   format: MatrixFormat = 'xlsx',
-): Promise<{ csvPath?: string; xlsxPath?: string }> {
-  const out: { csvPath?: string; xlsxPath?: string } = {};
+): Promise<{ csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport }> {
+  const out: { csvPath?: string; xlsxPath?: string; manualCarry?: ManualCarryReport } = {};
+  const xlsx = format === 'xlsx' || format === 'both';
+  // Read the workbook about to be overwritten BEFORE writing anything, so the tester's Manual
+  // results survive (#756) and a refusal leaves no half-written target behind.
+  const prior = xlsx ? await readPriorManualResults(deliverableXlsxPath(paths.cwd, paths.unit)) : null;
   if (format === 'csv' || format === 'both') {
     out.csvPath = writeCsv(paths.cwd, paths.unit, renderMatrixCsv(model));
   }
-  if (format === 'xlsx' || format === 'both') {
+  if (xlsx) {
     const wb = renderMatrixXlsx(model, getPackageVersion());
+    out.manualCarry = carryManualResults(wb, model, prior);
     out.xlsxPath = await writeXlsx(paths.cwd, paths.unit, wb);
   }
   return out;

package/src/exporters/matrix/wording.ts

@@ -40,8 +40,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 +132,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]}`],

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/test-generator/adapters/adapter-interface.ts

@@ -42,7 +42,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 +65,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}}

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

@@ -1 +1,7 @@
-await expect(page.getByText(/{{#if label}}{{escapeRegex label}}\s*{{else}}(?:^|\s){{/if}}{{escapeRegex dataValue}}$/)).toBeVisible();
+{{!-- Caption+value read: the ref names on-screen TEXT ("学科 -"), not an element, so the locator is
+      built inline from the caption rather than through the `locator` partial. That is why the scope
+      clause needs its own slot here — the partial's `parentLocator` handling never runs (#747).
+      Unscoped, `… in [Education Card 6] card` compiled away to nothing: on a screen repeating ten
+      学歴・職歴 cards the assertion strict-mode-failed where the caption repeats, and where it
+      happened to be unique elsewhere it passed having read a DIFFERENT card than the sentence names. --}}
+await expect({{#if parentLocator}}{{parentLocator}}{{else}}page{{/if}}.getByText(/{{#if label}}{{escapeRegex label}}\s*{{else}}(?:^|\s){{/if}}{{escapeRegex dataValue}}$/)).toBeVisible();

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

@@ -1,9 +1,13 @@
+{{!-- `getByRole` is built inline from role/name rather than through the `locator` partial, so the
+      scope clause needs its own slot here exactly as in label-value-assertion — the label branch's
+      twin (#747). `see [Logo] image with {{alt}} in [Product Card 3] card` searched every card on
+      the page before this. --}}
 {{#if name}}
 {{#if dataValue}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}}).toBeVisible();
+await expect({{#if parentLocator}}{{parentLocator}}{{else}}page{{/if}}.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}}).toBeVisible();
 {{else}}
-await expect(page.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{> locator-nth}}).toBeVisible();
+await expect({{#if parentLocator}}{{parentLocator}}{{else}}page{{/if}}.getByRole('{{role}}', { name: '{{escapeQuotes name}}'{{#if exact}}, exact: true{{/if}} }){{> locator-nth}}).toBeVisible();
 {{/if}}
 {{else}}
-await expect(page.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}}).toBeVisible();
-{{/if}}
+await expect({{#if parentLocator}}{{parentLocator}}{{else}}page{{/if}}.getByRole('{{role}}'{{#if exact}}, { exact: true }{{/if}}).filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}}).toBeVisible();
+{{/if}}