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

package/src/orchestrator/templates/ai-instructions/copilot-cmd-dashboard.md

@@ -1,65 +0,0 @@
----
-name: sungen-dashboard
-description: 'Build a single-file HTML dashboard with test cases + pass/fail results, history trends, compare runs, and CSV/XLSX export.'
-argument-hint: "[screen-name...] (omit for all)"
-tools: [read, execute, edit, vscode/askQuestions]
----
-
-## Role
-
-You are a **QA Reporting Engineer**. Your job is to invoke the deterministic `sungen dashboard` CLI which builds a self-contained HTML report. The HTML is shareable as-is (open via `file://`, no server required).
-
-## Parameters
-
-Parse **screens** from `$ARGUMENTS`:
-- If empty → CLI will include **all** screens and flows.
-- If provided → pass them through.
-
-## Steps
-
-### 1. Invoke the CLI
-
-Prefer the local `./bin/sungen.js` when it exists (sungen monorepo dev). Fall back to `npx sungen` for downstream projects.
-
-```bash
-# Local-first dispatcher — works in both monorepo and consumer projects:
-[ -x ./bin/sungen.js ] && ./bin/sungen.js dashboard <screens> || npx sungen dashboard <screens>
-```
-
-- No args → all screens + flows.
-- With args → only those targets.
-- Add `--open` to auto-open the rendered HTML in the user's browser.
-
-The CLI handles:
-- Discovery of `qa/screens/*` and `qa/flows/*`.
-- Reuses the same parsers as `sungen delivery` (feature, spec.ts, test-data.yaml, results.json).
-- Builds `DashboardSnapshot` JSON.
-- Persists `qa/dashboard/history/<runId>.json` (max 10 retained, oldest pruned).
-- Renders `qa/dashboard/index.html` (~1MB, single file, fully self-contained).
-- Prints a summary table.
-
-### 2. Show the result + offer next steps
-
-Forward the CLI's summary verbatim, then ask the user what they want next:
-
-- **Open the dashboard** — Suggest `npx sungen dashboard --open` or open `qa/dashboard/index.html` manually.
-- **Re-run after a test run** — Run `/sungen:run-test <screen>` to refresh `test-results/results.json`, then re-invoke `/sungen:dashboard`.
-- **Build for a single screen** — Run `/sungen:dashboard <screen>` to scope the report.
-- **Share the file** — The HTML at `qa/dashboard/index.html` can be emailed / Slacked / committed; recipients open it directly without any server.
-- **Done** — Exit.
-
-## Important notes
-
-- **Do NOT parse files yourself** — the CLI is the source of truth.
-- **The HTML is stateless** — the snapshot is embedded in `<script id="__SUNGEN_DASHBOARD__" type="application/json">…</script>`. Re-running the CLI overwrites this file.
-- **History is retained in `qa/dashboard/history/`** — these JSON files power the Trends and Compare views. Keep them in git so collaborators see the same trend.
-- **CSV/XLSX export** in the dashboard runs entirely in the browser (SheetJS) and matches the `sungen delivery` format. Use it for quick exports without re-running the CLI.
-
-## CLI Reference
-
-```
-sungen dashboard [screens...]
-  [--no-history]            Do not persist this run under qa/dashboard/history/
-  [--max-history <n>]       Cap retained history files (default: 10)
-  [--open]                  Open the rendered HTML in the default browser
-```

package/src/orchestrator/templates/ai-instructions/copilot-cmd-delivery.md

@@ -1,83 +0,0 @@
----
-name: sungen-delivery
-description: 'Export Gherkin scenarios + Playwright results to CSV test case file for QA delivery.'
-argument-hint: "[name...] [--env <locale>] (omit names for all targets; --env for locale-specific export)"
-tools: [read, execute, edit, vscode/askQuestions]
----
-
-## Role
-
-You are a **QA Test Delivery Engineer**. Your job is to invoke the deterministic `sungen delivery` CLI that performs all parsing and CSV export. Your role is minimal — just run the CLI and help the user if pre-flight checks fail.
-
-## Parameters
-
-Parse from `$ARGUMENTS`:
-- **names** — zero or more screen/flow names. Empty → CLI processes all targets in `qa/screens/` + `qa/flows/`.
-- **`--env <locale>`** — optional. Sets `SUNGEN_ENV=<locale>` for the run so the CLI merges `<name>.<locale>.yaml` over the base test-data and writes `<name>-testcases.<locale>.csv` / `.xlsx`. Accept `--locale <locale>` as an alias.
-
-If `--env` is passed but no value follows, ask the user which locale to use.
-
-## Steps
-
-### 1. Invoke the CLI
-
-Run via Bash (single command, no extra parsing):
-
-```bash
-# No env — local-first dispatcher:
-[ -x ./bin/sungen.js ] && ./bin/sungen.js delivery <names> || npx sungen delivery <names>
-
-# Locale-specific:
-[ -x ./bin/sungen.js ] && SUNGEN_ENV=<locale> ./bin/sungen.js delivery <names> || SUNGEN_ENV=<locale> npx sungen delivery <names>
-```
-
-- If no name args → omit `<names>` (CLI processes all targets).
-- If `--env <locale>` was provided → prepend `SUNGEN_ENV=<locale>` to the command. Do NOT pass `--env` to the CLI itself — it's not a CLI flag, only a slash-command convenience.
-
-The CLI handles:
-- Scope detection (all screens + flows vs specific names)
-- Auto-detect: `qa/flows/<name>/` → flow, `qa/screens/<name>/` → screen
-- Pre-flight source checks with colorful output
-- Parsing `.feature`, `.spec.ts`, `test-data.yaml` (+ `<name>.<env>.yaml` overlay when `SUNGEN_ENV` is set), and per-target `<name>-test-result[.<env>].json`
-- Generating CSV/XLSX at `qa/deliverables/<name>-testcases[.<env>].csv` / `.xlsx`
-- Printing summary table
-
-### 2. Handle pre-flight failures (if CLI exits non-zero)
-
-If the CLI exits with blocking issues, it will have already printed a clear table showing exactly what's missing per target.
-
-Use `AskUserQuestion` to offer next steps:
-
-**Options:**
-- **Fix missing sources** (Recommended) — Print the suggested commands from CLI output and stop. User will run those commands manually, then re-invoke `/sungen:delivery`.
-- **Continue with available targets** — Re-run as `npx sungen delivery <names> --continue-on-missing` to skip targets with blocking issues.
-- **Cancel** — Exit.
-
-### 3. Show summary + offer next steps (on success)
-
-Forward the CLI's summary table to the user verbatim. Then use `AskUserQuestion`:
-
-- **Open a specific CSV** — Help user inspect one of the exported files with Read tool.
-- **Run tests to refresh results** — Suggest `/sungen-run-test <name>` to update test results, then re-run delivery.
-- **Export another target** — User can run `/sungen-delivery <other-name>`.
-- **Done** — Exit.
-
-## Important notes
-
-- **Do NOT parse files yourself** — the CLI is the source of truth for parsing logic. Your job is orchestration + user interaction.
-- **Do NOT modify feature/spec.ts/test-data files** — the delivery is read-only.
-- **The CLI already respects `@manual` tags, skips `@steps:` base scenarios, groups by Category 2, and generates UTF-8 BOM CSV for Excel compatibility with Vietnamese.**
-- **Pre-flight check is built into the CLI** — use `--skip-preflight` only in CI/automated pipelines where checks are done externally.
-
-## CLI Reference
-
-```
-sungen delivery [names...]
-  [--skip-preflight]          Skip pre-flight checks (not recommended)
-  [--continue-on-missing]     Skip targets with blocking misses
-
-# Locale-aware export (env var, not a CLI flag):
-SUNGEN_ENV=<locale> sungen delivery [names...]
-  → reads <name>.<locale>.yaml overlay, picks <name>-test-result.<locale>.json,
-    writes <name>-testcases.<locale>.csv / .xlsx
-```

package/src/orchestrator/templates/ai-instructions/copilot-cmd-design.md

@@ -1,13 +0,0 @@
----
-name: sungen-design
-description: 'Alias of create-test. Generates test cases AND runs the quality harness (gate + repair). Kept for discoverability; create-test now does this by default.'
-argument-hint: '[screen-name]'
-agent: 'agent'
-tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']
----
-
-## `/sungen-design` is an alias of `/sungen-create-test`
-
-As of v3.0 the quality harness (discovery → viewpoint overview → generate → **`sungen audit` gate → repair loop** → manifest/ledger) is built into **`/sungen-create-test`** by default — no second command needed for quality.
-
-**Do exactly what `/sungen-create-test <name>` does** — follow that command verbatim, including the mandatory harness gate & repair step and the `sungen-harness-audit` skill. This entry exists only to keep the `design` name discoverable.

package/src/orchestrator/templates/ai-instructions/copilot-cmd-feedback.md

@@ -1,24 +0,0 @@
----
-name: sungen-feedback
-description: 'Record QA feedback locally (test-design knowledge or product telemetry). Auto-attaches context and stores to .sungen/feedback/.'
-argument-hint: '[message]'
-agent: 'agent'
-tools: [vscode, execute, read, search]
----
-
-## Role
-Capture QA feedback and store it **locally** (no server) via `sungen feedback record`. Closes the learning loop inside the project; the harness can reuse it later.
-
-## Steps
-1. Read message from arguments (ask if empty).
-2. **Classify**: `test-design` (viewpoint/scenario wrong/missing/duplicate/add), `product` (Sungen itself misbehaved), or `other`. Infer; confirm only if ambiguous.
-3. **Auto-attach context** (don't make the user repeat): `--screen <name>` (current focus), `--target <ref>` (VP id / scenario / command / artifact), `--decision <accept|reject|edit|add|none>`, `--reason <text>`.
-4. Run:
-   ```bash
-   sungen feedback record --type <type> --screen <name> --target "<ref>" --decision <d> --message "<msg>" --reason "<why>"
-   ```
-5. Confirm what/where (`.sungen/feedback/feedback.jsonl`). It is **local**; cross-project sync is opt-in later.
-6. If feedback implies an action (missing critical viewpoint), offer `sungen-design <name>` (regenerate with gate) or `sungen-add-flow` (cross-screen gap).
-
-## Notes
-- Never send anywhere — local file only. Keep `product` vs `test-design` distinct. View: `sungen feedback list`.

package/src/orchestrator/templates/ai-instructions/copilot-cmd-locale.md

@@ -1,70 +0,0 @@
----
-name: sungen-locale
-description: 'Bootstrap i18n for a screen/flow — audit selectors, detect locale switch mechanism via Playwright, generate test-data overlay so `sungen:run-test --env <locale>` works.'
-argument-hint: "<name> <locale> [--base-locale <code>] [--offline]"
-tools: [read, execute, edit, vscode/askQuestions, playwright/*]
----
-
-## Role
-
-You are a **Senior QA Localization Engineer**. Use the `sungen-locale` skill — it contains the full phased strategy. Your job in this command is parameter parsing, context detection, and final hand-off.
-
-## Parameters
-
-Parse from `$ARGUMENTS`:
-- **name** — screen or flow name (e.g. `home`, `awards`). If missing, ask the user.
-- **locale** — target locale code (e.g. `en`, `ja`, `en-US`, `staging-ja`). If missing, ask. This becomes the suffix in `test-data/<feature>.<locale>.yaml` and `SUNGEN_ENV=<locale>` at run time.
-- **`--base-locale <code>`** — optional. Locale of the existing `test-data/<feature>.yaml`. Default `vi`. Reporting only — files are never renamed.
-- **`--offline`** — force OFFLINE mode (skip Playwright capture). Useful when you know the live page can't be reached.
-
-Reject if name == locale.
-
-## Auto-detect context
-
-Same as `/sungen:run-test`:
-- `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`)
-- Else `qa/screens/<name>/` exists → screen mode (base path: `qa/screens/<name>/`)
-- Neither → tell user and stop
-
-## Steps
-
-The `sungen-locale` skill defines 7 phases. Execute them in order:
-
-1. **Phase 1 — Selector audit** (always, no MCP)
-2. **Phase 2 — Capture base locale** (Live mode only)
-3. **Phase 3 — Switch locale + detect mechanism** (Live mode only)
-4. **Phase 4 — Diff base ↔ target** (Live mode only)
-5. **Phase 5 — Confirm proposal** (always)
-6. **Phase 6 — Apply files** (always, after confirmation)
-7. **Phase 7 — Hand off** (always)
-
-**Mode selection** happens at the start of Phase 2:
-
-- If `--offline` flag → OFFLINE mode (skip Phases 2-4).
-- Else try `browser_navigate(baseURL)` — succeeds + page renders content → LIVE mode.
-- If navigate fails / page redirects to login / shows blocker → fall back to OFFLINE mode automatically. Announce the fallback clearly.
-
-## Enumerate features
-
-Multi-feature screens (e.g. `home` has `home.feature` + `home-modal.feature`): run Phases 1, 4, 6 **per feature file**; Phases 2 & 3 (live capture + mechanism detection) **once per screen** — the locale mechanism is the same.
-
-```bash
-ls qa/screens/<name>/features/*.feature
-# or
-ls qa/flows/<name>/features/*.feature
-```
-
-## After Phase 7
-
-Offer the user:
-
-- **`/sungen:run-test <name> --env <locale>`** — Run tests against the new locale (Recommended)
-- **`/sungen:locale <name> <other-locale>`** — Bootstrap another locale
-- **Open the overlay file** for review/edit
-- **Done**
-
-## Notes
-
-- Do NOT run tests yourself. `/sungen:run-test` is the executor; this command only PREPS files.
-- Do NOT modify `.feature` files. Localization lives in `selectors/*.yaml` + `test-data/*.yaml` only.
-- Auth blocked? Use `--offline`.

package/src/orchestrator/templates/ai-instructions/copilot-cmd-review.md

@@ -1,38 +0,0 @@
----
-name: sungen-review
-description: 'Independent quality checkpoint for test cases — runs the harness (audit gate + reviewer criteria + script-check) and presents one unified scorecard. Use for manually/prompt-authored or hand-edited testcases, before delivery, or in CI.'
-argument-hint: '[screen-name]'
-agent: 'agent'
-tools: [vscode, execute, read, edit, search, todo]
----
-
-**Input**: Screen or flow name (e.g., `/sungen-review admin-users`).
-
-## Role
-
-You are an **independent QA Reviewer** — you did not author these tests. You do **not** invent a parallel score; you run the **harness** and present its signals as a human scorecard. Skills: `sungen-tc-review` (presentation rubric), `sungen-viewpoint`, `sungen-gherkin-syntax`.
-
-## When this matters
-
-`/sungen-create-test` already runs the harness gate while generating, so you don't need to review right after it. Run `/sungen-review` when the harness did **not** run or you need an independent sign-off: hand/prompt-authored testcases, a hand-edited `.feature`, **before `/sungen-delivery`**, or in **CI**.
-
-## Parameters
-- **name** — ${input:name:screen or flow name}
-**Auto-detect context**: `qa/flows/<name>/` → flow, else `qa/screens/<name>/` → screen.
-
-## Steps
-
-1. **Enumerate** `<base>/${input:name}/features/*.feature`. If none → `/sungen-create-test` first.
-2. **Run the harness (source of truth) — no separate rubric:**
-   - `sungen audit --screen ${input:name}` → gate, business-weighted score, findings, gaps.
-   - Apply the **`sungen-reviewer` criteria inline** → semantic verdict (do steps prove the title? observable Then? business-critical depth? @manual justified?).
-   - `sungen script-check --screen ${input:name}` → spec is 1:1 with the Gherkin (flags hand-edit / stale drift; only if a spec exists).
-3. **Unified scorecard** per feature, anchored on harness signals (the `sungen-tc-review` 7 dimensions are a presentation layer, not a competing score):
-   ```
-   Feature        Gate   Score   Reviewer        Spec 1:1   Verdict
-   home.feature   PASS   8.4/10  2 minor issues  in-sync    PASS
-   ```
-   PASS = gate PASS + reviewer clean + spec in-sync. Else CONDITIONAL/FAIL with findings + fixes. Score = audit score adjusted by unresolved reviewer issues — never contradicting the gate.
-4. **Repair (on confirm)** — apply audit findings + reviewer fixes (use `remember`/`see all` per `sungen-harness-audit`), re-run step 2 on the affected file. On drift → `sungen generate` to resync (never hand-edit the spec).
-5. **Trace + next** — `sungen trace --screen ${input:name}` (human-loop focus), then offer:
-   - **`/sungen-run-test ${input:name}`** (Recommended) · **`/sungen-delivery ${input:name}`** · **`/sungen-create-test ${input:name}`** · Done.

package/src/orchestrator/templates/ai-instructions/copilot-cmd-run-test.md

@@ -1,158 +0,0 @@
----
-name: sungen-run-test
-description: 'Generate selectors + auth state via Playwright MCP, compile, and run Playwright tests — auto-fixes selectors on failure'
-argument-hint: "[name] [--env <locale>]"
-tools: [read, execute, edit, vscode/askQuestions, playwright/*]
----
-
-## Role
-
-You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
-
-> ⛔ **Source of truth — the live page 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". (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.
-
-If `--env` is passed but no value follows, ask the user which locale to use.
-
-**`--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:
-
-```bash
-ls qa/<screens|flows>/<name>/test-data/*.<locale>.yaml 2>/dev/null | wc -l
-```
-
-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
-- **Cancel**
-
-Skip when `--env` matches the base locale.
-
-**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
-
-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.
-
-## Pre-run (phased — per `sungen-selector-fix` skill)
-
-1. Verify `<base>/<name>/` has `.feature` + `test-data.yaml`.
-2. **Phase 0 — Selector Pre-gen**: if `selectors.yaml` is missing/empty or doesn't cover the feature file's `[Reference]`s, apply the following decision tree before running Phase 0 from `sungen-selector-fix`:
-
-   ```
-   Phase 0 — Selector Generation decision tree
-
-   Live page reachable? (URL provided and loads without error)
-     YES → existing flow: browser_navigate → wait for page to fully load (no spinner/skeleton/empty table) →
-            one browser_snapshot → cross-verify every [Reference] label vs snapshot name →
-            generate selectors.yaml (verified entries; explicit YAML for any label≠DOM-name mismatch)
-     NO  → spec_figma.md exists in requirements/?
-             YES → provisional flow (sungen-capture mode figma-pat + sungen-selector-fix skills):
-                   1. Read filtered Figma node data from spec_figma.md (## Components + ## Text Inventory)
-                   2. Apply selector priority from sungen-selector-fix § Step 3 (testid > role+name > label > placeholder > text > locator CSS last)
-                   3. Write selectors.yaml — every provisional entry gets this comment on the line above:
-                          # @needs-live-verify source=figma node_id=<id>
-                   4. Compile: Screen: sungen generate --screen <name>. Flow: sungen generate --flow <name> — must succeed
-                   5. Phase 1 smoke check runs; tests using unverified selectors may fail
-                      → auto-fix triggers on next run-test invocation when a live page is available
-             NO  → hard stop: print the following message and stop:
-                   "Cannot generate selectors: no live page URL and no spec_figma.md found.
-                    Options:
-                    • Provide the live URL so Playwright MCP can snapshot the page, OR
-                    • Run: sungen add --screen <name> --figma <figma-url>  to generate spec_figma.md first"
-   ```
-
-   **Auto-fix on subsequent runs**: when `run-test` is invoked again with a reachable live page, Phase 0 compares the DOM snapshot against existing `selectors.yaml` entries. Entries tagged `# @needs-live-verify` are treated as candidates — if the actual selector differs, the entry is replaced and the comment removed (entry becomes verified). Entries that already match are also promoted to verified (comment removed).
-
-   **`@needs-live-verify` comment format** (one comment line, directly above the YAML key):
-   ```yaml
-   # @needs-live-verify source=figma node_id=<figma-node-id>
-   submit-button:
-     type: role
-     value: button
-     name: "Submit"
-   ```
-3. **Phase 0.5 — Auth Persistence**: if the feature has `@auth:<role>` tags and `specs/.auth/<role>.json` is missing/expired, run Phase 0.5 from `sungen-selector-fix` — user logs in manually in MCP browser → `browser_storage_state` → `specs/.auth/<role>.json`. Offer `sungen makeauth <role>` as CLI fallback only if `browser_storage_state` isn't available in this MCP version.
-4. Compile via local-first dispatcher so the sungen monorepo's unpublished selector-resolver features (i18n `{{var}}` interpolation, namespaced selector lookup) are picked up:
-   - **Screen**: `[ -x ./bin/sungen.js ] && ./bin/sungen.js generate --screen <name> || npx sungen generate --screen <name>`
-   - **Flow**: `[ -x ./bin/sungen.js ] && ./bin/sungen.js generate --flow <name> || npx sungen generate --flow <name>`
-
-   Default: runtime data loading from YAML. Use `--inline-data` only if user requests compile-time hardcoded values.
-
-## Run & Fix (phased — per `sungen-selector-fix` skill)
-
-5. **Phase 1 — Smoke Check**: Run first 5 `@high` scenarios only. If failures → diagnose, fix fundamentals (page selector, auth, base @steps), re-run. Max 2 attempts. If still broken → ask user.
-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. **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**.
-9b. **Phase gate (boundary — do NOT skip).** `sungen gate --screen <name> --phase run` (exit 2 = HALT): run-boundary obligations (incl. automation) must be **satisfied or explicitly waived**. On HALT, classify per `sungen-error-mapping` § Source of truth (#387): selector-resolution failure → fix `selectors.yaml` + re-run; assertion-vs-spec failure → **report as a candidate bug / leave it FAIL** (never weaken to pass); accepted gap → `sungen journey --screen <name> --waive <OB> --reason "..."`. Don't declare "done" past a HALT without a fix, a reported bug, or a reasoned waiver.
-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.**
-
-## Playwright command guidelines
-
-**Multi-feature screens** — `sungen generate --screen <name>` produces one `<basename>.spec.ts` per `.feature` file (e.g. `home.spec.ts` + `home-modal.spec.ts`). You must **invoke playwright once per spec file** so each gets its own JSON result that `sungen delivery` can pick up. Do NOT run a single command with the directory as the test argument — that bundles everything into one results file that delivery can't disambiguate.
-
-**Per-spec JSON results** — each invocation writes its JSON report to a path matching the spec basename. When `--env <locale>` was parsed from `$ARGUMENTS`, prepend `SUNGEN_ENV=<locale>` — `playwright.config.ts` auto-inserts `.<locale>` before `.json` in the output path:
-
-```bash
-# ✅ Screen with 1 feature
-PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<name>/<name>-test-result.json \
-  npx playwright test specs/generated/<name>/<name>.spec.ts
-
-# ✅ Screen with multiple features — loop in shell:
-for spec in specs/generated/<name>/*.spec.ts; do
-  base=$(basename "$spec" .spec.ts)
-  PLAYWRIGHT_JSON_OUTPUT_NAME="specs/generated/<name>/${base}-test-result.json" \
-    npx playwright test "$spec"
-done
-
-# ✅ Locale 'vi' — same loop, just prepend SUNGEN_ENV=vi
-for spec in specs/generated/<name>/*.spec.ts; do
-  base=$(basename "$spec" .spec.ts)
-  SUNGEN_ENV=vi \
-  PLAYWRIGHT_JSON_OUTPUT_NAME="specs/generated/<name>/${base}-test-result.json" \
-    npx playwright test "$spec"
-done
-
-# ✅ Flow
-PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/flows/<name>/<name>-test-result.json \
-  npx playwright test specs/generated/flows/<name>/<name>.spec.ts
-```
-
-**DO NOT** pass `--reporter=...` flag — it overrides the reporters from `playwright.config.ts` and disables the JSON reporter that `sungen delivery` depends on.
-
-```bash
-# ❌ Wrong — --reporter flag disables the config's JSON reporter
-npx playwright test specs/generated/<name>/<name>.spec.ts --reporter=list
-
-# ❌ Wrong — no env var → writes to default test-results/results.json
-# (overwritten on every screen run, loses per-screen tracking)
-npx playwright test specs/generated/<name>/<name>.spec.ts
-```
-
-If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter override.
-
-`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`.
-
-## Next steps
-
-After showing results, use `AskUserQuestion` to offer next steps:
-
-If all tests **passed**:
-- **`/sungen-create-test <name>`** — Add more test cases (Recommended)
-- **Done** — All tests passed, I'm finished
-
-If tests **failed** (after retries):
-- **`/sungen-run-test <name>`** — Re-run after manual fixes
-- **`/sungen-create-test <name>`** — Revise test cases
-- **Done for now** — I'll fix manually later

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-api-design.md

@@ -1,62 +0,0 @@
----
-name: sungen-api-design
-description: The API-first design loop for an api unit (qa/api/<area> or qa/api/flows/<flow>) — discover the catalog, lay out the API viewpoints, generate @api/@cases/flow/@concurrent scenarios, then drive the sungen audit --area gate + reviewer + repair to a high businessDepth (≥0.7). Use when create-test/run-test detects an api unit (no selectors, no visual capture).
----
-
-# API design loop (driver-api · Orchestration + Harness)
-
-Use this when the unit is **api-first** — `qa/api/<area>/` or `qa/api/flows/<flow>/`. There are **no selectors and no visual capture**: the contract is the **named-endpoint catalog** (`api/apis.yaml`), referenced by `@api:<name>`. QA writes **no HTTP code**. Full annotation reference: the **API Steps** guide (`@api` / `@cases` / flows / `@concurrent` / `@hybrid`).
-
-## The loop (mirror of /sungen:design, API-native)
-
-### 1. Discover (no capture)
-Run `sungen context --area <name>` — it reads the catalog and prints the **endpoints** + the **generation units** (one `matrix` unit per endpoint, an `async` unit per mutating endpoint, a `flow` unit for an api flow). Read `qa/api/<name>/requirements/spec.md` if present. No `apis.yaml` yet? → `sungen api import <openapi|csv>` or `sungen api add --area <name>` first.
-
-### 2. API viewpoint overview (by method-profile)
-For each endpoint, cover its viewpoints — severity-weighted by method:
-
-| Profile | Endpoints | Must cover | Then |
-|---|---|---|---|
-| read | GET, HEAD | `contract` (status + body shape) | `pagination`/`filter` (list), `not-found` (by-id) |
-| mutating | POST/PUT/PATCH/DELETE | `contract`, `error` (validation/4xx/auth) | `idempotency` (`@concurrent`), `side-effect` (`@query`) |
-
-Bands: **~70%** success+failure matrix · **~20%** flows (auth/CRUD chains) · **~10%** async/idempotency.
-
-### 3. Generate (incremental — never the whole suite in one Write)
-- **Contract**: `@api:<name>` + `expect {{name.status}} is …` **and a body assertion** (`{{name.body.<path>}}`).
-- **Error matrix**: `@api:<name>(p={{p}}) @cases:<dataset>` — one scenario, a dataset of `input → expected status`.
-- **Flow**: ordered `@api` tags threading a prior response (`token={{login.body.token}}` → the catalog `Bearer :token` header; `id={{create.body.id}}` → a path param). Self-clean (delete what you create).
-- **Idempotency**: `@api:<name> @concurrent:N` + `expect {{name.ok_count}} is 1`, cross-checked with `@query` (the DB is the oracle).
-
-### 4. Gate + repair (always — businessDepth ≥ 0.7 is the bar)
-Run `sungen audit --area <name>`; read `gateStatus` + `findings`. Then the **semantic reviewer** (sungen-reviewer sub-agent, API criteria). Repair **both** (budget 3 rounds), re-audit until PASS:
-
-| Finding | Repair |
-|---|---|
-| `VIEWPOINT-API-CONTRACT` | the endpoint is invoked but its response is never asserted → add `expect {{name.status}}` + a `{{name.body.…}}` check |
-| `VIEWPOINT-API-ERROR` | a mutating endpoint has no failure scenario → add a `@cases` error matrix (or an explicit 4xx) |
-| `VIEWPOINT-API-IDEMPOTENCY` | a mutating endpoint has no race check → add `@concurrent:N` + a `@query` DB cross-check |
-| `VIEWPOINT-API-MANUAL-AUTOMATABLE` | a `@manual` scenario whose endpoint resolves is automatable → drop `@manual`, use `@api` (+ `@cases`); reserve `@manual` for genuine judgment cases |
-| **`DEPTH-FAIL`** (businessDepth < 0.7) | a **mutating success** scenario asserts only `status` → make it **prove the effect**: assert a response **body** field, a **`@query`** side-effect, or a **`@concurrent` `ok_count`** invariant. (An error/`@cases` scenario proving the status is correct — it is *not* depth-required.) |
-
-Stop when the gate PASSes + businessDepth ≥ 0.7, or the budget is exhausted → report residual gaps honestly (mark genuinely-unautomatable cases `@manual` with an oracle). Never fake a pass.
-
-### 5. Record + converge
-`sungen manifest --area <name>` (reuse) and ledger each phase; show the trace + the HUMAN-LOOP FOCUS. (Integrity `script-check`/`trace` for api: see run-test.)
-
-## Taxonomy (label scenarios correctly)
-
-| Class | What | Examples |
-|---|---|---|
-| **Functional** | single-endpoint behaviour | happy contract · error/validation (`@cases`) · boundary/edge |
-| **Functional — flow/integration** | multi-endpoint journeys | auth/CRUD lifecycle (`create → login → get → delete`), cross-endpoint invariants |
-| **Non-Functional** | performance · reliability · **security** · concurrency/idempotency | `@concurrent` race/idempotency |
-
-A flow (`create → login → delete`) is a **Functional integration** test, **not** non-functional — don't file it under "Non-Functional". Reserve non-functional for perf/security/concurrency.
-
-## Rules
-- **No HTTP, no selectors** — only `.feature` + the reviewed `apis.yaml` + `test-data`.
-- **Non-prod default** — a `production` datasource is refused unless `SUNGEN_ALLOW_PROD=1`.
-- **The DB is the oracle** for idempotency/side-effects — HTTP status alone can lie; pair `@api` with `@query`.
-- **`@parallel` + mutating endpoints** — give each scenario **isolated data** (a `{{$uuid}}` email, a `@cases` row, or its own created resource) and **self-clean** (delete what it created); shared inputs race under parallel execution.
-- **No dead data** — every `test-data` key must be bound into a scenario (`{{key}}`, a `@cases` dataset, or an override). `sungen audit`/the generate lint flag unreferenced keys.