@sun-asterisk/sungen 3.2.17 → 3.2.18

package/src/harness/audit.ts

@@ -9,6 +9,7 @@
 import * as path from 'path';
 import * as fs from 'fs';
 import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
+import { checkViewpointBaseline, ViewpointBaseline } from './viewpoint-baseline';
 import { featureBasename } from './unit-paths';
 import {
   loadCatalog, viewpointGate, assertionDepth, dataThemesFor, depthThresholdFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
@@ -27,6 +28,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;
@@ -45,13 +47,20 @@ export interface AuditReport {
   flowDepth: FlowDepthResult;   // H3 — stateful-flow regression depth (count / teardown / multi-source)
   oracle: OracleStrengthResult; // H4 — facet-oracle strength (weak name-substring vs title/detail/API/DB)
   ledger: LedgerResult;         // atomic viewpoint-item coverage (per-bullet status)
+  viewpointBaseline: ViewpointBaseline; // is the yardstick still the accepted one? (#557)
   calibration: {                // #8 — multi-axis score so a high overall can't hide a weak axis
     axes: Record<string, number>;
     weakest: { axis: string; value: number };
     inflated: boolean;
+    /** Axes excluded for lack of evidence (no spec / viewpoint file / decidable page type). */
+    notApplicable?: string[];
+    /** Set when a weak critical axis holds the overall down. */
+    cappedAt?: number;
   };
   score: {
-    overall: number;            // 0..10, business-weighted
+    overall: number;            // 0..10, business-weighted over the APPLICABLE axes
+    notApplicable?: string[];   // axes with no evidence — excluded, not scored as 1.0
+    cappedAt?: number;          // set when a weak critical axis holds the score down
     coverage: number;           // 0..1
     businessDepth: number;      // 0..1
     balance: number;            // 0..1
@@ -66,7 +75,7 @@ export interface AuditReport {
 }
 
 /** The catalog-resolution id for a unit dir (relative to qa/): screen · flows/<flow> · api/<area> · api/flows/<flow>. */
-function catalogIdFromScreenDir(screenDir: string): string {
+export function catalogIdFromScreenDir(screenDir: string): string {
   const parts = screenDir.split(path.sep);
   const qa = parts.lastIndexOf('qa');
   if (qa >= 0) {
@@ -118,7 +127,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);
@@ -147,7 +156,11 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const capGate = scoringCap?.gateProvider as
     ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus; cwd: string; screenName: string; threshold: number; businessCriticalMethods?: string[] }) => { gate: GateResult; depth: DepthResult }) | undefined;
   const provided = capGate?.({ scenarios, viewpoints, catalog, focus: intent.focus, cwd: projectRootFromScreenDir(screenDir), screenName: catalogScreenName, threshold: depthThresholdFor(intent.focus), businessCriticalMethods: intent.businessCriticalMethods });
-  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog, platform === 'mobile');
+  // Is the declaration this suite is measured against still the one a human accepted?
+  const viewpointBaseline = checkViewpointBaseline(
+    projectRootFromScreenDir(screenDir), catalogScreenName, viewpointPath);
+  const viewpointText = fs.existsSync(viewpointPath) ? readTextFile(viewpointPath) : '';
+  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog, platform === 'mobile', viewpointText);
   const depth = provided?.depth ?? assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
 
   // TQ-4 — deferral-aware coverage credit: an inherently cross-screen theme (cart / detail /
@@ -211,8 +224,57 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       : 1;
   const traceScore = 0.5 * trace.withVpCodeRatio + 0.5 * trace.mappedRatio;
 
-  // Business-weighted overall (coverage + depth dominate)
-  const rawOverall = (0.4 * coverage + 0.3 * businessDepth + 0.15 * balanceScore + 0.15 * traceScore) * 10;
+  // ---- Business-weighted overall -------------------------------------------
+  //
+  // Two rules make the number mean what it says:
+  //
+  //  1. Only axes the project supplies EVIDENCE for are scored, and the weights
+  //     are renormalised over them. The old formula spent 40% on page-type theme
+  //     coverage — which is 1.0 whenever no page type is detected — so a screen
+  //     with no detectable type collected 4 free points, while a mis-detected one
+  //     was judged against themes it can never have. Missing spec / viewpoint
+  //     files are treated the same way: absent evidence scores nothing, in either
+  //     direction.
+  //  2. The three axes the harness already measured but never counted —
+  //     claimProof, specFR, atomicLedger — now carry weight. A suite where two
+  //     thirds of the scenarios do not prove their own title used to score 7.9.
+  const specRatio = spec.frTotal ? spec.frCovered / spec.frTotal : 1;
+  //  3. Evidence has to be INDEPENDENT of what it judges. `atomicLedger` and
+  //     `traceability` both measure the suite against test-viewpoint.md, so a run
+  //     that rewrites that file scores them 100% by construction — which is exactly
+  //     what a create-test run did, silently dropping the performance viewpoint on
+  //     the way. While the declaration is unconfirmed, neither axis is evidence.
+  const viewpointMoved = viewpointBaseline.status === 'changed';
+  const axisDefs: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean }> = [
+    { key: 'coverage', value: coverage, weight: 0.22, applicable: !!gate.pageType && gate.themesTotal > 0, critical: true },
+    { key: 'specFR', value: specRatio, weight: 0.15, applicable: spec.hasSpec && spec.frTotal > 0, critical: true },
+    { key: 'atomicLedger', value: ledger.ratio, weight: 0.13, applicable: ledger.hasViewpoint && ledger.total > 0 && !viewpointMoved, critical: true },
+    { key: 'businessDepth', value: businessDepth, weight: 0.20, applicable: true, critical: true },
+    { key: 'claimProof', value: claim.ratio, weight: 0.15, applicable: claim.withClaims > 0, critical: true },
+    { key: 'traceability', value: traceScore, weight: 0.09, applicable: viewpoints.length > 0 && !viewpointMoved, critical: false },
+    { key: 'balance', value: balanceScore, weight: 0.06, applicable: true, critical: false },
+  ];
+  const scored = axisDefs.filter((a) => a.applicable);
+  const weightSum = scored.reduce((t, a) => t + a.weight, 0) || 1;
+  const weighted = scored.reduce((t, a) => t + a.weight * a.value, 0) / weightSum;
+
+  // A weak axis is a hole, and a hole must not be averaged away: the pass
+  // threshold teams set (7.x) has to mean "no hole", not "good on balance".
+  const criticalScored = scored.filter((a) => a.critical);
+  const weakestCritical = criticalScored.slice().sort((a, b) => a.value - b.value)[0];
+  const CAP_SEVERE = 6.9;   // below any 7.x gate
+  const CAP_WEAK = 7.9;
+  // Dropping an axis for lack of evidence must not become a shortcut to a perfect
+  // score: with no spec and no viewpoint file the remaining axes are easy to max.
+  // A top mark has to rest on complete evidence, so partial evidence caps below it.
+  const CAP_PARTIAL_EVIDENCE = 8.9;
+  let cap = 10;
+  if (weakestCritical && weakestCritical.value < 0.5) cap = CAP_SEVERE;
+  else if (weakestCritical && weakestCritical.value < 0.7) cap = CAP_WEAK;
+  const missingEvidence = axisDefs.filter((a) => !a.applicable).map((a) => a.key);
+  if (missingEvidence.length > 0) cap = Math.min(cap, CAP_PARTIAL_EVIDENCE);
+  const rawOverall = Math.min(weighted * 10, cap);
+  const capped = weakestCritical ? weighted * 10 > cap : false;
   // H7 — senior-grade band: the top decile (≥9) is reserved for suites that also clear the senior
   // axes — a stateful flow with FULL regression depth (count + teardown + multi-source), no weak
   // facet oracle, and no parallel-cart isolation risk. Otherwise the score is held just below 9, so
@@ -221,11 +283,27 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const overall = seniorBandedOverall(rawOverall, { flowStateful: flowDepth.stateful, flowRatio: flowDepth.ratio, oracleWeak: oracle.weak.length, isolationRisk: isoRisk });
 
   const findings: string[] = [];
+  if (capped) {
+    const why = weakestCritical && weakestCritical.value < 0.7
+      ? `"${weakestCritical.key}" is ${(weakestCritical.value * 100).toFixed(0)}% — a weak axis is a hole, not something the other axes can average away`
+      : `this unit supplies no evidence for [${missingEvidence.join(', ')}], and a top mark has to rest on complete evidence`;
+    findings.push(`SCORE-CAPPED: overall held at ${cap.toFixed(1)} because ${why}.`);
+  }
+  if (viewpointBaseline.status === 'changed') {
+    const moved = [
+      viewpointBaseline.removed?.length ? `removed [${viewpointBaseline.removed.join(', ')}]` : '',
+      viewpointBaseline.added?.length ? `added [${viewpointBaseline.added.join(', ')}]` : '',
+    ].filter(Boolean).join(', ');
+    findings.push(`VIEWPOINT-BASELINE-CHANGED: test-viewpoint.md no longer declares what it did when this unit was last accepted — ${moved || 'the declared ids were reordered or replaced'}. atomicLedger + traceability measure the suite AGAINST this file, so they are excluded from the score until the change is confirmed: a generator that rewrites the declaration scores both 100% by construction, and a viewpoint dropped from the file stops being missing from anything. Review the diff (a removed id means that coverage is now unclaimed), then run \`sungen audit --screen ${screenName} --accept-viewpoint\`.`);
+  }
+  if (gate.pageTypeSource === 'undetermined') {
+    findings.push(`PAGE-TYPE-UNDETERMINED: no page type fits this screen with enough confidence (best ${gate.pageTypeEvidence?.hits ?? 0} keyword hit(s)), so NO critical themes were demanded and the coverage axis is excluded from the score — declare it in test-viewpoint.md (\`page-type: <id>\`) to have the theme checklist applied.`);
+  }
   for (const c of flowCredits) {
     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 +367,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.`);
   }
@@ -367,15 +453,15 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // #8 — multi-axis calibration: a high overall must not hide a weak axis.
   const manualCompleteness = manualOracleResult.manualTotal
     ? 1 - manualOracleResult.insufficient.length / manualOracleResult.manualTotal : 1;
-  const axes: Record<string, number> = {
-    coverage: Math.round(coverage * 100) / 100,
-    businessDepth: Math.round(businessDepth * 100) / 100,
-    claimProof: Math.round(claim.ratio * 100) / 100,
-    specFR: spec.frTotal ? Math.round((spec.frCovered / spec.frTotal) * 100) / 100 : 1,
-    atomicLedger: Math.round(ledger.ratio * 100) / 100,
-    manualOracle: Math.round(manualCompleteness * 100) / 100,
-    taxonomy: taxonomyMismatch ? 0 : Math.round(trace.mappedRatio * 100) / 100,
-  };
+  // Only the axes that were actually scored appear here — an axis with no evidence
+  // (no spec, no viewpoint file, no decidable page type) is reported as such rather
+  // than as a silent 100%, which is what let empty inputs look like perfect ones.
+  const axes: Record<string, number> = {};
+  for (const a of scored) axes[a.key] = Math.round(a.value * 100) / 100;
+  // Measured but not weighted: they drive findings, not the headline.
+  axes.manualOracle = Math.round(manualCompleteness * 100) / 100;
+  axes.taxonomy = taxonomyMismatch ? 0 : Math.round(trace.mappedRatio * 100) / 100;
+  const notApplicable = axisDefs.filter((a) => !a.applicable).map((a) => a.key);
   const weakestEntry = Object.entries(axes).sort((a, b) => a[1] - b[1])[0];
   const weakest = { axis: weakestEntry[0], value: weakestEntry[1] };
   // Inflated when breadth hides a weak axis, OR when businessDepth is high but rests on a
@@ -386,7 +472,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   if (inflated) {
     findings.push(`SCORE-INFLATED-BY-BREADTH: overall ${Math.round(overall * 10) / 10}/10 but the weakest axis "${weakest.axis}" is ${(weakest.value * 100).toFixed(0)}% — breadth is hiding a weak dimension. Raise "${weakest.axis}" before trusting the headline.`);
   }
-  const calibration = { axes, weakest, inflated };
+  const calibration = { axes, weakest, inflated, notApplicable, cappedAt: capped ? cap : undefined };
 
   // Gate spans coverage (viewpoint themes), depth, claim-proof, spec-clause coverage,
   // AND taxonomy-match (scenarios must use the project's viewpoint IDs when defined).
@@ -397,7 +483,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     screen: screenName,
     scenarioCount: scenarios.length,
     gate, depth, claim, taxonomy, balance, duplicates, trace, spec,
-    taxonomyMismatch, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, flowDepth, oracle, ledger, calibration,
+    taxonomyMismatch, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, flowDepth, oracle, ledger, viewpointBaseline, calibration,
     score: {
       overall: Math.round(overall * 10) / 10,
       coverage: Math.round(coverage * 100) / 100,

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*(.+)$/);
@@ -113,6 +114,11 @@ export function inferFromText(reason: string): string | undefined {
   return undefined;
 }
 
+/** Every code the text supports, not just the first rule in declaration order. */
+export function inferAllFromText(reason: string): string[] {
+  return INFER.filter((r) => r.re.test(reason)).map((r) => r.code);
+}
+
 export interface ReasonMismatch { scenario: string; explicit: string; inferred: string }
 
 /**
@@ -123,7 +129,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*(.+)$/);
@@ -149,8 +155,15 @@ export function manualReasonMismatches(featurePath: string): ReasonMismatch[] {
       else if (l === '') continue;
       else break;
     }
-    const inferred = inferFromText(parts.join(' '));
-    if (inferred && inferred !== explicit) out.push({ scenario: m[1].trim(), explicit, inferred });
+    // The block scanned here includes the tester PROCEDURE, so several codes can
+    // match at once — "not worth automating" (M8, the author's actual reason) and
+    // "the service stays responsive" (M6, a word about latency, not layout). The
+    // first rule in declaration order used to win and the correct tag was reported
+    // as a mismatch. A tag is only wrong when the text supports some OTHER code and
+    // NOT the declared one.
+    const codes = inferAllFromText(parts.join(' '));
+    const inferred = codes.find((c) => c !== explicit);
+    if (inferred && !codes.includes(explicit)) out.push({ scenario: m[1].trim(), explicit, inferred });
   }
   return out;
 }

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