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

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;
@@ -49,9 +50,15 @@ export interface AuditReport {
     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
@@ -118,7 +125,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 +154,8 @@ 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');
+  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 +219,51 @@ 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;
+  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, 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, 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 +272,20 @@ 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 (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 +349,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 +435,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 +454,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).

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);