@sun-asterisk/sungen 3.2.32 → 3.2.33

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

package/src/harness/spec-branches.ts

@@ -16,6 +16,7 @@
  * explicit — a named heading, a table that declares conditions and outcomes, or an if/else
  * cascade — because a false "you missed a branch" costs more trust than it buys coverage.
  */
+import { keywordHit } from './keyword-match';
 import { ScenarioInfo } from './parse';
 
 export interface SpecBranch {
@@ -172,7 +173,9 @@ export function unenumeratedBranches(branches: SpecBranch[], featureText: string
     const words = [...new Set((b.label.toLowerCase().match(/[a-z][a-z-]{3,}/g) ?? []))]
       .filter((w) => !GENERIC_WORD.has(w));
     if (words.length === 0) return !hay.includes(b.label.toLowerCase());
-    const hits = words.filter((w) => hay.includes(w)).length;
+    // Word-aware (#779): `in·active` and `check·list` are not mentions of `active` and `list`,
+    // and two of them credited a branch no scenario cites.
+    const hits = words.filter((w) => keywordHit(hay, w)).length;
     return hits < Math.min(2, words.length);
   });
 }
@@ -289,7 +292,7 @@ export function visibilityPairGaps(scenarios: ScenarioInfo[]): VisibilityPairGap
     const subject = distinctive(s);
     // The counterpart has to be about the SAME thing — two shared distinctive words, the same
     // bar the ledger's prose matching uses.
-    const paired = allows.some((a) => subject.filter((w) => a.haystack.includes(w)).length >= Math.min(2, subject.length));
+    const paired = allows.some((a) => subject.filter((w) => keywordHit(a.haystack, w)).length >= Math.min(2, subject.length));
     if (!paired) out.push({ scenario: s.name, subject: subject.slice(0, 4), kind: 'permission' });
   }
   return out;

package/src/harness/spec-coverage.ts

@@ -9,6 +9,7 @@
  * Generic: no project data.
  */
 import * as fs from 'fs';
+import { keywordHit } from './keyword-match';
 import { ScenarioInfo } from './parse';
 import { readTextFile } from './read-text';
 
@@ -139,7 +140,11 @@ function directionCovered(block: string, dir: FrDirection, subject: string[]): b
   const pool = lines.length ? lines : [block];
   // Narrow to the lines about the clause's element when the suite names it the same way the spec
   // does; a spec in one language and selector keys in another must not read as "no evidence".
-  const about = subject.length ? pool.filter((l) => subject.some((x) => l.includes(x))) : [];
+  // Word-aware (#779), or the narrowing lets in a line about something else and then trusts it:
+  // `under·score` is not a mention of `Score`, but it selected the only absence assertion in the
+  // block and so proved a MUST NOT clause about the Score. (`keywordHit` keeps substring semantics
+  // for a non-ASCII element name, which is what the cross-language case above depends on.)
+  const about = subject.length ? pool.filter((l) => subject.some((x) => keywordHit(l, x))) : [];
   const scan = about.length ? about : pool;
   return scan.some((l) => NEGATIVE_ASSERTION.test(l) === (dir.polarity === 'negate'));
 }
@@ -269,7 +274,12 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
     const cited = featLower.includes(idLower) || cites.has(fr.id.toUpperCase());
     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));
+    // Word-aware, not substring (#779). `haystack.includes('format')` is satisfied by
+    // in·format·ion and `includes('length')` by wave·length, and two such collisions clear the
+    // `>= 2 words` bar as easily as one — so a MUST clause nobody tested read as covered. The
+    // threshold is a separate judgement (is one word enough evidence?) and is unchanged; see
+    // keyword-match.ts for why the boundary is leading-only.
+    const kwHit = words.length > 0 && scenarios.some((s) => words.filter((w) => keywordHit(s.haystack, w)).length >= Math.min(2, words.length));
     if (!cited && !kwHit) {
       if (fr.modality === 'MUST') uncoveredMust.push({ id: fr.id, text: fr.text.slice(0, 90) });
       continue;
@@ -279,7 +289,7 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
     // Which scenarios speak for this requirement — by its id (tags and comments sit in the block)
     // or by the same keyword rule used above.
     const owning = blocks.filter((b) => b.includes(idLower)
-      || (words.length > 0 && words.filter((w) => b.includes(w)).length >= Math.min(2, words.length)));
+      || (words.length > 0 && words.filter((w) => keywordHit(b, w)).length >= Math.min(2, words.length)));
     // Cited from outside any scenario (a header comment): nothing to judge a direction against, so
     // report nothing rather than invent a gap.
     if (!owning.length) { frCovered += units; continue; }
@@ -299,7 +309,7 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
     // 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)),
+      (row.code && b.includes(row.code.toLowerCase())) || kw.some((w) => keywordHit(b, 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)))];

package/src/harness/viewpoint-ledger.ts

@@ -11,6 +11,7 @@
 import * as fs from 'fs';
 import { ScenarioInfo } from './parse';
 import { readTextFile } from './read-text';
+import { keywordHit } from './keyword-match';
 
 export interface LedgerItem { id?: string; text: string; covered: boolean }
 
@@ -198,7 +199,7 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
     } 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);
+      isCovered = words.length > 0 && scenarios.some((s) => words.filter((w) => keywordHit(s.haystack, w)).length >= need);
     }
     if (isCovered) covered++;
     else missing.push({ id: item.id, text: item.text });

package/src/harness/write-atomic.ts

@@ -0,0 +1,22 @@
+/**
+ * Write a file so that a crash mid-write can never leave a truncated one behind: write a sibling
+ * tmp, then rename. Same directory = same device, so the rename is atomic; a concurrent writer is
+ * last-rename-wins. On failure the tmp is removed and the error rethrown — the caller still learns.
+ *
+ * `results merge` and `results sanitize` each grew this block inline, for the same reason and with
+ * the same comment. The third caller (`ai-skills/writer.ts`) did not, and its truncated manifest is
+ * precisely the corrupt input that #782's readers then absorbed in silence — so the two halves of
+ * that defect are one file apart.
+ */
+import * as fs from 'fs';
+
+export function writeFileAtomic(file: string, data: string): void {
+  const tmp = `${file}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort cleanup — the real error is below */ }
+    throw err;
+  }
+}

package/src/orchestrator/ai-skills/writer.ts

@@ -16,6 +16,8 @@ import * as path from 'path';
 import * as crypto from 'crypto';
 import { BuiltFile } from './build';
 import { AdapterKey } from './adapters';
+import { readJsonConfig, warnUnreadableConfig } from '../../harness/config-file';
+import { writeFileAtomic } from '../../harness/write-atomic';
 
 export interface ApplyOptions { force?: boolean; dryRun?: boolean; version: string }
 export interface ApplyReport {
@@ -42,10 +44,21 @@ function adapterOf(relPath: string): AdapterKey | null {
   return null;
 }
 
+/**
+ * The manifest is what makes orphan cleanup possible: it is the only record of which files a
+ * PREVIOUS version managed. An unreadable one used to read as an empty one — so cleanup found
+ * nothing to remove, and the stale files it failed to remove are absent from the NEW manifest too.
+ * No later run can ever find them again. Say it, then carry on with what can still be done.
+ */
 function readManifest(cwd: string): Manifest {
   const p = path.join(cwd, MANIFEST_REL);
-  if (!fs.existsSync(p)) return { version: '', managed: {} };
-  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return { version: '', managed: {} }; }
+  const read = readJsonConfig<Manifest>(p);
+  if (read.state === 'unreadable') {
+    warnUnreadableConfig(p, read.error,
+      'orphan cleanup is skipped this run, so files managed by an older version stay in place');
+    return { version: '', managed: {} };
+  }
+  return read.state === 'ok' ? read.value : { version: '', managed: {} };
 }
 
 export function applyOutputs(cwd: string, outputs: BuiltFile[], opts: ApplyOptions): ApplyReport {
@@ -121,7 +134,9 @@ export function applyOutputs(cwd: string, outputs: BuiltFile[], opts: ApplyOptio
     Object.assign(mergedManaged, newManaged);
     const mPath = path.join(cwd, MANIFEST_REL);
     fs.mkdirSync(path.dirname(mPath), { recursive: true });
-    fs.writeFileSync(mPath, JSON.stringify({ version: opts.version, managed: mergedManaged }, null, 2));
+    // Atomic: an interrupted `sungen init`/`update` must not leave a half-written manifest, because
+    // the reader above can only report that damage — it cannot undo it.
+    writeFileAtomic(mPath, JSON.stringify({ version: opts.version, managed: mergedManaged }, null, 2));
   }
   return r;
 }