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

package/dist/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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.12-beta.1",
+  "version": "3.2.12-beta.10",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -39,8 +39,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.12-beta.1",
-    "@sungen/driver-ui": "3.2.12-beta.1",
+    "@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",