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

package/src/harness/capability.ts

@@ -15,9 +15,55 @@ import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 export interface CapabilityProfile {
   platform?: string;       // web | mobile | …  (the runtime adapter)
   enabled: string[];       // driver ids enabled for this project
+  /**
+   * Which VERIFICATION layers this project's test scope uses — the recorded "test type"
+   * (`ui` = E2E-only; add `api` / `db` when the project also verifies via API/DB). Explicit here wins;
+   * when absent it is DERIVED from `enabled` (ui always; api if the api driver is on; db if db is on).
+   * Generation and the audit use it so an E2E-only project does not get @api/@query verification it
+   * never asked for.
+   */
+  verification?: string[];
   source: 'capabilities.yaml' | 'absent';
 }
 
+export type VerifyLayer = 'ui' | 'api' | 'db';
+
+/**
+ * Effective verification scope = the recorded "test type". Explicit `verification` wins; otherwise
+ * derived from the enabled drivers. `ui` is always in scope (every project observes the UI/E2E result).
+ */
+export function verificationScope(profile: CapabilityProfile): Set<VerifyLayer> {
+  if (profile.verification?.length) {
+    const s = new Set<VerifyLayer>(['ui']);
+    for (const v of profile.verification) if (v === 'api' || v === 'db' || v === 'ui') s.add(v);
+    return s;
+  }
+  const s = new Set<VerifyLayer>(['ui']);
+  if (profile.enabled.includes('api')) s.add('api');
+  if (profile.enabled.includes('db')) s.add('db');
+  return s;
+}
+
+export interface VerifyScopeFinding { layer: 'api' | 'db'; message: string; }
+
+/**
+ * Flag API/DB verification that is OUT OF the project's recorded scope: a unit whose scenarios use
+ * `@api`/`@requires:api` (or `@query`/`@requires:db`) while the project is not API/DB-testing AND the
+ * viewpoint never asked for that layer. Deterministic; advisory only (a nudge, never a hard gate).
+ */
+export function verificationScopeFindings(featureText: string, viewpointText: string, profile: CapabilityProfile): VerifyScopeFinding[] {
+  const scope = verificationScope(profile);
+  const vp = (viewpointText || '').toLowerCase();
+  const out: VerifyScopeFinding[] = [];
+  if (/@api\b|@requires:\s*api\b/.test(featureText) && !scope.has('api') && !/\bapi\b/.test(vp)) {
+    out.push({ layer: 'api', message: 'uses @api / @requires:api verification, but this project is not API-testing (capabilities `enabled` has no `api`) and the viewpoint does not request API verification. Keep the oracle UI-observable, OR record API in scope (capabilities `verification: [ui, api]` or `sungen capability add api`). Reserve API/DB verify for the ≤20% of effects with no UI observation.' });
+  }
+  if (/@query\b|@requires:\s*db\b/.test(featureText) && !scope.has('db') && !/\b(database|db)\b/.test(vp)) {
+    out.push({ layer: 'db', message: 'uses @query / @requires:db verification, but this project is not DB-testing (capabilities `enabled` has no `db`) and the viewpoint does not request DB verification. Keep the oracle UI-observable, OR record DB in scope (capabilities `verification: [ui, db]` or `sungen capability add db`). Reserve API/DB verify for the ≤20% of effects with no UI observation.' });
+  }
+  return out;
+}
+
 export interface DriverMeta {
   id: string;
   kind: 'platform' | 'capability';
@@ -41,6 +87,7 @@ export function readCapabilities(cwd: string): CapabilityProfile {
     return {
       platform: typeof y.platform === 'string' ? y.platform : undefined,
       enabled: Array.isArray(y.enabled) ? y.enabled.map(String) : [],
+      verification: Array.isArray(y.verification) ? y.verification.map(String) : undefined,
       source: 'capabilities.yaml',
     };
   } catch {
@@ -48,14 +95,17 @@ export function readCapabilities(cwd: string): CapabilityProfile {
   }
 }
 
-export function writeCapabilities(cwd: string, profile: { platform?: string; enabled: string[] }): string {
+export function writeCapabilities(cwd: string, profile: { platform?: string; enabled: string[]; verification?: string[] }): string {
   const p = capabilitiesPath(cwd);
   fs.mkdirSync(path.dirname(p), { recursive: true });
   const body =
     '# Sungen capability profile — which runtime/drivers this project uses.\n' +
     '# platform: the runtime adapter (web → Playwright, mobile → Appium). No default.\n' +
-    '# enabled: drivers turned on (added via `sungen capability add <driver>`).\n\n' +
-    stringifyYaml({ platform: profile.platform, enabled: profile.enabled });
+    '# enabled: drivers turned on (added via `sungen capability add <driver>`).\n' +
+    '# verification: the TEST TYPE — which layers this project verifies (`ui` = E2E only; add `api`/`db`\n' +
+    '#   only if the project actually verifies via API/Database). Absent → derived from `enabled`.\n' +
+    '#   This keeps an E2E-only project from getting @api/@query verification it never asked for.\n\n' +
+    stringifyYaml({ platform: profile.platform, enabled: profile.enabled, ...(profile.verification ? { verification: profile.verification } : {}) });
   fs.writeFileSync(p, body, 'utf-8');
   return p;
 }

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

package/src/harness/spec-coverage.ts

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

package/src/harness/trace.ts

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

package/src/harness/viewpoint-ledger.ts

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

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

@@ -22,7 +22,7 @@ If `spec_figma.md` exists OR the user provides a Figma URL for the PAT flow:
 
 ## Platform detection (do this FIRST)
 
-Read `qa/capabilities.yaml` and check the `platform` field.
+Read `qa/capabilities.yaml` and check the `platform` field — **and the verification scope** (`verification:` if set, else derived from `enabled`: `ui` always; `api`/`db` only if that driver is on). This is the project's recorded **test type**: an **E2E/UI-only** project (no `api`/`db`) must NOT get `@api`/`@query`/`@requires:api|db` verification unless the test-viewpoint explicitly asks for it — keep oracles UI-observable, and cap any in-scope API/DB-in-E2E verification at the **≤20% band** (see `sungen-tc-generation` → "Respect the project's verification scope"). `sungen audit` flags `VERIFICATION-OUT-OF-SCOPE`.
 
 - If `platform: mobile` → the visual-capture step (Step 3, "Auto-detect visual source") uses the **`sungen-capture-mobile`** skill (Appium MCP live capture) **instead of** the web `sungen-capture` (figma/live). Scenarios use mobile gesture vocabulary from `sungen-mobile-gestures` (tap, swipe, long-press — not click/hover) and `accessibility-id`-first selectors; mobile-specific steps (permission dialogs, clipboard, geolocation) are valid Gherkin, not errors. The `Background:` is a **navigation recipe** (see `add-screen --reach`), not a URL path. Everything else — viewpoints, `sungen-tc-generation`, the harness/audit loop — is platform-agnostic and unchanged.
 - If `platform: web` or field absent → follow the **web path** (all steps below, unchanged) — Figma/live capture via `sungen-capture` as documented in Step 3.
@@ -68,6 +68,15 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the design loop differs — **no visual capture, no selectors**; the contract is the named-endpoint catalog. **Follow the `sungen-api-design` + `sungen-api-coverage-model` skills end-to-end** instead of the screen/flow steps: `sungen context --area <name>` (discover endpoints + `fields:`) → **enumerate the Tier-1 case list per endpoint from the coverage model** (contract + not-found/required-matrix + auth + idempotency, expanded mechanically from `fields:`) → generate `@api`/`@cases`/flow/`@concurrent`/`@query` scenarios with **strict assertions** (prove the effect, never status-only) → **`sungen audit --area <name>` gate + reviewer + repair loop to businessDepth ≥ 0.7** → record + trace. Then recommend `/sungen-run-test <name>`. The capture / viewpoint-group / selector steps do **not** apply.
 {{/cap}}
 
+## Requirement traceability (before you finish)
+
+Cross-check `requirements/spec.md` against the scenarios you wrote: every `FR-`/`TR-`/`NFR-` id
+must either carry a `@spec:<id>` tag on the scenario that proves it, or be a conscious
+out-of-scope decision you state in the summary. `sungen audit` reports `SPEC-TRACE-IMPLICIT` for
+requirements it could only match by keyword — treat that list as a to-do: add the tag to the
+proving scenario, do not leave the link to inference. Delivery's requirement table follows the
+tag only, so an untagged requirement is later reported as an uncovered gap.
+
 ## Steps
 
 {{#cap parallel-subagents}}