@sun-asterisk/sungen 3.2.16-beta.1 → 3.2.16-beta.11

package/src/harness/parse.ts

@@ -7,6 +7,7 @@
  */
 import * as fs from 'fs';
 import { GherkinParser, ParsedScenario, ParsedStep } from '../generators/gherkin-parser';
+import { readTextFile } from './read-text';
 
 export type Priority = 'high' | 'normal' | 'low' | 'unknown';
 
@@ -51,9 +52,22 @@ export function idPrefix(id: string): string {
 
 // ---------- test-viewpoint.md ----------
 
+/**
+ * A viewpoint OVERVIEW id may be a bare category (`VP-LOGIC`, `VP-SEC`) — that is
+ * the scheme sungen itself prescribes, with the sequence number living on the
+ * scenario (`VP-LOGIC-013`). `isIdLike` demands a digit to avoid picking prose out
+ * of tables, which silently rejected every category id: a project declaring
+ * VP-LOGIC/VP-VAL/VP-SEC/VP-UI/VP-NAV/VP-PERF/VP-I18N parsed as ONE viewpoint
+ * (only VP-I18N, for the "18"), traceability collapsed to ~0%, and the audit told
+ * QA to re-tag scenarios that were already correct.
+ */
+function isViewpointId(s: string): boolean {
+  return isIdLike(s) || /^VP-[A-Z][A-Z0-9]*$/i.test(s);
+}
+
 export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
   if (!fs.existsSync(filePath)) return [];
-  const text = fs.readFileSync(filePath, 'utf-8');
+  const text = readTextFile(filePath);
   const lines = text.split('\n');
 
   const entries = new Map<string, ViewpointEntry>();
@@ -68,7 +82,7 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
       const cells = line.split('|').map((c) => c.trim()).filter((_, i, a) => i > 0 && i < a.length - 1);
       if (cells.length >= 3) {
         const id = cells[0];
-        if (isIdLike(id) && !/^-+$/.test(cells[1])) {
+        if (isViewpointId(id) && !/^-+$/.test(cells[1])) {
           const pr = /high/i.test(cells[1]) ? 'High' : /medium/i.test(cells[1]) ? 'Medium' : /low/i.test(cells[1]) ? 'Low' : 'Unknown';
           entries.set(id.toUpperCase(), { id: id.toUpperCase(), priority: pr as any, reason: cells[2] });
         }
@@ -85,7 +99,7 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
     if (/^##\s/.test(line)) { group = undefined; }
     if (group) {
       const m = line.match(/^[-*+]\s+([A-Za-z][A-Za-z0-9.-]*)/);
-      if (m && isIdLike(m[1])) {
+      if (m && isViewpointId(m[1])) {
         const id = m[1].toUpperCase();
         const existing = entries.get(id);
         if (existing) existing.group = group;

package/src/harness/quality-gates.ts

@@ -7,6 +7,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { ScenarioInfo, loadScenarios, idPrefix } from './parse';
 import { parseManualComments } from '../exporters/scenario-merger';
+import { readTextFile } from './read-text';
 
 // ---------- #2 Downstream-scope ----------
 
@@ -202,5 +203,5 @@ export function crossArtifactOwnership(screenDir: string, scenarios: ScenarioInf
 
 // convenience reader
 export function readText(p: string): string {
-  return fs.existsSync(p) ? fs.readFileSync(p, 'utf-8') : '';
+  return fs.existsSync(p) ? readTextFile(p) : '';
 }

package/src/harness/read-text.ts

@@ -0,0 +1,28 @@
+import * as fs from 'fs';
+
+/**
+ * Read a user-authored text file with line endings NORMALISED to `\n`.
+ *
+ * Why this exists: the harness parses spec.md / test-viewpoint.md / .feature with
+ * line-anchored regexes such as `/^\s*Scenario:\s*(.+)$/`. In JavaScript `.` does
+ * NOT match `\r`, so on a CRLF file `(.+)$` can never reach the end of the line
+ * and the match silently fails. The parser then reports "nothing found" rather
+ * than an error, which is far worse than crashing:
+ *
+ *   - `spec-coverage` found 0 requirements → the FR sensor scored a vacuous
+ *     100% and never emitted SPEC-UNCOVERED / SPEC-TRACE-IMPLICIT.
+ *   - `parseViewpointOverview` found 1 of N viewpoints → traceability collapsed
+ *     to ~0% and the audit told QA to "re-tag" scenarios that were already
+ *     correct.
+ *
+ * A Windows-authored spec is completely normal, so every harness parser that
+ * reads a user file must go through here.
+ */
+export function readTextFile(filePath: string): string {
+  return fs.readFileSync(filePath, 'utf-8').replace(/\r\n?/g, '\n');
+}
+
+/** `readTextFile` split into lines — the common case for line-anchored parsers. */
+export function readTextLines(filePath: string): string[] {
+  return readTextFile(filePath).split('\n');
+}

package/src/harness/script-check.ts

@@ -17,6 +17,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { loadScenarios, ScenarioInfo } from './parse';
 import { featureBasename } from './unit-paths';
+import { readTextFile } from './read-text';
 
 export interface ScriptCheckResult {
   screen: string;
@@ -153,7 +154,7 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
   let specTitles: string[] = [];
   let specSrc = '';
   if (committedSpec) {
-    specSrc = fs.readFileSync(committedSpec, 'utf-8');
+    specSrc = readTextFile(committedSpec);
     specTitles = extractTestTitles(specSrc);
   } else {
     findings.push('No generated spec found under specs/generated/ — run `sungen generate` / `/sungen:run-test` first.');
@@ -195,7 +196,7 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
       const fresh = findSpec(tmp, screenName, kind);
       if (fresh) {
         const a = normalize(specSrc);
-        const b = normalize(fs.readFileSync(fresh, 'utf-8'));
+        const b = normalize(readTextFile(fresh));
         if (a !== b) {
           drift = 'drift';
           // collect a few differing lines

package/src/harness/sensors.ts

@@ -10,6 +10,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { ScenarioInfo, ViewpointEntry, idPrefix } from './parse';
+import { readTextFile } from './read-text';
 
 // Business-critical category keywords (matched by CONTAINMENT against the VP category, so a
 // compound category like LIST-DISPLAY / ADD-TO-CART / PRODUCT-DISCOVERY classifies correctly).
@@ -56,7 +57,7 @@ export interface Catalog {
 
 export function loadCatalog(): Catalog {
   const p = path.join(__dirname, 'catalog', 'universal-viewpoints.yaml');
-  return parseYaml(fs.readFileSync(p, 'utf-8')) as Catalog;
+  return parseYaml(readTextFile(p)) as Catalog;
 }
 
 // Word-aware keyword match: `\b<kw>(s|es|ed|ing)?\b`, so a keyword matches whole words (plus
@@ -76,6 +77,10 @@ const has = (haystacks: string[], kw: string) => {
 
 export interface GateResult {
   pageType: string | null;
+  /** How the page type was decided — a declaration is authoritative, a guess is not. */
+  pageTypeSource?: 'declared' | 'detected' | 'undetermined';
+  /** Keyword evidence behind a detected type (best hits vs the runner-up). */
+  pageTypeEvidence?: { hits: number; runnerUp: number };
   themesTotal: number;
   themesCovered: number;       // deeply covered (has a data assertion)
   coverageRatio: number;
@@ -83,7 +88,18 @@ export interface GateResult {
   universalGaps: string[];
 }
 
-export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog, isMobile = false): GateResult {
+/**
+ * An explicit `page-type: <id>` line in test-viewpoint.md — the project stating what
+ * kind of screen this is. A declaration always beats keyword detection.
+ */
+export function declaredPageType(viewpointText: string, catalog: Catalog): string | null {
+  const m = viewpointText.match(/^\s*(?:[-*]\s*)?\**page[- ]?type\**\s*[:=]\s*`?([a-z0-9-]+)`?/im);
+  if (!m) return null;
+  const id = m[1].toLowerCase();
+  return Object.keys(catalog.page_types).includes(id) ? id : null;
+}
+
+export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog, isMobile = false, viewpointText = ''): GateResult {
   const haystacks = [
     ...scenarios.map((s) => s.haystack),
     ...viewpoints.map((v) => `${v.id} ${v.reason}`.toLowerCase()),
@@ -94,14 +110,35 @@ export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEn
   // too, so a mobile commerce/form screen is selected as ecommerce-list/form by keyword fit —
   // `mobile-home` does not crowd out a better-fitting type. With no type matching → pageType stays
   // null → no themes required → the gate passes leniently rather than false-FAILing.
+  // Detection needs EVIDENCE, not a single coincidental word. A knowledge-base search
+  // screen was classified `ecommerce-list` on ONE keyword hit and then judged against
+  // cart / add-to-cart / brand-filter themes it can never have — 40% of the quality
+  // score decided by one word, in both directions (an earlier misread scored it `auth`
+  // and handed it 3/3). Below the threshold the page type is UNDETERMINED: no themes
+  // are demanded (the audit says so instead of inventing a gap), and the project can
+  // settle it for good by declaring `page-type:` in test-viewpoint.md.
+  const MIN_HITS = 2;        // at least two distinct keywords
+  const MIN_MARGIN = 1;      // and a clear lead over the runner-up
   let pageType: string | null = null;
+  let source: GateResult['pageTypeSource'] = 'undetermined';
   let best = 0;
-  for (const [pt, def] of Object.entries(catalog.page_types)) {
-    if (pt.startsWith('mobile-') && !isMobile) continue;
-    const hits = def.detect_keywords.filter((k) => has(haystacks, k)).length;
-    if (hits > best) { best = hits; pageType = pt; }
+  let runnerUp = 0;
+  const declared = declaredPageType(viewpointText, catalog);
+  if (declared) {
+    pageType = declared;
+    source = 'declared';
+  } else {
+    for (const [pt, def] of Object.entries(catalog.page_types)) {
+      if (pt.startsWith('mobile-') && !isMobile) continue;
+      const hits = def.detect_keywords.filter((k) => has(haystacks, k)).length;
+      if (hits > best) { runnerUp = best; best = hits; pageType = pt; }
+      else if (hits > runnerUp) { runnerUp = hits; }
+    }
+    if (pageType && best >= MIN_HITS && best - runnerUp >= MIN_MARGIN) source = 'detected';
+    else { pageType = null; source = 'undetermined'; }
   }
 
+  const evidence = { hits: best, runnerUp };
   const gaps: GateResult['gaps'] = [];
   let total = 0, covered = 0;
   if (pageType) {
@@ -127,8 +164,13 @@ export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEn
 
   return {
     pageType,
+    pageTypeSource: source,
+    pageTypeEvidence: evidence,
     themesTotal: total,
     themesCovered: covered,
+    // No page type → no themes → the ratio is NOT a free 1.0: the score treats this
+    // axis as not-applicable and renormalises, so breadth can neither be faked nor
+    // punished by a guess.
     coverageRatio: total ? covered / total : 1,
     gaps,
     universalGaps,
@@ -376,8 +418,13 @@ export function coverageBalance(scenarios: ScenarioInfo[]): BalanceResult {
     byBucket[bucketForCategory(s.category)]++;
   }
 
-  const core = byBucket['business-core'];
-  const secondary = byBucket['presentation'] + byBucket['validation-security'];
+  // `behavior` (LOGIC / TRANSITION / WORKFLOW) IS business behaviour — it is the
+  // main category of sungen's own prescribed taxonomy. Counting only the commerce/API
+  // vocabulary (CART, PRODUCT, CHECKOUT, ENDPOINT…) as core meant a standard suite of
+  // 37 VP-LOGIC scenarios scored core=0 → a balance axis of 0% on a perfectly
+  // well-balanced suite. Navigation joins the secondary side, where it belongs.
+  const core = byBucket['business-core'] + byBucket['behavior'];
+  const secondary = byBucket['presentation'] + byBucket['validation-security'] + byBucket['navigation'];
   const imbalanced = secondary > core * 1.5 && core > 0;
   const unclassifiedRatio = scenarios.length ? byBucket['other'] / scenarios.length : 0;
   // A high `other` share means the VP taxonomy drifted from the catalog — the balance axis is then

package/src/harness/spec-coverage.ts

@@ -10,6 +10,7 @@
  */
 import * as fs from 'fs';
 import { ScenarioInfo } from './parse';
+import { readTextFile } from './read-text';
 
 export type Modality = 'MUST' | 'SHOULD' | 'MAY';
 
@@ -20,6 +21,11 @@ export interface SpecCoverageResult {
   frTotal: number;
   frCovered: number;
   uncoveredMust: { id: string; text: string }[];
+  /** Requirements counted as covered ONLY by keyword inference — no scenario
+   *  cites the id. The audit accepts that (it asks "did you think about this
+   *  requirement?"), but the link is not machine-checkable: delivery's
+   *  requirement table and any later refactor cannot follow it. */
+  inferredOnly: string[];
   triggerGaps: TriggerGap[];     // per-constraint trigger matrix gaps
   verdict: 'pass' | 'warn' | 'fail';
 }
@@ -40,8 +46,12 @@ const ACTION_TRIGGER: { trigger: string; re: RegExp }[] = [
 ];
 
 function modalityOf(text: string): Modality {
-  if (/\bMUST\b/.test(text)) return 'MUST';
-  if (/\bSHOULD\b/.test(text)) return 'SHOULD';
+  // Specs are written in the project's language — a Vietnamese spec states
+  // obligation with PHẢI / KHÔNG ĐƯỢC and recommendation with NÊN. Reading only
+  // English keywords silently demoted every requirement to MAY, so the
+  // "uncovered MUST" finding could never fire on those projects.
+  if (/\bMUST\b/i.test(text) || /\bPHẢI\b/i.test(text) || /KHÔNG ĐƯỢC/i.test(text)) return 'MUST';
+  if (/\bSHOULD\b/i.test(text) || /\bNÊN\b/i.test(text)) return 'SHOULD';
   return 'MAY';
 }
 
@@ -54,7 +64,7 @@ function actionTriggersIn(text: string): string[] {
 
 export function parseSpecClauses(specPath: string): { frs: FrClause[]; valRows: ValRow[] } {
   if (!fs.existsSync(specPath)) return { frs: [], valRows: [] };
-  const lines = fs.readFileSync(specPath, 'utf-8').split('\n');
+  const lines = readTextFile(specPath).split('\n');
 
   const frs: FrClause[] = [];
   for (const line of lines) {
@@ -97,12 +107,13 @@ function scenarioBlocks(featureText: string): string[] {
 export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featureText: string): SpecCoverageResult {
   const { frs, valRows } = parseSpecClauses(specPath);
   if (!fs.existsSync(specPath) || (frs.length === 0 && valRows.length === 0)) {
-    return { hasSpec: fs.existsSync(specPath), frTotal: 0, frCovered: 0, uncoveredMust: [], triggerGaps: [], verdict: 'pass' };
+    return { hasSpec: fs.existsSync(specPath), frTotal: 0, frCovered: 0, uncoveredMust: [], inferredOnly: [], triggerGaps: [], verdict: 'pass' };
   }
   const featLower = featureText.toLowerCase();
 
   // FR coverage: explicit @spec:FR / literal FR-id citation, else keyword fallback.
   const uncoveredMust: { id: string; text: string }[] = [];
+  const inferredOnly: string[] = [];
   let frCovered = 0;
   for (const fr of frs) {
     const idLower = fr.id.toLowerCase();
@@ -110,8 +121,12 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
     const words = [...new Set((fr.text.toLowerCase().match(/[a-z][a-z-]{4,}/g) || []))]
       .filter((w) => !/must|should|system|screen|users?|value|input|field/.test(w));
     const kwHit = words.length > 0 && scenarios.some((s) => words.filter((w) => s.haystack.includes(w)).length >= Math.min(2, words.length));
-    if (cited || kwHit) frCovered++;
-    else if (fr.modality === 'MUST') uncoveredMust.push({ id: fr.id, text: fr.text.slice(0, 90) });
+    if (cited || kwHit) {
+      frCovered++;
+      if (!cited) inferredOnly.push(fr.id); // covered, but nothing links it explicitly
+    } else if (fr.modality === 'MUST') {
+      uncoveredMust.push({ id: fr.id, text: fr.text.slice(0, 90) });
+    }
   }
 
   // Per-constraint trigger coverage — the matrix-collapse catch.
@@ -135,5 +150,5 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
   const verdict: SpecCoverageResult['verdict'] =
     uncoveredMust.length > 0 || triggerGaps.length > 0 ? 'fail' : 'pass';
 
-  return { hasSpec: true, frTotal: frs.length, frCovered, uncoveredMust, triggerGaps, verdict };
+  return { hasSpec: true, frTotal: frs.length, frCovered, uncoveredMust, inferredOnly, triggerGaps, verdict };
 }

package/src/harness/trace.ts

@@ -15,23 +15,24 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { reportSlug } from './unit-paths';
 import { segmentRuns, latestRunEvents, LedgerEvent } from './ledger';
+import { readTextFile } from './read-text';
 
 interface ManualItem { scenario: string; reason: string }
 
 function readJson(p: string): any | null {
-  try { return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf-8')) : null; } catch { return null; }
+  try { return fs.existsSync(p) ? JSON.parse(readTextFile(p)) : null; } catch { return null; }
 }
 
 function readLedger(screen: string): any[] {
   const p = path.join(process.cwd(), '.sungen', 'ledger', `${reportSlug(screen)}.jsonl`);
   if (!fs.existsSync(p)) return [];
-  return fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  return readTextFile(p).split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
 }
 
 /** Parse @manual scenarios + the explanatory comment line above each. */
 function parseManual(featurePath: string): ManualItem[] {
   if (!fs.existsSync(featurePath)) return [];
-  const lines = fs.readFileSync(featurePath, 'utf-8').split('\n');
+  const lines = readTextFile(featurePath).split('\n');
   const out: ManualItem[] = [];
   for (let i = 0; i < lines.length; i++) {
     const m = lines[i].match(/^\s*Scenario:\s*(.+)$/);

package/src/harness/viewpoint-ledger.ts

@@ -10,6 +10,7 @@
  */
 import * as fs from 'fs';
 import { ScenarioInfo } from './parse';
+import { readTextFile } from './read-text';
 
 export interface LedgerItem { id?: string; text: string; covered: boolean }
 
@@ -27,7 +28,7 @@ const GENERIC = new Set(['display', 'shown', 'value', 'field', 'input', 'page',
 /** Extract atomic checklist items from a viewpoint file (format-tolerant). */
 export function parseViewpointItems(viewpointPath: string): { id?: string; text: string }[] {
   if (!fs.existsSync(viewpointPath)) return [];
-  const lines = fs.readFileSync(viewpointPath, 'utf-8').split('\n');
+  const lines = readTextFile(viewpointPath).split('\n');
   const items: { id?: string; text: string }[] = [];
   let inFence = false;
   for (const raw of lines) {

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

@@ -68,6 +68,15 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the design loop differs — **no visual capture, no selectors**; the contract is the named-endpoint catalog. **Follow the `sungen-api-design` + `sungen-api-coverage-model` skills end-to-end** instead of the screen/flow steps: `sungen context --area <name>` (discover endpoints + `fields:`) → **enumerate the Tier-1 case list per endpoint from the coverage model** (contract + not-found/required-matrix + auth + idempotency, expanded mechanically from `fields:`) → generate `@api`/`@cases`/flow/`@concurrent`/`@query` scenarios with **strict assertions** (prove the effect, never status-only) → **`sungen audit --area <name>` gate + reviewer + repair loop to businessDepth ≥ 0.7** → record + trace. Then recommend `/sungen-run-test <name>`. The capture / viewpoint-group / selector steps do **not** apply.
 {{/cap}}
 
+## Requirement traceability (before you finish)
+
+Cross-check `requirements/spec.md` against the scenarios you wrote: every `FR-`/`TR-`/`NFR-` id
+must either carry a `@spec:<id>` tag on the scenario that proves it, or be a conscious
+out-of-scope decision you state in the summary. `sungen audit` reports `SPEC-TRACE-IMPLICIT` for
+requirements it could only match by keyword — treat that list as a to-do: add the tag to the
+proving scenario, do not leave the link to inference. Delivery's requirement table follows the
+tag only, so an untagged requirement is later reported as an uncovered gap.
+
 ## Steps
 
 {{#cap parallel-subagents}}

package/src/orchestrator/templates/ai-src/commands/delivery.md

@@ -1,7 +1,7 @@
 ---
 name: delivery
 description: "Export the Test Case & Coverage Matrix (review/manual/customer deliverable) from Gherkin + Playwright results. --legacy exports the classic per-scenario CSV/XLSX."
-argument-hint: "[name...] [--env <locale>] [--legacy] (omit names for all; --env for locale-specific export)"
+argument-hint: "[name...] [--format csv] [--env <locale>] [--legacy] (omit names for all)"
 order: 50
 claude-tools: "Bash, Read, Write, AskUserQuestion"
 copilot-tools: "[read, execute, edit, vscode/askQuestions]"
@@ -26,7 +26,14 @@ review → approve → official render.
 ## Parameters
 
 Parse from `$ARGUMENTS`:
-- **names** — zero or more screen/flow/api names. Empty → all targets.
+- **names** — zero or more screen/flow/api names. Empty → **a sweep of every unit**.
+  Strictness follows the scope: a **named** unit that is not ready aborts the run (the user asked
+  for that unit); a **sweep** exports every ready unit and skips the rest with an accounted
+  "Not exported" list, succeeding as long as something was written. So `/sungen:delivery` with no
+  argument is safe in a work-in-progress project — scaffolded units (added but `create-test` not
+  run) no longer block the units that are ready.
+- **`--format <xlsx|csv|both>`** — output format. **Default `xlsx` — one artifact only.** Pass
+  `--format csv` when the user wants the flat CSV (pipelines/diffing), `--format both` for both.
 - **`--env <locale>`** — sets `SUNGEN_ENV=<locale>` for the run (accept `--locale` as alias).
 - **`--legacy` / `--full`** — pass through to the CLI and skip the map flow entirely.
 
@@ -37,14 +44,19 @@ Parse from `$ARGUMENTS`:
 ```bash
 [ -x ./bin/sungen.js ] && ./bin/sungen.js delivery <names> || npx sungen delivery <names>
 ```
-(prepend `SUNGEN_ENV=<locale>` when `--env` was given; append `--legacy` when requested — then skip
-to step 5.)
+(prepend `SUNGEN_ENV=<locale>` when `--env` was given; append `--format <fmt>` when the user asked
+for a non-default format; append `--legacy` when requested — then skip to step 5.)
 
 Three outcomes per target:
 - **Rendered** → done, go to step 5.
 - **"no delivery map"** → go to step 2 (propose it).
 - **Gate findings / "not approved"** → go to step 4 (review & approve).
 
+On a sweep, read the **"Not exported"** list at the end: units marked *not authored yet* need
+`/sungen:create-test` first, the others each printed their own reason above (missing map, gate
+errors, or awaiting approval). Handle them one unit at a time — do not re-run the sweep expecting
+a different result.
+
 ### 2. Propose the Delivery Map (only when missing or the user asks to regroup)
 
 Read the unit's `.feature` (and `requirements/spec.md` for target naming). Write
@@ -58,27 +70,97 @@ groups:
     target: login.email            # ONE target: field/component dot-path, flow phrase, or METHOD /path
     intent: <one behavior/rule this item verifies>
     oracle: <the shared observable Pass/Fail statement>
-    category: normal | abnormal | security | nfr
+    dimensions: violated rule — required ×3 · format ×10 · full-width ×2   # see below
+    category: normal | abnormal | security | nfr   # see the rule below
     review: proposed               # ALWAYS proposed — only QA approval flips it
-    variants: [VP-VAL-001-B, VP-VAL-001-S]   # VP-ids; bare id on a @cases scenario = all its rows
+    variants: [VP-VAL-001-B, VP-VAL-001-S]   # the scenario ids of THIS project (VP-…, SEC-123, MS-HP-001 —
+                                             # whatever the titles use); a bare id on a @cases scenario = all its rows
 dispositions:                      # scenarios intentionally NOT delivered as test cases
   VP-DATA-000: { as: excluded, reason: data-setup checklist }
   # as: excluded | blocked | covered_elsewhere | accepted_risk
 ```
 
-**Grouping rules (the aggregation signature):**
-- One group = **one target + one intent + one oracle family**. When unsure, keep items separate —
-  the gates and QA decide, never guess-merge.
-- MAY share a group (become coverage dimensions): equivalence partitions, boundary values,
-  different data (`@cases` rows), a different trigger with the same oracle (blur vs submit),
-  locales.
-- MUST split: different target, intent, oracle family, category, execution mode (`@manual` vs
-  auto), test layer (`@api`/`@query`), or priority tag; sequence-sensitive flows (re-Given/When
-  after a Then) stay solo.
+**Grouping rules (the aggregation signature) — group COMPACTLY.** The matrix exists to be
+substantially shorter than the scenario list, so a reviewer can see missing viewpoints at a
+glance. Merge whenever the cases share ALL of: target · test intent/business rule ·
+precondition/condition · trigger or procedure shape · **the way the expected result is
+determined** (its oracle *family*, not its exact message).
+
+- **Oracle family = the determination method, parameterized.** All validation branches of ONE
+  field belong to ONE item — required, format, length, character-class are *expected branches*
+  (parameters) of "the field shows the validation message defined for the violated rule", shown
+  per variant, never separate items.
+- MAY vary inside one item (coverage dimensions, visible on the sub-rows): data values, boundary
+  points, **account states** (a seeded/locked/deleted account next to a wrong-password case),
+  provider/browser/locale, `@cases` rows, a different trigger with the same oracle (blur vs
+  submit), **execution mode** (auto + manual mix — the parent shows `Auto n · Manual m`), and
+  **priority** (the item takes the highest; per-variant priorities stay visible).
+- MUST split: different target, different intent/business rule, different way of determining the
+  expected result (a field-error family ≠ a session-established family), different test layer
+  (`@api`/`@query`), materially different precondition, or a different procedure shape —
+  sequence-sensitive flows (re-Given/When after a Then) stay solo. **Different risk classes never
+  merge**: XSS and SQL injection are separate items (different risk and determination), even on
+  the same field.
+- **Look for these families before settling on a grouping** — they are where under-merging happens:
+  | Family | Merge into one item |
+  |---|---|
+  | Static render | every "element X is visible/has its content on load" scenario of the screen — title, instructions, progress step, buttons present, header/footer |
+  | Field validation branches | all rules of ONE field (required · format · length · character class · full-width) |
+  | Account/entity states | wrong-credentials · locked · deleted · unverified for the same rejection oracle |
+  | Provider / surface sets | the 3 OAuth providers, header+footer, the a11y surfaces of one behaviour |
+  | Lifetime / mode pairs | checked vs unchecked, mobile vs desktop, when the oracle is one rule with two branches |
+  On a 36-scenario screen, four separate one-variant "renders on load" items should have been one.
+- When unsure, keep items separate — the gates and QA decide, never guess-merge.
 - Every scenario must land in exactly one group **or** one disposition (Gate B enforces 100%
   disposition). Data-setup blocks (`@manual:data-setup`) → `excluded`; SPEC-GAP placeholders →
   `blocked`.
 
+**`dimensions:` — the compact coverage digest (required for items with >3 variants).**
+This one short line is what the collapsed parent row shows instead of listing every variant, so a
+reviewer sees *which dimensions* the item covers without expanding it. Name the dimension, then the
+branches with counts:
+- `violated rule — required ×3 · format ×10 · full-width ×2`
+- `account state — wrong password · unregistered · locked · soft-deleted`
+- `submission method — Login button · Enter in Password · Enter in Email`
+
+Keep it ≤120 chars (Gate W warns). **YAML caveat:** a bare `: ` inside the value breaks the parse —
+use ` — ` as the label separator (as above) or quote the whole string.
+
+**`category` is not free choice for two classes (Gate K checks it):** a group whose variants are
+`VP-SEC-*` MUST be `category: security`, and `VP-NFR-*` MUST be `nfr` — otherwise the Coverage
+sheet's security/nfr column renders empty and the grid reports a gap the unit does not have while
+hiding the work it does have. `normal` vs `abnormal` stays your judgement.
+
+**Wording rules for `intent`/`oracle` (customer-facing — Gate W lints these):**
+- Plain product language, present simple, ~10–20 words, one behavior:
+  "A user can sign in with valid credentials and is redirected to the Jobs page."
+- Oracle = the observable outcome as a definite assertion ("The Jobs page is displayed and the
+  Logout link is visible.") — no `should`, no tester actions.
+- NEVER: `{{tokens}}`, `[Selector]` references, DSL phrasing (`User fill/click/see`), generator
+  labels (`Setup:`/`Observable:`/`Oracle:`), or vague verbs (`handles`, `surfaces`) when a precise
+  behavior exists. Use the visible UI label (the Login button, the Email field).
+- **Preserve the source meaning exactly** — never strengthen, weaken, or reinterpret an oracle
+  (a security assertion especially: if the source says "the password appears ONLY in the HTTPS
+  POST body", do not write "no plaintext password on the network").
+
+**Requirement coverage (`requirements:` section, optional):** `sungen delivery` scans
+`requirements/spec.md` for FR-/TR-/NFR- ids; ids traced by `@spec:` tags are `covered`, the rest
+are `gap` (Gate R warning). Record the reviewed status for genuine non-gaps:
+
+```yaml
+requirements:
+  TR-007: { status: planned, note: Performance needs Lighthouse-style tooling }
+  TR-004: { status: partially_covered, note: client-side covered by VP-SEC-003; hashing needs DB verify }
+  # status: covered | partially_covered | covered_elsewhere | planned | gap | not_applicable
+```
+
+**Never write `status: covered` for a requirement no variant traces to** (Gate R flags it). A note
+saying "proven by DI-SEC-CSRF" is prose — nothing detects it when that scenario later changes. If a
+scenario in THIS feature proves the requirement, **add `@spec:<id>` to that scenario** so the trace
+is real, then drop the override (it derives as `covered` on its own). Use `covered_elsewhere` only
+when another suite proves it, and name that suite; `not_applicable` when the spec itself excludes
+the requirement.
+
 Then validate and fix any ERROR findings:
 
 ```bash
@@ -115,6 +197,7 @@ counted in variants, never items**). Then `AskUserQuestion`:
 - **Open the workbook** — inspect `qa/deliverables/<unit>-testcases.xlsx` (Testcases sheet:
   collapse outline level 1 for the customer view; Coverage sheet: target × category grid + gaps).
 - **Run tests to refresh results** — `/sungen:run-test <unit>`, then re-run delivery.
+- **Also export CSV** — `sungen delivery <unit> --format csv` (flat `item`/`variant` rows for pipelines).
 - **Export the legacy workbook too** — `sungen delivery <unit> --legacy`.
 - **Done**
 
@@ -132,7 +215,8 @@ counted in variants, never items**). Then `AskUserQuestion`:
 ## CLI reference
 
 ```
-sungen delivery [names...]        # matrix (default; needs the map)
+sungen delivery [names...]        # matrix (default; needs the map) → XLSX only
+  --format <xlsx|csv|both>        # output format; default xlsx (one artifact)
   --check                         # gates only — validate the map, write nothing
   --approve [DI-a,DI-b]           # flip proposed→approved (+ stamp fingerprints); all groups when bare
   --preview                       # render despite review findings (DRAFT watermark)
@@ -140,5 +224,6 @@ sungen delivery [names...]        # matrix (default; needs the map)
   --skip-preflight | --continue-on-missing | --env <env>   # as before
 ```
 
-Outputs: `qa/deliverables/<unit>-testcases.xlsx` (Testcases + Coverage sheets) + `.csv`
-(flat, `Level` column `item|variant`). Legacy mode writes the classic files instead.
+Outputs: `qa/deliverables/<unit>-testcases.xlsx` (Testcases + Coverage sheets) by default;
+`--format csv` writes `<unit>-testcases.csv` instead (flat, `Level` column `item|variant`),
+`--format both` writes both. Legacy mode writes the classic files instead.