@sun-asterisk/sungen 3.2.24-beta.5 → 3.2.24

package/src/generators/test-generator/adapters/appium/templates/test-file.hbs

@@ -72,20 +72,38 @@ async function __ensureVisible(selector: string): Promise<WebdriverIO.Element> {
   }
   const safeBottom = Math.round(winH * 0.82); // above the floating bottom-nav band
   let lastY: number | null = null;
+  let lastEl: WebdriverIO.Element | null = null;
   for (let __i = 0; __i < 12; __i++) {
     let y: number | null = null;
+    let existsUndisplayed = false;
     try {
       const el = await $(selector);
       if (await el.isDisplayed()) {
         const r = await driver.getElementRect(el.elementId);
-        if (r.y + r.height <= safeBottom) return el; // rendered AND fully above the floating bottom nav → done
+        // Done when the element sits fully above the floating bottom-nav band — OR is simply too
+        // tall to ever fit there (a scroll container / full-screen list): demanding "fully above"
+        // from such an element makes the loop scroll a page that was already correct, dragging
+        // list-hosted siblings (e.g. the top bar as first list item) out of the viewport.
+        if (r.y + r.height <= safeBottom || r.height >= safeBottom) return el;
         y = r.y;
+        lastEl = el;
+      } else if (el.elementId) {
+        existsUndisplayed = true; // in the tree, just not visible right now
       }
     } catch { /* off-screen / not in tree yet → keep scrolling */ }
+    // Overlay grace (Android mirror of the iOS render grace above): the element is IN the tree but
+    // reports not-displayed — typically a launch popup/overlay covering it that auto-dismisses
+    // within seconds. Scrolling now would carry a list-hosted element (a Compose top bar is often
+    // the first list item) clean out of the viewport, where a down-only loop can never recover it —
+    // so wait the overlay out before the first scroll.
+    if (existsUndisplayed && __i < 4) { await driver.pause(1200); continue; }
     // No-progress break: the element is on screen but a prior scroll didn't move it — it's a FIXED
     // element (e.g. a bottom-nav tab, intentionally in the nav band) or we've hit the end of the
     // scrollable. Stop rather than burn the whole budget; the caller acts on it where it is.
-    if (y !== null && lastY !== null && Math.abs(y - lastY) < 2) return $(selector);
+    // Return the RESOLVED element, never a fresh $() stub: on an animation-churned tree (a looping
+    // banner is enough) a from-scratch re-find takes seconds and outlasts the caller's assertion
+    // budget — the element we just measured is the one the caller should act on.
+    if (y !== null && lastY !== null && Math.abs(y - lastY) < 2) return lastEl ?? $(selector);
     lastY = y;
     await driver.execute('mobile: scrollGesture', { left: 60, top: 420, width: 960, height: 1320, direction: 'down', percent: 0.5 });
     await driver.pause(300);
@@ -116,6 +134,74 @@ async function __assertVisible(selector: string): Promise<void> {
   }
   throw new Error(`Expect ${JSON.stringify(selector)} to be displayed — iOS geometry oracle: rect=${JSON.stringify(r)} is not on screen (0x0 = not rendered / scrolled out)`);
 }
+
+// Checkbox / toggle / radio state oracle. There is NO single authoritative source for it on
+// mobile, and the standard one lies in a way that cannot be detected from the read itself:
+// UiAutomator2 puts `checked` on EVERY Android node and defaults it to "false" when the widget
+// publishes no checked semantics. So a custom-rendered control — a Flutter widget without
+// `Semantics(checked: …)`, an RN `Pressable` without `accessibilityState={ checked: … }` — is not
+// ABSENT from the tree, it reports a confident false while sitting visibly ON, and a strict
+// `toHaveAttribute('checked','true')` fails with no way to see why.
+// Hence: probe every signal both runtimes expose, and let the DIRECTION of the assertion decide
+// how to combine them (__assertCheckedState below).
+//   Android: `checked`, `selected`, isSelected()   iOS: `value` ("1"/"0"), `selected`, isSelected()
+// Descendants are probed too, bounded: on a composite row (label + control merged into one a11y
+// node) the state routinely sits on an inner node while the queried outer node reports the default.
+// A child xpath must start with `.//` — a leading `//` is ABSOLUTE in Appium even when chained.
+async function __probeCheckedSignals(el: WebdriverIO.Element): Promise<{ source: string; value: boolean }[]> {
+  const out: { source: string; value: boolean }[] = [];
+  const read = async (node: WebdriverIO.Element, prefix: string): Promise<void> => {
+    for (const attr of driver.isIOS ? ['value', 'selected'] : ['checked', 'selected']) {
+      let raw: string | null = null;
+      try { raw = await node.getAttribute(attr); } catch { continue; } // attribute unsupported on this node
+      const v = String(raw ?? '').trim().toLowerCase();
+      if (v === 'true' || v === '1') out.push({ source: `${prefix}${attr}="${raw}"`, value: true });
+      else if (v === 'false' || v === '0') out.push({ source: `${prefix}${attr}="${raw}"`, value: false });
+      // anything else (empty, a real iOS `value` string like "Off") carries no parseable state → skip
+    }
+    try { out.push({ source: `${prefix}isSelected()`, value: await node.isSelected() }); } catch { /* not supported here */ }
+  };
+  await read(el, '');
+  // Only descend when the node itself yielded nothing positive — otherwise we already have the
+  // answer and a subtree walk would turn one assertion into dozens of round-trips for nothing.
+  if (!out.some(s => s.value)) {
+    let kids: WebdriverIO.Element[] = [];
+    try { kids = await el.$$('.//*'); } catch { /* no child query on this node */ }
+    for (const k of kids.slice(0, 8)) await read(k, 'descendant.');
+  }
+  return out;
+}
+
+// Assert checked/unchecked from the probed signals. The two directions are deliberately NOT
+// symmetric, because the evidence isn't:
+//   checked   → ANY credible positive signal passes. One runtime exposing the state is enough;
+//               demanding the standard attribute is what breaks custom-rendered controls.
+//   unchecked → NO signal anywhere may be positive. Strictly stronger than reading one attribute,
+//               so a visibly-ON custom toggle can't slip through as a false PASS.
+// Polls like WDIO's own matchers do — a tap-then-assert reads the tree mid-animation.
+// KNOWN LIMIT, stated rather than hidden: on Android a UiAutomator2-defaulted `checked="false"` is
+// indistinguishable from a genuine false — that information is not in the tree. So `unchecked`
+// passes on "no positive signal anywhere", which is the strongest available evidence, not proof.
+async function __assertCheckedState(el: WebdriverIO.Element, expected: boolean, label: string): Promise<void> {
+  // Fail loud with the REAL cause when the element never resolved (mirrors check-action, #430).
+  if (!el.elementId) throw new Error((el as any).error?.message || `Element not found: ${el.selector}`);
+  let signals: { source: string; value: boolean }[] = [];
+  for (let __i = 0; __i < 10; __i++) {
+    signals = await __probeCheckedSignals(el);
+    if (signals.some(s => s.value) === expected) return;
+    await driver.pause(500);
+  }
+  const want = expected ? 'checked' : 'unchecked';
+  if (signals.length === 0) {
+    throw new Error(
+      `Expect ${label} to be ${want} — the control publishes NO checked/selected state, on itself or any child. ` +
+      `A custom-rendered control has to publish it for any tool to read it: Flutter → wrap it in Semantics(checked: …); ` +
+      `React Native → accessibilityState={ checked: … }. Until then assert a visible consequence instead ` +
+      `(a label/text change), or tag the scenario @manual.`,
+    );
+  }
+  throw new Error(`Expect ${label} to be ${want} — read [${signals.map(s => `${s.source} → ${s.value}`).join(', ')}]`);
+}
 {{#if singleAuthRole}}
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -133,7 +219,9 @@ function __authSelector(s: { type: string; value: string }): string {
     case 'accessibility-id': case 'testid': case 'label': case 'placeholder': case 'text': return '~' + s.value;
     case 'android-uiautomator': return 'android=' + s.value;
     case 'ios-predicate': return '-ios predicate string:' + s.value;
-    case 'id': return 'id=' + s.value;
+    // Appium's id strategy prepends `<appPackage>:id/` to colon-less values, which breaks bare
+    // Compose testTagsAsResourceId ids — match those exactly via UiSelector on Android instead.
+    case 'id': return (!driver.isIOS && !s.value.includes(':')) ? 'android=new UiSelector().resourceId("' + s.value + '")' : 'id=' + s.value;
     case 'xpath': case 'locator': default: return s.value;
   }
 }
@@ -205,10 +293,29 @@ async function __ensureAuth(role: string): Promise<void> {
   }
 
   // ── Mode B: legacy authedMarker (present on the landing screen ⟺ logged in) ──
-  const markerPresent = async (): Promise<boolean> => present(cfg.authedMarker, 6000);
-  if (await markerPresent()) return; // idempotent — already authenticated (session kept by noReset)
+  // markerTimeoutMs: contract override for slow-booting apps — a cold start that needs 10-15s+ to
+  // render the landing screen false-negatives the 6s default into "logged out" and then blocks the
+  // spec when the login form never appears.
+  const __budget = cfg.markerTimeoutMs || 6000;
+  // When the contract also names a loggedOutMarker (an element unique to the login screen), the
+  // state is decided by WHICHEVER marker renders first (alternating short probes): a slow-booting
+  // landing screen costs only its real boot time instead of gambling on one fixed timeout, and a
+  // genuine logged-out state is detected without waiting out the full authed budget first.
+  if (cfg.loggedOutMarker) {
+    let loggedOut = false;
+    const __t0 = Date.now();
+    while (Date.now() - __t0 < __budget) {
+      if (await present(cfg.authedMarker, 3000)) return; // logged in — nothing to do
+      if (await present(cfg.loggedOutMarker, 3000)) { loggedOut = true; break; }
+    }
+    if (!loggedOut) {
+      throw new Error(`@auth:${role} could not decide the login state within ${__budget}ms — neither authedMarker nor loggedOutMarker rendered. Check the markers in ${rel}.`);
+    }
+  } else if (await present(cfg.authedMarker, __budget)) {
+    return; // idempotent — already authenticated (session kept by noReset)
+  }
   await runSteps(cfg.loginSteps);
-  if (!(await markerPresent())) {
+  if (!(await present(cfg.authedMarker, __budget))) {
     throw new Error(`@auth:${role} login failed — verify credentials / loginSteps / authedMarker in ${rel}.`);
   }
 }
@@ -267,25 +374,32 @@ describe('{{featureName}}', () => {
     // of cold-starting, which strands top-of-screen elements above the viewport.
     await driver.pause(500);
     await driver.activateApp(__APP_PKG__);
+    // Restore the NATIVE context — a prior scenario that entered a WebView (`switch to [X] frame`)
+    // without switching back would otherwise poison every following native find.
+    try { await driver.switchContext('NATIVE_APP'); } catch { /* single-context session */ }
     // Restore portrait so a prior scenario's `rotate to landscape` can't leak into this one — the
     // app relaunch above resets in-app state, but device orientation is OS-level and persists.
     try { await driver.setOrientation('PORTRAIT'); } catch { /* orientation control not supported */ }
     // Settle after a cold (re)launch: a Flutter app first renders a BLANK accessibility skeleton
     // (nested FrameLayout/View, no content-desc) for several seconds before the real tree appears.
-    // That skeleton is static, so a "two equal reads" check alone false-positives on it and we'd
-    // proceed before any element exists (→ every find fails). So require the tree to (a) contain
-    // rendered content — at least one non-empty content-desc/text — AND (b) be stable across two
-    // reads. A generous timeout covers slow cold renders on a stressed emulator. Best-effort: a
-    // timeout never fails the scenario, it just falls through to the step's own auto-wait.
-    let __prevSrc = '';
+    // So require rendered content — at least one non-empty content-desc/text — on two consecutive
+    // reads before proceeding. A generous timeout covers slow cold renders on a stressed emulator.
+    // Best-effort: a timeout never fails the scenario, it just falls through to the step's own
+    // auto-wait.
+    // "Settled" = rendered content present on TWO consecutive reads. Deliberately NOT full source
+    // equality: a UI with any looping animation (a rotating promo carousel is enough) never yields
+    // two identical snapshots, so an equality oracle starves and burns the whole timeout on every
+    // scenario. Two content-bearing reads still reject the blank first-frame skeleton (no
+    // content-desc/text at all) that a single read could false-positive on.
+    let __prevHadContent = false;
     await driver
       .waitUntil(
         async () => {
           const src = await driver.getPageSource();
           const hasContent = /content-desc="[^"]+"|\btext="[^"]+"/.test(src);
-          const stable = hasContent && src === __prevSrc;
-          __prevSrc = src;
-          return stable;
+          const settled = hasContent && __prevHadContent;
+          __prevHadContent = hasContent;
+          return settled;
         },
         { timeout: 30000, interval: 400, timeoutMsg: 'UI did not settle (no rendered content)' },
       )

package/src/generators/test-generator/template-engine.ts

@@ -43,6 +43,10 @@ export class TemplateEngine {
       return String(text).replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
     });
 
+    Handlebars.registerHelper('includes', function(text: string, search: string) {
+      return typeof text === 'string' && text.includes(search);
+    });
+
     // Comparison helpers for conditional logic
     Handlebars.registerHelper('eq', function(a: any, b: any) {
       return a === b;

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

@@ -677,6 +677,10 @@ export class SelectorResolver {
       case 'android-uiautomator':
       case 'ios-predicate':
       case 'id':
+      // css: only meaningful INSIDE a WebView context (hybrid screens, after `switch to [X]
+      // frame`) — the appium adapter's partial already renders it raw; without this pass-through
+      // the type fell to the placeholder strategy and compiled to an undefined selector.
+      case 'css':
         return withExtras({
           strategy: type,
           value,

package/src/harness/audit.ts

@@ -15,6 +15,7 @@ import { featureFilesFor } from './unit-paths';
 import {
   loadCatalog, viewpointGate, assertionDepth, dataThemesFor, depthThresholdFor, coverageBalance, duplicateClusters, 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';
@@ -235,7 +236,9 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const ledger = viewpointLedger(viewpointPath, scenarios, featureText);
   const negSideEffect = negativeSideEffect(scenarios);
   const ownership = crossArtifactOwnership(screenDir, scenarios);
-  const unsourced = sourceBacked(scenarios, parseSpecClauses(specPath).frs.map((f) => f.id), parseViewpointItems(viewpointPath).map((i) => i.text), viewpoints.map((v) => v.id), featureText);
+  // @exploration scenarios are probes outside the official suite — the finding's own fix
+  // ("tag it @exploration") must actually exempt them from source tracing.
+  const unsourced = sourceBacked(scenarios.filter((s) => !s.exploration), parseSpecClauses(specPath).frs.map((f) => f.id), parseViewpointItems(viewpointPath).map((i) => i.text), viewpoints.map((v) => v.id), featureText);
 
   // H3 — stateful-flow regression depth. For a UI flow whose scenarios mutate a cart/checkout
   // collection, the regression dimensions (count/quantity proof · teardown · multi-source) cap the
@@ -303,7 +306,13 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   //     that rewrites that file scores them 100% by construction — which is exactly
   //     what a create-test run did, silently dropping the performance viewpoint on
   //     the way. While the declaration is unconfirmed, neither axis is evidence.
-  const viewpointMoved = viewpointBaseline.status === 'changed';
+  const adoptedPostHoc = viewpointBaseline.status === 'new' && scenarios.length > 0;
+  // `changed` was the only untrusted state, but `new` alongside an EXISTING suite is the same
+  // problem seen earlier: the yardstick is being introduced against scenarios that already exist,
+  // 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;
   // #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
@@ -574,6 +583,9 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   } else if (balance.imbalanced && !flowScored) {
     findings.push(`BALANCE: ${balance.note} Stop expanding secondary viewpoints until business-core gaps are filled.`);
   }
+  if (adoptedPostHoc) {
+    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\`.`);
+  }
   if (!hasYardstick) {
     const lost = [
       'atomicLedger', 'traceability',
@@ -658,6 +670,31 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   if (depth.deferredBusinessCritical > 0 && depth.deferredBusinessCritical >= depth.businessCriticalTotal) {
     findings.push(`DEPTH-DEFERRED: businessDepth ${businessDepth.toFixed(2)} is computed over only ${depth.businessCriticalTotal} on-screen scenario(s); ${depth.deferredBusinessCritical} business-critical scenario(s) are deferred to @manual (excluded from the ratio). Automate them in a flow and verify with \`sungen flow-check\` — this ratio is NOT "all business depth covered".`);
   }
+  // #622 — a claim that names a count, proved by fewer assertions than it names. The count sits
+  // in the viewpoint CLAIM, so both the title-level and the claim-level shape are checked.
+  for (const g of ledger.partial.slice(0, 5)) {
+    findings.push(`CLAIM-PARTIAL: claim ${g.id ?? ''} names ${g.claimed} but its scenario asserts ${g.asserted} value(s) — "${g.text.slice(0, 70)}". Mapping a claim to a scenario id proves it is ADDRESSED, not that the oracle demonstrates it: assert all ${g.claimed}, use a \`see all …\` set assertion, or narrow the claim to what is actually proven.`);
+  }
+  for (const g of numericClaimGaps(scenarios).slice(0, 3)) {
+    findings.push(`CLAIM-PARTIAL: "${g.name}" claims ${g.claimed} ${g.noun} but asserts ${g.asserted} value(s) — assert all ${g.claimed}, or say in the title what the scenario actually proves.`);
+  }
+  // #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 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 };
+      cur.n++;
+      byId.set(m.id, cur);
+    }
+    for (const [id, v] of [...byId.entries()].slice(0, 5)) {
+      findings.push(`PRIORITY-CONTRADICTED: the viewpoint declares ${id} as "${v.declared}" but ${v.n} of its scenario(s) are tagged @${v.tagged}. A smoke run selects on the tag, so it picks up work the declaration deprioritised — reconcile them, and if the tag is right, fix the declaration rather than leaving both on record.`);
+    }
+  }
+  if (ledger.manualOnly.length > 0) {
+    findings.push(`VIEWPOINT-ITEM-MANUAL-ONLY: ${ledger.manualOnly.length} viewpoint claim(s) are carried only by @manual scenarios — ${ledger.manualOnly.slice(0, 4).map((m) => m.id).join(', ')}${ledger.manualOnly.length > 4 ? ', …' : ''}. The claim is ADDRESSED (a procedure exists) but nothing runs for it, so a regression would not notice it breaking. \`atomicLedger\` counts them, because the design work is real — the delivery must not report them as automated coverage.`);
+  }
   if (ledger.hasViewpoint && ledger.missing.length) {
     const sample = ledger.missing.slice(0, 6).map((m) => m.id || `"${m.text}"`).join(', ');
     findings.push(`VIEWPOINT-ITEM-MISSING: ${ledger.missing.length}/${ledger.total} atomic viewpoint items have no covering scenario (${(ledger.ratio * 100).toFixed(0)}% covered) — e.g. ${sample}. Cover each item or mark it deferred/spec-gap.`);

package/src/harness/capability-plan.ts

@@ -153,7 +153,9 @@ export function manualReasonMismatches(featurePath: string): ReasonMismatch[] {
     for (let k = i + 1; k < lines.length && k <= i + 16; k++) {
       const l = lines[k].trim();
       if (/^#/.test(l)) parts.push(l.replace(/^#+\s*/, ''));
-      else if (l === '') continue;
+      // A blank line after collected comments ends the body block — scanning past it would
+      // swallow the NEXT section's banner comment and mis-infer the reason code from it.
+      else if (l === '') { if (parts.length) break; continue; }
       else break;
     }
     // The block scanned here includes the tester PROCEDURE, so several codes can

package/src/harness/parse.ts

@@ -36,6 +36,7 @@ export interface ScenarioInfo {
   queryRefs?: string[];       // named queries referenced by this scenario (inline `query [name]` + @query: tags)
   apiRefs?: string[];         // named API endpoints referenced by this scenario (@api: tags)
   requiresCaps?: string[];    // @requires:<cap> — automation-ready but needs an opt-in driver (TQ-11)
+  exploration?: boolean;      // @exploration — a probe outside the official suite, exempt from source tracing
   deferredToFlow?: boolean;   // @deferred:flow — owned by a flow, not automated on this screen (H6)
   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). */
@@ -253,6 +254,7 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
     queryRefs: queryRefs.size ? [...queryRefs] : undefined,
     apiRefs: apiRefs.size ? [...apiRefs] : undefined,
     requiresCaps: requiresCaps.length ? requiresCaps : undefined,
+    exploration: tags.some((t) => /^@exploration\b/i.test(t)) || undefined,
     deferredToFlow: deferredToFlow || undefined,
     ownedByFlow,
   };

package/src/harness/script-check.ts

@@ -197,8 +197,12 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
   // ONLY the template form, so on the current codegen every @cases scenario was
   // reported MISSING (+ its test EXTRA) despite compiling and running fine.
   // Canonicalize the extracted title to the bare scenario name so both shapes
-  // (and plain titles) compare on the same footing.
-  const canonSpecTitle = (t: string) => t.replace(/\s*—(\s*\$\{__row\.__label\})?$/, '');
+  // (and plain titles) compare on the same footing. Mobile/mocha specs append the
+  // tags to the title (`it('<name> [@high @spec:FR-01]')` — mocha has no tag option),
+  // so strip that suffix too or every mobile scenario reads MISSING + EXTRA (#429).
+  const canonSpecTitle = (t: string) => t
+    .replace(/\s*\[@[^\]]*\]$/, '')
+    .replace(/\s*—(\s*\$\{__row\.__label\})?$/, '');
   const specTitleSet = new Set(specTitles.map(canonSpecTitle));
   const expectedSet = new Set(automated.map((s) => s.name));
   const missingInSpec = automated.filter((s) => !specTitleSet.has(s.name)).map((s) => s.name);

package/src/harness/sensors.ts

@@ -17,6 +17,8 @@ import { readTextFile } from './read-text';
 const BUSINESS_CRITICAL_CATS = [
   // UI commerce cores
   'LIST', 'CART', 'PRODUCT', 'FILTER', 'CHECKOUT', 'ORDER', 'DETAIL', 'DISCOVERY', 'CATEGORY', 'BRAND', 'DUPLICATE', 'CONSISTENCY',
+  // Payment surfaces are business-core in any commerce/fintech app (JALPAY, PAYMENT, WALLET …)
+  'PAY', 'WALLET',
   // API / DB capability cores — for an api/db suite the operation IS the business core
   'API', 'ENDPOINT', 'CRUD', 'QUERY', 'CONTRACT', 'RESOURCE',
 ];
@@ -27,7 +29,9 @@ const BUSINESS_CRITICAL_CATS = [
 const BUCKET_ORDER: Array<[string, string[]]> = [
   ['business-core', BUSINESS_CRITICAL_CATS],
   ['behavior', ['LOGIC', 'TRANSITION', 'WORKFLOW']],
-  ['validation-security', ['VAL', 'SEC', 'SUB', 'AUTH', 'LOGIN']],
+  // ERROR/EMPTY: error handling and empty-state guards are the same defensive family as
+  // validation — every non-trivial suite declares them, so `other` would swallow them.
+  ['validation-security', ['VAL', 'SEC', 'SUB', 'AUTH', 'LOGIN', 'ERROR', 'EMPTY']],
   ['navigation', ['NAV']],
   ['presentation', ['UI', 'LAYOUT', 'RESPONSIVE', 'DISPLAY', 'SEO', 'ACCESSIBILITY', 'USABILITY', 'VISUAL']],
 ];
@@ -843,3 +847,71 @@ export function claimProof(scenarios: ScenarioInfo[], focus = 'functional'): Cla
 
   return { total: measured.length, withClaims, proven, unproven, ratio, focus, threshold, verdict };
 }
+
+// ---------- Numeric claims, and priority that disagrees with the declaration ----------
+
+const NUMBER_WORDS: Record<string, number> = {
+  two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+};
+
+/**
+ * A title that names a COUNT, proved by fewer assertions than it claims.
+ *
+ * "restores all **six** buffered values" asserted four fields; "all **seven** confirmation rows
+ * are read-only" checked two. Exact id mapping made both read as covered, and `claimProof` had no
+ * rule for it — a claim can be mapped to a scenario and still be only partly proven, which is the
+ * gap between "declared coverage" and "coverage an oracle demonstrates" (#622).
+ *
+ * Counting is the whole point here: the number is in the title, so the check is arithmetic rather
+ * than semantic. A `see all …` assertion is exempt — it proves a set in one step, which is the
+ * stronger shape, not a weaker one.
+ */
+export function numericClaimGaps(scenarios: ScenarioInfo[]): Array<{ name: string; claimed: number; asserted: number; noun: string }> {
+  const out: Array<{ name: string; claimed: number; asserted: number; noun: string }> = [];
+  for (const s of scenarios) {
+    if (s.manual) continue;                                  // a procedure counts by hand
+    if (/\bsee all\b/.test(s.stepsText)) continue;            // a set proved in one assertion
+    const m = s.name.toLowerCase().match(/\b(?:all\s+)?(two|three|four|five|six|seven|eight|nine|ten|[2-9]|10)\s+([a-z][a-z-]{2,})/);
+    if (!m) continue;
+    const claimed = NUMBER_WORDS[m[1]] ?? Number(m[1]);
+    if (!Number.isFinite(claimed) || claimed < 2) continue;
+    // Only value-bearing assertions count: `see [X] … with/contains {{v}}`. A visibility check
+    // does not demonstrate one of N values.
+    const asserted = (s.stepsText.match(/\bsee \[[^\]]+\][^|]*?\b(?:with|contains) \{\{/g) ?? []).length;
+    if (asserted > 0 && asserted < claimed) out.push({ name: s.name, claimed, asserted, noun: m[2] });
+  }
+  return out;
+}
+
+/**
+ * A scenario whose priority tag contradicts the priority its viewpoint declares.
+ *
+ * The Priority-Viewpoints table is where release selection is supposed to come from. When the
+ * table says a flow is `Low` and its scenario is tagged `@high`, a smoke run picks up work the QA
+ * deliberately deprioritised — and nobody can tell which of the two was the decision (#622).
+ */
+export function priorityMismatches(
+  viewpointText: string, scenarios: ScenarioInfo[],
+): Array<{ id: string; declared: string; tagged: string; scenario: string }> {
+  const declared = new Map<string, string>();
+  for (const m of viewpointText.matchAll(/^\|\s*((?:VP|FL)[A-Z0-9._-]*)\s*\|\s*(critical|high|medium|normal|low|deferred)\s*\|/gim)) {
+    declared.set(m[1].toUpperCase(), m[2].toLowerCase());
+  }
+  if (declared.size === 0) return [];
+  // `medium` and `normal` are the same rank under different names in real documents.
+  const rank = (p: string): string => (p === 'medium' ? 'normal' : p);
+  const out: Array<{ id: string; declared: string; tagged: string; scenario: string }> = [];
+  for (const s of scenarios) {
+    const id = (s.vpId ?? '').toUpperCase();
+    if (!id) continue;
+    // The most specific declared row that prefixes this id.
+    const key = [...declared.keys()].filter((k) => id.startsWith(k)).sort((a, b) => b.length - a.length)[0];
+    if (!key) continue;
+    const want = rank(declared.get(key)!);
+    const got = rank(String(s.priority).toLowerCase());
+    // `critical` and `deferred` have no tag equivalent — nothing to contradict.
+    if (want === 'critical' || want === 'deferred') continue;
+    if (want !== got) out.push({ id: key, declared: declared.get(key)!, tagged: got, scenario: s.name });
+  }
+  return out;
+}

package/src/harness/viewpoint-ledger.ts

@@ -20,6 +20,39 @@ export interface LedgerResult {
   covered: number;
   ratio: number;
   missing: { id?: string; text: string }[];
+  /**
+   * Items whose id is carried ONLY by `@manual` scenarios. Accounted for — a documented
+   * procedure exists — but nothing runs, so a regression would not notice. Counted as covered
+   * (the claim IS addressed) and reported separately, the same split `FLOW-MANUAL-ONLY` makes
+   * for declared flows (#622).
+   */
+  manualOnly: { id?: string; text: string }[];
+  /**
+   * Items whose CLAIM names a count that the scenario carrying its id does not fully assert —
+   * "restores all six buffered values" proved on four fields. Exact id mapping shows a claim is
+   * ADDRESSED; it says nothing about whether the oracle demonstrates all of it (#622).
+   */
+  partial: { id?: string; text: string; claimed: number; asserted: number }[];
+}
+
+const NUMBER_WORDS: Record<string, number> = {
+  two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+};
+
+/** The count a claim names, when it names one: "all six values", "seven rows", "3 items". */
+function claimedCount(text: string): number | null {
+  // A digit after `step`/`screen`/`phase` is an ORDINAL, not a quantity — "the buffer exists at
+  // step 4" claims nothing about four of anything. And the counted thing has to be a noun: a
+  // function word after the number means the number was not counting.
+  const FUNCTION_WORD = /^(and|the|is|are|was|were|of|or|in|on|at|to|for|with|that|which|but|not|has|have|its)$/;
+  for (const m of text.toLowerCase().matchAll(/(\w+\s+)?\b(?:all\s+)?(two|three|four|five|six|seven|eight|nine|ten|[2-9]|10)\s+([a-z][a-z-]{2,})/g)) {
+    const before = (m[1] ?? '').trim();
+    if (/^(step|steps|screen|screens|phase|phases|page|pages|tier|round|part|section|version|mail_0?)$/.test(before)) continue;
+    if (FUNCTION_WORD.test(m[3])) continue;
+    const n = NUMBER_WORDS[m[2]] ?? Number(m[2]);
+    if (Number.isFinite(n) && n >= 2) return n;
+  }
+  return null;
 }
 
 const ID_RE = /\b([A-Z]{1,5}\d{0,2}(?:[.\-][A-Za-z0-9]+)*-?\d{0,3})\b/; // VP0.Title, VP7-002, MS-HP-001, TV-01
@@ -74,16 +107,43 @@ export function parseViewpointItems(viewpointPath: string): { id?: string; text:
 export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[], featureText: string): LedgerResult {
   const items = parseViewpointItems(viewpointPath);
   if (!fs.existsSync(viewpointPath) || items.length === 0) {
-    return { hasViewpoint: fs.existsSync(viewpointPath), total: 0, covered: 0, ratio: 1, missing: [] };
+    return { hasViewpoint: fs.existsSync(viewpointPath), total: 0, covered: 0, ratio: 1, missing: [], manualOnly: [], partial: [] };
   }
   const featLower = featureText.toLowerCase();
   const missing: { id?: string; text: string }[] = [];
+  const manualOnly: { id?: string; text: string }[] = [];
+  const partial: { id?: string; text: string; claimed: number; asserted: number }[] = [];
   let covered = 0;
 
   for (const item of items) {
-    let isCovered = false;
-    if (item.id && featLower.includes(item.id.toLowerCase())) isCovered = true;
-    else {
+    // WHEN AN ITEM DECLARES AN ID, THAT ID IS THE CONTRACT. It used to fall through to word
+    // matching when the id was absent from the suite, so an item whose id nobody carried was
+    // still counted covered on two shared non-generic words with ANY scenario. Two claims written
+    // deliberately WITHOUT a scenario were both scored covered — one on
+    // "confirmation"/"buffered", the other on "name"/"blocked". `atomicLedger 100%` then meant
+    // "no claim is more than two words away from some scenario", which is not a coverage
+    // statement at all, and the ledger could never report the gap it exists to report (#622).
+    //
+    // Word matching survives only where there is nothing better: a prose claim with no id.
+    let isCovered: boolean;
+    if (item.id) {
+      isCovered = featLower.includes(item.id.toLowerCase());
+      if (isCovered) {
+        // An id carried only by @manual scenarios is ADDRESSED but not RUNNING.
+        const carriers = scenarios.filter((s) => (s.vpId ?? '').toLowerCase() === item.id!.toLowerCase()
+          || s.haystack.includes(item.id!.toLowerCase()));
+        if (carriers.length > 0 && carriers.every((s) => s.manual)) manualOnly.push({ id: item.id, text: item.text });
+        // The count is in the CLAIM, not in the scenario title — so this is the only place both
+        // halves are in hand. `see all …` proves a set in one step and is exempt.
+        const n = claimedCount(item.text);
+        const auto = carriers.filter((s) => !s.manual);
+        if (n !== null && auto.length > 0 && !auto.some((s) => /\bsee all\b/.test(s.stepsText))) {
+          const asserted = Math.max(...auto.map((s) =>
+            (s.stepsText.match(/\bsee \[[^\]]+\][^|]*?\b(?:with|contains) \{\{/g) ?? []).length));
+          if (asserted > 0 && asserted < n) partial.push({ id: item.id, text: item.text, claimed: n, asserted });
+        }
+      }
+    } else {
       const words = [...new Set((item.text.toLowerCase().match(/[a-z][a-z-]{3,}/g) || []).filter((w) => !GENERIC.has(w)))];
       const need = Math.min(2, words.length);
       isCovered = words.length > 0 && scenarios.some((s) => words.filter((w) => s.haystack.includes(w)).length >= need);
@@ -92,7 +152,10 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
     else missing.push({ id: item.id, text: item.text });
   }
 
-  return { hasViewpoint: true, total: items.length, covered, ratio: items.length ? covered / items.length : 1, missing };
+  return {
+    hasViewpoint: true, total: items.length, covered,
+    ratio: items.length ? covered / items.length : 1, missing, manualOnly, partial,
+  };
 }
 
 /**

package/src/orchestrator/mobile-runtime-scaffolder.ts

@@ -61,7 +61,11 @@ export function emitMobileRuntime(cwd: string, opts: MobileInitOptions): Scaffol
       // appActivity is optional — leave empty when not provided so UiAutomator2
       // auto-resolves the launcher activity from appPackage. Only pin when explicitly passed.
       .replace('__APP_ACTIVITY__', opts.appActivity || '')
-      .replace('__ANDROID_UDID__', opts.androidUdid || 'emulator-5554')
+      // GLOBAL replace: the template holds this placeholder twice (the connectivity self-heal
+      // helper + the 'appium:udid' capability, #615). String-form .replace would fill only the
+      // first and ship a literal '__ANDROID_UDID__' as the session udid. Do NOT globalize the
+      // others: __APP_ACTIVITY__/__IOS_VERSION__ keep a second occurrence as sentinel comparisons.
+      .replace(/__ANDROID_UDID__/g, opts.androidUdid || 'emulator-5554')
       .replace('__IOS_BUNDLE_ID__', opts.iosBundleId || 'com.example.app')
       .replace('__IOS_DEVICE__', opts.iosDevice || 'iPhone 16')
       .replace('__IOS_VERSION__', opts.iosVersion || '18.0');

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -81,6 +81,29 @@ contract cannot stand in: the viewpoint is the one artifact that must stay **ind
 you generated**. That is why a filled one is an INPUT you never rewrite, and why authoring it
 FIRST — from the spec, before the scenarios exist — is the only order that keeps it honest.
 
+**If you find yourself writing it AFTER the suite, stop and say so.** That is not a neutral
+ordering choice: a yardstick derived from the scenarios reads 100% by construction, and anything
+dropped along the way stops being missing from anything. `sungen audit` now reports
+`VIEWPOINT-ADOPTED-POST-HOC` on the first sighting of a viewpoint alongside an existing suite and
+holds `atomicLedger` + `traceability` as unverified until a human accepts it — so the honest move
+is to write the claims from `spec.md` and the contract, mark plainly that they are a draft for QA
+review, and let the QA revise before `--accept-viewpoint`.
+
+**When you give a claim an id, a scenario must carry that id.** The id is the contract: a claim
+whose id no scenario carries is reported MISSING, and word overlap will not rescue it. Several
+scenarios may prove one claim, and a claim carried only by `@manual` scenarios is `ADDRESSED` but
+not running (`VIEWPOINT-ITEM-MANUAL-ONLY`) — do not let the delivery read it as automated coverage.
+
+**A claim that names a count must be proved that many times.** "restores all six buffered values"
+asserted on four fields is `CLAIM-PARTIAL`: mapping a claim to a scenario shows it is addressed,
+not that the oracle demonstrates it. Assert all of them, use one `see all …` set assertion, or
+narrow the claim to what is actually proven.
+
+**Priority comes from the declaration.** A scenario tagged `@high` under a viewpoint row that says
+`Low` is `PRIORITY-CONTRADICTED` — a smoke run selects on the tag, so it picks up work the QA
+deliberately deprioritised. Inherit the declared priority; if the tag is right, fix the
+declaration instead of leaving both on record.
+
 ---
 
 ## Platform detection (do this FIRST)