@sun-asterisk/sungen 3.2.31 → 3.2.33

package/src/harness/config-file.ts

@@ -0,0 +1,66 @@
+/**
+ * Reading a config file has THREE outcomes, not two: absent, parsed, and present-but-unreadable.
+ *
+ * Collapsing the third into the first is the defect class #782 catalogues. The shape recurs because
+ * it looks harmless: an `fs.existsSync` guard already answers absence, so the `catch` below it only
+ * ever fires for CORRUPTION — and returning the absent value there is the one case that must not be
+ * silent. A file that is absent was never written; a file that is broken WAS written, by someone who
+ * believes it is in effect.
+ *
+ * `run-manifest.ts:hashTopLevel` already draws the distinction for its own reader (`__unparseable__`
+ * rather than `{}`); this is that idea as a seam every config reader can share, so the next one does
+ * not have to rediscover it.
+ *
+ * Nothing here throws: the caller owns the consequence, because only the caller knows it. What the
+ * type removes is the option of not deciding.
+ */
+import * as fs from 'fs';
+import { parse as parseYaml } from 'yaml';
+
+export type ConfigRead<T> =
+  | { state: 'absent' }
+  | { state: 'ok'; value: T }
+  | { state: 'unreadable'; error: string };
+
+const message = (e: unknown): string => (e instanceof Error ? e.message.split('\n')[0] : String(e));
+
+/** Read + parse a YAML config. An empty or comment-only file parses to null — that is `ok`, not broken. */
+export function readYamlConfig<T>(file: string): ConfigRead<T> {
+  if (!fs.existsSync(file)) return { state: 'absent' };
+  try {
+    return { state: 'ok', value: (parseYaml(fs.readFileSync(file, 'utf-8')) ?? null) as T };
+  } catch (e) {
+    return { state: 'unreadable', error: message(e) };
+  }
+}
+
+/** Read + parse a JSON config. Unlike YAML, an empty file is NOT valid JSON and reads as unreadable. */
+export function readJsonConfig<T>(file: string): ConfigRead<T> {
+  if (!fs.existsSync(file)) return { state: 'absent' };
+  try {
+    return { state: 'ok', value: JSON.parse(fs.readFileSync(file, 'utf-8')) as T };
+  } catch (e) {
+    return { state: 'unreadable', error: message(e) };
+  }
+}
+
+/**
+ * One line to stderr naming the file, the parse error, and WHAT THE RUN WILL DO INSTEAD — the last
+ * part is the whole point: "capabilities.yaml is broken" leaves the reader guessing; "…so this run
+ * treats the project as web" tells them why their mobile suite just compiled wrong.
+ *
+ * At most once per file per process. `readCapabilities` alone has fifteen call sites, and a warning
+ * repeated fifteen times reads as noise — which is its own way of being ignored.
+ */
+const warned = new Set<string>();
+
+export function warnUnreadableConfig(file: string, error: string, consequence: string): void {
+  if (warned.has(file)) return;
+  warned.add(file);
+  console.error(`⚠️  ${file}: unreadable (${error}) — ${consequence}`);
+}
+
+/** Test seam: the dedup set is process-global, so a suite exercising several cases must clear it. */
+export function resetUnreadableConfigWarnings(): void {
+  warned.clear();
+}

package/src/harness/depth-lint.ts

@@ -15,6 +15,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { loadUnitScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
 import { loadCatalog, viewpointGate, assertionDepth, dataThemesFor, CatalogTheme } from './sensors';
+import { keywordHit } from './keyword-match';
 
 export type DepthAction = 'deepen' | 'defer';
 
@@ -45,7 +46,7 @@ export interface DepthLintReport {
 function matchTheme(s: ScenarioInfo, dataThemes: CatalogTheme[]): CatalogTheme | undefined {
   return dataThemes.find((t) => {
     const kws = t.depth?.keywords?.length ? t.depth.keywords : t.keywords;
-    return kws.some((k) => s.haystack.includes(k.toLowerCase()));
+    return kws.some((k) => keywordHit(s.haystack, k));
   });
 }
 

package/src/harness/flow-check.ts

@@ -12,6 +12,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { featureFilesFor } from './unit-paths';
+import { keywordHit } from './keyword-match';
 import { loadScenarios } from './parse';
 import { parseScenarios } from './capability-plan';
 import { readTextFile } from './read-text';
@@ -45,7 +46,10 @@ function featureTags(fp: string): string[] {
 }
 function targetsFromHint(hint: string): string[] {
   const h = hint.toLowerCase();
-  const hits = KNOWN_TARGETS.filter((k) => h.includes(k));
+  // Word-aware (#779): every KNOWN_TARGET is an ordinary noun, so a substring test read
+  // `re·order` / `dis·order` as the target `order` and then matched the two to each other —
+  // a deferral about reorder history reported COVERED by a flow scenario about a disorder.
+  const hits = KNOWN_TARGETS.filter((k) => keywordHit(h, k));
   if (hits.length) return hits;
   // fallback: significant words after "->"
   const after = h.split('->').pop() || h;
@@ -87,7 +91,7 @@ export function buildFlowCheck(cwd: string, onlyFlow?: string): FlowCheckReport
       // `@owned-by:<flow>` names the owner explicitly → only that flow's scenarios can cover it
       // (a false @owned-by is then surfaced as missing). Else any flow may cover it (legacy).
       const pool = s.ownedBy ? flowScenarios.filter((fs2) => fs2.flow === s.ownedBy) : flowScenarios;
-      const matches = pool.filter((fs2) => targets.some((t) => fs2.haystack.includes(t)));
+      const matches = pool.filter((fs2) => targets.some((t) => keywordHit(fs2.haystack, t)));
       let verdict: Deferral['verdict'] = 'missing';
       let via: string | undefined;
       if (matches.some((m) => m.deep)) { verdict = 'covered'; via = matches.find((m) => m.deep)!.flow; }

package/src/harness/keyword-match.ts

@@ -0,0 +1,85 @@
+/**
+ * Keyword matching for the audit's coverage sensors — the single rule every "does a scenario
+ * mention this?" question goes through.
+ *
+ * WHY THIS EXISTS (#776). The sensors used to ask `haystack.includes(keyword)`. A substring match
+ * is satisfied by a keyword buried inside an unrelated word, and it fails in the direction that
+ * HIDES problems: a theme nobody tested reads as covered. Measured case — the scenario title
+ * "…five steps from email through to information entry" made `format-boundary` covered on a screen
+ * with no text input at all, because in·format·ion contains `format`. That one word moved the
+ * screen from 7.9 FAIL to 8.9 PASS.
+ *
+ * THE RULE: anchor a word boundary at the START of the keyword, leave the END free.
+ *
+ * Not `\b…\b` at both ends, which is the obvious fix and is wrong. Every collision this defect
+ * produces is a PREFIX collision — the innocent word carries extra letters BEFORE the keyword:
+ *
+ *     format  ← in·format·ion, ·format·ting        range   ← ar·range·ment, o·range
+ *     saved   ← un·saved                           created ← re·created
+ *     success ← un·success·ful                     length  ← wave·length
+ *
+ * The `unsaved` / `unsuccessful` pair is the sharp end: the prefix INVERTS the meaning, so a
+ * scenario asserting a submit FAILED is what marks the submit-SUCCESS theme covered.
+ *
+ * Meanwhile English inflection lives entirely in the SUFFIX, and a trailing `\b` destroys it:
+ * `submit` stops matching "submitted", `success` stops matching "successfully", `valid` stops
+ * matching "validation", `create` stops matching "created". Those are true positives, and a
+ * both-ends boundary turns 4 of 5 of them into false gaps — trading a silent failure for a noisy
+ * one. A leading boundary alone kills all six collisions above and keeps all of them.
+ *
+ * WHAT THIS RULE DOES NOT FIX, stated rather than implied. A free suffix still admits a collision
+ * when the keyword is a true PREFIX of a common unrelated word:
+ *
+ *     feed → "feedback"    list → "listener"    length → "lengthy"
+ *
+ * No boundary rule can separate `feed` from `feedback`, so the cure is a less ambiguous KEYWORD,
+ * which is a catalog decision rather than a matcher one. #778 took it: the shipped catalog no
+ * longer carries any of the three bare forms — `"product list"`, `"feed item"` and
+ * `"max length"` / `"min length"` replaced them, and `cart-correctness` lost bare `price` and
+ * `quantity` (ordinary listing vocabulary that credited a cart theme on a screen with no cart).
+ *
+ * That closes today's instances, not the class. `tests/harness/keyword-word-boundary.run.ts`
+ * section (e) sweeps every single-word ASCII keyword in the catalog — theme `keywords`,
+ * `detect_keywords` and `depth.keywords` alike — so a NEW loose keyword fails the suite instead of
+ * entering silently. Adding one is possible, but only as a conscious act via that file's
+ * `KNOWN_LOOSE` map, which #778 left empty.
+ *
+ * NON-ASCII KEYWORDS fall back to substring, on purpose. JavaScript's `\b` is defined against
+ * `[A-Za-z0-9_]`, so `\bログイン` and `\bđăng nhập` never match anything at all — the anchor would
+ * silently disable the keyword rather than tighten it. Japanese and Chinese have no word
+ * boundaries to anchor to, which is precisely where substring matching is the CORRECT behaviour
+ * and the false-positive risk is low. Today every keyword reaching here is ASCII by construction
+ * (the catalog is English; the ledger and spec sensors extract words with `[a-z]` character
+ * classes), so this branch is a guard against a future non-ASCII catalog entry failing closed.
+ */
+
+/** True when `kw`'s first character can carry a `\b` anchor — i.e. it is an ASCII word character. */
+const anchorable = (kw: string): boolean => /^[a-z0-9_]/i.test(kw);
+
+const cache = new Map<string, RegExp | null>();
+
+/**
+ * Compile `kw` to its matcher, or `null` when the keyword must be compared as a plain substring.
+ * Cached: the sensors re-ask the same handful of catalog keywords once per scenario.
+ */
+function matcherFor(kw: string): RegExp | null {
+  const key = kw.toLowerCase();
+  if (cache.has(key)) return cache.get(key)!;
+  const re = anchorable(key)
+    ? new RegExp(`\\b${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`)
+    : null;
+  cache.set(key, re);
+  return re;
+}
+
+/** Does `haystack` mention `kw` as a word (not as the tail of a longer one)? */
+export function keywordHit(haystack: string, kw: string): boolean {
+  const h = haystack.toLowerCase();
+  const re = matcherFor(kw);
+  return re ? re.test(h) : h.includes(kw.toLowerCase());
+}
+
+/** Does ANY of `haystacks` mention `kw`? */
+export function hasKeyword(haystacks: string[], kw: string): boolean {
+  return haystacks.some((h) => keywordHit(h, kw));
+}

package/src/harness/next-step.ts

@@ -167,7 +167,8 @@ const REPAIRABLE = [
   'FLOW-CONTRACT-MISSING', 'FLOW-INVENTORY-MISSING', 'FLOW-UNCOVERED', 'FLOW-UNDECLARED',
   'FLOW-PHASE-MISFILED', 'FLOW-GUARANTEE-MISSING', 'FLOW-OUTCOME-UNPROVEN', 'CONTINUITY-ONE-SIDED',
   'ORACLE-URL-ONLY',
-  'SPEC-RESTATED-UNVERIFIED', 'VIEWPOINT-GESTURE-SUBSTITUTED', 'SPEC-UNCOVERED', 'TRIGGER-UNCOVERED',
+  'SPEC-RESTATED-UNVERIFIED', 'VIEWPOINT-GESTURE-SUBSTITUTED', 'SPEC-UNCOVERED', 'SPEC-CLAUSE-UNCOVERED',
+  'TRIGGER-UNCOVERED', 'PERMISSION-PAIR-MISSING', 'VISIBILITY-PAIR-MISSING',
   'VIEWPOINT-ITEM-MISSING', 'MANUAL-CODE-MISSING', 'MANUAL-AUTOMATABLE', 'DEPTH-DEFERRED',
 ];
 

package/src/harness/parse.ts

@@ -78,6 +78,32 @@ function isViewpointId(s: string): boolean {
   return isIdLike(s) || /^(?:VP|FL)-[A-Z][A-Z0-9]*$/i.test(s);
 }
 
+/**
+ * A markdown heading's TEXT, normalised the way the ledger already normalises it.
+ *
+ * Headings in a real viewpoint file are numbered ("## 2. Priority Viewpoints") and often bolded
+ * ("## **Priority Viewpoints**"), and both forms are what the authoring template produces. Every
+ * pass below anchored on the bare literal, so a numbered file parsed to ZERO viewpoints: the
+ * priority table was dropped whole, clean rows included, and the audit lost its traceability
+ * table. `viewpoint-ledger.ts` learned the same lesson at its own heading test (#657); this is
+ * that normalisation, applied where the overview reads headings.
+ *
+ * Returns null for a line that is not a heading, so a caller can tell "not a heading" from
+ * "a heading whose text is empty".
+ */
+function headingParts(line: string): { level: number; text: string } | null {
+  const m = line.match(/^(#{1,6})\s+(.*)$/);
+  if (!m) return null;
+  const text = m[2]
+    .replace(/[*`]/g, '')
+    // Multi-level (`2.1`, `3.2.4`) and roman numbering are at least as common in a numbered spec as
+    // a single digit, and a strip that only handled one level left `## 2.1 Priority Viewpoints`
+    // reading as `1 Priority Viewpoints` — the same zero-viewpoint failure, one dot away.
+    .replace(/^\s*(?:\d+(?:\.\d+)*|[IVXLCDM]+|[A-Z])\s*[.):]?\s+/, '')
+    .trim();
+  return { level: m[1].length, text };
+}
+
 export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
   if (!fs.existsSync(filePath)) return [];
   const text = readTextFile(filePath);
@@ -89,12 +115,15 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
   let inPriorityTable = false;
   for (const raw of lines) {
     const line = raw.trim();
-    if (/^##\s+Priority Viewpoints/i.test(line)) { inPriorityTable = true; continue; }
-    if (inPriorityTable && /^##\s/.test(line)) { inPriorityTable = false; }
+    const heading = headingParts(line);
+    if (heading && heading.level === 2 && /^Priority Viewpoints/i.test(heading.text)) { inPriorityTable = true; continue; }
+    if (inPriorityTable && heading && heading.level === 2) { inPriorityTable = false; }
     if (inPriorityTable && line.startsWith('|')) {
       const cells = line.split('|').map((c) => c.trim()).filter((_, i, a) => i > 0 && i < a.length - 1);
       if (cells.length >= 3) {
-        const id = cells[0];
+        // The same `**` the heading carries: ids are routinely written `| **VP-LOGIC** | High | … |`,
+        // and an id read with its emphasis markers still attached matches no scenario tag.
+        const id = cells[0].replace(/[*`]/g, '').trim();
         if (isViewpointId(id) && !/^-+$/.test(cells[1])) {
           const pr = /high/i.test(cells[1]) ? 'High' : /medium/i.test(cells[1]) ? 'Medium' : /low/i.test(cells[1]) ? 'Low' : 'Unknown';
           entries.set(id.toUpperCase(), { id: id.toUpperCase(), priority: pr as any, reason: cells[2] });
@@ -110,7 +139,10 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
   // FL-HP-001 were reported as unmapped. Both forms are additive here.
   for (const raw of lines) {
     const line = raw.trim();
-    const section = line.match(/^##\s+([A-Z]{2,}(?:-[A-Z0-9]{2,})*)\s+[—–-]\s*(.*)$/);
+    const head = headingParts(line);
+    const section = head && head.level === 2
+      ? head.text.match(/^([A-Z]{2,}(?:-[A-Z0-9]{2,})*)\s+[—–-]\s*(.*)$/)
+      : null;
     if (section && isViewpointId(section[1] + '-0')) {
       const id = section[1].toUpperCase();
       if (!entries.has(id)) entries.set(id, { id, priority: 'Unknown', reason: section[2] ?? '' });
@@ -130,11 +162,14 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
   let group: ViewpointEntry['group'] | undefined;
   for (const raw of lines) {
     const line = raw.trim();
-    const g = line.match(/^###\s+(Required|Recommended|Optional)/i);
+    const head = headingParts(line);
+    const g = head && head.level === 3 ? head.text.match(/^(Required|Recommended|Optional)/i) : null;
     if (g) { group = (g[1][0].toUpperCase() + g[1].slice(1).toLowerCase()) as any; continue; }
-    if (/^##\s/.test(line)) { group = undefined; }
+    if (head && head.level === 2) { group = undefined; }
     if (group) {
-      const m = line.match(/^[-*+]\s+([A-Za-z][A-Za-z0-9.-]*)/);
+      // `**` and backticks only — a single `*` is a bullet marker here, and stripping it would
+      // stop `* VP-A-001` being a bullet at all.
+      const m = line.replace(/\*\*|`/g, '').match(/^[-*+]\s+([A-Za-z][A-Za-z0-9.-]*)/);
       if (m && isViewpointId(m[1])) {
         const id = m[1].toUpperCase();
         const existing = entries.get(id);

package/src/harness/perf.ts

@@ -23,10 +23,8 @@
  *   units:
  *     place-order: { scenario_ms: 20000 }
  */
-import * as fs from 'fs';
 import * as path from 'path';
-import { parse as parseYaml } from 'yaml';
-import { readTextFile } from './read-text';
+import { readYamlConfig, warnUnreadableConfig } from './config-file';
 
 export interface PerfConfig {
   /** 0..100 — e.g. 75 for p75. */
@@ -51,12 +49,22 @@ export function perfConfigPath(projectRoot: string): string {
   return path.join(projectRoot, 'qa', 'perf.yaml');
 }
 
-/** Absent file → null (perf reporting is opt-in; nothing changes until configured). */
+/**
+ * Absent file → null (perf reporting is opt-in; nothing changes until configured).
+ *
+ * An UNREADABLE file is not that. Returning null for it drops the perf section out of the delivered
+ * matrix (`exporters/matrix/export.ts`) exactly as if no budgets had ever been declared — so a typo
+ * in qa/perf.yaml reads, in the deliverable, as "this project has no performance budgets". Say so.
+ */
 export function loadPerfConfig(projectRoot: string): PerfConfig | null {
   const p = perfConfigPath(projectRoot);
-  if (!fs.existsSync(p)) return null;
-  let raw: Record<string, unknown>;
-  try { raw = parseYaml(readTextFile(p)) as Record<string, unknown>; } catch { return null; }
+  const read = readYamlConfig<Record<string, unknown> | null>(p);
+  if (read.state === 'absent') return null;
+  if (read.state === 'unreadable') {
+    warnUnreadableConfig(p, read.error, 'perf budgets are not applied and the perf section is omitted from the delivered matrix');
+    return null;
+  }
+  const raw = read.value as Record<string, unknown>;
   if (!raw || typeof raw !== 'object') return null;
   const pctRaw = String(raw.percentile ?? 'p75').toLowerCase().replace(/^p/, '');
   const percentile = Math.min(100, Math.max(1, Number(pctRaw) || 75));

package/src/harness/quality-gates.ts

@@ -5,6 +5,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { keywordHit } from './keyword-match';
 import { ScenarioInfo, loadScenarios, idPrefix } from './parse';
 import { parseManualComments } from '../exporters/scenario-merger';
 import { readTextFile } from './read-text';
@@ -57,12 +58,19 @@ function downstreamRoutes(specText: string): string[] {
 }
 
 /**
- * H5 — a @parallel stateful (cart-mutating) flow with NO per-scenario isolation is flaky: scenarios
- * share state, so cart count/quantity asserts race. Mitigations: @cleanup:cart, @isolate, a fresh
+ * H5 — a stateful (cart-mutating) flow with NO per-scenario isolation is flaky: scenarios share
+ * state, so cart count/quantity asserts race. Mitigations: @cleanup:cart, @isolate, a fresh
  * browser context, or a "Given … empty cart" background. Returns true when the risk is unmitigated.
+ *
+ * #759 — this used to require a literal `@parallel`, which made the gate miss the common case.
+ * Parallel is the DEFAULT (code-generator.ts: `isParallelFeature = !isSerialFeature`); `@parallel`
+ * only NAMES that default and changes no codegen, so an untagged stateful flow is isolated exactly
+ * like a tagged one and carries exactly the same risk. The tag that actually changes the emitted
+ * suite is `@serial` — one shared ordered page, where state carry-over is the point — so that is
+ * what exempts a flow now. Same reading as serialCascadeRisk() below, which already said so.
  */
 export function isolationRisk(featureText: string, stateful: boolean, collection = 'cart'): boolean {
-  if (!stateful || !/@parallel\b/i.test(featureText)) return false;
+  if (!stateful || /@serial\b/i.test(featureText)) return false;
   // What discharges the risk is isolation of THE MUTATED COLLECTION — so the cleanup tag has
   // to name it (`@cleanup:cart` for a cart; `@cleanup:registration` for a registration flow).
   // A cleanup of something else (`@cleanup:overlay`) leaves the shared state shared.
@@ -149,8 +157,12 @@ export function downstreamScope(
     // names the same screen under its human label (register ↔ [Registration]).
     const labelsOf = (s: ScenarioInfo): string[] =>
       [...s.haystack.matchAll(/\[([^\]]+)\]/g)].map((m) => m[1].split(':')[0]);
+    // The slug is the route's last segment — in practice an ordinary noun (`order`, `detail`,
+    // `login`), so it is matched as a WORD (#779). `dis·order` is not a reference to `/account/order`,
+    // and crediting it downgraded a route nothing mentions from `absent` to merely `underCovered`.
+    // The full route stays a literal: a path is an identifier, not prose.
     const refs = scenarios.filter((s) =>
-      s.haystack.includes(slug) || s.haystack.includes(route.toLowerCase()) ||
+      keywordHit(s.haystack, slug) || s.haystack.includes(route.toLowerCase()) ||
       labelsOf(s).some((l) => sameScreenName(slug, l)));
     if (!refs.length) {
       // A scenario's haystack is its name + steps, so a route documented in a @manual scenario's

package/src/harness/read-text.ts

@@ -17,9 +17,15 @@ import * as fs from 'fs';
  *
  * A Windows-authored spec is completely normal, so every harness parser that
  * reads a user file must go through here.
+ *
+ * A leading UTF-8 BOM is stripped for the same reason. It is what PowerShell's `Out-File` and
+ * several Windows editors write by default, and it is invisible in every editor — but it breaks a
+ * line-anchored `/^\s*Scenario:/` on line 1, and `JSON.parse` rejects it outright while npm and
+ * most other tools quietly ignore it. A file the rest of the ecosystem reads fine must not read as
+ * corrupt here.
  */
 export function readTextFile(filePath: string): string {
-  return fs.readFileSync(filePath, 'utf-8').replace(/\r\n?/g, '\n');
+  return fs.readFileSync(filePath, 'utf-8').replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
 }
 
 /** `readTextFile` split into lines — the common case for line-anchored parsers. */

package/src/harness/secret-scan.ts

@@ -11,6 +11,19 @@ import * as path from 'path';
 
 export interface SecretHit { file: string; line: number; reason: string }
 
+/** A yaml sink the scanner could not read. Not a hit — the absence of one it cannot vouch for. */
+export interface UnscannedFile { file: string; reason: string }
+
+/**
+ * The scan result, deliberately two lists rather than one.
+ *
+ * This is a security control, and its whole value is that "no hits" means "I looked". A file the
+ * scanner could not read used to be dropped by a bare `catch`, so an unread yaml and a yaml with no
+ * secrets produced the identical answer: clean. Returning `unscanned` alongside makes the caller
+ * hold both facts — what was found, and what the finding does not cover.
+ */
+export interface SecretScanResult { hits: SecretHit[]; unscanned: UnscannedFile[] }
+
 // High-confidence vendor token prefixes (very low false-positive rate).
 const VENDOR_PREFIXES = /\b(figd_[A-Za-z0-9_-]{12,}|ghp_[A-Za-z0-9]{20,}|gho_[A-Za-z0-9]{20,}|glpat-[A-Za-z0-9_-]{16,}|sk-[A-Za-z0-9]{16,}|AKIA[0-9A-Z]{12,}|xox[baprs]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{30,})/;
 // A secret-named key assigned a long, non-placeholder value.
@@ -51,16 +64,59 @@ function scanText(text: string, file: string): SecretHit[] {
 /** Scan a unit dir's committed yaml sinks for likely real secrets: test-data/*.yaml,
  *  mock/*.yaml (mock response bodies are a credential magnet — pasted DevTools
  *  responses carry real tokens), and api/*.yaml (endpoint catalogs carry headers). */
-export function scanTestDataSecrets(baseDir: string): SecretHit[] {
+export function scanTestDataSecrets(baseDir: string): SecretScanResult {
   const hits: SecretHit[] = [];
+  const unscanned: UnscannedFile[] = [];
+  const why = (e: unknown): string => (e instanceof Error ? e.message.split('\n')[0] : String(e));
+
   for (const sub of ['test-data', 'mock', 'api']) {
     const dir = path.join(baseDir, sub);
     if (!fs.existsSync(dir)) continue;
-    for (const f of fs.readdirSync(dir)) {
+
+    // A directory that cannot be LISTED is a directory that cannot be scanned. This used to throw
+    // out of the scanner and abort the whole `generate`/`delivery` run; report it in the same place
+    // a hit would appear instead, so the operator learns what the clean verdict does not cover
+    // rather than losing the deliverable to an unrelated permission fault.
+    let entries: string[];
+    try { entries = fs.readdirSync(dir); } catch (e) { unscanned.push({ file: sub, reason: why(e) }); continue; }
+
+    for (const f of entries) {
       if (!/\.ya?ml$/i.test(f)) continue;
       const p = path.join(dir, f);
-      try { hits.push(...scanText(fs.readFileSync(p, 'utf-8'), path.join(sub, f))); } catch { /* ignore */ }
+      const rel = path.join(sub, f);
+      let text: string;
+      // `readdirSync` listed this file, so it exists as a name. A read that fails here means a
+      // restricted mount, a dangling symlink, or a file removed between the two calls — never
+      // "there was nothing to read". Silently skipping it let a committed credential ship under an
+      // explicit "clean" verdict.
+      try { text = fs.readFileSync(p, 'utf-8'); } catch (e) { unscanned.push({ file: rel, reason: why(e) }); continue; }
+      hits.push(...scanText(text, rel));
     }
   }
-  return hits;
+  return { hits, unscanned };
+}
+
+/**
+ * The operator-facing lines for a scan result — one renderer, because `generate` and `delivery`
+ * had grown two copies of it and only one of them would have learned about `unscanned`.
+ *
+ * Empty array when there is nothing to say. The unscanned block is NOT folded into the hit block:
+ * "possible secret" and "not examined" are different claims, and printing the second under the
+ * first's heading invites it to be dismissed as another false positive.
+ */
+export function formatSecretScan(result: SecretScanResult, limit = 10): string[] {
+  const out: string[] = [];
+  if (result.hits.length) {
+    out.push('', '⚠️  Possible secret(s) in committed test-data (review — do NOT commit real credentials):');
+    for (const h of result.hits.slice(0, limit)) out.push(`   ${h.file}:${h.line} — ${h.reason}`);
+    if (result.hits.length > limit) out.push(`   … and ${result.hits.length - limit} more`);
+    out.push('   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.');
+  }
+  if (result.unscanned.length) {
+    out.push('', `⚠️  Secret scan could NOT read ${result.unscanned.length} committed yaml file(s) — they are NOT covered by the result above:`);
+    for (const u of result.unscanned.slice(0, limit)) out.push(`   ${u.file} — ${u.reason}`);
+    if (result.unscanned.length > limit) out.push(`   … and ${result.unscanned.length - limit} more`);
+    out.push('   Make them readable and re-run before treating this unit as scanned.');
+  }
+  return out;
 }

package/src/harness/sensors.ts

@@ -11,6 +11,7 @@ import * as path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { ScenarioInfo, ViewpointEntry, idPrefix } from './parse';
 import { readTextFile } from './read-text';
+import { keywordHit, hasKeyword } from './keyword-match';
 
 // Business-critical category keywords (matched by CONTAINMENT against the VP category, so a
 // compound category like LIST-DISPLAY / ADD-TO-CART / PRODUCT-DISCOVERY classifies correctly).
@@ -86,18 +87,11 @@ export function loadCatalog(): Catalog {
   return parseYaml(readTextFile(p)) as Catalog;
 }
 
-// Word-aware keyword match: `\b<kw>(s|es|ed|ing)?\b`, so a keyword matches whole words (plus
-// simple plural/verb suffixes) but NOT as a substring of a larger word — e.g. `form` must not
-// match inside `Format` or `@platform`, while `product` still matches `products`. Multi-word
-// keywords ("add to cart", "is hidden") match the phrase with a boundary at each end.
-const wordRe = (kw: string) => {
-  const esc = kw.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  return new RegExp(`\\b${esc}(?:s|es|ed|ing)?\\b`);
-};
-const has = (haystacks: string[], kw: string) => {
-  const re = wordRe(kw);
-  return haystacks.some((h) => re.test(h));
-};
+// Word-aware keyword match — one rule for every sensor, in ./keyword-match (#776). A keyword
+// matches at a word START but may carry any suffix, so `form` does not match inside `Format` or
+// `@platform` while `submit` still matches `submitted`. The old local copy anchored BOTH ends,
+// which silently dropped every inflected true positive; see that module for the measurements.
+const has = hasKeyword;
 
 // ---------- Sensor 1: Viewpoint Gate (catalog-driven) ----------
 
@@ -112,6 +106,13 @@ export interface GateResult {
   coverageRatio: number;
   gaps: { theme: string; keywords: string[]; status: 'missing' | 'shallow' }[];
   universalGaps: string[];
+  /**
+   * WHICH scenario covered each satisfied theme, and on which keyword — the audit's second line of
+   * defence against a bogus coverage claim (#776). A bare count ("themes 3/3") gives a reviewer
+   * nothing to check, so a nonsense match survives; naming the evidence makes it obvious on sight.
+   * Mirrors how the Claim-Proof section already names the scenario behind each claim.
+   */
+  coveredBy: { theme: string; by: string; keyword: string }[];
 }
 
 /**
@@ -166,20 +167,36 @@ export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEn
 
   const evidence = { hits: best, runnerUp };
   const gaps: GateResult['gaps'] = [];
+  const coveredBy: GateResult['coveredBy'] = [];
   let total = 0, covered = 0;
   if (pageType) {
     for (const t of catalog.page_types[pageType].must_cover) {
       total++;
       // Scenarios that cover this theme by keyword (include @manual — a manual
       // scenario with a real assertion still covers the viewpoint for design).
-      const coverers = scenarios.filter((s) => t.keywords.some((k) => s.haystack.includes(k.toLowerCase())));
+      // Word-aware since #776: a substring match let `information` satisfy `format-boundary`.
+      const coverers = scenarios.filter((s) => t.keywords.some((k) => keywordHit(s.haystack, k)));
       if (coverers.length === 0) { gaps.push({ theme: t.theme, keywords: t.keywords, status: 'missing' }); continue; }
       // A theme WITHOUT `depth:` is visibility/navigation — landing/seeing/leaving IS the
       // assertion, so mere presence covers it. Only DATA-correctness themes (depth.requires:
       // data-assertion) need a data assertion to count as deeply covered.
       const needsDepth = t.depth?.requires === 'data-assertion';
-      if (!needsDepth) { covered++; continue; }
-      if (coverers.some((s) => s.hasDataAssertion)) covered++;
+      // Name the evidence for whichever scenario actually carries the theme — the one with the
+      // data assertion when depth is required, since that is the scenario the credit rests on.
+      const proof = (needsDepth ? coverers.find((s) => s.hasDataAssertion) : undefined) ?? coverers[0];
+      const credit = (): void => {
+        covered++;
+        coveredBy.push({
+          theme: t.theme,
+          by: proof.haystack,
+          // `proof` came out of `coverers`, which was filtered on this same predicate, so the find
+          // always lands — the `!` states that rather than inventing a fallback keyword that would
+          // misattribute the credit if the invariant ever broke.
+          keyword: t.keywords.find((k) => keywordHit(proof.haystack, k))!,
+        });
+      };
+      if (!needsDepth) { credit(); continue; }
+      if (coverers.some((s) => s.hasDataAssertion)) credit();
       else gaps.push({ theme: t.theme, keywords: t.keywords, status: 'shallow' });
     }
   }
@@ -203,6 +220,7 @@ export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEn
     coverageRatio: total ? covered / total : 1,
     gaps,
     universalGaps,
+    coveredBy,
   };
 }
 
@@ -269,7 +287,7 @@ export function assertionDepth(
   const isDismissBehavior = (s: ScenarioInfo) =>
     /\bis hidden\b|\bare hidden\b|\bdismiss|\bdisappear|\bno longer (visible|shown|present|displayed)\b|\bcloses? the (modal|dialog|popup|overlay|panel|menu)\b/.test(s.haystack);
   const isDepthRequired = (s: ScenarioInfo) =>
-    s.category !== 'NAV' && !isDismissBehavior(s) && depthKeywords.some((k) => s.haystack.includes(k.toLowerCase()));
+    s.category !== 'NAV' && !isDismissBehavior(s) && depthKeywords.some((k) => keywordHit(s.haystack, k));
 
   const required = nonManual.filter(isDepthRequired);
   const reqShallow = required.filter((s) => s.shallow);
@@ -347,7 +365,7 @@ export function flowCoveredThemes(
 ): { theme: string; flow: string }[] {
   const out: { theme: string; flow: string }[] = [];
   for (const g of gaps) {
-    const hit = flowScenarios.find((s) => s.deep && g.keywords.some((k) => s.haystack.includes(k.toLowerCase())));
+    const hit = flowScenarios.find((s) => s.deep && g.keywords.some((k) => keywordHit(s.haystack, k)));
     if (hit) out.push({ theme: g.theme, flow: hit.flow });
   }
   return out;
@@ -394,7 +412,8 @@ export function flowRegressionDepth(scenarios: ScenarioInfo[]): FlowDepthResult
 export interface OracleStrengthResult {
   weak: { name: string; hint: string; code?: string }[];   // facet-by-name-substring, or URL-only (code ORACLE-URL-ONLY)
   facetClaims: number;                       // scenarios that touch a category/brand facet (denominator)
-  ratio: number;                             // 1 - weak/facetClaims (1 when none) — caps businessDepth
+  weakFacet: number;                         // the facet-class subset of `weak` — the only numerator `facetClaims` denominates
+  ratio: number;                             // 1 - weakFacet/facetClaims, clamped 0..1 (1 when no facet claim) — caps businessDepth
 }
 
 // "see all [<item name/title>] ... contain(s) {{<facet>.term}}" — asserting every item's NAME carries
@@ -429,9 +448,11 @@ export function oracleStrength(scenarios: ScenarioInfo[]): OracleStrengthResult
       hint: `every \`Then\` is a URL assertion${guardLike ? ' on a permission / guard scenario' : ''} — it proves the router pushed a path, not that the page rendered for this user${guardLike ? ', and this is exactly the scenario a late 403 redirect turns falsely green' : ''}. Give the page selector an \`anchor:\` (a heading/landmark only the rendered page has) — one line per screen, and every \`see [X] page\` on it becomes a content oracle — or add a content assertion after it.`,
     });
   }
+  let weakFacet = 0;
   for (const s of scenarios) {
     if (s.manual) continue; // a @manual facet check is a deliberate deferral, not a weak automated oracle
     if (WEAK_FACET_ORACLE.test(s.stepsText)) {
+      weakFacet++;
       weak.push({
         name: s.name.slice(0, 80),
         hint: 'asserting every item NAME contains a category/brand term does not prove facet membership — assert the results-page TITLE/header carries the facet, a detail-page facet field, or an API/DB oracle; or defer the exhaustive check to @manual:M2.',
@@ -439,7 +460,17 @@ export function oracleStrength(scenarios: ScenarioInfo[]): OracleStrengthResult
     }
   }
   const facetClaims = scenarios.filter((s) => FACET_REF.test(s.stepsText) || FACET_REF.test(s.name)).length;
-  return { weak, facetClaims, ratio: facetClaims ? 1 - weak.length / Math.max(1, facetClaims) : 1 };
+  // Only the FACET class is denominated by `facetClaims`. `weak` also carries ORACLE-URL-ONLY
+  // findings (#662), which make no category/brand claim at all — averaging them into this axis
+  // drove `ratio` negative (5 URL-only over 2 facet claims → 1 - 5/2 = -1.5), which walked through
+  // the businessDepth floor and took the CLI's bar renderer down with it (#762). A URL-only oracle
+  // is NAMED as a finding and holds the score out of the senior band (`seniorBandedOverall`);
+  // it is not averaged into the facet axis — the invariant `url-only-oracle.run.ts` asserts.
+  // The clamp is not belt-and-braces: a weak-facet scenario need not itself satisfy FACET_REF
+  // (`see all [name] contains {{price.term}}` is weak but claims no facet), so `weakFacet` can
+  // still outrun `facetClaims`. This axis is declared 0..1; it leaves here inside 0..1.
+  const ratio = facetClaims ? Math.max(0, Math.min(1, 1 - weakFacet / facetClaims)) : 1;
+  return { weak, facetClaims, weakFacet, ratio };
 }
 
 /** Collect data-correctness themes (depth.requires) for a page-type + universal. */