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

package/src/harness/provenance.ts

@@ -1,22 +1,110 @@
 /**
- * Provenance stamp for deterministic reports (score-determinism D1).
+ * Provenance stamp for deterministic reports (score-determinism D1), and the RULES the audit's
+ * verdict was judged by (#933, owner decision W4).
  *
- * The audit score is a pure function of the project files + the bundled catalog.
- * Stamping the sungen version + a catalog hash into the report lets two users who
- * get different scores see IMMEDIATELY whether the cause is a version/catalog
- * mismatch (the main residual source of cross-user variance) rather than a real
- * difference in their test design.
+ * The audit score is a pure function of the project files + the bundled catalogs + the scoring
+ * code. Stamping them into the report lets two users who get different scores see IMMEDIATELY
+ * whether the cause is a rules mismatch rather than a real difference in their test design — and
+ * lets `verifyAuditReport` tell a report judged by today's rules from one judged by other rules:
+ *
+ *   sungenVersion   which package wrote it — informational: a newer sungen with the same rules
+ *                   gives the same verdict, so the version alone never makes a report stale
+ *   catalogHash     sha256(universal-viewpoints.yaml), first 12 hex — the viewpoint catalog
+ *   rulesHash       sha256(AUDIT_RULES_VERSION + every catalog file under harness/catalog/ + each
+ *                   bundled driver's sources/catalogs), first 12 hex — everything the verdict
+ *                   depends on that is not the project's own files. No package VERSION is hashed:
+ *                   packages are lockstep-versioned, so a release would stale every report
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
 
+/**
+ * The version of the audit's SCORING CODE. Bump it (by one) in the same change whenever what
+ * `runAudit` computes for the same project can change: a sensor, a threshold, a gate term
+ * (audit-gate-terms.ts), the score model or weights, a finding that feeds the verdict, or the
+ * audit sensor of a bundled driver. Every report scored before the bump then reads stale and asks
+ * for one `sungen audit`. Catalog edits (harness/catalog/*.yaml) and bundled-driver changes (their
+ * sources and catalogs are hashed) need no bump.
+ * A release that changes none of these keeps every report trusted across the upgrade.
+ * Enforced by tests/audit/run.ts: its rules lock (tests/audit/audit-rules.lock.json) fails when the
+ * fixtures' audit output changes under an unchanged rules hash. After the bump, re-record it:
+ *   npx tsx tests/audit/run.ts --record-rules-lock
+ */
+export const AUDIT_RULES_VERSION = 1;
+
 export interface Provenance {
   sungenVersion: string;
   catalogHash: string; // sha256(universal-viewpoints.yaml), first 12 hex — the catalog that drives the score
+  rulesHash: string;   // sha256(AUDIT_RULES_VERSION + harness/catalog/*.yaml + bundled drivers), first 12 hex — the verdict's rules
+}
+
+/** A bundled driver as an input of the rules: its package dir, or null when it is not installed. */
+export interface DriverRulesInput { name: string; version?: string; dir: string | null }
+
+/** What is not a driver's rule: dependencies, build output, tests, docs, editor and lock files. */
+const SKIP_DIR = new Set(['node_modules', 'dist', 'tests', 'test', 'coverage']);
+const SKIP_FILE = /^(?:\.|package(?:-lock)?\.json$|tsconfig.*\.json$|.*\.(?:md|tsbuildinfo)$)/;
+
+function driverFiles(root: string, rel = ''): string[] {
+  const out: string[] = [];
+  for (const e of fs.readdirSync(path.join(root, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name, 'en'))) {
+    if (e.name.startsWith('.')) continue;
+    const r = rel ? `${rel}/${e.name}` : e.name;
+    if (e.isDirectory()) { if (!SKIP_DIR.has(e.name)) out.push(...driverFiles(root, r)); }
+    else if (e.isFile() && !SKIP_FILE.test(e.name)) out.push(r);
+  }
+  return out;
+}
+
+/** The package root above a driver's resolved entry file (the dir whose package.json names it). */
+function packageRootOf(entry: string, name: string): string | null {
+  let dir = path.dirname(entry);
+  for (let i = 0; i < 8; i++) {
+    try { if (JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'))?.name === name) return dir; } catch { /* keep walking */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
 }
 
+/** Each bundled driver as discovery would load it (project anchor, then core's), or `absent`. */
+export function bundledDriverRulesInputs(): DriverRulesInput[] {
+  // Lazy: discovery pulls the capability registry, which nothing else here needs.
+  const { bundledDriverNames, resolveDriverCopy } = require('../capabilities/discover') as typeof import('../capabilities/discover');
+  return bundledDriverNames().map((name) => {
+    const copy = resolveDriverCopy(name);
+    const dir = copy ? packageRootOf(copy.resolved, name) : null;
+    return { name, version: copy?.version, dir };
+  });
+}
+
+const CATALOG_DIR = path.join(__dirname, 'catalog');
+const sha12 = (s: string | Buffer): string => crypto.createHash('sha256').update(s).digest('hex').slice(0, 12);
+
+/**
+ * The rules hash: the scoring version, every *.yaml of the catalog dir (by name), and each bundled
+ * driver — every source / catalog file of its package (by relative path; build output, tests and
+ * dependencies excluded), or a stable `absent` marker when it is not installed. A driver's version is
+ * deliberately left out: releases bump every package in lockstep, and only content changes the rules.
+ */
+export function rulesHashOf(rulesVersion: number, catalogDir: string = CATALOG_DIR, drivers: DriverRulesInput[] = bundledDriverRulesInputs()): string {
+  const files = fs.readdirSync(catalogDir).filter((f) => f.endsWith('.yaml')).sort();
+  const h = crypto.createHash('sha256').update(`audit-rules:${rulesVersion}\n`);
+  for (const f of files) h.update(`${f}\n`).update(fs.readFileSync(path.join(catalogDir, f))).update('\n');
+  for (const d of [...drivers].sort((a, b) => a.name.localeCompare(b.name, 'en'))) {
+    h.update(`driver:${d.name}\n`);
+    if (!d.dir) { h.update('absent\n'); continue; }
+    for (const f of driverFiles(d.dir)) h.update(`${f}\n`).update(fs.readFileSync(path.join(d.dir, f))).update('\n');
+  }
+  return h.digest('hex').slice(0, 12);
+}
+
+let cached: Provenance | null = null;
+
 export function getProvenance(): Provenance {
+  if (cached) return cached;
   let sungenVersion = 'unknown';
   try {
     const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf-8'));
@@ -24,10 +112,10 @@ export function getProvenance(): Provenance {
   } catch { /* version stays 'unknown' */ }
 
   let catalogHash = 'unknown';
-  try {
-    const cat = fs.readFileSync(path.join(__dirname, 'catalog', 'universal-viewpoints.yaml'), 'utf-8');
-    catalogHash = crypto.createHash('sha256').update(cat).digest('hex').slice(0, 12);
-  } catch { /* hash stays 'unknown' */ }
+  try { catalogHash = sha12(fs.readFileSync(path.join(CATALOG_DIR, 'universal-viewpoints.yaml'), 'utf-8')); } catch { /* hash stays 'unknown' */ }
+  let rulesHash = 'unknown';
+  try { rulesHash = rulesHashOf(AUDIT_RULES_VERSION); } catch { /* hash stays 'unknown' */ }
 
-  return { sungenVersion, catalogHash };
+  cached = { sungenVersion, catalogHash, rulesHash };
+  return cached;
 }

package/src/harness/script-check.ts

@@ -18,6 +18,8 @@ import * as os from 'os';
 import { loadUnitScenarios, ScenarioInfo } from './parse';
 import { featureFilesFor } from './unit-paths';
 import { readTextFile } from './read-text';
+import { CATALOG_GATE_RULES } from './gates/resolve-rule';
+import { evaluateGateTerms } from './gates/gate-terms';
 
 export interface ScriptCheckResult {
   screen: string;
@@ -340,7 +342,8 @@ function findSpecs(dir: string, name: string, kind: UnitKind): string[] {
 export async function runScriptCheck(screenDir: string, screenName: string, kind: UnitKind): Promise<ScriptCheckResult> {
   const featureFiles = featureFilesFor(screenDir, screenName);
   const scenarios = loadUnitScenarios(screenDir, screenName);
-  const automated = scenarios.filter((s) => !s.manual);
+  // Hand-written (@free / @impl:code) scenarios are proven by their traces, not compiled — no twin expected.
+  const automated = scenarios.filter((s) => !s.manual && !s.handWritten);
   const manual = scenarios.filter((s) => s.manual);
 
   const committedSpecs = findSpecs(path.join(process.cwd(), 'specs', 'generated'), screenName, kind);
@@ -388,9 +391,10 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
   // failed regenerate degrades check C to its heuristic instead of crashing it.
   let stepTrace: Map<string, string[]> | undefined;
   if (committedSpec) {
+    let tmp: string | undefined;
     try {
       const { CodeGenerator } = require('../generators/test-generator/code-generator');
-      const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sungen-scriptcheck-'));
+      tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sungen-scriptcheck-'));
       const qaSourceDir = path.join(process.cwd(), 'qa', kind === 'flow' ? 'flows' : kind === 'api' ? 'api' : 'screens');
       // api units derive their unit id (api/<area>) from the feature path — like `generate --api`;
       // screen/flow pass screenName + flowMode explicitly (unchanged → byte-identical regenerate).
@@ -428,9 +432,11 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
       if (drift === 'drift') {
         findings.push('DRIFT: committed spec differs from a fresh regenerate → spec was hand-edited or the .feature changed without `sungen generate`. The test code no longer reflects the Gherkin.');
       }
-      fs.rmSync(tmp, { recursive: true, force: true });
     } catch (e) {
       findings.push(`Drift check skipped (regenerate failed): ${e instanceof Error ? e.message : e}`);
+    } finally {
+      // Removed on every path: a throwing regenerate used to leave one sungen-scriptcheck-* dir per call.
+      if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
     }
   }
 
@@ -446,7 +452,16 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
   }
   const bypass = assertionlessTests.length > 0 || hollowSteps.length > 0;
 
-  const ok = !!committedSpec && countMatch && missingInSpec.length === 0 && extraInSpec.length === 0 && drift === 'in-sync' && !bypass;
+  // Every term is a hard rule (the #387 drift family): no gate-override can lower one, so the
+  // catalog alone decides (OES-11.3).
+  const faithful = evaluateGateTerms([
+    { rule: 'script.no-spec', holds: !!committedSpec },
+    { rule: 'script.count-mismatch', holds: countMatch },
+    { rule: 'script.missing-in-spec', holds: missingInSpec.length === 0 },
+    { rule: 'script.extra-in-spec', holds: extraInSpec.length === 0 },
+    { rule: 'script.drift', holds: drift === 'in-sync' },
+    { rule: 'script.bypass', holds: !bypass },
+  ], CATALOG_GATE_RULES);
 
   return {
     screen: screenName,
@@ -462,7 +477,7 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
     assertionlessTests,
     hollowSteps,
     bypass,
-    status: ok ? 'OK' : 'FAIL',
+    status: faithful.pass ? 'OK' : 'FAIL',
     findings,
   };
 }

package/src/harness/sensors.ts

@@ -13,6 +13,8 @@ import { ScenarioInfo, ViewpointEntry, idPrefix } from './parse';
 import { readTextFile } from './read-text';
 import { keywordHit, hasKeyword } from './keyword-match';
 import { countedAssertions } from './counted-assertions';
+import { CATALOG_GATE_RULES, GateRules } from './gates/resolve-rule';
+import { ruleVerdict, sensorSeverityOf } from './gates/gate-terms';
 
 // Business-critical category keywords (matched by CONTAINMENT against the VP category, so a
 // compound category like LIST-DISPLAY / ADD-TO-CART / PRODUCT-DISCOVERY classifies correctly).
@@ -276,6 +278,8 @@ export function assertionDepth(
   scenarios: ScenarioInfo[],
   dataThemes: CatalogTheme[] = [],
   focus = 'functional',
+  /** The unit's gate rules; the catalog alone (today's levels) by default. */
+  rules: GateRules = CATALOG_GATE_RULES,
 ): DepthResult {
   const nonManual = scenarios.filter((s) => !s.manual);
   const shallow = nonManual.filter((s) => s.shallow);
@@ -299,8 +303,7 @@ export function assertionDepth(
   const ratio = required.length ? 1 - reqShallow.length / required.length : 1;
 
   const threshold = DEPTH_THRESHOLDS[focus] ?? DEPTH_THRESHOLDS.functional;
-  let verdict: DepthVerdict = 'pass';
-  if (ratio < threshold) verdict = WARN_ONLY_FOCUS.has(focus) ? 'warn' : 'fail';
+  const verdict = ruleVerdict(rules, 'audit.assertion-depth', ratio < threshold, WARN_ONLY_FOCUS.has(focus));
 
   return {
     total: nonManual.length,
@@ -711,7 +714,10 @@ export interface ClaimUnproven {
   claim: string;       // the claim keyword matched in the title
   need: string;        // the assertion shape the steps must contain
   hint: string;        // how to fix
-  severity: 'fail' | 'warn';
+  /** Resolved from the row's catalog rule (fail = blocks when under the ratio; info only via an override). */
+  severity: 'fail' | 'warn' | 'info';
+  /** The gate rule that decided `severity` (`claim.*`, or `claim.partial-proof`). */
+  rule: string;
 }
 
 export interface ClaimProofResult {
@@ -726,16 +732,17 @@ export interface ClaimProofResult {
 }
 
 interface ClaimRule {
+  /** The catalog rule (`claim.*`) whose resolved severity a missing proof gets (OES-11.2). */
+  rule: string;
   claim: string;
   title: RegExp;        // claim keyword(s) in the title
   proof: RegExp;        // required assertion shape in the steps
   need: string;
   hint: string;
-  severity: 'fail' | 'warn';
   // Optional: even when `proof` matches, if `underproof` also matches the proof is
-  // PARTIAL (the right shape exists but on the wrong/another element) → a warn-level
-  // finding. e.g. an "each card exposes <action>" claim that has a see-all on price
-  // but asserts the actions with singular presence.
+  // PARTIAL (the right shape exists but on the wrong/another element) → a finding at the
+  // `claim.partial-proof` rule's level. e.g. an "each card exposes <action>" claim that has
+  // a see-all on price but asserts the actions with singular presence.
   underproof?: RegExp;
   underNeed?: string;
   underHint?: string;
@@ -749,29 +756,30 @@ const CLAIM_RULES: ClaimRule[] = [
     // catch, so proving it with a substring proves the opposite of what the title says. Found on
     // a real basic flow whose seven confirmation rows all used `contains` while claiming the six
     // values "survive unchanged" (#599).
+    rule: 'claim.unchanged-preserved',
     claim: 'unchanged/preserved',
     title: /\b(unchanged|unmodified|un-?edited|identical|preserved|intact|verbatim|as entered|without (?:any )?(?:change|modification))\b/,
     proof: /^(?![\s\S]*\bcontains \{\{)/,
     need: 'exact-value assertions (`see [X] text with {{v}}` / `field with {{v}}`) for the values the title says are unchanged',
     hint: 'swap `contains {{v}}` for `with {{v}}` on the continuity rows. A substring match cannot distinguish "unchanged" from "changed by adding a prefix" — and if the screen genuinely renders extra text around the value, say so in the title instead of claiming exactness.',
-    severity: 'warn',
   },
   {
     // An ORDER claim ("sorted by date descending", "ties broken by last-updated") is invisible to
     // a presence check: `see [List] table` passes whatever order the rows are in. It sits ahead of
     // the generic rules so "all results sorted …" is judged as an ordering claim, not an all-claim.
     // A tiebreaker is a Tier-1 guard in the tc-generation skill, yet no rule recognised it (#810).
+    rule: 'claim.ordering-sort',
     claim: 'ordering/sort',
     title: /\b(ascending|descending|sorted|sorts|sort order|ordered by|order by|in (?:chronological|alphabetical|reverse|numeric) order|(?:newest|oldest|latest|earliest|highest|lowest) first|tie-?break(?:s|er|ers)?|ties?)\b|降順|昇順|並び順|giảm dần|tăng dần|sắp xếp/,
     proof: /match data|is sorted|sorted (?:ascending|descending)|\brow \d+\b|\.first\.|\.last\.|\[\d+\]\.|order by/,
     need: 'an order-sensitive assertion (`table match data:` rows in the expected order, `is sorted ascending|descending`, or positional `row N` checks)',
     hint: 'a presence check passes in any order — assert the rows in their expected sequence (`User see [T] table match data:`), or the column sort state; a tiebreak needs two rows sharing the primary key.',
-    severity: 'fail',
   },
   {
     // A LIMIT claim ("never exceeds 10", "at most 5 files") is a count claim in disguise.
     // Ahead of 'no-side-effect', whose negation+effect pattern would otherwise swallow
     // "never exceeds 10 records" and ask for a duplicate-count proof.
+    rule: 'claim.limit-cap',
     claim: 'limit/cap',
     // The quantity must be ≥2 ("at most ONE order" is a no-duplicate claim — left to the rules
     // below) and not a duration ("up to 30 seconds" is a timing claim, not a cap).
@@ -779,51 +787,50 @@ const CLAIM_RULES: ClaimRule[] = [
     proof: /\bcount\b|tohavecount|table with|row with \{\{|match data|is at most|\bexactly\b|field with \{\{|\berror\b|invalid|is disabled/,
     need: 'a count/boundary assertion (count is N, `is at most`, the N+1th input rejected or truncated)',
     hint: 'assert the boundary itself — the count at the cap, or the value/error when one more is attempted — not just that the list or field is present.',
-    severity: 'fail',
   },
   {
+    rule: 'claim.all-every-each',
     claim: 'all/every/each',
     title: /\b(all|every|each)\b/,
     proof: /\bsee all\b/,
     need: 'a `User see all …` assertion (every element, not one)',
     hint: 'assert across all matched elements — for per-card structure use the all-card DSL (roadmap Q2).',
-    severity: 'fail',
     // singular action presence under an "each/every" claim = partial proof
     underproof: /\bsee \[[^\]]+\] (link|button)\b/,
     underNeed: 'an all-card assertion for the claimed action (not single presence)',
     underHint: 'the actions are asserted once, not per-card — wrap them with the all-card DSL `User see all [Card] contain [Action]` (roadmap Q2).',
   },
   {
+    rule: 'claim.only-belong-to',
     claim: 'only/belong-to',
     title: /\b(only|belongs? to|exclusively)\b/,
     proof: /\bsee all\b[^.]*\bcontain/,
     need: 'all-match (`User see all … contains …`)',
     hint: 'all displayed items must match the facet; "no items OUTSIDE" is UI-limited → verify via hybrid API/DB or mark @manual with reason.',
-    severity: 'warn',
   },
   {
+    rule: 'claim.single-exactly-one',
     claim: 'single/exactly-one',
     title: /\b(a single|single|exactly one|just one|only one)\b/,
     proof: /\bcount\b|\btable with\b|\bexactly\b|tohavecount/,
     need: 'a count assertion (e.g. count is 1)',
     hint: 'assert the quantity, not just presence.',
-    severity: 'fail',
   },
   {
+    rule: 'claim.correct-matching-identity',
     claim: 'correct/matching/identity',
     title: /\b(correct|matching|the same|same (product|name|price|value|item)|consistency|identity|lands? in|is the (product|item))\b/,
     proof: /\bremember\b/,
     need: 'capture + compare (`User remember … as {{v}}` then assert {{v}})',
     hint: 'remember the value on the source, then assert it on the target (cross-screen → defer to a flow as @manual).',
-    severity: 'fail',
   },
   {
+    rule: 'claim.changes-toggles',
     claim: 'changes/toggles',
     title: /\b(changes?|toggles?|updates?|reflects?|reopens?)\b/,
     proof: /\bremember\b|\bis hidden\b/,
     need: 'a state delta (before ≠ after, or a visible→hidden contrast)',
     hint: 'capture the before-state and assert the after-state differs, or assert the visible/hidden transition.',
-    severity: 'warn',
   },
   {
     // GENERAL — mutation-absence. A title asserts that a STATE-CHANGING action does NOT
@@ -834,6 +841,7 @@ const CLAIM_RULES: ClaimRule[] = [
     // count/contrast (record count unchanged) or defer to @manual. This is the general
     // 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.
+    rule: 'claim.no-side-effect',
     claim: 'no-side-effect/no-duplicate',
     // 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
@@ -851,33 +859,33 @@ const CLAIM_RULES: ClaimRule[] = [
     proof: /\bcount\b|ok_count|status_counts|row with \{\{|table with|tohavecount|is hidden|are hidden|is disabled|are disabled|not complete|no longer/,
     need: 'a record/request-count proof (count stays at one, e.g. `User see [Table] row with {{count}}`, an API `{{name.ok_count}}` invariant, or a `@query` DB count) or @manual with a request-count oracle',
     hint: 'a "does-not-happen / does-not-repeat" claim about a state-changing action is NOT proven by a terminal `see [...] page` — that page is identical whether or not the action (re-)fired. Prove the side-effect count is unchanged, or mark @manual with a setup→action→assert-no-duplicate oracle.',
-    severity: 'fail',
   },
   {
+    rule: 'claim.hidden-rejected',
     claim: 'hidden/rejected/not-complete',
     title: /\b(hidden|closed|dismiss(es|ed)?|not complete|rejected|inert)\b/,
     proof: /\bis hidden\b|\bare hidden\b|message is hidden|not complete|\bhidden\b/,
     need: 'a negative / hidden assertion (`… is hidden`)',
     hint: 'assert the absence/hidden state that the title claims, not just an unrelated visible element.',
-    severity: 'fail',
   },
   {
+    rule: 'claim.cleared-emptied',
     claim: 'cleared/emptied',
     title: /\b(cleared|clears|emptied|empties|reset to empty|wiped)\b/,
     proof: /\bis empty\b|with \{\{empty|with ['"]?['"]?\s*$|\bempty\b/,
     need: 'an empty/cleared assertion after the action (e.g. `field with {{empty_value}}` / `is empty`)',
     hint: 'prove the value is actually gone — return to the screen and assert the field is empty, not just that the action ran.',
-    severity: 'fail',
   },
   {
+    rule: 'claim.restored-preserved',
     claim: 'restored/preserved',
     title: /\b(restored|preserved|persists?|retained|remembered|kept)\b/,
     proof: /\bremember\b|with \{\{|field with/,
     need: 'the value re-asserted after the transition (capture or `field with {{v}}` after returning)',
     hint: 'prove the value survives — assert the field still holds the typed value after the reload/return, not just that it was typed.',
-    severity: 'warn',
   },
   {
+    rule: 'claim.independent-separate',
     claim: 'independent/separate',
     title: /\b(independent|separate|isolat(ed|es)|per[- ]tab|two tabs|each tab)\b/,
     // A storage `does not exist` check on the OTHER tenant's key proves isolation
@@ -886,23 +894,22 @@ const CLAIM_RULES: ClaimRule[] = [
     proof: /\bcontext\b|tab a|tab b|second (tab|context)|does not exist/,
     need: 'a multi-context proof (tab A vs tab B)',
     hint: 'independence across tabs/contexts is rarely DSL-expressible — mark @manual with a clear setup/action/oracle.',
-    severity: 'warn',
   },
   {
+    rule: 'claim.sanitized-inert',
     claim: 'sanitized/inert',
     title: /\b(sanitized|sanitised|escaped|inert|not executed|not rendered|stripped)\b/,
     proof: /field with \{\{|payload|inert|toContainText|is hidden/,
     need: 'the payload echoed as inert text (`field with {{payload}}`) + no execution',
     hint: 'prove the payload round-trips as literal text and triggers nothing — assert the field value and the absence of any effect.',
-    severity: 'warn',
   },
   {
+    rule: 'claim.announces-aria',
     claim: 'announces/aria',
     title: /\b(announce[sd]?|aria|screen[- ]reader|programmatically associated)\b/,
     proof: /aria|role|@manual|describedby|is focused|tab order/,
     need: 'an aria/role assertion (or @manual with a screen-reader oracle)',
     hint: 'ARIA announcement is usually not DSL-expressible — assert aria attributes if possible, else @manual with an NVDA/VoiceOver oracle.',
-    severity: 'warn',
   },
   {
     // GENERAL CATCH-ALL (last) — any negative/absence title not handled by a specific
@@ -912,6 +919,7 @@ const CLAIM_RULES: ClaimRule[] = [
     // only a positive presence. WARN, because a positive proxy is sometimes a valid
     // negative proof (e.g. "stayed on the login page"); the semantic reviewer is the
     // authoritative recall layer for the residue this can't judge structurally.
+    rule: 'claim.negative-absence',
     claim: 'negative-claim/absence',
     title: /(\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,
     // `does not exist` covers the storage-absence shape — the broad "any storage
@@ -921,7 +929,6 @@ const CLAIM_RULES: ClaimRule[] = [
     proof: /is hidden|are hidden|is empty|no longer|not complete|disabl|invalid|rejected|\berror\b|\bcount\b|row with \{\{|table with|\bremember\b|\bexactly\b|tohavecount|does not exist|tab order/i,
     need: 'a proof of the ABSENCE — a contrast/empty/hidden/error/count assertion, or @manual with an oracle',
     hint: 'a negative claim ("no / not / không …") is not proven by a positive `see [X]` that looks the same whether or not the claim holds. Assert the contrast (state hidden/empty, error shown, count unchanged), or mark @manual.',
-    severity: 'warn',
   },
 ];
 
@@ -1014,7 +1021,12 @@ export function taxonomyLint(scenarios: ScenarioInfo[]): TaxonomyResult {
   return { total: scenarios.length, checked, mislabeled };
 }
 
-export function claimProof(scenarios: ScenarioInfo[], focus = 'functional'): ClaimProofResult {
+/**
+ * `rules` resolves each row's catalog rule for the unit being audited (the catalog alone by default —
+ * today's levels). A rule switched `off` by a gate-override is not measured: its unproven claim is
+ * neither counted nor reported (a partial-proof switched off leaves the claim proven).
+ */
+export function claimProof(scenarios: ScenarioInfo[], focus = 'functional', rules: GateRules = CATALOG_GATE_RULES): ClaimProofResult {
   const measured = scenarios.filter((s) => !s.manual);
   const unproven: ClaimUnproven[] = [];
   let withClaims = 0;
@@ -1023,19 +1035,17 @@ export function claimProof(scenarios: ScenarioInfo[], focus = 'functional'): Cla
     const title = s.name.toLowerCase();
     const rule = CLAIM_RULES.find((r) => r.title.test(title));
     if (!rule) continue;          // no claim → not measured
+    const miss = !rule.proof.test(s.stepsText)
+      // proof shape entirely absent → the claim's own rule decides the level
+      ? { rule: rule.rule, need: rule.need, hint: rule.hint }
+      : rule.underproof && rule.underproof.test(s.stepsText)
+        // right shape exists but only as a partial proof
+        ? { rule: 'claim.partial-proof', need: rule.underNeed ?? rule.need, hint: rule.underHint ?? rule.hint }
+        : null;
+    const severity = miss ? sensorSeverityOf(rules.resolve(miss.rule)) : undefined;
+    if (miss && severity === null && miss.rule === rule.rule) continue;   // the claim's rule is off for this unit
     withClaims++;
-    if (!rule.proof.test(s.stepsText)) {
-      // proof shape entirely absent → fail at the rule's severity
-      unproven.push({ name: s.name, claim: rule.claim, need: rule.need, hint: rule.hint, severity: rule.severity });
-    } else if (rule.underproof && rule.underproof.test(s.stepsText)) {
-      // right shape exists but only as a partial proof → warn
-      unproven.push({
-        name: s.name, claim: rule.claim,
-        need: rule.underNeed ?? rule.need,
-        hint: rule.underHint ?? rule.hint,
-        severity: 'warn',
-      });
-    }
+    if (miss && severity) unproven.push({ name: s.name, claim: rule.claim, need: miss.need, hint: miss.hint, severity, rule: miss.rule });
   }
 
   const proven = withClaims - unproven.length;
@@ -1043,10 +1053,7 @@ export function claimProof(scenarios: ScenarioInfo[], focus = 'functional'): Cla
   const threshold = DEPTH_THRESHOLDS[focus] ?? DEPTH_THRESHOLDS.functional;
 
   const hasFail = unproven.some((u) => u.severity === 'fail');
-  let verdict: DepthVerdict = 'pass';
-  if (ratio < threshold) {
-    verdict = WARN_ONLY_FOCUS.has(focus) || !hasFail ? 'warn' : 'fail';
-  }
+  const verdict = ruleVerdict(rules, 'audit.claim-proof', ratio < threshold, WARN_ONLY_FOCUS.has(focus) || !hasFail);
 
   return { total: measured.length, withClaims, proven, unproven, ratio, focus, threshold, verdict };
 }

package/src/harness/triage-manual-classification.ts

@@ -0,0 +1,76 @@
+/**
+ * `sungen triage --screen <u> --case <id> --as product|test-defect|environment --reason "…"` (#928):
+ * classify one red by hand — the one `sungen triage` left unclassified, or one it got wrong — as a
+ * `triage-classification` decision in the unit's `decisions/` (read back by graph/manual-triage-decisions.ts).
+ *
+ *   validated first   the class, a reason, a case that exists, is red and is not exempt — before any
+ *                     prompt, so a human never confirms something that is then rejected
+ *   product           stricter than any automatic class (it leads to a QA decision): anyone may record it
+ *   test-defect,      can hide a product defect behind "fix the test" / "re-run": a human types a
+ *   environment       confirmation on a terminal (DOS-13.4); without one it is refused, nothing is
+ *                     written and the exact command is printed. Only after the typed phrase does the
+ *                     entry carry `humanConfirmed: true`, and a reader ignores one without it
+ *   bound             evidence_hash = the case's red as it reads now; a re-run voids the classification
+ */
+import type { AppendResult } from '../decisions/append-decision';
+import { appendDecision } from '../decisions/append-decision';
+import type { DecisionDraft } from '../decisions/decision-schema';
+import { gitUserName } from '../decisions/decision-source';
+import { ConfirmationIO, formatCommand, requireTypedConfirmation } from '../decisions/human-confirmation';
+import { resolveUnitCandidates } from '../cli/resolve-unit';
+import { HUMAN_ONLY_TRIAGE, MANUAL_TRIAGE_AS, ManualTriageClass, TRIAGE_DECISION_KIND } from '../graph/manual-triage-decisions';
+import { exemptionOf } from '../graph/test-case-satisfied';
+import { testCaseStates } from '../graph/test-case-states';
+import { unitScopeOfDir } from './gates/unit-gate-overrides';
+
+export interface ClassifyRedCaseInput {
+  projectRoot: string;
+  unit: string;
+  caseId: string;
+  /** product | test-defect | environment */
+  as: string;
+  reason?: string;
+  io: ConfirmationIO;
+}
+
+export interface ClassifyRedCaseResult extends AppendResult { caseId: string; class: ManualTriageClass }
+
+export async function classifyRedCase(i: ClassifyRedCaseInput): Promise<ClassifyRedCaseResult> {
+  const cls = Object.prototype.hasOwnProperty.call(MANUAL_TRIAGE_AS, i.as) ? MANUAL_TRIAGE_AS[i.as] : undefined;
+  if (!cls) throw new Error(`--as must be one of ${Object.keys(MANUAL_TRIAGE_AS).join(', ')} (got "${i.as}")`);
+  const reason = (i.reason ?? '').trim();
+  if (!reason) throw new Error('--reason is required: a classification records WHY this red is what you say it is');
+  const found = resolveUnitCandidates(i.unit, i.projectRoot);
+  if (found.length !== 1) throw new Error(`"${i.unit}" does not name exactly one unit under qa/screens, qa/flows or qa/api`);
+  const unitDir = found[0].dir;
+  const scope = unitScopeOfDir(i.projectRoot, unitDir);
+  if (!scope) throw new Error(`"${i.unit}" has no decisions scope`);
+  const cases = testCaseStates(i.projectRoot, i.unit, { unitDir, auditFindings: [] });
+  const tc = cases.find((c) => c.id === i.caseId);
+  if (!tc) {
+    const known = cases.slice(0, 8).map((c) => c.id).join(', ');
+    throw new Error(`no test case "${i.caseId}" in ${i.unit}${known ? ` — known: ${known}${cases.length > 8 ? ', …' : ''}` : ''}`);
+  }
+  if (tc.result !== 'failed' || !tc.evidence) throw new Error(`${tc.id} has no red result to classify (result: ${tc.result})`);
+  const exempt = exemptionOf(tc);
+  if (exempt) throw new Error(`${tc.id} is exempt (${exempt}) — it needs no classification`);
+
+  const human = HUMAN_ONLY_TRIAGE.has(cls);
+  if (human) {
+    await requireTypedConfirmation({
+      what: `classify the red ${tc.id} of ${i.unit} as ${cls}`,
+      phrase: tc.id,
+      command: formatCommand(['sungen', 'triage', found[0].kind === 'api' ? '--api' : '--screen', i.unit, '--case', tc.id, '--as', i.as, '--reason', reason]),
+      summary: [`case: ${tc.title}`, `automatic triage: ${tc.triage ? `${tc.triage.class} (${tc.triage.ruleId})` : 'none current'}`, `reason: ${reason}`,
+        `recorded by: ${gitUserName(i.projectRoot)}`, `as ${cls} it leaves the product-defect path — confirm only after reading its evidence (trace, error)`,
+        'it stops counting as soon as the case runs again'],
+      io: i.io,
+    });
+  }
+  const draft: DecisionDraft = {
+    kind: TRIAGE_DECISION_KIND, anchors: [], text: `${tc.id} is ${cls}: ${tc.title}`, reason,
+    payload: { case: tc.id, class: cls, ...(human ? { humanConfirmed: true } : {}) },
+    source: { by: gitUserName(i.projectRoot), where: 'cli' }, valid_from: new Date().toISOString(), visibility: 'internal', evidence_hash: tc.evidence,
+  };
+  return { ...appendDecision(i.projectRoot, scope, draft), caseId: tc.id, class: cls };
+}

package/src/harness/unit-paths.ts

@@ -49,3 +49,22 @@ export function featureFilesFor(unitDir: string, unit: string): string[] {
     ...names.filter((n) => n !== canonicalName),
   ].map((n) => path.join(dir, n));
 }
+
+/**
+ * The catalog-resolution id for a unit dir (relative to qa/): screen · flows/<flow> · api/<area> ·
+ * api/flows/<flow>; a bare screen is its basename. Shared by the audit, which scores and links the
+ * unit under this id, and its inputsHash, which reads what the audit reads under the same id.
+ */
+export function catalogIdFromScreenDir(screenDir: string): string {
+  const parts = screenDir.split(path.sep);
+  const qa = parts.lastIndexOf('qa');
+  if (qa >= 0) {
+    if (parts[qa + 1] === 'api' && parts[qa + 2] === 'flows' && parts[qa + 3]) return `api/flows/${parts[qa + 3]}`;
+    if (parts[qa + 1] === 'api' && parts[qa + 2]) return `api/${parts[qa + 2]}`;
+    if (parts[qa + 1] === 'flows' && parts[qa + 2]) return `flows/${parts[qa + 2]}`;
+  }
+  return path.basename(screenDir);
+}
+
+/** A screen unit — the only kind a sibling flow credits (TQ-4); flows and api units are not. */
+export const isScreenUnitId = (catalogId: string): boolean => !/^(flows|api)\//.test(catalogId);