@sun-asterisk/sungen 3.2.33 → 3.2.34

package/src/exporters/csv-exporter.ts

@@ -6,7 +6,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getPackageVersion } from './package-info';
-import { MergedScenario } from './scenario-merger';
+import { MergedScenario, extractManualReason } from './scenario-merger';
 import {
   extractAuthRole,
   extractPriority,
@@ -27,6 +27,7 @@ import { collectSecretValues, formatApiCallSummaryLines, formatApiExpected, form
 import { SelectorKeyMap, substituteSelectorKeysInStep } from './selector-key-resolver';
 import { formatVariantRow, resolveResultVariants } from './result-variants';
 import { collectQaEnvSecretDenylist, warnIfRedactionIncomplete } from './qa-env-secret-denylist';
+import { formatEnv } from './run-environment';
 
 export interface BuildCsvInput {
   screen: string;
@@ -207,6 +208,11 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
       testResult = testcaseType === 'Manual' ? 'Pending' : 'N/A';
       if (testcaseType !== 'Manual') {
         note = 'Scenario not compiled — re-run `sungen generate --screen ' + input.screen + '`';
+      } else {
+        // Why the case is manual — the `# MANUAL: …` comment — so the tester reading the
+        // deliverable knows what blocks automation (#810). Empty when no reason is written.
+        const reason = extractManualReason(m.feature.comments ?? []);
+        if (reason) note = redactSecrets(`Manual: ${reason}`, qaEnvSecrets.values);
       }
     } else {
       // Compiled but no execution record → Pending
@@ -290,15 +296,6 @@ export function buildSummary(screen: string, rows: TestCaseRow[], outputFile: st
  * the baseURL so the deliverable shows the exact URL each test targets
  * (e.g. `https://staging.example.com/kudos (chromium)`).
  */
-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})`;
-}
-
 function csvCell(v: string | number | undefined | null): string {
   if (v === null || v === undefined) return '';
   const s = String(v);

package/src/exporters/json-exporter.ts

@@ -5,7 +5,7 @@
  * richer ScenarioSnapshot / ScreenSnapshot shape used by the dashboard UI.
  */
 
-import { MergedScenario } from './scenario-merger';
+import { MergedScenario, extractManualReason } from './scenario-merger';
 import {
   extractAuthRole,
   extractPriority,
@@ -192,6 +192,7 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
       let testEnvironment: string | undefined;
       let testExecutor: string | undefined;
       let type: ScenarioSnapshot['type'];
+      let manualReason: string | undefined;
 
       if (result) {
         // A result exists → the scenario compiled AND ran; authoritative over the `!m.spec`
@@ -224,6 +225,9 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
         // No result AND no compiled test → Manual if @manual, else genuinely not compiled.
         type = baseType === 'Manual' ? 'Manual' : 'Not compiled';
         status = baseType === 'Manual' ? 'Pending' : 'N/A';
+        // Same Note source as csv-exporter: the `# MANUAL: …` reason (#810).
+        const reason = baseType === 'Manual' ? extractManualReason(m.feature.comments ?? []) : '';
+        if (reason) manualReason = redactSecrets(reason, qaEnvSecrets.values);
       } else {
         // Compiled but no execution record → Pending.
         type = baseType;
@@ -249,6 +253,7 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
         executedDate,
         errorMessage,
         tracePath,
+        manualReason,
         testEnvironment,
         testExecutor,
       });

package/src/exporters/manual-hybrid-oracle.ts

@@ -0,0 +1,112 @@
+/**
+ * The @manual "presence placeholder" hybrid (#810) — one predicate for every stage.
+ *
+ * Shape: a @manual scenario keeps complete Gherkin, but its only assertions are bare presence
+ * checks (`Then User see [Job List] table`), while the REAL oracle ("the newer row appears above
+ * the older one") sits in an unlabelled `# Tester verifies:` comment. Both gates only asked "is
+ * there a Then?", and the exporter only captures numbered comment lines — so the deliverable said
+ * "See [Job List] table" and a tester ticking it Passed recorded a check nobody made.
+ *
+ * The compile gate (SG-W008), the audit gate (MANUAL-STEPS-INSUFFICIENT) and both exporters read
+ * the comment block through THIS module, so the three can never disagree about what the oracle is.
+ */
+
+export interface KeywordStep {
+  /** Gherkin keyword as written: Given / When / Then / And / But (surrounding space allowed). */
+  keyword: string;
+  /** Step text without the keyword. */
+  text: string;
+}
+
+const NUMBERED = /^\d+[.)]\s*/;
+const DIVIDER = /^[-=*_]{2,}/;
+const HEADER = /^tester verifies\b\s*:?\s*(.*)$/i;
+const LABELLED_ORACLE = /^\d+[.)]\s*[A-Za-z /]*?(observ|oracle|expect|result|then|assert)[A-Za-z /]*:/i;
+
+/**
+ * The prose a `Tester verifies:` header carries when it is NOT written as numbered lines — the
+ * text on the header line itself plus the lines after it, up to the first numbered item or divider.
+ * Returns null when the block is empty (a bare header followed by numbered items is the structured
+ * shape, not this one) or when there is no header at all. Only the FIRST header's block is read —
+ * a second `Tester verifies:` ends it.
+ */
+export function extractUnlabeledOracle(comments: string[]): string | null {
+  const parts: string[] = [];
+  let inBlock = false;
+  for (const raw of comments) {
+    const line = raw.trim();
+    if (!inBlock) {
+      const m = line.match(HEADER);
+      if (!m) continue;
+      inBlock = true;
+      if (m[1].trim()) parts.push(m[1].trim());
+      continue;
+    }
+    if (!line) continue;
+    if (NUMBERED.test(line) || DIVIDER.test(line) || HEADER.test(line)) break;
+    parts.push(line);
+  }
+  const text = parts.join(' ').replace(/\s+/g, ' ').trim();
+  return text ? text : null;
+}
+
+/** True when the comments state an oracle — a labelled numbered line, or unlabelled header prose. */
+export function hasCommentOracle(comments: string[]): boolean {
+  return comments.some((c) => LABELLED_ORACLE.test(c.trim())) || extractUnlabeledOracle(comments) !== null;
+}
+
+/**
+ * A bare presence assertion: the element exists, nothing about its content, order, count or state.
+ * `User see [Job List] table` / `User is on [Home] page` / `User see [Save] button is visible`.
+ * Anything after the element type (`match data:`, `with {{v}}`, `row 2`, `is sorted …`) is a real check.
+ */
+export function isPresenceOnlyAssertion(text: string): boolean {
+  return /^User (?:see|is on) \[[^\]]+\](?: [a-z]+)?(?: (?:is|are) (?:visible|displayed|shown))?\s*$/i.test(text.trim());
+}
+
+/**
+ * True when no assertion checks anything beyond presence — including when there is no assertion
+ * at all (a documentation-style manual). Only then may unlabelled comment prose stand in as the
+ * oracle: a Then that already asserts content/order/count IS the oracle, and replacing it with the
+ * prose would drop the real check from the deliverable.
+ */
+export function onlyPresenceAssertions(assertionTexts: string[]): boolean {
+  return assertionTexts.every(isPresenceOnlyAssertion);
+}
+
+/** The scenario's assertion steps — a Then, plus every And/But whose preceding explicit keyword is Then. */
+export function assertionSteps(steps: KeywordStep[]): KeywordStep[] {
+  let bucket = '';
+  const out: KeywordStep[] = [];
+  for (const s of steps) {
+    const kw = s.keyword.trim();
+    if (kw === 'Given' || kw === 'When' || kw === 'Then') bucket = kw;
+    if (bucket === 'Then') out.push(s);
+  }
+  return out;
+}
+
+/**
+ * The banned hybrid: ≥1 assertion, every assertion a bare presence placeholder, and an oracle in
+ * the comments. A @manual whose Gherkin already asserts something real is fine — its comments are
+ * an elaboration, not the only statement of what the case checks.
+ */
+export function isPresencePlaceholderHybrid(steps: KeywordStep[], comments: string[]): boolean {
+  const asserts = assertionSteps(steps);
+  return asserts.length > 0 && onlyPresenceAssertions(asserts.map((s) => s.text)) && hasCommentOracle(comments);
+}
+
+/** Split raw scenario-block lines into keyword steps (for the text-based audit gate). */
+export function keywordStepsOf(block: string): KeywordStep[] {
+  const out: KeywordStep[] = [];
+  for (const line of block.split('\n')) {
+    const m = line.match(/^\s*(Given|When|Then|And|But)\s+(.+?)\s*$/);
+    if (m) out.push({ keyword: m[1], text: m[2] });
+  }
+  return out;
+}
+
+/** Comment lines of a raw scenario block, with the leading `# ` stripped. */
+export function commentLinesOf(block: string): string[] {
+  return block.split('\n').filter((l) => /^\s*#/.test(l)).map((l) => l.replace(/^\s*#\s?/, ''));
+}

package/src/exporters/matrix/build.ts

@@ -158,11 +158,14 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
     // fields — Setup → precondition (review B-02), Action → trigger, Observable →
     // expected, Oracle → verification method. Labels never remain inside prose.
     const manual = mode === 'manual' && m.feature.comments?.length
-      ? classifyManualComments(m.feature.comments)
+      ? classifyManualComments(m.feature.comments, bucketTexts(m.feature.orderedSteps, 'then'))
       : null;
 
     // Raw (pre-wording) step texts — these feed shapes + Gate C, never the cells.
-    const rawTrigger = manual ? manual.actions : bucketTexts(m.feature.orderedSteps, 'when');
+    // A manual with no numbered action lines keeps its Gherkin When steps as the trigger — the
+    // same fallback the oracle uses for Then. Taking comment actions only rendered "No action —
+    // the state is checked on page load." for a manual whose When clicks something (#810).
+    const rawTrigger = manual && manual.actions.length > 0 ? manual.actions : bucketTexts(m.feature.orderedSteps, 'when');
     const rawOracle = manual
       ? (manual.expected.length > 0 ? manual.expected : bucketTexts(m.feature.orderedSteps, 'then'))
       : m.resolvedExpected.filter((s) => s.bucket === 'then').map((s) => s.text);
@@ -593,6 +596,7 @@ export function buildMatrix(inputs: BuildInputs): MatrixModel {
         [v.ref, v.precondition.filter((line) => !commonPre.includes(line))])),
       triggerDeltas: Object.fromEntries(groupVariants.map((v) =>
         [v.ref, v.trigger.slice(prefixLen)])),
+      sharedTriggerSteps: prefixLen,
       // Nothing shared to hoist → say what varies rather than leaving the cell blank.
       trigger: prefixLen > 0 || groupVariants.length === 0
         ? (first?.trigger ?? []).slice(0, prefixLen)

package/src/exporters/matrix/export.ts

@@ -26,6 +26,7 @@ import { renderMatrixXlsx } from './render-xlsx';
 import { renderMatrixCsv } from './render-csv';
 import { DeliveryMap, MatrixFinding, MatrixModel } from './types';
 import { ApiCatalogEntry } from '../types';
+import { RunEnvironment } from '../run-environment';
 
 export interface MatrixTargetPaths {
   cwd: string;
@@ -46,6 +47,8 @@ export interface MatrixTargetPaths {
   specMdFile?: string;
   resultsPath: string | null;
   mapFile: string;
+  /** Executor + environment of the run (#850) — absent for gates-only callers (inspect, approve). */
+  runEnv?: RunEnvironment;
 }
 
 function readSpecText(paths: MatrixTargetPaths): string {
@@ -91,6 +94,7 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     specText: readSpecText(paths),
     apiCatalog: catalogFor(paths),
   });
+  model.runEnv = paths.runEnv;
   // Perf verdict (#569): budgets are config (qa/perf.yaml), samples are the run's
   // per-test durations. Advisory — reported here because delivery is where runs
   // are read; the audit's score stays a pure function of the design artifacts.

package/src/exporters/matrix/gates.ts

@@ -102,6 +102,12 @@ function gateASource(ctx: GateContext, findings: MatrixFinding[]): void {
           : `scenario ${vpId} has no Then step — a variant without an observable oracle cannot be delivered`,
       });
     }
+    if (m.unlabeledManualOracle) {
+      findings.push({
+        gate: 'A', severity: 'warning', ref: vpId,
+        message: `manual oracle found only in an unlabeled comment — exported verbatim into Expected; write the \`# Tester verifies:\` block as numbered "N. Observable: …" lines`,
+      });
+    }
   }
   for (const [vpId, n] of seen) {
     if (n > 1) findings.push({ gate: 'A', severity: 'error', ref: vpId, message: `duplicate VP-id ${vpId} (${n} scenarios)` });

package/src/exporters/matrix/render-testcase-sheet.ts

@@ -17,6 +17,7 @@ import * as ExcelJS from 'exceljs';
 import { renderReportHeaderBand, ARIAL_FONT } from '../xlsx-report-builder';
 import { redactSecrets } from '../api-testcase-formatter';
 import { clipNoteField } from '../playwright-report-parser';
+import { runCells } from '../run-environment';
 import { variantState } from './build';
 import { DeliveryItem, MatrixModel } from './types';
 import { SOFT_BLUE, DRAFT_RED, RESULT_STATES, dataCell, headerCell, draftBanner } from './xlsx-cells';
@@ -42,6 +43,9 @@ export const RESULT_COL = 12;
 
 /** Variant sub-row — only what distinguishes it from its parent (review GAP-01). */
 function variantValues(item: DeliveryItem, v: DeliveryItem['variants'][number], model: MatrixModel): ExcelJS.CellValue[] {
+  // Who ran it and against what — the same cells the legacy workbook fills (#850); blank
+  // until the variant has actually run.
+  const run = runCells(model.runEnv, v.result);
   return [
     v.ref,
     '',
@@ -50,15 +54,17 @@ function variantValues(item: DeliveryItem, v: DeliveryItem['variants'][number],
     numbered(item.preconditionDeltas[v.ref] ?? []),
     numbered(v.data),
     // Only the steps after the parent's shared prefix, numbered so the parent's
-    // steps + these read as one continuous procedure.
-    numbered(item.triggerDeltas[v.ref] ?? [], item.trigger.length + 1),
+    // steps + these read as one continuous procedure. Counted from the REAL shared
+    // steps, not `trigger.length`: with nothing shared the parent shows a generated
+    // "the action differs…" note, and the variant's first step read "2." (#848).
+    numbered(item.triggerDeltas[v.ref] ?? [], item.sharedTriggerSteps + 1),
     expectedWithVerification(v.oracle, v.verification),
     v.traces.join(', '),
     variantTypeLabel(v),
     variantState(v),
     isoDate(v.result?.startTime),
-    '',
-    '',
+    run.executor,
+    run.environment,
     // Redact BEFORE clipping — same denylist as the testcases CSV Note column.
     v.result?.error ? clipNoteField(redactSecrets(String(v.result.error), model.secretValues)) : '',
   ];

package/src/exporters/matrix/types.ts

@@ -176,8 +176,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 +257,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;
 
@@ -229,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;
 
@@ -255,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/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

@@ -11,6 +11,7 @@
 import { FeatureMetadata, OrderedStep, ScenarioMetadata, SpecFileData, SpecTest } from './types';
 import { isStepsBaseScenario, isSampleScaffoldScenario, 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;
 }
 
 /**
@@ -147,7 +182,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 +202,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/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;
 }
 
 /**