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

package/src/exporters/matrix/types.ts

@@ -0,0 +1,226 @@
+/**
+ * Delivery v2 — Test Case & Coverage Matrix model (docs/spec/delivery-coverage-matrix-spec.md).
+ *
+ * Gherkin stays the source of test meaning; the matrix is a derived presentation:
+ * one delivery item = one target + one intent + one oracle family, containing one or
+ * more atomic coverage variants (scenario / @cases row). Grouping semantics live in the
+ * committed Delivery Map (`qa/<kind>/<unit>/delivery/<unit>.map.yaml`) — AI-proposed,
+ * gate-validated, QA-approved.
+ */
+
+import { PlaywrightResult } from '../types';
+
+// ---------------------------------------------------------------------------
+// Delivery Map (the committed grouping artifact)
+// ---------------------------------------------------------------------------
+
+export type MapCategory = 'normal' | 'abnormal' | 'security' | 'nfr';
+export type ReviewState = 'proposed' | 'approved';
+export type DispositionKind = 'excluded' | 'blocked' | 'covered_elsewhere' | 'accepted_risk';
+
+export interface MapGroup {
+  /** Stable delivery id, unique per unit, order-independent (e.g. DI-EMAIL-FORMAT). */
+  id: string;
+  /** ONE primary target: field/component dot-path, function/flow phrase, or `METHOD /path`. */
+  target: string;
+  /** One coherent test intent (the primary behavior/rule verified). */
+  intent: string;
+  /** Oracle family in words — the shared Pass/Fail observation. */
+  oracle: string;
+  category: MapCategory;
+  review: ReviewState;
+  /** Optional short digest of the coverage dimensions this item varies over
+   *  (e.g. "required ×3 · format ×9 · full-width ×2"). Rendered on the parent row
+   *  instead of concatenating every variant's title — the compact review view. */
+  dimensions?: string;
+  /** Variant refs: `VP-ID` (all @cases rows when the scenario has a dataset) or `VP-ID#label`. */
+  variants: string[];
+}
+
+export interface MapDisposition {
+  as: DispositionKind;
+  reason?: string;
+}
+
+export type RequirementStatus =
+  | 'covered' | 'partially_covered' | 'covered_elsewhere' | 'planned' | 'gap' | 'not_applicable';
+
+export interface RequirementOverride {
+  status: RequirementStatus;
+  note?: string;
+}
+
+export interface DeliveryMap {
+  version: number;
+  unit: string;
+  /** ISO form number rendered in the workbook masthead (default BM-2-901-13). */
+  formNo?: string;
+  groups: MapGroup[];
+  /** VP-id → intentionally-not-grouped disposition. */
+  dispositions: Record<string, MapDisposition>;
+  /** Requirement-id → reviewed status override (partially_covered / not_applicable / …).
+   *  Without an override a requirement is `covered` when a variant traces to it, else `gap`. */
+  requirements: Record<string, RequirementOverride>;
+  /** VP-id → scenario fingerprint stamped at approval time (drift detector input).
+   *  The reserved key `__map__` holds the fingerprint of the map's own semantic
+   *  content (groups + dispositions) so edited wording re-opens review (GAP-09). */
+  fingerprints: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Derived model (deterministic, computed from the .feature at build time)
+// ---------------------------------------------------------------------------
+
+/** Execution layers a variant verifies on — cross-checked with the verification scope. */
+export type MatrixLayer = 'ui' | 'api' | 'db';
+
+/**
+ * One atomic coverage variant — the unit of execution, result, and traceability.
+ * Backed by one scenario, or one `@cases` dataset row of a scenario.
+ */
+export interface CoverageVariant {
+  /** `VP-ID` or `VP-ID#label` for a dataset row. */
+  ref: string;
+  vpId: string;
+  /** Dataset-row label when this variant is one `@cases` row. */
+  caseLabel?: string;
+  /** Human title (scenario name without the VP prefix; row label appended for @cases). */
+  title: string;
+  /** Viewpoint category from the VP prefix (LOGIC/VAL/UI/SEC/…). */
+  vpCategory: string;
+  priority: string;                        // High | Normal | Low
+  /** 'auto' | 'manual'; manual keeps its @manual:Mx reason. */
+  mode: 'auto' | 'manual';
+  manualReason?: string;
+  layers: MatrixLayer[];
+  /** @spec:* requirement traces. */
+  traces: string[];
+  /** Variables this scenario produces at RUN TIME (`remember … as {{v}}`, capability
+   *  bindings) — they never exist in test-data, so Gate D must not demand them. */
+  runtimeVars: string[];
+  /** Condition summary: differentiating dimension shown on the sub-row. */
+  condition: string;
+  /** Resolved data pairs (test-data values / dataset-row columns), `key: value` lines. */
+  data: string[];
+  /** Normalized trigger shape (When steps, `{{var}}` collapsed) — signature input. */
+  triggerShape: string[];
+  /** Trigger for display (When steps, vars resolved). */
+  trigger: string[];
+  /** Normalized oracle shape (Then steps / manual Observable+Oracle) — signature input. */
+  oracleShape: string[];
+  /** Oracle for display. */
+  oracle: string[];
+  /** HOW to check (manual `Oracle:` lines — tools, panes, queries). Rendered as
+   *  "Verification method" under the expected result, never inside it. */
+  verification: string[];
+  /** Precondition profile: auth role + scenario-level Given shapes — signature input. */
+  preconditionProfile: string;
+  /** Human preconditions (auth + own Given steps). */
+  precondition: string[];
+  /** 'simple' (G*W*T*) | 'sequence' (mid-flow Given / multi round-trip) | 'manual'. */
+  procedureProfile: 'simple' | 'sequence' | 'manual';
+  /** Canonical scenario fingerprint (drift detection). */
+  fingerprint: string;
+  /** Execution result, when the run report has one for this variant. */
+  result?: PlaywrightResult;
+}
+
+export type ItemResult = 'passed' | 'failed' | 'blocked' | 'partial' | 'not_run' | 'na';
+
+/** The exact word rendered in a variant's Result cell — the single vocabulary the
+ *  parent's roll-up formula counts (COUNTIF is exact-match). */
+export type VariantState = 'Passed' | 'Failed' | 'Blocked' | 'Pending' | 'N/A';
+
+/** One summarized row in the matrix — a group of variants sharing the signature. */
+export interface DeliveryItem {
+  id: string;
+  target: string;
+  intent: string;
+  oracle: string;
+  /** Short coverage-dimension digest from the map (compact parent view). */
+  dimensions?: string;
+  category: MapCategory;
+  review: ReviewState;
+  /** Highest priority among the variants (per-variant priorities stay on the sub-rows). */
+  priority: string;
+  /** Execution mode is a coverage dimension, not a split — 'mixed' when auto and
+   *  manual variants share one intent (e.g. account states needing seeded data). */
+  mode: 'auto' | 'manual' | 'mixed';
+  layers: MatrixLayer[];
+  /** Union of variant traces (exact per-variant traces stay on the variants). */
+  traces: string[];
+  /** Preconditions shared by EVERY variant (the intersection) — written once here. */
+  precondition: string[];
+  /** Leading trigger steps shared by every variant — written once here; each
+   *  variant renders only its remaining steps (`triggerDeltas`). */
+  trigger: string[];
+  variants: CoverageVariant[];
+  /** variant ref → its precondition lines that are not on the parent. */
+  preconditionDeltas: Record<string, string[]>;
+  /** variant ref → its trigger steps after the shared prefix. */
+  triggerDeltas: Record<string, string[]>;
+  /** Derived roll-up — never entered independently (Gate F). */
+  result: ItemResult;
+  resultCounts: { passed: number; failed: number; blocked: number; notRun: number; na: number };
+}
+
+export interface MatrixDisposition {
+  vpId: string;
+  title: string;
+  as: DispositionKind;
+  reason: string;
+}
+
+/** One row of the requirement-coverage table (Coverage sheet). */
+export interface RequirementCoverage {
+  id: string;                    // FR-003 / TR-001 / NFR-…
+  status: RequirementStatus;
+  /** Delivery items whose variants trace to this requirement. */
+  items: string[];
+  variantCount: number;
+  note: string;
+}
+
+// ---------------------------------------------------------------------------
+// Gate findings
+// ---------------------------------------------------------------------------
+
+export type GateId = 'A' | 'B' | 'C' | 'D' | 'E' | 'G' | 'K' | 'R' | 'W';
+export type FindingSeverity = 'error' | 'review' | 'warning';
+
+export interface MatrixFinding {
+  gate: GateId;
+  severity: FindingSeverity;
+  /** Delivery item / VP-id the finding anchors to, when applicable. */
+  ref?: string;
+  message: string;
+}
+
+// ---------------------------------------------------------------------------
+// The assembled matrix
+// ---------------------------------------------------------------------------
+
+export interface MatrixManifest {
+  unit: string;
+  transformerVersion: string;
+  sourceFingerprint: string;     // canonical hash over all scenario fingerprints
+  mapFingerprint: string;        // canonical hash of the map content
+  approvalState: 'approved' | 'draft';
+  itemCount: number;
+  variantCount: number;
+  thresholds: { maxVariantsPerItem: number };
+}
+
+export interface MatrixModel {
+  unit: string;
+  formNo: string;
+  items: DeliveryItem[];
+  dispositions: MatrixDisposition[];
+  /** Requirement coverage — empty when the unit has no requirements/spec.md ids. */
+  requirements: RequirementCoverage[];
+  findings: MatrixFinding[];
+  manifest: MatrixManifest;
+}
+
+/** Complexity warning threshold (rules draft Gate I; raised for compact grouping) — echoed in the manifest. */
+export const MAX_VARIANTS_PER_ITEM = 20;

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]?)/);
+  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]?)\b/);
+  const match = title.match(new RegExp(SCENARIO_ID.source + '\\b'));
   return match ? match[1] : undefined;
 }
 

package/src/exporters/xlsx-report-builder.ts

@@ -143,6 +143,7 @@ export function renderReportHeaderBand(
   ws: ExcelJS.Worksheet,
   titleLabel: string,
   sungenVersion?: string,
+  formNo: string = 'BM-2-901-13',
 ): void {
   const issueDate = (() => {
     const d = new Date();
@@ -187,9 +188,9 @@ export function renderReportHeaderBand(
   d1.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
   d1.border = allBordersBlack;
 
-  // G1 — No: BM-2-901-13
+  // G1 — No: <form number> (the company ISO form id; configurable via the delivery map)
   const g1 = ws.getCell('G1');
-  g1.value = 'No: BM-2-901-13';
+  g1.value = `No: ${formNo}`;
   g1.font = { size: 12, name: TIMES };
   g1.alignment = { vertical: 'middle' };
   g1.border = { top: thinBlack, left: thinBlack, right: thinBlack };

package/src/harness/audit.ts

@@ -17,7 +17,7 @@ import {
 } from './sensors';
 import { loadFlowScenarios } from './flow-check';
 import { manualReasonMismatches, MANUAL_REASONS, buildPlan } from './capability-plan';
-import { readCapabilities } from './capability';
+import { readCapabilities, verificationScopeFindings } from './capability';
 import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
 import { getProvenance, Provenance } from './provenance';
 import { specCoverage, SpecCoverageResult, parseSpecClauses } from './spec-coverage';
@@ -27,6 +27,7 @@ import { viewpointLedger, parseViewpointItems, LedgerResult } from './viewpoint-
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { contextRouter } from '../capabilities/context-router';
+import { readTextFile } from './read-text';
 
 export interface AuditReport {
   screen: string;
@@ -118,7 +119,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const catalogScreenName = catalogIdFromScreenDir(screenDir);
 
   const specPath = path.join(screenDir, 'requirements', 'spec.md');
-  const featureText = fs.existsSync(featurePath) ? fs.readFileSync(featurePath, 'utf-8') : '';
+  const featureText = fs.existsSync(featurePath) ? readTextFile(featurePath) : '';
 
   const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
   const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
@@ -129,7 +130,8 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   discoverAndRegisterCapabilities();
   // The active platform (web | mobile | …) activates its own capability for scoring + sensor routing.
   // `web` has no capability of its own → scoringCap stays the default `ui` (byte-identical).
-  const platform = readCapabilities(projectRootFromScreenDir(screenDir)).platform;
+  const capProfile = readCapabilities(projectRootFromScreenDir(screenDir));
+  const platform = capProfile.platform;
   const defaultCap = capabilityRegistry.defaultCapabilityId();
   const scoringCapId = scoringCapabilityFor(catalogScreenName, defaultCap, platform);
   const scoringCap = scoringCapId ? capabilityRegistry.get(scoringCapId) : undefined;
@@ -223,6 +225,10 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   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) ? readTextFile(viewpointPath) : '', capProfile)) {
+    findings.push(`VERIFICATION-OUT-OF-SCOPE (${v.layer}): this unit ${v.message}`);
+  }
   for (const g of gate.gaps) {
     if (g.status === 'shallow') {
       findings.push(`GATE: critical theme "${g.theme}" is covered only by SHALLOW scenarios (no data assertion) → deepen with \`... with {{value}}\` / \`table ... with {{value}}\` (count @manual cross-screen too).`);
@@ -284,6 +290,14 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   for (const u of spec.uncoveredMust) {
     findings.push(`SPEC-UNCOVERED: ${u.id} (MUST) has no covering scenario — "${u.text}" → add a scenario or tag one @spec:${u.id}.`);
   }
+  if (spec.inferredOnly.length > 0) {
+    // Covered, but only by keyword inference — no scenario cites the id. Delivery's
+    // requirement table (and any later refactor) cannot follow an inferred link, so
+    // the trace has to be written down while the author still knows which scenario
+    // proves what.
+    const shown = spec.inferredOnly.slice(0, 8).join(', ');
+    findings.push(`SPEC-TRACE-IMPLICIT: ${spec.inferredOnly.length} requirement(s) are covered by keyword inference only (${shown}${spec.inferredOnly.length > 8 ? ', …' : ''}) — add \`@spec:<id>\` to the scenario that proves each so the trace survives edits and delivery can report it.`);
+  }
   if (taxonomyMismatch) {
     findings.push(`VP-TAXONOMY-MISMATCH: only ${(trace.mappedRatio * 100).toFixed(0)}% of scenarios use the viewpoint IDs declared in test-viewpoint.md — scenarios invented a generic VP-<CAT> scheme. Re-tag to the project's viewpoint IDs so the coverage matrix is accurate.`);
   }

package/src/harness/blindspot.ts

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

package/src/harness/capability-plan.ts

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