@sun-asterisk/sungen 3.2.34 → 3.3.0-alpha.1

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

@@ -12,32 +12,45 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-tc-generation` | Test case generation strategy, output format |
 | `sungen-test-design-techniques` | EP, BVA, Decision Table, State Transition — systematic scenario generation |
 | `sungen-tc-review` | Review scoring, quality rules, checklist |
-| `sungen-viewpoint` | 17 UI patterns x 4 viewpoints — coverage checklists |
+| `sungen-viewpoint` | 32 UI patterns (17 web + 15 mobile-native) x 4 viewpoints — coverage checklists |
 | `sungen-selector-keys` | YAML key generation from `[Reference]` names, suffixes, lookup priority |
 | `sungen-selector-fix` | Selector generation from live page, auto-fix strategy |
-| `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
+| `sungen-delivery` | Export the Test Case & Coverage Matrix (or the legacy per-scenario CSV) from Gherkin + Playwright results |
 | `sungen-capture` | Acquire visual/design context — one skill, 4 modes: figma-mcp (Dev Mode MCP), figma-pat (URL → spec_figma.md), live (Playwright MCP scan), local (images in `requirements/ui/`) |
 | `sungen-locale` | Bootstrap i18n — audit selectors, detect locale switch mechanism, generate test-data overlay |
 | `sungen-data-factory` | Standardized test-data — field-type/security catalog, 4-source method, `.overwrite`, blind-spot prompts |
+| `sungen-harness-audit` | How to read `sungen audit` output and repair test-design findings (the create-test quality loop) |
+| `sungen-capture-mobile` | Capture a live mobile screen via Appium MCP — locator tree + screenshot (`@platform:mobile/android/ios`) |
+| `sungen-mobile-gestures` | Mobile gesture patterns (swipe, long-press, scroll-to, pinch, pull-to-refresh) — Gherkin + Appium MCP mapping |
+| `sungen-selector-fix-mobile` | Mobile selector fixing — Appium MCP exploration, accessibility-id-first strategy, run via wdio |
+| `sungen-api-design` | API-first design loop for an api unit — catalog, API viewpoints, `@api`/`@cases`/flow scenarios, audit gate + repair |
+| `sungen-api-coverage-model` | Per-endpoint API coverage model — tiered case set expanded from the catalog's `fields:` metadata |
+| `sungen-ingest-legacy` | Import a legacy manual test-case suite (Google Sheets or local file) via `sungen ingest` |
+| `sungen-dashboard` | Single-file HTML dashboard of test cases + results (`sungen dashboard`) |
 
-## Workflow (8 AI commands)
+## Workflow (12 AI commands)
 
 | Command | What it does |
 |---|---|
 | `/sungen:add-screen <name> <path>` | Scaffold `qa/screens/<name>/` directories |
 | `/sungen:add-flow <name> [--path <url>]` | Scaffold `qa/flows/<name>/` directories for E2E cross-screen testing |
-| `/sungen:create-test <name>` | Generate `.feature` + `test-data.yaml` (auto-detects screen or flow) |
+| `/sungen:add-api <name> [--base-url <url>] [--flow <name>] [--import <spec>]` | Scaffold an API area (`qa/api/<name>/`), or an ordered `@api` chain with `--flow` (`qa/api/flows/<name>/`); `--base-url` is needed only until the project has an API datasource; `--import` an OpenAPI/CSV spec to populate the endpoint catalog |
+| `/sungen:create-test <name>` | Generate `.feature` + `test-data.yaml`, then run the quality harness (auto-detects screen / flow / API) |
+| `/sungen:design <name>` | Alias of `create-test` |
 | `/sungen:create-data-test <name>` | Generate standardized test-data (valid/boundary/invalid + CHK trace) from the Data Factory catalog; no name = all units (asks to confirm) |
 | `/sungen:review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
-| `/sungen:run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
-| `/sungen:delivery [name...]` | Export the Test Case & Coverage Matrix (review/manual/customer deliverable; `--legacy` = classic CSV; all screens if no arg) |
+| `/sungen:run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen / flow / API) |
+| `/sungen:delivery [name...]` | Export the Test Case & Coverage Matrix (review/manual/customer deliverable; `--legacy` = classic CSV; all units if no arg) |
+| `/sungen:dashboard [name...]` | Build the single-file HTML dashboard (`qa/dashboard/index.html`) — results, trends, run compare, CSV/XLSX export |
 | `/sungen:locale <name> <locale>` | Bootstrap i18n for a screen — audit selectors, detect locale switch, generate overlay (run before `/sungen:run-test --env <locale>`) |
+| `/sungen:feedback [message]` | Record QA feedback locally (`.sungen/feedback/`) with context attached |
 
 **Screen path:** add-screen → create-test → review → run-test → delivery.
 **Flow path:** add-flow → create-test → review → run-test → delivery.
+**API path:** add-api (`--import <openapi|csv>` for accuracy) → create-test → run-test → delivery. API units carry no selectors and no visual capture; create-test runs the audit + reviewer loop itself.
 **i18n path:** (after run-test passes for base locale) → locale → run-test --env <locale> → delivery --env <locale>.
 
-`create-test`, `review`, and `run-test` auto-detect context: if `qa/flows/<name>/` exists → flow mode, else `qa/screens/<name>/` → screen mode.
+`create-test` and `run-test` auto-detect context: if `qa/api/<name>/` (or `qa/api/flows/<name>/`) exists → API mode, else if `qa/flows/<name>/` → flow mode, else `qa/screens/<name>/` → screen mode. `review` covers screen and flow units.
 
 After each command completes, use `AskUserQuestion` to present the next actions as selectable options. Never just print text — always give clickable choices so the user can continue the workflow seamlessly.
 

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

@@ -12,32 +12,45 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-tc-generation` | Test case generation strategy, output format |
 | `sungen-test-design-techniques` | EP, BVA, Decision Table, State Transition — systematic scenario generation |
 | `sungen-tc-review` | Review scoring, quality rules, checklist |
-| `sungen-viewpoint` | 17 UI patterns x 4 viewpoints — coverage checklists |
+| `sungen-viewpoint` | 32 UI patterns (17 web + 15 mobile-native) x 4 viewpoints — coverage checklists |
 | `sungen-selector-keys` | YAML key generation from `[Reference]` names, suffixes, lookup priority |
 | `sungen-selector-fix` | Selector generation from live page, auto-fix strategy |
-| `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
+| `sungen-delivery` | Export the Test Case & Coverage Matrix (or the legacy per-scenario CSV) from Gherkin + Playwright results |
 | `sungen-capture` | Acquire visual/design context — one skill, 4 modes: figma-mcp (Dev Mode MCP), figma-pat (URL → spec_figma.md), live (Playwright MCP scan), local (images in `requirements/ui/`) |
 | `sungen-locale` | Bootstrap i18n — audit selectors, detect locale switch mechanism, generate test-data overlay |
 | `sungen-data-factory` | Standardized test-data — field-type/security catalog, 4-source method, `.overwrite`, blind-spot prompts |
+| `sungen-harness-audit` | How to read `sungen audit` output and repair test-design findings (the create-test quality loop) |
+| `sungen-capture-mobile` | Capture a live mobile screen via Appium MCP — locator tree + screenshot (`@platform:mobile/android/ios`) |
+| `sungen-mobile-gestures` | Mobile gesture patterns (swipe, long-press, scroll-to, pinch, pull-to-refresh) — Gherkin + Appium MCP mapping |
+| `sungen-selector-fix-mobile` | Mobile selector fixing — Appium MCP exploration, accessibility-id-first strategy, run via wdio |
+| `sungen-api-design` | API-first design loop for an api unit — catalog, API viewpoints, `@api`/`@cases`/flow scenarios, audit gate + repair |
+| `sungen-api-coverage-model` | Per-endpoint API coverage model — tiered case set expanded from the catalog's `fields:` metadata |
+| `sungen-ingest-legacy` | Import a legacy manual test-case suite (Google Sheets or local file) via `sungen ingest` |
+| `sungen-dashboard` | Single-file HTML dashboard of test cases + results (`sungen dashboard`) |
 
-## Workflow (8 AI commands)
+## Workflow (12 AI commands)
 
 | Command | What it does |
 |---|---|
 | `/sungen-add-screen <name> <path>` | Scaffold `qa/screens/<name>/` directories |
 | `/sungen-add-flow <name> [--path <url>]` | Scaffold `qa/flows/<name>/` directories for E2E cross-screen testing |
-| `/sungen-create-test <name>` | Generate `.feature` + `test-data.yaml` (auto-detects screen or flow) |
+| `/sungen-add-api <name> [--base-url <url>] [--flow <name>] [--import <spec>]` | Scaffold an API area (`qa/api/<name>/`), or an ordered `@api` chain with `--flow` (`qa/api/flows/<name>/`); `--base-url` is needed only until the project has an API datasource; `--import` an OpenAPI/CSV spec to populate the endpoint catalog |
+| `/sungen-create-test <name>` | Generate `.feature` + `test-data.yaml`, then run the quality harness (auto-detects screen / flow / API) |
+| `/sungen-design <name>` | Alias of `create-test` |
 | `/sungen-create-data-test <name>` | Generate standardized test-data (valid/boundary/invalid + CHK trace) from the Data Factory catalog; no name = all units (asks to confirm) |
 | `/sungen-review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
-| `/sungen-run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
-| `/sungen-delivery [name...]` | Export the Test Case & Coverage Matrix (review/manual/customer deliverable; `--legacy` = classic CSV; all screens if no arg) |
+| `/sungen-run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen / flow / API) |
+| `/sungen-delivery [name...]` | Export the Test Case & Coverage Matrix (review/manual/customer deliverable; `--legacy` = classic CSV; all units if no arg) |
+| `/sungen-dashboard [name...]` | Build the single-file HTML dashboard (`qa/dashboard/index.html`) — results, trends, run compare, CSV/XLSX export |
 | `/sungen-locale <name> <locale>` | Bootstrap i18n for a screen — audit selectors, detect locale switch, generate overlay (run before `/sungen-run-test --env <locale>`) |
+| `/sungen-feedback [message]` | Record QA feedback locally (`.sungen/feedback/`) with context attached |
 
 **Screen path:** add-screen → create-test → review → run-test → delivery.
 **Flow path:** add-flow → create-test → review → run-test → delivery.
+**API path:** add-api (`--import <openapi|csv>` for accuracy) → create-test → run-test → delivery. API units carry no selectors and no visual capture; create-test runs the audit + reviewer loop itself.
 **i18n path:** (after run-test passes for base locale) → locale → run-test --env <locale> → delivery --env <locale>.
 
-`create-test`, `review`, and `run-test` auto-detect context: if `qa/flows/<name>/` exists → flow mode, else `qa/screens/<name>/` → screen mode.
+`create-test` and `run-test` auto-detect context: if `qa/api/<name>/` (or `qa/api/flows/<name>/`) exists → API mode, else if `qa/flows/<name>/` → flow mode, else `qa/screens/<name>/` → screen mode. `review` covers screen and flow units.
 
 After each command completes, present the next actions as selectable options. Never just print text — always give clickable choices so the user can continue the workflow seamlessly.
 

package/dist/orchestrator/templates/ai-src/partials/hand-back-rule.claude.md

@@ -0,0 +1,20 @@
+<!-- sungen:hand-back-rule v1 -->
+## ⛔ HARD RULE — the run's LAST action is the next-step hand-back
+
+A run is NOT finished when its files are written or its output prints. The final action of EVERY
+run — success, partial, failed, or aborted — is the next-step hand-back.
+
+**Ask `sungen next {{unitArg}}` rather than deciding from memory.** It derives the answer from what
+the project actually holds (artifacts on disk, the audit report, the accepted viewpoint baseline,
+the compiled spec, the run results and how many of them failed), so the hand-back stays correct
+even when the run ended somewhere unexpected — a failed install, a driver that turned out not to
+support this unit kind, an aborted repair loop. Every `sungen` command also prints
+`Next: sungen next …` as its own last line, on stderr when the command failed.
+
+**Hand back with `AskUserQuestion`** — one option per step `sungen next` lists. A `decide` step is
+a QA decision: offer it, never run it yourself. Ending with a prose summary and no choices is a
+broken run.
+
+If a step turns out to be impossible, that is still a hand-back: say what blocked it, run
+`sungen next {{unitArg}}`, and offer what remains.
+<!-- /sungen:hand-back-rule -->

package/dist/orchestrator/templates/ai-src/partials/hand-back-rule.codex.md

@@ -0,0 +1,20 @@
+<!-- sungen:hand-back-rule v1 -->
+## ⛔ HARD RULE — the run's LAST action is the next-step hand-back
+
+A run is NOT finished when its files are written or its output prints. The final action of EVERY
+run — success, partial, failed, or aborted — is the next-step hand-back.
+
+**Ask `sungen next {{unitArg}}` rather than deciding from memory.** It derives the answer from what
+the project actually holds (artifacts on disk, the audit report, the accepted viewpoint baseline,
+the compiled spec, the run results and how many of them failed), so the hand-back stays correct
+even when the run ended somewhere unexpected — a failed install, a driver that turned out not to
+support this unit kind, an aborted repair loop. Every `sungen` command also prints
+`Next: sungen next …` as its own last line, on stderr when the command failed.
+
+**Hand back as a numbered list and stop** — one item per step `sungen next` lists, then end your
+turn and wait for the user's pick. A `decide` step is a QA decision: list it, never run it
+yourself. Ending with a prose summary and no numbered choices is a broken run.
+
+If a step turns out to be impossible, that is still a hand-back: say what blocked it, run
+`sungen next {{unitArg}}`, and list what remains.
+<!-- /sungen:hand-back-rule -->

package/dist/orchestrator/templates/ai-src/partials/hand-back-rule.copilot.md

@@ -0,0 +1,20 @@
+<!-- sungen:hand-back-rule v1 -->
+## ⛔ HARD RULE — the run's LAST action is the next-step hand-back
+
+A run is NOT finished when its files are written or its output prints. The final action of EVERY
+run — success, partial, failed, or aborted — is the next-step hand-back.
+
+**Ask `sungen next {{unitArg}}` rather than deciding from memory.** It derives the answer from what
+the project actually holds (artifacts on disk, the audit report, the accepted viewpoint baseline,
+the compiled spec, the run results and how many of them failed), so the hand-back stays correct
+even when the run ended somewhere unexpected — a failed install, a driver that turned out not to
+support this unit kind, an aborted repair loop. Every `sungen` command also prints
+`Next: sungen next …` as its own last line, on stderr when the command failed.
+
+**Hand back as a numbered list and stop** — one item per step `sungen next` lists, then end your
+turn and wait for the user's pick. A `decide` step is a QA decision: list it, never run it
+yourself. Ending with a prose summary and no numbered choices is a broken run.
+
+If a step turns out to be impossible, that is still a hand-back: say what blocked it, run
+`sungen next {{unitArg}}`, and list what remains.
+<!-- /sungen:hand-back-rule -->

package/dist/orchestrator/templates/ai-src/skills/sungen-api-coverage-model/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sungen-api-coverage-model
-description: The per-endpoint API coverage model — the systematic case set to enumerate for each endpoint (read / mutating / flow), keyed to the catalog's fields: metadata, tiered so a first pass is complete (not "happy path + 1 error"). Load this in API unit mode alongside sungen-api-design; it turns endpoints × field constraints into a concrete case list, mechanically, instead of guessing.
+description: 'The per-endpoint API coverage model — the systematic case set to enumerate for each endpoint (read / mutating / flow), keyed to the catalog''s fields: metadata, tiered so a first pass is complete (not "happy path + 1 error"). Load this in API unit mode alongside sungen-api-design; it turns endpoints × field constraints into a concrete case list, mechanically, instead of guessing.'
 ---
 
 # API coverage model (what to test per endpoint)

package/dist/orchestrator/templates/ai-src/skills/sungen-capture-mobile/SKILL.md

@@ -6,7 +6,7 @@ user-invocable: false
 
 ## Purpose
 
-Launch a mobile app on a device/emulator, capture **one locator tree** (`generate_locators`) and **one screenshot**, and save them as visual context for test generation. The mobile analogue of `sungen-capture-live` — same job, Appium MCP instead of Playwright MCP.
+Launch a mobile app on a device/emulator, capture **one locator tree** (`generate_locators`) and **one screenshot**, and save them as visual context for test generation. The mobile analogue of `sungen-capture` mode `live` — same job, Appium MCP instead of Playwright MCP.
 
 Use when the target is a native/Flutter/React-Native app (`@platform:android` or `@platform:ios`) running on a connected device or emulator.
 
@@ -188,8 +188,8 @@ Flutter/RN expose the same Semantics on each, so one exploration covers most of
 
 ## Relationship to other capture skills
 
-- `sungen-capture-figma` / `sungen-capture-local` — design/image sources (platform-agnostic)
-- `sungen-capture-live` — web (Playwright MCP)
+- `sungen-capture` (modes `figma-mcp` / `figma-pat` / `local`) — design/image sources (platform-agnostic)
+- `sungen-capture` (mode `live`) — web (Playwright MCP)
 - `sungen-capture-mobile` — this skill, mobile (Appium MCP)
 
 All write to `requirements/ui/` and report back to the caller.

package/dist/orchestrator/templates/ai-src/skills/sungen-data-factory/SKILL.md

@@ -69,6 +69,15 @@ Rules:
   catalog defaults).
 - Map every `errorRef` placeholder (`M13`, `M39`, …) to the spec's real code via `errorMap`. Leave
   one unmapped **only** if the spec has none — the lint flags it as an open point to confirm.
+- Some catalog constraints are only placeholders (string `minLength: 1` / `maxLength: 255`, phone
+  `8..15`, …). A field that does not set its own value is warned **`PLACEHOLDER_CONSTRAINT`** — the
+  boundary cases are built from that number, so take it from the spec.
+- An **empty value** is judged by `required`, not by `minLength`: `required: false` → `""` is valid
+  (no "below minimum" case for it); `required: true` **or unset** → `""` is invalid. `minLength: 0`
+  has no min-1 case. So an optional field must say `required: false`.
+- To drop **one** generated case for **one** field, list its id under the field's **`disable:`**
+  (e.g. `disable: [CHK-STR-I2]` drops min-1 and keeps max+1 `CHK-STR-I2a`). It is reported as
+  not applicable. The overwrite's `disable:` drops a case for every field of the type.
 - **Complex forms:** a **group** field takes nested **`fields:`** (recursive; no `type` on the group → renders a nested object like `address.city`). A field whose rule depends on another takes **`dependsOn: { field, value }`** — recorded as a `_depends_on` note (the generator doesn't resolve the runtime condition; weave it into the scenario/`@cases`).
 - Set **`unique: true`** on a field that must be fresh every run (register email/username, anything
   that would clash with a record a previous run left behind). Its valid value then carries a runtime

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

@@ -73,6 +73,8 @@ reason comment); the Given/When/Then stay **exactly** as QA approved them:
 
 > **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.
 
+**`sungen triage` makes the first pass for you.** Its classes are this section's split: `test-defect` = selector-resolution / test-data failure (auto-fix scope), `product-candidate` = assertion-value failure with an Expected and a Received (apply the spec question above), `environment` = the run itself (fix the setup, not the test), `unclassified` = yours to judge — an assertion on an element that never appeared lands here, because a wrong selector and a missing message look the same.
+
 **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.

package/dist/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -631,7 +631,7 @@ on mobile a dialog-scoped ref still resolves against the whole screen (`SG-W021`
 | `@spec:<id>` | **Traceability**: this scenario proves requirement `<id>` from `requirements/spec.md` (`@spec:FR-003`). Repeatable — a scenario may prove several. Read by `sungen audit` (requirement coverage) and by delivery (the Coverage sheet's requirement table). Without it the link is only inferred from wording and cannot survive an edit. |
 | `@ui:<UI-NNN>` | **Design traceability**: this scenario proves design item `UI-NNN` from `requirements/ui-inventory.md` (`@ui:UI-014`). Repeatable. Read by `sungen audit` (`UI-ITEM-UNCOVERED`). An item deliberately not tested is recorded as a comment instead: `# UI-DEFERRED: UI-002..013 — <reason>`. Rules: `sungen-tc-generation` § Design Inventory. |
 | `@manual` | Skip in generation |
-| `@known-defect` | The scenario is EXPECTED to be red — it asserts a live defect. It still runs and still reports as failed (never skipped, never "fixed"), and it stays a pass-through tag so `--grep @known-defect` selects it. **`[mobile]`** Its failure does NOT escalate the next scenario's `@reset:` tier: a red that was designed in is not evidence of leftover state |
+| `@known-defect` | The scenario is EXPECTED to be red — it asserts a live defect. It still runs and still reports as failed (never skipped, never "fixed"), and it stays a pass-through tag so `--grep @known-defect` selects it. `@known-defect:DEF-NNN` names the record in `qa/defects/DEF-NNN-*.md` (`sungen defect draft` writes it); `sungen audit` reports `DEFECT-REF-MISSING` when that file does not exist. **`[mobile]`** Its failure does NOT escalate the next scenario's `@reset:` tier: a red that was designed in is not evidence of leftover state |
 | `@auth:role` | Use auth storage state for role |
 | `@no-auth` | Disable inherited auth |
 | `@steps:name` | Define reusable step block (base scenario) |

package/dist/orchestrator/templates/ai-src/skills/sungen-harness-audit/SKILL.md

@@ -35,6 +35,8 @@ user-invocable: false
 | **BALANCE** | secondary viewpoints (UI/validation/security) outweigh business-core | **Stop expanding** secondary viewpoints; generate the missing business-core scenarios first. Do not add more subscription/UI variants while core is thin. |
 | **TRACE** | scenarios use ad-hoc `VP-<CAT>-NNN` codes not linked to the viewpoint-overview | Make each scenario map to a viewpoint-overview id (align category codes, or add a mapping comment). |
 | **ORACLE-URL-ONLY** | every `Then` in the scenario is a page/URL assertion — it proves a path was pushed, not that the page rendered; on a permission/guard scenario a late 403 redirect turns it falsely green | Add `anchor:` to the page selector (one line per screen; every `see [X] page` on it becomes a content oracle) or a content assertion after the page step. Never delete the page step to silence it. |
+| **DEFECT-REF-MISSING** | a `@known-defect:DEF-NNN` tag names no file in `qa/defects/` | Draft the record (`sungen defect draft --screen <name> --scenario "<title>"`) or correct the id. Never drop the tag to silence it — the scenario still asserts a live defect. |
+| **DEFECT-ORPHAN** (info) | an open defect record names a scenario this unit no longer has | Update the record's `scenarios:` to the renamed title, or close the record if the scenario was removed on purpose. Nothing in the suite to repair. |
 | **UNIVERSAL** | a universal theme (error/empty-state, accessibility) is absent | Low priority — add if in scope; otherwise note as out-of-scope with reason. |
 
 ## P5 steps for deep cross-screen / list coverage

package/dist/orchestrator/templates/claude-hooks/sungen-hook.cjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * sungen — Claude Code hook launcher. Written by `sungen init` / `sungen update`; edits are
+ * overwritten. `.claude/settings.json` runs it in exec form (no shell):
+ *   { "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/sungen-hook.cjs", "<hook>"] }
+ *
+ * Finds the installed sungen and runs one hook IN-PROCESS (node on dist — no npx — so a hook costs
+ * one Node start). Lookup: $SUNGEN_HOOK_ENTRY when set (exactly that file), else the project's own
+ * dependency, else the global npm prefix.
+ *
+ * FAILS OPEN: kill-switch set, sungen not found, or any error → prints `{}` and exits 0. A hook can
+ * never block or derail a session.
+ *
+ * Off switches: SUNGEN_HOOKS=off (all) · SUNGEN_HOOK_<NAME>=off (one) · qa/sungen.config.yaml `hooks:`.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ENTRY = ['@sun-asterisk', 'sungen', 'dist', 'hooks', 'claude-hook-entry.js'];
+
+function noop() {
+  process.stdout.write('{}\n', () => process.exit(0));
+}
+
+function npmrcPrefix() {
+  try {
+    const m = fs.readFileSync(path.join(os.homedir(), '.npmrc'), 'utf8').match(/^\s*prefix\s*=\s*(.+?)\s*$/m);
+    return m ? m[1].replace(/^~(?=$|[\\/])/, os.homedir()) : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function findEntry() {
+  const override = process.env.SUNGEN_HOOK_ENTRY;
+  if (override) return fs.existsSync(override) ? override : null;
+  const project = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  try {
+    return require.resolve(ENTRY.join('/'), { paths: [project] });
+  } catch (_) { /* not a project dependency — try the global install */ }
+  const bin = path.dirname(process.execPath);
+  const prefixes = [process.env.npm_config_prefix, npmrcPrefix(), path.join(bin, '..'), bin].filter(Boolean);
+  for (const prefix of prefixes) {
+    for (const lib of [path.join(prefix, 'lib', 'node_modules'), path.join(prefix, 'node_modules')]) {
+      const candidate = path.join(lib, ...ENTRY);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+try {
+  if (/^(?:off|0|false|no|disabled?)$/i.test(String(process.env.SUNGEN_HOOKS || '').trim())) {
+    noop();
+  } else {
+    const entry = findEntry();
+    if (!entry) noop();
+    else Promise.resolve(require(entry).main(process.argv[2] || '')).then(() => process.exit(0), noop);
+  }
+} catch (_) {
+  noop();
+}

package/dist/utils/safe-yaml-parse.d.ts

@@ -0,0 +1,8 @@
+export declare const SAFE_YAML_MAX_ALIAS_COUNT = 10;
+export declare const SAFE_YAML_MAX_BYTES: number;
+export declare class UnsafeYamlError extends Error {
+    readonly source: string;
+    constructor(source: string, detail: string);
+}
+export declare function safeYamlParse(text: string, source?: string): unknown;
+//# sourceMappingURL=safe-yaml-parse.d.ts.map

package/dist/utils/safe-yaml-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-yaml-parse.d.ts","sourceRoot":"","sources":["../../src/utils/safe-yaml-parse.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAC5C,eAAO,MAAM,mBAAmB,QAAc,CAAC;AAE/C,qBAAa,eAAgB,SAAQ,KAAK;aACZ,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI3D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAW,GAAG,OAAO,CAiBtE"}

package/dist/utils/safe-yaml-parse.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsafeYamlError = exports.SAFE_YAML_MAX_BYTES = exports.SAFE_YAML_MAX_ALIAS_COUNT = void 0;
+exports.safeYamlParse = safeYamlParse;
+/**
+ * Parse YAML that a person or an agent wrote into `qa/` — decisions, test-basis, locks — without
+ * letting the file attack the reader (red-team #14, DOS-13.8).
+ *
+ * - `maxAliasCount` small: a "billion laughs" document that multiplies one anchor through nested
+ *   aliases is refused instead of expanding to gigabytes. None of these files has a reason to
+ *   alias at all; a handful is allowed so a hand-written file with one shared block still reads.
+ * - YAML **core** schema and nothing else: `!!binary`, `!!timestamp`, `!!js/…` or any custom tag is
+ *   an error (the library would otherwise resolve "known" extra tags even under core), and yaml-1.1
+ *   merge keys (`<<`) are not merged. `2026-10-21` stays the string it was written as, so a hash
+ *   over the parsed value equals a hash over the text's intent.
+ * - duplicate keys are an error: two `reason:` lines must not let the second silently win.
+ * - a byte cap: these files are a few hundred bytes; a 100 MB one is an attack or an accident.
+ */
+const yaml_1 = require("yaml");
+exports.SAFE_YAML_MAX_ALIAS_COUNT = 10;
+exports.SAFE_YAML_MAX_BYTES = 1024 * 1024;
+class UnsafeYamlError extends Error {
+    constructor(source, detail) {
+        super(`${source}: ${detail}`);
+        this.source = source;
+        this.name = 'UnsafeYamlError';
+    }
+}
+exports.UnsafeYamlError = UnsafeYamlError;
+function safeYamlParse(text, source = '<yaml>') {
+    if (Buffer.byteLength(text, 'utf8') > exports.SAFE_YAML_MAX_BYTES) {
+        throw new UnsafeYamlError(source, `larger than ${exports.SAFE_YAML_MAX_BYTES} bytes`);
+    }
+    let doc;
+    try {
+        doc = (0, yaml_1.parseDocument)(text, { schema: 'core', resolveKnownTags: false, merge: false, uniqueKeys: true, strict: true, prettyErrors: false });
+    }
+    catch (err) {
+        throw new UnsafeYamlError(source, err instanceof Error ? err.message : String(err));
+    }
+    const problem = doc.errors[0] ?? doc.warnings[0]; // an unresolved tag is only a warning to the library
+    if (problem)
+        throw new UnsafeYamlError(source, problem.message);
+    try {
+        return doc.toJS({ maxAliasCount: exports.SAFE_YAML_MAX_ALIAS_COUNT });
+    }
+    catch (err) {
+        throw new UnsafeYamlError(source, err instanceof Error ? err.message : String(err));
+    }
+}
+//# sourceMappingURL=safe-yaml-parse.js.map

package/dist/utils/safe-yaml-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-yaml-parse.js","sourceRoot":"","sources":["../../src/utils/safe-yaml-parse.ts"],"names":[],"mappings":";;;AA0BA,sCAiBC;AA3CD;;;;;;;;;;;;;GAaG;AACH,+BAAqC;AAExB,QAAA,yBAAyB,GAAG,EAAE,CAAC;AAC/B,QAAA,mBAAmB,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/C,MAAa,eAAgB,SAAQ,KAAK;IACxC,YAA4B,MAAc,EAAE,MAAc;QACxD,KAAK,CAAC,GAAG,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;QADJ,WAAM,GAAN,MAAM,CAAQ;QAExC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AALD,0CAKC;AAED,SAAgB,aAAa,CAAC,IAAY,EAAE,MAAM,GAAG,QAAQ;IAC3D,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,2BAAmB,EAAE,CAAC;QAC1D,MAAM,IAAI,eAAe,CAAC,MAAM,EAAE,eAAe,2BAAmB,QAAQ,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,GAAqC,CAAC;IAC1C,IAAI,CAAC;QACH,GAAG,GAAG,IAAA,oBAAa,EAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5I,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,eAAe,CAAC,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACtF,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAG,qDAAqD;IACzG,IAAI,OAAO;QAAE,MAAM,IAAI,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,IAAI,CAAC,EAAE,aAAa,EAAE,iCAAyB,EAAE,CAAC,CAAC;IAChE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,eAAe,CAAC,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACtF,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.34",
+  "version": "3.3.0-alpha.1",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -40,8 +40,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.34",
-    "@sungen/driver-ui": "3.2.34",
+    "@sungen/driver-data-factory": "3.3.0-alpha.1",
+    "@sungen/driver-ui": "3.3.0-alpha.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/basis/anchor-grammar.ts

@@ -0,0 +1,83 @@
+/**
+ * Anchor grammar and the shared trace vocabulary (DOS-12.1, DOS-12.2; takumi T7).
+ *
+ * | anchor                     | example                  | label       |
+ * |----------------------------|--------------------------|-------------|
+ * | `<docId>#<itemId>`         | `SPEC-AUTH-001#A-2`      | `EXTRACTED` |
+ * | `<docId>#<itemId>/val`     | `SPEC-AUTH-001#A-2/val`  | `EXTRACTED` |
+ * | `sec-<slug>`               | `sec-login-form`         | `INFERRED`  |
+ * | duplicate id / fuzzy match | —                        | `AMBIGUOUS` |
+ *
+ * docId is the spec frontmatter `id`; itemId is COMPOSED from BM-51 §4.1 (`2.0` under section row
+ * `A` → `A-2`). BM-51 has no `VAL-xx` codes: a Validation row is keyed by its item. `screen_id` is
+ * metadata and never part of an anchor. Every anchor is cited as `repo@SHA:path#Lx-Ly`.
+ */
+import { createHash } from 'crypto';
+
+export type AnchorKind = 'item' | 'validation' | 'section';
+export type AnchorConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
+
+/** Score band per label (takumi confidence taxonomy): inclusive lower, inclusive upper. */
+export const CONFIDENCE_BANDS: Record<AnchorConfidence, readonly [number, number]> = {
+  EXTRACTED: [0.9, 1],
+  INFERRED: [0.5, 0.89],
+  AMBIGUOUS: [0, 0.49],
+};
+
+const DOC_ID = '[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+';
+const ITEM_ID = '[A-Z]+-\\d+(?:\\.\\d+)?';
+const ITEM_ANCHOR_RE = new RegExp(`^(${DOC_ID})#(${ITEM_ID})(/val)?$`);
+const SECTION_ANCHOR_RE = /^sec-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const CITATION_RE = /^([^@\s]+)@([^:\s]+):([^#\s]+)#L(\d+)-L(\d+)$/;
+
+export interface ParsedAnchorId { kind: AnchorKind; docId?: string; itemId?: string; slug?: string }
+
+export function parseAnchorId(id: string): ParsedAnchorId | null {
+  const item = ITEM_ANCHOR_RE.exec(id);
+  if (item) return { kind: item[3] ? 'validation' : 'item', docId: item[1], itemId: item[2] };
+  if (SECTION_ANCHOR_RE.test(id)) return { kind: 'section', slug: id.slice(4) };
+  return null;
+}
+
+export function isItemAnchorId(id: string): boolean {
+  return ITEM_ANCHOR_RE.test(id);
+}
+
+export function isDocId(id: string): boolean {
+  return new RegExp(`^${DOC_ID}$`).test(id);
+}
+
+export function itemAnchorId(docId: string, itemId: string, validation = false): string {
+  return `${docId}#${itemId}${validation ? '/val' : ''}`;
+}
+
+/**
+ * BM-51 §4.1 numbers items `1.0, 2.0 …` under a bold section row; the composed id drops the `.0`
+ * (`2.0` under `A` → `A-2`) and keeps a real sub-number (`2.1` → `A-2.1`). No section → null.
+ */
+export function composeItemId(section: string | null, itemNumber: string): string | null {
+  if (!section || !/^[A-Z]+$/.test(section)) return null;
+  const n = itemNumber.trim().replace(/\.0+$/, '');
+  return /^\d+(?:\.\d+)?$/.test(n) ? `${section}-${n}` : null;
+}
+
+/** `sec-<slug>` from a heading: accents folded, ASCII kebab-case; a script with no ASCII gets a hash. */
+export function sectionAnchorId(heading: string): string {
+  const slug = heading.normalize('NFKD').replace(/\p{M}/gu, '').replace(/[đĐ]/g, 'd').toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return `sec-${slug || createHash('sha1').update(heading).digest('hex').slice(0, 8)}`;
+}
+
+export interface CitationBase { repo: string; sha: string; path: string }
+
+export function formatCitation(base: CitationBase, startLine: number, endLine: number): string {
+  return `${base.repo}@${base.sha}:${base.path.replace(/\\/g, '/')}#L${startLine}-L${endLine}`;
+}
+
+export function parseCitation(s: string): (CitationBase & { start: number; end: number }) | null {
+  const m = CITATION_RE.exec(s);
+  if (!m) return null;
+  const start = Number(m[4]);
+  const end = Number(m[5]);
+  return start >= 1 && end >= start ? { repo: m[1], sha: m[2], path: m[3], start, end } : null;
+}

package/src/basis/anchor-hash.ts

@@ -0,0 +1,27 @@
+/**
+ * Hash by anchor kind (DOS-12.3, red-team #1).
+ *
+ * | anchor kind                  | hash        | why                                                      |
+ * |------------------------------|-------------|----------------------------------------------------------|
+ * | section `sec-<slug>` (legacy) | `sha1-12`   | every manifest already on disk holds these; a new algorithm would read "changed" everywhere |
+ * | item `<docId>#<itemId>`       | `sha256-12` | new in schema 2, so nothing old depends on it            |
+ *
+ * `sectionHash` is the exact computation the manifest has always used: sha1 over the section
+ * body joined with LF and trimmed, first 12 hex. Do not "improve" it.
+ */
+import { createHash } from 'crypto';
+
+export type HashAlgo = 'sha1-12' | 'sha256-12';
+
+export function sectionHash(bodyLines: string[]): string {
+  return createHash('sha1').update(bodyLines.join('\n').trim()).digest('hex').slice(0, 12);
+}
+
+/** One table row as compared: cells trimmed, inner whitespace collapsed, joined by `|`. */
+export function normalizeRow(cells: string[]): string {
+  return cells.map((c) => c.normalize('NFC').replace(/\s+/g, ' ').trim()).join('|');
+}
+
+export function itemRowHash(cells: string[]): string {
+  return createHash('sha256').update(normalizeRow(cells)).digest('hex').slice(0, 12);
+}

package/src/basis/bm51-tables.ts

@@ -0,0 +1,65 @@
+/**
+ * Read the BM-51 screen-spec tables that carry item ids (company standard, DOS-12.0).
+ *
+ * `reports/mng/specs/_templates/BM-2-901-51-screen-specification-template.md`:
+ *   §4.1 Item          `| ID | Item Name | Item Type | Required | Note |`  — bold section row `A`, then `1.0`, `2.0` …
+ *   §4.2 Validation    `| ID | Type | Min | Max | Default | … |`          — rows keyed by the composed id `A-2`
+ *   §4.3 Data Mapping  `| ID | Data Source | API ID | … |`                — same key
+ *   §5   Event         `| ID | Given (Pre-condition) | … |`               — same key, or `-`
+ *
+ * Tables are recognised by their header (first column `ID` plus the second column's name), not by
+ * heading numbers, so a translated heading still reads. Rows keep their 1-based source line.
+ */
+import { composeItemId } from './anchor-grammar';
+
+export type Bm51TableKind = 'item' | 'validation' | 'mapping' | 'event';
+
+export interface Bm51Row { table: Bm51TableKind; cells: string[]; id: string; line: number }
+export interface Bm51ItemRow extends Bm51Row { section: string | null; itemId: string | null }
+export interface Bm51Tables { items: Bm51ItemRow[]; validations: Bm51Row[]; mappings: Bm51Row[]; events: Bm51Row[] }
+
+const SEPARATOR = /^\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/;
+const COMPOSED_ID = /^[A-Z]+-\d+(?:\.\d+)?$/;
+
+function splitRow(line: string): string[] {
+  const body = line.trim().replace(/^\|/, '').replace(/\|$/, '');
+  return body.split(/(?<!\\)\|/).map((c) => c.replace(/\\\|/g, '|').trim());
+}
+const bare = (cell: string): string => cell.replace(/\*\*|__|`/g, '').trim();
+
+function kindOf(header: string[]): Bm51TableKind | null {
+  if (bare(header[0] ?? '').toUpperCase() !== 'ID') return null;
+  const second = bare(header[1] ?? '').toLowerCase();
+  if (second === 'item name') return 'item';
+  if (second === 'type') return 'validation';
+  if (second === 'data source') return 'mapping';
+  if (second.startsWith('given')) return 'event';
+  return null;
+}
+
+/** `lines` are the spec's lines; `firstLine` is the 1-based number of `lines[0]`. */
+export function readBm51Tables(lines: string[], firstLine = 1): Bm51Tables {
+  const out: Bm51Tables = { items: [], validations: [], mappings: [], events: [] };
+  for (let i = 0; i < lines.length - 1; i++) {
+    if (!lines[i].trim().startsWith('|') || !SEPARATOR.test(lines[i + 1].trim())) continue;
+    const kind = kindOf(splitRow(lines[i]));
+    let j = i + 2;
+    let section: string | null = null;
+    for (; j < lines.length && lines[j].trim().startsWith('|'); j++) {
+      if (!kind) continue;
+      const cells = splitRow(lines[j]);
+      const id = bare(cells[0] ?? '');
+      const line = firstLine + j;
+      if (kind === 'item') {
+        if (/^[A-Z]+$/.test(id)) { section = id; continue; }
+        if (!/^\d+(?:\.\d+)?$/.test(id)) continue;
+        out.items.push({ table: kind, cells, id, line, section, itemId: composeItemId(section, id) });
+      } else if (COMPOSED_ID.test(id)) {
+        const row: Bm51Row = { table: kind, cells, id, line };
+        (kind === 'validation' ? out.validations : kind === 'mapping' ? out.mappings : out.events).push(row);
+      }
+    }
+    i = j - 1;
+  }
+  return out;
+}