@sun-asterisk/sungen 3.2.26 → 3.2.27

package/src/harness/flow-contract.ts

@@ -22,6 +22,7 @@
  *                       declared collection (order, application, submission …)
  */
 import * as fs from 'fs';
+import { refNamespaces, screenKey } from '../utils/ref-key';
 import * as path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { ScenarioInfo } from './parse';
@@ -179,7 +180,7 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
       actor: raw.actor !== undefined ? String(raw.actor) : undefined,
       trigger: raw.trigger !== undefined ? String(raw.trigger) : undefined,
       precondition: raw.precondition !== undefined ? String(raw.precondition) : undefined,
-      outcome: { screen: String(outcome!.screen).toLowerCase(), assertion: outcome!.assertion !== undefined ? String(outcome!.assertion) : undefined },
+      outcome: { screen: screenKey(String(outcome!.screen)), assertion: outcome!.assertion !== undefined ? String(outcome!.assertion) : undefined },
       value: raw.value !== undefined ? String(raw.value) : undefined,
       successGuarantee: raw.successGuarantee !== undefined ? String(raw.successGuarantee) : (raw.success_guarantee !== undefined ? String(raw.success_guarantee) : undefined),
       minimalGuarantee: raw.minimalGuarantee !== undefined ? String(raw.minimalGuarantee) : (raw.minimal_guarantee !== undefined ? String(raw.minimal_guarantee) : undefined),
@@ -210,7 +211,7 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
             .map((e) => ({
               name: String(e.name),
               owner: e.owner !== undefined ? String(e.owner) : undefined,
-              screens: Array.isArray(e.screens) ? (e.screens as unknown[]).map((x) => String(x).toLowerCase()) : [],
+              screens: Array.isArray(e.screens) ? (e.screens as unknown[]).map((x) => screenKey(String(x))) : [],
             }))
         : undefined,
       golden: raw.golden === true,
@@ -223,13 +224,12 @@ export function loadFlowContract(unitDir: string): { contract: FlowContract | nu
 
 /** `[screen:element]` namespaces referenced by a scenario's steps, in step order. */
 function namespacesInOrder(s: ScenarioInfo): string[] {
-  const out: string[] = [];
-  for (const m of s.stepsText.matchAll(/\[([a-z0-9_.-]+):/g)) out.push(m[1]);
-  return out;
+  // Through the shared vocabulary — a private regex here once dropped every multi-word screen (#660).
+  return refNamespaces(s.stepsText);
 }
 
 function touchesOutcome(s: ScenarioInfo, outcomeScreen: string): boolean {
-  return namespacesInOrder(s).includes(outcomeScreen);
+  return namespacesInOrder(s).includes(screenKey(outcomeScreen));
 }
 
 /**
@@ -244,7 +244,8 @@ function reachesOutcome(s: ScenarioInfo, outcomeScreen: string): boolean {
   // anywhere in the scenario would suppress every positive assertion in it.
   const steps = (s.steps ?? []).map((st) => st.text.toLowerCase());
   if (steps.length === 0) return touchesOutcome(s, outcomeScreen);
-  return steps.some((t) => t.includes(`[${outcomeScreen}`)
+  const key = screenKey(outcomeScreen);
+  return steps.some((t) => refNamespaces(t, { bare: true }).includes(key)
     && !/\b(is hidden|is not visible|does not exist|is absent|no longer)\b/.test(t));
 }
 
@@ -366,15 +367,39 @@ export function flowInventory(contract: FlowContract, scenarios: ScenarioInfo[])
  * Both inflate the flow count while adding no branch coverage, which is exactly what makes a
  * suite look complete to the harness and thin to a reviewer.
  */
+/** An interaction, whichever keyword the author put in front of it — `Then User click` exists. */
+const INTERACTION_VERB = /\buser\s+(?:click|clicks|tap|taps|fill|fills|type|types|select|selects|press|presses|check|checks|uncheck|unchecks|upload|uploads|submit|submits|enter|enters|choose|chooses|toggle|toggles|drag|drags|swipe|swipes|scroll|scrolls|hover|hovers|clear|clears)\b/i;
+
 export function misfiledPhases(
   contract: FlowContract, scenarios: ScenarioInfo[], basicPhase: string,
 ): Array<{ scenario: string; id: string; why: string }> {
   const out: Array<{ scenario: string; id: string; why: string }> = [];
   const outcome = contract.outcome.screen;
+  // A branch point is a STRUCTURAL fact before it is a vocabulary one. The check used to demand a
+  // branch WORD (back / cancel / retry…), so a precondition guard — `Given` already authenticated,
+  // or no originating session → `Then` redirected — had no way to satisfy it: such a scenario has
+  // no interaction step at all, by construction, and its branch is in the `Given`, not in a verb.
+  // Reported under AF and EF alike on a real project (#660). Two structural signals now count:
+  // no `When` at all (a guard by construction), or a `Given` the basic flow never establishes
+  // (a precondition branch). Vocabulary remains as the fallback for scenarios without step data.
+  const basicGivens = new Set(scenarios
+    .filter((sc) => phaseToken(flowIdOf(sc, contract.phases) ?? '') === phaseToken(basicPhase))
+    .flatMap((sc) => (sc.steps ?? []).filter((st) => st.bucket === 'given').map((st) => st.text.toLowerCase().trim())));
+  const branchesStructurally = (sc: ScenarioInfo): boolean => {
+    const steps = sc.steps ?? [];
+    if (steps.length === 0) return false;
+    // No interaction AND the journey does not complete: a guard by construction (the redirect or
+    // the blocked screen IS the branch). No interaction but the outcome IS reached is a different
+    // animal — a postcondition on the basic path — and stays subject to the checks below.
+    const interacts = steps.some((st) => st.bucket === 'when' || INTERACTION_VERB.test(st.text));
+    if (!interacts && !reachesOutcome(sc, outcome)) return true;
+    return steps.some((st) => st.bucket === 'given' && !basicGivens.has(st.text.toLowerCase().trim()));
+  };
   for (const s of scenarios) {
     const id = flowIdOf(s, contract.phases);
     if (!id || phaseToken(id) === phaseToken(basicPhase)) continue;
     const ph = phaseToken(id);
+    if (branchesStructurally(s)) continue;
     if (ph === 'EF' && reachesOutcome(s, outcome)) {
       // An error-then-recover flow legitimately ends at the outcome — it is the recovery that
       // is being proven, and a guard flow is blocked rather than "failed". Only a scenario with
@@ -415,8 +440,16 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
   // guard/error phase is evidence of a SECOND business goal in this flow.
   const declaredPhases = contract.phases;
   const basic = declaredPhases.filter((p) => p !== 'UI')[0];
+  // A flow the inventory declares WITH ITS OWN outcome is measured against that outcome, never
+  // against the use case's. A spec that keeps an entry variant deliberately light ("prove the
+  // entry reaches the action bar; do not repeat the full assertion") could only satisfy the old
+  // check by widening the scenario — which the human reviewer then called over-testing. The gate
+  // and the reviewer were optimising different things; the declaration is where they agree (#660).
+  const ownOutcome = new Set((contract.flows ?? []).filter((f) => f.outcome).map((f) => f.id));
   const offGoalScenarios = scenarios.filter((s) => {
     if (touchesOutcome(s, outcomeScreen)) return false;
+    const fid = flowIdOf(s, declaredPhases);
+    if (fid && ownOutcome.has(fid)) return false;
     const ph = phaseOf(s, declaredPhases, contract.phaseDetails);
     // Any NON-basic declared phase (guards, error recovery, alternate branches) legitimately
     // stops before the outcome — that is what a branch IS. Only an unclassified scenario that
@@ -470,7 +503,7 @@ export function flowQuality(unitDir: string, scenarios: ScenarioInfo[]): FlowQua
     const steps = s.steps ?? [];
     let current: string | null = null;
     for (let i = 0; i < steps.length; i++) {
-      const ns = (steps[i].text.match(/\[([A-Za-z0-9_.-]+):/) || [])[1]?.toLowerCase() ?? null;
+      const ns = refNamespaces(steps[i].text)[0] ?? null;
       if (!ns) continue;
       if (current !== null && ns !== current) {
         total++;

package/src/harness/next-step.ts

@@ -25,8 +25,14 @@ export interface NextStep {
   command: string;
   /** Why it is next — stated so an agent can weigh it, not just obey it. */
   because: string;
-  /** `blocked` steps are not runnable yet; they name what to resolve first. */
-  kind: 'do' | 'blocked' | 'optional';
+  /**
+   * `blocked` steps are not runnable yet; they name what to resolve first. `decide` steps are a
+   * HUMAN'S to run: an agent presents them and stops. Accepting the viewpoint baseline is the
+   * case — offered as a plain `do`, an agent that had just rewritten `test-viewpoint.md` from the
+   * spec ran it, and `atomicLedger`/`traceability` read 100% against a checklist it wrote itself
+   * in the same session (#660).
+   */
+  kind: 'do' | 'blocked' | 'optional' | 'decide';
 }
 
 export interface UnitState {
@@ -228,9 +234,9 @@ export function deriveSteps(s: UnitState): NextStep[] {
   }
   if (s.audit.viewpointBaselineStatus === 'changed') {
     out.push({
-      kind: 'do',
+      kind: 'decide',
       command: `sungen audit --screen ${s.unit} --accept-viewpoint`,
-      because: 'test-viewpoint.md changed since the accepted baseline, so the ledger and traceability axes are not evidence until you confirm the new declaration',
+      because: 'test-viewpoint.md changed since the accepted baseline, so the ledger and traceability axes are not evidence until a QA confirms the new declaration. A decision, not a step: an agent presents it and does not run it — accepting the yardstick you just wrote makes both axes read 100% by construction',
     });
   }
   const repair = s.audit.findings

package/src/harness/sensors.ts

@@ -659,7 +659,15 @@ const CLAIM_RULES: ClaimRule[] = [
     // category behind "browser back does not re-submit", "does not re-charge the card",
     // "double-click does not create two orders" — not a per-feature keyword.
     claim: 'no-side-effect/no-duplicate',
-    title: /(?=.*\b(submit|sen[dt]|resend|resubmit|re-?fire|re-?issue|re-?post|repost|create|charge|order|payment|\bpay\b|email|request|\botp\b|insert|register|book|duplicate|double[- ]?submit|again|twice)\b)(?=.*(\bno\b|\bnot\b|n['’]t\b|\bnever\b|\bwithout\b|\bcannot\b|prevent|block|avoid|reject|disabl|\bdeny\b|denies|\bkhông\b|\bchưa\b))/i,
+    // The negation must attach to an EFFECT — something created, sent, stored, charged, fired
+    // twice — not to the INPUT being refused. "duplicate address is rejected" is an observable
+    // rejection, proven by the error assertion in front of the user; "no duplicate record is
+    // created" is an absence nothing on the page can show. The rule used to fire on any action
+    // word beside any negation word, so ordinary rejection titles were told to go find a DB count,
+    // and renaming around the trigger words became the workflow (#660). Two shapes now qualify:
+    // (a) a negation followed by an effect token, (b) a repeat token (twice / again / double- or
+    // re-submit / second …) beside a negation, "only once" or a disabled control.
+    title: /(?:\b(?:no|not|n['’]t|never|without|cannot|không|chưa)\b[^.;]{0,40}?\b(?:creat(?:e|es|ed|ion)|record(?:s|ed)?|rows?|entr(?:y|ies)|sen[dt]|resen[dt]|charg(?:e|es|ed)|order(?:s|ed)?|payment|paid|insert(?:s|ed)?|submit(?:s|ted)?|submission|stor(?:e|es|ed)|sav(?:e|es|ed)|persist(?:s|ed)?|fir(?:e|es|ed)|issu(?:e|es|ed)|post(?:s|ed)?|email(?:s|ed)?|request(?:s|ed)?|\botp\b|twice|again|second|double|duplicate[sd]?|re-?submit(?:s|ted)?|tạo|gửi|lưu)\b)|(?=.*\b(?:double[- ]?(?:submit|click|tap|activation)|re-?submi(?:t|ts|tted|ssion)|twice|again|second (?:submit|submission|request|click|tap|order|charge|email|record))\b)(?=.*\b(?:no|not|n['’]t|never|without|cannot|prevent(?:s|ed)?|block(?:s|ed)?|avoid(?:s|ed)?|only once|exactly one|single|idempotent|disabled|không|chưa)\b)/i,
     // `is disabled` counts: when the spec's own mechanism against a repeat is "the control
     // is disabled immediately" (FR-014-style), asserting the disabled state IS the contrast —
     // the second activation cannot occur. Without it the canonical double-submit proof shape

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

@@ -96,7 +96,7 @@ dropped along the way stops being missing from anything. `sungen audit` now repo
 `VIEWPOINT-ADOPTED-POST-HOC` on the first sighting of a viewpoint alongside an existing suite and
 holds `atomicLedger` + `traceability` as unverified until a human accepts it — so the honest move
 is to write the claims from `spec.md` and the contract, mark plainly that they are a draft for QA
-review, and let the QA revise before `--accept-viewpoint`.
+review, and let the QA revise before `--accept-viewpoint`. **You never run `--accept-viewpoint` yourself** — `sungen next` lists it as a `⚖ decide` step for exactly this reason: an agent accepting the yardstick it wrote in the same session makes `atomicLedger` and `traceability` read 100% against its own checklist, and the Exception Flow it forgot stops being missing from anything. Present the acceptance to the QA (`AskUserQuestion`) with what the file declares, and stop.
 
 **When you give a claim an id, a scenario must carry that id.** The id is the contract: a claim
 whose id no scenario carries is reported MISSING, and word overlap will not rescue it. Several

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.
@@ -821,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:
@@ -847,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;
+}