@sun-asterisk/sungen 3.2.12-beta.9 → 3.2.13

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/adapters/playwright/templates/steps/actions/hover-element-with-text.hbs

@@ -0,0 +1 @@
+await {{> locator-base}}.filter({ hasText: {{> has-text-value dataValue=dataValue exact=exact legacyTail=(and (eq strategy "text") (eq value ""))}} }){{> locator-nth}}.hover();

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

@@ -0,0 +1 @@
+await expect({{> locator-base}}.filter({ hasText: {{> has-text-value dataValue=dataValue exact=exact legacyTail=(and (eq strategy "text") (eq value ""))}} }){{> locator-nth}}).toBeVisible();

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/generators/test-generator/utils/runtime-data-transformer.ts

@@ -5,11 +5,17 @@ const MARKER_PATTERN = /__SUNGEN_TD_([A-Za-z0-9_]+)__/;
  * Three passes: comments, string literals, then regex literals.
  */
 export function transformToRuntimeData(code: string, accessor: string = 'testData'): string {
-  // Pass 0: Comments — replace markers in // comments with decoded key name
-  // Prevents Pass 2 from misinterpreting // comment markers as regex delimiters
+  // Pass 0: Comments — replace markers in // comments with decoded key name.
+  // Prevents Pass 2 from misinterpreting // comment markers as regex delimiters.
+  // ANCHORED to line start (^\s*//) so a `//` INSIDE a string literal on a code line
+  // — e.g. a URL `https://careerforum.aki-inc.jp/` in a selector name — is NOT mistaken
+  // for a comment. Before this anchor, such a URL preceding a marker on the same line
+  // made Pass 0 strip the marker to its bare key, so Pass 1 never wrapped it in
+  // testData.get() (silent: `toHaveAttribute('href', 'official_site_url')`). Generated
+  // comments are always full-line, so anchoring loses nothing.
   code = code.replace(
-    /\/\/(.*)__SUNGEN_TD_([A-Za-z0-9_]+)__(.*)/g,
-    (_, before, enc, after) => `//${before}${decodeKey(enc)}${after}`
+    /^(\s*)\/\/(.*)__SUNGEN_TD_([A-Za-z0-9_]+)__(.*)$/gm,
+    (_, indent, before, enc, after) => `${indent}//${before}${decodeKey(enc)}${after}`
   );
 
   // Pass 1: String literal context — handles both whole-string and embedded markers

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/skills/sungen-data-factory/SKILL.md

@@ -177,12 +177,42 @@ 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

@@ -76,6 +76,7 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | Error | Diagnosis | Fix |
 |---|---|---|
 | strict mode violation | Multiple elements match | Add `nth: 0`, `exact: true`, or more specific `name` |
+| strict mode violation on `see`/`hover [X] item\|option\|cell with {{v}}` (dynamic list) | Older builds didn't filter the locator by the value | Since 3.2.13 `see`/`hover ... with {{v}}` on list-member roles filters by `hasText` like `click` (existence/hover the matching item) — keep the step data-driven, don't add per-item selectors. Update sungen if still unfiltered |
 | Timeout / not found | Element doesn't exist or name wrong | Re-snapshot → copy exact accessible name. Check iframe/dialog scope |
 | Element is not an input | Wrong element type targeted | Change `type` or `value` to match actual element |
 | not a select | Custom dropdown, not native `<select>` | Set the widget variant: `variant: radix-select`/`antd-select` (built-in recipes), a custom recipe name from `qa/app.yaml`, or project-wide `widgets.select` in `qa/app.yaml` |
@@ -91,6 +92,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