@sun-asterisk/sungen 3.2.31 → 3.2.32

package/src/harness/parse.ts

@@ -78,6 +78,32 @@ function isViewpointId(s: string): boolean {
   return isIdLike(s) || /^(?:VP|FL)-[A-Z][A-Z0-9]*$/i.test(s);
 }
 
+/**
+ * A markdown heading's TEXT, normalised the way the ledger already normalises it.
+ *
+ * Headings in a real viewpoint file are numbered ("## 2. Priority Viewpoints") and often bolded
+ * ("## **Priority Viewpoints**"), and both forms are what the authoring template produces. Every
+ * pass below anchored on the bare literal, so a numbered file parsed to ZERO viewpoints: the
+ * priority table was dropped whole, clean rows included, and the audit lost its traceability
+ * table. `viewpoint-ledger.ts` learned the same lesson at its own heading test (#657); this is
+ * that normalisation, applied where the overview reads headings.
+ *
+ * Returns null for a line that is not a heading, so a caller can tell "not a heading" from
+ * "a heading whose text is empty".
+ */
+function headingParts(line: string): { level: number; text: string } | null {
+  const m = line.match(/^(#{1,6})\s+(.*)$/);
+  if (!m) return null;
+  const text = m[2]
+    .replace(/[*`]/g, '')
+    // Multi-level (`2.1`, `3.2.4`) and roman numbering are at least as common in a numbered spec as
+    // a single digit, and a strip that only handled one level left `## 2.1 Priority Viewpoints`
+    // reading as `1 Priority Viewpoints` — the same zero-viewpoint failure, one dot away.
+    .replace(/^\s*(?:\d+(?:\.\d+)*|[IVXLCDM]+|[A-Z])\s*[.):]?\s+/, '')
+    .trim();
+  return { level: m[1].length, text };
+}
+
 export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
   if (!fs.existsSync(filePath)) return [];
   const text = readTextFile(filePath);
@@ -89,12 +115,15 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
   let inPriorityTable = false;
   for (const raw of lines) {
     const line = raw.trim();
-    if (/^##\s+Priority Viewpoints/i.test(line)) { inPriorityTable = true; continue; }
-    if (inPriorityTable && /^##\s/.test(line)) { inPriorityTable = false; }
+    const heading = headingParts(line);
+    if (heading && heading.level === 2 && /^Priority Viewpoints/i.test(heading.text)) { inPriorityTable = true; continue; }
+    if (inPriorityTable && heading && heading.level === 2) { inPriorityTable = false; }
     if (inPriorityTable && line.startsWith('|')) {
       const cells = line.split('|').map((c) => c.trim()).filter((_, i, a) => i > 0 && i < a.length - 1);
       if (cells.length >= 3) {
-        const id = cells[0];
+        // The same `**` the heading carries: ids are routinely written `| **VP-LOGIC** | High | … |`,
+        // and an id read with its emphasis markers still attached matches no scenario tag.
+        const id = cells[0].replace(/[*`]/g, '').trim();
         if (isViewpointId(id) && !/^-+$/.test(cells[1])) {
           const pr = /high/i.test(cells[1]) ? 'High' : /medium/i.test(cells[1]) ? 'Medium' : /low/i.test(cells[1]) ? 'Low' : 'Unknown';
           entries.set(id.toUpperCase(), { id: id.toUpperCase(), priority: pr as any, reason: cells[2] });
@@ -110,7 +139,10 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
   // FL-HP-001 were reported as unmapped. Both forms are additive here.
   for (const raw of lines) {
     const line = raw.trim();
-    const section = line.match(/^##\s+([A-Z]{2,}(?:-[A-Z0-9]{2,})*)\s+[—–-]\s*(.*)$/);
+    const head = headingParts(line);
+    const section = head && head.level === 2
+      ? head.text.match(/^([A-Z]{2,}(?:-[A-Z0-9]{2,})*)\s+[—–-]\s*(.*)$/)
+      : null;
     if (section && isViewpointId(section[1] + '-0')) {
       const id = section[1].toUpperCase();
       if (!entries.has(id)) entries.set(id, { id, priority: 'Unknown', reason: section[2] ?? '' });
@@ -130,11 +162,14 @@ export function parseViewpointOverview(filePath: string): ViewpointEntry[] {
   let group: ViewpointEntry['group'] | undefined;
   for (const raw of lines) {
     const line = raw.trim();
-    const g = line.match(/^###\s+(Required|Recommended|Optional)/i);
+    const head = headingParts(line);
+    const g = head && head.level === 3 ? head.text.match(/^(Required|Recommended|Optional)/i) : null;
     if (g) { group = (g[1][0].toUpperCase() + g[1].slice(1).toLowerCase()) as any; continue; }
-    if (/^##\s/.test(line)) { group = undefined; }
+    if (head && head.level === 2) { group = undefined; }
     if (group) {
-      const m = line.match(/^[-*+]\s+([A-Za-z][A-Za-z0-9.-]*)/);
+      // `**` and backticks only — a single `*` is a bullet marker here, and stripping it would
+      // stop `* VP-A-001` being a bullet at all.
+      const m = line.replace(/\*\*|`/g, '').match(/^[-*+]\s+([A-Za-z][A-Za-z0-9.-]*)/);
       if (m && isViewpointId(m[1])) {
         const id = m[1].toUpperCase();
         const existing = entries.get(id);

package/src/harness/spec-branches.ts

@@ -204,38 +204,93 @@ export function sameOracleClusters(scenarios: ScenarioInfo[]): Array<{ oracle: s
 }
 
 /**
- * A "denied → hidden" scenario with no "allowed → shown" counterpart (#630).
+ * A "hidden" scenario with no "shown" counterpart (#630, widened in #679).
  *
  * Two security cases proved that chat content is hidden when `MESSAGE_READ` is denied. If the code
  * hid it unconditionally — ignoring the permission entirely — both still pass. The deny side alone
  * cannot distinguish "the guard works" from "the feature is broken for everyone", so the pair is
  * the test, exactly as `min-1 / min / max / max+1` is the test for a boundary.
  *
- * The mirror of the negative-claim rule the skill already has, on the other side.
+ * The first version gated on PERMISSION vocabulary, and "show A or B, never both" is far broader
+ * than permission: a conditional button, an empty-vs-populated state, an active tab. A field report
+ * lost exactly that case — "the score button is hidden once a score exists" was written, "it is
+ * shown while no score is set" was not, and nothing asked for it. So the trigger is now the
+ * ELEMENT the assertion names: an element this suite proves ABSENT and never proves PRESENT is
+ * unpaired, whatever the condition is called. That also catches the vacuous form — a selector that
+ * matches nothing passes `is hidden` forever.
+ *
+ * Permission stays its own `kind`, because the repair advice differs and its wording is what the
+ * skill teaches.
  */
 const DENY_SHAPE = /\b(?:denied|deny|denies|forbidden|not authoriz\w*|unauthoriz\w*|no permission|without (?:the )?(?:permission|right|access|flag)|permission (?:is )?off|flag (?:is )?off|revoked|restricted)\b/i;
 const HIDDEN_SHAPE = /\b(?:is hidden|are hidden|not (?:visible|shown|displayed)|blocked|masked|redacted|does not (?:show|render|appear))\b/i;
 const ALLOW_SHAPE = /\b(?:granted|allowed|permitted|authoriz\w*|has (?:the )?(?:permission|right|access)|permission (?:is )?on|flag (?:is )?on|with (?:the )?(?:permission|right|access))\b/i;
 
-export function permissionPairGaps(
-  scenarios: ScenarioInfo[],
-): Array<{ scenario: string; subject: string[] }> {
-  const denies = scenarios.filter((s) => DENY_SHAPE.test(s.haystack) && HIDDEN_SHAPE.test(s.haystack));
-  if (denies.length === 0) return [];
-  const allows = scenarios.filter((s) => ALLOW_SHAPE.test(s.haystack) && !HIDDEN_SHAPE.test(s.stepsText));
+/** Absence in sungen's own assertion grammar — `is hidden`, `does not exist`, `not exists`. */
+const ABSENT_ASSERTION = /\bis hidden\b|\bare hidden\b|\bnot (?:visible|shown|displayed)\b|\bdoes not (?:exist|show|appear|render)\b|\bnot exists?\b/i;
+
+export interface VisibilityPairGap {
+  scenario: string;
+  subject: string[];
+  /** The element reference the pair is about, when the assertion names one. */
+  element?: string;
+  /** `permission` keeps the deny/allow repair advice; `condition` is any other state. */
+  kind: 'permission' | 'condition';
+}
+
+/** What a scenario ASSERTS — the Then side. Hand-built fixtures carry no buckets; use their steps. */
+function thenLines(s: ScenarioInfo): string[] {
+  const thens = (s.steps ?? []).filter((st) => st.bucket === 'then').map((st) => st.text.toLowerCase());
+  if (thens.length) return thens;
+  return s.stepsText ? [s.stepsText] : [];
+}
+/** Every `[ref]` of a line. */
+function refsIn(line: string): string[] {
+  return [...line.matchAll(/\[([^\]]{1,60})\]/g)].map((m) => m[1].trim().toLowerCase());
+}
+
+export function visibilityPairGaps(scenarios: ScenarioInfo[]): VisibilityPairGap[] {
+  // Every element the suite proves PRESENT, anywhere. A positive assertion names its element and
+  // any element it is scoped INSIDE (`[Row] row in [Table] table`) — both are demonstrably there.
+  const shown = new Set<string>();
+  for (const s of scenarios) {
+    for (const l of thenLines(s)) {
+      if (ABSENT_ASSERTION.test(l)) continue;
+      for (const ref of refsIn(l)) shown.add(ref);
+    }
+  }
   // Words only — the scenario ID is stripped first, because `[a-z][a-z-]{4,}` happily matches
   // `fl-er-` and an id fragment can never appear in the counterpart's title, so demanding it made
   // the pair impossible to find.
   const distinctive = (s: ScenarioInfo): string[] =>
     [...new Set((s.name.replace(/^\S+\s*/, '').toLowerCase().match(/[a-z]{5,}/g) ?? []))]
       .filter((w) => !GENERIC_WORD.has(w) && !/denied|denies|hidden|permission|scenario/.test(w));
-  const out: Array<{ scenario: string; subject: string[] }> = [];
-  for (const d of denies) {
-    const subject = distinctive(d);
+  const allows = scenarios.filter((s) => ALLOW_SHAPE.test(s.haystack) && !HIDDEN_SHAPE.test(s.stepsText));
+  const out: VisibilityPairGap[] = [];
+  const reported = new Set<string>();
+  for (const s of scenarios) {
+    const absent = thenLines(s).filter((l) => ABSENT_ASSERTION.test(l));
+    if (!absent.length && !(DENY_SHAPE.test(s.haystack) && HIDDEN_SHAPE.test(s.haystack))) continue;
+    const kind = DENY_SHAPE.test(s.haystack) ? 'permission' : 'condition';
+    // Only the FIRST ref of an absence line is its subject: in `see [Row] row in [Table] table … is
+    // hidden` the table is the scope, the row is what went away.
+    const subjects = [...new Set(absent.map((l) => refsIn(l)[0]).filter((r): r is string => !!r))];
+    if (subjects.length) {
+      for (const el of subjects) {
+        if (shown.has(el) || reported.has(el)) continue;
+        reported.add(el);
+        out.push({ scenario: s.name, subject: distinctive(s).slice(0, 4), element: el, kind });
+      }
+      continue;
+    }
+    // The assertion names no element — the permission vocabulary is then the only safe trigger,
+    // paired on the scenario's distinctive title words as before.
+    if (kind !== 'permission' || !HIDDEN_SHAPE.test(s.haystack)) continue;
+    const subject = distinctive(s);
     // The counterpart has to be about the SAME thing — two shared distinctive words, the same
     // bar the ledger's prose matching uses.
     const paired = allows.some((a) => subject.filter((w) => a.haystack.includes(w)).length >= Math.min(2, subject.length));
-    if (!paired) out.push({ scenario: d.name, subject: subject.slice(0, 4) });
+    if (!paired) out.push({ scenario: s.name, subject: subject.slice(0, 4), kind: 'permission' });
   }
   return out;
 }

package/src/harness/spec-coverage.ts

@@ -16,6 +16,12 @@ export type Modality = 'MUST' | 'SHOULD' | 'MAY';
 
 export interface TriggerGap { constraint: string; code: string; required: string[]; found: string[]; missing: string[] }
 
+/**
+ * One DIRECTION of a requirement that states both — `MUST be shown … MUST NOT be shown …` (#679).
+ * The id is cited, so the requirement looks covered; this names the half nothing asserts.
+ */
+export interface ClauseGap { id: string; polarity: 'affirm' | 'negate'; text: string }
+
 export interface SpecCoverageResult {
   hasSpec: boolean;
   frTotal: number;
@@ -27,10 +33,13 @@ export interface SpecCoverageResult {
    *  requirement table and any later refactor cannot follow it. */
   inferredOnly: string[];
   triggerGaps: TriggerGap[];     // per-constraint trigger matrix gaps
+  /** Requirements whose two opposing clauses are not BOTH proved (#679). */
+  clauseGaps: ClauseGap[];
   verdict: 'pass' | 'warn' | 'fail';
 }
 
-interface FrClause { id: string; text: string; modality: Modality }
+export interface FrDirection { polarity: 'affirm' | 'negate'; text: string }
+interface FrClause { id: string; text: string; modality: Modality; directions?: FrDirection[] }
 interface ValRow { constraint: string; code: string; triggers: string[] }
 
 // Parsing the spec's Trigger CELL: loose word match ("blur, submit").
@@ -55,6 +64,86 @@ function modalityOf(text: string): Modality {
   return 'MAY';
 }
 
+/**
+ * A requirement that states BOTH directions in one sentence — "`X` MUST be shown when no score is
+ * set; MUST NOT be shown once a score exists" (#679).
+ *
+ * One `FrClause` per LINE carried one modality for the whole sentence, and coverage was a binary
+ * check per id: ONE scenario tagged `@spec:FR-013` closed both halves. The half that went missing
+ * in the field was the MUST NOT one — the classic "both buttons rendered at once" defect, reported
+ * as covered 100% on the first generation.
+ *
+ * Deliberately narrow, three ways at once, because the finding is GATE-BLOCKING:
+ *   - only a HARD prohibition paired with a hard obligation ("MUST be shown and enabled" is one
+ *     direction and stays one unit);
+ *   - only a requirement that NAMES its element, backticked or bracketed — the direction evidence
+ *     is an assertion ABOUT something, and without a subject there is nothing to look for;
+ *   - only a VISIBILITY/enabledness requirement, because that is the vocabulary the evidence test
+ *     reads. "MUST validate the email format on submit. MUST NOT allow submission when it is
+ *     invalid." is an opposing pair in prose and NOT one here: nothing in a correct suite for it
+ *     asserts absence, so judging it would fail a suite with no gap in it.
+ */
+const VISIBILITY_CLAUSE = /\b(?:shown|shows?|displayed|displays?|visible|hidden|hides?|rendered|renders?|appears?|enabled|disabled)\b|表示|hiển thị/i;
+const PROHIBITION = /\b(?:must not|must never|shall not|shall never)\b|KHÔNG ĐƯỢC|してはならない/i;
+const OBLIGATION = /\b(?:must|shall)\b|\bPHẢI\b/i;
+
+function splitDirections(text: string): FrDirection[] | undefined {
+  if (!VISIBILITY_CLAUSE.test(text) || elementRefs(text).length === 0) return undefined;
+  const parts = text.split(/\s*(?:;|；|。|\.\s+|,?\s+but\s+)\s*/i).map((p) => p.trim()).filter(Boolean);
+  if (parts.length < 2) return undefined;
+  const affirm: string[] = [];
+  const negate: string[] = [];
+  for (const part of parts) {
+    if (PROHIBITION.test(part)) negate.push(part);
+    else if (OBLIGATION.test(part)) affirm.push(part);
+  }
+  if (!affirm.length || !negate.length) return undefined;
+  return [
+    { polarity: 'affirm', text: affirm.join('; ') },
+    { polarity: 'negate', text: negate.join('; ') },
+  ];
+}
+
+/** What the clause is ABOUT: a backticked or bracketed element name is the one distinctive token. */
+function elementRefs(text: string): string[] {
+  return [...new Set(
+    [...text.matchAll(/`([^`]+)`|\[([^\]]+)\]/g)]
+      .map((m) => (m[1] ?? m[2]).trim().toLowerCase())
+      .filter((x) => x.length >= 2 && x.length <= 60),
+  )];
+}
+
+/**
+ * Absence, in sungen's own assertion grammar (`is hidden`, `does not exist`) plus the prose a spec
+ * restatement uses. Positive visibility has no marker — `User see [T]` never says "is visible" —
+ * so the affirm side is "an assertion that is not a denial", which is what the suite actually writes.
+ */
+const NEGATIVE_ASSERTION = /\bis hidden\b|\bare hidden\b|\bnot (?:visible|shown|displayed|present)\b|\bdoes not (?:exist|show|appear|render)\b|\bnot exists?\b|\bno longer\b|表示されない|không hiển thị/i;
+
+/** Assertion lines of a scenario block — Then plus the And/But that inherit its bucket. */
+function assertionLines(block: string): string[] {
+  const out: string[] = [];
+  let bucket = '';
+  for (const raw of block.split('\n')) {
+    const kw = raw.trim().match(/^(given|when|then|and|but)\s+/);
+    if (!kw) continue;
+    if (kw[1] !== 'and' && kw[1] !== 'but') bucket = kw[1];
+    if (bucket === 'then') out.push(raw.trim());
+  }
+  return out;
+}
+
+/** Does this scenario block assert THIS direction of the requirement? */
+function directionCovered(block: string, dir: FrDirection, subject: string[]): boolean {
+  const lines = assertionLines(block);
+  const pool = lines.length ? lines : [block];
+  // Narrow to the lines about the clause's element when the suite names it the same way the spec
+  // does; a spec in one language and selector keys in another must not read as "no evidence".
+  const about = subject.length ? pool.filter((l) => subject.some((x) => l.includes(x))) : [];
+  const scan = about.length ? about : pool;
+  return scan.some((l) => NEGATIVE_ASSERTION.test(l) === (dir.polarity === 'negate'));
+}
+
 function specTriggersIn(text: string): string[] {
   return SPEC_TRIGGER.filter((t) => t.re.test(text)).map((t) => t.trigger);
 }
@@ -86,7 +175,10 @@ export function parseSpecClauses(specPath: string): { frs: FrClause[]; valRows:
     const id = m[1].toUpperCase();
     if (seen.has(id)) continue;          // first declaration wins
     seen.add(id);
-    frs.push({ id, text: m[2].replace(/\*\*/g, '').trim(), modality: modalityOf(m[2]) });
+    const text = m[2].replace(/\*\*/g, '').trim();
+    const modality = modalityOf(text);
+    // A MUST/MUST NOT pair is TWO requirements wearing one id (#679) — carry both directions.
+    frs.push({ id, text, modality, directions: modality === 'MUST' ? splitDirections(text) : undefined });
   }
 
   // Validation Rules table: a row carries a Constraint, a Trigger cell, and (often) a code.
@@ -156,33 +248,51 @@ export function citedIds(featureText: string): Set<string> {
 export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featureText: string): SpecCoverageResult {
   const { frs, valRows } = parseSpecClauses(specPath);
   if (!fs.existsSync(specPath) || (frs.length === 0 && valRows.length === 0)) {
-    return { hasSpec: fs.existsSync(specPath), frTotal: 0, frCovered: 0, uncoveredMust: [], inferredOnly: [], triggerGaps: [], verdict: 'pass' };
+    return { hasSpec: fs.existsSync(specPath), frTotal: 0, frCovered: 0, uncoveredMust: [], inferredOnly: [], triggerGaps: [], clauseGaps: [], verdict: 'pass' };
   }
   const featLower = featureText.toLowerCase();
   const cites = citedIds(featureText);
+  const blocks = scenarioBlocks(featureText);
 
   // FR coverage: explicit @spec:FR / literal FR-id citation, else keyword fallback.
   const uncoveredMust: { id: string; text: string }[] = [];
+  const clauseGaps: ClauseGap[] = [];
   const inferredOnly: string[] = [];
+  let frTotal = 0;
   let frCovered = 0;
   for (const fr of frs) {
+    // A requirement stating both directions is TWO units — counting it as one is what let a suite
+    // holding only the MUST half read 100% covered (#679).
+    const units = fr.directions ? fr.directions.length : 1;
+    frTotal += units;
     const idLower = fr.id.toLowerCase();
     const cited = featLower.includes(idLower) || cites.has(fr.id.toUpperCase());
     const words = [...new Set((fr.text.toLowerCase().match(/[a-z][a-z-]{4,}/g) || []))]
       .filter((w) => !/must|should|system|screen|users?|value|input|field/.test(w));
     const kwHit = words.length > 0 && scenarios.some((s) => words.filter((w) => s.haystack.includes(w)).length >= Math.min(2, words.length));
-    if (cited || kwHit) {
-      frCovered++;
-      if (!cited) inferredOnly.push(fr.id); // covered, but nothing links it explicitly
-    } else if (fr.modality === 'MUST') {
-      uncoveredMust.push({ id: fr.id, text: fr.text.slice(0, 90) });
+    if (!cited && !kwHit) {
+      if (fr.modality === 'MUST') uncoveredMust.push({ id: fr.id, text: fr.text.slice(0, 90) });
+      continue;
+    }
+    if (!cited) inferredOnly.push(fr.id); // covered, but nothing links it explicitly
+    if (!fr.directions) { frCovered++; continue; }
+    // Which scenarios speak for this requirement — by its id (tags and comments sit in the block)
+    // or by the same keyword rule used above.
+    const owning = blocks.filter((b) => b.includes(idLower)
+      || (words.length > 0 && words.filter((w) => b.includes(w)).length >= Math.min(2, words.length)));
+    // Cited from outside any scenario (a header comment): nothing to judge a direction against, so
+    // report nothing rather than invent a gap.
+    if (!owning.length) { frCovered += units; continue; }
+    const subject = elementRefs(fr.text);
+    for (const dir of fr.directions) {
+      if (owning.some((b) => directionCovered(b, dir, subject))) frCovered++;
+      else if (fr.modality === 'MUST') clauseGaps.push({ id: fr.id, polarity: dir.polarity, text: dir.text.slice(0, 90) });
     }
   }
 
   // Per-constraint trigger coverage — the matrix-collapse catch.
   // generic words that don't identify a constraint (would over-match happy-path scenarios)
   const GENERIC = new Set(['valid', 'local', 'part', 'domain', 'email', 'address', 'must', 'exist', 'store', 'field', 'input', 'value', 'formed', 'well', 'character', 'characters']);
-  const blocks = scenarioBlocks(featureText);
   const triggerGaps: TriggerGap[] = [];
   for (const row of valRows) {
     const kw = (row.constraint.toLowerCase().match(/[a-z]{4,}/g) || []).filter((w) => !GENERIC.has(w));
@@ -198,9 +308,9 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
   }
 
   const verdict: SpecCoverageResult['verdict'] =
-    uncoveredMust.length > 0 || triggerGaps.length > 0 ? 'fail' : 'pass';
+    uncoveredMust.length > 0 || triggerGaps.length > 0 || clauseGaps.length > 0 ? 'fail' : 'pass';
 
-  return { hasSpec: true, frTotal: frs.length, frCovered, uncoveredMust, inferredOnly, triggerGaps, verdict };
+  return { hasSpec: true, frTotal, frCovered, uncoveredMust, inferredOnly, triggerGaps, clauseGaps, verdict };
 }
 
 /**

package/src/orchestrator/appium-environment-setup.ts

@@ -0,0 +1,127 @@
+/**
+ * Appium environment bundle — emit `appium-environment/` into a mobile project and run its entry point.
+ *
+ * The bundle (bash for macOS, PowerShell for Windows) provisions the OS layer BELOW Appium: JDK, Android
+ * SDK + env vars, Xcode CLT, applesimutils, then the project-local Appium platform drivers, and ends with
+ * `appium driver doctor`. Emitted by `sungen init --mobile` / `sungen capability add mobile` and run once
+ * right after the driver install (spec: docs/spec/sungen_mobile_environment_setup_spec.md, issue #718).
+ *
+ * Core ships the scripts as templates only — no runtime is embedded, nothing is installed globally.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+
+export const APPIUM_ENV_DIR = 'appium-environment';
+
+export interface EmitResult {
+  created: string[];
+  skipped: string[];
+}
+
+export type EnvSetupOutcome = 'ran' | 'failed' | 'skipped' | 'unsupported';
+
+/** Bundled template root — resolves from src/orchestrator (tsx) and dist/orchestrator (copy-templates). */
+const TEMPLATE_ROOT = path.join(__dirname, 'templates', APPIUM_ENV_DIR);
+
+/** Files under `dir`, relative and posix-separated, sorted for a deterministic emit order. */
+function listTemplateFiles(dir: string, prefix = ''): string[] {
+  const out: string[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listTemplateFiles(path.join(dir, entry.name), rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
+/**
+ * Copy the bundle into `<cwd>/appium-environment/`, skipping every file that already exists (a QA may
+ * have edited the pinned cmdline-tools build or a hint — same idempotency as the other emitted files).
+ * `*.sh` get the executable bit explicitly: npm and git do not reliably preserve it.
+ */
+export function emitAppiumEnvironment(cwd: string): EmitResult {
+  const created: string[] = [];
+  const skipped: string[] = [];
+  // Non-fatal like the other provisioning steps: a broken install (templates missing) must not abort
+  // `init` / `capability add` — the harness scaffold is still valid without the bundle.
+  try {
+    for (const rel of listTemplateFiles(TEMPLATE_ROOT)) {
+      const dest = path.join(cwd, APPIUM_ENV_DIR, rel);
+      const label = `${APPIUM_ENV_DIR}/${rel}`;
+      if (fs.existsSync(dest)) { skipped.push(label); continue; }
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(path.join(TEMPLATE_ROOT, rel), dest);
+      if (rel.endsWith('.sh')) fs.chmodSync(dest, 0o755);
+      created.push(label);
+    }
+  } catch (e) {
+    console.warn(`⚠️  Could not emit ${APPIUM_ENV_DIR}/ (${e instanceof Error ? e.message : e}) — reinstall @sun-asterisk/sungen and re-run: sungen capability add mobile`);
+  }
+  return { created, skipped };
+}
+
+/** The command a QA re-runs by hand, for hints and the init summary. */
+export function appiumEnvironmentRerunCommand(): string {
+  return process.platform === 'win32'
+    ? `powershell -NoProfile -ExecutionPolicy Bypass -File .\\${APPIUM_ENV_DIR}\\setup.ps1`
+    : `./${APPIUM_ENV_DIR}/setup.sh`;
+}
+
+/**
+ * Translate the bundle's POSIX flags to their PowerShell switches. `sungen setup-mobile-env` speaks
+ * one flag vocabulary on both OSes, so the user does not have to know which script is underneath.
+ */
+const PS_SWITCH: Record<string, string> = {
+  '--check': '-Check',
+  '--skip-android': '-SkipAndroid',
+  '--no-profile': '-NoProfile',
+  // `--skip-ios` has no Windows counterpart: setup.ps1 has no iOS steps to skip.
+};
+
+function entryCommand(cwd: string, flags: string[] = []): { file: string; args: string[] } | null {
+  const bundle = path.join(cwd, APPIUM_ENV_DIR);
+  if (process.platform === 'win32') {
+    const switches = flags.map(f => PS_SWITCH[f]).filter((s): s is string => !!s);
+    return {
+      file: 'powershell',
+      // -NoProfile here is powershell.exe's own "skip the user profile" flag, unrelated to the
+      // bundle's -NoProfile switch; the latter arrives through `switches` after -File.
+      args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', path.join(bundle, 'setup.ps1'), ...switches],
+    };
+  }
+  // setup.sh handles Darwin; on Linux it prints the manual-path notice and exits 0.
+  if (process.platform === 'darwin' || process.platform === 'linux') {
+    return { file: 'bash', args: [path.join(bundle, 'setup.sh'), ...flags] };
+  }
+  return null;
+}
+
+/**
+ * Run the emitted entry point for this OS with inherited stdio — its per-step output IS the UX, and any
+ * Homebrew / sudo prompt must reach the user. Non-fatal by contract: problems are reported with the re-run
+ * command and init continues, because the scaffold itself is already complete.
+ */
+export function runAppiumEnvironmentSetup(
+  cwd: string,
+  opts: { skip?: boolean; flags?: string[] } = {},
+): EnvSetupOutcome {
+  if (opts.skip) {
+    console.log(`– skipped  environment setup (--skip-env-setup) — run it later: sungen setup-mobile-env`);
+    return 'skipped';
+  }
+  const cmd = entryCommand(cwd, opts.flags);
+  if (!cmd) {
+    console.log(`ℹ️  environment setup ships for macOS (setup.sh) and Windows (setup.ps1) — on ${process.platform} follow ${APPIUM_ENV_DIR}/README.md → Manual fallback`);
+    return 'unsupported';
+  }
+  console.log(`\n🔧 Provisioning the Appium environment (${APPIUM_ENV_DIR}/) — idempotent, re-run any time...`);
+  const result = spawnSync(cmd.file, cmd.args, { cwd, stdio: 'inherit' });
+  if (result.status === 0) return 'ran';
+  // status null = the shell itself could not start (ENOENT) or was killed — name the real cause.
+  const exit = result.error ? `could not start ${cmd.file}: ${result.error.message}`
+    : result.status === null ? `signal ${result.signal ?? '?'}` : `exit ${result.status}`;
+  console.warn(`⚠️  environment setup reported problems (${exit}) — fix the ✗ items above, then re-run: sungen setup-mobile-env (or ${appiumEnvironmentRerunCommand()} directly)`);
+  return 'failed';
+}

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

@@ -22,6 +22,8 @@ export interface MobileInitOptions {
   iosBundleId?: string;
   iosDevice?: string;
   iosVersion?: string;
+  /** Emit `appium-environment/` but do not run it now (`--skip-env-setup`); QA re-runs it by hand. */
+  skipEnvSetup?: boolean;
 }
 
 export interface ScaffoldResult {

package/src/orchestrator/project-initializer.ts

@@ -16,6 +16,7 @@ import {
   writeMobileCapabilities,
   installMobileDriver,
 } from './mobile-runtime-scaffolder';
+import { emitAppiumEnvironment, runAppiumEnvironmentSetup, appiumEnvironmentRerunCommand } from './appium-environment-setup';
 
 export { MobileInitOptions };
 
@@ -99,7 +100,7 @@ export class ProjectInitializer {
   private force: boolean;
   private mobile: MobileInitOptions;
 
-  constructor(private baseUrl: string, opts: { agents?: AdapterKey[]; force?: boolean; enabled?: boolean; mobileOnly?: boolean; appPackage?: string; appActivity?: string; appApk?: string; androidUdid?: string; iosBundleId?: string; iosDevice?: string; iosVersion?: string } = {}) {
+  constructor(private baseUrl: string, opts: { agents?: AdapterKey[]; force?: boolean; enabled?: boolean; mobileOnly?: boolean; appPackage?: string; appActivity?: string; appApk?: string; androidUdid?: string; iosBundleId?: string; iosDevice?: string; iosVersion?: string; skipEnvSetup?: boolean } = {}) {
     this.baseCwd = process.cwd();
     this.cwd = this.baseCwd;
     this.agents = opts.agents && opts.agents.length ? opts.agents : (['claude'] as AdapterKey[]);
@@ -114,6 +115,8 @@ export class ProjectInitializer {
       iosBundleId: opts.iosBundleId,
       iosDevice: opts.iosDevice,
       iosVersion: opts.iosVersion,
+      // `--skip-env-setup`: emit appium-environment/ but do not run it (CI, or the manual path).
+      skipEnvSetup: opts.skipEnvSetup ?? false,
     };
   }
 
@@ -500,6 +503,8 @@ export class ProjectInitializer {
       console.log(`  ${stepIndex++}. cd ${projectName}`);
     }
     if (this.mobileOnly) {
+      console.log(`  ${stepIndex++}. Open a NEW terminal if the environment setup wrote your shell profile (PATH / JAVA_HOME / ANDROID_HOME)`);
+      console.log(`  ${stepIndex++}. Environment not ready, or a new machine? Re-run: ${appiumEnvironmentRerunCommand()}  (idempotent)`);
       console.log(`  ${stepIndex++}. Fill in .env.appium with your device/app details (see .env.appium.example)`);
       console.log(`  ${stepIndex++}. Create your first screen: sungen add --screen <name>`);
       console.log(`  ${stepIndex++}. Use AI (Copilot/Claude) to generate Gherkin + selectors from the live app`);
@@ -642,8 +647,17 @@ export class ProjectInitializer {
     this.createdItems.push(...result.created);
     this.skippedItems.push(...result.skipped);
 
+    // appium-environment/ provisioning bundle — emitted BEFORE the driver install so it lands even when
+    // npm is offline, run AFTER it so its Appium step finds the project-local CLI. One summary line, not 17.
+    const env = emitAppiumEnvironment(this.cwd);
+    if (env.created.length > 0) this.createdItems.push(`appium-environment/ (${env.created.length} files)`);
+    else this.skippedItems.push('appium-environment/');
+
     // Best-effort driver install — non-fatal so offline init still scaffolds.
     installMobileDriver(this.cwd);
+
+    // Provision JDK / Android SDK / Xcode CLT / env vars / platform drivers — non-fatal by contract.
+    runAppiumEnvironmentSetup(this.cwd, { skip: this.mobile.skipEnvSetup });
   }
 
   /**

package/src/orchestrator/templates/ai-src/skills/sungen-error-mapping/SKILL.md

@@ -124,8 +124,12 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-E027` | A selectors.yaml entry declares a **`type:` that is not a selector type** — `type: 'testId'` (capital I), `'xpth'`, `'rol'`, `'test-id'`. YAML is untyped at run time, so this used to compile clean and resolve through the strategy switch's `default:` as `getByPlaceholder('<the value>')`: a locator that cannot match, surfacing much later as a timeout naming placeholder text nobody wrote. Reported once per entry, naming the entry key and the nearest valid spelling; every step using that entry now compiles to a `throw` | Fix the spelling in selectors.yaml. Valid types: `placeholder`, `role`, `testid`, `label`, `text`, `locator`, `id`, `upload`, `page`, `column`, `frame`, `table`, and the mobile strategies `accessibility-id`, `xpath`, `android-uiautomator`, `ios-predicate`, `css`. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
 | `SG-W030` | A selectors.yaml **`expanded.class`/`expanded.attribute`** value carries a character a class or attribute name cannot — whitespace, a quote, a backslash, `$`, `{`, `}`. The value is pasted into the generated spec (string literal, regex, `classList` argument) and selectors.yaml is often generated from the page under test, so it is refused and the field dropped: the step falls back to driving and asserting `aria-expanded`. Reported once per entry and field. The checked/selected signal is refused outright instead of warned about, because dropping it leaves the step with no state to read at all | Use the plain class or attribute name (Tailwind arbitrary values such as `bg-[#eff6ff]` or `!mt-0` are accepted); never paste a selector fragment or quoted text into the field |
 | `SG-E031` | A selectors.yaml **`checked:`/`selected:` declaration the compiler refuses**: the two spellings disagree (`checked.class` and `selected.class` with different values), a class token or attribute name carries whitespace / a quote / a backslash, or one entry declares both a `class` and an `attribute`. Every one of them is silent at run time — the generated matcher tests a single token, so the step would simply time out blaming your component — and an entry declaring two signals lets an action drive one while the assertion after it reads the other. Refused, not dropped: with no signal the step is back on the *"has no on/off state to set"* failure the declaration exists to remove | Declare ONE spelling and ONE of `class` / `attribute`, as a single plain token: `checked: { class: 'is-checked' }`, `selected: { class: 'border-link' }`, or `checked: { attribute: 'data-checked' }`. This is a selectors.yaml-only fix, allowed inside the run-test auto-fix loop |
+| `SG-W032` | A step carries the row filter **`in [T] table with {{v}}`** but the pattern that compiled it dropped the clause, so the generated code runs against the WHOLE table. `Then User see [Status] text in [Job Table] table with {{job_title}}` asserts on every `.status` in the table and passes on a row the sentence never named. The `table-*` family (positioned rows included) resolves its own container and is not flagged, nor is the two-`with` form, which scopes the row correctly, nor a step that WRITES — a write needs a value, so its `with {{v}}` IS that value and `fill [Search] field in [T] table with {{v}}` is an ordinary container-scoped write | Rewrite with the two-`with` form: `User see [Status] text with <expected> in [Job Row] row with {{job_title}}`. Point the second `[…]` at a ROW entry in selectors.yaml, not at the table entry — a filter applied to the table narrows nothing |
+| `SG-W034` | A `see [X] column with {{v}}` step runs inside a table whose rows are declared with a **`rows:` shape**, so the row is not an ARIA row and holds no ARIA cells — but the assertion's only other way to reach a cell is `getByRole('cell')`, which matches nothing there. `columns.<col>.index` cannot rescue it: it indexes that same empty set. Before this the step failed as a timeout blaming the app. Not reported on a real `<table>`, where the role fallback is correct | Name the cell on the column: `columns: { title: { index: 0, header: 'Title', elements: { cell: { type: locator, value: '.job-title' } } } }`. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
+| `SG-E035` | **`table match data:` on a table declared with a `rows:` shape** and no matching `columns:` entries. The assertion reads its header row from `thead tr` and addresses cells as `td, th`; a <div> list has neither — forever, not as a render race — so the step could only wait out every timeout and fail on an empty header row. Refused at compile time, naming the columns it needs | Declare each DataTable column on the table entry with the selector that matches its cell inside a row: `columns: { title: { index: 0, header: 'Title', elements: { cell: { type: locator, value: '.job-title' } } } }`. Declaring columns also removes the runtime header read on a real `<table>`. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
+| `SG-W036` | A **`remember [X] … as {{v}}` capture through a `locator`/`css` selector with no `nth:`**. A capture reads ONE element and the step takes the FIRST match — the right default, and what the documented `nth: 0` workaround asked for after Playwright's strict mode turned a list-shaped selector into a hard failure naming the count. But the first of many is a decision: if the selector describes every item in a list, the captured value is the first row's. Not reported for testid/label/placeholder/role+name/text entries, which name a particular thing | Declare the index (`nth: 0`) to say the first one is meant, or narrow the selector to the single element. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
 
-A diagnostic never changes generation's own exit code — `sungen generate --strict` turns any collected diagnostic into a non-zero exit for CI gates. They are not all inert, though: **`SG-W001`, `SG-W011`, `SG-E020`, `SG-E021`, `SG-W020`, `SG-E023`, `SG-E024`, `SG-E025`, `SG-E026` and `SG-E027` additionally compile the offending step to a runtime `throw`, and `SG-E031` refuses the whole file** — a step that reads as a check and silently checks nothing is worse than one that fails loudly. Generation always COMPLETES: the rest of the scenario and the rest of the file still compile. `SG-E022` is the odd one out — it blames the compiler, not your `.feature`, and throws nothing (the file is written so you can inspect it).
+A diagnostic never changes generation's own exit code — `sungen generate --strict` turns any collected diagnostic into a non-zero exit for CI gates. They are not all inert, though: **`SG-W001`, `SG-W011`, `SG-E020`, `SG-E021`, `SG-W020`, `SG-E023`, `SG-E024`, `SG-E025`, `SG-E026`, `SG-E027` and `SG-E035` additionally compile the offending step to a runtime `throw`, and `SG-E031` refuses the whole file** — a step that reads as a check and silently checks nothing is worse than one that fails loudly. Generation always COMPLETES: the rest of the scenario and the rest of the file still compile. `SG-E022` is the odd one out — it blames the compiler, not your `.feature`, and throws nothing (the file is written so you can inspect it).
 
 ### Runtime error → `Test data "<key>" references ${QA_*} but the environment variable is not set`