@sun-asterisk/sungen 3.2.12-beta.8 → 3.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.12-beta.8",
+  "version": "3.2.12",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,7 +12,7 @@
     "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && mkdir -p dist/generators/test-generator/adapters/appium/templates/steps && cp -r src/generators/test-generator/adapters/appium/templates/*.hbs dist/generators/test-generator/adapters/appium/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/appium/templates/steps dist/generators/test-generator/adapters/appium/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
     "build:dashboard": "cd ../../dashboard && npm install --silent && npm run build && cd - && cp ../../dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
-    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/exporter/overview-sheet.run.ts && tsx tests/exporter/delivery-divider-tcid.run.ts && tsx tests/exporter/note-expected-actual.run.ts && tsx tests/exporter/test-data-vars.run.ts && tsx tests/exporter/mobile-app-id.run.ts && tsx tests/exporter/api-testcase-cells.run.ts && tsx tests/exporter/delivery-cases-result.run.ts && tsx tests/exporter/precondition-auth-role.run.ts && tsx tests/exporter/report-builder-parity.run.ts && tsx tests/exporter/delivery-preflight-testdata.run.ts && tsx tests/exporter/delivery-preflight-selectors.run.ts && tsx tests/dashboard/api-flows-discovery.run.ts && tsx tests/dashboard/status-results-fallback.run.ts && tsx tests/codegen/verb-ref-masking.run.ts && tsx tests/codegen/table-aria-hidden-locators.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/api-runtime/file-upload-multipart.run.ts && tsx tests/api-runtime/schema-assertion.run.ts && tsx tests/runtime/test-data-cross-ref.run.ts && tsx tests/runtime/test-data-array-projection.run.ts &&tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/api-field-coverage/run.ts && tsx tests/packaging/run.ts && tsx tests/generate-hint/run.ts && tsx tests/template-assertion/run.ts && tsx tests/journey/run.ts && tsx tests/harness/serial-cascade.run.ts && tsx tests/ai-skills/cross-assistant-orphan.run.ts && tsx tests/init/codex-mcp-config.run.ts && tsx src/orchestrator/ai-skills/golden-skills.test.ts && tsx tests/db-runtime/sql-placeholder-rewrite.run.ts && tsx tests/db-runtime/fallback-flow-codified.run.ts && tsx tests/db-runtime/cosmos-engine.run.ts && tsx tests/db-runtime/mongodb-engine.run.ts && tsx tests/db-runtime/dynamodb-engine.run.ts && tsx tests/db-runtime/mysql-integration.opt-in.run.ts && tsx tests/db-runtime/mongodb-integration.opt-in.run.ts && tsx tests/db-runtime/dynamodb-integration.opt-in.run.ts",
+    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/exporter/overview-sheet.run.ts && tsx tests/exporter/delivery-divider-tcid.run.ts && tsx tests/exporter/note-expected-actual.run.ts && tsx tests/exporter/test-data-vars.run.ts && tsx tests/exporter/mobile-app-id.run.ts && tsx tests/exporter/api-testcase-cells.run.ts && tsx tests/exporter/delivery-cases-result.run.ts && tsx tests/exporter/precondition-auth-role.run.ts && tsx tests/exporter/report-builder-parity.run.ts && tsx tests/exporter/delivery-preflight-testdata.run.ts && tsx tests/exporter/delivery-preflight-selectors.run.ts && tsx tests/exporter/delivery-prerun-overview.run.ts && tsx tests/exporter/manual-testcase-testdata.run.ts && tsx tests/dashboard/api-flows-discovery.run.ts && tsx tests/dashboard/status-results-fallback.run.ts && tsx tests/codegen/verb-ref-masking.run.ts && tsx tests/codegen/table-aria-hidden-locators.run.ts && tsx tests/codegen/steps-base-not-compiled.run.ts && tsx tests/codegen/manual-oracle-gate.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/api-runtime/file-upload-multipart.run.ts && tsx tests/api-runtime/schema-assertion.run.ts && tsx tests/runtime/test-data-cross-ref.run.ts && tsx tests/runtime/test-data-array-projection.run.ts &&tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/api-field-coverage/run.ts && tsx tests/packaging/run.ts && tsx tests/generate-hint/run.ts && tsx tests/template-assertion/run.ts && tsx tests/journey/run.ts && tsx tests/harness/serial-cascade.run.ts && tsx tests/ai-skills/cross-assistant-orphan.run.ts && tsx tests/init/codex-mcp-config.run.ts && tsx src/orchestrator/ai-skills/golden-skills.test.ts && tsx tests/db-runtime/sql-placeholder-rewrite.run.ts && tsx tests/db-runtime/fallback-flow-codified.run.ts && tsx tests/db-runtime/cosmos-engine.run.ts && tsx tests/db-runtime/mongodb-engine.run.ts && tsx tests/db-runtime/dynamodb-engine.run.ts && tsx tests/db-runtime/mysql-integration.opt-in.run.ts && tsx tests/db-runtime/mongodb-integration.opt-in.run.ts && tsx tests/db-runtime/dynamodb-integration.opt-in.run.ts",
     "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update && tsx tests/ingest/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
   },
@@ -39,8 +39,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.12-beta.8",
-    "@sungen/driver-ui": "3.2.12-beta.8",
+    "@sungen/driver-data-factory": "3.2.12",
+    "@sungen/driver-ui": "3.2.12",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/commands/delivery.ts

@@ -291,11 +291,11 @@ export function runPreflight(cwd: string, target: DeliveryTarget): PreflightChec
     suggestions.push(`/sungen:create-test ${target.screen}`);
   }
   if (!selectorsOk) {
-    missing.push(`selectors.yaml missing entries: ${path.relative(cwd, selectorsFile)}`);
+    missing.push(`selectors.yaml missing entries (optional — filled by run-test): ${path.relative(cwd, selectorsFile)}`);
     suggestions.push(`/sungen:run-test ${target.screen}`);
   }
   if (!specOk) {
-    missing.push(`compiled .spec.ts missing: ${path.relative(cwd, specFile)}`);
+    missing.push(`compiled .spec.ts missing (optional — needed to run): ${path.relative(cwd, specFile)}`);
     suggestions.push(`sungen generate --${target.kind === 'flow' ? 'flow' : target.kind === 'api' ? 'api' : 'screen'} ${target.screen}`);
   }
   if (!resultsOk) {
@@ -371,7 +371,12 @@ function checkSelectorsHasEntries(selectorsFile: string, screen: string): boolea
 }
 
 export function hasBlockingMissing(p: PreflightCheck): boolean {
-  return !p.featureOk || !p.testDataOk || !p.selectorsOk || !p.specOk;
+  // Only the CONTENT sources block: feature + test-data are what every export row is
+  // built from. selectors / .spec.ts / test-result.json only affect execution status —
+  // when absent, delivery still exports a pre-run overview (parseSpecFile returns
+  // {tests: []}, results resolve to null) with every executable row PENDING, so QA can
+  // review the test-case list right after create-test, before the first run.
+  return !p.featureOk || !p.testDataOk;
 }
 
 // ----------------------------------------------------------------------------
@@ -664,12 +669,15 @@ function printPreflightTable(checks: PreflightCheck[]): void {
     log('');
   }
 
-  // Warn about optional misses (results.json)
-  const warnings = checks.filter((c) => !hasBlockingMissing(c) && !c.resultsOk);
+  // Warn about optional misses (selectors / .spec.ts / test-result.json). These no
+  // longer block: the export proceeds as a pre-run overview with Result = PENDING.
+  const warnings = checks.filter((c) => !hasBlockingMissing(c) && c.missing.length > 0);
   if (warnings.length > 0) {
-    log(`${COLOR.yellow}Warnings (optional missing):${COLOR.reset}`);
+    log(`${COLOR.yellow}Pre-run export (optional sources missing — executable rows will be PENDING):${COLOR.reset}`);
     for (const w of warnings) {
-      log(`  ${w.screen}: test-result.json missing — execution columns will be empty`);
+      log(`  ${COLOR.bold}${w.screen}${COLOR.reset}`);
+      for (const m of w.missing) log(`    - ${m}`);
+      for (const s of w.suggestions) log(`    ${COLOR.cyan}→ ${s}${COLOR.reset}`);
     }
     log('');
   }

package/src/exporters/result-variants.ts

@@ -5,7 +5,6 @@
  */
 import { MergedScenario } from './scenario-merger';
 import { PlaywrightResult } from './types';
-import { extractTestcaseType } from './feature-parser';
 
 export interface ResultVariant {
   /** Appended to the scenario display name: `''` for a plain scenario, ` — <label>` per
@@ -50,10 +49,12 @@ function rowLabel(row: Record<string, unknown>, i: number): string {
  * `<scenario> — <label>` — expand into one variant per EXECUTED row by matching that prefix (so an
  * already-run row carries its real pass/fail), attaching the backing dataset row by label.
  *
- * A MANUAL `@cases` scenario never executes, so that expansion can never fire — split it from the
- * DATASET instead: one variant per row (` — <label>`, no result → Pending), each carrying its row
- * so the manual tester gets one report line + its own data per case to walk and record. An auto
- * @cases scenario that has not run yet stays a single line (its expansion belongs to execution).
+ * When no row has EXECUTED yet there are no runtime titles to expand from — a MANUAL `@cases`
+ * never executes, and an auto `@cases` before its first run (the pre-run overview export) is in
+ * the same position. Both split from the DATASET instead: one variant per row (` — <label>`,
+ * no result → Pending/Manual), each carrying its row so the reader gets one report line + its
+ * own data per case. Executed rows always win (real pass/fail) — the dataset split only fills
+ * the not-yet-run gap.
  *
  * NOTE: this deliberately does NOT gate on `m.spec`. For @cases the compiled test title carries a
  * `— ${__row.__label}` suffix, so `findMatchingSpecTest` (base-name match) often leaves `m.spec`
@@ -81,7 +82,7 @@ export function resolveResultVariants(
         });
       }
     }
-    if (datasetRows && extractTestcaseType(m.feature.tags) === 'Manual') {
+    if (datasetRows) {
       return datasetRows.map((row, i) => ({ nameSuffix: ` — ${rowLabel(row, i)}`, row }));
     }
     return [{ nameSuffix: '' }];

package/src/exporters/scenario-merger.ts

@@ -21,7 +21,7 @@ import { isStepsBaseScenario, isSampleScaffoldScenario, extractTestcaseType } fr
  * 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.
  */
-function parseManualComments(comments: string[]): { steps: OrderedStep[]; expected: OrderedStep[] } {
+export function parseManualComments(comments: string[]): { steps: OrderedStep[]; expected: OrderedStep[] } {
   const steps: OrderedStep[] = [];
   const expected: OrderedStep[] = [];
   let last: OrderedStep | null = null;

package/src/exporters/spec-parser.ts

@@ -31,14 +31,21 @@ function extractTestBlock(content: string, startIdx: number): {
   // single-line, so `.*?` anchored on `}, async` is safe.
   // Accept both Playwright `test(...)` and mobile/Appium mocha `it(...)` (issue #391). The leading
   // `\b` prevents `it(` from matching the tail of a larger word like `submit(` / `edit(`.
-  const testRegex = /\b(?:test|it)\s*\(\s*(['"`])((?:\\.|(?!\1).)+)\1\s*,\s*(?:\{.*?\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
+  // A @cases title is emitted as CONCAT — `test('VP-… — ' + __row.__label, …)` (scenario.hbs) —
+  // so the closing quote is followed by `+ __row.__label` instead of the comma. Without the
+  // optional concat group the whole test() vanished from the parse and every @cases scenario
+  // exported as "Not compiled" whenever no test-result was present (the pre-run overview).
+  const testRegex = /\b(?:test|it)\s*\(\s*(['"`])((?:\\.|(?!\1).)+)\1\s*(?:\+\s*__row\.__label\s*)?,\s*(?:\{.*?\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
   testRegex.lastIndex = startIdx;
   const match = testRegex.exec(content);
   if (!match) return null;
 
   // [1] = outer quote char, [2] = title. Unescape `\'`/`\"`/backtick/backslash: the results.json
   // title is the RUNTIME string (`row's`), so the escaped source form would never match it.
-  const title = unescapeQuoted(match[2]);
+  // Concat form: the captured literal ends with the ` — ` separator the template appends
+  // before __row.__label — strip it so the title equals the feature's scenario name.
+  let title = unescapeQuoted(match[2]);
+  if (match[0].includes('__row.__label')) title = title.replace(/\s*—\s*$/, '');
   const bodyStart = match.index + match[0].length;
 
   // Find matching closing brace (accounting for nested braces)

package/src/generators/test-generator/code-generator.ts

@@ -8,6 +8,7 @@ import { DiagnosticsCollector } from './diagnostics';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities } from '../../harness/capability';
+import { parseManualComments } from '../../exporters/scenario-merger';
 
 /**
  * Filter base scenario steps for @extend: only keep Given→When steps.
@@ -168,6 +169,20 @@ function getEffectiveAuthRole(
 }
 
 
+/**
+ * True when the scenario has at least one step in the Then bucket —
+ * And/But inherit the preceding primary keyword (Given/When/Then).
+ */
+function hasThenStep(scenario: ParsedScenario): boolean {
+  let bucket = '';
+  for (const step of scenario.steps) {
+    const kw = step.keyword.trim();
+    if (kw === 'Given' || kw === 'When' || kw === 'Then') bucket = kw;
+    if (bucket === 'Then') return true;
+  }
+  return false;
+}
+
 /**
  * Check if tags contain @manual
  * @manual at feature level → skip entire feature
@@ -538,6 +553,33 @@ export class CodeGenerator {
     const renderedScenarios: Array<{ code: string; authRole?: string }> = [];
     for (const scenario of feature.scenarios) {
       if (isManual(scenario.tags)) {
+        // SG-W008 — two-direction rule for @manual scenarios:
+        //  • HAS Gherkin steps → the Gherkin must be COMPLETE: Given/When/Then. A dangling
+        //    When with no Then is invalid Gherkin, and comments can NOT substitute for the
+        //    missing Then — either add the Then, or drop the steps and move the whole
+        //    procedure into the `# Tester verifies:` block.
+        //  • NO Gherkin steps → documentation-style manual: the comments must carry the
+        //    FULL procedure the deliverable can extract — ≥1 numbered action line AND ≥1
+        //    labeled `Observable:`/`Oracle:`/`Expected:` line (parseManualComments — the
+        //    SAME parser delivery uses). Field finding (student-site, 87 scenarios): prose
+        //    paragraphs and rationale-only comments exported EMPTY Steps + Expected cells.
+        const isStructured = scenario.steps.length > 0;
+        if (isStructured && !hasThenStep(scenario)) {
+          this.diagnostics.add('SG-W008',
+            `@manual scenario "${scenario.name}" has Gherkin steps but no Then — a When without Then is invalid Gherkin. Add the Then step, or remove the steps and write the full procedure (action steps, then "Observable:"/"Oracle:" lines) in its \`# Tester verifies:\` block`,
+            { feature: feature.name, step: scenario.name });
+        } else if (!isStructured) {
+          const parsed = parseManualComments(scenario.comments ?? []);
+          if (!parsed.steps.length || !parsed.expected.length) {
+            const missing = !parsed.steps.length && !parsed.expected.length
+              ? 'numbered action steps and a labeled oracle line'
+              : !parsed.steps.length ? 'numbered action steps before the Observable/Oracle lines'
+              : 'a labeled "Observable:"/"Oracle:"/"Expected:" line';
+            this.diagnostics.add('SG-W008',
+              `@manual scenario "${scenario.name}" is documentation-style but its \`# Tester verifies:\` comments lack ${missing} — prose the delivery parser cannot extract exports EMPTY Steps/Expected cells. Use numbered lines: "1. <action>" … "N. Observable: <what>" / "Oracle: <tool>"`,
+              { feature: feature.name, step: scenario.name });
+          }
+        }
         if (this.options.verbose) {
           console.log(`  ⊘ Skipped @manual scenario: ${scenario.name}`);
         }
@@ -549,6 +591,18 @@ export class CodeGenerator {
         continue;
       }
 
+      // Skip @steps:<name> base scenarios — they are setup blocks that live ONLY inlined
+      // into @extend scenarios (stepsRegistry above). Compiling them as standalone tests
+      // duplicated coverage, skewed the Playwright count against the deliverable (the
+      // exporter rightly excludes them), and made script-check flag the extra test()
+      // as a hand-edit. Mirrors countSteps() and harness/parse loadScenarios().
+      if (scenario.stepsName) {
+        if (this.options.verbose) {
+          console.log(`  ⊘ Skipped @steps base scenario: ${scenario.name}`);
+        }
+        continue;
+      }
+
       // TQ-11 — @requires:<cap> with the cap NOT enabled → emit a clean skip stub (no driver
       // imports, so the spec still loads), visible as skipped-with-reason. With the cap enabled it
       // falls through and compiles as a real test.

package/src/generators/test-generator/diagnostics.ts

@@ -11,12 +11,16 @@
  *   SG-W006 — qa/app.<env>.yaml found (per-environment profiles are unsupported by design)
  *   SG-W007 — browser-alert handler step written AFTER an action step: the listener
  *             registers too late, an earlier dialog auto-dismisses with no error
+ *   SG-W008 — @manual scenario is incomplete in either direction: Gherkin steps without a
+ *             Then (invalid Gherkin; comments cannot substitute), or a documentation-style
+ *             manual (no steps) whose comments lack the extractable procedure — ≥1 numbered
+ *             action line + ≥1 labeled Observable:/Oracle:/Expected: line
  *
  * Diagnostics never block generation by themselves; `sungen generate --strict`
  * turns any collected diagnostic into a non-zero exit.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008';
 
 export interface Diagnostic {
   code: DiagnosticCode;

package/src/harness/audit.ts

@@ -291,7 +291,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     findings.push(`DOWNSTREAM-SCOPE-MISSING: "${d.route}" is a navigation target but is covered only by a page-nav assertion — cover its content/guards, or scaffold it (\`sungen add --screen ${d.slug}\`).`);
   }
   for (const m of manualOracleResult.insufficient.slice(0, 8)) {
-    findings.push(`MANUAL-STEPS-INSUFFICIENT: "${m}" — a @manual scenario needs setup · action · observable expected · oracle/tool (not just a one-line note).`);
+    findings.push(`MANUAL-STEPS-INSUFFICIENT: "${m}" — @manual is incomplete: either Gherkin steps without a Then (invalid Gherkin; comments can't substitute), or a documentation manual whose comments lack numbered action steps + a labeled Observable:/Oracle: line. Write \`# Tester verifies:\` as "1. <action>" … "N. Observable: <what>" / "Oracle: <tool>" — that is what the delivery parser extracts into Steps/Expected.`);
   }
   // TQ-2 — automatable @manual: deferred (usually cross-screen) but fully DSL-expressible.
   for (const m of autoManual.scenarios.slice(0, 8)) {

package/src/harness/quality-gates.ts

@@ -6,6 +6,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { ScenarioInfo, loadScenarios, idPrefix } from './parse';
+import { parseManualComments } from '../exporters/scenario-merger';
 
 // ---------- #2 Downstream-scope ----------
 
@@ -96,11 +97,27 @@ export function manualOracle(featureText: string): ManualOracleResult {
   for (const b of blocks(featureText)) {
     if (!/@manual\b/.test(b)) continue;
     manualTotal++;
-    const commentLines = b.split('\n').filter((l) => /^\s*#/.test(l));
-    const hasOracle = /tester verifies|oracle\s*:|requires|verify that|expected\s*:|steps?\s*:/i.test(b);
-    const hasNumberedSteps = /^\s*#?\s*\d+\.\s/m.test(b);
-    // sufficient = an oracle/steps marker, OR a substantive comment block (≥3 comment lines)
-    if (!(hasOracle || hasNumberedSteps || commentLines.length >= 3)) {
+    // Two-direction rule (mirrors compile-time SG-W008):
+    //  • HAS Gherkin steps → the Gherkin must be COMPLETE: Given/When/Then. A dangling
+    //    When with no Then is invalid Gherkin, and comments can NOT substitute for the
+    //    missing Then — the hybrid "steps + oracle-in-comments" shape is banned.
+    //  • NO Gherkin steps → documentation-style manual: comments must carry the FULL
+    //    procedure the deliverable can extract — ≥1 numbered action line AND ≥1 labeled
+    //    Observable:/Oracle:/Expected: line (parseManualComments — the SAME parser the
+    //    delivery exporter uses, so this gate can't drift from the exported cells).
+    //    Prose paragraphs / rationale-only comments export EMPTY Steps + Expected.
+    const hasGherkinSteps = /^\s*(Given|When|Then)\s/m.test(b);
+    let bad: boolean;
+    if (hasGherkinSteps) {
+      bad = !/^\s*Then\s/m.test(b);
+    } else {
+      const commentLines = b.split('\n')
+        .filter((l) => /^\s*#/.test(l))
+        .map((l) => l.replace(/^\s*#\s?/, ''));
+      const parsed = parseManualComments(commentLines);
+      bad = !parsed.steps.length || !parsed.expected.length;
+    }
+    if (bad) {
       const name = (b.match(/Scenario:\s*(.+)/) || [])[1] || '(unnamed)';
       insufficient.push(name.trim().slice(0, 80));
     }

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

@@ -96,7 +96,7 @@ Run (local-first): `[ -x ./bin/sungen.js ] && ./bin/sungen.js data validate --sc
 
 ### 5.6 Domain / stateful preconditions (spec + viewpoint only — no DB/API needed)
 
-If the spec describes a **stateful precondition** — an entity with relationships or a business state the test needs *before* it runs (e.g. "a paid order of user A", "a valid unused reset token ≤24h", "the session-storage buffer holds the entered values") — author a **state-recipe** in `qa/data-factory/recipes.yaml` under `resources:` (each with `entity`, `provenance`, `dependsOn`, `desiredState`, `lifecycle`, `with:` values; plus `bindings:`). Provenance is **not only api/db** — pick `prior-flow` / `fixture` / `client-storage` / `server-context` / `manual` (use `api`/`db` only when a datasource exists). Then run `data state --recipe <name>`: it validates the graph and renders a standardized **manual precondition** block (`@manual:data-setup` when it can't be auto-provisioned) to weave into the scenario's `Background`. This is the domain/stateful improvement that works with **only spec + viewpoint** — the testcase states the required state precisely instead of a vague note; it auto-provisions later if an api/db datasource is added (no rewrite). For a **journey where the same data flows across screens** (setup → confirmation → complete), declare a `shared: { entity, screens: [...] }` so one dataset is used across all of them (the Cross-artifact Gate then asserts they match).
+If the spec describes a **stateful precondition** — an entity with relationships or a business state the test needs *before* it runs (e.g. "a paid order of user A", "a valid unused reset token ≤24h", "the session-storage buffer holds the entered values") — **auto-draft it: run `… data state --scaffold <name>`** to generate a recipe skeleton from the spec's precondition sentences (one resource per signal, provenance guessed, entity as `TODO`). Then **fill each `entity`/`desiredState`/`bindings` and confirm the domain specifics with the QA** (`AskUserQuestion`) — never invent domain values. (You can also hand-author the `resources:` graph in `qa/data-factory/recipes.yaml`.) Provenance is **not only api/db** — pick `prior-flow` / `fixture` / `client-storage` / `server-context` / `manual` (use `api`/`db` only when a datasource exists). Then run `data state --recipe <name>`: it validates the graph and renders a standardized **manual precondition** block (`@manual:data-setup` when it can't be auto-provisioned) to weave into the scenario's `Background`. This is the domain/stateful improvement that works with **only spec + viewpoint** — the testcase states the required state precisely instead of a vague note; it auto-provisions later if an api/db datasource is added (no rewrite). For a **journey where the same data flows across screens** (setup → confirmation → complete), declare a `shared: { entity, screens: [...] }` so one dataset is used across all of them (the Cross-artifact Gate then asserts they match).
 
 ### 5.7 Cross-artifact check (testcase ↔ data agree)
 

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

@@ -167,7 +167,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 
    **5d. Sequential fallback.** Use the single-context incremental path (Step 2: tier-by-tier `Write`/`Edit` batches) when: only **one** shard applies, **Copilot / no sub-agents**, or a constrained setup. Same output, just no speedup. **For flows**: `[Screen:Element]` namespace refs, test-data namespaced by phase, `@flow` tag.
 
-5.3. **Standardize field test-data — Data Factory (when the unit has input fields).** Don't hand-invent per-field values — make them **standard**. For each input field, author the field-map `qa/data-factory/<name>.fields.yaml` (field → catalog `type` + the spec's real `constraints` + `errorMap` placeholder→real code), then run (Bash, local-first) `[ -x ./bin/sungen.js ] && ./bin/sungen.js data lint --screen <name> || npx sungen data lint --screen <name>` and `… data gen --screen <name>`, per the **`sungen-data-factory`** skill. `data gen` **MERGES** into `test-data.yaml` (replaces only its field keys, preserves your scenario/namespaced data), so it is safe to run here. Weave the standardized **boundary/invalid** sets into `@cases` (`Scenario Outline` + `Examples`) with `CHK-*` trace; keep the map's `errorMap`/`constraints` aligned to the spec. Then run `… data validate --screen <name>` (values are semantically correct) and — once the `.feature` exists — `… data crosscheck --screen <name>` (testcase ↔ data agree: no dangling `{{var}}`, shared datasets identical); fix any `error`. If the spec has a **stateful precondition** (an entity/state the test needs first), author a state-recipe + run `… data state` and weave its `@manual:data-setup` `Background` block (see the `sungen-data-factory` skill — works with spec+viewpoint only, no DB/API). **This is the same standard as `/sungen:create-data-test`, applied inline — so you do NOT run that command separately afterwards.** A unit with **no input fields** (navigation / list / capture-compare) → **skip this step** (nothing to standardize).
+5.3. **Standardize field test-data — Data Factory (when the unit has input fields).** Don't hand-invent per-field values — make them **standard**. For each input field, author the field-map `qa/data-factory/<name>.fields.yaml` (field → catalog `type` + the spec's real `constraints` + `errorMap` placeholder→real code), then run (Bash, local-first) `[ -x ./bin/sungen.js ] && ./bin/sungen.js data lint --screen <name> || npx sungen data lint --screen <name>` and `… data gen --screen <name>`, per the **`sungen-data-factory`** skill. `data gen` **MERGES** into `test-data.yaml` (replaces only its field keys, preserves your scenario/namespaced data), so it is safe to run here. Weave the standardized **boundary/invalid** sets into `@cases` (`Scenario Outline` + `Examples`) with `CHK-*` trace; keep the map's `errorMap`/`constraints` aligned to the spec. Then run `… data validate --screen <name>` (values are semantically correct) and — once the `.feature` exists — `… data crosscheck --screen <name>` (testcase ↔ data agree: no dangling `{{var}}`, shared datasets identical); fix any `error`. If the spec has a **stateful precondition** (an entity/state the test needs first), run `… data state --scaffold <name>` to auto-draft a recipe skeleton from the spec, **fill each `entity`/`desiredState` + confirm domain values with the QA**, then `… data state` and weave its `@manual:data-setup` `Background` block (see the `sungen-data-factory` skill — works with spec+viewpoint only, no DB/API). **This is the same standard as `/sungen:create-data-test`, applied inline — so you do NOT run that command separately afterwards.** A unit with **no input fields** (navigation / list / capture-compare) → **skip this step** (nothing to standardize).
 
 5.4. **Depth self-check (deterministic — run BEFORE the audit).** Run `sungen depth-lint --screen <name>` (Bash). It reuses the audit's businessDepth classifier and splits every shallow business-critical scenario into two actionable buckets — act on them now so the audit/repair loop doesn't burn rounds on depth:
    - **DEEPEN IN PLACE** — add a real value assertion to each (`User see all [X] contain {{v}}`, `User remember [X] as {{v}}` + `… with {{v}}`). The printed `template` is a **hint** keyed off the theme — apply judgment to the scenario's actual claim; do NOT paste a value assertion that doesn't fit (e.g. a carousel-visibility scenario should assert the product SET, not a price). If a flagged scenario is genuinely visibility/behavior (not data-correctness), that's an over-count — leave it and note it, never fake an assertion.
@@ -196,7 +196,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 4. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format. **For flows**, use the "Flow Test Generation" section in the skill. When requirements exist, use the "Requirements-Driven Generation" strategy. **For Tier 1**, apply the **Lightweight Guard** — verify required fields, validation rules, business rules, security checks, and key state transitions all have TCs after generation. **For Tier 2+**, **MUST** apply the full **Mapping Contract** — walk every `spec.md` section top-to-bottom and produce the indicated TCs per Table 1; handle `test-viewpoint.md` per Table 2. Do not silently skip sections. Present sections as a numbered list and let user pick.
 5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills. Generate **group-by-group** (one viewpoint group at a time, tier-by-tier `Write`/`Edit` batches) to stay under the output-token cap. **For flows**: use `[Screen:Element]` namespace format, namespace test-data by phase, add `@flow` tag. **If a scenario needs `@query` DB verification**, check the datasource `engine` first — unsupported engine → follow `sungen-gherkin-syntax` § "Unsupported DB engine — fallback" instead of authoring `@query` steps.
    > **No parallel fan-out here.** Copilot has no sub-agents, so generation is sequential (the Claude Code variant fans out one `sungen-generator` per viewpoint group and merges). Same output, no speedup.
-5.3. **Standardize field test-data — Data Factory (when the unit has input fields).** For each input field, author the field-map `qa/data-factory/<name>.fields.yaml` (field → catalog `type` + real `constraints` + `errorMap`), then run `sungen data lint --screen ${input:name}` and `sungen data gen --screen ${input:name}` per the **`sungen-data-factory`** skill. `data gen` **MERGES** into `test-data.yaml` (replaces only its field keys, preserves the rest), so it is safe here. Weave the standardized boundary/invalid sets into `@cases` with `CHK-*` trace. Then `… data validate` (values correct) + `… data crosscheck` (testcase↔data agree); for a stateful precondition, author a state-recipe + `… data state` and weave its `@manual:data-setup` `Background` (works spec+viewpoint only). **Same standard as `/sungen:create-data-test`, applied inline — do NOT run that command separately afterwards.** No input fields (navigation/list) → skip.
+5.3. **Standardize field test-data — Data Factory (when the unit has input fields).** For each input field, author the field-map `qa/data-factory/<name>.fields.yaml` (field → catalog `type` + real `constraints` + `errorMap`), then run `sungen data lint --screen ${input:name}` and `sungen data gen --screen ${input:name}` per the **`sungen-data-factory`** skill. `data gen` **MERGES** into `test-data.yaml` (replaces only its field keys, preserves the rest), so it is safe here. Weave the standardized boundary/invalid sets into `@cases` with `CHK-*` trace. Then `… data validate` (values correct) + `… data crosscheck` (testcase↔data agree); for a stateful precondition, `… data state --scaffold <name>` to auto-draft → fill entities + confirm with QA → `… data state`, weave the `@manual:data-setup` `Background` (works spec+viewpoint only). **Same standard as `/sungen:create-data-test`, applied inline — do NOT run that command separately afterwards.** No input fields (navigation/list) → skip.
 5.4. **Depth self-check (deterministic — BEFORE the audit).** Run `sungen depth-lint --screen ${input:name}`. It splits every shallow business-critical scenario into **DEEPEN IN PLACE** (add a real value assertion — the printed `template` is a theme-keyed hint, apply judgment to the actual claim; never fake one onto a visibility/behavior scenario) and **CROSS-SCREEN** (route to a flow / tag `@manual:Mx` + reason — removes it from the depth denominator honestly). Act on both, re-run until `deepen` is empty (or only honest over-counts remain), THEN gate. Lifts first-pass `businessDepth` mechanically instead of via 2–3 repair rounds.
 5.5. **Quality gate & repair (harness — always run).** Per `sungen-harness-audit`: run `sungen audit --screen ${input:name}` (structural), THEN do an **independent semantic review inline** using the `sungen-reviewer` criteria (does each scenario's steps PROVE its title/viewpoint? observable Thens? business-critical assertion depth?). Merge both sets of issues; if gate FAILs / findings exist, repair (budget 3) and re-audit — GATE missing theme → generate it (cross-screen → **automate it in the flow** via `/sungen:add-flow`, NOT a full `@manual` screen duplicate — `sungen audit` flags an automatable `@manual` as `MANUAL-AUTOMATABLE`; reserve `@manual:Mx` for true judgment/missing-capability); DEPTH → add data assertions; BALANCE → add business-core first; TRACE → align VP ids. Never fake a pass.
 5.6. **Record.** `sungen manifest --screen ${input:name}`. Ledger **each phase** (not just repair) — pick one `runId` at the start and pass it so `trace`/`ledger report` show THIS run, not a mix: `sungen ledger record --screen ${input:name} --run <runId> --step <discovery|viewpoint|gherkin|audit|repair:N> --ms <elapsed>`. On re-run, start with `sungen manifest --screen ${input:name} --diff` and only regenerate changed sections.

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

@@ -15,6 +15,17 @@ Turn a screen/flow's fields into **standardized test data** — not guessed valu
 Data Factory is **bundled with core** (runtime-free) — no `capability add` needed; the `sungen data …`
 CLI is available out of the box.
 
+**Auto-detection (act on these, don't wait to be asked).** `sungen generate`/`sungen audit` now NOTICE
+the work a unit needs, even before any field-map exists:
+- **`DATA-FACTORY-UNSTANDARDIZED`** — the unit has input fields but no `qa/data-factory/<name>.fields.yaml`.
+  → author the field-map + `data gen` (this skill's main job).
+- **`DATA-FACTORY-PRECONDITION-UNDECLARED`** — the spec describes a stateful precondition (a required
+  entity/state) but the test declares none. → **auto-draft a state-recipe** from the spec sentence, run
+  `sungen data state`, and weave its `@manual:data-setup` `Background`; confirm the drafted values with
+  the QA (`AskUserQuestion`) — never invent domain values.
+When you see either finding, do the work rather than leaving it — that is what makes Sungen self-driving
+instead of a toolbox the QA must operate.
+
 ## The 4-source method (phuong-phap-tao-test-data.md)
 
 Never invent values from memory. Cross-reference four sources — each covers the previous one's gap:
@@ -139,6 +150,12 @@ Field values are not enough when a test needs a **business state first** — "a
 a **`provenance`** (`prior-flow` | `fixture` | `client-storage` | `server-context` | `manual` |
 `api` | `db`), optional `dependsOn`, `desiredState`, `lifecycle` (`reusable`/`consumable`/`expiring`/
 `leased`/`mutable-state`/`unique-per-run`), and `with:` values — plus `bindings:` (`orderId: ${order.id}`).
+**Auto-draft it — don't make the QA hand-write it.** When the spec describes a precondition (or you saw
+a `PRECONDITION-UNDECLARED` finding), run **`sungen data state --scaffold <unit>`**: it drafts a recipe
+skeleton from the spec's precondition sentences (one resource per signal, provenance guessed, entity
+left as `TODO`). Then **fill each `entity` + `desiredState`/`bindings` from the spec and confirm the
+domain specifics with the QA (`AskUserQuestion`)** — never invent domain values.
+
 Run **`sungen data state`**: it validates the graph (cycles, dangling deps, bindings) and renders a
 standardized **manual precondition** block — tagged **`@manual:data-setup`** when it can't be
 auto-provisioned — to weave into the scenario's `Background`. **This works with only spec + viewpoint:
@@ -147,15 +164,55 @@ a resource uses `api`/`db` provenance (+ a `provider:` endpoint), the *same* rec
 rewrite. For a **journey where the same data flows across screens** (setup → confirmation → complete),
 add `shared: { entity, screens: [...] }` so one dataset is used across all of them.
 
+## One QA-facing door: `/sungen:create-test`
+
+QA never needs to remember which `sungen data …` sub-command to run. **`/sungen:create-test` is the
+single entry** — it standardizes fields, validates, cross-checks, and drafts any stateful precondition
+inline. The `sungen data gen|lint|validate|crosscheck|state|provenance|fixture` commands are the
+**deterministic plumbing** the create-test loop (and CI) drives; run them directly only for a targeted
+re-standardize. `/sungen:create-data-test` is the same pipeline on demand (re-standardize after editing
+a field-map/`.overwrite`, or a unit authored before Data Factory) — not a step you must invoke after
+create-test.
+
 ## Cross-artifact check — testcase ↔ data agree
 
 `data validate` checks the data alone; **`sungen data crosscheck`** checks the testcase and its data
-AGREE: no dangling `{{var}}` (every referenced var has a value), a cross-screen `shared` dataset is
-identical across the journey (confirmation shows what setup entered), and a declared state-precondition
-is surfaced in the feature. Run it after the `.feature` exists; fix any `error`. Together
-`data validate` + `data crosscheck` are the **Data Gate + Cross-artifact Gate** (the `data-only`
-harness profile). Every `data gen` also stamps a `_fingerprint` (catalog+generator+context hash) so a
-reader/cache can tell whether the inputs that produced the data changed.
+AGREE **and are COMPLETE**: no dangling `{{var}}`; a cross-screen `shared` dataset is identical across
+the journey; a declared state-precondition is surfaced; **and — even when you author `@cases` by hand
+instead of merging `data gen` — the authored values COVER the BVA the field-map's constraints require
+and the login experience checklist**:
+- **`BVA_UNCOVERED`** — a bounded dimension is missing a boundary value. Classic miss: `email
+  minLength: 5` → you must have an email of length **4 (invalid), 5, 6**; a URL/code of length 5 does
+  NOT count (matched by type). Add the missing values (the exact BVA is in `data gen`'s output) or waive.
+- **`EXPERIENCE_UNCOVERED`** — a login/auth unit is missing credential-state scenarios: **soft-deleted**,
+  locked, unverified, password-expired, **valid-with-surrounding-whitespace** (trim → accept). Add each
+  (a seeded account in that state) or waive per spec.
+
+Treat these as MUST-ADDRESS in the create-test loop — they are exactly the gaps a QA reviewer catches.
+Together `data validate` + `data crosscheck` are the **Data Gate + Cross-artifact + Coverage Gate** (the
+`data-only` profile). Every `data gen` also stamps a `_fingerprint` (catalog+generator+context hash).
+
+## Boundary completeness + trim
+
+Boundary Value Analysis is **complete by construction**: for every bounded dimension in the field-map's
+`constraints` — including ones the field-type's catalog didn't model (e.g. an **email `minLength`**) —
+the generator auto-emits the full set **min-1 (invalid) · min · min+1 · max-1 · max · max+1 (invalid)**.
+So a spec "email min 5" yields length 4 (invalid), 5, 6 — don't hand-add them. Text fields also carry a
+**leading/trailing-whitespace** case (trim behaviour: the server must trim then accept, or reject per
+spec — confirm). If `data validate`/the QA still finds a missing boundary, it means the constraint was
+absent from the field-map — add it there.
+
+## Login / authentication screens — credential-state cases (experience)
+
+A login screen is not just field-format validation. The catalog carries an **experience checklist**
+(`auth-account-states`) of credential/account STATES a login must cover — each a scenario, most needing
+a domain-state precondition (a seeded account in that state; declare it with a state-recipe →
+`@manual:data-setup` Background):
+- **active** (happy path) · **wrong-password** · **non-existent** (same generic error — anti-enumeration)
+- **soft-deleted** (must NOT authenticate — real-world bug precedent) · **locked/suspended** ·
+  **unverified-email** · **password-expired** · **valid-with-surrounding-whitespace** (trim → accept).
+When the unit is a login/auth screen, generate these as scenarios (confirm the exact outcome/message
+code with the spec). Do not assume the outcome — ask the QA for states the spec doesn't pin.
 
 ## Weaving into scenarios
 

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

@@ -48,8 +48,8 @@ Source modules: `src/exporters/*.ts`
 | 4 | Compiled spec | `specs/generated/<name>/<name>.spec.ts` | `specs/generated/flows/<name>/<name>.spec.ts` | `sungen generate` |
 | 5 | Test results | `specs/generated/<name>/<name>-test-result.json` or `test-results/results.json` | `specs/generated/flows/<name>/<name>-test-result.json` or global fallback | `run-test` |
 
-**Sources 1-4 are blocking** — CLI aborts if any is missing.
-**Source 5 is optional** — CSV is still generated but Test Result/Date/Executor/Env columns are empty (all tests show as Pending).
+**Sources 1-2 are blocking** (they are what every export row is built from) — CLI aborts if either is missing.
+**Sources 3-5 are optional** — when selectors/spec/results are absent, delivery still exports a **pre-run overview**: content columns (Steps · Expected results · Test Data · Precondition) are complete from the feature + test-data, and every executable row shows **Pending**. This is the intended path for QA to review the test-case list right after `create-test`, before the first `run-test`. Once `.spec.ts`/results exist they are picked up automatically — no flag needed.
 
 The CLI reads the **per-target result file first** (co-located with `.spec.ts`), then falls back to the global `test-results/results.json`. Per-target is preferred because the global file gets OVERWRITTEN each time Playwright runs, losing results from earlier targets.
 

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

@@ -91,6 +91,7 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W005` | `qa/app.yaml` unknown key / unknown preset / unparseable | Fix the key, or `extends: native\|radix\|antd` |
 | `SG-W006` | `qa/app.<env>.yaml` found — unsupported by design | Describe the app once in `qa/app.yaml`; env differences belong in test-data overlays |
 | `SG-W007` | Browser-alert handler step written AFTER an action — listener registers too late, the dialog auto-dismisses silently | Use the compound form `click [X] button and accept [OK] alert` (preferred), or move the alert step before the trigger |
+| `SG-W008` | `@manual` scenario incomplete in either direction: (a) HAS Gherkin steps but NO `Then` — a dangling `When` is invalid Gherkin, comments can NOT substitute; (b) documentation-style (NO steps) but its comments lack numbered action lines and/or a labeled oracle line — prose paragraphs / rationale-only comments export EMPTY Steps + Expected cells | Two valid shapes only: complete the Gherkin with a `Then`, or write the FULL procedure in the `# Tester verifies:` block as NUMBERED lines — action steps first (`1. <action>`), then labeled `Observable:`/`Oracle:`/`Expected:` lines (the number is what fills Steps, the label is what fills Expected results) |
 
 ### Assertion errors → apply the Source-of-truth gate above FIRST
 

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

@@ -317,7 +317,11 @@ Security:         [S1 – admin only]
 3. **Claim-Proof** (`CLAIM-UNPROVEN`) — a title claiming `all`/`only`/`every`/`single`/`correct`/`same`/`changes`/`hidden`/`cleared`/`restored`/`independent`/`sanitized`/`announces` MUST have the matching assertion (`see all …`, count, `remember`+compare, `is hidden`, return-and-assert-empty, etc.). If the title promises it, the steps must prove it.
    - **Negative / absence claims** (`does not` / `no` / `never` / `prevents` / `không` / `chưa` — any language; `no-side-effect/no-duplicate`, `negative-claim/absence`): the `Then` must **differ** between the claim holding and not holding. A terminal `see [X] page` that looks identical whether or not the bad thing happened proves nothing. For a side-effect that should NOT repeat (re-submit on back, re-charge, duplicate order, resend OTP), assert the **count is unchanged** (`User see [Records] table with {{one}}` / `row with {{count}}`); if it's not UI-observable, mark `@manual` with a request-count oracle (shape below). This is general — it covers any side-effect, not a fixed verb list.
 4. **Downstream-scope** (`DOWNSTREAM-SCOPE-MISSING`) — when the spec's Navigation Flow / success target is **another screen** (e.g. a confirmation/sent page), don't stop at a terminal `see [X] page`. Either cover that screen's content/guards (if its viewpoint items are in scope — they often have their own `MS-*` IDs), or scaffold it (`sungen add --screen <name>`) and note the handoff. Do not silently drop the downstream surface.
-5. **Manual-oracle** (`MANUAL-STEPS-INSUFFICIENT`) — every `@manual` scenario needs **setup · action · observable expected · oracle/tool**, not a one-line note. Use this comment shape:
+5. **Manual-oracle** (`MANUAL-STEPS-INSUFFICIENT` at audit, `SG-W008` at generate) — a `@manual` scenario has exactly TWO valid shapes; the hybrid (Gherkin steps with the oracle stashed in comments) is **banned**:
+   - **Shape A — documentation-style** (NO Gherkin steps at all): the whole procedure lives in comments — numbered **action steps first**, then labeled `Observable:`/`Oracle:` lines. Use whenever the expected is unconfirmed (SPEC-GAP) or any part of the procedure is outside the DSL (password manager, DevTools, browser zoom/viewport, multi-tab, DB seeding). Do NOT keep a stray Gherkin fragment (`Given … page` + one fill) — a `When` without `Then` is invalid Gherkin, and a partial fragment can INVERT the chronology (e.g. "save a credential first" rendering AFTER "open the page").
+   - **Shape B — complete Gherkin**: `Given/When/Then`, all steps present. Use when the expected IS known and only execution is manual.
+   Gate (`SG-W008`, both directions): a `@manual` with Gherkin steps but no `Then` fires — comments (even labeled `Oracle:` lines) can NOT substitute for the missing `Then`. A `@manual` with NO steps ALSO fires when its comments lack ≥1 numbered action line + ≥1 labeled `Observable:`/`Oracle:`/`Expected:` line — prose paragraphs and rationale-only comments export EMPTY Steps/Expected cells.
+   In shape A the observable/oracle lines MUST carry their **label** (`Observable:` / `Oracle:` / `Expected:`) — the delivery parser extracts Expected results **by label**; unlabeled prose all lands in the Steps column and the Expected cell exports EMPTY. And the numbered action steps MUST precede them — without the actions the tester has an oracle but no procedure. Use this comment shape:
    ```gherkin
    @high @manual
    Scenario: VP-… <claim>
@@ -325,8 +329,8 @@ Security:         [S1 – admin only]
      # Tester verifies:
      #   1. <setup>            e.g. seed a registered email; throttle the network
      #   2. <action>           e.g. click [Submit] with the request in flight
-     #   3. <observable>       e.g. only ONE POST is dispatched
-     #   4. Oracle: <tool>     e.g. DevTools Network panel / mail-catcher / NVDA
+     #   3. Observable: <what> e.g. Observable: only ONE POST is dispatched
+     #   4. Oracle: <tool>     e.g. Oracle: DevTools Network panel / mail-catcher / NVDA
    ```
 
 #### Tier 1 guard — minimum before writing scenarios