@sun-asterisk/sungen 3.2.34-beta.1 → 3.3.0-alpha.1

package/src/harness/next-step.ts

@@ -16,12 +16,17 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { parse as parseYaml } from 'yaml';
-import { reportSlug, featureFilesFor } from './unit-paths';
-import { readTextFile } from './read-text';
+import { reportSlug } from './unit-paths';
 import { checkAssetsDrift } from '../orchestrator/assets-drift';
-import { viewpointFileIsAiDraft } from './viewpoint-draft-header';
-import { readViewpointDeclaration } from './viewpoint-baseline';
+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. */
@@ -36,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 {
@@ -43,8 +55,6 @@ export interface UnitState {
   kind: 'screen' | 'flow' | 'api';
   hasSpec: boolean;
   hasViewpoint: boolean;
-  /** test-viewpoint.md carries `drafted-by: ai` — written by the AI, not yet accepted by a QA. */
-  viewpointIsAiDraft?: boolean;
   hasContract: boolean;
   hasFlowInventory: boolean;
   scenarioCount: number;
@@ -52,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;
@@ -66,94 +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;
-}
-
-/**
- * Everything the resolver needs, read from disk. `unitId` is the catalog id
- * (`<screen>` · `flows/<f>` · `api/<a>`); `unitDir` is its directory.
- */
-const RESULT_FILE = /-test-result(?:\.[^.]+)*\.json$/;
+const exists = (p: string): boolean => fs.existsSync(p);
 
 /**
- * Does the selector text resolve at least one element? A scaffold resolves none: the web one holds
- * only the `page` route, the mobile one only header comments. Matching the WORD "placeholder" was
- * wrong both ways (#868): it flagged a real file whose key names an input's placeholder text, and
- * missed both scaffolds, which never contain it.
+ * 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`.
  */
-function hasResolvedSelector(selectorText: string): boolean {
-  let doc: unknown;
-  try { doc = parseYaml(selectorText); } catch { return selectorText.trim().length >= 40; }
-  if (!doc || typeof doc !== 'object') return false;
-  // A real cell, not a marker left to be filled in. Numbers count (an id or index can be numeric).
-  const real = (v: unknown): boolean => (typeof v === 'string' || typeof v === 'number')
-    && String(v).trim() !== '' && !/^(?:todo|tbd|placeholder|replace me)$/i.test(String(v).trim());
-  return Object.values(doc as Record<string, unknown>).some((e) => {
-    if (!e || typeof e !== 'object') return false;
-    const { type, value, name, locator } = e as { type?: unknown; value?: unknown; name?: unknown; locator?: unknown };
-    // Every SelectorEntry shape: a CSS `locator`, or a non-page `type` with a value or a role name.
-    return real(locator) || (typeof type === 'string' && type !== 'page' && (real(value) || real(name)));
-  });
-}
-
 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 selectorTexts = selectorFiles.map((f) => read(path.join(selectorsDir, f)));
+  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 {
-      // `<f>-test-result[.<os>][.<env>].json` — a mobile run writes the OS into the name, an env
-      // run (SUNGEN_ENV=staging) the env; both are runs (#868).
-      return fs.readdirSync(d).some((f) => RESULT_FILE.test(f));
-    } 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 };
@@ -161,19 +126,19 @@ export function readUnitState(
     unit, kind,
     hasSpec: exists(path.join(req, 'spec.md')),
     hasViewpoint: exists(path.join(req, 'test-viewpoint.md')),
-    // An id-less draft has nothing to accept: only the missing-yardstick step speaks for it.
-    viewpointIsAiDraft: viewpointFileIsAiDraft(path.join(req, 'test-viewpoint.md'))
-      && readViewpointDeclaration(path.join(req, 'test-viewpoint.md')) !== null,
     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 && !selectorTexts.some(hasResolvedSelector),
-    compiled, hasResults, hasDeliverable,
+    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
@@ -188,140 +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;
-  }
-  // Before any generation: the AI drafts the viewpoint and audits it BEFORE it writes scenarios, so
-  // this is exactly where a draft would otherwise be accepted by the process that wrote it.
-  if (s.viewpointIsAiDraft) {
-    out.push({
-      kind: 'decide',
-      command: `sungen audit --screen ${s.unit} --accept-viewpoint`,
-      because: 'test-viewpoint.md is marked `drafted-by: ai` — nobody has reviewed it, so the ledger and traceability axes are held as unverified. A QA reviews the claims (adds what matters, deletes what does not), then accepts; the command records the baseline and removes the marker. A decision, not a step: an agent presents it and does not run it',
-    });
-  }
-  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' && !s.viewpointIsAiDraft) {   // the draft's own decide step is already above
-    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

@@ -8,7 +8,6 @@
 import * as fs from 'fs';
 import { GherkinParser, ParsedScenario, ParsedStep } from '../generators/gherkin-parser';
 import { readTextFile, readViewpointText } from './read-text';
-import { parsePriority, toEntryPriority } from './viewpoint-priority';
 import { featureFilesFor } from './unit-paths';
 
 export type Priority = 'high' | 'normal' | 'low' | 'unknown';
@@ -16,7 +15,7 @@ export type Priority = 'high' | 'normal' | 'low' | 'unknown';
 export interface ViewpointEntry {
   id: string;            // e.g. VP-DATA-CONSISTENCY
   priority: 'High' | 'Medium' | 'Low' | 'Unknown';
-  /** The declared priority word as written (`critical` · `high` · `medium` · `med` · `normal` · `low` ·
+  /** The declared priority word as written (`critical` · `high` · `medium` · `normal` · `low` ·
    *  `deferred` · `skip`, which also stands for skipped / n/a / none / not applicable), kept because `priority` folds several of them together and the
    *  PRIORITY-CONTRADICTED check needs them apart. Absent when no priority was declared. */
   priorityWord?: string;
@@ -26,14 +25,14 @@ export interface ViewpointEntry {
 
 /**
  * Whole SECTIONS that declare something ABOUT the checklist rather than listing claims or
- * viewpoints — known issues, spec gaps, traceability indexes, references and appendices, changelogs. Shared by the atomic
+ * viewpoints — known issues, traceability indexes, references, changelogs. Shared by the atomic
  * ledger (their rows are not claims to prove, #630) and the viewpoint-overview parser (an id
  * listed there is a reference, not a declaration, #833). `UI Patterns Identified` is the author's
  * pick of WHICH sungen-viewpoint patterns apply — a `Skip` row there is not a claim to cover (#841).
  * A `How to run` / `Procedure` section — that exact heading, optionally naming one id — is a manual
  * check's steps, not claims of its own (#855); `How to test the login flow` stays a normal section.
  */
-export const NON_DECLARATION_SECTION = /^(?:(?:ui patterns?(?: identified)?|(?:how to (?:run|test|reproduce|verify)|(?:manual )?procedures?)(?:\s+(?:vp|fl)-[^\s:]+)?)\s*:?$|(?:known issues?|open questions?|spec gaps?|appendi(?:x|ces)|phụ lục|deferred|out of scope|viewpoint grouping|traceability|metadata|scope|journey phases?|revision history|references?|sources?|changelog)\b)/i;
+export const NON_DECLARATION_SECTION = /^(?:(?:ui patterns?(?: identified)?|(?:how to (?:run|test|reproduce|verify)|(?:manual )?procedures?)(?:\s+(?:vp|fl)-[^\s:]+)?)\s*:?$|(?:known issues?|open questions?|deferred|out of scope|viewpoint grouping|traceability|metadata|scope|journey phases?|revision history|references?|sources?|changelog)\b)/i;
 
 /**
  * Every word a viewpoint row may declare as its priority — ONE list for the overview parser, the
@@ -41,7 +40,7 @@ export const NON_DECLARATION_SECTION = /^(?:(?:ui patterns?(?: identified)?|(?:h
  * `Skip` that the `sungen add` / `add-flow` scaffolds themselves suggest (#853). `deferred` and the
  * not-applicable words are declarations as well: such a row is not a claim to cover.
  */
-export const PRIORITY_WORDS = 'critical|high|medium|med|normal|low|deferred|skip(?:ped)?|n\\/a|none|not applicable';
+export const PRIORITY_WORDS = 'critical|high|medium|normal|low|deferred|skip(?:ped)?|n\\/a|none|not applicable';
 /** "Declared not applicable" — folded to `skip` so every consumer checks one word. */
 const NOT_APPLICABLE = /^(?:skip(?:ped)?|n\/a|none|not applicable)$/i;
 
@@ -55,7 +54,7 @@ const PRIORITY_HEADER = /^(?:priority|pri|level|severity|優先度?|độ ưu ti
 function priorityOf(cell: string): { priority: ViewpointEntry['priority']; priorityWord?: string } {
   const raw = cell.match(PRIORITY_WORD)?.[1].toLowerCase();
   const word = raw && NOT_APPLICABLE.test(raw) ? 'skip' : raw;
-  const priority = toEntryPriority(parsePriority(cell));
+  const priority = /high/i.test(cell) ? 'High' : /medium/i.test(cell) ? 'Medium' : /low/i.test(cell) ? 'Low' : 'Unknown';
   return word ? { priority, priorityWord: word } : { priority };
 }
 
@@ -64,9 +63,6 @@ export interface ScenarioInfo {
   vpCode?: string;       // VP-CART-001 style code in the scenario title
   category?: string;     // CART, LIST, VAL, ... (from the code)
   priority: Priority;
-  /** The priority tag as written, lower-cased, without `@` — keeps `critical` / `medium` / `med`, which
-   *  `priority` has no slot for, so PRIORITY-CONTRADICTED can fold it like the declared word (#861). */
-  priorityTag?: string;
   manual: boolean;
   thenCount: number;
   hasDataAssertion: boolean;  // a Then asserts {{data}} / contains / match data
@@ -83,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 }>;
@@ -332,9 +329,6 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   const requiresCaps = tags.filter((t) => /^@requires:/i.test(t)).map((t) => t.slice('@requires:'.length).trim().toLowerCase()).filter(Boolean);
   let priority: Priority = 'unknown';
   for (const t of tags) if (PRIORITY_TAGS[t]) priority = PRIORITY_TAGS[t];
-  // Deliberately wider than `priority` (every priority word, any case): only PRIORITY-CONTRADICTED reads
-  // it, so `@critical` / `@High` are judged there without moving what select-by-ids or the score see.
-  const priorityTag = [...tags].reverse().find((t) => /^@(?:critical|high|medium|med|normal|low)$/i.test(t))?.slice(1).toLowerCase();
 
   const { vpCode, category } = vpCodeOf(sc.name);
   // Project-scheme ID: the leading token of the title (VP0-001 / MS-HP-001 / VP-LIST-001).
@@ -386,7 +380,6 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
     vpCode,
     category,
     priority,
-    priorityTag,
     manual,
     thenCount,
     hasDataAssertion: hasData,
@@ -412,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/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,
   };
 }