@sun-asterisk/sungen 3.2.28 → 3.2.29

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -46,6 +46,12 @@ interface SelectorEntry {
   // === v2: Table ===
   columns?: Record<string, { index: number; header: string; elements?: Record<string, SelectorEntry> }>;
   pagination?: Record<string, string>;
+  // What EVERY row of this table matches, relative to the table locator (issue #688). The table
+  // templates assume an ARIA table — `getByRole('row')`, `tbody` — and on a list built from plain
+  // <div>s that universe is 0 elements, so `is hidden` / `is empty` pass without checking anything.
+  // `rows: 'div.job-row'` replaces the whole row chain. Distinct from a ROW LABEL's own `type: locator`
+  // entry, which positions ONE row (`tbody tr:first-child`) — a shape is a property of the table.
+  rows?: string;
 
   // === v2: Assertion Helpers ===
   attribute?: string;     // Attribute to check (for "has" assertions)
@@ -130,6 +136,7 @@ export interface ResolvedSelector {
   contenteditable?: boolean;  // Rich text editor
   columns?: Record<string, { index: number; header: string; elements?: Record<string, any> }>;
   pagination?: Record<string, string>;
+  rows?: string;        // Row shape, relative to the table (issue #688) — see SelectorEntry.rows
   attribute?: string;   // Attribute to check
   pattern?: string;     // Regex for attribute value
   expanded?: { class?: string; attribute?: string; state?: 'none' };  // Expand/collapse state signal
@@ -150,10 +157,35 @@ export class SelectorResolver {
   private diagnostics?: DiagnosticsCollector;
   private contentNamedRoles: string[] = DEFAULT_CONTENT_NAMED_ROLES;
   private warnedContentNamed = new Set<string>();
+  /** The adapter's target platform — gates the list-member auto-infer (#665). Defaults to web. */
+  private platform: 'web' | 'mobile' = 'web';
 
-  constructor(selectorsDir?: string, screenName?: string) {
+  constructor(selectorsDir?: string, screenName?: string, platform: 'web' | 'mobile' = 'web') {
     this.selectorsDir = selectorsDir || path.join(process.cwd(), 'qa', 'selectors', 'screens');
     this.screenName = screenName;
+    this.platform = platform;
+  }
+
+  /**
+   * A role that resolved with NO accessible name, on the mobile adapter — a dead selector (#665).
+   *
+   * `appium-selector.hbs` renders a role as `~{{name || value}}`, so with no name it emits the role
+   * TOKEN itself: `~listitem`, `~status`. A native a11y tree has no role concept and contains no
+   * such string, so the locator can never match — yet it compiled clean and only failed at run time
+   * with `element with selector "~listitem" wasn't found`.
+   *
+   * The invariant is "role with no name", NOT "role in LIST_MEMBER_ROLES". Both are reachable and
+   * both are dead:
+   *   · auto-infer  — only the three LIST_MEMBER_ROLES are nameless (the other 22 default the label)
+   *   · an entry    — a list-member role withholds the name by design, and `name: null` is the
+   *                   documented opt-out for a content-named role, so `type: role` reaches it too
+   * One predicate covers every door; the CALLERS choose the remedy, because it differs: with no
+   * entry the fix is "add one", with an entry the fix is "change its type".
+   *
+   * Web is unaffected — there the role IS the locator (see LIST_MEMBER_ROLES).
+   */
+  private isUnusableMobileRole(r: ResolvedSelector | null | undefined): boolean {
+    return this.platform === 'mobile' && !!r && r.strategy === 'role' && !r.name;
   }
 
   /** Attach the compile-diagnostics collector (SG-W003) */
@@ -452,11 +484,28 @@ export class SelectorResolver {
     // Auto-infer locator from elementType when no exact YAML entry exists
     if (elementType) {
       const inferred = SelectorResolver.inferFromElementType(elementType, displayLabel);
-      if (inferred) {
+
+      // #665 — auto-infer is an ARIA concept. It survives on mobile only because a label-named
+      // role hands the appium template a `name` to render as an accessibility-id (`[Submit]
+      // button` → `~Submit`, a plausible guess). A nameless role has nothing to hand it, and the
+      // template's `~{{name || value}}` fell through to the role TOKEN — `[Job List] item` →
+      // `~listitem`, a string no Android/iOS a11y tree contains. Clean compile, guaranteed miss.
+      //
+      // Declining rather than warning is what repairs the workflow. `sungen-selector-fix` Phase 0
+      // decides whether to scan the live page by asking whether the ref "can't be auto-inferred";
+      // while auto-infer answered yes, Phase 0 skipped the scan, so no real selector was ever
+      // written and a warning would have reported the breakage with the repair path still switched
+      // off. Declining makes Phase 0 scan, and if it was skipped the not-found throw below names
+      // the exact key to add — the remedy here is "add an entry", which is what that error says.
+      //
+      // Web is untouched: `getByRole('listitem')` with no name is a real, working locator there.
+      if (inferred && !this.isUnusableMobileRole(inferred)) {
         // Same SG-W003 class as the explicit-entry path: an auto-inferred name on a
         // name-from-content role ([Loading] spinner → getByRole('status', { name: 'Loading' }))
         // can never match. Add a YAML entry with name: null to opt out.
-        if (inferred.strategy === 'role' && inferred.name && inferred.role && this.contentNamedRoles.includes(inferred.role)) {
+        // WEB ONLY — see the note at the entry-path emission (#665).
+        if (this.platform !== 'mobile'
+          && inferred.strategy === 'role' && inferred.name && inferred.role && this.contentNamedRoles.includes(inferred.role)) {
           const warnKey = `${inferred.role}:${displayLabel}`;
           if (!this.warnedContentNamed.has(warnKey)) {
             this.warnedContentNamed.add(warnKey);
@@ -584,6 +633,7 @@ export class SelectorResolver {
     if (entry.contenteditable) v2Fields.contenteditable = true;
     if (entry.columns) v2Fields.columns = entry.columns;
     if (entry.pagination) v2Fields.pagination = entry.pagination;
+    if (typeof entry.rows === 'string' && entry.rows.trim()) v2Fields.rows = entry.rows.trim();
     if (entry.attribute) v2Fields.attribute = entry.attribute;
     if (entry.pattern) v2Fields.pattern = entry.pattern;
     if (entry.expanded) v2Fields.expanded = entry.expanded;
@@ -658,7 +708,16 @@ export class SelectorResolver {
         // reference text. For name-from-content roles (status/alert/…) that filter can
         // never match the live element (its accessible name is computed from its content,
         // e.g. a toast's message text) — issue #467. Opt out with `name: null`.
-        if (entry.name === undefined && name && this.contentNamedRoles.includes(value)) {
+        //
+        // WEB ONLY. "The accessible name is computed from content" is an ARIA rule with no mobile
+        // counterpart: the appium template turns a role into an accessibility-id lookup, so
+        // `[Loading] spinner` → `~Loading` is exactly as legitimate a guess as `[Submit] button`
+        // → `~Submit`, which this compiler emits happily. On mobile the warning was therefore a
+        // false positive — and worse, its remedy made things strictly worse: `name: null` leaves
+        // the role nameless, which now renders as the role TOKEN and is refused outright (#665).
+        // A wrong selector fails loudly at run time; advice that manufactures a dead one does not.
+        if (this.platform !== 'mobile'
+          && entry.name === undefined && name && this.contentNamedRoles.includes(value)) {
           const warnKey = `${value}:${originalLabel}`;
           if (!this.warnedContentNamed.has(warnKey)) {
             this.warnedContentNamed.add(warnKey);
@@ -669,14 +728,31 @@ export class SelectorResolver {
             );
           }
         }
-        return withExtras({
-          strategy: 'role',
-          role: value,
-          name: name,  // Use the name field for accessible name
-          value,
-          nth,
-          exact,
-        });
+        {
+          const resolvedRole = withExtras({
+            strategy: 'role',
+            role: value,
+            name: name,  // Use the name field for accessible name
+            value,
+            nth,
+            exact,
+          });
+          // #665 — the same dead selector as the auto-infer path, reached through an ENTRY: a
+          // list-member role withholds its name by design, and `name: null` is the documented
+          // opt-out for a content-named role. Either way a mobile role with no name renders as
+          // the role token. Different remedy from the auto-infer case, so a different message:
+          // the entry exists, it is the TYPE that cannot work here.
+          if (this.isUnusableMobileRole(resolvedRole)) {
+            throw new Error(
+              `Selector "${originalLabel}" is \`type: role, value: ${value}\`${name === null ? ' with `name: null`' : ''}, ` +
+              `which resolves to a role with no accessible name. A native app has no role concept, so this compiles to ` +
+              `the accessibility-id "~${value}" — a string no Android/iOS a11y tree contains, and the step can never match. ` +
+              `Give this entry a locator the device actually exposes: \`type: accessibility-id\` (a content-desc / ` +
+              `accessibilityIdentifier), \`type: xpath\`, or \`type: id\`.`
+            );
+          }
+          return resolvedRole;
+        }
 
       case 'testid':
         return withExtras({

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"]

package/src/harness/parse.ts

@@ -41,6 +41,12 @@ export interface ScenarioInfo {
   ownedByFlow?: string;       // @owned-by:<flow> — the flow that owns this deferred scenario (H6)
   /** Ordered steps with their resolved bucket (And/But inherit) — flow handoff analysis (#569). */
   steps?: Array<{ bucket: 'given' | 'when' | 'then'; text: string }>;
+  /**
+   * The `.feature` this scenario was read from. A unit may hold several (`add --feature`), and
+   * `scenarioIdReuse` scopes its uniqueness check to ONE file — so the sensor needs to know
+   * which. Set by `loadScenarios`; absent on hand-built fixtures, which then count as one file.
+   */
+  sourceFile?: string;
 }
 
 /** Format-tolerant: is this token an ID (project's scheme), not a prose word?
@@ -270,7 +276,7 @@ export function loadScenarios(featurePath: string): ScenarioInfo[] {
   const feature = parser.parseFeatureFile(featurePath);
   return (feature.scenarios || [])
     .filter((s) => !s.stepsName && !s.hookType) // skip @steps/@hook blocks
-    .map((s) => classifyScenario(withBackground(s, feature.background)));
+    .map((s) => ({ ...classifyScenario(withBackground(s, feature.background)), sourceFile: featurePath }));
 }
 
 /**

package/src/harness/repair.ts

@@ -10,6 +10,7 @@ import * as path from 'path';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { scoringCapabilityFor } from './audit';
+import { readCapabilities } from './capability';
 
 export interface RepairProposal { source: 'audit' | 'runtime'; signal: string; ruleId: string; fix: string }
 export interface RepairPlan {
@@ -50,7 +51,13 @@ function failuresFromResult(file: string): string[] {
  */
 export function planRepair(unitId: string, reportName: string, cwd: string, generatedDir?: string): RepairPlan {
   discoverAndRegisterCapabilities();
-  const capId = scoringCapabilityFor(unitId, capabilityRegistry.defaultCapabilityId());
+  // The ACTIVE PLATFORM is part of capability resolution, and leaving it out silently sent every
+  // mobile unit to the web catalog: `scoringCapabilityFor`'s third parameter is what lets `mobile`
+  // beat the default `ui`, `runAudit` passes it, and this call did not. A bare screen on a
+  // `platform: mobile` project therefore resolved to `ui` — whose repair rules are the WEB ones —
+  // so registering a mobile catalog would have changed nothing here. `cwd` is the project root
+  // (the CLI passes `process.cwd()`), which is where `qa/capabilities.yaml` lives.
+  const capId = scoringCapabilityFor(unitId, capabilityRegistry.defaultCapabilityId(), readCapabilities(cwd).platform);
   const rules = (capId ? capabilityRegistry.get(capId)?.repair?.rules : undefined) ?? [];
 
   const signals: { source: 'audit' | 'runtime'; text: string }[] = [];