@sun-asterisk/sungen 3.2.35 → 3.3.0-alpha.10

package/src/orchestrator/templates/ai-src/commands/add-api.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion"
 copilot-tools: "[vscode, execute, read, agent, edit, search, todo]"
 codex-trigger: "Run when the user asks to add or scaffold a NEW API area/resource or an API flow to test (REST/HTTP endpoints, not a UI screen). Step 1 of the API workflow. Do NOT use for UI screens, flows across screens, creating test cases, or running tests."
 ---
+<!-- include: hand-back-rule -->
+
 {{^cap parallel-subagents}}
 **Input**: an API area name (a resource/tag, e.g. `orders`, `users`) and the base URL:
 `/sungen-add-api orders --base-url https://api.example.com`.

package/src/orchestrator/templates/ai-src/commands/add-flow.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwr
 copilot-tools: "[vscode, execute, read, agent, edit, search, todo]"
 codex-trigger: "Run when the user asks to add a NEW cross-screen end-to-end flow. Step 1 (flow variant). Do NOT use for a single screen, creating test cases, or running tests."
 ---
+<!-- include: hand-back-rule -->
+
 {{^cap parallel-subagents}}
 **Input**: Flow name and optional starting URL (e.g., `/sungen-add-flow award-submission --path /login`).
 
@@ -119,7 +121,7 @@ if 1, 3 or 8 fails, propose SPLITTING into separate flows:
 4. Is that outcome **valuable to the actor**? (an order placed, a password reset — not "a page rendered")
 5. Is **every step necessary** for that outcome?
 6. Are all steps at the **same business abstraction**?
-7. Are optional/error branches **flows of this goal** (Alternate / Exception flows), not new goals?
+7. Are optional/error branches **phases of this goal** (ER/EH), not new goals?
 8. Does **no segment** form an independently valuable flow on its own?
 9. Can you write **a single clear final assertion**?
 10. Can you name it "**Verb + outcome**"? (`place-order`, `reset-password` — not `cart-and-filter`)
@@ -134,11 +136,8 @@ Record the screen list — you will need it for:
 ### 1b. Author the Flow Contract (`requirements/flow-contract.yaml`)
 
 Write the answers down as the flow's contract — `sungen audit` scores the flow **against it**
-(the `flowCoverage` axis, per declared flow; `FLOW-OUTCOME-UNPROVEN` when no automated scenario
-asserts data on the outcome screen; `FLOW-SCOPE-CREEP` when scenarios never touch it). The audit
-also requires **both guarantees** and the **`flows:` inventory** on every contract —
-`FLOW-GUARANTEE-MISSING` / `FLOW-INVENTORY-MISSING` otherwise, and the top mark is withheld — so
-write them now rather than meet them after the spec and viewpoint are reviewed:
+(the `flowCoverage` axis: HP/ER/EH journey phases; `FLOW-OUTCOME-UNPROVEN` when no automated
+scenario asserts data on the outcome screen; `FLOW-SCOPE-CREEP` when scenarios never touch it):
 
 ```yaml
 goal: "Place an order for a product added from home"   # Verb + outcome
@@ -149,22 +148,7 @@ outcome:
   screen: checkout            # the [Screen:...] namespace carrying the final proof
   assertion: "The confirmation shows the order number and the paid total"
 value: "The customer has paid; the shop has a new order"
-successGuarantee: "An order exists with the cart's lines and total; the cart is empty"
-minimalGuarantee: "No order and no charge without a confirmation; the cart is unchanged"   # what Exception flows assert
-phases: [BF, AF, EF]          # Basic / Alternate / Exception flows (default) — the first one must reach `outcome`
-flows:                        # the inventory: every flow of the use case, each with a status
-  - id: BF
-    outcome: "The successGuarantee — order confirmed with its number and total"
-    status: covered
-  - id: AF01
-    branchFrom: "BF step 3, the user edits the quantity in the cart"
-    outcome: "Re-enters BF at step 3 with the new total"
-    status: covered
-  - id: EF01
-    branchFrom: "BF step 4, the payment is declined"
-    outcome: "The minimalGuarantee — no order, cart kept, an error shown"
-    status: pending-clarification   # covered | deferred | pending-clarification | out-of-scope
-    reason: "The decline message is not in the spec — asked the BA"
+phases: [HP, ER, EH]          # journey phases (default); add UI only if the flow owns UI states
 stateful: cart                # the mutated collection, if any — enables regression-depth dims
 golden: true                  # optional — release-critical: Final Inspection expects @golden scenarios here
 external:                     # optional — legs owned by another team/vendor (System INTEGRATION Testing)
@@ -173,10 +157,6 @@ external:                     # optional — legs owned by another team/vendor (
     screens: [payment]        # the flow namespaces that leg passes through
 ```
 
-`phases: [HP, ER, EH]` (happy path / error recovery / guards) is the lighter vocabulary for a short
-single-outcome flow — it still needs both guarantees and a `flows:` inventory. Enumerating the
-flows (the step × risk matrix) is described in the `sungen-tc-generation` skill, flow section.
-
 **A filled contract is an INPUT to generation — never an output.** Like `test-viewpoint.md`,
 generation must not rewrite it to match what was generated; disagree → propose the diff and ask.
 

package/src/orchestrator/templates/ai-src/commands/add-screen.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwr
 copilot-tools: "[vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']"
 codex-trigger: "Run when the user asks to add or scaffold a NEW screen/page to test. Step 1 of the sungen workflow. Do NOT use for flows, creating test cases, or running tests."
 ---
+<!-- include: hand-back-rule -->
+
 {{^cap parallel-subagents}}
 **Input**: Screen name and URL path (e.g., `/sungen-add-screen login /login`).
 Optionally include a Figma URL: `/sungen-add-screen login /login --figma https://www.figma.com/design/...`.

package/src/orchestrator/templates/ai-src/commands/create-data-test.md

@@ -7,6 +7,7 @@ claude-tools: "Read, Grep, Bash, Glob, Write, Edit, AskUserQuestion, Skill"
 copilot-tools: "[vscode, execute, read, agent, edit, search, todo]"
 codex-trigger: "Run when the user asks to CREATE, generate, or standardize TEST DATA / test values for a screen or flow (valid/boundary/invalid, boundary values, negative data). Uses the Data Factory driver. Not for generating the .feature scenarios themselves (that is create-test)."
 ---
+<!-- include: hand-back-rule -->
 
 **Input**: A screen or flow name (e.g., `/sungen:create-data-test login`), OR **no name** to do every unit (with a confirmation — see ALL mode). Load the `sungen-data-factory` skill for the full method.
 

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -7,22 +7,7 @@ claude-tools: "Read, Grep, Bash, Glob, Write, AskUserQuestion, Skill, mcp__playw
 copilot-tools: "[vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']"
 codex-trigger: "Run when the user asks to CREATE, generate, write, or author test cases / a .feature file for a screen or flow. Step 2 (after add-screen/add-flow, before run-test). Do NOT use for executing, running, or compiling existing tests."
 ---
-## ⛔ 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, or aborted — is the next-step hand-back.
-
-**Ask `sungen next <unit>` 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), 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.
-
-This matters most exactly where it used to break. A run that ended on a command with no footer of
-its own — `sungen capability add`, a dead-end install — left the session with nothing to follow and
-it stopped mid-workflow. If a step turns out to be impossible, that is still a hand-back: say what
-blocked it, run `sungen next <unit>`, and offer what remains. Ending with a prose summary and no
-choices is a broken run.
+<!-- include: hand-back-rule -->
 
 ---
 {{#cap parallel-subagents}}
@@ -115,6 +100,22 @@ declaration instead of leaving both on record.
 
 ---
 
+## ⛔ HARD RULE — approvals and waivers are a human's, on a terminal
+
+`sungen contract approve`, `sungen journey --waive`, `sungen journey --decide` and `sungen journey --signoff` record a QA
+decision (the sign-off is the single human gate before delivery) and ask for a typed confirmation on a real terminal (TTY). Never run them, never fake the
+terminal (`script`, `expect`, a pty wrapper), and never edit `contracts.lock.yaml` or
+`qa/**/decisions/` by hand. When one is due, show the exact command and stop for the human.
+
+**Hand-written free tests (`@free` / `@impl:code`).** When the unit has free tests with recorded
+traces, write their Gherkin with `sungen contract derive --screen <name>` — deterministic, it writes
+`features/<name>.free.feature` with every scenario tagged `@free @proposed`. Do not author those
+steps yourself; you may name the scenarios and suggest VP-ids. A `@proposed` scenario is not
+counted by the audit until a QA approves it (`sungen contract approve --screen <name>`). When
+two recorded tests claim one ID, `sungen contract derive` exits `1`, names both tests and writes
+nothing: stop and ask the QA to give each test its own ID (its title's leading ID, or its `@tag`).
+Never rename a test's ID — or a scenario's — yourself to get past it.
+
 ## Platform detection (do this FIRST)
 
 Read `qa/capabilities.yaml` and check the `platform` field — **and the verification scope** (`verification:` if set, else derived from `enabled`: `ui` always; `api`/`db` only if that driver is on). This is the project's recorded **test type**: an **E2E/UI-only** project (no `api`/`db`) must NOT get `@api`/`@query`/`@requires:api|db` verification unless the test-viewpoint explicitly asks for it — keep oracles UI-observable, and cap any in-scope API/DB-in-E2E verification at the **≤20% band** (see `sungen-tc-generation` → "Respect the project's verification scope"). `sungen audit` flags `VERIFICATION-OUT-OF-SCOPE`.

package/src/orchestrator/templates/ai-src/commands/dashboard.md

@@ -7,6 +7,8 @@ claude-tools: "Bash, Read, AskUserQuestion"
 copilot-tools: "[read, execute, edit, vscode/askQuestions]"
 codex-trigger: "Run when the user asks to OPEN or view the sungen results dashboard."
 ---
+<!-- include: hand-back-rule -->
+
 ## 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).

package/src/orchestrator/templates/ai-src/commands/delivery.md

@@ -7,6 +7,8 @@ claude-tools: "Bash, Read, Write, AskUserQuestion"
 copilot-tools: "[read, execute, edit, vscode/askQuestions]"
 codex-trigger: "Run when the user asks to EXPORT or deliver test cases for QA hand-off. Final step. Do NOT use for creating or running tests."
 ---
+<!-- include: hand-back-rule -->
+
 ## Role
 
 You are a **QA Test Delivery Engineer**. The deterministic `sungen delivery` CLI does all parsing,
@@ -235,3 +237,5 @@ sungen delivery [names...]        # matrix (default; needs the map) → XLSX onl
 Outputs: `qa/deliverables/<unit>-testcases.xlsx` (Overview + Auto + Manual + Coverage sheets) by default;
 `--format csv` writes `<unit>-testcases.csv` instead (flat, `Level` column `item|variant`),
 `--format both` writes both. Legacy mode writes the classic files instead.
+
+<!-- include: waiting-for-you -->

package/src/orchestrator/templates/ai-src/commands/design.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Bash, Glob, Write, AskUserQuestion, Skill, mcp__playw
 copilot-tools: "[vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']"
 codex-trigger: "Run when the user asks to capture DESIGN/visual context (Figma, live page scan, mockups) for a screen. Used before create-test. Do NOT use for writing or running tests."
 ---
+<!-- include: hand-back-rule -->
+
 {{#cap parallel-subagents}}
 ## `/sungen:design` is an alias of `/sungen:create-test`
 {{/cap}}

package/src/orchestrator/templates/ai-src/commands/feedback.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Bash, Glob"
 copilot-tools: "[vscode, execute, read, search]"
 codex-trigger: "Run when the user wants to send FEEDBACK about sungen itself."
 ---
+<!-- include: hand-back-rule -->
+
 ## Role
 {{#cap parallel-subagents}}
 

package/src/orchestrator/templates/ai-src/commands/locale.md

@@ -6,6 +6,8 @@ claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwr
 copilot-tools: "[read, execute, edit, vscode/askQuestions, playwright/*]"
 codex-trigger: "Run when the user asks to bootstrap i18n/localization for a screen. Runs before run-test --env <locale>."
 ---
+<!-- include: hand-back-rule -->
+
 ## 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.

package/src/orchestrator/templates/ai-src/commands/review.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Glob, Bash, Edit, Write, AskUserQuestion"
 copilot-tools: "[vscode, execute, read, edit, search, todo]"
 codex-trigger: "Run when the user asks to REVIEW or score the quality of already-generated test cases. Step 3 (between create-test and run-test). Do NOT use for creating or running tests."
 ---
+<!-- include: hand-back-rule -->
+
 {{^cap parallel-subagents}}
 **Input**: Screen or flow name (e.g., `/sungen-review admin-users`).
 
@@ -95,3 +97,5 @@ You are an **independent QA Reviewer** — you did not author these tests. You d
 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.
 {{/cap}}
+
+<!-- include: waiting-for-you -->

package/src/orchestrator/templates/ai-src/commands/run-test.md

@@ -7,6 +7,8 @@ claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwr
 copilot-tools: "[read, execute, edit, vscode/askQuestions, playwright/*, appium/*]"
 codex-trigger: "Run when the user asks to RUN, execute, or compile tests, generate selectors.yaml, or run tests. Step 4. Do NOT use for authoring/creating new test cases."
 ---
+<!-- include: hand-back-rule -->
+
 ## ⛔ HARD RULE — the transition INTO this run is a tool call, never prose
 
 A QA field report: the user picked "Run test" from create-test's hand-back, and the session
@@ -25,14 +27,6 @@ inside the run, not reasons to stop and hand the work back.
   `export PATH="$HOME/.nvm/versions/node/$(ls $HOME/.nvm/versions/node | grep '^v22' | tail -1)/bin:$PATH"`
   — and say so in one line. Only if NO compatible Node exists do you stop, with the exact
   install command as the hand-back.
-- Ending this run follows the same law as create-test: the LAST action is the next-step
-  hand-back (the AskUserQuestion in "After showing results"), no matter how the run went.
-  **Ask `sungen next <unit>` rather than deciding from memory** — it derives the answer from what
-  the project now holds, so the hand-back stays correct even when the run ended somewhere
-  unexpected (a failed install, a driver that does not support this unit kind, an aborted repair
-  loop). Every `sungen` command also prints `Next: sungen next …` as its own last line. A step
-  that turns out to be impossible is still a hand-back: say what blocked it, run
-  `sungen next <unit>`, and offer what remains.
 
 ---
 
@@ -273,6 +267,10 @@ question already.
 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. No more fix loops. Then run `sungen triage --screen <name>` and render its table as the results summary: every red or flaky scenario already sits in one class (`product-candidate`, `unclassified`, `test-defect`, `environment`, `blocked-capability`, `known-defect`, `flaky`) with the rule and one evidence line. You may move an `unclassified` row into a class only with a written evidence line of your own. You may never turn a `product-candidate` into a `test-defect` by editing the `.feature` or the expected value — the Gherkin is frozen; report it as a candidate bug. For each `product-candidate` you judge to be a product bug, run `sungen defect draft --screen <name> --scenario "<title>"`, fill the record's Summary, check its Expected against `spec.md`, then add `@known-defect:DEF-NNN` to that scenario's tag line (the tag-only exception above). The severity in the draft is `proposed` — confirm it with QA (`AskUserQuestion`) before the hand-back and set `severity_source: qa`. A row you judge is not a product bug stays in the summary with your reason, and gets no record. A `bare-timeout` row (`unclassified`) is never re-run inside this command — Phase 4 was the final run; offer the re-run in Next steps.
+8a. **Test Contract — every unit with a lock.** When `qa/<screens|flows|api>/<name>/contracts.lock.yaml` exists, check the suite still does what QA approved:
+   - **`@free` / `@impl:code` scenarios** (hand-written specs, not compiled): after the Phase 4 final run, run their specs with the project's free-test config and `--trace on` (`npx playwright test -c <free-test config> --trace on`) — their trace is the only proof. That config writes to its own `outputDir: 'test-results-free'` with `trace: 'on'` and the sungen run-record reporter; never run them into `test-results/`, which the next compiled run clears (the trace is then gone and the scenario is `unproven`). If the project has no such config, no trace is admissible: tell the QA, do not write or edit the config yourself. Then `sungen contract check --screen <name> --trace`.
+   - **No free tests**: `sungen contract check --screen <name>`.
+   - **Exit 2 (hard)** — `oracle-weakened`, `target-changed`, `assertion-lost`, `lock-uncommitted`, `unproven` → report each finding to the QA in the results summary, with its rule. **Never** edit the `.feature`, an expected value, the lock or a decision to turn it green, and **never** run `sungen contract approve` — approving is a QA's decision, on a terminal. **Exit 0 with `review`** → list it for the QA: review blocks `sungen delivery` until QA re-approves. **Exit 1** → report the error. No lock → skip: every scenario is `proposed`, which never blocks.
 9. **Phase 8 — Serial-cascade risk check** (#414): If any scenario has many steps, a skipped test may cause downstream steps to be incorrectly skipped due to the serial-cascade sensor detecting false "not reached" conditions. When you see "test skipped" messages during Phase 3–4 runs, check if the skipped scenario is a **blockers-exist** dependency in the test ledger (`sungen ledger query --screen <name>`). If the scenario had high step count and cascade fired, offer: *"Scenarios with deep steps can trigger serial-cascade skipping. Consider parallelizing this spec with `@concurrent` tags or breaking into smaller scenarios."* Let the user decide whether to refactor (do not auto-apply parallelization).
 {{#cap parallel-subagents}}
 9. **Integrity check & trace (always run after the final run).**

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/partials/waiting-for-you.claude.md

@@ -0,0 +1,11 @@
+<!-- sungen:waiting-for-you v1 -->
+## Waiting for you — the commands only the QA runs
+
+Right before the hand-back question, run `sungen next {{unitArg}}` and quote its **⏳ Waiting for you**
+block **verbatim** — every command exactly as printed, each with its reason. Those commands approve,
+sign off, waive, classify a red, accept in-run decisions or re-run once the environment is up: they are
+the QA's alone, and most refuse without a person typing a confirmation. Tell the QA to run each one in
+their own terminal — in Claude Code, type `! <command>` in the prompt (a `/sungen:…` command is typed
+as is). **Never run them yourself**, and never pipe or type a confirmation into them. When `sungen next`
+prints no such block, say that nothing is waiting for the QA.
+<!-- /sungen:waiting-for-you -->

package/src/orchestrator/templates/ai-src/partials/waiting-for-you.codex.md

@@ -0,0 +1,11 @@
+<!-- sungen:waiting-for-you v1 -->
+## Waiting for you — the commands only the QA runs
+
+Right before the hand-back list, run `sungen next {{unitArg}}` and quote its **⏳ Waiting for you**
+block **verbatim** — every command exactly as printed, each with its reason. Those commands approve,
+sign off, waive, classify a red, accept in-run decisions or re-run once the environment is up: they are
+the QA's alone, and most refuse without a person typing a confirmation. Tell the QA to run each one
+themselves, in their own terminal (a slash command is typed as is). **Never run them yourself**, and
+never pipe or type a confirmation into them. When `sungen next` prints no such block, say that nothing
+is waiting for the QA.
+<!-- /sungen:waiting-for-you -->

package/src/orchestrator/templates/ai-src/partials/waiting-for-you.copilot.md

@@ -0,0 +1,11 @@
+<!-- sungen:waiting-for-you v1 -->
+## Waiting for you — the commands only the QA runs
+
+Right before the hand-back list, run `sungen next {{unitArg}}` and quote its **⏳ Waiting for you**
+block **verbatim** — every command exactly as printed, each with its reason. Those commands approve,
+sign off, waive, classify a red, accept in-run decisions or re-run once the environment is up: they are
+the QA's alone, and most refuse without a person typing a confirmation. Tell the QA to run each one
+themselves, in their own terminal (a slash command is typed as is). **Never run them yourself**, and
+never pipe or type a confirmation into them. When `sungen next` prints no such block, say that nothing
+is waiting for the QA.
+<!-- /sungen:waiting-for-you -->

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

@@ -126,8 +126,7 @@ exist in test-data, so Gate D does not ask for them: the capture step renders as
 are resolved by TestDataLoader at execution time — including when nested inside a test-data value
 (`seed: "Summary intro {{$timestamp}}"`). They have no static value to print, so the report names
 them instead: `<unique timestamp>`, `<unique id>`, `<random 1-100>`, `<today's date>`,
-`<current date-time>`, and `{{$date:+1d}}` reads `<today's date + 1 day>`. An unknown `{{$foo}}` (or an
-argument the runtime does not support, e.g. `{{$date:tz=…}}`) is left raw on purpose — it is a typo and Gate D says so.
+`<current date-time>`. An unknown `{{$foo}}` is left raw on purpose — it is a typo and Gate D says so.
 
 **Data fidelity**: invisible test data is made visible, never normalized — `''` → `(empty)`,
 whitespace-only → `(5 spaces)`, padded → `" value "` quoted verbatim. A trim/collapse here would

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

@@ -124,9 +124,9 @@ reason comment); the Given/When/Then stay **exactly** as QA approved them:
 | `SG-W012` | A mock-install step written AFTER a navigation step in the same block — `page.route()` registered after `goto()` misses every request fired during page load | Move the mock-install step before the navigation, or into `Background` |
 | `SG-W013` | A page step (`see [X] page` / `is on [X] page` / `wait for [X] page`) whose `[Ref]` has no `type: page` selector entry (or collides with a non-page entry) — the step falls back to the feature's own path (or `/<ref>/`) instead of `X`'s real URL, so the anchored match can never reach it: the assertion always fails, the wait can only time out | Declare a `type: page` entry for `[Ref]` with its real URL; if the key collides with another type, disambiguate with a `--type` suffix (`sungen-selector-keys` § Collision rule) |
 | `SG-W014` | `[X] page with {{v}}` where `{{v}}`'s base test-data value carries no query and no fragment — the step checks the PATH only, asserting less than it reads as | Informational — pass a value like `?q=…` if you meant to assert a query, or drop `with {{v}}` for a bare page |
-| `SG-W015` | `see [X] card/item with {{n}}` where `{{n}}`'s test-data value is a **bare number** — this compiles to a TEXT assertion (`toHaveText('3')`), NOT a count. An author reaching for "3 cards are shown" gets an assertion that can only pass if the card's TEXT is literally the digit: a wrong test with no error. Scoped to container-ish element types (`card`/`item`/`option` + plurals); a text element asserting a numeric readout (`[Row Quantity] text with 4`) stays silent. In a `@cases` scenario the value is judged on every dataset row; it also fires on `see [X] row with {{n}}` whose rows MIX numbers and text (a row count needs every row numeric, so the step stays a text assertion) | For mixed `@cases` rows: put the counting rows in their own `@cases` scenario. For a COUNT use a form that has count semantics: `see [Ref] row with {{n}}` / `see [T] table with {{n}}`, or a list `should have count`. If the number really is the element's text, assert it on a **text/label** element instead |
+| `SG-W015` | `see [X] card/item with {{n}}` where `{{n}}`'s test-data value is a **bare number** — this compiles to a TEXT assertion (`toHaveText('3')`), NOT a count. An author reaching for "3 cards are shown" gets an assertion that can only pass if the card's TEXT is literally the digit: a wrong test with no error. Scoped to container-ish element types (`card`/`item`/`option` + plurals); a text element asserting a numeric readout (`[Row Quantity] text with 4`) stays silent | For a COUNT use a form that has count semantics: `see [Ref] row with {{n}}` / `see [T] table with {{n}}`, or a list `should have count`. If the number really is the element's text, assert it on a **text/label** element instead |
 | `SG-W016` | A table step on a table located by CSS/testid whose value does not mention `table` and that declares no `rows:` — the table templates find rows by `getByRole('row')`; on a list built from `<div>`s that is 0 rows, so `is hidden`/`is empty` PASS without checking anything and counts/clicks time out (issue #688). A heuristic — the compiler cannot see the DOM — so it warns once per table | Declare the row shape on the TABLE entry (`rows: 'div.job-row'`, relative to the table) — it drives all seven table steps — or locate the table by `role: table` if it really is one. Do not put the shape on a row label's entry: that key positions ONE row |
-| `SG-W017` | A step needs a **selector-entry field the entry does not declare**, so there is nothing honest to compile — today: a table paginate step whose table entry declares no `pagination.next`/`.prev` (#712); a web `fill [X] date-picker` whose entry locates a `<button>` (a calendar trigger) and names no fill recipe (#907). The mirror of `SG-W004`: that one reports a field written that nothing reads, this one a field a consumer needs that nobody wrote. The step compiles to a loud runtime `throw` rather than guessing a locator, which is the #690 failure mode (a locator no page has, failing far from its cause) | Add the missing field to the entry in selectors.yaml — for pagination: `pagination:` with `next:`/`prev:` locators; for a button date-picker: `variant: <recipe>` naming a `qa/app.yaml` recipe with a `fill` intent (and `assertValue` to read it back). This is a selectors.yaml-only fix, allowed inside the run-test auto-fix loop |
+| `SG-W017` | A step needs a **selector-entry field the entry does not declare**, so there is nothing honest to compile — today, a table paginate step whose table entry declares no `pagination.next`/`.prev` (#712). The mirror of `SG-W004`: that one reports a field written that nothing reads, this one a field a consumer needs that nobody wrote. The step compiles to a loud runtime `throw` rather than guessing a locator, which is the #690 failure mode (a locator no page has, failing far from its cause) | Add the missing field to the entry in selectors.yaml — for pagination: `pagination:` with `next:`/`prev:` locators. This is a selectors.yaml-only fix, allowed inside the run-test auto-fix loop |
 | `SG-W018` | A selectors.yaml entry declares an **`nth:` outside the contract** — `nth: -2`, `nth: 'last'`, `nth: 1.5`. `nth:` was the one entry field whose VALUE nothing checked (issue #720), so the web adapter silently DROPPED the filter (identical to deleting the line — the step then hits `strict mode violation: resolved to N elements`, which names the DOM and never the YAML line) while the mobile adapter emitted `$$('~x')[-1]` / `[last]` — `undefined` indexing and a bare identifier. The value is now ignored and reported once per entry | Write an integer `>= 0` for a zero-based index, or `-1` for the last match (`.last()` on web, `.at(-1)` on mobile). There is no keyword form: `'last'` is a string, not an index. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
 | `SG-E020` | A step matched a pattern, but the **active adapter ships no template** for it (e.g. a web-only step compiled under `platform: mobile`). The feature file still generates — that one step compiles to `throw new Error("[sungen] …")` naming the step, feature, pattern, template and adapter, so the failure is loud and traceable rather than a crashed build | Rephrase to a step the target adapter actually ships (see `sungen-gherkin-syntax` Platform Support section / `sungen-mobile-gestures`), or tag the scenario `@manual` with the platform reason |
 | `SG-E021` | The step carries a trailing **state clause** (`… is hidden`) that the pattern which matched it does not assert — the clause would be SILENTLY DROPPED. Worst shape in this table: it does not weaken an assertion, it can INVERT one. `see [X] page is hidden` matched `page-assertion` (priority 13) ahead of `is-hidden` (11), so the step compiled to `toHaveURL(...)` — asserting the page IS displayed, and passing. Also fires on `wait for [X] is checked` (a wait honours only `hidden`/`visible`/`disabled`/`enabled`; everything else silently fell back to `visible`) and on `row`/`column in [T] table … is <state>` for any state but `hidden` | Move the state onto the element that has it: `Then User see [X] checkbox is checked`. For a page, assert the page you expect (`Then User see [Other] page`) or a marker element (`Then User see [Banner] is hidden`). If sungen cannot express the check, tag the scenario `@manual`. The diagnostic names the pattern that swallowed the clause — that name tells you which form you actually hit |
@@ -139,7 +139,7 @@ reason comment); the Given/When/Then stay **exactly** as QA approved them:
 | `SG-W028` | A trailing **scope clause was DROPPED**, so the step runs against more of the page than its sentence names. Two causes, one code: (1) the word after `in [X]` is not a container type — `in [Job Card] widget`, or a leaf element used as a parent — so the clause matched nothing and the first-`[ref]`/first-`{{data}}` extractors took only the head of the sentence; (2) the by-content form `in [X] <type> with {{v}}` on the **mobile** adapter, where a parent is chained with `$()` and has no content filter. Before this code, both compiled clean and silently widened the assertion to the WHOLE screen — in a list of look-alike cards the test then passes for the wrong reason, findable only by diffing the generated `.spec.ts` against the Gherkin (#667) | For (1) use a real container type: `table` `list` `list-item` `section` `dialog` `modal` `drawer` `overlay` `form` `card` `item` `row` `group` `panel` `region` `container` `tab` `menu`. For (2) give the container an accessibility-id that identifies it and scope by that, or assert on the element the value belongs to |
 | `SG-W029` | A **mobile feature with no usable app-package `Path:`** — the line is missing, or it holds a web-style route (`Path: /applied-jobs`). The compiler then cannot name the app to reset between scenarios, and before this code that was SILENT: the per-scenario `beforeEach` was not emitted at all, so Background fell to Mocha's `before()` — once per FILE. Every scenario shared one continuous app session, so a tab switch or a scroll in one stranded elements off-screen for every later one, and the `@reset:` tier ladder was dropped with it, leaving the tag inert (#669). The spec now always emits the reset machinery and resolves the app id from the session capability instead, throwing a named error at run time if nothing supplies one | Add the package to the feature: `Path: com.example.app/.MainActivity`, or `Path: <androidPkg>/<activity> | <iosBundleId>` for a dual-id feature. A `Path:` starting with `/` is a web route and will not be read as a package. Failing that, set `APP_PACKAGE` (Android) / `IOS_BUNDLE_ID` (iOS) so `wdio.conf` puts the id on the session |
 | `SG-E022` | The **generated spec file itself** is not parseable JS/TS, so NOTHING in it runs — Playwright reports one `SyntaxError` and every scenario in the unit is lost. A compiler self-check (`@babel/parser`) on the emitted code, added after a field report where the runtime-data marker post-processor mis-paired quote delimiters across two literals and the user only found out at `npx playwright test`. Reported, never thrown — the file is still written so you keep the artifact to inspect. **Unlike every other code in this table this one blames the COMPILER, not your `.feature`** | Nothing to fix in the Gherkin — this should be impossible. **Report it** with the `.feature` (and the step) the file was generated from, attaching the unparseable `.spec.ts`. Check first that you are running the project-local compiler (`npx sungen`), not an older global one |
-| `SG-E023` | The step carries an **assertion clause** (`matches "…"`, `contains`, `has text`) but the generated code is a BARE VISIBILITY check — the clause was swallowed by a catch-all and the test would pass whatever the element says. The sibling of `SG-E021`, for the clauses that are not states: `SG-E021` closed the state case declaratively, but a dropped `matches`/`contains`/`has text` still slid through (reproduced live: a `matches "<format>"` step compiled by an older sungen lost the assertion entirely, emitted no warning, and left a `toBeVisible()` that passed whatever the label said). Four separate defects arrived this way, so the step now compiles to a runtime `throw`. Deliberately narrow — fires only on the bare-visibility shape, so a pattern that genuinely consumed the clause (`is-hidden`, `contains`, `matches-format`, the state family, or a `filter({ hasText })` on a list member) is untouched. Also fires on a trailing `is <word>` / `is not <word>` that is no state (`is on`, `is open`, `is active`, `is not visible`) — only `is visible`/`displayed`/`shown`/`present` and `is not hidden` are what a visibility check asserts | For an `is <word>` ending: use a state from the `sungen-gherkin-syntax` States list (`is expanded`/`is collapsed` for a disclosure), or `@manual`. Otherwise, either the phrasing is not the supported one for that clause — check the exact form in `sungen-gherkin-syntax` — or this sungen predates the step: verify you are running the project-local compiler (`npx sungen`), not an older global one |
+| `SG-E023` | The step carries an **assertion clause** (`matches "…"`, `contains`, `has text`) but the generated code is a BARE VISIBILITY check — the clause was swallowed by a catch-all and the test would pass whatever the element says. The sibling of `SG-E021`, for the clauses that are not states: `SG-E021` closed the state case declaratively, but a dropped `matches`/`contains`/`has text` still slid through (reproduced live: a `matches "<format>"` step compiled by an older sungen lost the assertion entirely, emitted no warning, and left a `toBeVisible()` that passed whatever the label said). Four separate defects arrived this way, so the step now compiles to a runtime `throw`. Deliberately narrow — fires only on the bare-visibility shape, so a pattern that genuinely consumed the clause (`is-hidden`, `contains`, `matches-format`, the state family, or a `filter({ hasText })` on a list member) is untouched | Either the phrasing is not the supported one for that clause — check the exact form in `sungen-gherkin-syntax` — or this sungen predates the step: verify you are running the project-local compiler (`npx sungen`), not an older global one |
 | `SG-E024` | A mobile **app-lifecycle** step (`User restart the app` / `User reinstall the app`) in a feature that declares no `Path:` app id. The lifecycle templates resolve the target app through `__resolveAppId()`, a helper the appium test-file template emits ONLY when the id is present, so the spec used to compile clean and then die at runtime with `ReferenceError: __resolveAppId is not defined` — taking the WHOLE spec down, not the one step, because the failure lands in a before hook. (Field case: a mobile unit scaffolded with the nav recipe in `--path` instead of `--reach`, so `Path` never carried an app id.) Now refused at compile time as a `throw` naming the missing line | Add the app id under the `Feature` line: `Path: com.example.app/.MainActivity \| com.example.app`. For a mobile unit `--path` carries the **APP ID** and `--reach` carries the navigation recipe — if the nav recipe ended up in `--path`, that is the mistake |
 | `SG-E025` | A feature tagged `@platform:ios` uses a step the Appium adapter does **not** serve on iOS — the template either throws deep inside a device run (`set-connectivity`, `location-services`, `open-notifications`) or silently does nothing (`hide-keyboard`, a guarded `if (!driver.isIOS …)`). Derived from the template body via the per-OS axis of the step-support matrix, so it cannot disagree with the adapter. Only an explicit `@platform:ios` is gated (`@platform:mobile` picks its OS at run time). Compiles to a loud `throw` | Use a step the matrix marks ✅ for iOS (see `docs/spec/step-support-matrix.md`), tag the feature `@platform:mobile` if it should run on either OS, or tag the scenario `@manual` |
 | `SG-E026` | A **click step names a position** (`at position "top-left"`, `at offset x=…, y=…`) that would not be honoured: the keyword is misspelt or unquoted, a value is outside the grammar (not a number, negative, above 100%, a missing axis, an unknown preset), text follows the position, or another click form claimed the step first (`try to click`, a `with {{v}}` text filter, `… and accept [OK] alert`, `double click`). Each of those would compile to a click on the element's CENTRE and pass — for a backdrop-dismiss overlay that is the one outcome that proves nothing — so the step compiles to a loud `throw` | Write `click [X] <type> at position "top-left\|top-right\|bottom-left\|bottom-right"` or `… at offset x=<n>px\|%, y=<n>px\|%` as the LAST thing in the step, on a plain `click` (no `try to`, no `with {{v}}`, no alert clause). Web only — on mobile tap the control the position targets |
@@ -175,8 +175,7 @@ The scenario uses a SECRET test-data key whose `QA_*` variable is missing in thi
 
 Sungen picks assertion based on element type:
 - **Input** (`field`, `textarea`, `search`, `slider`) → `toHaveValue()`
-- **Dropdown / date-picker** (`dropdown`, `select`, `combobox`, `date-picker`) → the `assertValue` recipe when the entry's `variant:` (or `widgets.select` / `widgets.datepicker`) names one; otherwise a runtime tag probe: `toHaveValue()` on a native `<select>`/input, `toHaveText()` on a `<button role="combobox">` trigger (Radix/shadcn, MUI) or a `<button>` that opens a calendar popover. Pin one branch with `variant: native` or an `assertValue` recipe in `qa/app.yaml`. Any other element with a `variant:` uses its recipe's `assertValue` too.
-- **`SG-W017` on a date-picker fill** (the entry is provably a button: `role: button`, or a css/locator ending in a `button` tag) and, at run time, **`[sungen] [X] is not a fillable element`** (a trigger the compiler could not prove is a button) → the fill target is a calendar / popup trigger. Declare a recipe with `fill` (and `assertValue`) intents in `qa/app.yaml` and set `variant: <recipe>` on the entry, or `widgets.datepicker` for every date-picker. Do not change the step to a click.
+- **Dropdown** (`dropdown`, `select`, `combobox`) → runtime tag probe: `toHaveValue()` on a native `<select>`/input, `toHaveText()` on a `<button role="combobox">` trigger (Radix/shadcn, MUI). Pin one branch with `variant: native` or an `assertValue` recipe in `qa/app.yaml`.
 - **Text** (everything else: `message`, `heading`, `label`, `row`) → `toHaveText()`
 - **Partial** (`contains` keyword) → `toContainText()`
 

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

@@ -37,7 +37,7 @@ AND    →  inherits from preceding keyword
 
 ```
 User is on [T] page | page with {{v}} | dialog      # {{v}} = query/fragment ("?id=200", "#tab") APPENDED to the page value — a bare "200" onto "/x?id=199" gives "?id=199200"
-User fill [T] field | textarea | search | slider | date-picker with {{v}}   # date-picker: web only unless qa/app.yaml declares widgets.datepicker — appium refuses it; on web a <button> trigger (calendar popover) needs a fill recipe (variant: / widgets.datepicker) or it is refused (SG-W017)
+User fill [T] field | textarea | search | slider | date-picker with {{v}}   # date-picker: web only unless qa/app.yaml declares widgets.datepicker — appium refuses it
 User fill [T] uploader with {{f}}                                    [web]
 User clear [T] field
 User check [T] checkbox | toggle | radio
@@ -145,20 +145,14 @@ two content-filtered queries can hit different rows if the table re-renders in b
 ```
 # 1. Visibility: User see [T] type (NEVER add "is visible") | is hidden
 # 2. Text (toHaveText): User see [T] message | header | label with {{v}}
-#    `label` forks on the entry: declared by IDENTITY (xpath/accessibility-id/testid/id/css/locator)
-#    → toContainText on THAT element; `exact: true` → toHaveText, and an EMPTY {{v}} asserts the
-#    element shows no text (contains '' would pass on anything); no entry, or `type: text` → matches
-#    the caption+value text pair anywhere on screen
+#    `label` forks on the entry: declared by IDENTITY (xpath/accessibility-id/testid/id/css)
+#    → asserts THAT element contains {{v}} (add `exact: true` for a strict match); no entry,
+#    or `type: text` → matches the caption+value text pair anywhere on screen
 # 3. Partial (toContainText): User see [T] text contains {{v}}
 # 3b. Format (shape, not value): User see [T] label matches "yyyy/mm/dd ~ yyyy/mm/dd"
-# 4. Input (toHaveValue): User see [T] field | search | slider with {{v}}
-#    dropdown | select | combobox | date-picker → the entry's `assertValue` recipe if it has one
-#    (variant: / widgets.select / widgets.datepicker), else the tag is probed at runtime
-#    (toHaveValue on a native input/select, toHaveText on a custom trigger such as a <button>).
-#    Any element whose entry has a `variant:` reads back through that recipe's `assertValue`
+# 4. Input (toHaveValue): User see [T] field | date-picker | search | slider with {{v}}
+#    dropdown | select | combobox → tag probed at runtime (toHaveValue native, toHaveText custom trigger)
 # 5. State: User see [T] button is disabled | checkbox is checked | dialog with {{v}} is hidden
-#    open/closed: User see [T] button | section is expanded | is collapsed   [web — reads `expanded:`, else aria-expanded;
-#    an entry with `expanded: { state: none }` has no state to read → refused, SG-W017]
 # 6. Attribute (toHaveAttribute): User see [T] image | link with {{v}}
 #    WHICH attribute comes from the entry's `attribute:` — any name, not just href/src
 # 7. Count: User see [T] row with {{count}}
@@ -507,11 +501,7 @@ zero-match assertion failure, not a platform gap.
 
 ### States
 
-`hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `expanded` `collapsed` `sorted ascending` `sorted descending`
-
-Any other trailing `is <word>` / `is not <word>` (`is on`, `is active`, `is open`, `is not visible`) is
-**not** a state: the compiler refuses it (SG-E023) rather than check only visibility. `is displayed` /
-`is shown` / `is present` read as `is visible`, and `is not hidden` as visible too.
+`hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`
 
 ### Element Types
 
@@ -549,18 +539,12 @@ Use `{{$var}}` in test-data YAML for values that must be unique per test run. Re
 
 | Variable | Example | Output |
 |---|---|---|
-| `{{$timestamp}}` | `"User-{{$timestamp}}"` | `"User-1714000000000"` (milliseconds) |
+| `{{$timestamp}}` | `"User-{{$timestamp}}"` | `"User-1714000000"` |
 | `{{$uuid}}` | `"{{$uuid}}"` | `"a1b2c3d4-..."` |
 | `{{$random:min:max}}` | `"{{$random:1:100}}"` | `"42"` |
 | `{{$date}}` | `"{{$date}}"` | `"2026-04-24"` |
-| `{{$date:+Nd}}` / `{{$date:-Nd}}` | `"{{$date:+1d}}"` | `"2026-04-25"` — today shifted by N days |
 | `{{$datetime}}` | `"{{$datetime}}"` | `"2026-04-24T10:30:00.000Z"` |
 
-`{{$date}}` is the LOCAL calendar date of the machine running the tests — the "today" the browser shows
-when `playwright.config.ts` sets no `timezoneId`. If the config pins `timezoneId`, export the same zone as
-`TZ` (e.g. `TZ=Asia/Tokyo npx playwright test`) so both agree. `{{$datetime}}` is a UTC instant (`…Z`). Any `{{$date:…}}` argument other than `±Nd`
-(`tz=…`, a format) and any `{{$datetime:…}}` argument are not supported and stay literal.
-
 **Rules:**
 - `$timestamp` and `$uuid` → same value across all keys in one `load()` call (stable within a test file)
 - `$random` → unique per occurrence (each key gets a different random)

package/src/orchestrator/templates/ai-src/skills/sungen-tc-generation/SKILL.md

@@ -773,9 +773,8 @@ those namespaces are the **System INTEGRATION** group — keep their oracles abo
 > **Auto-detect**: if path is `qa/flows/<name>/` → use this section. Skip Steps 1–4 above.
 
 **Read `requirements/flow-contract.yaml` FIRST — it is the flow's boundary and the yardstick
-`sungen audit` scores the flow against** (`flowCoverage` axis = the declared flows / phases
-automated; `FLOW-OUTCOME-UNPROVEN`; `FLOW-SCOPE-CREEP`; `FLOW-GUARANTEE-MISSING`;
-`FLOW-INVENTORY-MISSING`). **A filled contract is an INPUT — never rewrite it
+`sungen audit` scores the flow against** (`flowCoverage` axis = journey phases HP/ER/EH automated;
+`FLOW-OUTCOME-UNPROVEN`; `FLOW-SCOPE-CREEP`). **A filled contract is an INPUT — never rewrite it
 to match your output** (same rule as `test-viewpoint.md`).
 
 > **HARD RULE — the contract must be AUTHORED, never merely cited.** If
@@ -797,7 +796,7 @@ to match your output** (same rule as `test-viewpoint.md`).
 | Selector format | `[Element]` | `[Screen:Element]` (namespaced) |
 | Test data keys | `{{variable}}` | `{{phase.variable}}` |
 | Feature tag | `@auto` / `@smoke` etc. | `@flow` (required) |
-| Scenario ids | `VP-<CATEGORY>-NNN` | `FL-<PHASE>-NNN` — use-case phases `BF`/`AF0n`/`EF0n` (see below), or the flat `HP` (happy path) / `ER` (error recovery) / `EH` (guards) / `UI` for a short single-outcome flow — the contract still needs both guarantees and a `flows:` inventory either way |
+| Scenario ids | `VP-<CATEGORY>-NNN` | `FL-<PHASE>-NNN` — use-case phases `BF`/`AF0n`/`EF0n` (see below), or the flat `HP` (happy path) / `ER` (error recovery) / `EH` (guards) / `UI` for a short single-outcome flow |
 
 **Scenarios to generate — every phase demanded by the contract, automated:**
 

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();
+}