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

package/src/exporters/matrix/wording.ts

@@ -0,0 +1,221 @@
+/**
+ * Wording normalization — deterministic rendering step AFTER semantic
+ * normalization (review feedback §10): turn sungen DSL steps into controlled
+ * manual-test English without changing the target, condition, trigger,
+ * precondition, oracle, or trace.
+ *
+ * - Actions render in the imperative:      "User fill [Email] field with X"
+ *                                        →  "Enter X in the Email field."
+ * - Expected results render as observable assertions (never tester actions):
+ *   "User see [Jobs] page" → "The Jobs page is displayed."
+ * - Manual `# Tester verifies:` labels (Setup:/Action:/Observable:/Oracle:)
+ *   become structured fields instead of prose: Setup → precondition,
+ *   Action → action, Observable → expected, Oracle → verification method.
+ */
+
+/** A step that CAPTURES a runtime value: `User remember [X] text as {{var}}`. */
+export const RUNTIME_CAPTURE = /\bremember\b/i;
+
+/**
+ * Variable names a scenario defines at RUN TIME rather than reading from
+ * test-data: values captured from the page (`remember … as {{v}}`) and values
+ * bound by a capability precondition tag (`@query:`, `@api:`, `@dataFactory:`).
+ * The compiler already treats these as "captured" (DataResolver.registerCaptured);
+ * the delivery matrix must agree or it demands a static value that cannot exist.
+ */
+export function runtimeVarsOf(stepTexts: string[], tags: string[]): Set<string> {
+  const out = new Set<string>();
+  for (const text of stepTexts) {
+    if (!RUNTIME_CAPTURE.test(text)) continue;
+    const m = text.match(/\bas\s+\{\{\s*([^}]+?)\s*\}\}/i);
+    if (m) out.add(m[1].trim());
+  }
+  // A capability precondition binds its result under the endpoint/query/recipe
+  // name, so `{{<name>}}` and `{{<name>.field}}` exist only during the run.
+  for (const t of tags) {
+    const m = t.match(/^@(?:query|api|dataFactory):([^(\s]+)/);
+    if (m) out.add(m[1]);
+  }
+  return out;
+}
+
+// `[Email] field` → `Email field` (the visible label + its element type).
+function deRef(text: string): string {
+  return text.replace(/\[([^\]]+)\]/g, '$1');
+}
+
+function sentence(text: string): string {
+  // Trim the ENDS only — internal whitespace may be the test data itself
+  // (a padded email, a spaces-only value); collapsing it would silently
+  // change what the tester types (review GAP-04).
+  let s = text.trim();
+  if (!s) return s;
+  s = s.charAt(0).toUpperCase() + s.slice(1);
+  if (!/[.!?…"]$/.test(s)) s += '.';
+  return s;
+}
+
+/**
+ * Render one action step in the imperative. Pattern table covers the common
+ * sungen step verbs; anything unmatched falls back to actor-stripped text —
+ * still readable, never a raw `User fill`.
+ */
+export function renderAction(raw: string): string {
+  let s = raw.trim().replace(/^(User|The user)\s+/i, '');
+  // `remember … as {{v}}` DECLARES a runtime variable — the trailing token is a
+  // name, not a value to resolve. Quote it so no `{{brace}}` reaches the sheet
+  // whatever rule matches below.
+  if (RUNTIME_CAPTURE.test(s)) s = s.replace(/\bas\s+\{\{\s*([^}]+?)\s*\}\}/i, 'as "$1"');
+
+  const rules: Array<[RegExp, (m: RegExpMatchArray) => string]> = [
+    // remember [X] (text|value) as "v" — capture a value for a later comparison
+    [/^remembers? \[([^\]]+)\]\s*(text|value)?\s*as "([^"]+)"$/i,
+      (m) => `Note the ${m[1]} ${m[2] || 'text'} for later (as "${m[3]}")`],
+    // fill [X] field with V
+    [/^fills? \[([^\]]+)\][a-z ]* with (.+)$/i, (m) => `Enter ${m[2]} in the ${m[1]} field`],
+    // clear [X] field
+    [/^clears? \[([^\]]+)\](.*)$/i, (m) => `Clear the ${m[1]}${m[2] || ' field'}`],
+    // click [X] <type>
+    [/^clicks? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Click the ${m[1]}${m[2] ? ` ${m[2]}` : ''}`],
+    // press <Key> at/in [X] field
+    [/^press(?:es)? (.+?) (?:at|in|on|inside) \[([^\]]+)\](?: field)?$/i, (m) => `Press ${m[1]} in the ${m[2]} field`],
+    [/^press(?:es)? (.+)$/i, (m) => `Press ${m[1]}`],
+    // select V in/from [X] dropdown
+    [/^selects? (.+?) (?:in|from) \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Select ${m[1]} in the ${m[2]}${m[3] ? ` ${m[3]}` : ''}`],
+    // check/uncheck [X] checkbox
+    [/^(un)?checks? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `${m[1] ? 'Uncheck' : 'Check'} the ${m[2]}${m[3] ? ` ${m[3]}` : ''}`],
+    // hover [X]
+    [/^hovers? (?:over )?\[([^\]]+)\]\s*(\w+)?$/i, (m) => `Hover over the ${m[1]}${m[2] ? ` ${m[2]}` : ''}`],
+    // upload V to [X]
+    [/^uploads? (.+?) (?:to|into) \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Upload ${m[1]} to the ${m[2]}${m[3] ? ` ${m[3]}` : ''}`],
+    // is on [X] page (as an action = navigate)
+    [/^is on \[([^\]]+)\] page(.*)$/i, (m) => `Open the ${m[1]} page${m[2] ?? ''}`],
+    // wait for [X] <type> (is )?visible
+    [/^waits? for \[([^\]]+)\]\s*(\w+)?(?: is)?(?: visible)?$/i, (m) => `Wait until the ${m[1]}${m[2] ? ` ${m[2]}` : ''} is visible`],
+    // scroll to [X]
+    [/^scrolls? (?:to|into) \[([^\]]+)\]\s*(\w+)?$/i, (m) => `Scroll to the ${m[1]}${m[2] ? ` ${m[2]}` : ''}`],
+  ];
+
+  for (const [re, out] of rules) {
+    const m = s.match(re);
+    if (m) return sentence(deRef(out(m)));
+  }
+  return sentence(deRef(s));
+}
+
+/**
+ * Render one expected step as an observable assertion (no tester action, no
+ * `should`, no DSL `User see`).
+ */
+export function renderExpected(raw: string): string {
+  // A capture step is an INSTRUCTION wherever it sits — Gherkin often chains
+  // `remember … / remember … / expect a is not b` inside one Then block. Render
+  // it as the note-it-down action, never as an assertion (and never leaving the
+  // declared `{{name}}` token behind).
+  if (RUNTIME_CAPTURE.test(raw) && /\bas\s+\{\{/.test(raw)) return renderAction(raw);
+  let s = raw.trim().replace(/^(User|The user)\s+/i, '');
+
+  const rules: Array<[RegExp, (m: RegExpMatchArray) => string]> = [
+    // expect A is (not) B — comparing two captured values (order matters: "is not" first)
+    [/^expects? (.+?) is not (.+)$/i, (m) => `${m[1]} differs from ${m[2]}`],
+    [/^expects? (.+?) is (.+)$/i, (m) => `${m[1]} equals ${m[2]}`],
+    // see all [X] <type> contain(s) V — every matching element, not just the first
+    [/^sees? all \[([^\]]+)\]\s*(\w+)? (?:contains?|match(?:es)?|belongs?) (.+)$/i,
+      (m) => `Every ${m[1]}${m[2] ? ` ${m[2]}` : ''} contains ${m[3]}`],
+    // see all [X] <type> contain [Child] <type> — structural per-item proof
+    [/^sees? all \[([^\]]+)\]\s*(\w+)? (?:contains?|includes?) \[([^\]]+)\]\s*(\w+)?$/i,
+      (m) => `Every ${m[1]}${m[2] ? ` ${m[2]}` : ''} contains a ${m[3]}${m[4] ? ` ${m[4]}` : ''}`],
+    // see [X] page
+    [/^sees? \[([^\]]+)\] page$/i, (m) => `The ${m[1]} page is displayed`],
+    // see [X] <type> with V
+    [/^sees? \[([^\]]+)\]\s*(\w+)? with (.+)$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} shows ${m[3]}`],
+    // see [X] <type> contains V
+    [/^sees? \[([^\]]+)\]\s*(\w+)? contains (.+)$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} contains ${m[3]}`],
+    // see [X] <type> has text V
+    [/^sees? \[([^\]]+)\]\s*(\w+)? has text (.+)$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} shows ${m[3]}`],
+    // see [X] <type> is hidden / is disabled / is enabled / …
+    [/^sees? \[([^\]]+)\]\s*(\w+)? is (.+)$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} is ${m[3]}`],
+    // not see [X] <type>
+    [/^(?:do(?:es)? )?not sees? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} is not displayed`],
+    // see [X] <type>
+    [/^sees? \[([^\]]+)\]\s*(\w+)?$/i, (m) => `The ${m[1]}${m[2] ? ` ${m[2]}` : ''} is visible`],
+  ];
+
+  for (const [re, out] of rules) {
+    const m = s.match(re);
+    if (m) return sentence(deRef(out(m)));
+  }
+  return sentence(deRef(s));
+}
+
+/** Precondition wording: a state, not an action ("The user is signed out."). */
+export function renderPrecondition(raw: string): string {
+  const s = raw.trim().replace(/^(User|The user)\s+/i, '');
+  const m = s.match(/^is on \[([^\]]+)\] page(.*)$/i);
+  if (m) return sentence(`The user is on the ${m[1]} page${m[2] ?? ''}`);
+  // "wait for [X] <type> (is) visible" is a STATE once established, not an action.
+  const w = s.match(/^waits? for \[([^\]]+)\]\s*(\w+)?(?: is)?(?: visible)?$/i);
+  if (w) return sentence(`The ${w[1]}${w[2] ? ` ${w[2]}` : ''} is visible`);
+  const auth = s.match(/^is (signed|logged) (in|out)(.*)$/i);
+  if (auth) return sentence(`The user is ${auth[1]} ${auth[2]}${auth[3] ?? ''}`);
+  return sentence(deRef(`The user ${s.charAt(0).toLowerCase()}${s.slice(1)}`));
+}
+
+/**
+ * A manual `Setup:` line is an INSTRUCTION the tester performs to establish the
+ * state — imperative reads correctly ("Seed the locked account."), while
+ * "The user seed …" is broken grammar (review GAP-08).
+ */
+export function renderSetupInstruction(raw: string): string {
+  return renderAction(raw);
+}
+
+// ---------------------------------------------------------------------------
+// Manual `# Tester verifies:` comment classification (structured, label-free)
+// ---------------------------------------------------------------------------
+
+export interface ManualProcedure {
+  /** Setup/Precondition/Arrange lines — the state to establish first. */
+  preconditions: string[];
+  /** Action/unlabelled lines — the imperative procedure. */
+  actions: string[];
+  /** Observable/Expect/Result/Assert lines — the observable outcome. */
+  expected: string[];
+  /** Oracle/Verify lines — HOW to check (tools, panes, queries). */
+  verification: string[];
+}
+
+/**
+ * Split a manual scenario's numbered comment lines into the four structured
+ * fields. Labels are consumed (structured), never left inside the prose —
+ * review feedback §10.2(3). Continuation lines append to the previous item;
+ * pre-amble (rationale/header/dividers) is skipped.
+ */
+export function classifyManualComments(comments: string[]): ManualProcedure {
+  const out: ManualProcedure = { preconditions: [], actions: [], expected: [], verification: [] };
+  let last: { list: string[]; idx: number } | null = null;
+
+  const bucketOf = (label: string): keyof ManualProcedure => {
+    if (/setup|precondition|arrange|given/i.test(label)) return 'preconditions';
+    if (/oracle|verify|verification|how to check/i.test(label)) return 'verification';
+    if (/observ|expect|result|then|assert/i.test(label)) return 'expected';
+    return 'actions';
+  };
+
+  for (const raw of comments) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (/^[-=*_]{2,}/.test(line)) { last = null; continue; }
+    const m = line.match(/^\d+[.)]\s*(?:([A-Za-z][A-Za-z /]*?):\s*)?(.+)$/);
+    if (m) {
+      const label = (m[1] || '').trim();
+      const text = m[2].trim();
+      const list = out[bucketOf(label)];
+      list.push(text);
+      last = { list, idx: list.length - 1 };
+    } else if (last) {
+      last.list[last.idx] += ' ' + line;
+    }
+  }
+  return out;
+}

package/src/exporters/scenario-merger.ts

@@ -10,6 +10,7 @@
 
 import { FeatureMetadata, OrderedStep, ScenarioMetadata, SpecFileData, SpecTest } from './types';
 import { isStepsBaseScenario, isSampleScaffoldScenario, extractTestcaseType } from './feature-parser';
+import { SCENARIO_ID } from './feature-parser';
 
 /**
  * Parse a @manual scenario's `# Tester verifies:` comment block into procedure vs
@@ -162,7 +163,7 @@ function findMatchingSpecTest(scenario: ScenarioMetadata, tests: SpecTest[]): Sp
   if (exact) return exact;
 
   // Fallback: match by VP-ID prefix (ignore trailing text differences)
-  const vpMatch = scenario.name.match(/^(VP-[A-Z][A-Z0-9]*-\d+(?:[a-zA-Z]|-[A-Z0-9]+)?)/);
+  const vpMatch = scenario.name.match(SCENARIO_ID);
   if (vpMatch) {
     const vpId = vpMatch[1];
     const byVp = tests.find((t) => t.vpId === vpId);

package/src/exporters/spec-parser.ts

@@ -5,6 +5,7 @@
 
 import * as fs from 'fs';
 import { SpecTest, SpecFileData } from './types';
+import { SCENARIO_ID } from './feature-parser';
 
 /**
  * Extract the inner body of a test('title', async (...) => { BODY }) block.
@@ -165,7 +166,7 @@ function classifyBlock(block: CodeBlock): 'precondition' | 'step' | 'expectation
  * Try to extract VP ID (e.g., VP-UI-001) from the start of a scenario title.
  */
 function extractVpId(title: string): string | undefined {
-  const match = title.match(/^(VP-[A-Z][A-Z0-9]*-\d+(?:[a-zA-Z]|-[A-Z0-9]+)?)\b/);
+  const match = title.match(new RegExp(SCENARIO_ID.source + '\\b'));
   return match ? match[1] : undefined;
 }
 

package/src/harness/audit.ts

@@ -27,6 +27,7 @@ import { viewpointLedger, parseViewpointItems, LedgerResult } from './viewpoint-
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { contextRouter } from '../capabilities/context-router';
+import { readTextFile } from './read-text';
 
 export interface AuditReport {
   screen: string;
@@ -118,7 +119,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const catalogScreenName = catalogIdFromScreenDir(screenDir);
 
   const specPath = path.join(screenDir, 'requirements', 'spec.md');
-  const featureText = fs.existsSync(featurePath) ? fs.readFileSync(featurePath, 'utf-8') : '';
+  const featureText = fs.existsSync(featurePath) ? readTextFile(featurePath) : '';
 
   const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
   const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
@@ -225,7 +226,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     findings.push(`COVERED-VIA-FLOW: critical theme "${c.theme}" is not covered on this screen but is deeply covered by flow "${c.flow}" — cross-screen depth correctly owned by the flow, so it is credited (not a screen gap). Verify with \`sungen flow-check\`.`);
   }
   // Verification-scope (advisory): API/DB verification the project's recorded test type never asked for.
-  for (const v of verificationScopeFindings(featureText, fs.existsSync(viewpointPath) ? fs.readFileSync(viewpointPath, 'utf-8') : '', capProfile)) {
+  for (const v of verificationScopeFindings(featureText, fs.existsSync(viewpointPath) ? readTextFile(viewpointPath) : '', capProfile)) {
     findings.push(`VERIFICATION-OUT-OF-SCOPE (${v.layer}): this unit ${v.message}`);
   }
   for (const g of gate.gaps) {
@@ -289,6 +290,14 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   for (const u of spec.uncoveredMust) {
     findings.push(`SPEC-UNCOVERED: ${u.id} (MUST) has no covering scenario — "${u.text}" → add a scenario or tag one @spec:${u.id}.`);
   }
+  if (spec.inferredOnly.length > 0) {
+    // Covered, but only by keyword inference — no scenario cites the id. Delivery's
+    // requirement table (and any later refactor) cannot follow an inferred link, so
+    // the trace has to be written down while the author still knows which scenario
+    // proves what.
+    const shown = spec.inferredOnly.slice(0, 8).join(', ');
+    findings.push(`SPEC-TRACE-IMPLICIT: ${spec.inferredOnly.length} requirement(s) are covered by keyword inference only (${shown}${spec.inferredOnly.length > 8 ? ', …' : ''}) — add \`@spec:<id>\` to the scenario that proves each so the trace survives edits and delivery can report it.`);
+  }
   if (taxonomyMismatch) {
     findings.push(`VP-TAXONOMY-MISMATCH: only ${(trace.mappedRatio * 100).toFixed(0)}% of scenarios use the viewpoint IDs declared in test-viewpoint.md — scenarios invented a generic VP-<CAT> scheme. Re-tag to the project's viewpoint IDs so the coverage matrix is accurate.`);
   }

package/src/harness/blindspot.ts

@@ -10,6 +10,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { readTextFile } from './read-text';
 
 export interface Blindspot {
   ts: string;
@@ -35,7 +36,7 @@ export function addBlindspot(entry: Omit<Blindspot, 'ts'> & { ts?: string }): st
 export function listBlindspots(): Blindspot[] {
   const p = storePath();
   if (!fs.existsSync(p)) return [];
-  return fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean).map((l) => {
+  return readTextFile(p).split('\n').filter(Boolean).map((l) => {
     try { return JSON.parse(l) as Blindspot; } catch { return null; }
   }).filter(Boolean) as Blindspot[];
 }

package/src/harness/capability-plan.ts

@@ -9,6 +9,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { loadDriverCatalog } from './capability';
+import { readTextFile } from './read-text';
 
 export type ReasonClass = 'capability' | 'keep' | 'flow';
 export interface ReasonDef { code: string; label: string; cls: ReasonClass; drivers: string[] }
@@ -61,7 +62,7 @@ interface ParsedScenario { name: string; tags: string[]; manual: boolean; reason
 /** Parse scenarios with their tags + the reason comment line above (for @manual). */
 export function parseScenarios(featurePath: string): ParsedScenario[] {
   if (!fs.existsSync(featurePath)) return [];
-  const lines = fs.readFileSync(featurePath, 'utf-8').split('\n');
+  const lines = readTextFile(featurePath).split('\n');
   const out: ParsedScenario[] = [];
   for (let i = 0; i < lines.length; i++) {
     const m = lines[i].match(/^\s*Scenario:\s*(.+)$/);
@@ -123,7 +124,7 @@ export interface ReasonMismatch { scenario: string; explicit: string; inferred:
  */
 export function manualReasonMismatches(featurePath: string): ReasonMismatch[] {
   if (!fs.existsSync(featurePath)) return [];
-  const lines = fs.readFileSync(featurePath, 'utf-8').split('\n');
+  const lines = readTextFile(featurePath).split('\n');
   const out: ReasonMismatch[] = [];
   for (let i = 0; i < lines.length; i++) {
     const m = lines[i].match(/^\s*Scenario:\s*(.+)$/);

package/src/harness/feedback.ts

@@ -12,6 +12,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { readTextFile } from './read-text';
 
 export type FeedbackType = 'test-design' | 'product' | 'other';
 export type FeedbackDecision = 'accept' | 'reject' | 'edit' | 'add' | 'none';
@@ -36,7 +37,7 @@ function currentAuditScore(screen?: string): number | undefined {
   if (!screen) return undefined;
   const p = path.join(process.cwd(), '.sungen', 'reports', `${screen}-audit.json`);
   if (!fs.existsSync(p)) return undefined;
-  try { return JSON.parse(fs.readFileSync(p, 'utf-8'))?.score?.overall; } catch { return undefined; }
+  try { return JSON.parse(readTextFile(p))?.score?.overall; } catch { return undefined; }
 }
 
 export function recordFeedback(entry: Omit<FeedbackEntry, 'ts' | 'source' | 'auditScore'> & { ts?: string; source?: string }): string {
@@ -60,7 +61,7 @@ export function recordFeedback(entry: Omit<FeedbackEntry, 'ts' | 'source' | 'aud
 export function readFeedback(): FeedbackEntry[] {
   const p = feedbackPath();
   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 FeedbackSummary {

package/src/harness/flow-check.ts

@@ -13,6 +13,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { loadScenarios } from './parse';
 import { parseScenarios } from './capability-plan';
+import { readTextFile } from './read-text';
 
 const KNOWN_TARGETS = ['cart', 'category', 'brand', 'detail', 'checkout', 'wishlist', 'order', 'payment', 'login'];
 
@@ -33,7 +34,7 @@ function featurePath(base: string, kind: 'screens' | 'flows', name: string): str
 }
 function featureTags(fp: string): string[] {
   if (!fs.existsSync(fp)) return [];
-  for (const line of fs.readFileSync(fp, 'utf-8').split('\n')) {
+  for (const line of readTextFile(fp).split('\n')) {
     const t = line.trim();
     if (t.startsWith('Feature:')) break;
     if (t.startsWith('@')) return t.split(/\s+/).filter((x) => x.startsWith('@'));

package/src/harness/flow-plan.ts

@@ -12,6 +12,7 @@ import * as path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { MANUAL_REASONS, inferReasonCode } from './capability-plan';
 import { buildFlowCheck, Contract } from './flow-check';
+import { readTextFile } from './read-text';
 
 const REF_RE = /\[([A-Za-z][\w ]*?):([\w &.-]+?)\]/g;
 
@@ -19,7 +20,7 @@ interface FlowScenario { name: string; manual: boolean; reason: string; tags: st
 
 function parseFlowScenarios(featurePath: string): FlowScenario[] {
   if (!fs.existsSync(featurePath)) return [];
-  const lines = fs.readFileSync(featurePath, 'utf-8').split('\n');
+  const lines = readTextFile(featurePath).split('\n');
   const out: FlowScenario[] = [];
   const idx: number[] = [];
   lines.forEach((l, i) => { if (/^\s*Scenario:/.test(l)) idx.push(i); });
@@ -50,7 +51,7 @@ function parseFlowScenarios(featurePath: string): FlowScenario[] {
 function selectorKeys(selectorsPath: string): Set<string> {
   if (!fs.existsSync(selectorsPath)) return new Set();
   try {
-    const y = parseYaml(fs.readFileSync(selectorsPath, 'utf-8')) || {};
+    const y = parseYaml(readTextFile(selectorsPath)) || {};
     return new Set(Object.keys(y).map((k) => k.toLowerCase()));
   } catch { return new Set(); }
 }

package/src/harness/intent.ts

@@ -14,6 +14,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { readTextFile } from './read-text';
 
 export type IntentFocus = 'functional' | 'e-commerce' | 'security' | 'smoke';
 
@@ -50,7 +51,7 @@ export function readIntent(projectRoot: string): IntentProfile {
   const ctx = path.join(projectRoot, 'qa', 'context.md');
   if (!fs.existsSync(ctx)) return DEFAULT_INTENT;
   let text: string;
-  try { text = fs.readFileSync(ctx, 'utf-8').toLowerCase(); } catch { return DEFAULT_INTENT; }
+  try { text = readTextFile(ctx).toLowerCase(); } catch { return DEFAULT_INTENT; }
 
   const grab = (key: string): string | undefined => {
     const m = text.match(new RegExp(`(?:^|\\n)\\s*${key}\\s*:\\s*([a-z0-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