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

package/src/exporters/matrix/render-xlsx.ts

@@ -0,0 +1,289 @@
+/**
+ * Render the Test Case & Coverage Matrix workbook.
+ *
+ * Sheets:
+ *   1. Testcases — one parent row per delivery item, variant sub-rows grouped with
+ *      Excel outline (expanded for execution; the level-1 outline button collapses
+ *      to the customer/review view — same sheet, one model, two views).
+ *   2. Coverage — target × category grid (items + variants, `—` marks the gaps),
+ *      dispositions, and the generation manifest.
+ *
+ * Every sheet keeps the company ISO masthead (renderReportHeaderBand). A draft
+ * matrix (unapproved groups / review findings) carries a red DRAFT banner.
+ */
+
+import * as ExcelJS from 'exceljs';
+import {
+  renderReportHeaderBand,
+  allBordersBlack,
+  ARIAL_FONT,
+  BLACK,
+  LAVENDER,
+} from '../xlsx-report-builder';
+import { statusToTestResult, formatExecutedDate } from '../playwright-report-parser';
+import { CoverageVariant, DeliveryItem, ItemResult, MatrixModel, MapCategory } from './types';
+
+const CATEGORY_ORDER: MapCategory[] = ['normal', 'abnormal', 'security', 'nfr'];
+const SOFT_BLUE = { argb: 'FFDCE6F1' };
+const DRAFT_RED = { argb: 'FFC00000' };
+const GAP_FILL = { argb: 'FFFCE4EC' };
+
+function headerCell(c: ExcelJS.Cell, label: string): void {
+  c.value = label;
+  c.font = { bold: true, size: 10, color: BLACK, name: ARIAL_FONT };
+  c.fill = { type: 'pattern', pattern: 'solid', fgColor: LAVENDER };
+  c.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
+  c.border = allBordersBlack;
+}
+
+function dataCell(c: ExcelJS.Cell, value: ExcelJS.CellValue, opts?: { bold?: boolean; fill?: { argb: string }; center?: boolean; color?: { argb: string } }): void {
+  c.value = value;
+  c.font = { bold: opts?.bold ?? false, size: 10, name: ARIAL_FONT, ...(opts?.color ? { color: opts.color } : {}) };
+  c.alignment = { horizontal: opts?.center ? 'center' : 'left', vertical: 'top', wrapText: true };
+  c.border = allBordersBlack;
+  if (opts?.fill) c.fill = { type: 'pattern', pattern: 'solid', fgColor: opts.fill };
+}
+
+function itemResultLabel(item: DeliveryItem): string {
+  const { passed, failed, blocked, notRun } = item.resultCounts;
+  const total = item.variants.length;
+  const map: Record<ItemResult, string> = {
+    passed: `${passed}/${total} Passed`,
+    failed: `${passed}/${total} Passed · ${failed} Failed`,
+    blocked: `${blocked} Blocked`,
+    partial: `${passed}/${total} Passed · ${notRun} not run`,
+    not_run: 'Pending',
+  };
+  return map[item.result];
+}
+
+function variantResultLabel(v: CoverageVariant): string {
+  if (!v.result) return 'Pending';
+  return statusToTestResult(v.result.status);
+}
+
+function numbered(lines: string[]): string {
+  if (lines.length === 0) return '';
+  if (lines.length === 1) return lines[0];
+  return lines.map((l, i) => `${i + 1}. ${l}`).join('\n');
+}
+
+/** Red DRAFT banner on row 5 when the matrix is not approved for official delivery. */
+function draftBanner(ws: ExcelJS.Worksheet, model: MatrixModel): void {
+  if (model.manifest.approvalState !== 'draft') return;
+  ws.mergeCells('B5:H5');
+  const c = ws.getCell('B5');
+  c.value = 'DRAFT — NOT APPROVED FOR OFFICIAL DELIVERY (review-required findings or proposed groups remain)';
+  c.font = { bold: true, size: 11, name: ARIAL_FONT, color: { argb: 'FFFFFFFF' } };
+  c.fill = { type: 'pattern', pattern: 'solid', fgColor: DRAFT_RED };
+  c.alignment = { horizontal: 'center', vertical: 'middle' };
+}
+
+// ---------------------------------------------------------------------------
+// Sheet 1 — Testcases (the matrix)
+// ---------------------------------------------------------------------------
+
+const MATRIX_HEADERS = [
+  'ID', 'Target', 'Test Intent / Condition', 'Category', 'Priority', 'Precondition',
+  'Coverage / Test Data', 'Action / Trigger', 'Expected (Oracle)', 'Mode', 'Trace',
+  'Result', 'Executed Date', 'Executor', 'Note\n(Evidence, DefectID)',
+];
+
+function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?: string): void {
+  const ws = wb.addWorksheet('Testcases');
+  ws.properties.outlineLevelRow = 1;
+
+  ws.columns = [
+    { width: 3 },  // A margin
+    { width: 20 }, // B ID
+    { width: 18 }, // C Target
+    { width: 42 }, // D Intent / Condition
+    { width: 11 }, // E Category
+    { width: 9 },  // F Priority
+    { width: 26 }, // G Precondition
+    { width: 34 }, // H Coverage / Data
+    { width: 34 }, // I Trigger
+    { width: 42 }, // J Expected
+    { width: 11 }, // K Mode
+    { width: 13 }, // L Trace
+    { width: 17 }, // M Result
+    { width: 13 }, // N Executed
+    { width: 13 }, // O Executor
+    { width: 24 }, // P Note
+  ];
+
+  renderReportHeaderBand(wb, ws, `${model.unit.toUpperCase()} TEST CASE & COVERAGE MATRIX`, sungenVersion, model.formNo);
+  draftBanner(ws, model);
+
+  // Summary band (row 6) — items vs variants stay separate metrics by design (I8):
+  // the ITEM count is reviewer workload, the VARIANT count is execution workload.
+  const passed = model.items.reduce((a, i) => a + i.resultCounts.passed, 0);
+  const failed = model.items.reduce((a, i) => a + i.resultCounts.failed, 0);
+  const notRun = model.items.reduce((a, i) => a + i.resultCounts.notRun + i.resultCounts.blocked, 0);
+  const band = ws.getRow(6);
+  [
+    `Delivery items: ${model.manifest.itemCount}`,
+    `Coverage variants: ${model.manifest.variantCount}`,
+    `Passed: ${passed}`, `Failed: ${failed}`, `Pending: ${notRun}`,
+  ].forEach((label, i) => {
+    const c = band.getCell(2 + i);
+    dataCell(c, label, { bold: true, fill: SOFT_BLUE, center: true });
+  });
+
+  const HEADER_ROW = 8;
+  const hr = ws.getRow(HEADER_ROW);
+  hr.height = 28;
+  MATRIX_HEADERS.forEach((label, i) => headerCell(hr.getCell(2 + i), label));
+
+  let rowIdx = HEADER_ROW + 1;
+  for (const item of model.items) {
+    // Parent row — the delivery item (the review unit).
+    const pr = ws.getRow(rowIdx++);
+    const single = item.variants.length === 1;
+    const only = single ? item.variants[0] : undefined;
+    const coverage = single
+      ? numbered(only!.data)
+      : `${item.variants.length} variants: ${item.variants.map((v) => v.condition).join(' · ')}`;
+    const values: ExcelJS.CellValue[] = [
+      item.id,
+      item.target,
+      item.intent,
+      item.category,
+      item.priority,
+      numbered(item.precondition),
+      coverage,
+      numbered(item.trigger),
+      item.oracle,
+      item.mode === 'manual' ? `Manual${only?.manualReason ? ` (${only.manualReason})` : ''}` : 'Auto',
+      item.traces.join(', '),
+      itemResultLabel(item),
+      single ? formatExecutedDate(only!.result?.startTime) : '',
+      '',
+      item.review === 'proposed' ? 'REVIEW REQUIRED' : '',
+    ];
+    values.forEach((v, i) => dataCell(pr.getCell(2 + i), v, {
+      bold: true,
+      fill: SOFT_BLUE,
+      center: i === 3 || i === 4 || i === 9,
+      ...(String(values[14]).startsWith('REVIEW') && i === 14 ? { color: DRAFT_RED } : {}),
+    }));
+
+    // Variant sub-rows — the execution units (outline level 1; collapse for review).
+    if (!single) {
+      for (const v of item.variants) {
+        const vr = ws.getRow(rowIdx++);
+        vr.outlineLevel = 1;
+        const vValues: ExcelJS.CellValue[] = [
+          v.ref,
+          '',
+          v.condition,
+          '', '', '',
+          numbered(v.data),
+          numbered(v.trigger),
+          numbered(v.oracle),
+          v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : 'Auto',
+          v.traces.join(', '),
+          variantResultLabel(v),
+          formatExecutedDate(v.result?.startTime),
+          '',
+          v.result?.error ? String(v.result.error).slice(0, 200) : '',
+        ];
+        vValues.forEach((val, i) => dataCell(vr.getCell(2 + i), val, { center: i === 9 }));
+      }
+    }
+  }
+
+  ws.autoFilter = { from: { row: HEADER_ROW, column: 2 }, to: { row: rowIdx - 1, column: 16 } };
+  ws.views = [{ state: 'frozen', ySplit: HEADER_ROW }];
+}
+
+// ---------------------------------------------------------------------------
+// Sheet 2 — Coverage (overview grid + dispositions + manifest)
+// ---------------------------------------------------------------------------
+
+function addCoverageSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?: string): void {
+  const ws = wb.addWorksheet('Coverage');
+  ws.columns = [
+    { width: 3 }, { width: 30 }, { width: 16 }, { width: 16 }, { width: 16 }, { width: 16 },
+    { width: 16 }, { width: 40 },
+  ];
+  renderReportHeaderBand(wb, ws, `${model.unit.toUpperCase()} COVERAGE OVERVIEW`, sungenVersion, model.formNo);
+  draftBanner(ws, model);
+
+  // --- Target × category grid ---
+  let rowIdx = 7;
+  dataCell(ws.getRow(rowIdx).getCell(2), 'Coverage matrix — delivery items (coverage variants) per target × category', { bold: true });
+  rowIdx += 1;
+  const gridHeader = ws.getRow(rowIdx++);
+  headerCell(gridHeader.getCell(2), 'Target');
+  CATEGORY_ORDER.forEach((cat, i) => headerCell(gridHeader.getCell(3 + i), cat));
+  headerCell(gridHeader.getCell(3 + CATEGORY_ORDER.length), 'Total');
+
+  const targets = Array.from(new Set(model.items.map((i) => i.target)));
+  for (const target of targets) {
+    const row = ws.getRow(rowIdx++);
+    dataCell(row.getCell(2), target, { bold: true });
+    let totalItems = 0;
+    let totalVariants = 0;
+    CATEGORY_ORDER.forEach((cat, i) => {
+      const cell = row.getCell(3 + i);
+      const items = model.items.filter((it) => it.target === target && it.category === cat);
+      const variants = items.reduce((a, it) => a + it.variants.length, 0);
+      totalItems += items.length;
+      totalVariants += variants;
+      // `—` is an explicit statement: this target × category cell has NO coverage.
+      dataCell(cell, items.length === 0 ? '—' : `${items.length} (${variants})`, {
+        center: true,
+        ...(items.length === 0 ? { fill: GAP_FILL } : {}),
+      });
+    });
+    dataCell(row.getCell(3 + CATEGORY_ORDER.length), `${totalItems} (${totalVariants})`, { center: true, bold: true });
+  }
+
+  // --- Dispositions ---
+  if (model.dispositions.length > 0) {
+    rowIdx += 1;
+    dataCell(ws.getRow(rowIdx).getCell(2), 'Not in the matrix (explicit dispositions)', { bold: true });
+    rowIdx += 1;
+    const dh = ws.getRow(rowIdx++);
+    ['Source', 'Disposition', 'Reason', 'Title'].forEach((l, i) => headerCell(dh.getCell(2 + i), l));
+    for (const d of model.dispositions) {
+      const row = ws.getRow(rowIdx++);
+      dataCell(row.getCell(2), d.vpId);
+      dataCell(row.getCell(3), d.as, { center: true });
+      dataCell(row.getCell(4), d.reason);
+      dataCell(row.getCell(5), d.title);
+    }
+  }
+
+  // --- Manifest ---
+  rowIdx += 1;
+  dataCell(ws.getRow(rowIdx).getCell(2), 'Generation manifest', { bold: true });
+  rowIdx += 1;
+  const m = model.manifest;
+  const manifestRows: Array<[string, string]> = [
+    ['Unit', m.unit],
+    ['Approval state', m.approvalState],
+    ['Delivery items', String(m.itemCount)],
+    ['Coverage variants', String(m.variantCount)],
+    ['Source fingerprint', m.sourceFingerprint],
+    ['Map fingerprint', m.mapFingerprint],
+    ['Transformer version', m.transformerVersion],
+    ['Max variants / item (warn)', String(m.thresholds.maxVariantsPerItem)],
+  ];
+  for (const [k, v] of manifestRows) {
+    const row = ws.getRow(rowIdx++);
+    dataCell(row.getCell(2), k, { bold: true, fill: SOFT_BLUE });
+    ws.mergeCells(rowIdx - 1, 3, rowIdx - 1, 7);
+    dataCell(row.getCell(3), v);
+  }
+}
+
+// ---------------------------------------------------------------------------
+
+export function renderMatrixXlsx(model: MatrixModel, sungenVersion?: string): ExcelJS.Workbook {
+  const wb = new ExcelJS.Workbook();
+  addMatrixSheet(wb, model, sungenVersion);
+  addCoverageSheet(wb, model, sungenVersion);
+  return wb;
+}

package/src/exporters/matrix/types.ts

@@ -0,0 +1,176 @@
+/**
+ * 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;
+  /** 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 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>;
+  /** VP-id → scenario fingerprint stamped at approval time (drift detector input). */
+  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[];
+  /** 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[];
+  /** 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';
+
+/** One summarized row in the matrix — a group of variants sharing the signature. */
+export interface DeliveryItem {
+  id: string;
+  target: string;
+  intent: string;
+  oracle: string;
+  category: MapCategory;
+  review: ReviewState;
+  priority: string;
+  mode: 'auto' | 'manual';
+  layers: MatrixLayer[];
+  /** Union of variant traces (exact per-variant traces stay on the variants). */
+  traces: string[];
+  precondition: string[];
+  /** Common trigger when all variants share one shape, else '(per variant)'. */
+  trigger: string[];
+  variants: CoverageVariant[];
+  /** Derived roll-up — never entered independently (Gate F). */
+  result: ItemResult;
+  resultCounts: { passed: number; failed: number; blocked: number; notRun: number };
+}
+
+export interface MatrixDisposition {
+  vpId: string;
+  title: string;
+  as: DispositionKind;
+  reason: string;
+}
+
+// ---------------------------------------------------------------------------
+// Gate findings
+// ---------------------------------------------------------------------------
+
+export type GateId = 'A' | 'B' | 'C' | 'D' | 'E' | 'G';
+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[];
+  findings: MatrixFinding[];
+  manifest: MatrixManifest;
+}
+
+/** Complexity warning threshold (rules draft Gate I) — echoed in the manifest. */
+export const MAX_VARIANTS_PER_ITEM = 12;

package/src/exporters/scenario-merger.ts

@@ -162,7 +162,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(/^(VP-[A-Z][A-Z0-9]*-\d+(?:[a-zA-Z]|-[A-Z0-9]+)?)/);
   if (vpMatch) {
     const vpId = vpMatch[1];
     const byVp = tests.find((t) => t.vpId === vpId);

package/src/exporters/spec-parser.ts

@@ -165,7 +165,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(/^(VP-[A-Z][A-Z0-9]*-\d+(?:[a-zA-Z]|-[A-Z0-9]+)?)\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';
@@ -129,7 +129,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 +224,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) ? fs.readFileSync(viewpointPath, 'utf-8') : '', 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).`);

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/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.