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

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

@@ -0,0 +1,111 @@
+---
+name: create-data-test
+description: "Generate standardized test-data for a screen/flow from the Data Factory catalog — valid/boundary/invalid values with CHK-* traceability (no free-form guessing)"
+argument-hint: [screen-or-flow-name]
+order: 25
+claude-tools: "Read, Grep, Bash, Glob, Write, Edit, AskUserQuestion, Skill"
+copilot-tools: "[vscode, execute, read, agent, edit, search, todo]"
+codex-trigger: "Run when the user asks to CREATE, generate, or standardize TEST DATA / test values for a screen or flow (valid/boundary/invalid, boundary values, negative data). Uses the Data Factory driver. Not for generating the .feature scenarios themselves (that is create-test)."
+---
+
+**Input**: A screen or flow name (e.g., `/sungen:create-data-test login`), OR **no name** to do every unit (with a confirmation — see ALL mode). Load the `sungen-data-factory` skill for the full method.
+
+> **When to use.** `/sungen:create-test` already standardizes field test-data via Data Factory **inline** (its step 5.3), so you normally do **not** need this command as a follow-up. Use it **on demand** to *re-standardize*: after you edit a field-map or the `.overwrite`, for a unit authored before Data Factory existed, to refresh error-code mappings, or to (re)generate across many units at once (ALL mode). It MERGES into existing test-data (never clobbers).
+
+## Role
+
+You are a **Senior QA Engineer** producing **test data to a standard**, not by guessing. You do NOT invent values field-by-field. You follow the 4-source method (spec rules → field-type catalog → design technique → DB mapping), driven by the **Data Factory** capability driver. Values come from the catalog (`common/` + the project's `.overwrite`), each tagged with a `CHK-*` id that traces back to the spec. Where the catalog cannot cover a project-specific field, you **ask the QA** — you never fabricate domain data.
+
+## Preconditions
+
+1. **Availability** — Data Factory is **bundled with core** (no `capability add` needed); its CLI (`sungen data …`) is available out of the box. Just continue.
+2. Determine mode from `$ARGUMENTS`:
+   - A **name** given → single-unit mode (that screen/flow only).
+   - **No name** → **ALL mode** (see below — always confirm first).
+
+## ALL mode (no name) — confirm before doing everything
+
+If no name was given, the user wants **all** screens/flows — but this is wide, and a missing name is often a typo (they meant `create-data-test home`). So:
+
+1. List every unit under `qa/screens/*` and `qa/flows/*`, and classify each as **new** (no `test-data/<name>.yaml` yet) vs **would-overwrite**.
+2. Show the list and use `AskUserQuestion` to confirm: *"Generate test-data for ALL N units? (X new · Y would overwrite)"* — default to **No**.
+3. Only proceed when the user confirms. Then run the per-unit flow below for each (the CLI `sungen data gen --all` also enforces this confirm; `--yes` after the user agrees).
+
+## Per-unit flow (single unit, or each unit in ALL mode)
+
+Auto-detect: `qa/flows/<name>/` → flow; else `qa/screens/<name>/` → screen. (API units carry their contract in `apis.yaml` — data there is `@cases` in create-test, not this command.)
+
+### 1. Read the sources (Nguồn 1 + 4)
+
+Read `qa/<screens|flows>/<name>/requirements/spec.md` and `test-viewpoint.md`. For **each input field / parameter**, extract:
+- data **type** (map to a catalog field-type: email · password · phone · string · number-integer · number-float · currency · postcode · katakana …),
+- `required`, format, **min/max** length or value,
+- the real **error/message code** the spec shows when a rule is violated,
+- any **DB mapping** (unique, cross-entity dependency) noted in the spec.
+
+Viewpoint tells you which fields are high-priority → give them the fullest data.
+
+**No input fields → nothing to generate.** If the unit is a pure navigation / listing / capture-compare flow (e.g. a home-shopping browse flow) with **no user-input fields or parameters**, Data Factory has nothing to standardize. Report *"`<name>`: no input fields → nothing to generate"* and stop for this unit — do **not** write an empty `qa/data-factory/<name>.fields.yaml`. (Its scenarios are covered by create-test's data, not by field-level test data.)
+
+### 2. Write the field-map — `qa/data-factory/<name>.fields.yaml`
+
+This is the input the deterministic generator expands. One entry per field:
+
+```yaml
+screen: <name>            # or: flow: <name>
+fields:
+  - name: email
+    type: email
+    required: true
+    unique: true                                   # fresh-per-run (register email won't collide)
+    constraints: { maxLocal: 64, maxTotal: 254 }   # project's real limits
+    errorMap: { M13: E1042, M02: E1001 }            # catalog placeholder → project's real code
+  - name: password
+    type: password
+    constraints: { minLength: 8, maxLength: 32 }
+```
+
+**`unique: true`** — set it for a field that must be **different every run** (register email/username that can't clash with a record a previous run created). The valid value then gets a runtime `{{$timestamp}}` (email → `user+{{$timestamp}}@…`), so each run is fresh — no cross-run cache, no order-dependent flakiness. Boundary/invalid values stay literal (they test rules, not record creation).
+
+Map every placeholder error code you can (`errorMap`) to the spec's real code. Leave a code unmapped only if the spec truly has none — the lint will flag it as an open point to confirm with BA/Dev.
+
+**Complex forms — nested & dependent fields.** For a grouped/object field, give it **`fields:`** (sub-fields, expanded recursively; no `type` on the group). For a field whose rule depends on another, add **`dependsOn: { field: <other>, value: <v> }`** — it's recorded as a note so the scenario/`@cases` honor it (the generator doesn't resolve the runtime condition):
+```yaml
+fields:
+  - name: address                       # group → nested object
+    fields:
+      - { name: city, type: string, constraints: { maxLength: 50 } }
+      - { name: postcode, type: postcode, dependsOn: { field: country, value: JP } }
+```
+
+### 3. Blind spots — ask, do not invent
+
+If a field's type is **not** in the catalog (a business enum, a cross-entity constraint, a project data model), **stop and ask the QA** with `AskUserQuestion` for: (1) the valid set, (2) invalid / non-existent values, (3) the error code when wrong, (4) dependencies on other fields. Record the answer in `qa/data-factory/project/<entity>.yaml` for reuse. Never fabricate domain values.
+
+### 4. Lint the coverage
+
+Run (local-first): `[ -x ./bin/sungen.js ] && ./bin/sungen.js data lint --screen <name> || npx sungen data lint --screen <name>`. Fix what it reports: add missing boundary values, resolve `UNRESOLVED` items (supply the constraint), map `OPEN_ERRORREF` codes. The bar is the phuong-phap §6 checklist — every required field has valid + boundary + invalid, one invalid per rule.
+
+### 5. Generate the test-data
+
+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`. 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
+
+Use `AskUserQuestion` to offer the next step: review the generated data, run `/sungen:create-test <name>` (if scenarios don't exist yet), or `/sungen:run-test <name>`.

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

@@ -167,6 +167,8 @@ 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), 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.
    - **CROSS-SCREEN** — route to a flow (`/sungen:add-flow`) or tag `@manual:Mx` + reason; do NOT fake an on-screen data assertion. This removes it from the screen's depth denominator honestly.
@@ -194,6 +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, `… 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/dist/orchestrator/templates/ai-src/commands/run-test.md

@@ -127,6 +127,7 @@ If the unit is **api-first**, skip every selector/capture phase (an API test has
 ## Pre-run (phased — per `sungen-selector-fix` skill)
 
 1. Verify `<base>/<name>/` has `.feature` + `test-data.yaml`. **If the feature has `@query` steps**, check the resolved datasource `engine` in `qa/datasources.yaml` — unsupported engine → follow the `sungen-gherkin-syntax` skill § "Unsupported DB engine — fallback" before compiling (do not attempt a direct connect).
+1.5. **Data Factory pre-check (before running)** — Data Factory is bundled with core, so whenever a field-map exists (`qa/data-factory/<name>.fields.yaml`), confirm the test-data is standardized and covers each field before you run: `[ -x ./bin/sungen.js ] && ./bin/sungen.js data lint --screen <name> || npx sungen data lint --screen <name>`. If it reports coverage gaps (missing boundary/invalid, unresolved values, unmapped error codes) or the field-map is newer than `test-data/<name>.yaml`, refresh via `/sungen:create-data-test <name>` (or `sungen data gen --screen <name>`) — then compile. Blind spots (a `type` not in the catalog) are for the QA to answer, not to invent. No field-map / driver disabled → skip this step.
 2. **Phase 0 — Selector Pre-gen**: if `selectors.yaml` is missing/empty or doesn't cover the feature file's `[Reference]`s, apply the following decision tree before running Phase 0 from `sungen-selector-fix`:
 
    ```

package/dist/orchestrator/templates/ai-src/config/claude.md

@@ -18,14 +18,16 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
 | `sungen-capture` | Acquire visual/design context — one skill, 4 modes: figma-mcp (Dev Mode MCP), figma-pat (URL → spec_figma.md), live (Playwright MCP scan), local (images in `requirements/ui/`) |
 | `sungen-locale` | Bootstrap i18n — audit selectors, detect locale switch mechanism, generate test-data overlay |
+| `sungen-data-factory` | Standardized test-data — field-type/security catalog, 4-source method, `.overwrite`, blind-spot prompts |
 
-## Workflow (7 AI commands)
+## Workflow (8 AI commands)
 
 | Command | What it does |
 |---|---|
 | `/sungen:add-screen <name> <path>` | Scaffold `qa/screens/<name>/` directories |
 | `/sungen:add-flow <name> [--path <url>]` | Scaffold `qa/flows/<name>/` directories for E2E cross-screen testing |
 | `/sungen:create-test <name>` | Generate `.feature` + `test-data.yaml` (auto-detects screen or flow) |
+| `/sungen:create-data-test <name>` | Generate standardized test-data (valid/boundary/invalid + CHK trace) from the Data Factory catalog; no name = all units (asks to confirm) |
 | `/sungen:review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
 | `/sungen:run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
 | `/sungen:delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |

package/dist/orchestrator/templates/ai-src/config/copilot.md

@@ -18,14 +18,16 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
 | `sungen-capture` | Acquire visual/design context — one skill, 4 modes: figma-mcp (Dev Mode MCP), figma-pat (URL → spec_figma.md), live (Playwright MCP scan), local (images in `requirements/ui/`) |
 | `sungen-locale` | Bootstrap i18n — audit selectors, detect locale switch mechanism, generate test-data overlay |
+| `sungen-data-factory` | Standardized test-data — field-type/security catalog, 4-source method, `.overwrite`, blind-spot prompts |
 
-## Workflow (7 AI commands)
+## Workflow (8 AI commands)
 
 | Command | What it does |
 |---|---|
 | `/sungen-add-screen <name> <path>` | Scaffold `qa/screens/<name>/` directories |
 | `/sungen-add-flow <name> [--path <url>]` | Scaffold `qa/flows/<name>/` directories for E2E cross-screen testing |
 | `/sungen-create-test <name>` | Generate `.feature` + `test-data.yaml` (auto-detects screen or flow) |
+| `/sungen-create-data-test <name>` | Generate standardized test-data (valid/boundary/invalid + CHK trace) from the Data Factory catalog; no name = all units (asks to confirm) |
 | `/sungen-review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
 | `/sungen-run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
 | `/sungen-delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |

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

@@ -0,0 +1,213 @@
+---
+name: sungen-data-factory
+description: 'Use when create-data-test (or create-test) needs standardized TEST DATA — valid/boundary/invalid values for input fields with CHK-* traceability. Drives the Data Factory catalog + the 4-source method. Invoke after reading spec.md, when authoring the field-map or filling test-data.'
+user-invocable: false
+---
+
+## What this skill does
+
+Turn a screen/flow's fields into **standardized test data** — not guessed values. You author a
+**field-map**; the deterministic `sungen data gen` expands it from the Data Factory **catalog**
+(field-type + security + technique library) into valid / boundary / invalid values, each carrying a
+`CHK-*` id that traces to the spec. Your judgment goes into *reading the spec correctly* and
+*answering blind spots* — never into inventing values the catalog or the QA should own.
+
+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:
+
+1. **Spec validate rules** — required, format, min/max, business rules, and the **error/message code**
+   per rule. Defines the legal/illegal boundary. (Says the *law*, not every way to *break* it.)
+2. **Field-type catalog** — the accumulated "how this type breaks" knowledge (email/password/phone/
+   number/…). This is the Data Factory `common/` — it fills the "spec doesn't list every break" gap.
+3. **Design technique** — Boundary Value Analysis / Equivalence Partitioning / Decision Table / State
+   Transition — reduces the rule + candidates to a *minimal-but-sufficient* representative set.
+4. **DB mapping** — unique constraints, cross-entity dependency, real backend limits → precondition
+   data, not just a single input value.
+
+Then classify every value into **Valid / Boundary / Invalid** (each invalid tagged with its error
+code) and give it a `CHK-*` id for traceability.
+
+## The field-map — `qa/data-factory/<name>.fields.yaml`
+
+Your main artifact. One entry per input field; the generator expands it:
+
+```yaml
+screen: login                 # or  flow: <name>
+fields:
+  - name: email
+    type: email               # a catalog field-type (see list below)
+    required: true
+    constraints: { maxLocal: 64, maxTotal: 254 }   # the project's REAL limits from spec
+    errorMap: { M13: E1042, M02: E1001 }            # catalog placeholder code → project's real code
+  - name: password
+    type: password
+    constraints: { minLength: 8, maxLength: 32 }
+```
+
+**Catalog field-types** (P1): `email` · `password` · `phone` · `string` · `number-integer` ·
+`number-float` · `currency` · `postcode` · `katakana` (JP). Security payload banks auto-append to a
+field's invalid group via the type's `uses_security` (`sqli`, `xss`, `idor`, `broken-auth`, `upload`,
+`input-validation`).
+
+Rules:
+- Pick the closest `type`; put the project's real numbers in `constraints` (they override the
+  catalog defaults).
+- Map every `errorRef` placeholder (`M13`, `M39`, …) to the spec's real code via `errorMap`. Leave
+  one unmapped **only** if the spec has none — the lint flags it as an open point to confirm.
+- **Complex forms:** a **group** field takes nested **`fields:`** (recursive; no `type` on the group → renders a nested object like `address.city`). A field whose rule depends on another takes **`dependsOn: { field, value }`** — recorded as a `_depends_on` note (the generator doesn't resolve the runtime condition; weave it into the scenario/`@cases`).
+- Set **`unique: true`** on a field that must be fresh every run (register email/username, anything
+  that would clash with a record a previous run left behind). Its valid value then carries a runtime
+  `{{$timestamp}}` (email → `user+{{$timestamp}}@…`) so each run is unique — no cross-run cache
+  (which would make tests order-dependent/flaky). Prefer this over caching prior-run values. For
+  reusing a value produced earlier **within the same run** (register → then log in with it), bind it
+  via the scenario (`@dataFactory` recipe / `testData.bind`), not a cross-run cache.
+
+## No input fields → nothing to generate
+
+Data Factory standardizes **field-level input data**. If a unit has no user-input fields or
+parameters — a pure navigation, listing, or capture-compare flow — there is nothing to generate.
+Report *"no input fields → nothing to generate"* and skip it; do **not** write an empty field-map.
+Those scenarios are covered by the data create-test already produced, not by field-level test data.
+(This is a correct outcome, not a gap — don't force a field-map to make the unit "processed".)
+
+## Blind spots — ask, never fabricate
+
+If a field's type is **not** in the catalog — a business enum, a cross-entity constraint, a
+project-specific data model — do **not** guess. Ask the QA (via `AskUserQuestion`) for: (1) the valid
+set, (2) invalid / non-existent values, (3) the error code when wrong, (4) dependencies on other
+fields. Record it in `qa/data-factory/project/<entity>.yaml` so it becomes reusable project catalog.
+This is the core discipline: *common is never enough; when blind, think and ask — don't invent.*
+
+## 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`) 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, **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
+
+Run `sungen data lint` and clear it: every required field has **≥1 valid**, **boundary present**
+(exact min/max, not only over-boundary) for bounded types, **≥1 invalid per rule** (not one generic
+"wrong" value for many rules), no `UNRESOLVED` values, error codes mapped or explicitly left open.
+Then `sungen data gen` writes the standardized `test-data/<name>.yaml`. Do not hand-edit the
+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`
+(`@cases`) referencing the values — see `sungen-gherkin-syntax`. This keeps one logic + many values
+instead of copy-pasted scenarios, and each row carries its `CHK-*` id for traceability.

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

@@ -6,6 +6,7 @@ user-invocable: false
 
 ## ⚠️ Gotchas — read before generating
 
+- **Field-level test-data follows the Data Factory standard — don't hand-invent values.** When the unit has input fields, the field values (valid / boundary / invalid + error codes) come from the **`sungen-data-factory`** catalog via a field-map + `sungen data gen` (create-test step 5.3), not free-form guessing. Weave the standardized boundary/invalid sets into `@cases` with `CHK-*` trace. This skill still owns scenario structure, viewpoints, and non-field oracles.
 - **Write incrementally — never emit the whole suite in one response.** Build the `.feature` in batches via successive `Write`/`Edit` (≈10–15 scenarios per call). For **Full coverage**, write tier-by-tier: `Write` Tier 1 → `Edit` append Tier 2 → `Edit` append Tier 3.
   → One huge `Write` can exceed the model's output-token cap → `API Error: Claude's response exceeded the N output token maximum`. Single-pass full coverage only fits when `CLAUDE_CODE_MAX_OUTPUT_TOKENS ≥ 64000`; otherwise batch. Batching also lets the audit/reviewer run per batch — higher quality.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.11",
+  "version": "3.2.12-beta.10",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -39,7 +39,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-ui": "3.2.11",
+    "@sungen/driver-data-factory": "3.2.12-beta.10",
+    "@sungen/driver-ui": "3.2.12-beta.10",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/capabilities/discover.ts

@@ -27,7 +27,7 @@ import { LOCAL_DRIVERS, registerCoreCapability } from './builtins';
  * move to their packages (R5.5/R5.6) they join this list and leave `LOCAL_DRIVERS`; eventually this
  * becomes a scan of installed `@sungen/driver-*` packages (R5.7).
  */
-const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/driver-api', '@sungen/driver-mobile'];
+const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/driver-api', '@sungen/driver-mobile', '@sungen/driver-data-factory'];
 
 /**
  * Bundled (non-opt-in) drivers: shipped as a core dependency (`drivers.yaml` `bundled: true`), so the
@@ -36,7 +36,10 @@ const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/dri
  * symlink for the package is missing). Surface it LOUDLY: otherwise the entire UI step vocabulary is
  * absent and every step silently compiles to "Unrecognized step pattern" with no clue why.
  */
-const BUNDLED_DRIVERS = new Set(['@sungen/driver-ui']);
+// `@sungen/driver-data-factory` is bundled too — but it is RUNTIME-FREE (only a knowledge catalog +
+// codegen), so shipping it by default adds no runtime, unlike ui/db/api/mobile. It makes standardized
+// test-data available out of the box (no `capability add` needed); inert until a field-map/recipe exists.
+const BUNDLED_DRIVERS = new Set(['@sungen/driver-ui', '@sungen/driver-data-factory']);
 
 function loadExternalDriver(name: string): void {
   // Resolve from the user's PROJECT first, then from core's own location. Opt-in drivers

package/src/cli/commands/capability.ts

@@ -15,6 +15,36 @@ function coreVersion(): string {
   try { return require('../../../package.json').version || 'latest'; } catch { return 'latest'; }
 }
 
+/**
+ * Resolve the driver version to install for the running core `core`.
+ *
+ * Lockstep wants the EXACT `core` version. But the beta channel publishes `<core>-beta.N` before a
+ * stable `<core>` ever exists — so a released core (e.g. 3.2.10) asking for `@3.2.10` hits ETARGET
+ * out-of-the-box when npm only has `3.2.10-beta.2` (`sungen capability add` then fails for a fresh
+ * user). Fall back on the SAME version line: prefer exact `core`, else the highest `core-beta.N`,
+ * else the `beta` dist-tag as a last resort. Keeps the driver's pinned core-dep on the same line.
+ */
+function resolveDriverVersion(pkg: string, core: string): string {
+  if (core === 'latest') return 'beta';
+  try {
+    const out = spawnSync('npm', ['view', pkg, 'versions', '--json'], { encoding: 'utf-8', shell: true });
+    if (out.status !== 0 || !out.stdout) return core; // can't query → let the exact install try/fail
+    let versions: string[] = [];
+    const parsed = JSON.parse(out.stdout);
+    versions = Array.isArray(parsed) ? parsed : [parsed];
+    if (versions.includes(core)) return core; // exact exists → lockstep
+    const prefix = `${core}-beta.`;
+    const betas = versions
+      .filter((v) => typeof v === 'string' && v.startsWith(prefix))
+      .map((v) => parseInt(v.slice(prefix.length), 10))
+      .filter((n) => Number.isInteger(n));
+    if (betas.length) return `${core}-beta.${Math.max(...betas)}`; // highest same-line prerelease
+    return 'beta'; // nothing on this line → newest beta dist-tag
+  } catch {
+    return core;
+  }
+}
+
 /**
  * Add `test:mobile` to the project's package.json scripts (if absent).
  * Idempotent — skips if the script is already set.
@@ -187,14 +217,22 @@ export function registerCapabilityCommand(program: Command): void {
         }
 
         const adapterName = meta.adapter || meta.id;
-        const bundled = adapterRegistry.hasAdapter(adapterName); // e.g. `web` is bundled in Phase 2a
+        // Bundled = a platform adapter baked into core (e.g. `web`), OR a capability driver shipped
+        // as a core dependency (`drivers.yaml` bundled: true, e.g. data-factory) — present already,
+        // so no install/verify: `capability add` on it just records it in the profile.
+        const bundled = adapterRegistry.hasAdapter(adapterName) || meta.bundled === true;
 
         if (!bundled && !o.skipInstall) {
           // Pin the driver to the RUNNING core's exact version (lockstep). Without this, plain
           // `npm install @sungen/driver-x` resolves the package's `latest` dist-tag — which on a
           // beta channel can lag (e.g. a prerelease first-published-as-latest), pulling a driver
           // whose core dep resolves to the wrong @sun-asterisk/sungen and fails to load.
-          const spec = `${meta.package}@${coreVersion()}`;
+          const core = coreVersion();
+          const target = resolveDriverVersion(meta.package, core); // exact core, else same-line beta, else 'beta' tag
+          const spec = `${meta.package}@${target}`;
+          if (target !== core) {
+            console.log(`ℹ ${meta.package}@${core} is not published yet — installing ${spec} (closest on the ${core} line).`);
+          }
           console.log(`📦 Installing ${spec} (dev dependency)...`);
           const r = spawnSync('npm', ['install', '-D', spec], { stdio: 'inherit', shell: true });
           if (r.status !== 0) throw new Error(`npm install -D ${spec} failed.`);