@sun-asterisk/sungen 3.2.32 → 3.2.34

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,8 +5,10 @@
  */
 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 { commentLinesOf, isPresencePlaceholderHybrid, keywordStepsOf } from '../exporters/manual-hybrid-oracle';
 import { readTextFile } from './read-text';
 
 // ---------- #2 Downstream-scope ----------
@@ -57,12 +59,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 +158,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
@@ -208,14 +221,15 @@ export function manualOracle(featureText: string): ManualOracleResult {
     //    Observable:/Oracle:/Expected: line (parseManualComments — the SAME parser the
     //    delivery exporter uses, so this gate can't drift from the exported cells).
     //    Prose paragraphs / rationale-only comments export EMPTY Steps + Expected.
+    //  • HAS a Then whose every assertion is a bare presence placeholder, with the real oracle
+    //    in the comments (#810) — the same hybrid wearing a Then (manual-hybrid-oracle.ts, the
+    //    SAME predicate as compile-time SG-W008).
     const hasGherkinSteps = /^\s*(Given|When|Then)\s/m.test(b);
+    const commentLines = commentLinesOf(b);
     let bad: boolean;
     if (hasGherkinSteps) {
-      bad = !/^\s*Then\s/m.test(b);
+      bad = !/^\s*Then\s/m.test(b) || isPresencePlaceholderHybrid(keywordStepsOf(b), commentLines);
     } else {
-      const commentLines = b.split('\n')
-        .filter((l) => /^\s*#/.test(l))
-        .map((l) => l.replace(/^\s*#\s?/, ''));
       const parsed = parseManualComments(commentLines);
       bad = !parsed.steps.length || !parsed.expected.length;
     }

package/src/harness/read-text.ts

@@ -17,12 +17,43 @@ 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. */
 export function readTextLines(filePath: string): string[] {
   return readTextFile(filePath).split('\n');
 }
+
+/**
+ * Drop HTML comments (`<!-- … -->`, multi-line too) — they are author notes and scaffold samples,
+ * never content. Newlines inside a comment are kept so every later line keeps its position (#841).
+ *
+ * Only a CLOSED comment is dropped. An unclosed `<!--` (a forgotten `-->`) stays text: dropping it
+ * to the end of the file would silently delete every declaration below it. A fenced code block is
+ * content, and so is a `<!--` written inside backticks: both are how a document SHOWS the syntax.
+ */
+export function stripHtmlComments(text: string): string {
+  // A comment body never holds another `<!--`: an opener with no `-->` before the next opener is
+  // the unclosed one, and must not reach a LATER comment's closer and eat everything between.
+  const blank = (s: string): string => s.replace(/(?<!`)<!--(?:(?!<!--)[\s\S])*?-->/g, (m) => m.replace(/[^\n]/g, ''));
+  // split() with a capture group keeps the fences at the odd indexes.
+  return text.split(/(^```[^\n]*\n[\s\S]*?^```[^\n]*$)/m).map((part, i) => (i % 2 ? part : blank(part))).join('');
+}
+
+/**
+ * `test-viewpoint.md` as every harness sensor must read it: normalised, comments removed, and
+ * '' when the unit has none. `sungen add` scaffolds its samples inside `<!-- -->`; read raw, an
+ * untouched scaffold declared VP-UI/VP-VAL/VP-LOGIC/VP-SEC and carried 12 phantom claims (#841).
+ */
+export function readViewpointText(filePath: string): string {
+  return fs.existsSync(filePath) ? stripHtmlComments(readTextFile(filePath)) : '';
+}

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/select-by-ids.ts

@@ -0,0 +1,83 @@
+/**
+ * Select scenarios by test-case ID — backs `sungen select` and `run-test --ids` (#835).
+ *
+ * An ID means what it means everywhere else in the harness: `vpId`, the leading ID token of the
+ * scenario title (`VP-UI-001`, `MS-HP-001`, `VP0-001`). Matching is exact and case-insensitive —
+ * `VP-UI-001` never selects `VP-UI-0010` or `VP-UI-001-B` — and every ID that selects nothing
+ * runnable is reported, because the alternative is a 0-test run that reports green.
+ */
+import * as path from 'path';
+import { ScenarioInfo } from './parse';
+
+/**
+ * Escape scenario titles into one `-g` / `--mochaOpts.grep` regex. Full titles, not bare IDs:
+ * a title starts with its own ID, so it can only appear inside its own test's title — and a
+ * `@cases` row test (`<title> — <row label>`) still contains it.
+ */
+export function titlesToGrep(titles: string[]): string {
+  return titles.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+}
+
+export interface IdSelectionGroup {
+  /** Feature basename (`products`, `home-modal`) — names the spec and the result file. */
+  feature: string;
+  ids: string[];
+  titles: string[];
+  grep: string;
+}
+
+export interface IdSelection {
+  features: IdSelectionGroup[];
+  /** IDs no scenario carries, with near matches (`VP-VAL-001` → `VP-VAL-001-B`). */
+  unknown: Array<{ id: string; didYouMean: string[] }>;
+  /** IDs whose every scenario is manual, owned by a flow or waiting on a capability — nothing to run. */
+  notRunnable: Array<{ id: string; reason: string }>;
+}
+
+/** `"VP-UI-001, vp-ui-002 VP-UI-001"` → `['VP-UI-001', 'VP-UI-002']`. */
+export function parseIdList(raw: string): string[] {
+  return [...new Set(raw.split(/[\s,]+/).map((s) => s.trim().toUpperCase()).filter(Boolean))];
+}
+
+/** `VP-C-002.` → `VP-C-002`: the title token may carry trailing punctuation the user never types. */
+const idOf = (s: ScenarioInfo): string | undefined => s.vpId?.replace(/[.-]+$/, '') || undefined;
+
+function notRunnableReason(s: ScenarioInfo, enabledCaps: Set<string>): string | null {
+  if (s.deferredToFlow) return `owned by a flow${s.ownedByFlow ? ` (${s.ownedByFlow})` : ''} — run it there`;
+  if (s.featureManual) return 'its Feature is @manual — no spec is generated for it';
+  if (s.manual) return 'manual — no automated test exists';
+  // Compiled as `test.skip` while the capability is off: the run would report a skip, not a result.
+  const missing = (s.requiresCaps ?? []).filter((c) => !enabledCaps.has(c));
+  if (missing.length) return `needs capability ${missing.join(', ')} — compiled as a skip until \`sungen capability add ${missing.join(' ')}\``;
+  return null;
+}
+
+export function selectByIds(scenarios: ScenarioInfo[], ids: string[], unit: string, enabledCaps: Set<string> = new Set()): IdSelection {
+  const out: IdSelection = { features: [], unknown: [], notRunnable: [] };
+  const groups = new Map<string, IdSelectionGroup>();
+  const allIds = [...new Set(scenarios.map(idOf).filter((v): v is string => !!v))];
+
+  for (const id of ids) {
+    const hits = scenarios.filter((s) => idOf(s) === id);
+    if (hits.length === 0) {
+      const didYouMean = allIds.filter((v) => v.startsWith(`${id}-`) || id.startsWith(`${v}-`)).slice(0, 5);
+      out.unknown.push({ id, didYouMean });
+      continue;
+    }
+    const runnable = hits.filter((s) => !notRunnableReason(s, enabledCaps));
+    if (runnable.length === 0) {
+      out.notRunnable.push({ id, reason: notRunnableReason(hits[0], enabledCaps)! });
+      continue;
+    }
+    for (const s of runnable) {
+      const feature = s.sourceFile ? path.basename(s.sourceFile, '.feature') : unit;
+      const g = groups.get(feature) ?? { feature, ids: [], titles: [], grep: '' };
+      if (!g.ids.includes(id)) g.ids.push(id);
+      if (!g.titles.includes(s.name)) g.titles.push(s.name);
+      groups.set(feature, g);
+    }
+  }
+  for (const g of groups.values()) g.grep = titlesToGrep(g.titles);
+  out.features = [...groups.values()];
+  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. */
@@ -603,6 +634,9 @@ export interface TraceResult {
   mappedToOverview: number;
   withVpCodeRatio: number;
   mappedRatio: number;
+  /** Viewpoint IDs read from test-viewpoint.md. 0 = nothing to map to, so `mappedRatio` is not a
+   *  measurement — the scenario IDs were never checked (#832). */
+  overviewIds: number;
   note: string;
 }
 
@@ -614,6 +648,24 @@ export interface TraceResult {
  */
 const unprefixed = (id: string): string => id.replace(/^(?:VP|FL)-/i, '').toUpperCase();
 
+/**
+ * The traceability note, worded from the SAME ratio the audit's TRACE finding fires on —
+ * mapped / ALL scenarios (#852). It used to compare mapped against scenarios WITH an id, so 0 of
+ * 0 (no scenario yet, or none tagged) and 2 of 2 tagged out of 10 all read "Traceable." while
+ * the audit reported `TRACE: Traceable.` for a 0–20% mapping.
+ */
+function traceNote(total: number, withCode: number, mapped: number, declared: number, exampleId?: string): string {
+  if (declared === 0) {
+    return 'No viewpoint ID found in test-viewpoint.md — the file is missing, or none of its sections declares one — so the scenario IDs were not checked. Declarations are read from a `## Priority Viewpoints` table, `### Required / Recommended / Optional` lists, and tables whose first column is a `VP-`/`FL-` ID or an ID of a family declared there (Known Issues / Traceability / References sections are skipped).';
+  }
+  if (total === 0) return 'No scenarios yet — traceability is measured once the feature has scenarios.';
+  if (mapped >= total * 0.5) return 'Traceable.';
+  const example = exampleId ? ` (e.g. \`${exampleId}-001 …\`)` : '';
+  if (withCode === 0) return `No scenario carries a viewpoint ID — start each title with one of the IDs declared in test-viewpoint.md${example}.`;
+  if (mapped < withCode * 0.5) return 'Scenario IDs do not match the viewpoint-overview ids (weak traceability — re-tag to the project viewpoint IDs).';
+  return `Only ${mapped} of ${total} scenarios carry a declared viewpoint ID — ${total - withCode} have no ID at all; tag them with the project's IDs${example}.`;
+}
+
 export function traceability(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[]): TraceResult {
   const overviewIds = new Set(viewpoints.map((v) => v.id.toUpperCase()));
   const overviewBare = new Set(viewpoints.map((v) => unprefixed(v.id)));
@@ -638,9 +690,10 @@ export function traceability(scenarios: ScenarioInfo[], viewpoints: ViewpointEnt
     mappedToOverview: mapped.length,
     withVpCodeRatio: scenarios.length ? withCode.length / scenarios.length : 0,
     mappedRatio: scenarios.length ? mapped.length / scenarios.length : 0,
-    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.',
+    overviewIds: overviewIds.size,
+    // With no ID read there is nothing to match against: telling the author to re-tag sends them
+    // to change scenarios that may be right (#832). Name the file and the sections read instead.
+    note: traceNote(scenarios.length, withCode.length, mapped.length, overviewIds.size, viewpoints[0]?.id),
   };
 }
 
@@ -702,6 +755,31 @@ const CLAIM_RULES: ClaimRule[] = [
     hint: 'swap `contains {{v}}` for `with {{v}}` on the continuity rows. A substring match cannot distinguish "unchanged" from "changed by adding a prefix" — and if the screen genuinely renders extra text around the value, say so in the title instead of claiming exactness.',
     severity: 'warn',
   },
+  {
+    // An ORDER claim ("sorted by date descending", "ties broken by last-updated") is invisible to
+    // a presence check: `see [List] table` passes whatever order the rows are in. It sits ahead of
+    // the generic rules so "all results sorted …" is judged as an ordering claim, not an all-claim.
+    // A tiebreaker is a Tier-1 guard in the tc-generation skill, yet no rule recognised it (#810).
+    claim: 'ordering/sort',
+    title: /\b(ascending|descending|sorted|sorts|sort order|ordered by|order by|in (?:chronological|alphabetical|reverse|numeric) order|(?:newest|oldest|latest|earliest|highest|lowest) first|tie-?break(?:s|er|ers)?|ties?)\b|降順|昇順|並び順|giảm dần|tăng dần|sắp xếp/,
+    proof: /match data|is sorted|sorted (?:ascending|descending)|\brow \d+\b|\.first\.|\.last\.|\[\d+\]\.|order by/,
+    need: 'an order-sensitive assertion (`table match data:` rows in the expected order, `is sorted ascending|descending`, or positional `row N` checks)',
+    hint: 'a presence check passes in any order — assert the rows in their expected sequence (`User see [T] table match data:`), or the column sort state; a tiebreak needs two rows sharing the primary key.',
+    severity: 'fail',
+  },
+  {
+    // A LIMIT claim ("never exceeds 10", "at most 5 files") is a count claim in disguise.
+    // Ahead of 'no-side-effect', whose negation+effect pattern would otherwise swallow
+    // "never exceeds 10 records" and ask for a duplicate-count proof.
+    claim: 'limit/cap',
+    // The quantity must be ≥2 ("at most ONE order" is a no-duplicate claim — left to the rules
+    // below) and not a duration ("up to 30 seconds" is a timing claim, not a cap).
+    title: /\b(?:never exceeds?|(?:does not|doesn['’]t|not) exceed|at most|no more than|up to|capped at|caps? at|maximum of|max(?:imum)?)\s+(?:\d{2,}|[2-9]|two|three|four|five|six|seven|eight|nine|ten)\b(?!\s*(?:ms|milliseconds?|s|secs?|seconds?|mins?|minutes?|hours?|days?)\b)|\b(?:never exceeds?|(?:does not|doesn['’]t) exceed) (?:the )?(?:limit|cap|quota|maximum)\b|以内|上限|tối đa/,
+    proof: /\bcount\b|tohavecount|table with|row with \{\{|match data|is at most|\bexactly\b|field with \{\{|\berror\b|invalid|is disabled/,
+    need: 'a count/boundary assertion (count is N, `is at most`, the N+1th input rejected or truncated)',
+    hint: 'assert the boundary itself — the count at the cap, or the value/error when one more is attempted — not just that the list or field is present.',
+    severity: 'fail',
+  },
   {
     claim: 'all/every/each',
     title: /\b(all|every|each)\b/,
@@ -994,14 +1072,16 @@ export function numericClaimGaps(scenarios: ScenarioInfo[]): Array<{ name: strin
  * The Priority-Viewpoints table is where release selection is supposed to come from. When the
  * table says a flow is `Low` and its scenario is tagged `@high`, a smoke run picks up work the QA
  * deliberately deprioritised — and nobody can tell which of the two was the decision (#622).
+ *
+ * Reads the SAME parse traceability does (`parseViewpointOverview`). It used to scan the raw text
+ * for any `| VP-… | high |` row, so one audit run "saw" an id for this check and not for
+ * traceability (#833), and a row in a Known Issues table could raise a contradiction.
  */
 export function priorityMismatches(
-  viewpointText: string, scenarios: ScenarioInfo[],
+  viewpoints: ViewpointEntry[], scenarios: ScenarioInfo[],
 ): Array<{ id: string; declared: string; tagged: string; scenario: string }> {
   const declared = new Map<string, string>();
-  for (const m of viewpointText.matchAll(/^\|\s*((?:VP|FL)[A-Z0-9._-]*)\s*\|\s*(critical|high|medium|normal|low|deferred)\s*\|/gim)) {
-    declared.set(m[1].toUpperCase(), m[2].toLowerCase());
-  }
+  for (const v of viewpoints) if (v.priorityWord) declared.set(v.id.toUpperCase(), v.priorityWord);
   if (declared.size === 0) return [];
   // `medium` and `normal` are the same rank under different names in real documents.
   const rank = (p: string): string => (p === 'medium' ? 'normal' : p);
@@ -1014,8 +1094,9 @@ export function priorityMismatches(
     if (!key) continue;
     const want = rank(declared.get(key)!);
     const got = rank(String(s.priority).toLowerCase());
-    // `critical` and `deferred` have no tag equivalent — nothing to contradict.
-    if (want === 'critical' || want === 'deferred') continue;
+    // `critical`, `deferred` and `skip` (declared not applicable, #853) have no tag equivalent —
+    // nothing to contradict.
+    if (want === 'critical' || want === 'deferred' || want === 'skip') continue;
     if (want !== got) out.push({ id: key, declared: declared.get(key)!, tagged: got, scenario: s.name });
   }
   return out;

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);
   });
 }
@@ -191,7 +194,7 @@ export function sameOracleClusters(scenarios: ScenarioInfo[]): Array<{ oracle: s
     if (s.manual) continue;                     // a procedure's oracle is prose
     const asserts = [...(s.steps ?? [])]
       .filter((st) => st.bucket === 'then')
-      .map((st) => st.text.toLowerCase().replace(/\s+/g, ' ').trim())
+      .map((st) => `${st.text} ${st.arg ?? ''}`.toLowerCase().replace(/\s+/g, ' ').trim())   // the table is the oracle too (#817)
       .sort();
     if (asserts.length === 0) continue;
     const key = asserts.join(' ; ');
@@ -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;