@sun-asterisk/sungen 3.2.2 → 3.2.3-beta.3

package/{src/orchestrator/templates/ai-instructions/claude-cmd-run-test.md → dist/orchestrator/templates/ai-src/commands/run-test.md}

@@ -1,39 +1,106 @@
 ---
 name: run-test
-description: 'Generate selectors + auth state via Playwright MCP, compile, and run Playwright tests — auto-fixes selectors on failure'
-argument-hint: "[screen-name] [--env <locale>]"
-allowed-tools: Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_run_code, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state
+description: "Generate selectors + auth state (Playwright MCP for web / Appium MCP for mobile), compile, and run tests — auto-fixes selectors on failure"
+argument-hint: "[screen-name] [--env <locale>] [--ios|--android|--both]"
+order: 40
+claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_run_code, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state, mcp__appium-mcp__select_device, mcp__appium-mcp__appium_session_management, mcp__appium-mcp__generate_locators, mcp__appium-mcp__appium_get_page_source, mcp__appium-mcp__appium_find_element, mcp__appium-mcp__appium_gesture, mcp__appium-mcp__appium_screenshot, mcp__appium-mcp__appium_set_value"
+copilot-tools: "[read, execute, edit, vscode/askQuestions, playwright/*, appium/*]"
+codex-trigger: "Run when the user asks to RUN, execute, or compile tests, generate selectors.yaml, or run tests. Step 4. Do NOT use for authoring/creating new test cases."
 ---
-
 ## Role
 
-You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
+You are a **Senior Developer**.
+- **Web screens/flows** → use `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills (Playwright MCP + `npx playwright test`).
+- **Mobile screens** (`platform: mobile` in `qa/capabilities.yaml`) → use `sungen-selector-fix-mobile`, `sungen-capture-mobile`, `sungen-mobile-gestures`, `sungen-selector-keys` (Appium MCP + `npm run test:mobile`).
+
+## Platform detection (do this FIRST)
+
+Read `qa/capabilities.yaml` and check the `platform` field.
+
+- If `platform: mobile` → switch to the **mobile path** (below).
+- If `platform: web` or field absent → follow the **web path** (all steps below, unchanged).
+
+### Mobile path
+
+When `platform: mobile`:
+
+- **Selectors**: use **Appium MCP** (`select_device` → `appium_session_management(create)` → `generate_locators`), per the `sungen-selector-fix-mobile` skill. Also load `sungen-capture-mobile` and `sungen-mobile-gestures`.
+- **Auth**: web Phase 0.5 (`storageState`) does not exist on mobile. When the feature has `@auth:<role>`, check `specs/.auth-mobile/<role>.json`; if missing, run the guided auth-contract builder (Phase 0.5 in `sungen-selector-fix-mobile`) BEFORE Phase 1.
+- **Compile**: `[ -x ./bin/sungen.js ] && ./bin/sungen.js generate --screen <name> --framework appium || npx sungen generate --screen <name> --framework appium`
+- **OS selection**: parse the target OS from `$ARGUMENTS` — `--ios`, `--android`, or `--both`
+  (alias: `--platform <android|ios|both>`) → set `MOBILE_PLATFORM=<value>`. Default to `android` when no flag is given.
+- **Run**: WebdriverIO, not Playwright. Scope one spec with `SUNGEN_SPECS`; prefix the parsed `MOBILE_PLATFORM`:
+  ```bash
+  # Android (default — no flag, or --android)
+  SUNGEN_SPECS='./specs/generated/<name>/<name>.spec.ts' npm run test:mobile
+  # iOS only (--ios)
+  SUNGEN_SPECS='./specs/generated/<name>/<name>.spec.ts' MOBILE_PLATFORM=ios npm run test:mobile
+  # both OSes (--both)
+  SUNGEN_SPECS='./specs/generated/<name>/<name>.spec.ts' MOBILE_PLATFORM=both npm run test:mobile
+  ```
+  `wdio.conf.ts` auto-selects `@wdio/globals` specs and auto-starts Appium. iOS needs a booted Simulator and `IOS_BUNDLE_ID`/`IOS_UDID` env vars.
+- **Results**: the wdio reporter writes `<name>-test-result.<android|ios>[.<env>].json` — one file per capability, so a both-OS run keeps both outcomes.
+- **Skip** the "Playwright command guidelines" section below — it applies to web only.
+- The phased waves (smoke → priority → full → regression), attempt budgets, and next-steps mirror the web flow — follow the `sungen-selector-fix-mobile` skill for the mobile equivalents.
+
+Stop here for mobile — do not continue to the web path.
+
+> ⛔ **Source of truth — the live page/device is NOT the oracle; `.feature`/`test-data`/`spec.md` are.** Auto-fix is for **selector-resolution** failures (wrong locator → fix `selectors.yaml`). An **assertion-value** failure where the app contradicts the spec is a **CANDIDATE BUG → report it, let it FAIL** — never loosen the rule, weaken the assertion, edit the expected value/`.feature`, or hand-edit the generated `.spec.ts` to make it pass. See `sungen-error-mapping` § "Source of truth".
+
+> ⛔ **The `.feature` Gherkin is QA-approved and FROZEN.** During auto-fix you may write
+> **only** `selectors.yaml`, `test-data.yaml` (and other `*.yaml` data), plus the **one narrow
+> `.feature` edit** allowed: the **element-type token** on a `[Reference]` (e.g. `field`→`textbox`,
+> `button`→`link` — selector resolution, not test logic). You must **NOT** change the Gherkin's
+> content or logic: no rewriting/adding/removing steps, no `wait for` steps, no changed expected
+> values, no weakened assertions. A failure that would need any of those is a **CANDIDATE BUG /
+> QA finding → report it, let it FAIL** (it may be a real bug). The live page is NOT the oracle;
+> never hand-edit the generated `.spec.ts` either. See `sungen-error-mapping` § "HARD RULE".
+> (A `password > 8` test that fails on 6 chars is a bug to report, not a `>= 6` edit.)
 
 ## Parameters
 
 Parse from `$ARGUMENTS`:
 - **name** — screen or flow name. If missing, ask the user.
 - **`--env <locale>`** — optional. Sets `SUNGEN_ENV=<locale>` for the test run so the runtime test-data resolver merges `<name>.<locale>.yaml` over the base, and `playwright.config.ts` writes results to `<name>-test-result.<locale>.json`. Accept `--locale <locale>` as an alias.
+- **`--ios`**, **`--android`**, **`--both`** (mobile only) — optional. Sets `MOBILE_PLATFORM` for the test run. Default: `android` if not specified. Parsed into `MOBILE_PLATFORM=<value>` and used in WebdriverIO test runs.
 
 If `--env` is passed but no value follows, ask the user which locale to use.
 
+{{#cap parallel-subagents}}
 **`--env <locale>` pre-flight**: when `--env` is passed AND the matching overlay file doesn't exist yet (`test-data/<feature>.<locale>.yaml` missing), tests will silently fall back to base locale values — the run will execute but won't actually exercise the locale. Before kicking off Phase 0.5, check:
+{{/cap}}
+{{^cap parallel-subagents}}
+**`--env <locale>` pre-flight**: when `--env` is passed AND the matching overlay file doesn't exist yet (`test-data/<feature>.<locale>.yaml` missing), tests will silently fall back to base locale — the run will execute but won't actually exercise the locale. Before Phase 0.5, check:
+{{/cap}}
 
 ```bash
 ls qa/<screens|flows>/<name>/test-data/*.<locale>.yaml 2>/dev/null | wc -l
 ```
 
+{{#cap parallel-subagents}}
 If the count is 0 → use `AskUserQuestion` to offer:
 - **Run `/sungen:locale <name> <locale>` first** (Recommended) — bootstrap the overlay before running tests
 - **Continue anyway** — run with empty overlay (tests will assert base-locale text, will likely fail on a real locale page)
+{{/cap}}
+{{^cap parallel-subagents}}
+Count 0 → offer the user:
+- **Run `/sungen-locale <name> <locale>` first** (Recommended) — bootstrap the overlay
+- **Continue anyway** — tests will likely fail on a real locale page
+{{/cap}}
 - **Cancel**
 
+{{#cap parallel-subagents}}
 Skip this pre-flight when `--env` matches the base locale (no overlay needed in that case).
+{{/cap}}
+{{^cap parallel-subagents}}
+Skip when `--env` matches the base locale.
+{{/cap}}
 
 **Auto-detect context**: check if `qa/api/<name>/` or `qa/api/flows/<name>/` exists → **API unit mode** (below). Else if `qa/flows/<name>/` → flow mode (base path: `qa/flows/<name>/`). Else `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
 
 ## API unit mode (driver-api) — no selectors
 
+{{#cap parallel-subagents}}
 If the unit is **api-first**, skip every selector/capture phase (an API test has no DOM). Instead:
 
 1. **Resolve the datasource** — ensure the `kind: api` datasource's `base_url` + auth are wired in `qa/datasources.yaml` + `.env.qa` (the `${X_URL}` key from `sungen api init`). A `production` datasource is refused unless `SUNGEN_ALLOW_PROD=1`.
@@ -47,6 +114,15 @@ If the unit is **api-first**, skip every selector/capture phase (an API test has
    - **400 "parameter missing" / body ignored** → the endpoint wants a form body, not JSON → set `encoding: form` (or `multipart`) on the catalog entry, re-`generate --area`. Don't mark the scenario `@manual`.
    - **flaky** → enforce self-cleaning flows, per-row isolation (`@cases`), `@concurrent` caps.
 5. **Integrity + trace** — `sungen script-check --area <name>` (verify the spec is a 1:1 of the Gherkin; on DRIFT re-`generate --area`, never hand-edit) and `sungen trace --area <name>` (process map + HUMAN-LOOP FOCUS). Then report + offer next steps.
+{{/cap}}
+{{^cap parallel-subagents}}
+If the unit is **api-first**, skip every selector/capture phase (an API test has no DOM):
+1. **Resolve the datasource** — `base_url` + auth wired in `qa/datasources.yaml` + `.env.qa` (`${X_URL}` from `sungen api init`); a `production` datasource is refused unless `SUNGEN_ALLOW_PROD=1`.
+2. **Compile**: `npx sungen generate --area <name>` → `specs/generated/api/<name>/`.
+3. **Run**: `npx playwright test specs/generated/api/<name>/<name>.spec.ts`.
+4. **Auto-fix** (use `sungen-error-mapping`): 401/403 → `@hybrid`+`@auth` or `Bearer :token` header (`sungen makeauth`); base_url unresolved → set `${X_URL}`; missing param → trace `{{var}}` to test-data/a prior `@api` response; `expect.status` mismatch → reconcile against `apis.yaml` (re-`generate --area`, never hand-edit the spec); **400 "parameter missing" / body ignored → set `encoding: form` (or `multipart`) on the catalog entry, don't mark @manual**; flaky → self-clean + `@concurrent` caps.
+5. **Integrity + trace** — `sungen script-check --area <name>` (1:1; on DRIFT re-`generate --area`, never hand-edit the spec) + `sungen trace --area <name>` (process map + HUMAN-LOOP FOCUS). Report + offer next steps.
+{{/cap}}
 
 ## Pre-run (phased — per `sungen-selector-fix` skill)
 
@@ -99,10 +175,17 @@ If the unit is **api-first**, skip every selector/capture phase (an API test has
 6. **Phase 2 — Priority Wave**: Run all `@high` scenarios. Fix only failures from this wave. Max 2 attempts. Shared selectors fixed here cascade to later phases.
 7. **Phase 3 — Full Run**: Run all tests. Fix only **new** failures (elements unique to `@normal`/`@low`). Max 1 attempt. Don't loop on low-priority failures.
 8. **Phase 4 — Regression**: One final full run. Report results. No more fix loops.
+9. **Phase 8 — Serial-cascade risk check** (#414): If any scenario has many steps, a skipped test may cause downstream steps to be incorrectly skipped due to the serial-cascade sensor detecting false "not reached" conditions. When you see "test skipped" messages during Phase 3–4 runs, check if the skipped scenario is a **blockers-exist** dependency in the test ledger (`sungen ledger query --screen <name>`). If the scenario had high step count and cascade fired, offer: *"Scenarios with deep steps can trigger serial-cascade skipping. Consider parallelizing this spec with `@concurrent` tags or breaking into smaller scenarios. See `sungen-selector-fix` § Phase 8."* Let the user decide whether to refactor (do not auto-apply parallelization).
+{{#cap parallel-subagents}}
 9. **Integrity check & trace (always run after the final run).**
    - `sungen script-check --screen <name>` — verify the generated spec is a **1:1** of the Gherkin (every non-@manual scenario ↔ one `test()`, no drift). If it reports **DRIFT** (spec hand-edited or stale), re-run `sungen generate --screen <name>` so the spec matches the feature, then re-run — **never hand-edit the generated spec** (auto-fix must edit `selectors.yaml`, not the `.spec.ts`).
    - `sungen ledger record --screen <name> --step run --ms <elapsed>` (record this run), then `sungen trace --screen <name>` — show the process map + bottlenecks + **HUMAN-LOOP FOCUS** (the @manual scenarios the QA must verify) to the user.
 10. **Capability-pending offer (consent-gated).** If `sungen audit --screen <name>` reports `AUTOMATION-READY-PENDING` (or the run shows `@requires:<cap>` tests skipped "requires …"), these are **automation-ready** scenarios waiting on an opt-in driver. Use `AskUserQuestion` to offer: *"N scenario(s) are automation-ready — enable `<cap>` to run them? (`sungen capability add <cap>`)"*. **Only on the user's yes** run `sungen capability add <cap>` then re-run those specs; on no, leave them skipped (they are NOT failures and NOT manual). **Never auto-install.**
+{{/cap}}
+{{^cap parallel-subagents}}
+9. **Integrity & trace (always run after the final run).** `sungen script-check --screen <name>` — verify the spec is a **1:1** of the Gherkin; if **DRIFT**, re-run `sungen generate --screen <name>` (never hand-edit the `.spec.ts` — auto-fix edits `selectors.yaml`). Then `sungen ledger record --screen <name> --step run --ms <elapsed>` and `sungen trace --screen <name>` to show the process map + bottlenecks + **HUMAN-LOOP FOCUS**.
+10. **Capability-pending offer (consent-gated).** If `sungen audit` reports `AUTOMATION-READY-PENDING` (or `@requires:<cap>` tests are skipped "requires …"), offer: *"N scenario(s) are automation-ready — enable `<cap>` to run them? (`sungen capability add <cap>`)"*. Only on the user's yes, run `sungen capability add <cap>` + re-run; on no, leave skipped (not failures, not manual). **Never auto-install.**
+{{/cap}}
 
 ## Playwright command guidelines
 
@@ -129,7 +212,9 @@ for spec in specs/generated/<name>/*.spec.ts; do
   PLAYWRIGHT_JSON_OUTPUT_NAME="specs/generated/<name>/${base}-test-result.json" \
     npx playwright test "$spec"
 done
+{{#cap parallel-subagents}}
 # → writes <basename>-test-result.vi.json for each feature
+{{/cap}}
 
 # ✅ Flow
 PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/flows/<name>/<name>-test-result.json \
@@ -140,26 +225,52 @@ PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/flows/<name>/<name>-test-result.json
 
 ```bash
 # ❌ Wrong — --reporter flag disables the config's JSON reporter
+{{#cap parallel-subagents}}
 npx playwright test specs/generated/<screen>/<screen>.spec.ts --reporter=list
+{{/cap}}
+{{^cap parallel-subagents}}
+npx playwright test specs/generated/<name>/<name>.spec.ts --reporter=list
+{{/cap}}
 
 # ❌ Wrong — no env var → writes to default test-results/results.json
 # (overwritten on every screen run, loses per-screen tracking)
+{{#cap parallel-subagents}}
 npx playwright test specs/generated/<screen>/<screen>.spec.ts
+{{/cap}}
+{{^cap parallel-subagents}}
+npx playwright test specs/generated/<name>/<name>.spec.ts
+{{/cap}}
 ```
 
 If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter override.
 
+{{#cap parallel-subagents}}
 `sungen delivery` reads per-feature `<basename>-test-result[.env].json` files (one per feature in the screen) and writes one CSV/XLSX per feature (e.g. `home-testcases.csv` + `home-modal-testcases.csv`). When `--env <locale>` was used here, run delivery with the same locale (`/sungen:delivery <name> --env <locale>`) so it picks the matching `*-test-result.<locale>.json` files and produces `*-testcases.<locale>.csv` / `.xlsx`.
+{{/cap}}
+{{^cap parallel-subagents}}
+`sungen delivery` reads per-feature `<basename>-test-result[.env].json` files (one per feature in the screen) and writes one CSV/XLSX per feature (e.g. `home-testcases.csv` + `home-modal-testcases.csv`). When `--env <locale>` was used here, run delivery with the same locale (`/sungen-delivery <name> --env <locale>`) so it picks the matching `*-test-result.<locale>.json` files and produces `*-testcases.<locale>.csv` / `.xlsx`.
+{{/cap}}
 
 ## Next steps
 
 After showing results, use `AskUserQuestion` to offer next steps:
 
 If all tests **passed**:
+{{#cap parallel-subagents}}
 - **`/sungen:create-test <screen>`** — Add more test cases (Recommended)
+{{/cap}}
+{{^cap parallel-subagents}}
+- **`/sungen-create-test <name>`** — Add more test cases (Recommended)
+{{/cap}}
 - **Done** — All tests passed, I'm finished
 
 If tests **failed** (after retries):
+{{#cap parallel-subagents}}
 - **`/sungen:run-test <screen>`** — Re-run after manual fixes
 - **`/sungen:create-test <screen>`** — Revise test cases
+{{/cap}}
+{{^cap parallel-subagents}}
+- **`/sungen-run-test <name>`** — Re-run after manual fixes
+- **`/sungen-create-test <name>`** — Revise test cases
+{{/cap}}
 - **Done for now** — I'll fix manually later

package/dist/orchestrator/templates/ai-src/config/codex.md

@@ -0,0 +1,8 @@
+# AGENTS.md — sungen
+
+This project uses **sungen** (Gherkin → Playwright test compiler). Its workflow and
+reference skills are installed under `.agents/skills/sungen-*`. Codex auto-discovers them;
+pick a workflow step with `/skills` or `$sungen-create-test`, or just describe the task
+(e.g. "create a test for the login screen") and the matching skill triggers by description.
+
+Workflow order: add-screen → create-test → review → run-test → delivery.

package/{src/orchestrator/templates/ai-instructions/claude-skill-capture-mobile.md → dist/orchestrator/templates/ai-src/skills/sungen-capture-mobile/SKILL.md}

@@ -30,7 +30,12 @@ Resolve in this order:
 1. `Path:` line in the feature / `App ID` in `spec.md` → split into `appPackage` + `appActivity`.
    A dual-id Path (`<pkg>/<activity> | <iosBundleId>`) → take the part for the OS you are exploring
    (left of `|` = Android pkg/activity, right = iOS bundle id).
+{{#cap parallel-subagents}}
 2. If missing → `AskUserQuestion`: *"What is the appPackage/appActivity (Android) or bundleId (iOS)?"*
+{{/cap}}
+{{^cap parallel-subagents}}
+2. If missing → ask the user: *"What is the appPackage/appActivity (Android) or bundleId (iOS)?"*
+{{/cap}}
 3. **Navigation recipe** — read the feature's `Background:` (the in-app web-path analog). Line 1
    `Given User is on [Home] screen` is the launcher/landing screen the app opens on; each following
    `When/And User tap [...]` (or gesture) is one hop toward the target screen. You will **replay**
@@ -80,8 +85,14 @@ After the LAST step you are on the target screen — capture HERE (steps 5–6).
   screen.** Screenshot where you are and report: *"recipe step N: [Label] not found — fix the
   Background nav path."* Fail loud (run-test would fail at the same step anyway).
 - **No recipe yet** (guided-stub Background, but the target is NOT the launcher) ⇒ drive to the
+{{#cap parallel-subagents}}
   screen interactively off the live tree (if unsure which control leads there, `AskUserQuestion`),
   then **report the exact nav steps you took** so create-test/add-screen can write them into the
+{{/cap}}
+{{^cap parallel-subagents}}
+  screen interactively off the live tree (if unsure which control leads there, ask the user), then
+  **report the exact nav steps you took** so create-test/add-screen can write them into the
+{{/cap}}
   Background. Do **not** edit the `.feature` yourself — Gherkin authorship stays with those commands.
 
 ### 5. Capture the locator tree (primary AI context)

package/dist/orchestrator/templates/{ai-instructions/github-skill-sungen-error-mapping.md → ai-src/skills/sungen-error-mapping/SKILL.md}

@@ -21,13 +21,51 @@ Then choose the fix from the patterns below.
 
 ---
 
+## ⛔⛔ HARD RULE — the `.feature` (Gherkin) is FROZEN during run-test
+
+The Gherkin test cases have been **reviewed and approved by QA**. During the run-test auto-fix
+loop you **MUST NOT change their content or logic**. Concretely, you may write only:
+
+- ✅ `selectors.yaml` — locators (the normal auto-fix)
+- ✅ `test-data.yaml` and other `*.yaml` data files
+- ✅ **ONE narrow `.feature` edit:** the **element-type token** on a `[Reference]`
+  (e.g. `[Email] field` → `[Email] textbox`, `button` → `link`). This is selector resolution,
+  not test logic. NEVER touch the reference name, the step keyword, the expected value, the
+  assertion, or the scenario structure.
+
+**Forbidden in `.feature` (all of these are content/logic — report, don't edit):**
+adding/removing/rewriting steps, adding `wait for` steps, changing expected values or rules,
+weakening assertions, "fixing" an unknown step pattern, adding table-scope steps. If a failure
+needs any of these, it is a **finding for QA** — surface it in the run summary and let the test
+**FAIL**. A failing test may be a **real bug**; do not edit the QA-approved Gherkin to make it pass.
+
+## ⛔ Source of truth — classify EVERY failure before you "fix" it
+
+`.feature` + `test-data.yaml` + `spec.md` are the **oracle**. The **live page is NOT** — it may be the thing that's broken. A failing test is not automatically a test to "make pass". Classify first:
+
+- **Selector-resolution failure** (element not found / wrong locator / strict-mode / wrong element type) → the test looked in the wrong place. **Fix the locator in `selectors.yaml`** (re-snapshot, copy the exact accessible name). Legit auto-fix.
+- **Assertion-value failure** (element FOUND, but observed value ≠ expected) → STOP and ask the decisive question: ***does `spec.md` PIN this exact value?***
+  - **Spec PINS the value and live contradicts it** (spec mandates X, app shows Y) → **CANDIDATE BUG**. **Report it** (let the test FAIL). **NEVER** change the expected, loosen the rule, weaken the assertion (`toHaveText`→`toContainText`), shrink a boundary (`>8`→`>=6`), or edit `.feature`/`.spec.ts` to pass.
+  - **Spec does NOT pin the exact string, and your expected was your own transcription/guess** (whitespace, casing, punctuation, or a label the spec only *describes* narratively) while the live value is the legitimate, spec-consistent truth → **accuracy fix (allowed):** set `test-data.yaml`/`.feature` to the **real** value — *not* weakening, the claim is unchanged. (e.g. hero `<h1>` renders `AutomationExercise`; spec says "the Automation Exercise logo" but pins no string → fix `hero_title` to `"AutomationExercise"`, don't leave it failing.)
+  - Expected is wrong **relative to a value `spec.md` DOES state** (typo vs the spec) → fix to the **spec** value, never the live page.
+
+> **Accuracy fix vs weakening — the line:** an *accuracy fix* matches a spec-consistent reality the spec didn't pin (cosmetic, meaning preserved). *Weakening* changes the **oracle** to dodge a real discrepancy. **If the spec pins it, or you're unsure → treat as a bug and leave it failing.**
+
+> **Cardinal sin (do NOT do this):** a `password > 8 chars` rule fails on a 6-char input → "fix" it to `>= 6` so the test passes. The logic is now meaningless. A failing assertion is a **finding**, not a chore.
+
+**Auto-fix loop scope:** the run-test auto-fix loop engages ONLY on **selector-resolution** failures. On an assertion-value failure where the app contradicts the spec → **HALT and report**, do not loop it into passing.
+
+**Never hand-edit the generated `.spec.ts`** (e.g. inserting `page.evaluate`/`fetch` to bypass a broken control). `sungen script-check` regenerates the spec from `.feature` and flags any edit as DRIFT — regenerate, don't patch.
+
+---
+
 ## Fix Priority (try in order)
 
 1. **Auth issue** — page redirected to login? Fix auth first, everything else is noise
 2. **Element not found** — wrong name/type/value in selectors.yaml. Re-snapshot, copy exact name
 3. **Multiple matches** — add `nth`, `exact: true`, or `scope` to narrow down
 4. **Wrong assertion** — `toHaveText` vs `toHaveValue` mismatch, wrong expected data
-5. **Timing** — SPA not loaded, async content. Add `wait for` step in .feature
+5. **Timing** — SPA not loaded, async content. Prefer tuning waits/caching in `specs/base.ts` (see Performance section). Do NOT add a `wait for` step to `.feature` — if the test genuinely needs a wait step, **report it** as a Gherkin gap for QA; the auto-fix loop must not edit the approved Gherkin.
 
 ---
 
@@ -43,11 +81,13 @@ Then choose the fix from the patterns below.
 | not a select | Custom dropdown, not native `<select>` | Set `variant: 'custom'` |
 | Frame not found | iframe selector wrong or doesn't exist | Fix `frame` value, verify iframe in snapshot |
 
-### Assertion errors → fix in `test-data.yaml` or `.feature`
+### Assertion errors → apply the Source-of-truth gate above FIRST
 
-| Error | Diagnosis | Fix |
+> The "Fix" column below applies **only when the expected value was wrong relative to `spec.md`** (a test defect). If the app's value contradicts the spec, the row is a **candidate bug → report it, do not edit the expected to match live**. Never weaken `toHaveText`→`toContainText` just to pass.
+
+| Error | Diagnosis | Fix (only if the TEST was wrong per spec) |
 |---|---|---|
-| toHaveText mismatch | Expected text differs from actual | Fix value in test-data. If element is input type → change Gherkin type to `field`/`textarea` (triggers `toHaveValue` instead) |
+| toHaveText mismatch | Expected text differs from actual | If the test's expected was wrong per spec → fix value in **test-data** (not `.feature`). If element is an input → change only the **element-type token** in `.feature` (e.g. `field`/`textarea`, the allowed selector-type edit). If the app value contradicts spec → **report as bug, let it FAIL**. |
 | toHaveValue mismatch | Expected value differs from actual | Fix value in test-data |
 | toContainText mismatch | Partial text not found | Fix expected partial text in test-data |
 | toBeVisible timeout | Element exists but hidden, or name wrong | Check: is element conditionally visible? Wrong name? Inside dialog? |
@@ -60,7 +100,7 @@ Sungen picks assertion based on element type:
 - **Text** (everything else: `message`, `heading`, `label`, `row`) → `toHaveText()`
 - **Partial** (`contains` keyword) → `toContainText()`
 
-If `toHaveText` fails on an input → the Gherkin step has wrong target type. Fix: change type in `.feature`.
+If `toHaveText` fails on an input → the Gherkin step has the wrong target type. Fix: change **only the element-type token** in `.feature` (e.g. `[Email] message` → `[Email] field`). This is the one permitted `.feature` edit — do not change the reference name, value, or anything else.
 
 ---
 
@@ -68,7 +108,7 @@ If `toHaveText` fails on an input → the Gherkin step has wrong target type. Fi
 
 | Error | Diagnosis | Fix |
 |---|---|---|
-| `tableRow is not defined` | Column assertion without preceding row scope step | Add `User see [Ref] row in [Table] table with {{v}}` before `User see [Col] column with {{v}}` |
+| `tableRow is not defined` | Column assertion without preceding row scope step | The Gherkin is missing a row-scope step — this is a **QA authoring gap → report it, let it FAIL**. Do NOT add the step during run-test (the Gherkin is frozen). |
 | `toHaveText` on cell fails (with columns) | Wrong column index in `columns` config | Re-count columns in snapshot (0-indexed). Fix `index` in selectors.yaml |
 | `toBeVisible` on cell fails (no columns) | `filter({ hasText })` didn't match | Check exact cell text in snapshot. Fix value in test-data |
 | Row filter matches 0 rows | Filter text doesn't match any row content | Re-snapshot → find actual row text. Fix filter value in test-data |
@@ -84,7 +124,7 @@ If `toHaveText` fails on an input → the Gherkin step has wrong target type. Fi
 | Redirect to login page | Auth expired. Ask user to log in manually via MCP browser |
 | `storageState` file not found | Ask user to log in manually via MCP browser, then save storage state |
 | Most tests timeout on first step | Auth expired — ask user to re-authenticate via MCP browser |
-| Page shows home instead of target | SPA + expired auth. Re-authenticate + add `wait for` step |
+| Page shows home instead of target | SPA + expired auth. Re-authenticate via MCP browser. (If a wait is genuinely needed, tune `specs/base.ts` — do NOT add a `wait for` step to the frozen `.feature`.) |
 
 **Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
 
@@ -94,7 +134,7 @@ If `toHaveText` fails on an input → the Gherkin step has wrong target type. Fi
 
 | Error | Fix |
 |---|---|
-| Unknown step pattern | Rewrite step to match `sungen-gherkin-syntax` patterns |
+| Unknown step pattern | The Gherkin uses a step the compiler doesn't recognize — a **QA authoring issue → report it, let it FAIL**. Do NOT rewrite the step during run-test (the Gherkin is frozen; fix belongs in create-test/review). |
 | Missing selector | Add key to `selectors.yaml` |
 | Missing variable | Add key to `test-data.yaml` |
 | Invalid selector type | Use: role/testid/placeholder/label/text/locator/page/upload/frame |
@@ -105,7 +145,7 @@ If `toHaveText` fails on an input → the Gherkin step has wrong target type. Fi
 
 | Error | Diagnosis | Fix |
 |---|---|---|
-| Navigation timeout between screens | Cross-screen transition takes too long or URL mismatch | Add explicit `wait for page` step between screen transitions in `.feature`. Verify target URL path |
+| Navigation timeout between screens | Cross-screen transition takes too long or URL mismatch | Verify the target URL path; tune navigation waits in `specs/base.ts`. Do NOT add a `wait for page` step to `.feature` — if the flow genuinely needs one, **report it** as a Gherkin gap for QA. |
 | Selector `"screen:element"` not found | Namespace key missing or wrong format | Ensure colon-namespaced key in `selectors.yaml` is **quoted**: `"login:submit":`. Check screen prefix matches `[Screen:Element]` ref in Gherkin |
 | Test data `screen.key` undefined | Phase namespace mismatch | Verify `test-data.yaml` uses dot-namespaced keys: `login.email`, `submission.nominee`. Keys must match `{{screen.key}}` refs in `.feature` |
 | State lost between screens | Auth/session expired during multi-screen flow | Ensure all screens in the flow share the same `@auth:role` tag. Check if the app invalidates sessions on navigation |

package/{src/orchestrator/templates/ai-instructions/claude-skill-harness-audit.md → dist/orchestrator/templates/ai-src/skills/sungen-harness-audit/SKILL.md}

@@ -71,15 +71,15 @@ Use these when repairing GATE/DEPTH findings for the hard viewpoints (cart/detai
 ## Discovery / fallback tree (when input is limited)
 
 ```
-spec.md đủ tốt?      → YES: Spec-first
+spec.md good enough?       → YES: Spec-first
   │ NO
-source code có?      → YES: Source-first (mine behavior từ code)
+source code available?     → YES: Source-first (mine behavior from code)
   │ NO
-testcase cũ tương tự?→ YES: History-first
+similar legacy testcases?  → YES: History-first
   │ NO
-domain rủi ro+defect?→ YES: Defect-first
+risky domain + defects?    → YES: Defect-first
   │ NO
-→ hỏi QA; QA chưa phản hồi → OUTPUT kèm ASSUMPTION LIST rõ ràng (không stall)
+→ ask QA; if QA hasn't responded → OUTPUT with an explicit ASSUMPTION LIST (do not stall)
 ```
 
 See `docs/orchestration-spec.md` for the full flow and `docs/spec/sungen_refactor_spec.md` for the design rationale.