@sun-asterisk/sungen 3.2.2-beta.11 → 3.2.2-beta.14

package/src/harness/audit.ts

@@ -146,7 +146,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const capGate = scoringCap?.gateProvider as
     ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus; cwd: string; screenName: string; threshold: number; businessCriticalMethods?: string[] }) => { gate: GateResult; depth: DepthResult }) | undefined;
   const provided = capGate?.({ scenarios, viewpoints, catalog, focus: intent.focus, cwd: projectRootFromScreenDir(screenDir), screenName: catalogScreenName, threshold: depthThresholdFor(intent.focus), businessCriticalMethods: intent.businessCriticalMethods });
-  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog);
+  const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog, platform === 'mobile');
   const depth = provided?.depth ?? assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
 
   // TQ-4 — deferral-aware coverage credit: an inherently cross-screen theme (cart / detail /

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

@@ -91,6 +91,21 @@ page_types:
           keywords: ["success message", "saved", "created", "confirmation"]
           template: "User see [Success] message with {{success_text}}"
 
+  # Mobile launcher / home screen (Appium). Display + navigation only — no web form/validation.
+  # A `mobile-*` candidate (considered ONLY for mobile targets; never for web). Keywords are
+  # launcher-DISTINCTIVE (a tab-bar landing screen) and deliberately exclude generic tokens like
+  # "tab"/"navigation"/"home" that a mobile commerce/list screen also carries — so such a screen
+  # still selects ecommerce-list, not mobile-home. Both themes are presence/navigation (no `depth:`)
+  # — seeing the content and leaving Home (a destination marker OR the Home-only anchor going
+  # `is hidden`) IS the assertion; no data-assertion is forced.
+  mobile-home:
+    detect_keywords: ["bottom navigation", launcher, greeting, "home screen", "launcher screen"]
+    must_cover:
+      - theme: content-visibility
+        keywords: [displayed, render, loads, exposes, shown, visible]
+      - theme: navigation-correctness
+        keywords: [tap, navigate, "leaves home", "is hidden", opens, navigation]
+
   auth:
     detect_keywords: [login, logout, password, signin, "sign in", credential]
     must_cover:

package/src/harness/journey.ts

@@ -116,19 +116,31 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
     detail: autoPending ? `${audit.automatableManual.automatable} @manual scenario(s) a driver could automate` : 'no capability-pending automatable cases',
   });
 
-  // Human sign-off: always pending until S5 explicit signoff; carries the review-queue count.
-  const manualCount = (audit.manualOracle && audit.manualOracle.total) || 0;
+  // Needs-you: the review queue. Prefer PRECISE per-scenario anchors from audit's structured
+  // depth data — each shallow business-critical scenario carries its own VP id — over regex-parsing
+  // the aggregate "DEPTH:" finding string (which names no scenario, so points nowhere). Then
+  // supplement with the remaining human-judgment findings.
+  const shallowBC: { name: string; category?: string }[] = (audit.depth && audit.depth.shallowBusinessCritical) || [];
+  for (const s of shallowBC) {
+    needsYou.push({
+      text: `DEEPEN — "${s.name}": assert data, not just visibility (\`… with {{value}}\` / \`see all … contain {{v}}\`), or defer cross-screen with @manual + reason.`,
+      anchor: extractAnchor(s.name),
+    });
+  }
+  const haveStructuredDepth = shallowBC.length > 0;
+  for (const f of (audit.findings || [])) {
+    if (!isHumanFinding(f)) continue;
+    if (haveStructuredDepth && /^\s*DEPTH\b/i.test(f)) continue; // superseded by the per-scenario items above
+    needsYou.push({ text: f, anchor: extractAnchor(f) });
+  }
+
+  // Human sign-off: always pending until S5 explicit signoff; carries the now-final review-queue count.
+  const manualCount = (audit.manualOracle && (audit.manualOracle.manualTotal ?? audit.manualOracle.total)) || 0;
   obligations.push({
     id: 'OB-signoff', title: 'Human sign-off', status: 'pending',
-    detail: `${needsYou.length} item(s) queued for your review (single sign-off at the end)`,
+    detail: `${needsYou.length} item(s) queued for your review · ${manualCount} @manual scenario(s)`,
   });
 
-  // Needs-you: human-judgment findings (the review-queue seed), with their anchors (titles) intact.
-  for (const f of (audit.findings || [])) if (isHumanFinding(f)) needsYou.push({ text: f, anchor: extractAnchor(f) });
-  // Re-stamp the signoff detail now that needsYou is filled.
-  const signoff = obligations.find((o) => o.id === 'OB-signoff');
-  if (signoff) signoff.detail = `${needsYou.length} item(s) queued for your review · ${manualCount} @manual scenario(s)`;
-
   // Next suggested = first non-satisfied obligation; if all satisfied but run-test not done → run.
   const firstGap = obligations.find((o) => o.status !== 'satisfied' && o.id !== 'OB-signoff');
   let nextSuggested: string;
@@ -331,3 +343,92 @@ export function renderGate(v: GateVerdict): string {
   L.push('');
   return L.join('\n');
 }
+
+// ---------------- #409: project-level roll-up across all units ----------------
+//
+// Multi-unit fan-out PARALLELISES generation but human review/sign-off must stay SERIAL — you can't
+// judge N boards at once. This roll-up is that serial surface: one row per unit (gate · score · phase
+// · what it still needs), and a single "review this next" pointer. The per-unit board is unchanged;
+// this only aggregates the same read-only `runJourney` synthesis.
+
+export type UnitKind = 'screen' | 'flow' | 'api';
+export interface UnitSummary {
+  unit: string;
+  kind: UnitKind;
+  score: number | null;
+  gateStatus: string | null;
+  youAreHere: string;
+  obligationsOpen: number;   // non-satisfied, non-waived (excludes OB-signoff)
+  reviewQueue: number;
+  signedOff: boolean;
+  started: boolean;          // has an audit report yet
+}
+
+/** Discover every unit under qa/screens, qa/flows, and qa/api top-level areas. */
+export function listUnits(projectRoot: string): { unit: string; kind: UnitKind }[] {
+  const out: { unit: string; kind: UnitKind }[] = [];
+  const scan = (sub: string, kind: UnitKind) => {
+    const d = path.join(projectRoot, 'qa', sub);
+    if (!fs.existsSync(d)) return;
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      // 'flows' under qa/api is a container for api-flows (a nested tier) — not a unit itself.
+      if (e.isDirectory() && !(sub === 'api' && e.name === 'flows')) out.push({ unit: e.name, kind });
+    }
+  };
+  scan('screens', 'screen');
+  scan('flows', 'flow');
+  scan('api', 'api');
+  return out;
+}
+
+/** Roll up every unit's journey into one table of summaries (serial review surface). */
+export function rollupJourney(projectRoot: string): UnitSummary[] {
+  return listUnits(projectRoot).map(({ unit, kind }) => {
+    const r = runJourney(projectRoot, unit);
+    const signedOff = r.obligations.find((o) => o.id === 'OB-signoff')?.status === 'satisfied';
+    const obligationsOpen = r.obligations.filter(
+      (o) => o.id !== 'OB-signoff' && o.status !== 'satisfied' && o.status !== 'waived',
+    ).length;
+    return {
+      unit, kind, score: r.score, gateStatus: r.gateStatus, youAreHere: r.youAreHere,
+      obligationsOpen, reviewQueue: r.needsYou.length, signedOff,
+      started: r.generatedFrom.includes('audit'),
+    };
+  });
+}
+
+function unitStatusLabel(r: UnitSummary): string {
+  if (!r.started) return '◻️ not started';
+  if (r.signedOff) return '✅ signed off';
+  if (r.obligationsOpen > 0) return `⏳ ${r.obligationsOpen} obligation(s) open`;
+  if (r.reviewQueue > 0) return `🔎 review ${r.reviewQueue} item(s)`;
+  return '🟡 ready to sign off';
+}
+
+export function renderRollupBoard(rows: UnitSummary[]): string {
+  const L: string[] = [];
+  L.push('# Journey roll-up — all units');
+  L.push('');
+  if (!rows.length) {
+    L.push('No units found under `qa/screens`, `qa/flows`, or `qa/api`.');
+    return L.join('\n');
+  }
+  L.push('| Unit | Kind | Score | Gate | Phase | Needs |');
+  L.push('|---|---|---|---|---|---|');
+  for (const r of rows) {
+    L.push(`| ${r.unit} | ${r.kind} | ${r.score ?? '—'} | ${r.gateStatus ?? '—'} | ${r.youAreHere} | ${unitStatusLabel(r)} |`);
+  }
+  L.push('');
+  const blocked = rows.filter((r) => r.started && (r.obligationsOpen > 0));
+  const toReview = rows.filter((r) => r.started && r.obligationsOpen === 0 && !r.signedOff && r.reviewQueue >= 0);
+  const notStarted = rows.filter((r) => !r.started);
+  L.push(`**${rows.filter((r) => r.signedOff).length}/${rows.length} signed off** · ${blocked.length} with open obligations · ${notStarted.length} not started.`);
+  L.push('');
+  L.push('## → Next (review is serial — one unit at a time)');
+  const next = blocked[0] || toReview[0] || notStarted[0];
+  if (!next) L.push('All units signed off — `sungen delivery` to export.');
+  else if (!next.started) L.push(`Generate **${next.unit}** — \`/sungen:create-test ${next.unit}\`.`);
+  else L.push(`Review **${next.unit}** (${unitStatusLabel(next)}) — \`sungen journey --screen ${next.unit}\`, then sign off.`);
+  L.push('');
+  return L.join('\n');
+}

package/src/harness/sensors.ts

@@ -59,9 +59,17 @@ export function loadCatalog(): Catalog {
   return parseYaml(fs.readFileSync(p, 'utf-8')) as Catalog;
 }
 
+// Word-aware keyword match: `\b<kw>(s|es|ed|ing)?\b`, so a keyword matches whole words (plus
+// simple plural/verb suffixes) but NOT as a substring of a larger word — e.g. `form` must not
+// match inside `Format` or `@platform`, while `product` still matches `products`. Multi-word
+// keywords ("add to cart", "is hidden") match the phrase with a boundary at each end.
+const wordRe = (kw: string) => {
+  const esc = kw.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`\\b${esc}(?:s|es|ed|ing)?\\b`);
+};
 const has = (haystacks: string[], kw: string) => {
-  const k = kw.toLowerCase();
-  return haystacks.some((h) => h.includes(k));
+  const re = wordRe(kw);
+  return haystacks.some((h) => re.test(h));
 };
 
 // ---------- Sensor 1: Viewpoint Gate (catalog-driven) ----------
@@ -75,16 +83,21 @@ export interface GateResult {
   universalGaps: string[];
 }
 
-export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog): GateResult {
+export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEntry[], catalog: Catalog, isMobile = false): GateResult {
   const haystacks = [
     ...scenarios.map((s) => s.haystack),
     ...viewpoints.map((v) => `${v.id} ${v.reason}`.toLowerCase()),
   ];
 
-  // Detect page-type by detect_keywords hit count
+  // Detect page-type by detect_keywords hit count. `mobile-*` page-types are candidates ONLY for
+  // mobile targets; web targets never consider them. Mobile targets still consider the web types
+  // too, so a mobile commerce/form screen is selected as ecommerce-list/form by keyword fit —
+  // `mobile-home` does not crowd out a better-fitting type. With no type matching → pageType stays
+  // null → no themes required → the gate passes leniently rather than false-FAILing.
   let pageType: string | null = null;
   let best = 0;
   for (const [pt, def] of Object.entries(catalog.page_types)) {
+    if (pt.startsWith('mobile-') && !isMobile) continue;
     const hits = def.detect_keywords.filter((k) => has(haystacks, k)).length;
     if (hits > best) { best = hits; pageType = pt; }
   }
@@ -97,10 +110,14 @@ export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEn
       // Scenarios that cover this theme by keyword (include @manual — a manual
       // scenario with a real assertion still covers the viewpoint for design).
       const coverers = scenarios.filter((s) => t.keywords.some((k) => s.haystack.includes(k.toLowerCase())));
-      const deep = coverers.some((s) => s.hasDataAssertion);
-      if (deep) covered++;
-      else if (coverers.length > 0) gaps.push({ theme: t.theme, keywords: t.keywords, status: 'shallow' });
-      else gaps.push({ theme: t.theme, keywords: t.keywords, status: 'missing' });
+      if (coverers.length === 0) { gaps.push({ theme: t.theme, keywords: t.keywords, status: 'missing' }); continue; }
+      // A theme WITHOUT `depth:` is visibility/navigation — landing/seeing/leaving IS the
+      // assertion, so mere presence covers it. Only DATA-correctness themes (depth.requires:
+      // data-assertion) need a data assertion to count as deeply covered.
+      const needsDepth = t.depth?.requires === 'data-assertion';
+      if (!needsDepth) { covered++; continue; }
+      if (coverers.some((s) => s.hasDataAssertion)) covered++;
+      else gaps.push({ theme: t.theme, keywords: t.keywords, status: 'shallow' });
     }
   }
 

package/src/orchestrator/flow-manager.ts

@@ -6,11 +6,18 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { readCapabilities } from '../harness/capability';
 
 export interface FlowOptions {
   name: string;
   path?: string;
   description?: string;
+  /**
+   * Mobile navigation recipe for the flow's starting screen. A `>`-separated list of nav steps
+   * that take the app from launch to the first screen in the flow. Scaffolded into the Background.
+   * Ignored (with a warning) for web projects.
+   */
+  reach?: string;
 }
 
 export class FlowManager {
@@ -25,6 +32,18 @@ export class FlowManager {
   async addFlow(options: FlowOptions): Promise<void> {
     this.validateFlowName(options.name);
 
+    // Detect project platform from qa/capabilities.yaml
+    const caps = readCapabilities(this.cwd);
+    const isMobile = caps.platform === 'mobile';
+
+    // --reach is mobile-only; warn and drop when the project is web
+    if (options.reach && !isMobile) {
+      console.warn(
+        `Warning: --reach is a mobile navigation recipe and is ignored for web projects. Dropping it.`
+      );
+      options = { ...options, reach: undefined };
+    }
+
     const flowName = this.normalizeFlowName(options.name);
     const flowDir = path.join(this.flowsDir, flowName);
 
@@ -59,28 +78,40 @@ export class FlowManager {
       process.exit(1);
     }
 
-    fs.writeFileSync(featurePath, this.generateFeatureTemplate(options, flowName), 'utf-8');
+    fs.writeFileSync(featurePath, this.generateFeatureTemplate(options, flowName, isMobile), 'utf-8');
 
     const startPath = options.path || '/login';
-    fs.writeFileSync(selectorPath, [
-      `# ${options.name} Flow Selectors`,
-      `# Namespace keys by screen to avoid duplicates: "login:submit", "awards:submit"`,
-      ``,
-      `# --- Login screen ---`,
-      `login:`,
-      `  type: 'page'`,
-      `  value: '${startPath}'`,
-      ``,
-      `# "login:email":`,
-      `#   type: 'testid'`,
-      `#   value: 'email-input'`,
-      ``,
-      `# "login:submit":`,
-      `#   type: 'role'`,
-      `#   value: 'button'`,
-      `#   name: 'Login'`,
-      ``,
-    ].join('\n'), 'utf-8');
+    const selectorLines = isMobile
+      ? [
+          `# ${options.name} Flow Selectors (mobile)`,
+          `# Namespace keys by screen: "home:button", "settings:save"`,
+          `# Generated at /sungen:run-test via Appium MCP — accessibility-id preferred.`,
+          ``,
+          `# "home:element":`,
+          `#   type: 'accessibility-id'`,
+          `#   value: 'element-id'`,
+          ``,
+        ]
+      : [
+          `# ${options.name} Flow Selectors`,
+          `# Namespace keys by screen to avoid duplicates: "login:submit", "awards:submit"`,
+          ``,
+          `# --- Login screen ---`,
+          `login:`,
+          `  type: 'page'`,
+          `  value: '${startPath}'`,
+          ``,
+          `# "login:email":`,
+          `#   type: 'testid'`,
+          `#   value: 'email-input'`,
+          ``,
+          `# "login:submit":`,
+          `#   type: 'role'`,
+          `#   value: 'button'`,
+          `#   name: 'Login'`,
+          ``,
+        ];
+    fs.writeFileSync(selectorPath, selectorLines.join('\n'), 'utf-8');
 
     fs.writeFileSync(testDataPath, [
       `# ${options.name} Flow Test Data`,
@@ -90,7 +121,7 @@ export class FlowManager {
     ].join('\n'), 'utf-8');
 
     const specPath = path.join(requirementsDir, 'spec.md');
-    fs.writeFileSync(specPath, this.generateSpecTemplate(options, flowName), 'utf-8');
+    fs.writeFileSync(specPath, this.generateSpecTemplate(options, flowName, isMobile), 'utf-8');
 
     const viewpointPath = path.join(requirementsDir, 'test-viewpoint.md');
     fs.writeFileSync(viewpointPath, this.generateViewpointTemplate(options), 'utf-8');
@@ -104,12 +135,21 @@ export class FlowManager {
     console.log(`  ${path.relative(this.cwd, requirementsUiDir)}/`);
     console.log('');
 
-    console.log('Next steps:');
-    console.log(`  1. Fill requirements/spec.md with flow specification (screens, transitions, business rules)`);
-    console.log(`     Optionally add UI designs to requirements/ui/`);
-    console.log(`  2. Generate test cases: /sungen:create-test ${flowName}`);
-    console.log(`  3. Compile: sungen generate --flow ${flowName}`);
-    console.log(`  4. Run: npx playwright test\n`);
+    if (isMobile) {
+      console.log('Next steps:');
+      console.log(`  1. Fill requirements/spec.md with flow specification (screens, transitions, business rules)`);
+      console.log(`     Use sungen-capture-mobile to scan each screen via Appium MCP`);
+      console.log(`  2. Generate test cases: /sungen:create-test ${flowName}`);
+      console.log(`  3. Compile: sungen generate --flow ${flowName} --framework appium`);
+      console.log(`  4. Run: npm run test:mobile\n`);
+    } else {
+      console.log('Next steps:');
+      console.log(`  1. Fill requirements/spec.md with flow specification (screens, transitions, business rules)`);
+      console.log(`     Optionally add UI designs to requirements/ui/`);
+      console.log(`  2. Generate test cases: /sungen:create-test ${flowName}`);
+      console.log(`  3. Compile: sungen generate --flow ${flowName}`);
+      console.log(`  4. Run: npx playwright test\n`);
+    }
   }
 
   private validateFlowName(name: string): void {
@@ -131,7 +171,39 @@ export class FlowManager {
       .replace(/-+/g, '-');
   }
 
-  private generateSpecTemplate(options: FlowOptions, flowName: string): string {
+  private generateSpecTemplate(options: FlowOptions, flowName: string, isMobile: boolean): string {
+    if (isMobile) {
+      return `# ${options.name} Flow Specification
+
+## Overview
+- **Platform:** mobile (Android + iOS)
+- **Auth Required:** no
+- **Starting screen reach:** ${options.reach || '<!-- nav recipe to reach the first screen, e.g. "tap [Tab] > tap [Row]" -->'}
+
+## Screens in Flow
+<!-- List all screens this flow visits, in order -->
+
+| # | Screen | Reach | Description |
+|---|--------|-------|-------------|
+| 1 | [Screen Name] | tap [element] | [What user does here] |
+
+## Flow Steps
+
+### Step 1: [Screen Name]
+- **Action:** [What the user taps]
+- **Expected:** [What should happen]
+- **Transition:** Navigates to Step 2
+
+## Business Rules
+<!-- Rules that affect the flow: permissions, conditions, limits -->
+- [Rule 1]
+
+## Notes
+<!-- Edge cases, known issues, environment-specific behavior -->
+- [Note 1]
+`;
+    }
+
     const startPath = options.path || '/login';
     return `# ${options.name} Flow Specification
 
@@ -215,9 +287,33 @@ export class FlowManager {
     ].join('\n');
   }
 
-  private generateFeatureTemplate(options: FlowOptions, flowName: string): string {
+  private generateFeatureTemplate(options: FlowOptions, flowName: string, isMobile: boolean): string {
     const description = options.description || `complete the ${options.name} flow`;
 
+    if (isMobile) {
+      const background = this.buildMobileBackground(options.reach);
+      return `@flow @platform:mobile
+Feature: ${options.name} Flow
+
+  As a user
+  I want to ${description}
+  So that I can accomplish my end-to-end goal
+
+  # Mobile (Appium) flow — selectors use colon namespace: "home:element", "settings:save".
+  # See sungen-mobile-gestures for swipe/long-press/scroll steps.
+
+${background}
+  @high
+  Scenario: Sample step for ${options.name}
+    When User tap [Home:element]
+    Then User see [Settings] screen
+
+  Scenario: Sample next step for ${options.name}
+    When User tap [Settings:element]
+    Then User see [Result:header] header with {{result_text}}
+`;
+    }
+
     return `@flow
 Feature: ${options.name} Flow
 
@@ -240,4 +336,44 @@ Feature: ${options.name} Flow
     Then User see "expected result" text
 `;
   }
+
+  /**
+   * Build the Background block for a mobile flow — same structure as screen-manager.
+   * The `--reach` steps represent how to reach the FIRST screen of the flow from app launch.
+   */
+  private buildMobileBackground(reach?: string): string {
+    const normalizeStep = (raw: string): string =>
+      raw
+        .trim()
+        .replace(/^(given|when|and|then|but)\s+/i, '')
+        .replace(/^user\s+/i, '')
+        .trim();
+
+    const steps = (reach || '')
+      .split('>')
+      .map(normalizeStep)
+      .filter(Boolean);
+
+    if (steps.length === 0) {
+      return [
+        '  Background:',
+        '    # Navigation recipe — how to reach the first screen of this flow from app launch.',
+        '    # Prefill with --reach "tap [Tab] > tap [Row]" at add-flow time.',
+        '    Given User is on [Home] screen',
+        '    # When User tap [<tab or button that leads to the first screen>]',
+        '',
+      ].join('\n');
+    }
+
+    const navLines = steps.map(
+      (body, i) => `    ${i === 0 ? 'When' : 'And'} User ${body}`,
+    );
+    return [
+      '  Background:',
+      '    # Navigation recipe — replayed by capture-mobile to land on the first screen.',
+      '    Given User is on [Home] screen',
+      ...navLines,
+      '',
+    ].join('\n');
+  }
 }