@sun-asterisk/sungen 3.0.0 → 3.1.0

package/src/harness/quality-gates.ts

@@ -0,0 +1,152 @@
+/**
+ * Quality gates (batch): downstream-scope + manual-oracle + negative-side-effect +
+ * cross-artifact ownership + source-backed strictness.
+ * Generic — read the project's own spec.md / feature text / sibling flows; no project data.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { ScenarioInfo, loadScenarios, idPrefix } from './parse';
+
+// ---------- #2 Downstream-scope ----------
+
+export interface DownstreamResult {
+  downstreamRoutes: string[];                 // success/navigation targets ≠ own route
+  underCovered: { route: string; slug: string }[]; // referenced only by a bare page-nav
+}
+
+/** Routes the spec hands off to (Navigation Flow / success), other than the screen's own route. */
+function downstreamRoutes(specText: string): string[] {
+  const ownRoute = (specText.match(/\*\*Route\*\*\s*:\s*`?(\/[^\s`]+)/) || [])[1] || '';
+  const routes = new Set<string>();
+  for (const line of specText.split('\n')) {
+    if (!/success|navigat|to \(|→/i.test(line)) continue;
+    for (const m of line.matchAll(/`?(\/[a-z][a-z0-9/_-]+)`?/gi)) {
+      const r = m[1];
+      if (r !== ownRoute && r.split('/').length > ownRoute.split('/').length - 0) routes.add(r);
+    }
+  }
+  // keep only routes that extend beyond the own route (a distinct downstream surface)
+  return [...routes].filter((r) => r !== ownRoute && (!ownRoute || r.startsWith(ownRoute + '/') || r.split('/').length >= 3));
+}
+
+export function downstreamScope(specText: string, scenarios: ScenarioInfo[]): DownstreamResult {
+  const routes = downstreamRoutes(specText);
+  const underCovered: { route: string; slug: string }[] = [];
+  for (const route of routes) {
+    const slug = (route.split('/').filter(Boolean).pop() || route).toLowerCase();
+    const refs = scenarios.filter((s) => s.haystack.includes(slug) || s.haystack.includes(route.toLowerCase()));
+    if (!refs.length) continue; // not referenced at all — out of this screen's scope entirely
+    // Substantively covered only if some scenario OPERATES on the downstream — i.e. it
+    // starts there (`is on [<downstream>]`) — not merely navigates to it as a terminal
+    // `see [<downstream>] page` assertion. The latter just proves the transition.
+    const opensOn = new RegExp(`\\bis on \\[[^\\]]*${slug}`, 'i');
+    const contentCovered = refs.some((s) => opensOn.test(s.haystack));
+    if (!contentCovered) underCovered.push({ route, slug });
+  }
+  return { downstreamRoutes: routes, underCovered };
+}
+
+// ---------- #4 Manual-oracle ----------
+
+export interface ManualOracleResult {
+  manualTotal: number;
+  insufficient: string[];   // @manual scenarios lacking setup/action/oracle
+}
+
+function blocks(featureText: string): string[] {
+  return featureText.split(/\n\s*\n/).filter((b) => /\bScenario:/.test(b));
+}
+
+export function manualOracle(featureText: string): ManualOracleResult {
+  const insufficient: string[] = [];
+  let manualTotal = 0;
+  for (const b of blocks(featureText)) {
+    if (!/@manual\b/.test(b)) continue;
+    manualTotal++;
+    const commentLines = b.split('\n').filter((l) => /^\s*#/.test(l));
+    const hasOracle = /tester verifies|oracle\s*:|requires|verify that|expected\s*:|steps?\s*:/i.test(b);
+    const hasNumberedSteps = /^\s*#?\s*\d+\.\s/m.test(b);
+    // sufficient = an oracle/steps marker, OR a substantive comment block (≥3 comment lines)
+    if (!(hasOracle || hasNumberedSteps || commentLines.length >= 3)) {
+      const name = (b.match(/Scenario:\s*(.+)/) || [])[1] || '(unnamed)';
+      insufficient.push(name.trim().slice(0, 80));
+    }
+  }
+  return { manualTotal, insufficient };
+}
+
+// ---------- #4 Negative side-effect ----------
+
+const NEG_TITLE = /\b(does not|doesn't|no second|not dispatch|not sent|without submitting|no leak|single request|exactly one|count is 1|only one request|no duplicate|not create)\b/i;
+
+/** Titles asserting an ABSENCE must prove it (count / negative / @manual+oracle), not just a happy outcome. */
+export function negativeSideEffect(scenarios: ScenarioInfo[]): string[] {
+  const flagged: string[] = [];
+  for (const s of scenarios) {
+    if (s.manual) continue;                 // @manual is a legitimate deferral (oracle checked by #4 manual-oracle)
+    if (!NEG_TITLE.test(s.name)) continue;
+    const proven = /\bcount\b|tohavecount|table with|is hidden|are hidden|not complete|message is hidden/.test(s.stepsText);
+    if (!proven) flagged.push(s.name.slice(0, 80));
+  }
+  return flagged;
+}
+
+// ---------- #7 Source-backed strictness ----------
+
+/** A scenario should trace to a source: a viewpoint ID (its own scheme), an FR id, or a
+ * viewpoint item (keyword overlap). ID match is language-agnostic and primary. */
+export function sourceBacked(scenarios: ScenarioInfo[], frIds: string[], viewpointItems: string[], viewpointIds: string[], featureText: string): string[] {
+  if (!frIds.length && !viewpointItems.length && !viewpointIds.length) return []; // no contract
+  const vpIds = viewpointIds.map((s) => s.toUpperCase());
+  const itemWords = viewpointItems.map((t) => new Set((t.toLowerCase().match(/[a-z][a-z-]{4,}/g) || [])));
+  // per-scenario blocks (INCLUDING comments) so an FR cited in a comment counts as a source
+  const blockOf = new Map<string, string>();
+  for (const b of featureText.split(/\n\s*\n/)) {
+    const m = b.match(/Scenario:\s*(.+)/);
+    if (m) blockOf.set(m[1].trim().toLowerCase(), b.toLowerCase());
+  }
+  const unsourced: string[] = [];
+  for (const s of scenarios) {
+    const id = (s.vpId || s.vpCode || '').toUpperCase();
+    const mapsId = !!id && vpIds.some((v) => id === v || id.startsWith(v) || v.startsWith(idPrefix(id)));
+    const block = blockOf.get(s.name.trim().toLowerCase()) || s.haystack;
+    const citesFr = frIds.some((fid) => block.includes(fid.toLowerCase()));
+    const sWords = new Set((s.haystack.match(/[a-z][a-z-]{4,}/g) || []));
+    const mapsItem = itemWords.some((iw) => { let hits = 0; for (const w of iw) if (sWords.has(w)) hits++; return hits >= 2; });
+    if (!mapsId && !citesFr && !mapsItem) unsourced.push(s.name.slice(0, 80));
+  }
+  return unsourced;
+}
+
+// ---------- #6 Cross-artifact ownership ----------
+
+export interface OwnershipResult { duplicates: { scenario: string; flow: string }[] }
+
+/** Scenarios whose step-skeleton also appears in a sibling flow feature → duplicate ownership. */
+export function crossArtifactOwnership(screenDir: string, scenarios: ScenarioInfo[]): OwnershipResult {
+  const duplicates: { scenario: string; flow: string }[] = [];
+  // screenDir = <root>/qa/screens/<name>; flows live at <root>/qa/flows/*/features/*.feature
+  const flowsRoot = path.resolve(screenDir, '..', '..', 'flows');
+  if (!fs.existsSync(flowsRoot)) return { duplicates };
+  const bySkeleton = new Map<string, string>();
+  for (const flow of fs.readdirSync(flowsRoot)) {
+    const fdir = path.join(flowsRoot, flow, 'features');
+    if (!fs.existsSync(fdir)) continue;
+    for (const f of fs.readdirSync(fdir).filter((x) => x.endsWith('.feature'))) {
+      for (const fs2 of loadScenarios(path.join(fdir, f))) {
+        if (fs2.stepSkeleton && fs2.stepSkeleton.length > 20) bySkeleton.set(fs2.stepSkeleton, flow);
+      }
+    }
+  }
+  if (!bySkeleton.size) return { duplicates };
+  for (const s of scenarios) {
+    const flow = s.stepSkeleton && s.stepSkeleton.length > 20 ? bySkeleton.get(s.stepSkeleton) : undefined;
+    if (flow) duplicates.push({ scenario: s.name.slice(0, 70), flow });
+  }
+  return { duplicates };
+}
+
+// convenience reader
+export function readText(p: string): string {
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf-8') : '';
+}

package/src/harness/script-check.ts

@@ -68,7 +68,10 @@ export function analyzeFaithfulness(specSrc: string, automatedTitles: Set<string
   for (const blk of extractTestBlocks(specSrc)) {
     if (!automatedTitles.has(blk.title)) continue; // only non-@manual scenarios
     const body = blk.body;
-    if (!body.some((l) => /expect\(/.test(l))) assertionlessTests.push(blk.title);
+    // An assertion is a Playwright `expect(...)` OR a Data Driver DB assertion
+    // (`db.assertRow/assertNoRow/assertCount/...`) — a DB check is a real oracle, so a
+    // DB-only scenario (no UI expect) is NOT a bypass.
+    if (!body.some((l) => /expect\(|\bdb\.assert\w*\s*\(/.test(l))) assertionlessTests.push(blk.title);
     // hollow step: a `// step` whose region (until the NEXT step-comment / block end)
     // contains no executable code. The region — not just the next line — is checked,
     // so block-style steps (`// Assert all … { … expect … }`) are correctly counted.

package/src/harness/sensors.ts

@@ -9,7 +9,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { parse as parseYaml } from 'yaml';
-import { ScenarioInfo, ViewpointEntry } from './parse';
+import { ScenarioInfo, ViewpointEntry, idPrefix } from './parse';
 
 // Business-critical category codes (project VP-<CAT> prefixes). Configurable later.
 const BUSINESS_CRITICAL_CATS = ['LIST', 'CART', 'PRODUCT', 'FILTER', 'CHECKOUT', 'ORDER'];
@@ -263,17 +263,23 @@ export interface TraceResult {
 
 export function traceability(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[]): TraceResult {
   const overviewIds = new Set(viewpoints.map((v) => v.id.toUpperCase()));
-  const withCode = scenarios.filter((s) => s.vpCode);
-  // A scenario maps to overview if its full VP code OR its category-derived id exists in overview.
-  const mapped = withCode.filter((s) => overviewIds.has(s.vpCode!) || [...overviewIds].some((id) => id.includes(s.category || '###')));
+  // A scenario carries an ID if it has a project-scheme leading ID (vpId) or a VP-CAT code.
+  const withCode = scenarios.filter((s) => s.vpId || s.vpCode);
+  // Maps to overview if the scenario's ID, its sequence-stripped prefix, or its VP-CAT code
+  // matches a declared viewpoint ID (format-tolerant: VP0-001↔VP0, MS-HP-001↔MS-HP-001).
+  const mapped = withCode.filter((s) => {
+    const id = (s.vpId || s.vpCode || '').toUpperCase();
+    if (overviewIds.has(id) || overviewIds.has(idPrefix(id))) return true;
+    return [...overviewIds].some((oid) => id.startsWith(oid) || oid.startsWith(idPrefix(id)) || (!!s.category && oid.includes(s.category)));
+  });
   return {
     total: scenarios.length,
     withVpCode: withCode.length,
     mappedToOverview: mapped.length,
     withVpCodeRatio: scenarios.length ? withCode.length / scenarios.length : 0,
     mappedRatio: scenarios.length ? mapped.length / scenarios.length : 0,
-    note: mapped.length < withCode.length * 0.5
-      ? 'Scenarios use ad-hoc VP-<CAT>-NNN codes not linked to viewpoint-overview ids (weak traceability — see review Gate 4).'
+    note: withCode.length && mapped.length < withCode.length * 0.5
+      ? 'Scenario IDs do not match the viewpoint-overview ids (weak traceability — re-tag to the project viewpoint IDs).'
       : 'Traceable.',
   };
 }
@@ -367,14 +373,85 @@ const CLAIM_RULES: ClaimRule[] = [
     hint: 'capture the before-state and assert the after-state differs, or assert the visible/hidden transition.',
     severity: 'warn',
   },
+  {
+    // GENERAL — mutation-absence. A title asserts that a STATE-CHANGING action does NOT
+    // happen / does not repeat (submit, send, create, charge, order, pay, email, request,
+    // OTP, register, book, a re-/double-/again repeat…) paired with a negation in EITHER
+    // language. A mutation's absence is NOT observable from a positive `see [X] page` —
+    // that page looks identical whether or not the mutation fired — so it MUST prove a
+    // count/contrast (record count unchanged) or defer to @manual. This is the general
+    // category behind "browser back does not re-submit", "does not re-charge the card",
+    // "double-click does not create two orders" — not a per-feature keyword.
+    claim: 'no-side-effect/no-duplicate',
+    title: /(?=.*\b(submit|sen[dt]|resend|resubmit|re-?fire|re-?issue|re-?post|repost|create|charge|order|payment|\bpay\b|email|request|\botp\b|insert|register|book|duplicate|double[- ]?submit|again|twice)\b)(?=.*(\bno\b|\bnot\b|n['’]t\b|\bnever\b|\bwithout\b|\bcannot\b|prevent|block|avoid|reject|disabl|\bdeny\b|denies|\bkhông\b|\bchưa\b))/i,
+    proof: /\bcount\b|row with \{\{|table with|tohavecount|is hidden|are hidden|not complete|no longer/,
+    need: 'a record/request-count proof (count stays at one, e.g. `User see [Table] row with {{count}}`) or @manual with a request-count oracle',
+    hint: 'a "does-not-happen / does-not-repeat" claim about a state-changing action is NOT proven by a terminal `see [...] page` — that page is identical whether or not the action (re-)fired. Prove the side-effect count is unchanged, or mark @manual with a setup→action→assert-no-duplicate oracle.',
+    severity: 'fail',
+  },
   {
     claim: 'hidden/rejected/not-complete',
-    title: /\b(hidden|closed|dismiss(es|ed)?|does not|doesn't|not complete|rejected|inert)\b/,
+    title: /\b(hidden|closed|dismiss(es|ed)?|not complete|rejected|inert)\b/,
     proof: /\bis hidden\b|\bare hidden\b|message is hidden|not complete|\bhidden\b/,
     need: 'a negative / hidden assertion (`… is hidden`)',
     hint: 'assert the absence/hidden state that the title claims, not just an unrelated visible element.',
     severity: 'fail',
   },
+  {
+    claim: 'cleared/emptied',
+    title: /\b(cleared|clears|emptied|empties|reset to empty|wiped)\b/,
+    proof: /\bis empty\b|with \{\{empty|with ['"]?['"]?\s*$|\bempty\b/,
+    need: 'an empty/cleared assertion after the action (e.g. `field with {{empty_value}}` / `is empty`)',
+    hint: 'prove the value is actually gone — return to the screen and assert the field is empty, not just that the action ran.',
+    severity: 'fail',
+  },
+  {
+    claim: 'restored/preserved',
+    title: /\b(restored|preserved|persists?|retained|remembered|kept)\b/,
+    proof: /\bremember\b|with \{\{|field with/,
+    need: 'the value re-asserted after the transition (capture or `field with {{v}}` after returning)',
+    hint: 'prove the value survives — assert the field still holds the typed value after the reload/return, not just that it was typed.',
+    severity: 'warn',
+  },
+  {
+    claim: 'independent/separate',
+    title: /\b(independent|separate|isolat(ed|es)|per[- ]tab|two tabs|each tab)\b/,
+    proof: /\bcontext\b|tab a|tab b|second (tab|context)/,
+    need: 'a multi-context proof (tab A vs tab B)',
+    hint: 'independence across tabs/contexts is rarely DSL-expressible — mark @manual with a clear setup/action/oracle.',
+    severity: 'warn',
+  },
+  {
+    claim: 'sanitized/inert',
+    title: /\b(sanitized|sanitised|escaped|inert|not executed|not rendered|stripped)\b/,
+    proof: /field with \{\{|payload|inert|toContainText|is hidden/,
+    need: 'the payload echoed as inert text (`field with {{payload}}`) + no execution',
+    hint: 'prove the payload round-trips as literal text and triggers nothing — assert the field value and the absence of any effect.',
+    severity: 'warn',
+  },
+  {
+    claim: 'announces/aria',
+    title: /\b(announce[sd]?|aria|screen[- ]reader|programmatically associated)\b/,
+    proof: /aria|role|@manual|describedby|is focused/,
+    need: 'an aria/role assertion (or @manual with a screen-reader oracle)',
+    hint: 'ARIA announcement is usually not DSL-expressible — assert aria attributes if possible, else @manual with an NVDA/VoiceOver oracle.',
+    severity: 'warn',
+  },
+  {
+    // GENERAL CATCH-ALL (last) — any negative/absence title not handled by a specific
+    // rule above. Language-aware negation, NO verb list: if the title says "no / not /
+    // never / without / không / prevents …" the steps must carry a NEGATIVE/contrast
+    // assertion (hidden, empty, error, count, no-longer, a remembered before/after) — not
+    // only a positive presence. WARN, because a positive proxy is sometimes a valid
+    // negative proof (e.g. "stayed on the login page"); the semantic reviewer is the
+    // authoritative recall layer for the residue this can't judge structurally.
+    claim: 'negative-claim/absence',
+    title: /(\bno\b|\bnot\b|n['’]t\b|\bnever\b|\bwithout\b|\bcannot\b|prevent|block|avoid|reject|disabl|\bdeny\b|denies|\bkhông\b|\bchưa\b)/i,
+    proof: /is hidden|are hidden|is empty|no longer|not complete|disabl|invalid|rejected|\berror\b|\bcount\b|row with \{\{|table with|\bremember\b|\bexactly\b|tohavecount/i,
+    need: 'a proof of the ABSENCE — a contrast/empty/hidden/error/count assertion, or @manual with an oracle',
+    hint: 'a negative claim ("no / not / không …") is not proven by a positive `see [X]` that looks the same whether or not the claim holds. Assert the contrast (state hidden/empty, error shown, count unchanged), or mark @manual.',
+    severity: 'warn',
+  },
 ];
 
 // ---------- Viewpoint taxonomy-lint (harness-roadmap §0.5 Q3) ----------

package/src/harness/spec-coverage.ts

@@ -0,0 +1,139 @@
+/**
+ * Spec-clause coverage (harness G2) — the spec-layer faithfulness check.
+ *
+ * Parses the structured parts of a screen `spec.md` (Functional Requirements + the
+ * Validation Rules table) and verifies (a) every MUST FR is covered by a scenario and
+ * (b) for EACH validation constraint, every trigger the spec mandates is actually
+ * exercised. The trigger check is PER-CONSTRAINT — so "validate format on blur AND on
+ * submit" tested only on blur is caught even when other constraints do use submit.
+ * Generic: no project data.
+ */
+import * as fs from 'fs';
+import { ScenarioInfo } from './parse';
+
+export type Modality = 'MUST' | 'SHOULD' | 'MAY';
+
+export interface TriggerGap { constraint: string; code: string; required: string[]; found: string[]; missing: string[] }
+
+export interface SpecCoverageResult {
+  hasSpec: boolean;
+  frTotal: number;
+  frCovered: number;
+  uncoveredMust: { id: string; text: string }[];
+  triggerGaps: TriggerGap[];     // per-constraint trigger matrix gaps
+  verdict: 'pass' | 'warn' | 'fail';
+}
+
+interface FrClause { id: string; text: string; modality: Modality }
+interface ValRow { constraint: string; code: string; triggers: string[] }
+
+// Parsing the spec's Trigger CELL: loose word match ("blur, submit").
+const SPEC_TRIGGER: { trigger: string; re: RegExp }[] = [
+  { trigger: 'blur', re: /\b(blur|on blur|focus[- ]?out)\b/i },
+  { trigger: 'submit', re: /\b(submit|on submit)\b/i },
+];
+// Detecting the trigger ACTION in a scenario: must be an actual action, NOT the word
+// "submit" in a "[Submit] button is disabled" assertion.
+const ACTION_TRIGGER: { trigger: string; re: RegExp }[] = [
+  { trigger: 'blur', re: /\b(press tab|blur|focus[- ]?out|loses? focus|tab away|tab out)\b/i },
+  { trigger: 'submit', re: /(click \[submit\]|press enter|\benter key\b|送信する)/i },
+];
+
+function modalityOf(text: string): Modality {
+  if (/\bMUST\b/.test(text)) return 'MUST';
+  if (/\bSHOULD\b/.test(text)) return 'SHOULD';
+  return 'MAY';
+}
+
+function specTriggersIn(text: string): string[] {
+  return SPEC_TRIGGER.filter((t) => t.re.test(text)).map((t) => t.trigger);
+}
+function actionTriggersIn(text: string): string[] {
+  return ACTION_TRIGGER.filter((t) => t.re.test(text)).map((t) => t.trigger);
+}
+
+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 frs: FrClause[] = [];
+  for (const line of lines) {
+    const m = line.match(/\*\*FR-(\d+)\*\*\s*:\s*(.+)$/);
+    if (m) frs.push({ id: `FR-${m[1]}`, text: m[2].replace(/\*\*/g, '').trim(), modality: modalityOf(m[2]) });
+  }
+
+  // Validation Rules table: a row carries a Constraint, a Trigger cell, and (often) a code.
+  const valRows: ValRow[] = [];
+  let cTrigger = -1, cConstraint = -1, cCode = -1, inTable = false;
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.startsWith('|') && /\btrigger\b/i.test(line) && cTrigger < 0) {
+      const cells = line.split('|').map((c) => c.trim());
+      cTrigger = cells.findIndex((c) => /^trigger$/i.test(c));
+      cConstraint = cells.findIndex((c) => /constraint/i.test(c));
+      cCode = cells.findIndex((c) => /code/i.test(c));
+      inTable = cTrigger >= 0;
+      continue;
+    }
+    if (inTable) {
+      if (!line.startsWith('|')) { inTable = false; cTrigger = -1; continue; }
+      if (/^\|[\s|:-]+\|?$/.test(line)) continue;
+      const cells = line.split('|').map((c) => c.trim());
+      const triggers = [...new Set((cells[cTrigger] || '').split(/,|\band\b/i).flatMap((p) => specTriggersIn(p)))];
+      if (!triggers.length) continue; // server-only rows etc.
+      const constraint = (cConstraint >= 0 ? cells[cConstraint] : '').replace(/`/g, '') || 'validation';
+      const codeM = (cCode >= 0 ? cells[cCode] : line).match(/M\d+/);
+      valRows.push({ constraint, code: codeM ? codeM[0] : '', triggers });
+    }
+  }
+  return { frs, valRows };
+}
+
+/** Split a feature file into per-scenario blocks (tags + comments + steps), keyed by blank lines. */
+function scenarioBlocks(featureText: string): string[] {
+  return featureText.split(/\n\s*\n/).filter((b) => /\bScenario:/.test(b)).map((b) => b.toLowerCase());
+}
+
+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' };
+  }
+  const featLower = featureText.toLowerCase();
+
+  // FR coverage: explicit @spec:FR / literal FR-id citation, else keyword fallback.
+  const uncoveredMust: { id: string; text: string }[] = [];
+  let frCovered = 0;
+  for (const fr of frs) {
+    const idLower = fr.id.toLowerCase();
+    const cited = featLower.includes(idLower);
+    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) });
+  }
+
+  // Per-constraint trigger coverage — the matrix-collapse catch.
+  // generic words that don't identify a constraint (would over-match happy-path scenarios)
+  const GENERIC = new Set(['valid', 'local', 'part', 'domain', 'email', 'address', 'must', 'exist', 'store', 'field', 'input', 'value', 'formed', 'well', 'character', 'characters']);
+  const blocks = scenarioBlocks(featureText);
+  const triggerGaps: TriggerGap[] = [];
+  for (const row of valRows) {
+    const kw = (row.constraint.toLowerCase().match(/[a-z]{4,}/g) || []).filter((w) => !GENERIC.has(w));
+    // blocks that belong to this constraint: cite its msg code (primary), or mention a
+    // DISTINCTIVE constraint word (generic words filtered to avoid matching happy paths).
+    const own = blocks.filter((b) =>
+      (row.code && b.includes(row.code.toLowerCase())) || kw.some((w) => b.includes(w)),
+    );
+    if (!own.length) continue; // constraint has no scenarios at all — FR/viewpoint gate covers that
+    const found = [...new Set(own.flatMap((b) => actionTriggersIn(b)))];
+    const missing = row.triggers.filter((t) => !found.includes(t));
+    if (missing.length) triggerGaps.push({ constraint: row.constraint, code: row.code, required: row.triggers, found, missing });
+  }
+
+  const verdict: SpecCoverageResult['verdict'] =
+    uncoveredMust.length > 0 || triggerGaps.length > 0 ? 'fail' : 'pass';
+
+  return { hasSpec: true, frTotal: frs.length, frCovered, uncoveredMust, triggerGaps, verdict };
+}

package/src/harness/viewpoint-ledger.ts

@@ -0,0 +1,80 @@
+/**
+ * Viewpoint Atomic Coverage Ledger (harness #2).
+ *
+ * The project's `test-viewpoint.md` IS the coverage contract. This parses it into ATOMIC
+ * items (each bullet / table row / ID-prefixed line) and reports the status of EACH —
+ * covered / missing — instead of the coarse "viewpoint mentioned" signal. It is fully
+ * project-driven (works on any project's viewpoint file, any domain), which is why it
+ * scales where a hardcoded domain catalog does not. Advisory: it surfaces the per-item
+ * gaps that inflate a "looks-covered" score; it does not fail the gate.
+ */
+import * as fs from 'fs';
+import { ScenarioInfo } from './parse';
+
+export interface LedgerItem { id?: string; text: string; covered: boolean }
+
+export interface LedgerResult {
+  hasViewpoint: boolean;
+  total: number;
+  covered: number;
+  ratio: number;
+  missing: { id?: string; text: string }[];
+}
+
+const ID_RE = /\b([A-Z]{1,5}\d{0,2}(?:[.\-][A-Za-z0-9]+)*-?\d{0,3})\b/; // VP0.Title, VP7-002, MS-HP-001, TV-01
+const GENERIC = new Set(['display', 'shown', 'value', 'field', 'input', 'page', 'screen', 'button', 'link', 'text', 'check', 'verify', 'should', 'with', 'when', 'then', 'user', 'this', 'that', 'each', 'item', 'items']);
+
+/** 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 items: { id?: string; text: string }[] = [];
+  let inFence = false;
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.startsWith('```')) { inFence = !inFence; continue; }
+    if (inFence || !line) continue;
+    if (/^#{1,6}\s/.test(line)) continue;                 // markdown heading
+    let text = '';
+    const bullet = line.match(/^(?:[-*+]|\d+[.)])\s+(.*)$/);
+    if (bullet) text = bullet[1];
+    else if (line.startsWith('|')) {                       // table data row
+      if (/^\|[\s|:-]+\|?$/.test(line)) continue;           // separator
+      const cells = line.split('|').map((c) => c.trim()).filter(Boolean);
+      if (/^(vp|id|viewpoint|priority|reason|no\.?|category|item|trigger|#|pattern|applicable|notes|field|constraint|code|description|status)$/i.test(cells[0] || '')) continue; // header
+      text = cells.join(' — ');
+    } else continue;
+    text = text.replace(/[*`]/g, '').trim();
+    if (!text) continue;
+    const idM = text.match(ID_RE);
+    const id = idM && /\d/.test(idM[1]) ? idM[1] : undefined; // require a digit so prose words aren't IDs
+    const words = (text.toLowerCase().match(/[a-z][a-z-]{3,}/g) || []).filter((w) => !GENERIC.has(w));
+    if (!id && words.length < 2) continue;                 // not substantive enough to track
+    items.push({ id, text: text.slice(0, 100) });
+  }
+  return items;
+}
+
+export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[], featureText: string): LedgerResult {
+  const items = parseViewpointItems(viewpointPath);
+  if (!fs.existsSync(viewpointPath) || items.length === 0) {
+    return { hasViewpoint: fs.existsSync(viewpointPath), total: 0, covered: 0, ratio: 1, missing: [] };
+  }
+  const featLower = featureText.toLowerCase();
+  const missing: { id?: string; text: string }[] = [];
+  let covered = 0;
+
+  for (const item of items) {
+    let isCovered = false;
+    if (item.id && featLower.includes(item.id.toLowerCase())) isCovered = true;
+    else {
+      const words = [...new Set((item.text.toLowerCase().match(/[a-z][a-z-]{3,}/g) || []).filter((w) => !GENERIC.has(w)))];
+      const need = Math.min(2, words.length);
+      isCovered = words.length > 0 && scenarios.some((s) => words.filter((w) => s.haystack.includes(w)).length >= need);
+    }
+    if (isCovered) covered++;
+    else missing.push({ id: item.id, text: item.text });
+  }
+
+  return { hasViewpoint: true, total: items.length, covered, ratio: items.length ? covered / items.length : 1, missing };
+}

package/src/ingest/baseline-audit.ts

@@ -0,0 +1,100 @@
+/**
+ * QA baseline audit over a legacy testcase inventory (P-A). Reuses the harness
+ * duplicate sensor + the capability-plan reason classifier so the legacy view and
+ * the Gherkin view agree. Advisory — evaluates the *existing* manual suite and the
+ * automation/driver opportunity; it does not gate anything.
+ */
+import { LegacyInventory, LegacyTestcase } from './legacy-parser';
+import { duplicateClusters } from '../harness/sensors';
+import { ScenarioInfo } from '../harness/parse';
+import { classifyReason, MANUAL_REASONS } from '../harness/capability-plan';
+
+export interface BaselineReport {
+  total: number;
+  sheets: { name: string; type: string; rows: number }[];
+  byCategory: Record<string, number>;
+  byPriority: Record<string, number>;
+  byResult: Record<string, number>;
+  depthRatio: number;          // % of TC whose Expected asserts a concrete value
+  deepCount: number;
+  duplicateClusters: number;
+  exactDuplicates: number;
+  reasons: {                   // capability-plan style distribution
+    ui: number; crossScreen: number; capabilityManual: number; keepManual: number;
+    byCode: Record<string, number>;
+    driverCandidates: { driver: string; count: number }[];
+  };
+}
+
+/** An Expected that asserts a concrete value (not just "displayed/visible"). */
+function isDeep(tc: LegacyTestcase): boolean {
+  const e = (tc.expected || '').trim().toLowerCase();
+  if (!e) return false;
+  const shallowOnly = /^(.{0,40})(表示される|hiển thị|displayed|shown|is visible|表示)$/.test(e);
+  const hasValue = /(=|equals?|bằng|giá trị|\bvalue\b|"|「|\bmessage\b|エラー|error|\bcount\b|số lượng|\bformat\b|định dạng)/.test(e);
+  return hasValue || (!shallowOnly && e.length > 30);
+}
+
+/** Synthesize a ScenarioInfo-lite so we can reuse harness sensors on the inventory. */
+export function legacyToScenarioInfo(tc: LegacyTestcase): ScenarioInfo {
+  const skeleton = (tc.steps || '')
+    .replace(/\{\{[^}]*\}\}/g, '{}').replace(/"[^"]*"/g, '""')
+    .replace(/\d+/g, 'N').replace(/\s+/g, ' ').trim().toLowerCase();
+  const hay = `${tc.category} ${tc.steps} ${tc.expected}`.toLowerCase();
+  return {
+    name: `${tc.category}: ${tc.id}`,
+    category: (tc.category || '').toUpperCase().replace(/[^A-Z0-9]+/g, '-').slice(0, 16),
+    priority: tc.priority,
+    manual: true,
+    thenCount: tc.expected ? 1 : 0,
+    hasDataAssertion: isDeep(tc),
+    shallow: !isDeep(tc),
+    stepSkeleton: skeleton,
+    haystack: hay,
+  } as ScenarioInfo;
+}
+
+export function baselineAudit(inv: LegacyInventory): BaselineReport {
+  const tcs = inv.testcases;
+  const inc = (m: Record<string, number>, k: string) => { m[k] = (m[k] || 0) + 1; };
+
+  const byCategory: Record<string, number> = {};
+  const byPriority: Record<string, number> = {};
+  const byResult: Record<string, number> = {};
+  let deepCount = 0;
+  const byCode: Record<string, number> = {};
+  let ui = 0, crossScreen = 0, capabilityManual = 0, keepManual = 0;
+  const driverHits: Record<string, number> = {};
+
+  for (const tc of tcs) {
+    inc(byCategory, tc.category || '(uncategorized)');
+    inc(byPriority, tc.priority);
+    inc(byResult, (tc.result || '(not-run)').trim() || '(not-run)');
+    if (isDeep(tc)) deepCount++;
+
+    const code = classifyReason(`${tc.precondition || ''} ${tc.steps} ${tc.expected} ${tc.testData || ''}`);
+    if (!code) { ui++; continue; }
+    inc(byCode, code);
+    if (code === 'XS') { crossScreen++; continue; }
+    const def = MANUAL_REASONS[code];
+    if (def?.cls === 'keep') keepManual++;
+    else { capabilityManual++; for (const d of def?.drivers || []) driverHits[d] = (driverHits[d] || 0) + 1; }
+  }
+
+  const dup = duplicateClusters(tcs.map(legacyToScenarioInfo));
+
+  return {
+    total: tcs.length,
+    sheets: inv.sheets,
+    byCategory, byPriority, byResult,
+    depthRatio: tcs.length ? deepCount / tcs.length : 0,
+    deepCount,
+    duplicateClusters: dup.clusters.length,
+    exactDuplicates: dup.exactDuplicateCount,
+    reasons: {
+      ui, crossScreen, capabilityManual, keepManual, byCode,
+      driverCandidates: Object.entries(driverHits).map(([driver, count]) => ({ driver, count }))
+        .sort((a, b) => b.count - a.count),
+    },
+  };
+}