@sungen/driver-data-factory 3.2.12-beta.8 → 3.2.12

package/common/experience/auth-account-states.yaml

@@ -0,0 +1,19 @@
+# Experience checklist: authentication credential / account states — from real login-testing experience.
+# These are LOGIN/AUTH *scenarios*, NOT field-format data: each case is a credential pair whose ACCOUNT
+# is in a particular state, with an expected auth outcome. Most need a domain-state PRECONDITION (a
+# seeded account in that state) — declare it with a state-recipe (`sungen data state`) so it renders a
+# @manual:data-setup Background. Data Factory carries this knowledge; create-test's login viewpoint
+# generates the scenarios. Confirm the exact outcome/message code with the spec/BA — never assume.
+experience: auth-account-states
+description: Credential/account states a login (email+password or credential form) screen must cover.
+applies_when: "a login / sign-in / authentication screen (credential form)"
+cases:
+  - { id: CHK-AUTH-01, state: active, expect: "login succeeds → authenticated destination", note: "happy path — a valid ACTIVE account" }
+  - { id: CHK-AUTH-02, state: wrong-password, expect: "auth fails with a generic error (no user-enumeration)" }
+  - { id: CHK-AUTH-03, state: non-existent-account, expect: "auth fails with the SAME generic error as wrong-password (don't reveal which is wrong)" }
+  - { id: CHK-AUTH-04, state: soft-deleted, expect: "login REJECTED — a soft-deleted account must NOT authenticate", note: "real-world bug precedent: soft-deleted rows still passing auth because the query didn't filter deleted_at" }
+  - { id: CHK-AUTH-05, state: locked-or-suspended, expect: "login blocked with a locked/suspended message (not the generic auth error)" }
+  - { id: CHK-AUTH-06, state: unverified-email, expect: "login blocked or routed to verification, per spec" }
+  - { id: CHK-AUTH-07, state: password-expired, expect: "routed to password reset / forced change, per spec" }
+  - { id: CHK-AUTH-08, state: valid-with-surrounding-whitespace, expect: "email trimmed then login succeeds (pair a valid account email with leading/trailing spaces)", note: "trim behaviour — see the email field-type CHK-EMAIL-WS" }
+oracle: "Each non-happy state needs a seeded account IN that state (a domain-state precondition / fixture). The 'wrong-password' and 'non-existent' outcomes should be indistinguishable (anti-enumeration). soft-deleted / locked / unverified / expired must each be blocked with the correct, spec-defined outcome."

package/common/field-types/email.yaml

@@ -16,6 +16,9 @@ boundary:
   - { id: CHK-EMAIL-B1, gen: "local part = maxLocal", note: "local part = max (64)" }
   - { id: CHK-EMAIL-B2, gen: "local part = maxLocal-1", note: "local part = max-1" }
   - { id: CHK-EMAIL-B3, gen: "total = maxTotal", note: "total length = max (255)" }
+  # min-length side (total = minLength / minLength±1) is auto-completed by the BVA pass from the
+  # field-map's `minLength` — see ensureBvaComplete; no gen entry needed here.
+  - { id: CHK-EMAIL-WS, value: " user@example.com ", validity: valid, note: "leading/trailing whitespace — server MUST trim then accept (pair with a valid password); if the spec rejects instead, override validity to invalid" }
 invalid:
   - { id: CHK-EMAIL-I1, value: "user@", reason: "missing domain", errorRef: M13 }
   - { id: CHK-EMAIL-I2, value: "user@.com", reason: "dot in wrong position", errorRef: M13 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-data-factory",
-  "version": "3.2.12-beta.8",
+  "version": "3.2.12",
   "description": "Sungen Data Factory capability — standardized test-data generation from a field-type + security knowledge catalog (valid/boundary/invalid + traceability), the .overwrite merge layer, and (opt-in) @dataFactory runtime seeding. Design-time knowledge is runtime-free. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -14,7 +14,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.12-beta.8",
+    "@sun-asterisk/sungen": "3.2.12",
     "yaml": "^2.4.0"
   },
   "files": [

package/src/boundary.ts

@@ -216,9 +216,22 @@ export function satisfiesEmail(value: string, c: Record<string, any>): boolean {
   const local = value.slice(0, at);
   if (Number.isFinite(c.maxLocal) && local.length > c.maxLocal) return false;
   if (Number.isFinite(c.maxTotal) && value.length > c.maxTotal) return false;
+  // Total-length MIN (a spec often sets an email min length, e.g. 5) — the oracle must enforce it so a
+  // below-min email is correctly INVALID (was ignored → the min boundary silently missing).
+  const minTotal = c.minLength ?? c.minTotal;
+  if (Number.isFinite(minTotal) && value.length < minTotal) return false;
   return true;
 }
 
+/** Build an email of exactly `n` total chars (for the total-length MIN boundary — small n). */
+export function emailOfTotalLength(n: number): string | null {
+  if (!Number.isFinite(n) || n < 1) return null;
+  if (n < 3) return 'a'.repeat(n);              // too short to be a real address → malformed (below-min case)
+  const rest = n - 2;                            // chars after "a@"
+  if (rest < 3) return 'a@' + 'b'.repeat(rest);  // e.g. n=4 → "a@bb" (no dot → also malformed, below-min)
+  return 'a@' + 'b'.repeat(rest - 2) + '.c';     // e.g. n=5 → "a@b.c", n=6 → "a@bb.c"
+}
+
 function satisfiesLength(type: string, value: string, c: Record<string, any>): boolean {
   const min = c.minLength ?? c.length;
   const max = c.maxLength ?? c.length;
@@ -258,3 +271,49 @@ export function satisfiesConstraints(type: string, value: string | null, c: Reco
   }
   return null;
 }
+
+// ---- BVA completeness: every bounded dimension gets its full min-1/min/min+1/max-1/max/max+1 set ----
+
+export interface BvaExtra { label: string; value: string; validity: Validity; group: 'boundary' | 'invalid'; }
+
+/**
+ * Ensure the canonical Boundary-Value-Analysis set is present for EVERY bounded dimension declared in
+ * the constraints — even one the field-type's catalog `gen:` entries don't exercise. This closes the
+ * QA-reported gap: email declared `minLength: 5` but the catalog only modelled maxLocal/maxTotal, so
+ * the min side (length 4 = min-1 invalid, 5 = min, 6 = min+1) was silently missing. Emits only the
+ * MISSING points (dedup by exact value), so a type whose catalog already covers a dimension (string /
+ * password / number) yields nothing — no churn.
+ */
+export function ensureBvaComplete(type: string, c: Record<string, any>, existing: Array<string | null>): BvaExtra[] {
+  const have = new Set(existing.filter((v): v is string => v != null));
+  const out: BvaExtra[] = [];
+  const push = (label: string, value: string | null) => {
+    if (value == null || have.has(value)) return;
+    const ok = satisfiesConstraints(type, value, c);
+    const validity: Validity = ok === false ? 'invalid' : 'valid';
+    out.push({ label, value, validity, group: validity === 'invalid' ? 'invalid' : 'boundary' });
+    have.add(value);
+  };
+  if (type === 'email') {
+    const minTotal = c.minLength ?? c.minTotal;
+    if (Number.isFinite(minTotal)) {
+      push('minTotal-1', emailOfTotalLength((minTotal as number) - 1));
+      push('minTotal', emailOfTotalLength(minTotal as number));
+      push('minTotal+1', emailOfTotalLength((minTotal as number) + 1));
+    }
+    return out;
+  }
+  if (STR_TYPES.has(type)) {
+    const min = c.minLength ?? c.length, max = c.maxLength ?? c.length;
+    if (Number.isFinite(min)) { push('minLen-1', fillString(type, min - 1)); push('minLen', fillString(type, min)); push('minLen+1', fillString(type, min + 1)); }
+    if (Number.isFinite(max)) { push('maxLen-1', fillString(type, max - 1)); push('maxLen', fillString(type, max)); push('maxLen+1', fillString(type, max + 1)); }
+    return out;
+  }
+  if (NUM_TYPES.has(type)) {
+    const min = c.min, max = c.max, st = step(type, c);
+    if (Number.isFinite(min)) { push('min-1', fmtNum(type, c, min - st)); push('min', fmtNum(type, c, min)); push('min+1', fmtNum(type, c, min + st)); }
+    if (Number.isFinite(max)) { push('max-1', fmtNum(type, c, max - st)); push('max', fmtNum(type, c, max)); push('max+1', fmtNum(type, c, max + st)); }
+    return out;
+  }
+  return out;
+}

package/src/catalog-loader.ts

@@ -14,7 +14,7 @@ import { readFileSync, readdirSync, existsSync, statSync } from 'fs';
 import { join } from 'path';
 import { createHash } from 'crypto';
 import { parse as parseYaml } from 'yaml';
-import type { Catalog, FieldType, SecurityBank, Technique, DataPoint, OverwriteWarning, CatalogProvenance, FieldTypeProvenance } from './types';
+import type { Catalog, FieldType, SecurityBank, Technique, Experience, DataPoint, OverwriteWarning, CatalogProvenance, FieldTypeProvenance } from './types';
 
 /** Resolve the packaged `common/` dir (works from src/ in dev via tsx and from dist/ when built). */
 export function commonDir(): string {
@@ -49,7 +49,11 @@ export function loadShippedCatalog(root = commonDir()): Catalog {
   for (const { data } of readYamlFilesDeep(join(root, 'techniques'))) {
     if (data?.technique) techniques[data.technique] = data as Technique;
   }
-  return { fieldTypes, security, techniques };
+  const experience: Record<string, Experience> = {};
+  for (const { data } of readYamlFilesDeep(join(root, 'experience'))) {
+    if (data?.experience) experience[data.experience] = data as Experience;
+  }
+  return { fieldTypes, security, techniques, experience };
 }
 
 /**
@@ -130,6 +134,7 @@ export function loadEffectiveCatalog(projectDir: string, root = commonDir()): {
     fieldTypes: { ...shipped.fieldTypes },
     security: { ...shipped.security },
     techniques: { ...shipped.techniques },
+    experience: { ...shipped.experience },
   };
 
   for (const [type, ov] of Object.entries(overlayFieldTypes)) {

package/src/cli.ts

@@ -13,8 +13,10 @@ import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { loadEffectiveCatalog, describeProvenance } from './catalog-loader';
 import { expandFieldMap, renderTestData, type FieldMap } from './generator';
 import { buildRequest, fingerprint } from './contract';
-import { loadStateRecipes, validateStateRecipe, buildStatePlan, renderPreconditionBlock, hasDatasource } from './state';
+import { loadStateRecipes, validateStateRecipe, buildStatePlan, renderPreconditionBlock, hasDatasource, scaffoldRecipe, renderRecipeYaml } from './state';
 import { crosscheckUnit, crosscheckShared } from './crosscheck';
+import { coverageUnit } from './coverage';
+import { detectPreconditionSignals } from './detect';
 import { lintFieldMap, summarize } from './lint';
 import { validateGenerated } from './validate';
 import { generateFixture } from './fixture';
@@ -237,21 +239,23 @@ export function registerDataFactoryCommand(program: any): void {
 
   data
     .command('crosscheck')
-    .description('Cross-artifact Gate (M3-B): verify the testcase and its test-data agree — no dangling {{var}}, shared datasets identical across the journey, declared state-preconditions surfaced')
+    .description('Cross-artifact + coverage Gate: testcase ↔ data agree (no dangling {{var}}, shared datasets identical) AND the authored data COVERS the required BVA + the login experience checklist')
     .option('--screen <name>', 'Cross-check one unit (default: all field-maps + all shared datasets)')
     .action((opts: { screen?: string }) => {
       const cwd = process.cwd();
       ensureDataFactoryReadme(cwd);
       const names = opts.screen ? [opts.screen] : listFieldMaps(cwd);
+      const { catalog } = loadEffectiveCatalog(cwd);
       const findings = [
         ...names.flatMap((n) => crosscheckUnit(cwd, n)),
         ...(opts.screen ? [] : crosscheckShared(cwd)),
+        ...names.flatMap((n) => coverageUnit(cwd, n, catalog)),
       ];
       const errors = findings.filter((f) => f.severity === 'error').length;
       const warns = findings.filter((f) => f.severity === 'warn').length;
       const badge = errors ? '✗' : warns ? '⚠' : '✓';
       console.log(`${badge} crosscheck: ${errors} error · ${warns} warn (${names.length} unit(s))`);
-      for (const f of findings) console.log(`  ${f.severity === 'error' ? '✗' : f.severity === 'warn' ? '⚠' : '·'} [${f.unit}] ${f.code}: ${f.message}`);
+      for (const f of findings) console.log(`  ${f.severity === 'error' ? '✗' : f.severity === 'warn' ? '⚠' : '·'} [${(f as any).unit}] ${f.code}: ${f.message}`);
       if (errors) process.exitCode = 1;
     });
 
@@ -259,9 +263,34 @@ export function registerDataFactoryCommand(program: any): void {
     .command('state')
     .description('Domain/stateful data (M3-A Layer 0): validate the state-recipes in recipes.yaml and render each as a standardized manual precondition block (+ a resolved .state.yaml plan)')
     .option('--recipe <name>', 'Only this recipe (default: all recipes with a `resources`/`shared` graph)')
-    .action((opts: { recipe?: string }) => {
+    .option('--scaffold <unit>', 'Auto-draft a state-recipe SKELETON from the unit\'s spec.md precondition signals (Layer-C auto-draft), then review/fill it')
+    .option('--force', 'With --scaffold: overwrite an existing recipe of the same name')
+    .action((opts: { recipe?: string; scaffold?: string; force?: boolean }) => {
       const cwd = process.cwd();
       ensureDataFactoryReadme(cwd);
+
+      // --scaffold: auto-draft a recipe skeleton from the unit's spec precondition signals.
+      if (opts.scaffold) {
+        const unit = opts.scaffold;
+        const specPath = ['screens', 'flows'].map((k) => join(cwd, 'qa', k, unit, 'requirements', 'spec.md')).find(existsSync);
+        const specText = specPath ? readFileSync(specPath, 'utf8') : '';
+        const signals = detectPreconditionSignals(specText);
+        const recipe = scaffoldRecipe(unit, signals);
+        if (!recipe) { console.log(`No stateful-precondition signals found in ${unit}'s spec — nothing to scaffold (a screen may simply have no precondition).`); return; }
+        const recipesPath = join(FIELDMAP_DIR(cwd), 'recipes.yaml');
+        const doc: any = existsSync(recipesPath) ? (parseYaml(readFileSync(recipesPath, 'utf8')) || {}) : {};
+        doc.recipes = doc.recipes || {};
+        if (doc.recipes[recipe.name] && !opts.force) { console.error(`✗ recipe "${recipe.name}" already exists — edit it, or pass --force to overwrite the scaffold.`); process.exitCode = 1; return; }
+        // Splice the human-friendly (commented) block rather than a bare re-serialize, to preserve TODO hints.
+        const header = existsSync(recipesPath) ? readFileSync(recipesPath, 'utf8').replace(/\s*$/, '') + '\n' : 'recipes:\n';
+        const block = renderRecipeYaml(recipe);
+        writeFileSync(recipesPath, (header.includes('recipes:') ? header : 'recipes:\n' + header) + block, 'utf8');
+        console.log(`  ✓ scaffolded recipe "${recipe.name}" → ${recipesPath.replace(cwd + '/', '')} (${signals.length} signal(s))`);
+        console.log(`  → REVIEW: name each entity, set desiredState/bindings, confirm domain values with QA, then \`sungen data state --recipe ${recipe.name}\`.`);
+        for (const s of signals) console.log(`    · signal: ${s}`);
+        return;
+      }
+
       let recipes = loadStateRecipes(cwd);
       if (opts.recipe) recipes = recipes.filter((r) => r.name === opts.recipe);
       if (recipes.length === 0) { console.error('No state-recipes (recipes with a `resources` or `shared` graph) in qa/data-factory/recipes.yaml.'); process.exitCode = 1; return; }

package/src/coverage.ts

@@ -0,0 +1,165 @@
+/**
+ * Data Factory — coverage check (does the AUTHORED test-data actually cover the standardized set?).
+ *
+ * `data validate` checks the DF-generated field block is internally correct; `data crosscheck` checks
+ * testcase ↔ data agree. But `/sungen:create-test` often AUTHORS login/flow test-data by hand (seeded
+ * accounts + `@cases`) instead of merging `data gen`'s output — so the deterministic BVA the generator
+ * would produce (e.g. email length 4/5/6 for `minLength: 5`) and the experience checklist (soft-deleted
+ * login…) can be silently missed. This check reconciles the authored values against BOTH:
+ *   - the BVA the field-map's constraints REQUIRE (per bounded dimension), and
+ *   - the auth-account-states experience checklist (for a login/auth unit).
+ * It matches fuzzily (authored keys are free-form): length for length dims, numeric value for numeric
+ * dims, keyword for experience. Advisory (warn) — a visible nudge the create-test loop must address or
+ * the QA waives; never blocks. Pure + deterministic.
+ */
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { parse as parseYaml } from 'yaml';
+import type { Catalog } from './types';
+import { expandField, type FieldMap, type FieldDef } from './generator';
+
+export interface CoverageFinding {
+  unit: string;
+  severity: 'warn' | 'info';
+  code: 'BVA_UNCOVERED' | 'EXPERIENCE_UNCOVERED';
+  field?: string;
+  message: string;
+}
+
+const STR_LEN_TYPES = new Set(['email', 'string', 'password', 'phone', 'postcode', 'katakana']);
+const NUM_TYPES = new Set(['number-integer', 'number-float', 'currency']);
+
+function unitTestDataPath(cwd: string, name: string): string | null {
+  for (const kind of ['screens', 'flows']) {
+    const p = join(cwd, 'qa', kind, name, 'test-data', `${name}.yaml`);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+function unitFeatureText(cwd: string, name: string): string {
+  for (const kind of ['screens', 'flows']) {
+    const dir = join(cwd, 'qa', kind, name, 'features');
+    if (!existsSync(dir)) continue;
+    try { return readdirSync(dir).filter((f) => f.endsWith('.feature')).map((f) => readFileSync(join(dir, f), 'utf8')).join('\n'); } catch { return ''; }
+  }
+  return '';
+}
+function loadYaml(p: string): Record<string, any> {
+  if (!existsSync(p)) return {};
+  try { return (parseYaml(readFileSync(p, 'utf8')) as Record<string, any>) || {}; } catch { return {}; }
+}
+
+/** Every string value anywhere in the test-data (top-level scalars + nested + `@cases` rows). */
+function collectStrings(data: Record<string, any>): string[] {
+  const out: string[] = [];
+  const walk = (v: unknown) => {
+    if (typeof v === 'string') out.push(v);
+    else if (Array.isArray(v)) v.forEach(walk);
+    else if (v && typeof v === 'object') Object.values(v as Record<string, unknown>).forEach(walk);
+  };
+  for (const [k, v] of Object.entries(data)) { if (k.startsWith('_')) continue; walk(v); }
+  return out;
+}
+
+/** Short human label for a boundary point (from its note / id). */
+function pointLabel(p: { id: string; note?: string }): string {
+  if (p.note) { const tail = p.note.split(/·|:/).pop()?.trim(); if (tail) return tail; }
+  return p.id.replace(/^CHK-[A-Z0-9]+-/, '');
+}
+
+/** BVA coverage for one field: which required boundary points are not represented among authored values. */
+function bvaGaps(field: FieldDef, catalog: Catalog, authored: string[]): string[] {
+  if (!field.type) return [];
+  const ef = expandField(field, catalog);
+  const synth = ef.points.filter((p) => p.synthesized && p.value != null);
+  if (!synth.length) return [];
+  const gaps: string[] = [];
+  const seen = new Set<string>();
+  if (STR_LEN_TYPES.has(field.type)) {
+    // Type-aware filter so an unrelated string of the same LENGTH doesn't falsely "cover" the boundary
+    // (e.g. a 5-char URL must not count as covering an email `minLength`-5 case). Email → values with
+    // an `@`; katakana → values with kana; others (generic string) stay loose.
+    const plausible =
+      field.type === 'email' ? authored.filter((s) => s.includes('@'))
+      : field.type === 'katakana' ? authored.filter((s) => /[゠-ヿｦ-ﾟ]/.test(s))
+      : authored;
+    const authoredLens = new Set(plausible.map((s) => s.length));
+    for (const p of synth) {
+      const len = (p.value as string).length;
+      const key = `len:${len}`;
+      if (seen.has(key) || authoredLens.has(len)) { seen.add(key); continue; }
+      seen.add(key);
+      gaps.push(`${pointLabel(p)} (length ${len}, ${p.expectedValidity})`);
+    }
+  } else if (NUM_TYPES.has(field.type)) {
+    const authoredNums = new Set(authored.map((s) => Number(s)).filter((n) => Number.isFinite(n)));
+    for (const p of synth) {
+      const n = Number(p.value);
+      const key = `num:${n}`;
+      if (seen.has(key) || authoredNums.has(n)) { seen.add(key); continue; }
+      seen.add(key);
+      gaps.push(`${pointLabel(p)} (value ${p.value}, ${p.expectedValidity})`);
+    }
+  }
+  return gaps;
+}
+
+/** Keyword patterns proving an auth-account-state is covered somewhere in the data/feature. */
+const STATE_COVERED: Record<string, RegExp> = {
+  active: /valid|active|success|happy/i,
+  'wrong-password': /wrong.?pass|password.?mismatch|incorrect.?pass|bad.?pass/i,
+  'non-existent-account': /unregister|non.?exist|not.*(exist|found|in nj)|no account/i,
+  'soft-deleted': /soft.?delet|deleted.?account|marked.?deleted|deleted_at/i,
+  'locked-or-suspended': /lock|suspend|inactive|disabled account/i,
+  'unverified-email': /unverif|not.?verified|pending.?verif|email.?verification/i,
+  'password-expired': /expir/i,
+  // valid-with-surrounding-whitespace is handled by a VALUE-level check (an actual email with
+  // leading/trailing space), not this blob regex — the word "trim" alone (from the empty-trim case)
+  // must NOT count as covering the valid-after-trim case.
+};
+
+/** Coverage check for one unit — BVA gaps per field + auth-experience gaps for a login/auth unit. */
+export function coverageUnit(cwd: string, name: string, catalog: Catalog): CoverageFinding[] {
+  const fmPath = join(cwd, 'qa', 'data-factory', `${name}.fields.yaml`);
+  if (!existsSync(fmPath)) return [];
+  const map = loadYaml(fmPath) as FieldMap;
+  if (!map || !Array.isArray(map.fields)) return [];
+  const tdPath = unitTestDataPath(cwd, name);
+  const data = tdPath ? loadYaml(tdPath) : {};
+  const authored = collectStrings(data);
+  const feature = unitFeatureText(cwd, name);
+  const blob = (authored.join('\n') + '\n' + JSON.stringify(data) + '\n' + feature).toLowerCase();
+  const out: CoverageFinding[] = [];
+
+  // 1. BVA coverage per field (flatten nested groups to leaves).
+  const leaves: FieldDef[] = [];
+  const walk = (fs: FieldDef[]) => { for (const f of fs) { if (f.fields) walk(f.fields); else leaves.push(f); } };
+  walk(map.fields);
+  for (const f of leaves) {
+    const gaps = bvaGaps(f, catalog, authored);
+    if (gaps.length) {
+      out.push({ unit: name, field: f.name, severity: 'warn', code: 'BVA_UNCOVERED',
+        message: `field "${f.name}" (${f.type}): ${gaps.length} boundary case(s) not represented in test-data — ${gaps.join('; ')}. The field-map's constraints require them (e.g. minLength → a below-min & at-min value); author them or waive with a reason.` });
+    }
+  }
+
+  // 2. Auth-experience coverage — only for a login/auth unit (has an email + a password field).
+  const isLogin = leaves.some((f) => f.type === 'email') && leaves.some((f) => f.type === 'password');
+  const exp = catalog.experience?.['auth-account-states'];
+  if (isLogin && exp) {
+    // An actual email value carrying leading/trailing whitespace = the valid-after-trim case covered.
+    const hasWhitespaceEmail = authored.some((s) => s.includes('@') && s !== s.trim());
+    const missing: string[] = [];
+    for (const c of exp.cases || []) {
+      const state = String((c as any).state || c.id);
+      if (state === 'valid-with-surrounding-whitespace') { if (!hasWhitespaceEmail) missing.push(state); continue; }
+      const re = STATE_COVERED[state];
+      if (re && !re.test(blob)) missing.push(state);
+    }
+    if (missing.length) {
+      out.push({ unit: name, severity: 'warn', code: 'EXPERIENCE_UNCOVERED',
+        message: `login unit: auth-account-states not covered — ${missing.join(', ')}. Each needs a credential-state scenario (a seeded account in that state → the correct rejection/route). Add them or waive per spec (some may be N/A).` });
+    }
+  }
+  return out;
+}

package/src/crosscheck.ts

@@ -61,6 +61,29 @@ function loadYaml(path: string): Record<string, any> {
   try { return (parseYaml(readFileSync(path, 'utf8')) as Record<string, any>) || {}; } catch { return {}; }
 }
 
+/**
+ * Column names supplied per-row by every `@cases:<dataset>` referenced in the feature (where the
+ * dataset is a top-level LIST in test-data). A `{{col}}` inside a data-driven scenario resolves to
+ * the current row, not a top-level key — so these are valid roots, not dangling. Mirrors the
+ * compiler's data-driven lint, which is @cases-aware; without this, any @cases scenario that reads
+ * a row column (`{{input}}`, `{{code}}`, …) would be a false-positive DANGLING_VAR.
+ */
+export function casesColumns(featureText: string, data: Record<string, any>): Set<string> {
+  const cols = new Set<string>();
+  const re = /@cases:([A-Za-z0-9_.-]+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(featureText))) {
+    const ds = data[m[1]];
+    if (!Array.isArray(ds)) continue;
+    for (const row of ds) {
+      if (row && typeof row === 'object' && !Array.isArray(row)) {
+        for (const k of Object.keys(row)) cols.add(k);
+      }
+    }
+  }
+  return cols;
+}
+
 /** Cross-check one unit's feature ↔ test-data. */
 export function crosscheckUnit(cwd: string, name: string): CrossFinding[] {
   const out: CrossFinding[] = [];
@@ -70,10 +93,11 @@ export function crosscheckUnit(cwd: string, name: string): CrossFinding[] {
   if (!feature) return out;
   const data = loadYaml(paths.testData);
   const topKeys = new Set(Object.keys(data).filter((k) => !k.startsWith('_')));
+  const caseCols = casesColumns(feature, data); // @cases row columns resolve per-row, not as top-level keys
 
-  // 1. Dangling vars — a {{var}} whose root key is absent from test-data.
+  // 1. Dangling vars — a {{var}} whose root key is absent from test-data (and not a @cases column).
   for (const v of referencedVars(feature)) {
-    if (!topKeys.has(v)) {
+    if (!topKeys.has(v) && !caseCols.has(v)) {
       out.push({ unit: name, severity: 'error', code: 'DANGLING_VAR', message: `scenario references {{${v}}} but no "${v}" key exists in test-data/${name}.yaml` });
     }
   }

package/src/detect.ts

@@ -0,0 +1,122 @@
+/**
+ * Data Factory — auto-detection (Layer A of the auto-orchestration design).
+ *
+ * Makes Sungen NOTICE what test-data work a unit needs, without QA having to know to run a command:
+ *   - a unit that HAS input fields but has NO field-map → its data was never standardized;
+ *   - a spec that describes a STATEFUL PRECONDITION (a required entity/state) with no state-recipe and
+ *     no Background/@manual precondition → the stateful setup is undeclared.
+ * Both are surfaced as advisory findings at `sungen generate`/`sungen audit` (the DF advisory sensor).
+ * Deterministic heuristics over spec.md + the feature; no runtime, no LLM. Advisory only — a nudge +
+ * an auto-draft prompt, never a hard fail (the fuzzy precondition scan must not block).
+ */
+import { join } from 'path';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { loadStateRecipes } from './state';
+
+export interface DetectFinding {
+  code: 'UNSTANDARDIZED' | 'PRECONDITION_UNDECLARED';
+  scenario: string;
+  message: string;
+  severity: 'warn' | 'info';
+}
+
+function readIfExists(path: string): string {
+  try { return existsSync(path) ? readFileSync(path, 'utf8') : ''; } catch { return ''; }
+}
+
+function readSpec(dir: string): string {
+  return readIfExists(join(dir, 'requirements', 'spec.md'));
+}
+
+function readFeature(dir: string): string {
+  const fdir = join(dir, 'features');
+  if (!existsSync(fdir)) return '';
+  try {
+    return readdirSync(fdir).filter((f) => f.endsWith('.feature')).map((f) => readIfExists(join(fdir, f))).join('\n');
+  } catch { return ''; }
+}
+
+/**
+ * Does the unit take user input? Strongest signal: a Gherkin `fill [X] field` / `type` step; plus a
+ * spec field table row typed as input/select/textarea. A pure navigation / list / capture screen has
+ * none → we must NOT nag it ("no input fields → nothing to generate").
+ */
+export function hasInputFields(specText: string, featureText: string): boolean {
+  if (/\b(fill|type|enter|input|select|choose)\b\s+\[[^\]]+\]\s*(field|input|dropdown|textbox)?/i.test(featureText)) return true;
+  if (/\|\s*(input|select|textarea|checkbox|radio|combobox)\b/i.test(specText)) return true;
+  if (/\binput\s*\(|\bselect\s*\(|\btextarea\b/i.test(specText)) return true;
+  return false;
+}
+
+/** A field-map exists for this unit. */
+export function hasFieldMap(cwd: string, name: string): boolean {
+  return existsSync(join(cwd, 'qa', 'data-factory', `${name}.fields.yaml`));
+}
+
+/** Precondition signal phrases — a spec sentence hinting the test needs a pre-existing entity/state. */
+const PRECONDITION_SIGNALS = [
+  'requires', 'required before', 'precondition', 'pre-condition', 'prerequisite',
+  'logged in', 'authenticated', 'signed in', 'must be logged',
+  'already exists', 'already registered', 'existing ', 'pre-existing', 'must exist',
+  'reset token', 'verification', 'provisional account', 'session-storage', 'session storage',
+  'buffer', 'seeded', 'must have', 'previously', 'valid token', 'auth token',
+];
+
+/** Extract spec sentences that look like a stateful precondition (deduped, capped). */
+export function detectPreconditionSignals(specText: string): string[] {
+  if (!specText) return [];
+  const hits: string[] = [];
+  const seen = new Set<string>();
+  // Split into sentence-ish units (lines / bullet items / sentences).
+  const units = specText.split(/\n|(?<=[.。])\s+/).map((s) => s.replace(/\s+/g, ' ').trim()).filter(Boolean);
+  for (const u of units) {
+    const low = u.toLowerCase();
+    // Skip markdown headings/table separators, and spec-template meta lines (US labels, rationale)
+    // that mention auth/priority only descriptively — not an actual precondition.
+    if (/^#{1,6}\s|^\|?\s*-{3,}/.test(u)) continue;
+    if (/^\*\*(why|independent test|acceptance|business context|target users|priority)\b/i.test(u)) continue;
+    if (/\bpriority\b/i.test(low) && /\bp[0-9]\b/i.test(low)) continue;
+    const sig = PRECONDITION_SIGNALS.find((s) => low.includes(s));
+    if (sig) {
+      const key = low.slice(0, 60);
+      if (!seen.has(key)) { seen.add(key); hits.push(u.length > 160 ? u.slice(0, 157) + '…' : u); }
+    }
+    if (hits.length >= 4) break;
+  }
+  return hits;
+}
+
+/** Is a stateful precondition already declared — a state-recipe with resources, or a Background/@manual? */
+export function hasStateDeclaration(cwd: string, featureText: string): boolean {
+  if (/^\s*Background:/m.test(featureText) || /@manual\b/.test(featureText)) return true;
+  return loadStateRecipes(cwd).some((r) => (r.resources && r.resources.length) || r.shared);
+}
+
+/** Run Layer-A detection for one unit dir. Returns advisory findings (possibly empty). */
+export function detectUnit(cwd: string, dir: string, name: string): DetectFinding[] {
+  const spec = readSpec(dir);
+  const feature = readFeature(dir);
+  const out: DetectFinding[] = [];
+
+  // 1. Inputs exist but never standardized.
+  if (!hasFieldMap(cwd, name) && hasInputFields(spec, feature)) {
+    out.push({
+      code: 'UNSTANDARDIZED',
+      scenario: name,
+      severity: 'warn',
+      message: `DATA-FACTORY-UNSTANDARDIZED: ${name} has input fields but no standardized test-data (no qa/data-factory/${name}.fields.yaml) — run \`/sungen:create-data-test ${name}\` (or it is authored inline by \`/sungen:create-test\`) so values are standardized valid/boundary/invalid, not hand-invented.`,
+    });
+  }
+
+  // 2. Stateful precondition described in the spec but not declared anywhere.
+  const signals = detectPreconditionSignals(spec);
+  if (signals.length && !hasStateDeclaration(cwd, feature)) {
+    out.push({
+      code: 'PRECONDITION_UNDECLARED',
+      scenario: name,
+      severity: 'info',
+      message: `DATA-FACTORY-PRECONDITION-UNDECLARED: ${name}'s spec describes a stateful precondition but the test declares none (no state-recipe, no Background/@manual). Declare it with a state-recipe + \`sungen data state\` so it renders a @manual:data-setup Background. Signals: ${signals.map((s) => `"${s}"`).join('; ')}`,
+    });
+  }
+  return out;
+}

package/src/generator.ts

@@ -10,7 +10,7 @@
  * same output (determinism is an asset). Nothing here reads a live page or an LLM.
  */
 import type { Catalog, FieldType, DataPoint, SelectionContext } from './types';
-import { expandBoundaryHint, satisfiesConstraints, type Validity } from './boundary';
+import { expandBoundaryHint, satisfiesConstraints, ensureBvaComplete, type Validity } from './boundary';
 import { evaluateWhen, fieldFacts, inProfile } from './applicability';
 
 export interface FieldDef {
@@ -265,6 +265,23 @@ export function expandField(field: FieldDef, catalog: Catalog, ctx: SelectionCon
     }
   }
 
+  // BVA completeness: for every bounded dimension in the constraints, ensure the full
+  // min-1/min/min+1/max-1/max/max+1 set exists — auto-adding only what the catalog left out (e.g. an
+  // email `minLength` the catalog didn't model). Only in-range points are `boundary`; out-of-range are
+  // `invalid`. Appended after the catalog cases so it never overrides an authored one.
+  const idCode = type.toUpperCase().replace(/[^A-Z0-9]/g, '');
+  for (const ex of ensureBvaComplete(type, c, points.map((p) => p.value))) {
+    points.push({
+      id: `CHK-${idCode}-BVA-${ex.label}`,
+      group: ex.group,
+      value: ex.value,
+      expectedValidity: ex.validity,
+      synthesized: true,
+      note: `BVA (auto): ${ex.label}`,
+      ...(ex.validity === 'invalid' ? { reason: `out of bounds (${ex.label})` } : {}),
+    });
+  }
+
   return {
     name: field.name,
     type: field.type,

package/src/index.ts

@@ -25,21 +25,25 @@ export { lintFieldMap, summarize } from './lint';
 export type { LintIssue } from './lint';
 export { validateGenerated, validatePoints } from './validate';
 export type { ValidationFinding } from './validate';
-export { expandBoundaryHint, satisfiesConstraints } from './boundary';
-export type { Validity, BoundaryPoint } from './boundary';
+export { expandBoundaryHint, satisfiesConstraints, ensureBvaComplete, emailOfTotalLength } from './boundary';
+export type { Validity, BoundaryPoint, BvaExtra } from './boundary';
 export { evaluateWhen, inProfile, fieldFacts } from './applicability';
 export { generate, buildRequest, validateRequest, fingerprint, GENERATOR_VERSION, SCHEMA_VERSION } from './contract';
 export type { DataFactoryRequest, DataFactoryResult } from './contract';
-export { loadStateRecipes, validateStateRecipe, buildStatePlan, renderPreconditionBlock, topoSort, hasDatasource } from './state';
+export { loadStateRecipes, validateStateRecipe, buildStatePlan, renderPreconditionBlock, topoSort, hasDatasource, scaffoldRecipe, renderRecipeYaml, guessProvenance } from './state';
 export type { StateRecipe, StateResource, StatePlan, StateFinding, Provenance, Lifecycle } from './state';
 export { crosscheckUnit, crosscheckShared, crosscheckAll, referencedVars } from './crosscheck';
 export type { CrossFinding } from './crosscheck';
+export { detectUnit, hasInputFields, hasFieldMap, detectPreconditionSignals, hasStateDeclaration } from './detect';
+export type { DetectFinding } from './detect';
+export { coverageUnit } from './coverage';
+export type { CoverageFinding } from './coverage';
 export { registerDataFactoryCommand } from './cli';
 export { generateFixture } from './fixture';
 export type { FixtureResult, FixtureExpected, ExpectedRow } from './fixture';
 export { dataFactoryCoverageSensor } from './sensor';
 export { dfPreconditionCodegen } from './precondition';
-export type { Catalog, FieldType, SecurityBank, Technique, DataPoint, OverwriteWarning, CatalogProvenance, FieldTypeProvenance, SelectionContext, Profile } from './types';
+export type { Catalog, FieldType, SecurityBank, Technique, Experience, DataPoint, OverwriteWarning, CatalogProvenance, FieldTypeProvenance, SelectionContext, Profile } from './types';
 
 /** Register the Data Factory capability. */
 export function register(registry: CapabilityRegistry): void {

package/src/sensor.ts

@@ -5,7 +5,10 @@
  * coverage lint as `sungen data lint` and surfaces the gaps in the generate output — so weak
  * test-data coverage (missing boundary/invalid, unresolved values, unmapped error codes, blind
  * spots) is visible in the standard harness flow, not only when you remember to run `data lint`.
- * A unit with no field-map produces no findings (Data Factory is opt-in per unit).
+ *
+ * Auto-detection (Layer A): even with NO field-map, it NOTICES what's missing — a unit with input
+ * fields but no standardized data, or a spec that describes a stateful precondition the test never
+ * declares — so Sungen nudges QA instead of staying silent (was: "no field-map → nothing to say").
  *
  * Advisory, not gate: the ContextRouter scopes gate sensors by the annotation tags a feature carries,
  * and test-data generation is a design-time concern with no `.feature` tag — so gating here would
@@ -18,6 +21,7 @@ import type { Sensor } from '@sun-asterisk/sungen';
 import { loadEffectiveCatalog } from './catalog-loader';
 import { lintFieldMap, summarize } from './lint';
 import { validateGenerated } from './validate';
+import { detectUnit } from './detect';
 import type { FieldMap } from './generator';
 
 export const dataFactoryCoverageSensor: Sensor<{ dir: string; cwd: string }> = {
@@ -26,11 +30,21 @@ export const dataFactoryCoverageSensor: Sensor<{ dir: string; cwd: string }> = {
   kind: 'advisory',
   run: ({ dir, cwd }) => {
     const name = basename(dir);
+    // Layer A auto-detection — runs regardless of whether a field-map exists, so a unit that needs
+    // standardization or a declared precondition is NOTICED, not silently skipped.
+    const detected = detectUnit(cwd, dir, name).map((d) => ({
+      sensorId: 'data-factory-coverage',
+      capability: 'data-factory',
+      scenario: d.scenario,
+      message: d.message,
+      severity: d.severity,
+    }));
+
     const fieldMapPath = join(cwd, 'qa', 'data-factory', `${name}.fields.yaml`);
-    if (!existsSync(fieldMapPath)) return []; // opt-in per unit — no field-map, nothing to say
+    if (!existsSync(fieldMapPath)) return detected; // no field-map: report only what detection noticed
     let map: FieldMap;
-    try { map = parseYaml(readFileSync(fieldMapPath, 'utf8')) as FieldMap; } catch { return []; }
-    if (!map || !Array.isArray(map.fields)) return [];
+    try { map = parseYaml(readFileSync(fieldMapPath, 'utf8')) as FieldMap; } catch { return detected; }
+    if (!map || !Array.isArray(map.fields)) return detected;
 
     const { catalog, warnings } = loadEffectiveCatalog(cwd);
     const { issues } = lintFieldMap(map, catalog);
@@ -71,6 +85,8 @@ export const dataFactoryCoverageSensor: Sensor<{ dir: string; cwd: string }> = {
         severity: s.errors ? 'warn' : 'info',
       });
     }
+    // Detection findings (e.g. an undeclared stateful precondition) are still relevant with a field-map.
+    findings.push(...detected);
     return findings;
   },
 };

package/src/state.ts

@@ -171,6 +171,53 @@ export function hasDatasource(cwd: string): boolean {
   return existsSync(join(cwd, 'datasources.yaml')) || existsSync(join(cwd, 'qa', 'datasources.yaml'));
 }
 
+/** Guess a provenance from a precondition sentence — best-effort; QA confirms. */
+export function guessProvenance(signal: string): Provenance {
+  const s = signal.toLowerCase();
+  if (/session-storage|session storage|local ?storage|cookie|buffer/.test(s)) return 'client-storage';
+  if (/token|reset|verification|otp|invitation|seeded/.test(s)) return 'fixture';
+  if (/logged in|authenticated|signed in|auth token|session/.test(s)) return 'server-context';
+  if (/already|existing|registered|must exist|previously|prior/.test(s)) return 'prior-flow';
+  return 'manual';
+}
+
+/**
+ * Auto-scaffold a state-recipe SKELETON from a spec's precondition sentences (Layer-C auto-draft).
+ * Deterministic: one resource per detected signal, provenance guessed, entity left as a TODO for the
+ * AI/QA to fill (never fabricates a domain entity). Returns null when no precondition signal is found.
+ */
+export function scaffoldRecipe(unit: string, signals: string[]): StateRecipe | null {
+  if (!signals.length) return null;
+  const resources: StateResource[] = signals.slice(0, 4).map((sig, i) => ({
+    ref: `r${i + 1}`,
+    entity: 'TODO',                 // ← name the real entity (from the signal); do not invent domain values
+    provenance: guessProvenance(sig),
+    lifecycle: 'reusable',
+    note: sig,
+  }));
+  return {
+    name: `${unit}_precondition`,
+    description: `stateful precondition for ${unit} — AUTO-SCAFFOLDED from spec; REVIEW: name each entity, set desiredState/bindings, confirm with QA`,
+    resources,
+  };
+}
+
+/** Serialize a scaffolded recipe as a YAML block to splice under `recipes:` (2-space indented). */
+export function renderRecipeYaml(recipe: StateRecipe): string {
+  const lines: string[] = [`  ${recipe.name}:`];
+  if (recipe.description) lines.push(`    description: "${recipe.description}"`);
+  lines.push('    resources:');
+  for (const r of recipe.resources || []) {
+    lines.push(`      - ref: ${r.ref}`);
+    lines.push(`        entity: ${r.entity}        # ← name the real entity`);
+    lines.push(`        provenance: ${r.provenance}   # guessed — confirm (prior-flow|fixture|client-storage|server-context|manual|api|db)`);
+    if (r.lifecycle) lines.push(`        lifecycle: ${r.lifecycle}`);
+    if (r.note) lines.push(`        note: ${JSON.stringify(r.note)}`);
+  }
+  lines.push('    # bindings: { someId: "${r1.id}" }   # ← wire ids the test needs');
+  return lines.join('\n') + '\n';
+}
+
 /** Render the precondition block for weaving into a Gherkin Background (with the @manual tag if needed). */
 export function renderPreconditionBlock(plan: StatePlan): string {
   const tag = plan.manual ? '# @manual:data-setup — required state (auto-provisions when an api/db datasource is added)' : '# required state (Layer 1: auto-provisioned via the referenced endpoints)';

package/src/types.ts

@@ -75,10 +75,25 @@ export interface Technique {
   [k: string]: unknown;
 }
 
+/**
+ * A domain-EXPERIENCE checklist — cases that come from real-world testing experience, not from a
+ * field's format (e.g. the credential/account states a login screen must cover: soft-deleted, locked,
+ * unverified…). Each case is a SCENARIO that usually needs a domain-state precondition, so it is
+ * knowledge for the login/auth viewpoint + a state-recipe — not a field-level value.
+ */
+export interface Experience {
+  experience: string;
+  description?: string;
+  applies_when?: string;
+  cases: Array<Record<string, unknown> & { id: string; expect?: string }>;
+  oracle?: string;
+}
+
 export interface Catalog {
   fieldTypes: Record<string, FieldType>;
   security: Record<string, SecurityBank>;
   techniques: Record<string, Technique>;
+  experience: Record<string, Experience>;
 }
 
 /** Named case-selection profiles (which groups/categories a run wants). */