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

package/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/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/src/utils/safe-yaml-parse.ts

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+import { parseDocument } from 'yaml';
+
+export const SAFE_YAML_MAX_ALIAS_COUNT = 10;
+export const SAFE_YAML_MAX_BYTES = 1024 * 1024;
+
+export class UnsafeYamlError extends Error {
+  constructor(public readonly source: string, detail: string) {
+    super(`${source}: ${detail}`);
+    this.name = 'UnsafeYamlError';
+  }
+}
+
+export function safeYamlParse(text: string, source = '<yaml>'): unknown {
+  if (Buffer.byteLength(text, 'utf8') > SAFE_YAML_MAX_BYTES) {
+    throw new UnsafeYamlError(source, `larger than ${SAFE_YAML_MAX_BYTES} bytes`);
+  }
+  let doc: ReturnType<typeof parseDocument>;
+  try {
+    doc = 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: SAFE_YAML_MAX_ALIAS_COUNT });
+  } catch (err) {
+    throw new UnsafeYamlError(source, err instanceof Error ? err.message : String(err));
+  }
+}