@sun-asterisk/sungen 3.2.25 → 3.2.27

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

@@ -68,6 +68,23 @@ Use these when repairing GATE/DEPTH findings for the hard viewpoints (cart/detai
 4. **EP/data families are OK.** A `duplicates` cluster with `sameDataLikely=false` is an intentional equivalence-partition family (e.g. many invalid-email cases) — keep it; only collapse `sameDataLikely=true` exact duplicates.
 5. **Advisory findings — surface, don't gate.** `MANUAL-REASON-MISMATCH` → fix the scenario's `@manual:Mx` code (so the planner recommends the right driver) during repair. `CAPABILITY-SUGGESTION` → **present it to the user as a next-step option** (e.g. "N @manual could be automated — `sungen capability add api db`?"), **recommend-only — never auto-install**. `VERIFICATION-OUT-OF-SCOPE (api|db)` → the unit uses `@api`/`@query`/`@requires:api|db` verification the project's recorded **test type** never opted into (E2E/UI-only per `capabilities.yaml`, and the viewpoint doesn't ask for it). During repair: **rewrite the oracle to be UI-observable** (or downgrade the deep check to an `(optional deep check: …)` note); only keep the API/DB verification if the project genuinely tests that layer — then record it (`verification: [ui, api]` / `sungen capability add`). Keep API/DB-in-E2E to the ≤20% band. Neither of these fails the gate.
 
+6. **A gate that contradicts the spec's intent is a question, not a repair.** When the only way to
+   satisfy a finding is to change what the spec deliberately asked for — widening an entry variant the
+   spec keeps light so `FLOW-SCOPE-CREEP` stops firing, renaming a title around a trigger word so a
+   claim rule stops firing, adding an assertion the spec never demands — **stop and put the conflict
+   to the user** (`AskUserQuestion`: the finding, the spec passage it collides with, the two ways out).
+   A score reached by editing toward the gate is not a measurement of the suite; it is a measurement
+   of how well the gate was gamed, and the human reviewer will read it as over-testing or a false
+   claim. Where the harness provides a declaration route — `flows:` with a per-flow `outcome:`, a
+   `status: deferred` with a reason, `@manual` naming the gesture — that route is the fix, never the
+   scenario.
+7. **`--accept-viewpoint` is a QA decision. Never run it.** `atomicLedger` and `traceability` are
+   evidence only while `test-viewpoint.md` is independent of what was generated. `sungen next` lists
+   the acceptance as a `⚖ decide` step: present it (the diff of declared ids, what was added, what was
+   dropped) and let the QA run the command. An agent that accepts the yardstick it just wrote makes
+   both axes read 100% by construction — and the spec's Exception Flow it forgot stops being missing
+   from anything.
+
 ## Discovery / fallback tree (when input is limited)
 
 ```

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

@@ -340,6 +340,9 @@ Security:         [S1 – admin only]
 `sungen audit` enforces these. Generate compliant output up front:
 
 1. **Taxonomy-match** (`VP-TAXONOMY-MISMATCH`, gate-FAIL) — when `test-viewpoint.md` declares its own viewpoint IDs (e.g. `VP0`, `VP1`, … `VP12`, `MS-HP-001`, `MS-EH-001`), **reuse those IDs verbatim as the scenario codes**. Do NOT invent a generic `VP-UI / VP-LOGIC / VP-VAL` scheme — that breaks the coverage matrix. Only fall back to `VP-<CATEGORY>-<NNN>` when the viewpoint file declares no IDs.
+   - **`--accept-viewpoint` is the QA's command, not yours.** `sungen next` shows it as a `⚖ decide`
+     step. Present the declared-id diff and stop; a yardstick accepted by the process it measures
+     reads 100% by construction.
    - **Match the scenarios to the file — never the file to the scenarios.** A filled `test-viewpoint.md` is an input; do not rewrite its declarations to fit what you generated. That is not compliance, it is moving the yardstick: `traceability` + `atomicLedger` then read 100% by construction and a dropped viewpoint stops being missing from anything. Disagree with the taxonomy → propose the diff and ask. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and excludes both axes until a human accepts the change (`sungen audit --screen <name> --accept-viewpoint`).
 2. **Spec-coverage triggers** (`TRIGGER-UNCOVERED`, gate-FAIL) — the Validation-Rules table lists a **trigger** per constraint (e.g. `blur, submit`). Generate one scenario **per (constraint × trigger)** — a `format` rule validating *on blur AND on submit* needs BOTH a blur scenario (`press Tab`) and a submit scenario (`click [Submit]` / `press Enter`). Never collapse the trigger × input matrix to one representative case.
 3. **Claim-Proof** (`CLAIM-UNPROVEN`) — a title claiming `all`/`only`/`every`/`single`/`correct`/`same`/`changes`/`hidden`/`cleared`/`restored`/`independent`/`sanitized`/`announces` MUST have the matching assertion (`see all …`, count, `remember`+compare, `is hidden`, return-and-assert-empty, etc.). If the title promises it, the steps must prove it.
@@ -718,7 +721,7 @@ flows:
     branchFrom: "BF step 1, the control tapped twice"
     outcome: "One request, one record"
     status: pending-clarification      # the spec is silent — ASK, never assume a guard
-    reason: "The guard lives in ST_AUTH_001's spec, which this project does not hold."
+    reason: "The guard lives in SCREEN_A_001's spec, which this project does not hold."
 ```
 
 Four statuses, and **silence is not one of them**: `covered` · `deferred` · `pending-clarification`
@@ -728,6 +731,36 @@ missing flow. `sungen audit` then measures `flowCoverage` per DECLARED FLOW and
 `FLOW-UNCOVERED` (declared, nobody wrote it), `FLOW-UNDECLARED` (a scenario claiming a flow id the
 inventory never declares), `FLOW-STATUS-UNREASONED` and `FLOW-INVENTORY-MISSING`.
 
+**Enumerate every branch the spec declares — do not rely on reading carefully.** Before writing
+scenarios, list each mutually-exclusive branch the spec makes explicit, one line per arm:
+
+- every `### Exception Flow X` / `### Alternative Flow X` heading;
+- every row of a decision table (`DEC-*`, `BR-*`, any table of conditions → outcomes);
+- every arm of an if/elif/else cascade in pseudocode;
+- every state transition a state machine declares.
+
+Each arm needs its OWN scenario, or a written exclusion. **Covering a sibling arm proves nothing
+about this one** — and two scenarios that assert the same thing under different names are one test
+counted twice, which is worse than a gap because the coverage sheet reports it as two.
+`sungen audit` reports `SPEC-BRANCH-UNCOVERED` and `BRANCH-OVERCLAIMED`. This rule existed as
+prose before and was missed three times in three flows; it is enumerated now for that reason.
+
+**Two viewpoints per UI region, not one.** A region that has both conditional rendering (`DEC-*`)
+and an acceptance scenario describing a click needs a case for EACH: "render — DEC-xxx" and
+"interaction — click → destination". Finishing the render half is the easy half, and stopping there
+is the common failure. Every navigation target the spec names needs a click-through case
+(`NAV-TARGET-ABSENT`), even when this flow does not consume the destination — a context param
+handed to another screen is that screen's input, and the handoff is where it goes wrong.
+
+**A deny case needs its allow case.** "permission denied → content hidden" passes just as happily
+when the content is hidden for everyone. Pair it with "permission granted → content shown", the
+way a boundary needs `min-1 / min / max / max+1` (`PERMISSION-PAIR-MISSING`).
+
+**State that ARRIVES with the data is a different case from state the test creates.** A
+discriminator field you can only observe at load (an item already favourited before the page
+opens) is a different oracle timing from the same field set by an action inside the test. Both are
+needed; the first is usually `@manual:M1` or a data-factory fixture.
+
 **One id per atomic CLAIM in the viewpoint.** The flow id groups; the viewpoint id identifies.
 Writing `FL-BF-001` on four different claims makes the ledger count four items while traceability
 sees one, so the coverage arithmetic and "which test proves this?" are both wrong and neither
@@ -791,6 +824,13 @@ is a gap to REPORT, not to quietly absorb.
 that never touches `outcome.screen` and is not a guard (`EH`) or error-recovery (`ER`) belongs in a
 DIFFERENT flow — propose the split instead of writing it here (`FLOW-SCOPE-CREEP` will flag it).
 Auth persistence across transitions is part of `EH` unless the project declares it its own phase.
+**The exception is declared, not widened:** when the spec KEEPS a variant deliberately light — an
+entry variant that only proves the alternative entry reaches the action bar, without repeating the
+full assertion the basic flow already carries — declare that flow in `flows:` with its own
+`outcome:` and the audit judges it against that outcome. Never widen the scenario to satisfy the
+gate; a reviewer reads the result as over-testing, and the finding was the thing that was wrong.
+When a gate and the spec's stated intent collide and no declaration route exists, stop and put the
+conflict to the user — do not edit toward the score.
 
 **Manual in flows**: always `@manual:Mx` with the reason code — bare `@manual` is flagged
 (`MANUAL-CODE-MISSING`) because the capability planner cannot route it. Typical flow deferrals:
@@ -817,7 +857,7 @@ Feature: Award Submission Flow
 
   @high
   Scenario: FL-EH-001 Direct access to the award form without login redirects to login
-    When User go to [Awards] page
+    Given User is on [Awards] page
     Then User see [Login] page
 ```
 

package/src/utils/ref-key.ts

@@ -0,0 +1,43 @@
+/**
+ * ONE vocabulary for what a `[Reference]` means.
+ *
+ * The compiler's documented key rule is "the lowercase of the `[Reference]` text, spaces
+ * preserved" (`SelectorResolver.generateKey`). The harness re-implemented that rule with its own
+ * regex — `/\[([a-z0-9_.-]+):/` — which has no space in it, so a multi-word screen such as
+ * `[Basic Info:Email]` compiled, ran and passed, and was NEVER seen by `touchesOutcome`,
+ * `reachesOutcome`, phase coverage, handoffs or the navigation-target check. A real project
+ * hyphenated every namespace with zero functional change and its audit went 6.9 → 8.9 (#660).
+ *
+ * Two rules, one place:
+ *  - `normalizeRefLabel` IS the compiler's key rule. The compiler delegates here.
+ *  - `screenKey` is the COMPARISON form the harness uses for a screen/namespace: separators are
+ *    equivalent (`basic info` ≡ `basic-info` ≡ `basic_info`), because a contract author writes
+ *    `outcome.screen: basic-info` as readily as the feature writes `[Basic Info:…]`, and the
+ *    harness only ever asks "is this the same screen?" — never "which YAML key resolves?".
+ */
+
+/** The compiler's selector-key rule: NFC, lowercase, trimmed, inner whitespace collapsed. */
+export function normalizeRefLabel(label: string): string {
+  return label.normalize('NFC').toLowerCase().trim().replace(/\s+/g, ' ');
+}
+
+/** Comparison form for a screen / namespace name — separator-insensitive. */
+export function screenKey(label: string): string {
+  return normalizeRefLabel(label).replace(/[\s_-]+/g, ' ').trim();
+}
+
+/**
+ * Every namespace a piece of step text references, in order, as `screenKey`s.
+ * `[Screen:Element]` → `screen`; a bare `[Screen]` page reference is included too when `bare`
+ * is set (a `see [Done] page` assertion names the screen without an element).
+ */
+export function refNamespaces(text: string, opts: { bare?: boolean } = {}): string[] {
+  const out: string[] = [];
+  for (const m of text.matchAll(/\[([^\]]+)\]/g)) {
+    const inner = m[1];
+    const colon = inner.indexOf(':');
+    if (colon !== -1) out.push(screenKey(inner.slice(0, colon)));
+    else if (opts.bare) out.push(screenKey(inner));
+  }
+  return out;
+}