@sun-asterisk/sungen 3.2.16-beta.7 → 3.2.16-beta.9

package/src/harness/journey.ts

@@ -16,6 +16,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
 import { reportSlug } from './unit-paths';
+import { readTextFile } from './read-text';
 
 export type ObStatus = 'satisfied' | 'needs-work' | 'pending' | 'waived';
 
@@ -44,13 +45,13 @@ export interface JourneyReport {
 }
 
 function readJSON(p: string): any {
-  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 readLedgerPhases(p: string): string[] {
   if (!fs.existsSync(p)) return [];
   const out: string[] = [];
-  for (const line of fs.readFileSync(p, 'utf-8').split('\n')) {
+  for (const line of readTextFile(p).split('\n')) {
     if (!line.trim()) continue;
     try { const d = JSON.parse(line); if (d.step) out.push(String(d.step)); } catch { /* skip */ }
   }

package/src/harness/ledger.ts

@@ -14,6 +14,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { reportSlug } from './unit-paths';
+import { readTextFile } from './read-text';
 
 export interface LedgerEvent {
   ts: string;
@@ -75,7 +76,7 @@ export function recordEvent(screen: string, ev: Omit<LedgerEvent, 'ts'> & { ts?:
 export function readEvents(screen: string): LedgerEvent[] {
   const p = ledgerPath(screen);
   if (!fs.existsSync(p)) return [];
-  return fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  return readTextFile(p).split('\n').filter(Boolean).map((l) => JSON.parse(l));
 }
 
 export interface LedgerReport {
@@ -121,7 +122,7 @@ export function buildReport(screen: string, opts: { allRuns?: boolean } = {}): L
   const auditPath = path.join(process.cwd(), '.sungen', 'reports', `${reportSlug(screen)}-audit.json`);
   if (fs.existsSync(auditPath)) {
     try {
-      const a = JSON.parse(fs.readFileSync(auditPath, 'utf-8'));
+      const a = JSON.parse(readTextFile(auditPath));
       coveredCritical = a?.gate?.themesCovered ?? null;
       scenarioCount = a?.scenarioCount ?? null;
     } catch { /* ignore */ }

package/src/harness/manifest.ts

@@ -12,6 +12,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { createHash } from 'crypto';
 import { featureBasename, reportSlug } from './unit-paths';
+import { readTextFile } from './read-text';
 
 export interface SpecSection { name: string; hash: string }
 export interface ManifestEntry { scenario: string; vpCode?: string; section: string; specHash: string }
@@ -59,7 +60,7 @@ function matchSection(featureSection: string, specNames: string[]): string | nul
 /** Parse spec.md into hashable sections (## and ### headings; "Section:" prefix stripped). */
 export function parseSpecSections(specPath: string): SpecSection[] {
   if (!fs.existsSync(specPath)) return [];
-  const lines = fs.readFileSync(specPath, 'utf-8').split('\n');
+  const lines = readTextFile(specPath).split('\n');
   const sections: { name: string; body: string[] }[] = [];
   let cur: { name: string; body: string[] } | null = null;
   for (const line of lines) {
@@ -79,7 +80,7 @@ export function parseSpecSections(specPath: string): SpecSection[] {
 /** Parse feature into scenario → section mapping using `# --- Section: X ---` comments. */
 function parseFeatureSections(featurePath: string): { scenario: string; vpCode?: string; section: string }[] {
   if (!fs.existsSync(featurePath)) return [];
-  const lines = fs.readFileSync(featurePath, 'utf-8').split('\n');
+  const lines = readTextFile(featurePath).split('\n');
   const out: { scenario: string; vpCode?: string; section: string }[] = [];
   let section = '(unsectioned)';
   for (const raw of lines) {
@@ -164,7 +165,7 @@ export function manifestPath(screenName: string): string {
 }
 export function loadManifest(screenName: string): Manifest | null {
   const p = manifestPath(screenName);
-  return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf-8')) : null;
+  return fs.existsSync(p) ? JSON.parse(readTextFile(p)) : null;
 }
 export function saveManifest(m: Manifest): string {
   const p = manifestPath(m.screen);

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

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/skills/sungen-delivery/SKILL.md

@@ -89,6 +89,11 @@ target × category grid with explicit `—` gaps, dispositions, manifest. CSV mi
 flat with a `Level` column (`item`/`variant`) + a requirement-coverage appendix.
 `delivery_item_count` ≠ progress — variants are the execution metric.
 
+**Runtime-captured values**: a scenario may produce its own values — `User remember [X] text as
+{{v}}` (compared later) or a capability binding (`@query:`/`@api:`/`@dataFactory:`). These never
+exist in test-data, so Gate D does not ask for them: the capture step renders as an instruction
+(`Note the X text for later (as "v")`) and later references read `the captured v`.
+
 **Data fidelity**: invisible test data is made visible, never normalized — `''` → `(empty)`,
 whitespace-only → `(5 spaces)`, padded → `" value "` quoted verbatim. A trim/collapse here would
 silently break the whitespace tests it describes.

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -288,6 +288,7 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 
 | Tag | Effect |
 |---|---|
+| `@spec:<id>` | **Traceability**: this scenario proves requirement `<id>` from `requirements/spec.md` (`@spec:FR-003`). Repeatable — a scenario may prove several. Read by `sungen audit` (requirement coverage) and by delivery (the Coverage sheet's requirement table). Without it the link is only inferred from wording and cannot survive an edit. |
 | `@manual` | Skip in generation |
 | `@auth:role` | Use auth storage state for role |
 | `@no-auth` | Disable inherited auth |

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

@@ -4,6 +4,28 @@ description: 'Use when create-test needs to translate spec.md/Figma/UI into .fea
 user-invocable: false
 ---
 
+
+## Traceability — tag the requirement each scenario proves
+
+Every requirement id in `requirements/spec.md` (`FR-`/`TR-`/`NFR-`) must be reachable from a
+scenario, and the link must be **written down, not inferred**:
+
+```gherkin
+@high @spec:FR-003
+Scenario: VP-VAL-002 An email in an invalid format shows the format error
+```
+
+- Put `@spec:<id>` on the scenario that actually proves the requirement; repeat the tag when one
+  scenario proves several (`@spec:FR-003 @spec:FR-004`).
+- One requirement may be proved by several scenarios — tag each of them.
+- A requirement you deliberately do not cover here (performance budget, i18n suite, server-side
+  concern) needs no tag; record it later in the delivery map's `requirements:` section with a
+  status and reason.
+- Why it matters: `sungen audit` also counts a requirement as covered when its keywords merely
+  resemble a scenario title, and reports `SPEC-TRACE-IMPLICIT` for those. Delivery's requirement
+  table follows **only** the explicit tag — an untagged requirement reads as an uncovered gap in
+  the customer-facing coverage sheet even when a scenario does prove it.
+
 ## ⚠️ 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.