@sun-asterisk/sungen 3.2.12-beta.1 → 3.2.12-beta.10

package/src/exporters/csv-exporter.ts

@@ -25,7 +25,7 @@ import {
 import { ApiCatalogEntry, EnvironmentInfo, PlaywrightResult, ScreenSummary, TestCaseRow } from './types';
 import { collectSecretValues, formatApiExpected, formatApiRequest, hasApiCalls, redactSecrets } from './api-testcase-formatter';
 import { SelectorKeyMap, substituteSelectorKeysInStep } from './selector-key-resolver';
-import { resolveResultVariants } from './result-variants';
+import { formatVariantRow, resolveResultVariants } from './result-variants';
 
 export interface BuildCsvInput {
   screen: string;
@@ -70,7 +70,7 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
     // Data-driven (@cases): expand to one CSV row per executed dataset input (Playwright titles
     // "<scenario> — <label>"); plain scenarios resolve their single result. Shared with the
     // dashboard/JSON exporter via resolveResultVariants so the two can't drift on @cases handling.
-    const variants = resolveResultVariants(m, input.results);
+    const variants = resolveResultVariants(m, input.results, input.testData);
 
    for (const variant of variants) {
     const displayName = `${m.feature.name}${variant.nameSuffix}`;
@@ -132,7 +132,11 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
     // Multi-line bullet format keeps delivery CSV/XLSX in sync with the
     // dashboard's Test data section. Multi-line CSV cells are valid (quoted
     // automatically) and render natively as multi-line in XLSX.
-    const testData = formatTestData(m.feature.referencedVars, input.testData, Infinity, '\n');
+    let testData = formatTestData(m.feature.referencedVars, input.testData, Infinity, '\n');
+    // @cases: each report line shows ITS OWN dataset row (executed auto rows and manual
+    // split rows both carry variant.row) — one line per case, one dataset per line.
+    const variantRow = formatVariantRow(variant, '\n');
+    if (variantRow) testData = testData ? `${testData}\n${variantRow}` : variantRow;
 
     // Status for this (possibly per-input) row — resolved into `variant` above.
     const result: PlaywrightResult | undefined = variant.result;

package/src/exporters/feature-parser.ts

@@ -9,7 +9,7 @@ import { FeatureMetadata, OrderedStep, ScenarioMetadata } from './types';
 /**
  * Variables referenced in a scenario: find all {{var_name}} in step text.
  */
-function extractReferencedVars(scenario: ParsedScenario): string[] {
+function extractReferencedVars(scenario: ParsedScenario, includeComments = false): string[] {
   const vars = new Set<string>();
   for (const step of scenario.steps) {
     const matches = step.text.matchAll(/\{\{([a-zA-Z_][a-zA-Z0-9_.-]*)\}\}/g);
@@ -28,6 +28,19 @@ function extractReferencedVars(scenario: ParsedScenario): string[] {
       }
     }
   }
+  // Manual scenarios carry their real tester procedure in `# Tester verifies:` comment
+  // blocks — the {{var}} refs there are the data the tester needs, so include them
+  // (issue: manual test cases exported with an empty Test Data cell). Automated
+  // scenarios keep step-only scanning: their comments are notes (SPEC-GAP etc.) and
+  // would only add noise vars to the delivery report.
+  if (includeComments) {
+    for (const line of scenario.comments ?? []) {
+      const matches = line.matchAll(/\{\{([a-zA-Z_][a-zA-Z0-9_.-]*)\}\}/g);
+      for (const match of matches) {
+        vars.add(match[1]);
+      }
+    }
+  }
   return Array.from(vars);
 }
 
@@ -85,7 +98,7 @@ export function parseFeatureMetadata(featureFilePath: string): FeatureMetadata {
       tags: [...parsed.tags, ...sc.tags],
       stepsName: sc.stepsName,
       extendsName: sc.extendsName,
-      referencedVars: extractReferencedVars(sc),
+      referencedVars: extractReferencedVars(sc, extractTestcaseType([...parsed.tags, ...sc.tags]) === 'Manual'),
       rawGivenSteps: given,
       rawWhenSteps:  when,
       rawThenSteps:  then,

package/src/exporters/json-exporter.ts

@@ -23,7 +23,7 @@ import {
 } from './playwright-report-parser';
 import { ApiCatalogEntry, EnvironmentInfo, PlaywrightResult } from './types';
 import { SelectorKeyMap, substituteSelectorKeysInStep } from './selector-key-resolver';
-import { resolveResultVariants } from './result-variants';
+import { formatVariantRow, resolveResultVariants } from './result-variants';
 import {
   ScenarioSnapshot,
   ScreenSnapshot,
@@ -123,13 +123,17 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
     }
     // Dashboard modal uses whitespace-pre-wrap — pass '\n' to render one
     // key/value per line instead of the CSV-friendly "; " join.
-    const testDataStr = formatTestData(m.feature.referencedVars, input.testData, Infinity, '\n');
+    const baseTestDataStr = formatTestData(m.feature.referencedVars, input.testData, Infinity, '\n');
 
-    // @cases scenarios expand to one snapshot entry per executed dataset row (shared with the CSV
-    // exporter via resolveResultVariants), so their per-row pass/fail is counted — not collapsed
-    // into one Pending/N/A entry as before.
-    const variants = resolveResultVariants(m, input.results ?? null);
+    // @cases scenarios expand to one snapshot entry per executed dataset row — and manual
+    // @cases split per DATASET row (shared with the CSV exporter via resolveResultVariants),
+    // so their per-row pass/fail is counted — not collapsed into one Pending/N/A entry.
+    const variants = resolveResultVariants(m, input.results ?? null, input.testData);
     for (const variant of variants) {
+      // Per-line Test Data: shared vars + THIS variant's dataset row (parity with csv-exporter).
+      let testDataStr = baseTestDataStr;
+      const variantRow = formatVariantRow(variant, '\n');
+      if (variantRow) testDataStr = testDataStr ? `${testDataStr}\n${variantRow}` : variantRow;
       const displayName = `${m.feature.name}${variant.nameSuffix}`;
       const { vpId, category1 } = splitVpAndName(displayName);
       const tcId = generateTcId(input.screen, vpId, fallbackIndex);

package/src/exporters/result-variants.ts

@@ -5,12 +5,42 @@
  */
 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 executed
+  /** Appended to the scenario display name: `''` for a plain scenario, ` — <label>` per
    *  @cases dataset row (so each row gets a distinct category1). */
   nameSuffix: string;
   result?: PlaywrightResult;
+  /** The @cases dataset row backing this variant — lets the exporters render the row's own
+   *  columns into the Test Data cell (`__`-prefixed bookkeeping keys excluded). Present on
+   *  executed auto rows (matched by label) and on manual split rows. */
+  row?: Record<string, unknown>;
+}
+
+/**
+ * Read the `@cases:<name>` dataset rows for a scenario from the (flattened) test-data map.
+ * `loadTestData()` flattens arrays to JSON strings — accept that shape and raw arrays.
+ * Scalar rows normalize to `{ value }`, mirroring the runtime TestDataLoader.cases().
+ */
+export function getCasesDatasetRows(
+  m: MergedScenario,
+  testData: Record<string, string> | null | undefined,
+): Array<Record<string, unknown>> | null {
+  const tag = m.feature.tags.find((t) => t.startsWith('@cases:'));
+  if (!tag || !testData) return null;
+  let list: unknown = testData[tag.slice('@cases:'.length)];
+  if (typeof list === 'string') {
+    try { list = JSON.parse(list); } catch { return null; }
+  }
+  if (!Array.isArray(list) || list.length === 0) return null;
+  return list.map((row) =>
+    row && typeof row === 'object' && !Array.isArray(row) ? (row as Record<string, unknown>) : { value: row });
+}
+
+/** Display label of a dataset row — mirrors the runtime TestDataLoader.cases() rule. */
+function rowLabel(row: Record<string, unknown>, i: number): string {
+  return String(row.case ?? row.name ?? row.label ?? `row ${i + 1}`);
 }
 
 /**
@@ -18,9 +48,12 @@ export interface ResultVariant {
  *
  * A `@cases:<dataset>` scenario compiles to one `test()` per dataset row, whose Playwright title is
  * `<scenario> — <label>` — expand into one variant per EXECUTED row by matching that prefix (so an
- * already-run row carries its real pass/fail). A plain scenario resolves its single result by the
- * spec test title. With no results — or a @cases scenario with no matching result yet — a lone
- * variant with no result is returned, so the caller marks it Pending / N/A.
+ * 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).
  *
  * 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`
@@ -30,13 +63,26 @@ export interface ResultVariant {
 export function resolveResultVariants(
   m: MergedScenario,
   results: Map<string, PlaywrightResult> | null,
+  testData?: Record<string, string> | null,
 ): ResultVariant[] {
   const isCases = m.feature.tags.some((t) => t.startsWith('@cases:'));
-  if (isCases && results) {
-    const marker = `${m.feature.name} — `;
-    const rows = [...results.entries()].filter(([t]) => t.includes(marker));
-    if (rows.length) {
-      return rows.map(([t, r]) => ({ nameSuffix: ` — ${t.slice(t.indexOf(marker) + marker.length)}`, result: r }));
+  if (isCases) {
+    const datasetRows = getCasesDatasetRows(m, testData);
+    const byLabel = new Map<string, Record<string, unknown>>();
+    (datasetRows ?? []).forEach((row, i) => byLabel.set(rowLabel(row, i), row));
+
+    if (results) {
+      const marker = `${m.feature.name} — `;
+      const ran = [...results.entries()].filter(([t]) => t.includes(marker));
+      if (ran.length) {
+        return ran.map(([t, r]) => {
+          const label = t.slice(t.indexOf(marker) + marker.length);
+          return { nameSuffix: ` — ${label}`, result: r, row: byLabel.get(label) };
+        });
+      }
+    }
+    if (datasetRows && extractTestcaseType(m.feature.tags) === 'Manual') {
+      return datasetRows.map((row, i) => ({ nameSuffix: ` — ${rowLabel(row, i)}`, row }));
     }
     return [{ nameSuffix: '' }];
   }
@@ -45,3 +91,16 @@ export function resolveResultVariants(
   }
   return [{ nameSuffix: '' }];
 }
+
+/**
+ * Render a variant's dataset row for the Test Data cell: one `col: value` line per column,
+ * `__`-prefixed bookkeeping keys excluded. Returns '' when the variant carries no row.
+ */
+export function formatVariantRow(variant: ResultVariant, separator: string = '\n'): string {
+  if (!variant.row) return '';
+  const useBullet = separator.includes('\n');
+  return Object.entries(variant.row)
+    .filter(([k]) => !k.startsWith('__'))
+    .map(([k, v]) => `${useBullet ? '• ' : ''}${k}: ${v}`)
+    .join(separator);
+}

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

@@ -133,6 +133,7 @@ function truncate(s: string, max: number): string {
   return s.substring(0, max - 1) + '…';
 }
 
+
 /**
  * Resolve `{{var}}` test-data placeholders in a step / expected-result line to their concrete values,
  * so the delivery report shows what QA actually verifies (e.g. `text contains {{app_version}}` →

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

@@ -90,9 +90,21 @@ Run (local-first): `[ -x ./bin/sungen.js ] && ./bin/sungen.js data lint --screen
 
 Run (local-first): `[ -x ./bin/sungen.js ] && ./bin/sungen.js data gen --screen <name> || npx sungen data gen --screen <name>`. If `test-data/<name>.yaml` already exists it **merges** the standardized field data in — it **replaces only the field keys it owns and preserves every other key** (create-test's data, flow-namespaced keys, `@cases` datasets, overrides). It asks before merging (in ALL mode after they confirmed, add `--yes`; `--force` skips the prompt). The output is standardized `valid/boundary/invalid` values with `CHK-*` traceability.
 
+### 5.5 Validate semantic correctness
+
+Run (local-first): `[ -x ./bin/sungen.js ] && ./bin/sungen.js data validate --screen <name> || npx sungen data validate --screen <name>`. This is stronger than lint (coverage): it checks every generated value is **semantically** correct — each `valid`/`boundary` value actually satisfies the constraints, and each synthesized `invalid` value actually violates them (a value in the `valid` set that breaks `maxLength`, or a "below min" case that landed inside the range, is a `VALUE_NOT_VALID` error). Fix any `error`; `INVALID_LOOKS_VALID` warns are a prompt to confirm the value is invalid for a non-length reason (charset/format). Each generated value also carries an `expected: valid|invalid` field in the test-data for traceability.
+
+### 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") — **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)
+
+Run (local-first): `… data crosscheck --screen <name>`. It verifies the testcase and its test-data agree: no dangling `{{var}}` (every referenced var has a value), any cross-screen **shared** dataset is identical across the journey, and a declared state-precondition is surfaced in the feature. Fix any `error`. This is the `data-only` harness profile — `data validate` (values correct) + `data crosscheck` (values match the test); together they are the deterministic Data Gate + Cross-artifact Gate.
+
 ### 6. Weave into scenarios (if create-test already ran)
 
-If the `.feature` exists, turn the generated invalid/boundary sets into data-driven `Scenario Outline` + `Examples` (`@cases`) referencing the values — following `sungen-gherkin-syntax`. Otherwise leave the standardized `test-data/<name>.yaml` for `/sungen:run-test` to consume.
+If the `.feature` exists, turn the generated invalid/boundary sets into data-driven `Scenario Outline` + `Examples` (`@cases`) referencing the values — following `sungen-gherkin-syntax`. Weave any `data state` precondition block into the `Background`. Otherwise leave the standardized `test-data/<name>.yaml` for `/sungen:run-test` to consume.
 
 ## After running
 

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. **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. **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:
@@ -85,20 +96,26 @@ This is the core discipline: *common is never enough; when blind, think and ask
 ## Customizing the catalog — `.overwrite` (survives `sungen update`)
 
 The shipped `common/` is a floor. Project rules go in `qa/data-factory/common.overwrite.yaml`,
-deep-merged over the common (**later-wins**, keyed by `type` + data-point `id`): same `id` replaces,
-new `id` appends, `constraints` merge key-by-key. `sungen update` refreshes `common/` but never
-touches your overlay. If an update makes an overlay entry stale (references a bank/constraint that no
-longer exists), the loader **warns you to prune it** — it never edits your file. Prefer a targeted
-`errorMap`/`constraints` in the field-map for per-screen tweaks; use `.overwrite` only for rules that
-apply project-wide.
+deep-merged over the common (**later-wins**, keyed by `type` + data-point `id`) via three explicit
+operations: **EXTEND** (a new `id` appends), **REPLACE** (same `id` wins; `constraints` merge
+key-by-key), **DISABLE** (list ids under `disable:` to drop shipped cases that don't apply — a stale
+target id warns). You can also override `security:` banks and `techniques:` the same way. `sungen
+update` refreshes `common/` but never touches your overlay; a stale entry **warns you to prune it** —
+it never edits your file. Nothing is silently overwritten: **`sungen data provenance`** (and a
+`⟲ .overwrite →` line at `data gen`) shows exactly what your overlay changed, and each overlaid value
+is tagged `via: .overwrite` in the test-data. Prefer a targeted `errorMap`/`constraints` in the
+field-map for per-screen tweaks; use `.overwrite` only for rules that apply project-wide.
 
 ## Bulk-import fixtures (CSV)
 
 For CSV/Excel import or bulk-upload testing, `sungen data fixture --screen <name> [--rows N] [--invalid]`
 turns the field-map into a fixture FILE under `qa/fixtures/`: `<name>.csv` (N valid rows; nested groups
 → dotted headers; `unique` fields row-indexed) that should import cleanly, and — with `--invalid` —
-`<name>.invalid.csv` (one seeded-bad row per field + a `_violation` column) for row-level rejection
-tests. Reference it from an `@api` upload (`files:`) or a UI file input.
+`<name>.invalid.csv` (one seeded-bad row per field, **same columns as the valid file so a strict
+importer fails on the data, not an extra column**) plus a **sidecar** `<name>.invalid.expected.yaml`
+that says which 0-based row must be rejected and why (`field`, `chk`, `reason`, `expected_error`).
+Reference the CSV from an `@api` upload (`files:`) or a UI file input, and assert row rejection against
+the sidecar.
 
 ## Verify before done — the phuong-phap §6 checklist
 
@@ -109,6 +126,86 @@ Then `sungen data gen` writes the standardized `test-data/<name>.yaml`. Do not h
 generated values — change the field-map or `.overwrite` and re-run (determinism: same input → same
 data).
 
+Then run **`sungen data validate`** — the semantic check beyond coverage. It verifies each generated
+value is *correct*, not just *present*: every `valid`/`boundary` value actually satisfies the
+constraints and every synthesized `invalid` value actually violates them. A boundary is expanded to
+**one case per point** (`min / min+1` → two cases; `< min` → min-1, below the minimum), each stamped
+`expected: valid|invalid` in the output. Any `VALUE_NOT_VALID` error means a value labeled valid breaks
+a constraint — fix the field-map/constraints and re-run. This is what stops the "structurally right but
+semantically wrong" data (e.g. a "below minimum length" case that is actually long enough to pass).
+
+**Applicability & profiles.** The generator only emits cases that apply, and reports the rest (never
+silent). Set **`required: true|false`** correctly — an optional field drops the "empty (required)" case;
+a numeric field with `min ≥ 0` drops the negative example. Security/injection payloads land in their own
+**`adversarial:`** bucket, separate from `invalid:`. Dropped cases show up as `_not_applicable` in the
+output + a `NOT_APPLICABLE` lint info. A `--profile` (`regression` default · `functional` · `smoke` ·
+`security-min`) and `--locale`/`--channel`/`--sink` on `data gen|validate|lint` select a reduced set;
+selection is deterministic. Prefer setting `required` in the field-map over disabling the empty case.
+
+## Domain / stateful preconditions (spec + viewpoint only — no DB/API)
+
+Field values are not enough when a test needs a **business state first** — "a paid order of user A",
+"a valid unused reset token ≤24h", "the session-storage buffer holds the entered values". Declare a
+**state-recipe** in `qa/data-factory/recipes.yaml` under `resources:` — each resource has an `entity`,
+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:
+provenance is usually `prior-flow`/`fixture`/`manual`, NOT DB/API.** If a datasource is later added and
+a resource uses `api`/`db` provenance (+ a `provider:` endpoint), the *same* recipe auto-provisions — no
+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.
+
+## 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
 
 When a `.feature` exists, express invalid/boundary sets as data-driven `Scenario Outline` + `Examples`