@sun-asterisk/sungen 3.2.28 → 3.2.30

package/src/harness/audit.ts

@@ -13,20 +13,20 @@ import { checkViewpointBaseline, ViewpointBaseline } from './viewpoint-baseline'
 import { flowQuality, statefulDepthFor, continuityGaps, flowInventory, misfiledPhases, FlowQualityResult, InventoryResult } from './flow-contract';
 import { featureFilesFor } from './unit-paths';
 import {
-  loadCatalog, viewpointGate, assertionDepth, dataThemesFor, depthThresholdFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
+  loadCatalog, viewpointGate, assertionDepth, dataThemesFor, depthThresholdFor, coverageBalance, duplicateClusters, scenarioIdReuse, ReusedScenarioId, traceability, claimProof, taxonomyLint,
   automatableManual, flowCoveredThemes, flowRegressionDepth, oracleStrength, declaredPageType,
   numericClaimGaps, priorityMismatches,
   GateResult, DepthResult, BalanceResult, DuplicateResult, TraceResult, ClaimProofResult, TaxonomyResult, Catalog, AutomatableManualResult, FlowDepthResult, OracleStrengthResult,
 } from './sensors';
 import { loadFlowScenarios } from './flow-check';
-import { manualReasonMismatches, MANUAL_REASONS, buildPlan } from './capability-plan';
+import { manualReasonMismatches, MANUAL_REASONS, buildPlan, KEEP_REASON_CODES, MANUAL_REASON_RANGE } from './capability-plan';
 import { readCapabilities, verificationScopeFindings } from './capability';
 import { readIntent, projectRootFromScreenDir, IntentProfile } from './intent';
 import { getProvenance, Provenance } from './provenance';
 import { specCoverage, SpecCoverageResult, parseSpecClauses, restatedRequirementSources } from './spec-coverage';
 import { downstreamScope, manualOracle, readText, DownstreamResult, ManualOracleResult,
   negativeSideEffect, sourceBacked, crossArtifactOwnership, isolationRisk, serialCascadeRisk } from './quality-gates';
-import { viewpointLedger, parseViewpointItems, browserGestureSubstitutions, viewpointIntegrity, LedgerResult } from './viewpoint-ledger';
+import { viewpointLedger, parseViewpointItems, browserGestureSubstitutions, substitutionRemedy, viewpointIntegrity, LedgerResult } from './viewpoint-ledger';
 import { specBranches, unenumeratedBranches, sameOracleClusters, permissionPairGaps, awaitingSeedData, unconsideredRisks, MULTI_SCREEN_RISKS } from './spec-branches';
 const MULTI_SCREEN_RISK_COUNT = MULTI_SCREEN_RISKS.length;
 import { capabilityRegistry } from '../capabilities/registry';
@@ -45,6 +45,8 @@ export interface AuditReport {
   duplicates: DuplicateResult;
   trace: TraceResult;
   taxonomyMismatch: boolean;    // scenarios use IDs not in the project's test-viewpoint.md
+  /** #694 — two different scenarios in one .feature carrying the same VP id. Gate-blocking. */
+  reusedScenarioIds: ReusedScenarioId[];
   downstream: DownstreamResult; // downstream screens referenced but under-covered
   manualOracle: ManualOracleResult; // @manual scenarios lacking setup/action/oracle
   automatableManual: AutomatableManualResult; // @manual that is actually automatable (deferred, not judgment) — TQ-2
@@ -460,30 +462,15 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     if (!flowQ.contract!.minimalGuarantee) {
       findings.push('FLOW-GUARANTEE-MISSING: the contract declares no `minimalGuarantee:` — the postcondition that must hold in EVERY flow, including failure ("no second account for the same email", "no verification mail on a rejected submit"). Exception/guard scenarios have nothing to assert against without it; add it (and `successGuarantee:` for the goal-reached side).');
     }
-    // #599 — integrity of the DECLARATION itself: three ways it can be internally wrong while
-    // every coverage number still reads well.
-    {
-      const testDataDir = path.join(screenDir, 'test-data');
-      const extra: Array<{ label: string; text: string }> = [];
-      try {
-        for (const f of fs.readdirSync(testDataDir).filter((x) => x.endsWith('.yaml'))) {
-          extra.push({ label: `test-data/${f}`, text: readTextFile(path.join(testDataDir, f)) ?? '' });
-        }
-      } catch { /* api units and fresh scaffolds carry none */ }
-      const vi = viewpointIntegrity(viewpointPath, scenarios.map((sc) => sc.vpId ?? '').filter(Boolean), extra);
-      for (const d of vi.duplicateIds.slice(0, 4)) {
-        findings.push(`VIEWPOINT-ID-REUSED: "${d.id}" labels ${d.count} different claims (${d.texts.map((t) => `"${t.slice(0, 44)}…"`).join(' · ')}). The ledger then counts ${d.count} items while traceability sees ONE id, so both the coverage arithmetic and "which test proves this?" go wrong — and neither number looks suspicious. Give each atomic claim its own id; several ids may share a flow.`);
-      }
-      for (const d of vi.danglingRefs.slice(0, 5)) {
-        findings.push(`TRACE-REF-DANGLING: ${d.where} cites "${d.ref}", which no scenario carries. Nothing breaks at runtime, so a wrong pointer survives every refactor and quietly misleads the next maintainer. Fix the reference, or the scenario id it was meant to name.`);
-      }
-      if (vi.uniformPriority) {
-        findings.push(`VIEWPOINT-PRIORITY-UNIFORM: all ${vi.uniformPriority.rows} rows of the Priority Viewpoints table are "${vi.uniformPriority.levels[0]}". That is a formality, not a priority: nothing can be selected for a smoke run and the release conversation has no input. Rank by business impact and risk — the basic flow and the data-integrity guards are not the same bet as an exit path a screen suite already covers.`);
-      }
-    }
     // #595 — a viewpoint item naming a browser-level gesture, answered with an in-app control.
     for (const g of browserGestureSubstitutions(viewpointPath, scenarios, platform).slice(0, 4)) {
-      findings.push(`VIEWPOINT-GESTURE-SUBSTITUTED: the viewpoint asks for "${g.gesture}" ("${g.item.slice(0, 80)}…") but the suite exercises an in-app control instead. They are different mechanisms — an app button runs the screen's own re-hydrate logic, browser history does not, and a defect that only shows on history navigation lives in exactly that gap. The step vocabulary has no reload/back step (#593), so defer it with \`@manual\` naming the gesture rather than substituting silently.`);
+      // The remedy is not the same on both platforms, and getting it wrong is the difference between
+      // useful advice and a lie: web still has no reload/back step (#593), so `@manual` is the honest
+      // reply — but every mobile gesture in this set now compiles, so telling a mobile author to defer
+      // would send them to a manual procedure for work the compiler does. Read from the ledger entry
+      // (`substitutionRemedy`), never re-derived here, so a step landing for web needs no edit here.
+      const remedy = substitutionRemedy(g);
+      findings.push(`VIEWPOINT-GESTURE-SUBSTITUTED: the viewpoint asks for "${g.gesture}" ("${g.item.slice(0, 80)}…") but the suite exercises an in-app control instead. They are different mechanisms — an app button runs the screen's own re-hydrate logic and the gesture does not, so a defect that only shows on the gesture's own path lives in exactly that gap. ${remedy}`);
     }
     // #595 — a flow whose requirement list is a hand restatement of the screen specs it
     // traverses. `specFR` read 100% over two restated FRs while the guard clause the flow most
@@ -523,6 +510,41 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       findings.push(`FLOW-HANDOFF-SHALLOW: only ${flowQ.handoffs.asserted}/${flowQ.handoffs.total} cross-screen transitions are followed by an assertion in the new screen — carried state (the thing a flow exists to verify) is unproven at the handoff. businessDepth is capped until asserted.`);
     }
   }
+  // #694 — two DIFFERENT scenarios wearing the same VP id. BLOCKING (it joins the gate
+  // conjunction below) where the declaration-integrity findings that follow are advisory: a
+  // reused id does not stop here, it reaches the customer. `generateTcId` builds the delivered
+  // testcase id straight out of the vpId, so the collision ships as two rows carrying ONE id in
+  // the deliverable — and the result-merge fallback has already attached one sibling's run
+  // result to another, delivering 7 never-executed testcases as "Passed" (see
+  // `exporters/scenario-merger.ts`). `matrix/gates.ts` already grades this `severity: 'error'`,
+  // but only at delivery; blocking at audit is what makes it cheap to fix (renumber, regenerate).
+  const reusedIds = scenarioIdReuse(scenarios);
+  for (const r of reusedIds.slice(0, 6)) {
+    findings.push(`SCENARIO-ID-REUSED: ${r.count} different scenarios in ${r.file || 'this feature'} carry the id "${r.id}" (${r.titles.map((t) => `"${t.slice(0, 52)}…"`).join(' · ')}). Every axis stays green — the duplicate sensor clusters identical STEPS, so scenarios that merely share an id sail past it — while the deliverable gets ${r.count} rows under one testcase id and the run-result merge can attach the wrong scenario's result. Give each scenario its own sequence number within its category; the ledger item that now reads UNCOVERED is the sibling that lost its number.`);
+  }
+  // #599 — integrity of the DECLARATION itself: three ways it can be internally wrong while
+  // every coverage number still reads well. Advisory. This used to sit inside the
+  // `flowQ.hasContract` branch above, so a SCREEN unit never reached it at all — the checks ran
+  // on flows only, silently, for every release since they landed (#694).
+  {
+    const testDataDir = path.join(screenDir, 'test-data');
+    const extra: Array<{ label: string; text: string }> = [];
+    try {
+      for (const f of fs.readdirSync(testDataDir).filter((x) => x.endsWith('.yaml'))) {
+        extra.push({ label: `test-data/${f}`, text: readTextFile(path.join(testDataDir, f)) ?? '' });
+      }
+    } catch { /* api units and fresh scaffolds carry none */ }
+    const vi = viewpointIntegrity(viewpointPath, scenarios.map((sc) => sc.vpId ?? '').filter(Boolean), extra);
+    for (const d of vi.duplicateIds.slice(0, 4)) {
+      findings.push(`VIEWPOINT-ID-REUSED: "${d.id}" labels ${d.count} different claims (${d.texts.map((t) => `"${t.slice(0, 44)}…"`).join(' · ')}). The ledger then counts ${d.count} items while traceability sees ONE id, so both the coverage arithmetic and "which test proves this?" go wrong — and neither number looks suspicious. Give each atomic claim its own id; several ids may share a flow.`);
+    }
+    for (const d of vi.danglingRefs.slice(0, 5)) {
+      findings.push(`TRACE-REF-DANGLING: ${d.where} cites "${d.ref}", which no scenario carries. Nothing breaks at runtime, so a wrong pointer survives every refactor and quietly misleads the next maintainer. Fix the reference, or the scenario id it was meant to name.`);
+    }
+    if (vi.uniformPriority) {
+      findings.push(`VIEWPOINT-PRIORITY-UNIFORM: all ${vi.uniformPriority.rows} rows of the Priority Viewpoints table are "${vi.uniformPriority.levels[0]}". That is a formality, not a priority: nothing can be selected for a smoke run and the release conversation has no input. Rank by business impact and risk — the basic flow and the data-integrity guards are not the same bet as an exit path a screen suite already covers.`);
+    }
+  }
   // #592 W5 — a continuity mechanism proved on one side only.
   if (isUiFlow) {
     const scenarioTexts = scenarios.map((s) => `${s.name} ${s.stepsText}`);
@@ -536,7 +558,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     // manual, most of them M5-inbox — invisible while tagged bare).
     const bareManual = (featureText.match(/@manual(?![:\w])/g) || []).length;
     if (bareManual > 0) {
-      findings.push(`MANUAL-CODE-MISSING: ${bareManual} @manual tag(s) carry no reason code — tag @manual:M1..M9 (M5 = external dependency e.g. inbox, M3 = mock/network, M7 = environment) so the capability planner can route what a driver would automate.`);
+      findings.push(`MANUAL-CODE-MISSING: ${bareManual} @manual tag(s) carry no reason code — tag @manual:${MANUAL_REASON_RANGE} (M5 = external dependency e.g. inbox, M3 = mock/network, M7 = environment, M10 = device/OS capability, M11 = real-device only) so the capability planner can route what a driver would automate.`);
     }
   }
   for (const c of flowCredits) {
@@ -671,7 +693,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     const plan = buildPlan(screenDir, screenName, catalogScreenName, platform);
     if (plan.recommendations.length) {
       const recs = plan.recommendations.map((r) => `\`sungen capability add ${r.driver}\` (automates ${r.count})`).join(' · ');
-      findings.push(`CAPABILITY-SUGGESTION: ${plan.capabilityManual} @manual scenario(s) are capability-manual (a driver could automate them) — ${recs}. Recommend-only: nothing is installed automatically; the ${plan.judgmentManual} judgment-manual (M6/M8/M9) correctly stay manual.`);
+      findings.push(`CAPABILITY-SUGGESTION: ${plan.capabilityManual} @manual scenario(s) are capability-manual (a driver could automate them) — ${recs}. Recommend-only: nothing is installed automatically; the ${plan.judgmentManual} judgment-manual (${KEEP_REASON_CODES.join('/')}) correctly stay manual.`);
     }
     // Named, not dropped: without this the scenarios read as "nothing could help", and the
     // operator's only clue was an install that dead-ends (#597).
@@ -835,15 +857,18 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const calibration = { axes, weakest, inflated, notApplicable, cappedAt: capped ? cap : undefined };
 
   // Gate spans coverage (viewpoint themes), depth, claim-proof, spec-clause coverage,
-  // AND taxonomy-match (scenarios must use the project's viewpoint IDs when defined).
+  // taxonomy-match (scenarios must use the project's viewpoint IDs when defined),
+  // AND scenario-id uniqueness — a reused id reaches the customer's deliverable as two rows
+  // under one testcase id, and has already shipped a never-executed testcase as "Passed" (#694).
   const gateStatus: 'PASS' | 'FAIL' =
-    gate.gaps.length === 0 && depth.verdict !== 'fail' && claim.verdict !== 'fail' && spec.verdict !== 'fail' && !taxonomyMismatch && !gateSensorError ? 'PASS' : 'FAIL';
+    gate.gaps.length === 0 && depth.verdict !== 'fail' && claim.verdict !== 'fail' && spec.verdict !== 'fail' && !taxonomyMismatch && !gateSensorError
+    && reusedIds.length === 0 ? 'PASS' : 'FAIL';
 
   return {
     screen: screenName,
     scenarioCount: scenarios.length,
     gate, depth, claim, taxonomy, balance, duplicates, trace, spec,
-    taxonomyMismatch, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, flowDepth, oracle, ledger, viewpointBaseline, calibration,
+    taxonomyMismatch, reusedScenarioIds: reusedIds, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, flowDepth, oracle, ledger, viewpointBaseline, calibration,
     ...(isUiFlow ? { flowQuality: flowQ, flowInventory: inventory ?? undefined } : {}),
     score: {
       overall: Math.round(overall * 10) / 10,

package/src/harness/capability-plan.ts

@@ -2,7 +2,7 @@
  * Capability Planner (Phase 2b) — deterministic, recommend-only.
  *
  * Classifies each scenario's execution mode + each @manual case by reason code
- * (M1–M9), maps capability-reasons to drivers, and emits the manual-reason KPI.
+ * (M1–M11), maps capability-reasons to drivers, and emits the manual-reason KPI.
  * Never installs anything (that's `sungen capability add`). See
  * docs/spec/sungen_phase2b_spec.md.
  */
@@ -22,13 +22,37 @@ export const MANUAL_REASONS: Record<string, ReasonDef> = {
   M4: { code: 'M4', label: 'Missing stable selector/test-id', cls: 'capability', drivers: [] }, // locator contract, no driver
   M5: { code: 'M5', label: 'External dependency',           cls: 'capability', drivers: ['mail-file', 'contract'] },
   M6: { code: 'M6', label: 'Visual / UX judgment',          cls: 'keep',       drivers: ['specialized'] },
+  // `capability` with no driver is deliberate and matches M4: the case IS automatable once the
+  // environment exists, it just is not an `sungen capability add` away. Reclassifying it as `keep`
+  // would claim the opposite — that no environment could ever run it — and would silently move
+  // every existing M7 scenario from the capability-manual count to judgment-manual.
   M7: { code: 'M7', label: 'Environment limitation',        cls: 'capability', drivers: [] }, // testability, no driver
   M8: { code: 'M8', label: 'Not worth automating',          cls: 'keep',       drivers: [] },
   M9: { code: 'M9', label: 'True human judgment',           cls: 'keep',       drivers: [] },
+  // Mobile-specific (M10/M11). Both are `keep` with no driver, and that is the honest answer:
+  // nothing installable automates them, so the planner must not imply otherwise. Before these
+  // existed every mobile-specific reason collapsed into M7, which made "needs a real device" and
+  // "waiting on staging infra" indistinguishable in the report.
+  M10: { code: 'M10', label: 'Device/OS capability',        cls: 'keep',       drivers: [] },
+  M11: { code: 'M11', label: 'Real-device only',            cls: 'keep',       drivers: [] },
   // Not a single-screen driver gap: automatable cross-screen via a flow (/sungen:add-flow).
   XS: { code: 'XS', label: 'Cross-screen (automate via flow)', cls: 'flow',    drivers: [] },
 };
 
+/** Codes that stay manual whatever is installed — derived, so a new `keep` code joins by itself. */
+export const KEEP_REASON_CODES: string[] = Object.values(MANUAL_REASONS)
+  .filter((r) => r.cls === 'keep')
+  .map((r) => r.code);
+
+/** The documented reason-code range, e.g. "M1..M11". Derived so guidance can never go stale. */
+export const MANUAL_REASON_RANGE: string = (() => {
+  const ns = Object.keys(MANUAL_REASONS)
+    .filter((c) => /^M\d+$/.test(c))
+    .map((c) => Number(c.slice(1)))
+    .sort((a, b) => a - b);
+  return ns.length ? `M${ns[0]}..M${ns[ns.length - 1]}` : '';
+})();
+
 // Keyword inference (best-effort retrofit). Order matters — first match wins.
 // Cross-screen "deferred to a flow" is checked FIRST: it is not a driver gap on
 // this screen, it is handled by a flow — so it must not recommend a driver.
@@ -41,6 +65,14 @@ const INFER: { code: string; re: RegExp }[] = [
   // "email" alone is too greedy (every subscription test mentions it) → require a real external-mail
   // signal (verification mail / OTP / inbox), so an API/DB-oracle test isn't misread as M5.
   { code: 'M5', re: /\b(external|third[-\s]?party|sandbox|payment gateway|invoice|download|verification (e?mail|link)|otp|mailbox|inbox|e?mail link)\b/i },
+  // Mobile-specific, and they MUST sit ahead of M6/M7 or they never fire: M6 matches
+  // /keyboard|accessibilit|responsive/ and M7 matches /environment/, either of which would take a
+  // mobile reason first. They stay BEHIND M1–M5 on purpose, so a mobile phrasing of an ordinary
+  // driver gap ("assert via API", "needs a stable test-id") still routes to the driver that solves
+  // it. One known consequence of that order: "IAP sandbox" hits M5's `sandbox` before M10 — the
+  // external-payment reading is the more useful one, and the order test pins it either way.
+  { code: 'M11', re: /\b(real device|máy thật|physical device|nfc|biometric|fingerprint|face id|touch id|camera thật|real camera|push token)\b/i },
+  { code: 'M10', re: /\b(notification shade|app switcher|recents|in-app purchase|iap|interruption|incoming call|permission variance|os version)\b/i },
   { code: 'M6', re: /\b(visual|responsive|layout|accessibilit|a11y|keyboard|screen reader|ux|breakpoint)\b/i },
   { code: 'M7', re: /\b(environment|staging[-\s]?only|infra|env limitation)\b/i },
   { code: 'M8', re: /\b(not worth|exploratory|one[-\s]?off)\b/i },

package/src/harness/catalog/drivers.yaml

@@ -10,7 +10,7 @@
 #   status:    shipped → published as an npm package (R5);  planned → not built yet.
 #   bundled:   true → installed automatically (a dependency of @sun-asterisk/sungen),
 #              so `capability add` is unnecessary.
-#   unblocks:  manual-reason codes (M1–M9) this driver resolves (Phase 2b taxonomy).
+#   unblocks:  manual-reason codes (M1–M11) this driver resolves (Phase 2b taxonomy).
 #
 # R5 status: the three real capabilities ship as packages — @sungen/driver-ui (web UI,
 # bundled as the default), @sungen/driver-db, @sungen/driver-api. The web *platform*

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

@@ -106,6 +106,125 @@ page_types:
       - theme: navigation-correctness
         keywords: [tap, navigate, "leaves home", "is hidden", opens, navigation]
 
+  # ---- mobile page-types -------------------------------------------------------------------
+  # All `mobile-*`, so `sensors.ts` never offers them to a web target. Two rules shaped the
+  # keywords below:
+  #   1. Detection needs 2 distinct hits AND a 1-hit lead (MIN_HITS/MIN_MARGIN), so keywords must
+  #      DISCRIMINATE, not merely occur. Generic mobile words ("tap", "screen") are absent.
+  #   2. A mobile target still considers the web types, and that is correct: a mobile commerce
+  #      screen SHOULD select ecommerce-list, and a mobile form leaning on generic form
+  #      vocabulary (field/submit/validation) SHOULD select `form`. These types are for what a
+  #      web type has no concept of, so each keyword set is built from natively-distinctive nouns.
+  # Themes carry `depth:` wherever the honest oracle is a value rather than a sighting — that is
+  # what separates a suite that scrolls and asserts a value from one that only asserts presence.
+  # Every theme is expressible in the SHIPPED mobile vocabulary (scroll/swipe/pull-to-refresh/
+  # rotate/background/restart/grant-permission/set-connectivity/deep-link), so none of them forces
+  # an @manual. OS-back themes remain absent, but the REASON has changed: the `go back` step now
+  # exists (per-OS KEYCODE_BACK / WDA navigation-back), so the blocker is no longer vocabulary. What
+  # stops it now is blast radius — a new `must_cover` theme is a new gap for every existing mobile
+  # 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"]
+    must_cover:
+      - theme: list-data
+        keywords: [list, feed, row, "list item", displayed]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["row contains", "item contains", "every row", "all items", "each row", "list shows"]
+          template: "User see all [List Item] text contains {{expected_label}}"
+      - theme: refresh-correctness
+        keywords: ["pull to refresh", refresh, reload, refreshed]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["after refresh", "refreshed list", "new item", "updated list", "after pull to refresh"]
+          template: "User pull to refresh [List] … User see all [List Item] text contains {{expected_label}}"
+      - theme: scroll-reachability
+        keywords: [scroll, swipe, "load more", "infinite scroll", "below the fold"]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["after scrolling", "scrolled to", "last item", "load more", "next page"]
+          template: "User scroll to [Last List Item] … User see [Last List Item] text contains {{expected_last}}"
+
+  mobile-detail:
+    detect_keywords: ["detail screen", "detail view", "detail header", "item detail", "detail pane"]
+    must_cover:
+      - theme: detail-data
+        keywords: [detail, header, displayed, field]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["detail shows", "detail contains", "detail header", "detail value", "detail field"]
+          template: "User see [Detail Title] text contains {{expected_title}}"
+      - theme: list-detail-consistency
+        keywords: [consistent, consistency, match, "same item", "correct item"]
+        depth:
+          requires: data-assertion
+          cross_screen: true
+          keywords: ["same item name", "matching name", "same value", "consistency", "same title"]
+          template: "User remember [List Item] text as {{v}} … User see [Detail Title] text contains {{v}}"
+
+  mobile-form:
+    detect_keywords: ["soft keyboard", "keyboard overlap", "hide keyboard", "on-screen keyboard", "keyboard covers"]
+    must_cover:
+      - theme: field-validation
+        keywords: [validation, invalid, required, error]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["error message", "validation message", "invalid input", "required message"]
+          template: "User see [Field Error] message contains {{error_text}}"
+      # No `depth:` on purpose: the claim IS a sighting — after the keyboard is hidden the field
+      # and its action are visible again. Forcing a value assertion here would invent an oracle.
+      - theme: keyboard-overlap
+        keywords: ["soft keyboard", "keyboard overlap", "hide keyboard", "keyboard covers", "keyboard hides"]
+      - theme: submit-correctness
+        keywords: [submit, save, submitted, saved]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["after submit", "saved value", "success message", "after saving"]
+          template: "User see [Success Message] text contains {{success_text}}"
+
+  mobile-auth:
+    detect_keywords: [biometric, fingerprint, "face id", "touch id", "app lock"]
+    must_cover:
+      - theme: credential-validation
+        keywords: [invalid, "wrong password", error, incorrect]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["error message", "invalid credential", "wrong password", "incorrect password"]
+          template: "User see [Login Error] message contains {{error_text}}"
+      - theme: session-persistence
+        keywords: [session, restart, persist, "stays signed in"]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["after restart", "still signed in", "session persists", "remains signed in"]
+          template: "User restart the app … User see [Account Name] text contains {{user_name}}"
+
+  mobile-settings:
+    detect_keywords: ["settings screen", toggle, preference, "settings list", "settings item"]
+    must_cover:
+      - theme: toggle-state-correctness
+        keywords: [toggle, switch, enabled, disabled]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["toggle state", "switch is on", "enabled state", "reflects the", "shows enabled"]
+          template: "User see [Notifications Toggle] text contains {{expected_state}}"
+      - theme: setting-persistence
+        keywords: [persist, restart, saved, "after reopening"]
+        depth:
+          requires: data-assertion
+          cross_screen: false
+          keywords: ["after restart", "setting persists", "still enabled", "saved setting", "after reopening"]
+          template: "User restart the app … User see [Notifications Toggle] text contains {{expected_state}}"
+
   auth:
     detect_keywords: [login, logout, password, signin, "sign in", credential]
     must_cover:
@@ -127,3 +246,29 @@ universal:
     keywords: ["empty", "no data", "no result", "failed", "error state"]
   - theme: accessibility
     keywords: ["keyboard", "tab order", "accessible", "aria", "focus"]
+
+# Same role as `universal`, but only offered to MOBILE targets — `universal` applies to web too,
+# where "rotate to landscape" or "airplane mode" is meaningless.
+#
+# READ THIS BEFORE ADDING TEETH HERE: like `universal`, these themes are REMINDERS. They surface
+# through `universalGaps`, which reaches the audit narrative and the capability sensors but is NOT
+# an input to the score. A theme placed here can never move a number.
+#
+# That is deliberate, not an oversight. These concerns are real on every mobile screen, but not
+# every mobile screen owes every one of them — a settings screen has no deep link, a read-only list
+# has no permission prompt. Scoring them uniformly would penalise honest suites for gaps that are
+# not gaps. The themes that DO carry weight sit in each page-type's `must_cover` above, where they
+# apply to a screen that genuinely owes them.
+mobile_universal:
+  - theme: orientation-stability
+    keywords: [rotate, landscape, portrait, orientation]
+  - theme: connectivity-degraded
+    keywords: ["airplane mode", offline, "wifi", "mobile data", "no connection"]
+  - theme: app-lifecycle-resume
+    keywords: [background, resume, foreground, "returns to the app", restart]
+  - theme: permission-prompt
+    keywords: [permission, grant, denied, allow]
+  - theme: gesture-reachability
+    keywords: [scroll, swipe, "off screen", "below the fold"]
+  - theme: deep-link-entry
+    keywords: ["deep link", deeplink, "universal link"]