@sun-asterisk/sungen 3.2.32 → 3.2.34-beta.1

package/src/harness/audit.ts

@@ -32,7 +32,11 @@ const MULTI_SCREEN_RISK_COUNT = MULTI_SCREEN_RISKS.length;
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { contextRouter } from '../capabilities/context-router';
-import { readTextFile } from './read-text';
+import { readTextFile, readViewpointText } from './read-text';
+import { isAiDraft } from './viewpoint-draft-header';
+import { viewpointReviewOpenFindings } from './viewpoint-review-open';
+import { uiInventoryCoverage, uiInventoryFindings, UiInventoryResult } from './ui-inventory';
+import { defectLinkFindings } from './defects';
 
 export interface AuditReport {
   screen: string;
@@ -57,6 +61,8 @@ export interface AuditReport {
   flowQuality?: FlowQualityResult;      // #569 — flow contract verification (flows only)
   /** #595 — coverage per DECLARED FLOW; absent when the contract declares no `flows:`. */
   flowInventory?: InventoryResult;
+  /** #811 — design items vs the suite; present only when the unit holds design sources. */
+  uiInventory?: UiInventoryResult;
   calibration: {                // #8 — multi-axis score so a high overall can't hide a weak axis
     axes: Record<string, number>;
     weakest: { axis: string; value: number };
@@ -185,6 +191,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const scoringCap = scoringCapId ? capabilityRegistry.get(scoringCapId) : undefined;
   const catalog = (scoringCap?.viewpoints?.() as Catalog | undefined) || loadCatalog();
   const spec = specCoverage(specPath, scenarios, featureText);
+  const uiInv = uiInventoryCoverage(path.join(screenDir, 'requirements'), featureText);
 
   // P3 — intent profile from qa/context.md drives the depth threshold (focus).
   const intent = readIntent(projectRootFromScreenDir(screenDir));
@@ -196,7 +203,10 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // Is the declaration this suite is measured against still the one a human accepted?
   const viewpointBaseline = checkViewpointBaseline(
     projectRootFromScreenDir(screenDir), catalogScreenName, viewpointPath);
-  const viewpointText = fs.existsSync(viewpointPath) ? readTextFile(viewpointPath) : '';
+  const viewpointText = readViewpointText(viewpointPath);
+  // `drafted-by: ai` — unreviewed until `--accept-viewpoint` removes it. Only a draft that declares ids
+  // has anything to accept; an id-less one is VIEWPOINT-MISSING's to report, not a dead-end finding.
+  const aiDraft = isAiDraft(viewpointText) && viewpointBaseline.status !== 'absent';
   // #569 — a flow WITH a contract is measured against ITS declaration, not a screen's.
   // Keyword page-type detection force-fit flows into screen checklists (a registration
   // flow judged as a `form` screen scored coverage 0%), so for contract-holding flows the
@@ -211,9 +221,13 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     ? { ...catalog, page_types: {} } as Catalog
     : catalog;
   const capGate = scoringCap?.gateProvider as
-    ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus; cwd: string; screenName: string; threshold: number; businessCriticalMethods?: string[] }) => { gate: GateResult; depth: DepthResult }) | undefined;
-  const provided = capGate?.({ scenarios, viewpoints, catalog: gateCatalog, focus: intent.focus, cwd: projectRootFromScreenDir(screenDir), screenName: catalogScreenName, threshold: depthThresholdFor(intent.focus), businessCriticalMethods: intent.businessCriticalMethods });
-  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, gateCatalog, platform === 'mobile', viewpointText);
+    ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus; cwd: string; screenName: string; threshold: number; businessCriticalMethods?: string[]; isMobile: boolean; viewpointText: string }) => { gate: GateResult; depth: DepthResult }) | undefined;
+  // The capability gate gets the SAME isMobile + viewpoint text as the in-core fallback, or a declared
+  // `page-type:` is ignored wherever driver-ui scores — every web project, and a mobile project whose
+  // CLI cannot resolve driver-mobile (#864).
+  const isMobile = platform === 'mobile';
+  const provided = capGate?.({ scenarios, viewpoints, catalog: gateCatalog, focus: intent.focus, cwd: projectRootFromScreenDir(screenDir), screenName: catalogScreenName, threshold: depthThresholdFor(intent.focus), businessCriticalMethods: intent.businessCriticalMethods, isMobile, viewpointText });
+  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, gateCatalog, isMobile, viewpointText);
   const depth = provided?.depth ?? assertionDepth(scenarios, dataThemesFor(gateCatalog, gate.pageType), intent.focus);
 
   // TQ-4 — deferral-aware coverage credit: an inherently cross-screen theme (cart / detail /
@@ -227,7 +241,12 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     if (flowScenarios.length) {
       for (const c of flowCoveredThemes(gate.gaps, flowScenarios)) {
         const i = gate.gaps.findIndex((g) => g.theme === c.theme);
-        if (i >= 0) { gate.gaps.splice(i, 1); gate.themesCovered++; flowCredits.push(c); }
+        if (i >= 0) {
+          gate.gaps.splice(i, 1); gate.themesCovered++; flowCredits.push(c);
+          // Keep the claim-proof list in step with the count (#776) — a theme credited to a flow
+          // must SAY it came from a flow, or the evidence lines silently under-report the total.
+          gate.coveredBy.push({ theme: c.theme, by: `(flow) ${c.flow}`, keyword: '—' });
+        }
       }
       gate.coverageRatio = gate.themesTotal ? gate.themesCovered / gate.themesTotal : 1;
     }
@@ -292,12 +311,16 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // #569 — handoff integrity: a flow's depth is also whether each cross-screen transition
   // is followed by an assertion on the carried state (same floor discipline as the other caps).
   const HANDOFF_FLOOR = 0.5;
-  const businessDepth = Math.min(
+  // Each FLOOR is a floor on the CAP, not on the result — an out-of-range input ratio walks
+  // straight through it (a -1.5 oracle ratio yielded businessDepth -0.25 and crashed the CLI's
+  // bar renderer, #762). The axis is declared `0..1` above and weighted `critical`, so a negative
+  // value would also drag `score.overall` below zero. Clamp once, here, where the axis is formed.
+  const businessDepth = Math.max(0, Math.min(1, Math.min(
     depth.bcDepthRatio,
     flowDepth.stateful ? FLOW_DEPTH_FLOOR + (1 - FLOW_DEPTH_FLOOR) * flowDepth.ratio : 1,
-    oracle.weak.length ? ORACLE_FLOOR + (1 - ORACLE_FLOOR) * oracle.ratio : 1,
+    oracle.weakFacet ? ORACLE_FLOOR + (1 - ORACLE_FLOOR) * oracle.ratio : 1,
     flowQ.hasContract && flowQ.handoffs.total > 0 ? HANDOFF_FLOOR + (1 - HANDOFF_FLOOR) * flowQ.handoffs.ratio : 1,
-  );
+  )));
   // When the taxonomy drifted (most scenarios unclassified), the balance axis is unreliable — cap it
   // at 0.5 instead of awarding a vacuous 1.0 so a stale taxonomy fails loudly, not silently (H1).
   const balanceScore = balance.unclassifiedRatio > 0.4
@@ -333,7 +356,8 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // so it can only measure what their author already thought of. One field run wrote the file
   // after generating the suite and said so in its own header — and both axes still read 100%,
   // because a first audit records the baseline silently (#622). Untrusted until a human accepts it.
-  const viewpointMoved = viewpointBaseline.status === 'changed' || adoptedPostHoc;
+  // An AI draft rides the same hold: its line is only removed when a human accepts it.
+  const viewpointMoved = viewpointBaseline.status === 'changed' || adoptedPostHoc || aiDraft;
   // #618 — is there a YARDSTICK at all? `atomicLedger` and `traceability` are both measured
   // against test-viewpoint.md, and four more sensors read it (the ledger, the declaration-integrity
   // checks, the browser-gesture check, the continuity check). When the file is absent every one of
@@ -364,7 +388,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     { key: 'atomicLedger', value: ledger.ratio, weight: 0.13, applicable: ledger.hasViewpoint && ledger.total > 0 && !viewpointMoved, critical: true, withheld: viewpointMoved && ledger.hasViewpoint && ledger.total > 0 },
     { key: 'businessDepth', value: businessDepth, weight: 0.20, applicable: true, critical: true },
     { key: 'claimProof', value: claim.ratio, weight: 0.15, applicable: claim.withClaims > 0, critical: true },
-    { key: 'traceability', value: traceScore, weight: 0.09, applicable: viewpoints.length > 0 && !viewpointMoved, critical: false, withheld: viewpointMoved && viewpoints.length > 0 },
+    { key: 'traceability', value: traceScore, weight: 0.09, applicable: viewpoints.length > 0 && scenarios.length > 0 && !viewpointMoved, critical: false, withheld: viewpointMoved && viewpoints.length > 0 && scenarios.length > 0 },
     // A use-case decomposition is EF-heavy by construction (1 basic flow, N alternates, N
     // exceptions) — that is the shape of a well-decomposed use case, not neglected business
     // core. `flowCoverage` already measures whether the journey's phases are covered, so
@@ -576,7 +600,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     findings.push(`COVERED-VIA-FLOW: critical theme "${c.theme}" is not covered on this screen but is deeply covered by flow "${c.flow}" — cross-screen depth correctly owned by the flow, so it is credited (not a screen gap). Verify with \`sungen flow-check\`.`);
   }
   // Verification-scope (advisory): API/DB verification the project's recorded test type never asked for.
-  for (const v of verificationScopeFindings(featureText, fs.existsSync(viewpointPath) ? readTextFile(viewpointPath) : '', capProfile)) {
+  for (const v of verificationScopeFindings(featureText, viewpointText, capProfile)) {
     findings.push(`VERIFICATION-OUT-OF-SCOPE (${v.layer}): this unit ${v.message}`);
   }
   for (const g of gate.gaps) {
@@ -594,19 +618,26 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       `add data assertions (\`... with {{value}}\`, \`see all ... contain {{v}}\`) or, if cross-screen, defer to a flow with @manual + reason.`,
     );
   }
-  // H5 — state isolation: a @parallel stateful flow that mutates the cart needs per-scenario
-  // isolation, else count/quantity asserts go flaky. Warn (advisory) when no mitigation is present
+  // H5 — state isolation: a stateful flow that mutates the cart needs per-scenario isolation, else
+  // count/quantity asserts go flaky. Warn (advisory) when no mitigation is present
   // (@cleanup:cart / @isolate / a "Given … empty cart" background / fresh context).
+  // #759 — scoped by the ABSENCE of @serial, not the presence of @parallel: parallel is the default.
   if (isoRisk) {
     const what = flowQ.contract?.stateful ?? 'cart';
-    findings.push(`ISOLATION-RISK: this @parallel flow mutates ${what} but has no per-scenario isolation → count/quantity/state asserts can go flaky when scenarios share it. Add \`@cleanup:${what}\` (or \`@isolate\`, a fresh context, or \`{{$timestamp}}\` data) so each scenario starts clean.`);
+    findings.push(`ISOLATION-RISK: this flow mutates ${what} but has no per-scenario isolation → count/quantity/state asserts can go flaky when scenarios share it. Add \`@cleanup:${what}\` (or \`@isolate\`, a fresh context, or \`{{$timestamp}}\` data) so each scenario starts clean.`);
   }
   // #414 — serial-cascade masking: an @serial suite of independent (re-navigating) scenarios hides
   // failures, because Playwright's describe.serial SKIPS everything after the first red. Isolation is
   // the default, so this only fires when @serial was added to a suite that didn't need it.
-  const cascadeN = serialCascadeRisk(featureText, scenarios.length);
-  if (cascadeN) {
-    findings.push(`SERIAL-CASCADE-RISK: this \`@serial\` suite has ${cascadeN} INDEPENDENT scenarios (each re-navigates via Background) that don't need a shared-page sequence. \`describe.serial\` SKIPS every test after the first failure → one early red MASKS the rest as never-run. **Drop \`@serial\`** — the default per-scenario isolation runs every scenario and isolates failures. Keep \`@serial\` only for a genuinely stateful ordered sequence (where scenario N depends on N-1's state).`);
+  // `@serial` is a property of ONE feature file — only that file compiles to `describe.serial` — so
+  // each file is judged on its own text and its own scenarios. The unit-wide text paired one
+  // feature's @serial with another's navigating Background and counted every scenario of the unit,
+  // telling QA to drop @serial from a genuinely ordered 2-scenario feature (#887).
+  for (const file of featureFiles.filter((f) => fs.existsSync(f))) {
+    const cascadeN = serialCascadeRisk(readTextFile(file), scenarios.filter((s) => s.sourceFile === file).length);
+    if (cascadeN) {
+      findings.push(`SERIAL-CASCADE-RISK: the \`@serial\` suite ${path.basename(file)} has ${cascadeN} INDEPENDENT scenarios (each re-navigates via Background) that don't need a shared-page sequence. \`describe.serial\` SKIPS every test after the first failure → one early red MASKS the rest as never-run. **Drop \`@serial\`** — the default per-scenario isolation runs every scenario and isolates failures. Keep \`@serial\` only for a genuinely stateful ordered sequence (where scenario N depends on N-1's state).`);
+    }
   }
   if (flowDepth.stateful && flowDepth.missing.length) {
     // The advice names the collection the CONTRACT declared. It used to say "the cart" whatever
@@ -633,12 +664,19 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   for (const m of taxonomy.mislabeled) {
     findings.push(`VP-MISLABEL: "${m.name}" is coded VP-${m.current} but reads as ${m.suggested} (signal: "${m.signal}") → re-tag VP-${m.suggested}-NNN so the coverage matrix isn't skewed.`);
   }
+  // Scenario ↔ defect record links (qa/defects/) — advisory, never scored.
+  findings.push(...defectLinkFindings(projectRootFromScreenDir(screenDir), catalogScreenName, featureText, scenarios.map((sc) => sc.name)));
   if (balance.unclassifiedRatio > 0.4) {
     findings.push(`TAXONOMY-UNCLASSIFIED: ${balance.note} → align the VP-<CATEGORY> codes with the catalog (or extend the bucket keywords) so coverage-balance is meaningful.`);
   } else if (balance.imbalanced && !flowScored) {
     findings.push(`BALANCE: ${balance.note} Stop expanding secondary viewpoints until business-core gaps are filled.`);
   }
-  if (adoptedPostHoc) {
+  if (aiDraft) {
+    findings.push(`VIEWPOINT-DRAFT-UNREVIEWED: \`requirements/test-viewpoint.md\` is marked \`drafted-by: ai\` and no QA has accepted it, so it is not recorded as the baseline and \`atomicLedger\` + \`traceability\` are held as unverified — a checklist the AI wrote would otherwise score the suite it generated at 100% by construction. QA: review the claims (add what you care about, delete what you do not), then \`sungen audit --screen ${screenName} --accept-viewpoint\` — it records the baseline and removes the \`drafted-by: ai\` line. A QA decision: an agent presents it and does not run it.`);
+  }
+  // create-test's checklist review of the viewpoint, still waiting for QA — advisory, never scored.
+  findings.push(...viewpointReviewOpenFindings(path.dirname(viewpointPath)));
+  if (adoptedPostHoc && !aiDraft) {   // a draft's own finding already says this and names the accept command
     findings.push(`VIEWPOINT-ADOPTED-POST-HOC: this is the first audit of \`requirements/test-viewpoint.md\` and the suite ALREADY has ${scenarios.length} scenarios, so the yardstick is being introduced against tests that already exist. A declaration written after the suite can only measure what its author already thought of — and if it was derived FROM the suite, \`atomicLedger\` and \`traceability\` read 100% by construction while anything dropped along the way stops being missing from anything. Both axes are held as unverified until you review the claims (add what you care about, delete what you do not) and confirm: \`sungen audit --screen ${screenName} --accept-viewpoint\` — a QA decision: an agent presents it and does not run it.`);
   }
   if (!hasYardstick) {
@@ -647,7 +685,8 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       ...(unsourced.length ? [`${unsourced.length} scenario(s) could not be traced to a source`] : []),
     ];
     findings.push(`VIEWPOINT-MISSING: \`requirements/test-viewpoint.md\` ${ledger.hasViewpoint ? 'declares no viewpoints' : 'does not exist'}, so this unit has no yardstick. Two scored axes are excluded (atomicLedger, traceability) and four sensors cannot run: the atomic ledger, the declaration-integrity checks (reused ids, dangling refs, uniform priority), the browser-gesture check and the two-way continuity check. Nothing here is a pass — it is unmeasured [${lost.join(', ')}]. A flow contract does NOT substitute: the contract declares the use case, the viewpoint declares the CLAIMS the suite is scored against, and only the second is independent of what was generated. Author it (\`sungen add-flow\` scaffolds a template), then \`sungen audit --screen ${screenName} --accept-viewpoint\`.`);
-  } else if (trace.mappedRatio < 0.5) {
+  } else if (scenarios.length > 0 && trace.mappedRatio < 0.5) {
+    // No scenario yet is not a traceability gap — the axis is n/a, like coverage and claimProof (#852).
     findings.push(`TRACE: ${trace.note}`);
   }
   // (UNIVERSAL viewpoint-gap finding now emitted by the `ui` gate sensor — see the gate block below.)
@@ -688,8 +727,10 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   for (const d of downstream.underCovered) {
     findings.push(`DOWNSTREAM-SCOPE-MISSING: "${d.route}" is a navigation target but is covered only by a page-nav assertion — cover its content/guards, or scaffold it (\`sungen add --screen ${d.slug}\`).`);
   }
+  // #811 — design inventory (advisory): never moves the score or the gate.
+  findings.push(...uiInventoryFindings(uiInv));
   for (const m of manualOracleResult.insufficient.slice(0, 8)) {
-    findings.push(`MANUAL-STEPS-INSUFFICIENT: "${m}" — @manual is incomplete: either Gherkin steps without a Then (invalid Gherkin; comments can't substitute), or a documentation manual whose comments lack numbered action steps + a labeled Observable:/Oracle: line. Write \`# Tester verifies:\` as "1. <action>" … "N. Observable: <what>" / "Oracle: <tool>" — that is what the delivery parser extracts into Steps/Expected.`);
+    findings.push(`MANUAL-STEPS-INSUFFICIENT: "${m}" — @manual is incomplete: either Gherkin steps without a Then (invalid Gherkin; comments can't substitute), a Then that only asserts presence (\`see [X] table\`) while the real oracle sits in a \`# Tester verifies:\` comment (the deliverable's Expected would not say what is checked), or a documentation manual whose comments lack numbered action steps + a labeled Observable:/Oracle: line. Write \`# Tester verifies:\` as "1. <action>" … "N. Observable: <what>" / "Oracle: <tool>" — that is what the delivery parser extracts into Steps/Expected.`);
   }
   // TQ-2 — automatable @manual: deferred (usually cross-screen) but fully DSL-expressible.
   for (const m of autoManual.scenarios.slice(0, 8)) {
@@ -787,7 +828,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   // #622 — the priority table is where release selection comes from; a tag that contradicts it
   // means nobody can tell which of the two was the decision.
   {
-    const pm = priorityMismatches(hasYardstick ? (readText(viewpointPath) ?? '') : '', scenarios);
+    const pm = priorityMismatches(hasYardstick ? viewpoints : [], scenarios);
     const byId = new Map<string, { declared: string; tagged: string; n: number }>();
     for (const m of pm) {
       const cur = byId.get(m.id) ?? { declared: m.declared, tagged: m.tagged, n: 0 };
@@ -860,8 +901,11 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   axes.manualOracle = Math.round(manualCompleteness * 100) / 100;
   // Only a real mismatch scores 0. Without a yardstick `trace.mappedRatio` is 0 because there is
   // nothing to map to, and reporting that as the weakest axis sent authors to "raise taxonomy" —
-  // an axis that was never measured.
-  if (hasYardstick) axes.taxonomy = taxonomyMismatch ? 0 : Math.round(trace.mappedRatio * 100) / 100;
+  // an axis that was never measured. The same holds for a yardstick the ledger can read but that
+  // declares no viewpoint ID traceability can read (per-axis tables only, #832): the ledger has
+  // items, so `hasYardstick` is true, yet there is still nothing to map to. Same condition as the
+  // `traceability` score axis (`applicable: viewpoints.length > 0`).
+  if (hasYardstick && viewpoints.length > 0 && scenarios.length > 0) axes.taxonomy = taxonomyMismatch ? 0 : Math.round(trace.mappedRatio * 100) / 100;
   const notApplicable = axisDefs.filter((a) => !a.applicable).map((a) => a.key);
   const weakestEntry = Object.entries(axes).sort((a, b) => a[1] - b[1])[0];
   const weakest = { axis: weakestEntry[0], value: weakestEntry[1] };
@@ -889,6 +933,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     gate, depth, claim, taxonomy, balance, duplicates, trace, spec,
     taxonomyMismatch, reusedScenarioIds: reusedIds, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, flowDepth, oracle, ledger, viewpointBaseline, calibration,
     ...(isUiFlow ? { flowQuality: flowQ, flowInventory: inventory ?? undefined } : {}),
+    ...(uiInv.designSources.length ? { uiInventory: uiInv } : {}),
     score: {
       overall: Math.round(overall * 10) / 10,
       coverage: Math.round(coverage * 100) / 100,

package/src/harness/capability.ts

@@ -11,6 +11,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { readYamlConfig, warnUnreadableConfig } from './config-file';
 
 export interface CapabilityProfile {
   platform?: string;       // web | mobile | …  (the runtime adapter)
@@ -23,7 +24,13 @@ export interface CapabilityProfile {
    * never asked for.
    */
   verification?: string[];
-  source: 'capabilities.yaml' | 'absent';
+  /**
+   * Where the profile came from. `'unreadable'` is NOT `'absent'`: the file exists and says
+   * something, we just cannot read it. Callers that WRITE capabilities.yaml must branch on this —
+   * scaffolding a default over a file whose contents we failed to parse destroys the user's
+   * declaration (see `cli/commands/generate.ts`).
+   */
+  source: 'capabilities.yaml' | 'absent' | 'unreadable';
 }
 
 export type VerifyLayer = 'ui' | 'api' | 'db';
@@ -119,18 +126,22 @@ export function capabilitiesPath(cwd: string): string {
 
 export function readCapabilities(cwd: string): CapabilityProfile {
   const p = capabilitiesPath(cwd);
-  if (!fs.existsSync(p)) return { platform: undefined, enabled: [], source: 'absent' };
-  try {
-    const y = parseYaml(fs.readFileSync(p, 'utf-8')) || {};
-    return {
-      platform: typeof y.platform === 'string' ? y.platform : undefined,
-      enabled: Array.isArray(y.enabled) ? y.enabled.map(String) : [],
-      verification: Array.isArray(y.verification) ? y.verification.map(String) : undefined,
-      source: 'capabilities.yaml',
-    };
-  } catch {
-    return { platform: undefined, enabled: [], source: 'absent' };
+  const read = readYamlConfig<Record<string, unknown> | null>(p);
+  if (read.state === 'absent') return { platform: undefined, enabled: [], source: 'absent' };
+  if (read.state === 'unreadable') {
+    // The profile decides the runtime adapter, the driver set and the verification scope. Reporting
+    // it once here covers all fifteen call sites; what each does about it is still its own choice.
+    warnUnreadableConfig(p, read.error,
+      'this run cannot tell which platform or drivers the project declares, and falls back to none');
+    return { platform: undefined, enabled: [], source: 'unreadable' };
   }
+  const y = (read.value || {}) as Record<string, unknown>;
+  return {
+    platform: typeof y.platform === 'string' ? y.platform : undefined,
+    enabled: Array.isArray(y.enabled) ? y.enabled.map(String) : [],
+    verification: Array.isArray(y.verification) ? y.verification.map(String) : undefined,
+    source: 'capabilities.yaml',
+  };
 }
 
 export function writeCapabilities(cwd: string, profile: { platform?: string; enabled: string[]; verification?: string[] }): string {

package/src/harness/catalog/universal-viewpoints.yaml

@@ -24,7 +24,7 @@ page_types:
     detect_keywords: [cart, product, checkout, catalog, brand, category, "add to cart"]
     must_cover:
       - theme: list-data
-        keywords: [list, displayed, card, "product card", grid]
+        keywords: ["product list", displayed, card, "product card", grid]
         depth:
           requires: data-assertion
           cross_screen: false
@@ -38,7 +38,7 @@ page_types:
           keywords: ["product detail", "detail page", "same product name", "matching name", "consistency", "same price"]
           template: "User remember [Product Name] text as {{v}} … User see [Detail Product Name] header with {{v}}"
       - theme: cart-correctness
-        keywords: ["cart contains", quantity, "price", subtotal, "in cart", "cart content", "cart product"]
+        keywords: ["cart contains", "cart quantity", "cart price", subtotal, "in cart", "cart content", "cart product"]
         depth:
           requires: data-assertion
           cross_screen: true
@@ -77,7 +77,7 @@ page_types:
           keywords: ["required", "must be", "error message", "validation message"]
           template: "User see [Field Error] message with {{error_text}}"
       - theme: format-boundary
-        keywords: [format, invalid, boundary, length, range]
+        keywords: [format, invalid, boundary, "max length", "min length", range]
         depth:
           requires: data-assertion
           cross_screen: false
@@ -125,10 +125,10 @@ page_types:
   # suite, which is a scoring decision for an owner, not a drive-by. `viewpoint-ledger` already
   # covers the dangerous half by refusing `tap [Back]` as an answer to an OS-back viewpoint item.
   mobile-list:
-    detect_keywords: [feed, "pull to refresh", "infinite scroll", "load more", "list item", "list row"]
+    detect_keywords: ["feed item", "pull to refresh", "infinite scroll", "load more", "list item", "list row"]
     must_cover:
       - theme: list-data
-        keywords: [list, feed, row, "list item", displayed]
+        keywords: ["feed item", row, "list item", displayed]
         depth:
           requires: data-assertion
           cross_screen: false

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/counted-assertions.ts

@@ -0,0 +1,33 @@
+/**
+ * How many items a scenario's assertions demonstrate — the denominator of CLAIM-PARTIAL (#622).
+ *
+ * One reading for both places that check a counted claim (the viewpoint ledger and the title-level
+ * `numericClaimGaps`), which used to carry their own copy of the regex.
+ *
+ * Counted, once per distinct assertion:
+ *   - a value: `see [X] … with|contains {{v}}`;
+ *   - a positive state: `see [X] … is checked|selected|enabled|disabled`;
+ *   - an indicator's presence: `see [X] icon|checkbox|toggle|radio|badge|image` (#866) — on mobile a
+ *     ticked item is often observable ONLY as its tick icon, so one per item is the proof.
+ * Not counted: plain visibility of text/headers (it shows a label, not one of N values) and absence
+ * (`is hidden`, `not …`), which proves nothing is there.
+ */
+// The tail stops before the NEXT `see [`, or consecutive assertions would swallow each other.
+const SEE_STEP = /\bsee \[([^\]]+)\]((?:(?!\bsee \[)[^[])*)/g;
+const VALUE = /^[^|]*?\b(?:with|contains) (\{\{[^}]*\}\})/;
+const ABSENT = /^\s*\S*\s*(?:is hidden|is not\b|not\b|does not\b)/;
+const STATE = /^\s*\S*\s*is (checked|selected|enabled|disabled)\b/;
+const INDICATOR = /^\s*(icon|checkbox|toggle|radio|badge|image)\b/;
+
+export function countedAssertions(stepsText: string): number {
+  const seen = new Set<string>();
+  for (const m of stepsText.matchAll(SEE_STEP)) {
+    const [, target, rest] = m;
+    if (ABSENT.test(rest)) continue;
+    // Keyed on the target and WHAT it proves — never on the tail, which runs into the next step, so
+    // the same element asserted before and after an action is still one assertion.
+    const proof = VALUE.exec(rest)?.[1] ?? STATE.exec(rest)?.[1] ?? INDICATOR.exec(rest)?.[1];
+    if (proof) seen.add(`${target}|${proof}`);
+  }
+  return seen.size;
+}

package/src/harness/data-driven-lint.ts

@@ -155,29 +155,100 @@ function overrideKeys(raw?: string): Set<string> {
   return out;
 }
 
+interface FeatureUnderLint {
+  /** Feature file basename — names the test-data file the runtime loads for it. */
+  name: string;
+  scenarios: ParsedScenario[];
+  tags: string[];
+}
+
+/** What every feature of a unit shares: unit-level refs and the @api catalog. */
+interface UnitLintContext {
+  screenDir: string;
+  screenName: string;
+  cwd: string;
+  fileRefs: Set<string>;
+  apiParams: Map<string, string[]>;
+}
+
 /** Lint the @cases/@query usage of one screen/flow directory. Returns advisory warnings. */
 export function lintDataDriven(screenDir: string, cwd: string = process.cwd()): DataDrivenWarning[] {
   const base = path.basename(screenDir);
   const screenName = unitIdOf(screenDir);
   // Every `.feature` of the unit — `add --feature` sub-features lint too. A file that
   // fails to parse contributes nothing rather than voiding the whole unit's lint.
-  const scenarios: ParsedScenario[] = [];
-  const featureTags: string[] = [];
-  for (const p of featureFilesFor(screenDir, base).filter((f) => fs.existsSync(f))) {
+  const features: FeatureUnderLint[] = [];
+  const featureFiles = featureFilesFor(screenDir, base).filter((f) => fs.existsSync(f));
+  for (const p of featureFiles) {
     try {
       const feature = new GherkinParser().parseFeatureFile(p);
-      scenarios.push(...(feature.scenarios || []));
-      featureTags.push(...(feature.tags || []));
+      features.push({ name: path.basename(p, '.feature'), scenarios: feature.scenarios || [], tags: feature.tags || [] });
     } catch {
       /* a file that fails to parse contributes nothing */
     }
   }
-  if (scenarios.length === 0) return [];
+  if (!features.some((f) => f.scenarios.length > 0)) return [];
+
+  const ctx: UnitLintContext = {
+    screenDir, screenName, cwd,
+    // `{{key}}` refs carried by the unit's selectors (i18n) and mock catalog are live too.
+    fileRefs: refsInUnitFiles(screenDir),
+    apiParams: apiParamsByName(screenName, cwd),
+  };
+
+  // #839 — each feature against ITS OWN test-data file. The runtime loads
+  // `test-data/<feature file basename>.yaml` (TestDataLoader.load(unit, featureFileName)), with no
+  // fallback and no merging; reading `<unit dir>.yaml` instead found nothing whenever the names
+  // differ — the default for `add --screen x --path /a/b` (→ b.feature) and for `--feature` — so
+  // every key read as missing and no orphan was ever reported. The tables are deliberately NOT
+  // merged: a key in another feature's file compiles to the literal `${key}` here.
+  const warns: DataDrivenWarning[] = [];
+  for (const f of features) if (f.scenarios.length > 0) warns.push(...lintFeature(f, ctx));
+  warns.push(...unloadedTestDataFiles(screenDir, featureFiles.map((f) => path.basename(f, '.feature'))));
+
+  // Catalog-level lint (SELECT-only, params declared/used, datasource present).
+  try {
+    for (const e of lintCatalog(screenName, null, cwd).errors) warns.push({ message: e });
+  } catch {
+    /* no catalog → nothing to lint */
+  }
+  return warns;
+}
+
+/**
+ * A test-data file no feature loads is dead in full: the runtime reads only
+ * `<feature>.yaml` and its `<feature>.<env>.yaml` overlays. Typically a `<unit>.yaml` written by
+ * hand next to a feature `add --path` named after the URL — its keys never reach a test.
+ * Every existing feature file counts (even one that failed to parse), so a parse error never
+ * turns its data into a false "loaded by no feature".
+ */
+function unloadedTestDataFiles(screenDir: string, featureNames: string[]): DataDrivenWarning[] {
+  let files: string[];
+  try {
+    files = fs.readdirSync(path.join(screenDir, 'test-data')).filter((f) => /\.ya?ml$/.test(f) && !f.startsWith('_'));
+  } catch {
+    return [];
+  }
+  const loaded = (stem: string): boolean => featureNames.some((n) => stem === n || stem.startsWith(`${n}.`));
+  return files
+    .filter((f) => !loaded(f.replace(/\.ya?ml$/, '')) || !f.endsWith('.yaml'))
+    .map((f) => ({
+      message: `test-data/${f} is loaded by no feature — the runtime reads test-data/<feature>.yaml (+ <feature>.<env>.yaml) for ${featureNames.map((n) => `${n}.feature`).join(', ')}: move its keys there or remove it.`,
+    }));
+}
 
-  const tdPath = path.join(screenDir, 'test-data', `${base}.yaml`);
-  const td: Record<string, any> = tdPath && fs.existsSync(tdPath) ? parseYaml(fs.readFileSync(tdPath, 'utf8')) || {} : {};
+function lintFeature(feature: FeatureUnderLint, ctx: UnitLintContext): DataDrivenWarning[] {
+  const { screenName, cwd, fileRefs, apiParams } = ctx;
+  const { scenarios, tags: featureTags } = feature;
+  const tdFile = `test-data/${feature.name}.yaml`;
+  const tdPath = path.join(ctx.screenDir, 'test-data', `${feature.name}.yaml`);
+  const td: Record<string, any> = fs.existsSync(tdPath) ? parseYaml(fs.readFileSync(tdPath, 'utf8')) || {} : {};
   const topKeys = new Set(Object.keys(td));
   const warns: DataDrivenWarning[] = [];
+  // H3: an `@extend:<base>` scenario runs the base's steps first — the base's captures bind for it.
+  // Per feature, like the compiler's steps registry: an `@extend` never reaches another file's base.
+  const stepsBase = new Map<string, ParsedScenario>();
+  for (const sc of scenarios) if (sc.stepsName) stepsBase.set(sc.stepsName, sc);
   // Bindings a `@beforeAll` hook's `@api:`/`@query:` preconditions make are readable from EVERY
   // scenario of the feature (the compiler registers them feature-wide). A `remember … as` inside the
   // hook is NOT — it stays hook-local — so only the tag-bound names are exempted here.
@@ -186,18 +257,12 @@ export function lintDataDriven(screenDir: string, cwd: string = process.cwd()):
     if (sc.hookType !== 'beforeAll') continue;
     for (const t of sc.tags || []) { const m = t.match(/^@(?:api|query):([A-Za-z_]\w*)/); if (m) featureBound.add(m[1]); }
   }
-  // H3: an `@extend:<base>` scenario runs the base's steps first — the base's captures bind for it.
-  const stepsBase = new Map<string, ParsedScenario>();
-  for (const sc of scenarios) if (sc.stepsName) stepsBase.set(sc.stepsName, sc);
-  // `{{key}}` refs carried by the unit's selectors (i18n) and mock catalog are live too.
-  const fileRefs = refsInUnitFiles(screenDir);
   // A feature-level `@manual` makes every scenario manual (the whole file is skipped by the compiler).
   const featureManual = featureTags.some((t) => t === '@manual' || t.startsWith('@manual:'));
 
   // What the scenarios bind, collected up front — the @query pass below adds the params it binds by name.
   const usedHeads = new Set<string>();
   const usedDatasets = new Set<string>();
-  const apiParams = apiParamsByName(screenName, cwd);
   for (const h of fileRefs) usedHeads.add(h);
   for (const sc of scenarios) {
     for (const r of collectRefs(sc, featureManual || isManualScenario(sc))) usedHeads.add(r.split(/[.[]/)[0]);
@@ -228,7 +293,7 @@ export function lintDataDriven(screenDir: string, cwd: string = process.cwd()):
       const ds = casesTag.slice('@cases:'.length).trim();
       const rows = td[ds];
       if (!Array.isArray(rows)) {
-        warns.push({ scenario: sc.name, message: `@cases:${ds} → dataset "${ds}" is missing or not a list in test-data.` });
+        warns.push({ scenario: sc.name, message: `@cases:${ds} → dataset "${ds}" is missing or not a list in ${tdFile}.` });
       } else {
         const colSets = rows.map((r) => new Set(Object.keys(r || {}).filter((k) => !ROW_META.has(k))));
         const allCols = new Set<string>();
@@ -256,7 +321,7 @@ export function lintDataDriven(screenDir: string, cwd: string = process.cwd()):
       for (const r of refs) {
         const head = r.split(/[.[]/)[0];
         if (head.startsWith('$') || bound.has(head) || featureBound.has(head) || topKeys.has(head)) continue;
-        warns.push({ scenario: sc.name, message: `{{${r}}} is not a test-data key and nothing binds it at run time — it compiles to the literal text '\${${r}}' (add the key to test-data, or fix the ref).` });
+        warns.push({ scenario: sc.name, message: `{{${r}}} is not a test-data key and nothing binds it at run time — it compiles to the literal text '\${${r}}' (add the key to ${tdFile}, or fix the ref).` });
       }
     }
 
@@ -289,15 +354,8 @@ export function lintDataDriven(screenDir: string, cwd: string = process.cwd()):
   for (const k of topKeys) {
     if (k.startsWith('_')) continue; // Data Factory metadata, not scenario data
     if (!usedHeads.has(k) && !usedDatasets.has(k)) {
-      warns.push({ message: `test-data key "${k}" is defined but never referenced ({{${k}}}, a @cases dataset, or an override) — dead data: bind it into a scenario or remove it.` });
+      warns.push({ message: `test-data key "${k}" is defined but never referenced ({{${k}}}, a @cases dataset, or an override) by ${feature.name}.feature — dead data: bind it into a scenario or remove it from ${tdFile}.` });
     }
   }
-
-  // Catalog-level lint (SELECT-only, params declared/used, datasource present).
-  try {
-    for (const e of lintCatalog(screenName, null, cwd).errors) warns.push({ message: e });
-  } catch {
-    /* no catalog → nothing to lint */
-  }
   return warns;
 }