@sun-asterisk/sungen 3.2.16-beta.11 → 3.2.16-beta.13

package/src/harness/audit.ts

@@ -9,6 +9,7 @@
 import * as path from 'path';
 import * as fs from 'fs';
 import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
+import { checkViewpointBaseline, ViewpointBaseline } from './viewpoint-baseline';
 import { featureBasename } from './unit-paths';
 import {
   loadCatalog, viewpointGate, assertionDepth, dataThemesFor, depthThresholdFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
@@ -46,6 +47,7 @@ export interface AuditReport {
   flowDepth: FlowDepthResult;   // H3 — stateful-flow regression depth (count / teardown / multi-source)
   oracle: OracleStrengthResult; // H4 — facet-oracle strength (weak name-substring vs title/detail/API/DB)
   ledger: LedgerResult;         // atomic viewpoint-item coverage (per-bullet status)
+  viewpointBaseline: ViewpointBaseline; // is the yardstick still the accepted one? (#557)
   calibration: {                // #8 — multi-axis score so a high overall can't hide a weak axis
     axes: Record<string, number>;
     weakest: { axis: string; value: number };
@@ -73,7 +75,7 @@ export interface AuditReport {
 }
 
 /** The catalog-resolution id for a unit dir (relative to qa/): screen · flows/<flow> · api/<area> · api/flows/<flow>. */
-function catalogIdFromScreenDir(screenDir: string): string {
+export function catalogIdFromScreenDir(screenDir: string): string {
   const parts = screenDir.split(path.sep);
   const qa = parts.lastIndexOf('qa');
   if (qa >= 0) {
@@ -154,6 +156,9 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const capGate = scoringCap?.gateProvider as
     ((i: { scenarios: ScenarioInfo[]; viewpoints: ViewpointEntry[]; catalog: Catalog; focus: typeof intent.focus; cwd: string; screenName: string; threshold: number; businessCriticalMethods?: string[] }) => { gate: GateResult; depth: DepthResult }) | undefined;
   const provided = capGate?.({ scenarios, viewpoints, catalog, focus: intent.focus, cwd: projectRootFromScreenDir(screenDir), screenName: catalogScreenName, threshold: depthThresholdFor(intent.focus), businessCriticalMethods: intent.businessCriticalMethods });
+  // Is the declaration this suite is measured against still the one a human accepted?
+  const viewpointBaseline = checkViewpointBaseline(
+    projectRootFromScreenDir(screenDir), catalogScreenName, viewpointPath);
   const viewpointText = fs.existsSync(viewpointPath) ? readTextFile(viewpointPath) : '';
   const gate = provided?.gate ?? viewpointGate(scenarios, viewpoints, catalog, platform === 'mobile', viewpointText);
   const depth = provided?.depth ?? assertionDepth(scenarios, dataThemesFor(catalog, gate.pageType), intent.focus);
@@ -234,13 +239,19 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   //     claimProof, specFR, atomicLedger — now carry weight. A suite where two
   //     thirds of the scenarios do not prove their own title used to score 7.9.
   const specRatio = spec.frTotal ? spec.frCovered / spec.frTotal : 1;
+  //  3. Evidence has to be INDEPENDENT of what it judges. `atomicLedger` and
+  //     `traceability` both measure the suite against test-viewpoint.md, so a run
+  //     that rewrites that file scores them 100% by construction — which is exactly
+  //     what a create-test run did, silently dropping the performance viewpoint on
+  //     the way. While the declaration is unconfirmed, neither axis is evidence.
+  const viewpointMoved = viewpointBaseline.status === 'changed';
   const axisDefs: Array<{ key: string; value: number; weight: number; applicable: boolean; critical: boolean }> = [
     { key: 'coverage', value: coverage, weight: 0.22, applicable: !!gate.pageType && gate.themesTotal > 0, critical: true },
     { key: 'specFR', value: specRatio, weight: 0.15, applicable: spec.hasSpec && spec.frTotal > 0, critical: true },
-    { key: 'atomicLedger', value: ledger.ratio, weight: 0.13, applicable: ledger.hasViewpoint && ledger.total > 0, critical: true },
+    { key: 'atomicLedger', value: ledger.ratio, weight: 0.13, applicable: ledger.hasViewpoint && ledger.total > 0 && !viewpointMoved, critical: true },
     { key: 'businessDepth', value: businessDepth, weight: 0.20, applicable: true, critical: true },
     { key: 'claimProof', value: claim.ratio, weight: 0.15, applicable: claim.withClaims > 0, critical: true },
-    { key: 'traceability', value: traceScore, weight: 0.09, applicable: viewpoints.length > 0, critical: false },
+    { key: 'traceability', value: traceScore, weight: 0.09, applicable: viewpoints.length > 0 && !viewpointMoved, critical: false },
     { key: 'balance', value: balanceScore, weight: 0.06, applicable: true, critical: false },
   ];
   const scored = axisDefs.filter((a) => a.applicable);
@@ -278,6 +289,13 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
       : `this unit supplies no evidence for [${missingEvidence.join(', ')}], and a top mark has to rest on complete evidence`;
     findings.push(`SCORE-CAPPED: overall held at ${cap.toFixed(1)} because ${why}.`);
   }
+  if (viewpointBaseline.status === 'changed') {
+    const moved = [
+      viewpointBaseline.removed?.length ? `removed [${viewpointBaseline.removed.join(', ')}]` : '',
+      viewpointBaseline.added?.length ? `added [${viewpointBaseline.added.join(', ')}]` : '',
+    ].filter(Boolean).join(', ');
+    findings.push(`VIEWPOINT-BASELINE-CHANGED: test-viewpoint.md no longer declares what it did when this unit was last accepted — ${moved || 'the declared ids were reordered or replaced'}. atomicLedger + traceability measure the suite AGAINST this file, so they are excluded from the score until the change is confirmed: a generator that rewrites the declaration scores both 100% by construction, and a viewpoint dropped from the file stops being missing from anything. Review the diff (a removed id means that coverage is now unclaimed), then run \`sungen audit --screen ${screenName} --accept-viewpoint\`.`);
+  }
   if (gate.pageTypeSource === 'undetermined') {
     findings.push(`PAGE-TYPE-UNDETERMINED: no page type fits this screen with enough confidence (best ${gate.pageTypeEvidence?.hits ?? 0} keyword hit(s)), so NO critical themes were demanded and the coverage axis is excluded from the score — declare it in test-viewpoint.md (\`page-type: <id>\`) to have the theme checklist applied.`);
   }
@@ -465,7 +483,7 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
     screen: screenName,
     scenarioCount: scenarios.length,
     gate, depth, claim, taxonomy, balance, duplicates, trace, spec,
-    taxonomyMismatch, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, flowDepth, oracle, ledger, calibration,
+    taxonomyMismatch, downstream, manualOracle: manualOracleResult, automatableManual: autoManual, flowDepth, oracle, ledger, viewpointBaseline, calibration,
     score: {
       overall: Math.round(overall * 10) / 10,
       coverage: Math.round(coverage * 100) / 100,

package/src/harness/capability-plan.ts

@@ -114,6 +114,11 @@ export function inferFromText(reason: string): string | undefined {
   return undefined;
 }
 
+/** Every code the text supports, not just the first rule in declaration order. */
+export function inferAllFromText(reason: string): string[] {
+  return INFER.filter((r) => r.re.test(reason)).map((r) => r.code);
+}
+
 export interface ReasonMismatch { scenario: string; explicit: string; inferred: string }
 
 /**
@@ -150,8 +155,15 @@ export function manualReasonMismatches(featurePath: string): ReasonMismatch[] {
       else if (l === '') continue;
       else break;
     }
-    const inferred = inferFromText(parts.join(' '));
-    if (inferred && inferred !== explicit) out.push({ scenario: m[1].trim(), explicit, inferred });
+    // The block scanned here includes the tester PROCEDURE, so several codes can
+    // match at once — "not worth automating" (M8, the author's actual reason) and
+    // "the service stays responsive" (M6, a word about latency, not layout). The
+    // first rule in declaration order used to win and the correct tag was reported
+    // as a mismatch. A tag is only wrong when the text supports some OTHER code and
+    // NOT the declared one.
+    const codes = inferAllFromText(parts.join(' '));
+    const inferred = codes.find((c) => c !== explicit);
+    if (inferred && !codes.includes(explicit)) out.push({ scenario: m[1].trim(), explicit, inferred });
   }
   return out;
 }

package/src/harness/viewpoint-baseline.ts

@@ -0,0 +1,128 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseViewpointOverview } from './parse';
+
+/**
+ * Keep the yardstick from moving with the thing it measures.
+ *
+ * `test-viewpoint.md` is the project's declaration of WHAT must be tested, and two
+ * scored axes measure the suite against it: `traceability` (do scenarios use the
+ * declared viewpoint ids?) and `atomicLedger` (is every declared item covered?).
+ * Both are only evidence while the declaration is INDEPENDENT of the suite.
+ *
+ * A `/sungen:create-test` run rewrote a filled test-viewpoint.md, replacing the
+ * declared categories with exactly the ones it had just generated. Both axes read
+ * 100% by construction — and the performance viewpoint it dropped on the way
+ * (4 perf scenarios → 2) went unreported, because VP-PERF was no longer declared
+ * for anything to be missing from.
+ *
+ * So: remember the declaration, and when it changes, say so and stop counting the
+ * two axes that depend on it until a human accepts the new baseline. Same rule the
+ * score model already applies to an undetermined page type — absent independent
+ * evidence scores nothing, in either direction.
+ */
+
+/** Axes whose evidence is `test-viewpoint.md` — excluded while the baseline is unconfirmed. */
+export const VIEWPOINT_DEPENDENT_AXES = ['atomicLedger', 'traceability'] as const;
+
+export interface ViewpointBaseline {
+  status: 'absent' | 'new' | 'unchanged' | 'changed';
+  /** sha1 of the normalized file — '' when the unit has no test-viewpoint.md. */
+  hash: string;
+  ids: string[];
+  /** Only on `changed`: how the declaration moved. */
+  added?: string[];
+  removed?: string[];
+  recordedAt?: string;
+}
+
+interface BaselineFile {
+  version: 1;
+  units: Record<string, { hash: string; ids: string[]; recordedAt: string }>;
+}
+
+function baselinePath(projectRoot: string): string {
+  return path.join(projectRoot, '.sungen', 'viewpoint-baseline.json');
+}
+
+function readBaselineFile(projectRoot: string): BaselineFile {
+  const p = baselinePath(projectRoot);
+  if (!fs.existsSync(p)) return { version: 1, units: {} };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(p, 'utf-8')) as BaselineFile;
+    return parsed && typeof parsed === 'object' && parsed.units ? parsed : { version: 1, units: {} };
+  } catch {
+    return { version: 1, units: {} };   // unreadable → treat as unrecorded, never throw
+  }
+}
+
+function writeBaselineFile(projectRoot: string, data: BaselineFile): void {
+  const p = baselinePath(projectRoot);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, `${JSON.stringify(data, null, 2)}\n`, 'utf-8');
+}
+
+/**
+ * Hash the DECLARATION, not the prose: an author reflowing a sentence must not read
+ * as the taxonomy moving. Only the declared viewpoint ids are fingerprinted.
+ */
+function fingerprint(ids: string[]): string {
+  return crypto.createHash('sha1').update(ids.join('\n')).digest('hex').slice(0, 12);
+}
+
+/**
+ * Compare the unit's current test-viewpoint declaration to the recorded baseline.
+ * Read-only — recording is the caller's decision, so an audit stays a measurement
+ * and `--accept-viewpoint` stays the explicit human act. A first sighting reports
+ * `new` (nothing to compare against yet).
+ */
+export function checkViewpointBaseline(
+  projectRoot: string,
+  unitId: string,
+  viewpointPath: string,
+): ViewpointBaseline {
+  if (!fs.existsSync(viewpointPath)) return { status: 'absent', hash: '', ids: [] };
+  const ids = parseViewpointOverview(viewpointPath).map((v) => v.id).sort();
+  const hash = fingerprint(ids);
+  if (ids.length === 0) return { status: 'absent', hash: '', ids: [] };
+
+  const file = readBaselineFile(projectRoot);
+  const recorded = file.units[unitId];
+  if (!recorded) return { status: 'new', hash, ids };
+  if (recorded.hash === hash) return { status: 'unchanged', hash, ids, recordedAt: recorded.recordedAt };
+
+  const before = new Set(recorded.ids ?? []);
+  const now = new Set(ids);
+  return {
+    status: 'changed',
+    hash,
+    ids,
+    added: ids.filter((i) => !before.has(i)),
+    removed: (recorded.ids ?? []).filter((i) => !now.has(i)),
+    recordedAt: recorded.recordedAt,
+  };
+}
+
+/** Record the current declaration as the accepted baseline (`sungen audit --accept-viewpoint`). */
+export function acceptViewpointBaseline(
+  projectRoot: string,
+  unitId: string,
+  current: { hash: string; ids: string[] },
+): void {
+  const file = readBaselineFile(projectRoot);
+  file.units[unitId] = {
+    hash: current.hash,
+    ids: current.ids,
+    recordedAt: new Date().toISOString(),
+  };
+  writeBaselineFile(projectRoot, file);
+}
+
+/** Read the declaration without recording anything (used by `--accept-viewpoint`). */
+export function readViewpointDeclaration(viewpointPath: string): { hash: string; ids: string[] } | null {
+  if (!fs.existsSync(viewpointPath)) return null;
+  const ids = parseViewpointOverview(viewpointPath).map((v) => v.id).sort();
+  if (ids.length === 0) return null;
+  return { hash: fingerprint(ids), ids };
+}

package/src/orchestrator/assets-drift.ts

@@ -0,0 +1,64 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { getPackageVersion } from '../exporters/package-info';
+
+/**
+ * Are this project's AI assets (commands + skills under `.claude/` etc.) the ones
+ * the running sungen would write?
+ *
+ * Upgrading the npm package does NOT refresh them — `sungen update` does. Nothing
+ * said so, so a project kept running prompts from an older build indefinitely: a
+ * QA upgraded, re-ran `/sungen:create-test`, and got the OLD command (141 lines vs
+ * the shipped 267) with none of the newer guidance. The failure is invisible
+ * because everything still "works", just to an older specification.
+ *
+ * The manifest already records the version + a hash per managed file; this only
+ * reads it and reports.
+ */
+export interface AssetsDrift {
+  recordedVersion: string;
+  runningVersion: string;
+  /** Managed files whose content no longer matches the manifest's hash. */
+  changed: number;
+  total: number;
+}
+
+export function checkAssetsDrift(cwd: string): AssetsDrift | null {
+  const manifestPath = path.join(cwd, '.sungen', 'manifest.json');
+  if (!fs.existsSync(manifestPath)) return null;   // not a sungen project (yet)
+
+  let manifest: { version?: string; managed?: Record<string, string> };
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return null;                                    // unreadable → say nothing
+  }
+  const recordedVersion = manifest.version ?? '';
+  const runningVersion = getPackageVersion();
+  const managed = manifest.managed ?? {};
+  const total = Object.keys(managed).length;
+  if (!recordedVersion || total === 0) return null;
+
+  // A version match is the common case — trust it and skip hashing entirely.
+  if (recordedVersion === runningVersion) return null;
+
+  let changed = 0;
+  for (const rel of Object.keys(managed)) {
+    if (!fs.existsSync(path.join(cwd, rel))) changed++;
+  }
+  return { recordedVersion, runningVersion, changed, total };
+}
+
+/** One line, on stderr so `--json` output stays machine-readable. */
+export function warnAssetsDrift(cwd: string): void {
+  const drift = checkAssetsDrift(cwd);
+  if (!drift) return;
+  const gray = '\x1b[90m';
+  const cyan = '\x1b[36m';
+  const reset = '\x1b[0m';
+  process.stderr.write(
+    `${gray}note: this project's AI commands/skills were written by sungen ${drift.recordedVersion}, ` +
+    `you are running ${drift.runningVersion} — run ${cyan}sungen update${reset}${gray} to refresh them ` +
+    `(upgrading the package alone does not).${reset}\n`,
+  );
+}

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

@@ -68,15 +68,6 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the design loop differs — **no visual capture, no selectors**; the contract is the named-endpoint catalog. **Follow the `sungen-api-design` + `sungen-api-coverage-model` skills end-to-end** instead of the screen/flow steps: `sungen context --area <name>` (discover endpoints + `fields:`) → **enumerate the Tier-1 case list per endpoint from the coverage model** (contract + not-found/required-matrix + auth + idempotency, expanded mechanically from `fields:`) → generate `@api`/`@cases`/flow/`@concurrent`/`@query` scenarios with **strict assertions** (prove the effect, never status-only) → **`sungen audit --area <name>` gate + reviewer + repair loop to businessDepth ≥ 0.7** → record + trace. Then recommend `/sungen-run-test <name>`. The capture / viewpoint-group / selector steps do **not** apply.
 {{/cap}}
 
-## Requirement traceability (before you finish)
-
-Cross-check `requirements/spec.md` against the scenarios you wrote: every `FR-`/`TR-`/`NFR-` id
-must either carry a `@spec:<id>` tag on the scenario that proves it, or be a conscious
-out-of-scope decision you state in the summary. `sungen audit` reports `SPEC-TRACE-IMPLICIT` for
-requirements it could only match by keyword — treat that list as a to-do: add the tag to the
-proving scenario, do not leave the link to inference. Delivery's requirement table follows the
-tag only, so an untagged requirement is later reported as an uncovered gap.
-
 ## Steps
 
 {{#cap parallel-subagents}}
@@ -124,12 +115,16 @@ tag only, so an untagged requirement is later reported as an uncovered gap.
      - **Fill test-viewpoint.md first** — I'll help you identify edge cases, known issues, and design decisions for this screen before generating tests
      - **Continue without it** — generate tests from spec and other sources only
 
+   **A filled `test-viewpoint.md` is an INPUT — never an output.** Do NOT rewrite, re-order, or replace its viewpoint declarations as part of generating tests. It is the yardstick two scored axes measure the suite against (`traceability`, `atomicLedger`): rewrite it to match what you just generated and both read 100% by construction, while any viewpoint you quietly dropped stops being missing from anything. If the declared taxonomy genuinely does not fit the screen, **report the mismatch and ask** — propose the diff (ids added / removed and why) and let the QA decide. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and stops scoring both axes when this file moves, so an unannounced rewrite lowers the score rather than raising it.
+
    **Context discovery (prefer an isolated agent).** Reading all sources here can flood this context. **Claude Code:** spawn the **`sungen-discovery`** sub-agent (Task tool, `subagent_type: sungen-discovery`) to read spec/figma/ui/live in isolation and return a **compact discovery report** (sources, completeness, conflicts, recommended route, key facts); use that report instead of pasting raw sources. **Copilot / no sub-agents:** do the reading inline as below.
 {{/cap}}
 {{^cap parallel-subagents}}
    - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), ask:
      - **1) Fill test-viewpoint.md first** — identify edge cases, known issues, and design decisions before generating tests
      - **2) Continue without it** — generate tests from spec and other sources only
+
+   **A filled `test-viewpoint.md` is an INPUT — never an output.** Do NOT rewrite, re-order, or replace its viewpoint declarations while generating tests. It is the yardstick two scored axes measure the suite against (`traceability`, `atomicLedger`): rewrite it to match what you just generated and both read 100% by construction, while any viewpoint you quietly dropped stops being missing from anything. If the declared taxonomy genuinely does not fit the screen, **report the mismatch and ask** — propose the diff (ids added / removed and why) and let the QA decide. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and stops scoring both axes when this file moves.
 {{/cap}}
 
    **Auto-detect visual source** — do NOT ask the user to pick a source. Instead, check what already exists and use it:
@@ -265,3 +260,23 @@ tag only, so an untagged requirement is later reported as an uncovered gap.
 {{^cap parallel-subagents}}
 **No selectors.yaml** — selectors are generated during `/sungen-run-test`.
 {{/cap}}
+
+## Finish — always hand the next step back
+
+Do not stop after writing the files. Close every run with, in this order:
+
+1. **The traceability check below** — an untagged requirement becomes an uncovered gap at delivery.
+2. **The harness result in one line** — score, gate verdict, and the axis the `SCORE-CAPPED` finding
+   names (that finding is the single answer to "how do I raise the score").
+3. **`AskUserQuestion` with the next actions** — never end with prose alone. Offer
+   `/sungen:run-test <name>` (recommended once the tiers are written), re-running `create-test` to
+   extend, and "Done for now". A run that ends without this leaves the operator guessing.
+
+### Requirement traceability
+
+Cross-check `requirements/spec.md` against the scenarios you wrote: every `FR-`/`TR-`/`NFR-` id
+must either carry a `@spec:<id>` tag on the scenario that proves it, or be a conscious
+out-of-scope decision you state in the summary. `sungen audit` reports `SPEC-TRACE-IMPLICIT` for
+requirements it could only match by keyword — treat that list as a to-do: add the tag to the
+proving scenario, do not leave the link to inference. Delivery's requirement table follows the
+tag only, so an untagged requirement is later reported as an uncovered gap.

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

@@ -340,6 +340,7 @@ 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.
+   - **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.
    - **Negative / absence claims** (`does not` / `no` / `never` / `prevents` / `không` / `chưa` — any language; `no-side-effect/no-duplicate`, `negative-claim/absence`): the `Then` must **differ** between the claim holding and not holding. A terminal `see [X] page` that looks identical whether or not the bad thing happened proves nothing. For a side-effect that should NOT repeat (re-submit on back, re-charge, duplicate order, resend OTP), assert the **count is unchanged** (`User see [Records] table with {{one}}` / `row with {{count}}`); if it's not UI-observable, mark `@manual` with a request-count oracle (shape below). This is general — it covers any side-effect, not a fixed verb list.