@sun-asterisk/sungen 3.2.34 → 3.3.0-alpha.2

package/src/harness/next-step.ts

@@ -16,9 +16,17 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { reportSlug, featureFilesFor } from './unit-paths';
-import { readTextFile } from './read-text';
+import { reportSlug } from './unit-paths';
 import { checkAssetsDrift } from '../orchestrator/assets-drift';
+import type { HeadSnapshot } from '../contract/contract-git';
+import { evaluateGraph, EvaluateOptions } from '../graph/evaluate-graph';
+import { CORE_NODES } from '../graph/nodes/core-node-catalog';
+import type { TestCaseState } from '../graph/test-case-state-shape';
+import { testCaseStates } from '../graph/test-case-states';
+import {
+  countFailedResults, countScenarios, hasDeliverableFor, hasResolvedSelector, isCompiled, readIfExists, unitResultFiles,
+} from '../graph/unit-artifact-probes';
+import { AuditNotCounted, ContractFacts, ContractSummary, readContractFacts, readTrustedAudit } from '../graph/unit-state-facts';
 
 export interface NextStep {
   /** The command to run, as the operator would type it. */
@@ -33,6 +41,13 @@ export interface NextStep {
    * in the same session (#660).
    */
   kind: 'do' | 'blocked' | 'optional' | 'decide';
+  /** The graph node that produced the step (OES-10.1). `--json` detail; the text never shows it. */
+  nodeId?: string;
+  granularity?: 'unit' | 'test-case';
+  /** The one test case the step is about (`sungen next <unit> --case <id>`). */
+  testCase?: string;
+  /** Catalog rule ids (gate-rules.yaml) the step answers to. */
+  gates?: string[];
 }
 
 export interface UnitState {
@@ -47,6 +62,13 @@ export interface UnitState {
   selectorsArePlaceholder: boolean;
   compiled: boolean;
   hasResults: boolean;
+  /**
+   * Scenarios whose FINAL attempt failed (failed · timedOut · interrupted) across the unit's result
+   * files — a retried pass is not a failure. Any failure puts `sungen triage` in the path: with only
+   * "optional" left after a deliverable, a red run read as done and its reds reached the export
+   * unclassified. Absent when the state was not read from disk.
+   */
+  failedCount?: number;
   hasDeliverable: boolean;
   audit?: {
     overall: number;
@@ -61,69 +83,42 @@ export interface UnitState {
    * warning is one grey stderr line at the top of every command (#620).
    */
   assetsDrift?: { recordedVersion: string; runningVersion: string };
+  /** An audit report exists but does not count (stale, untrusted) — gate and delivery block on it too. */
+  auditNotCounted?: AuditNotCounted;
+  /** The rebuilt Test Contract verdict (DOS-14.4); absent when not read from disk or no scenario exists. */
+  contract?: ContractSummary;
+  /** Per-test-case state (DOS-11.1); absent when not read from disk or unreadable. */
+  testCases?: TestCaseState[];
   steps: NextStep[];
 }
 
-const exists = (p: string): boolean => fs.existsSync(p);
-
-function readJson(p: string): Record<string, unknown> | null {
-  try {
-    return JSON.parse(readTextFile(p)) as Record<string, unknown>;
-  } catch {
-    return null;                                    // absent or unreadable — treated as "not run"
-  }
+export interface ReadUnitStateOptions {
+  /** git HEAD read once for many units (`sungen next` with no unit). */
+  gitSnapshot?: HeadSnapshot;
 }
 
-function countScenarios(unitDir: string, unit: string): number {
-  let n = 0;
-  for (const f of featureFilesFor(unitDir, unit)) {
-    const text = fs.existsSync(f) ? readTextFile(f) : '';
-    n += (text.match(/^\s*Scenario(?: Outline)?:/gm) ?? []).length;
-  }
-  return n;
-}
+const exists = (p: string): boolean => fs.existsSync(p);
 
 /**
- * Everything the resolver needs, read from disk. `unitId` is the catalog id
- * (`<screen>` · `flows/<f>` · `api/<a>`); `unitDir` is its directory.
+ * Everything the resolver needs, read from disk. `unit` is the catalog id
+ * (`<screen>` · `flows/<f>` · `api/<a>`); `unitDir` is its directory. The audit report is read
+ * through verifyAuditReport, as `sungen gate` and `sungen delivery` read it: a stale or untrusted
+ * report counts as never audited (OES-11.4) and is named in `auditNotCounted`.
  */
 export function readUnitState(
-  projectRoot: string, unitDir: string, unit: string, kind: UnitState['kind'],
+  projectRoot: string, unitDir: string, unit: string, kind: UnitState['kind'], opts: ReadUnitStateOptions = {},
 ): UnitState {
   const req = path.join(unitDir, 'requirements');
   const slug = reportSlug(unit);
-  const audit = readJson(path.join(projectRoot, '.sungen', 'reports', `${slug}-audit.json`));
+  const { report: audit, notCounted } = readTrustedAudit(projectRoot, unit);
   const selectorsDir = path.join(unitDir, 'selectors');
   let selectorFiles: string[] = [];
   try {
     selectorFiles = fs.readdirSync(selectorsDir).filter((f) => f.endsWith('.yaml'));
   } catch { /* api units carry no selectors */ }
-  // `readTextFile` throws on a missing file, and every path here is legitimately absent at some
-  // point in a unit's life — the resolver exists to report exactly that, so it must not crash on it.
-  const read = (p: string): string => (fs.existsSync(p) ? readTextFile(p) : '');
-  const selectorText = selectorFiles.map((f) => read(path.join(selectorsDir, f))).join('\n');
+  const selectorTexts = selectorFiles.map((f) => readIfExists(path.join(selectorsDir, f)));
   const contractPath = path.join(req, 'flow-contract.yaml');
-  const contractText = read(contractPath);
-
-  const specDirs = [
-    path.join(projectRoot, 'specs', 'generated', 'flows', unit),
-    path.join(projectRoot, 'specs', 'generated', unit),
-  ];
-  const compiled = specDirs.some((d) => {
-    try {
-      return fs.readdirSync(d).some((f) => f.endsWith('.spec.ts'));
-    } catch { return false; }
-  });
-  const hasResults = specDirs.some((d) => {
-    try {
-      return fs.readdirSync(d).some((f) => f.endsWith('-test-result.json'));
-    } catch { return false; }
-  });
-  let hasDeliverable = false;
-  try {
-    hasDeliverable = fs.readdirSync(path.join(projectRoot, 'qa', 'deliverables'))
-      .some((f) => f.startsWith(`${slug}-`));
-  } catch { /* nothing exported yet */ }
+  const resultFiles = unitResultFiles(projectRoot, unit);
 
   const score = (audit?.score ?? {}) as { overall?: number };
   const baseline = (audit?.viewpointBaseline ?? {}) as { status?: string };
@@ -134,14 +129,16 @@ export function readUnitState(
     hasContract: exists(contractPath),
     // A contract WITHOUT `flows:` can only be scored per phase, which is a materially weaker
     // claim — so it is part of the state, not a detail.
-    hasFlowInventory: /^\s*flows:\s*$/m.test(contractText),
+    hasFlowInventory: /^\s*flows:\s*$/m.test(readIfExists(contractPath)),
     scenarioCount: countScenarios(unitDir, unit),
     hasSelectors: selectorFiles.length > 0,
     // A scaffolded selector file exists but resolves nothing; treating it as "done" is what
     // makes a run look further along than it is.
-    selectorsArePlaceholder: selectorFiles.length > 0
-      && (/TODO|PLACEHOLDER|REPLACE ME/i.test(selectorText) || selectorText.trim().length < 40),
-    compiled, hasResults, hasDeliverable,
+    selectorsArePlaceholder: selectorFiles.length > 0 && !selectorTexts.some(hasResolvedSelector),
+    compiled: isCompiled(projectRoot, unit),
+    hasResults: resultFiles.length > 0,
+    failedCount: countFailedResults(resultFiles),
+    hasDeliverable: hasDeliverableFor(projectRoot, slug),
     assetsDrift: (() => {
       const d = checkAssetsDrift(projectRoot);
       return d && d.recordedVersion !== d.runningVersion
@@ -156,131 +153,24 @@ export function readUnitState(
         viewpointBaselineStatus: baseline.status,
       }
       : undefined,
+    ...(notCounted ? { auditNotCounted: notCounted } : {}),
     steps: [],
   };
+  let contract: ContractFacts | undefined;
+  if (state.scenarioCount > 0) state.contract = (contract = readContractFacts(projectRoot, unit, unitDir, opts.gitSnapshot)).summary;
+  try {
+    state.testCases = testCaseStates(projectRoot, unit, { unitDir, auditFindings: state.audit?.findings ?? [] })
+      .map((tc) => (contract?.cases.has(tc.id) ? { ...tc, contract: contract.cases.get(tc.id) } : tc));
+  } catch { /* an unparseable .feature — the unit-level nodes still answer, as before test-case state */ }
   state.steps = deriveSteps(state);
   return state;
 }
 
-/** The finding codes worth naming in a next step — each maps to a specific repair. */
-const REPAIRABLE = [
-  'FLOW-CONTRACT-MISSING', 'FLOW-INVENTORY-MISSING', 'FLOW-UNCOVERED', 'FLOW-UNDECLARED',
-  'FLOW-PHASE-MISFILED', 'FLOW-GUARANTEE-MISSING', 'FLOW-OUTCOME-UNPROVEN', 'CONTINUITY-ONE-SIDED',
-  'ORACLE-URL-ONLY',
-  'SPEC-RESTATED-UNVERIFIED', 'VIEWPOINT-GESTURE-SUBSTITUTED', 'SPEC-UNCOVERED', 'SPEC-CLAUSE-UNCOVERED',
-  'TRIGGER-UNCOVERED', 'PERMISSION-PAIR-MISSING', 'VISIBILITY-PAIR-MISSING',
-  'VIEWPOINT-ITEM-MISSING', 'MANUAL-CODE-MISSING', 'MANUAL-AUTOMATABLE', 'DEPTH-DEFERRED',
-  'UI-INVENTORY-MISSING', 'UI-INVENTORY-INCOMPLETE', 'UI-ITEM-UNCOVERED',
-];
-
 /**
- * The ordered answer. Earliest unmet precondition first, so the list reads as a path rather than
- * a menu — and a `blocked` step names what to resolve instead of pretending it can run.
+ * The ordered answer — earliest unmet precondition first, so the list reads as a path rather than a
+ * menu. Evaluated over the internal node graph (src/graph, OES-10.1): each former if/return branch
+ * is one node, and an open blocking node cuts everything after it, exactly as the `return`s did.
  */
-export function deriveSteps(s: UnitState): NextStep[] {
-  const out: NextStep[] = [];
-  const design = s.kind === 'api' ? `/sungen:create-test ${s.unit}` : `/sungen:create-test ${s.unit}`;
-
-  if (!s.hasSpec && !s.hasViewpoint) {
-    out.push({
-      kind: 'blocked',
-      command: `write qa/${s.kind === 'screen' ? 'screens' : s.kind === 'flow' ? 'flows' : 'api'}/${s.unit}/requirements/spec.md`,
-      because: 'the unit has neither a spec nor a test-viewpoint, so there is nothing to generate FROM — generation without a source invents behaviour',
-    });
-    return out;
-  }
-  // Stale AI assets come FIRST, because they invalidate the advice below: a HARD RULE added to
-  // `create-test` reaches nobody until `sungen update` runs, so the run that follows will repeat
-  // whatever the old instructions said. Upgrading the package alone does not refresh them, and the
-  // existing warning is one grey stderr line among a command's whole output (#620).
-  if (s.assetsDrift) {
-    out.push({
-      kind: 'do',
-      command: 'sungen update',
-      because: `this project's AI commands/skills were written by sungen ${s.assetsDrift.recordedVersion} and you are running ${s.assetsDrift.runningVersion} — upgrading the package does NOT refresh them, so any rule added since ${s.assetsDrift.recordedVersion} is not in effect for the next run`,
-    });
-  }
-  // The yardstick. `atomicLedger` and `traceability` are measured against test-viewpoint.md and
-  // four sensors read it, so its absence is not cosmetic — and it can go missing from a unit that
-  // already HAS a spec (a run deleted it), which the "no source at all" branch above never sees.
-  if (!s.hasViewpoint) {
-    out.push({
-      kind: 'blocked',
-      command: s.kind === 'flow'
-        ? `sungen add-flow --flow ${s.unit} --path <start-url>    # repairs the missing scaffold; never overwrites`
-        : `write qa/screens/${s.unit}/requirements/test-viewpoint.md`,
-      because: 'requirements/test-viewpoint.md is missing — it is the yardstick `atomicLedger` and `traceability` are measured against, and four sensors read it, so the audit reports VIEWPOINT-MISSING and those axes are excluded. A flow contract does not substitute: it declares the use case, the viewpoint declares the claims',
-    });
-  }
-  if (s.kind === 'flow' && !s.hasContract) {
-    out.push({
-      kind: 'blocked',
-      command: `author requirements/flow-contract.yaml, then ${design}`,
-      because: 'a flow with no contract is scored as a generic screen against page-type themes a journey cannot have (FLOW-CONTRACT-MISSING)',
-    });
-    return out;
-  }
-  if (s.scenarioCount === 0) {
-    out.push({ kind: 'do', command: design, because: 'no scenarios exist yet' });
-    return out;
-  }
-  if (s.kind === 'flow' && !s.hasFlowInventory) {
-    out.push({
-      kind: 'do',
-      command: `add \`flows:\` to requirements/flow-contract.yaml, then sungen audit --screen ${s.unit}`,
-      because: 'without the inventory, coverage is measured per PHASE — and a phase counts as covered as soon as one scenario carries it, so the number cannot tell you a flow is missing',
-    });
-  }
-  if (!s.audit) {
-    out.push({ kind: 'do', command: `sungen audit --screen ${s.unit}`, because: 'the suite has never been measured' });
-    return out;
-  }
-  if (s.audit.viewpointBaselineStatus === 'changed') {
-    out.push({
-      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 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
-    .map((f) => f.split(':')[0].trim())
-    .filter((code) => REPAIRABLE.includes(code));
-  if (repair.length > 0) {
-    out.push({
-      kind: 'do',
-      command: `repair, then sungen audit --screen ${s.unit}`,
-      because: `${repair.length} finding(s) name a specific repair: ${[...new Set(repair)].slice(0, 4).join(', ')}`,
-    });
-  }
-  if (s.audit.gateStatus === 'FAIL') {
-    out.push({
-      kind: 'blocked',
-      command: `repair the gate, then sungen audit --screen ${s.unit}`,
-      because: `the viewpoint gate is FAIL at ${s.audit.overall}/10 — running tests against a design that fails its own gate measures the wrong thing`,
-    });
-    return out;
-  }
-  if (s.kind !== 'api' && (!s.hasSelectors || s.selectorsArePlaceholder)) {
-    out.push({
-      kind: 'do',
-      command: `/sungen:run-test ${s.unit}`,
-      because: s.hasSelectors
-        ? 'the selector file is still a placeholder, so nothing resolves against a live page'
-        : 'no selectors exist yet — run-test generates them from the live page, compiles and auto-fixes',
-    });
-    return out;
-  }
-  if (!s.compiled) {
-    out.push({ kind: 'do', command: `sungen generate --${s.kind === 'flow' ? 'flow' : 'screen'} ${s.unit}`, because: 'the suite has not been compiled to a spec yet' });
-    return out;
-  }
-  if (!s.hasResults) {
-    out.push({ kind: 'do', command: `/sungen:run-test ${s.unit}`, because: 'the compiled spec has never been run, so every case is Pending' });
-    return out;
-  }
-  if (!s.hasDeliverable) {
-    out.push({ kind: 'do', command: `/sungen:delivery ${s.unit}`, because: 'results exist but have not been exported to the Test Case & Coverage Matrix' });
-  }
-  out.push({ kind: 'optional', command: `/sungen:create-test ${s.unit}`, because: 'extend coverage — the next tier, or the flows the inventory still lists as pending' });
-  return out;
+export function deriveSteps(s: UnitState, opts: EvaluateOptions = {}): NextStep[] {
+  return evaluateGraph(CORE_NODES, s, s.testCases, opts);
 }

package/src/harness/parse.ts

@@ -79,6 +79,7 @@ export interface ScenarioInfo {
   deferredToFlow?: boolean;   // @deferred:flow — owned by a flow, not automated on this screen (H6)
   ownedByFlow?: string;       // @owned-by:<flow> — the flow that owns this deferred scenario (H6)
   featureManual?: boolean;    // its Feature is tagged @manual — codegen skips the whole file (#835)
+  handWritten?: boolean;      // @free / @impl:code — counted, never compiled (isHandWritten, DOS-14.8)
   /** Ordered steps with their resolved bucket (And/But inherit) — flow handoff analysis (#569). */
   /** `arg` = the step's data table, normalised (#817) — absent when the step has none. */
   steps?: Array<{ bucket: 'given' | 'when' | 'then'; text: string; arg?: string }>;
@@ -285,6 +286,25 @@ function withBackground(sc: ParsedScenario, background?: ParsedScenario): Parsed
   return { ...sc, steps: [...bg, ...((sc.steps as ParsedStep[]) || [])] } as ParsedScenario;
 }
 
+/**
+ * The `VP-<CATEGORY>-<n>` / `FL-<PHASE>-<n>` code in a scenario title, and its category — the ONE
+ * reading of it; the manifest kept an older copy of this regex and recorded no code for
+ * VP-I18N-001, VP-LIST-DISPLAY-01, VP-AF02-01 or any FL- id (#889).
+ *
+ * Category is everything between `VP-` and the final `-<sequence>` — INCLUDING hyphens, so
+ * compound categories (VP-LIST-DISPLAY-01, VP-ADD-TO-CART-03, VP-PRODUCT-DISCOVERY-02) parse,
+ * not just single-word ones. A single-word category (VP-CART-001) still works. (H1)
+ * Flows use journey-phase ids (FL-HP-001 / FL-ER-002) — the VP- anchor rejected them, so every
+ * flow scenario had NO category and the whole suite bucketed `other` (taxonomy=0%, #569).
+ * Segments may carry digits: the use-case framework numbers its flows (VP-AF02-01,
+ * VP-EF11-01 — one id per Alternate/Exception Flow), and `[A-Z]+` also silently truncated
+ * VP-I18N-001 to no category at all (the `18` broke the class mid-segment).
+ */
+export function vpCodeOf(title: string): { vpCode?: string; category?: string } {
+  const m = title.match(/\b(?:VP|FL)-([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*)-\d+/i);
+  return m ? { vpCode: m[0].toUpperCase(), category: m[1].toUpperCase() } : {};
+}
+
 function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   const tags = sc.tags || [];
   const deferredToFlow = tags.includes('@deferred:flow');
@@ -310,17 +330,7 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   let priority: Priority = 'unknown';
   for (const t of tags) if (PRIORITY_TAGS[t]) priority = PRIORITY_TAGS[t];
 
-  // Category is everything between `VP-` and the final `-<sequence>` — INCLUDING hyphens, so
-  // compound categories (VP-LIST-DISPLAY-01, VP-ADD-TO-CART-03, VP-PRODUCT-DISCOVERY-02) parse,
-  // not just single-word ones. A single-word category (VP-CART-001) still works. (H1)
-  // Flows use journey-phase ids (FL-HP-001 / FL-ER-002) — the VP- anchor rejected them, so every
-  // flow scenario had NO category and the whole suite bucketed `other` (taxonomy=0%, #569).
-  // Segments may carry digits: the use-case framework numbers its flows (VP-AF02-01,
-  // VP-EF11-01 — one id per Alternate/Exception Flow), and `[A-Z]+` also silently truncated
-  // VP-I18N-001 to no category at all (the `18` broke the class mid-segment).
-  const codeMatch = sc.name.match(/\b(?:VP|FL)-([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*)-\d+/i);
-  const vpCode = codeMatch ? codeMatch[0].toUpperCase() : undefined;
-  const category = codeMatch ? codeMatch[1].toUpperCase() : undefined;
+  const { vpCode, category } = vpCodeOf(sc.name);
   // Project-scheme ID: the leading token of the title (VP0-001 / MS-HP-001 / VP-LIST-001).
   const leadMatch = sc.name.match(/^\s*([A-Za-z][A-Za-z0-9.-]*)/);
   const vpId = leadMatch && isIdLike(leadMatch[1]) ? leadMatch[1].toUpperCase() : undefined;
@@ -395,9 +405,26 @@ export function loadScenarios(featurePath: string): ScenarioInfo[] {
   const feature = parser.parseFeatureFile(featurePath);
   // Kept apart from `manual` so the audit's accounting is unchanged; only `select` reads it.
   const featureManual = (feature.tags || []).some((t: string) => /^@manual\b/i.test(t)) || undefined;
+  // A derived `@proposed` scenario (sungen contract derive, DOS-14.8) is not counted until QA approves it;
+  // an approved `@free` / `@impl:code` one IS counted, but never compiled (`handWritten`).
+  const tagsOf = (s: { tags?: string[] }): string[] => [...(feature.tags || []), ...(s.tags || [])];
   return (feature.scenarios || [])
-    .filter((s) => !s.stepsName && !s.hookType) // skip @steps/@hook blocks
-    .map((s) => ({ ...classifyScenario(withBackground(s, feature.background)), sourceFile: featurePath, featureManual }));
+    .filter((s) => !s.stepsName && !s.hookType && !tagsOf(s).some((t) => PROPOSED_TAG.test(t))) // skip @steps/@hook blocks and unapproved proposals
+    .map((s) => ({
+      ...classifyScenario(withBackground(s, feature.background)), sourceFile: featurePath, featureManual,
+      handWritten: isHandWritten(tagsOf(s), featurePath) || undefined,
+    }));
+}
+
+const PROPOSED_TAG = /^@proposed$/i;
+
+/**
+ * Is a scenario implemented by HAND-WRITTEN code rather than compiled (DOS-14.2, 14.8)? `@free`,
+ * `@impl:code`, a derived `@proposed`, or anything in a derived `*.free.feature`. The one predicate
+ * codegen (never compiles these), script-check (never expects a compiled twin) and the harness share.
+ */
+export function isHandWritten(tags: readonly string[], featureFile?: string): boolean {
+  return (!!featureFile && featureFile.endsWith('.free.feature')) || tags.some((t) => /^@(?:free|impl:code|proposed)$/i.test(t));
 }
 
 /**

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;
@@ -107,6 +109,12 @@ const ASSERTION_STEP_COMMENT = /^\s*\/\/\s*Assert\b/;
 // but as a bare substring it would also exempt a genuinely hollow step whose test-data or step
 // text happened to contain it.
 const NOOP_STEP_MARKER = /^\s*\/\/\s*App launched via wdio capabilities/;
+// The same kind of step on the web adapter, where the explanation IS the step comment: the
+// step-mapper compiles `Given User is on [Edit] dialog` (and its exit) to `// Enter dialog scope:
+// Edit` and no code, because it only re-roots the steps after it — the next assertion runs as
+// `page.getByRole('dialog', …).getByRole(…)`. A field unit reported 13 BYPASS, every one of them
+// this comment, and exited 2 on a correct suite (#881). Anchored to the whole marker line.
+const SCOPE_STEP_MARKER = /^\s*\/\/\s*(?:Enter|Exit) dialog scope(?::\s*.*)?$/;
 
 /** A spec comment line reduced to its text, for comparison against a compiler step comment. */
 const commentText = (line: string): string => line.trim().replace(/^\/\/\s?/, '').trim();
@@ -241,7 +249,7 @@ export function analyzeFaithfulness(
       const hasCode = region.some((l) => !isComment(l) && CODE_LINE.test(l));
       // A documented no-op emits its explanation INTO the step's region, so read the region
       // (not just the marker line) for it — see NOOP_STEP_MARKER.
-      if (hasCode || region.some((l) => NOOP_STEP_MARKER.test(l))) continue;
+      if (hasCode || region.some((l) => NOOP_STEP_MARKER.test(l)) || SCOPE_STEP_MARKER.test(body[markers[s]])) continue;
       if (tailAmbiguous && s === markers.length - 1) continue;
       hollowSteps.push({ test: title, step: body[markers[s]].trim().slice(0, 70) });
     }
@@ -334,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);
@@ -382,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).
@@ -422,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 });
     }
   }
 
@@ -440,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,
@@ -456,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,
   };
 }