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

package/src/harness/manifest.ts

@@ -6,21 +6,33 @@
  * scenario: keep / regenerate / retire — so the orchestrator regenerates only the
  * parts whose spec changed (stable + cheap), and never silently drifts.
  *
+ * Schema 2 (DOS-12.3, red-team #1): each entry names its `hashAlgo`. Section entries keep `sha1-12`
+ * and the fuzzy `matchSection` — changing either would make every manifest on disk read "changed".
+ * Only item anchors (`<docId>#<itemId>` in a `# --- Section: … ---` comment) use `sha256-12` + exact
+ * ids. A manifest WITHOUT `schema` is compared as is (its sections are sha1-12) and upgraded on save.
  * Deterministic. Manifest lives at .sungen/manifest/<screen>.json.
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { createHash } from 'crypto';
 import { featureFilesFor, reportSlug } from './unit-paths';
 import { readTextFile } from './read-text';
 import { vpCodeOf } from './parse';
+import { HashAlgo, sectionHash } from '../basis/anchor-hash';
+import { isItemAnchorId } from '../basis/anchor-grammar';
+import { extractSpecAnchors } from '../basis/extract-spec-anchors';
+import { normalizeSectionName as norm, readSpecSectionBlocks } from '../basis/spec-sections';
+import { assertNoPendingMigration, withMigrationSentinel } from '../basis/migration-sentinel';
+
+export const MANIFEST_SCHEMA = 2;
 
 export interface SpecSection { name: string; hash: string }
-export interface ManifestEntry { scenario: string; vpCode?: string; section: string; specHash: string }
+export interface ManifestEntry { scenario: string; vpCode?: string; section: string; specHash: string; hashAlgo?: HashAlgo }
 export interface Manifest {
+  schema?: number;                         // absent = written before schema 2 → silent re-baseline
   screen: string;
   builtAt: string;
-  specSections: Record<string, string>;   // section name → hash (snapshot at build time)
+  specSections: Record<string, string>;   // section name → sha1-12 (snapshot at build time)
+  specItems?: Record<string, string>;     // item anchor → sha256-12 (schema 2, BM-51 specs with a docId)
   entries: ManifestEntry[];                // scenario ↔ section ↔ hash
 }
 
@@ -33,13 +45,6 @@ export interface ChangePlan {
   summary: { keep: number; regenerate: number; retire: number; newSections: number };
 }
 
-function norm(s: string): string {
-  return s.replace(/\(Tier[^)]*\)/i, '').replace(/[#*-]/g, '').trim().toLowerCase().replace(/\s+/g, ' ');
-}
-function shortHash(s: string): string {
-  return createHash('sha1').update(s).digest('hex').slice(0, 12);
-}
-
 const NO_SPEC = '(no-spec-link)';
 
 /**
@@ -61,21 +66,17 @@ function matchSection(featureSection: string, specNames: string[]): string | nul
 /** Parse spec.md into hashable sections (## and ### headings; "Section:" prefix stripped). */
 export function parseSpecSections(specPath: string): SpecSection[] {
   if (!fs.existsSync(specPath)) return [];
-  const lines = readTextFile(specPath).split('\n');
-  const sections: { name: string; body: string[] }[] = [];
-  let cur: { name: string; body: string[] } | null = null;
-  for (const line of lines) {
-    const h = line.match(/^#{2,3}\s+(.*)$/);
-    if (h) {
-      if (cur) sections.push(cur);
-      const name = h[1].replace(/^Section:\s*/i, '').trim();
-      cur = { name, body: [] };
-    } else if (cur) {
-      cur.body.push(line);
-    }
+  return readSpecSectionBlocks(readTextFile(specPath).split('\n')).map((s) => ({ name: norm(s.name), hash: sectionHash(s.body) }));
+}
+
+/** Item anchors a scenario can be linked to exactly: unambiguous §4.1 items and their §4.2 rows. */
+function parseSpecItems(specPath: string): Record<string, string> {
+  if (!fs.existsSync(specPath)) return {};
+  const out: Record<string, string> = {};
+  for (const a of extractSpecAnchors(readTextFile(specPath), { repo: '.', sha: 'WORKTREE', path: 'spec.md' }).anchors) {
+    if (a.kind !== 'section' && a.confidence === 'EXTRACTED') out[a.id] = a.hash;
   }
-  if (cur) sections.push(cur);
-  return sections.map((s) => ({ name: norm(s.name), hash: shortHash(s.body.join('\n').trim()) }));
+  return out;
 }
 
 /** Parse feature into scenario → section mapping using `# --- Section: X ---` comments. */
@@ -87,7 +88,7 @@ function parseFeatureSections(featurePath: string): { scenario: string; vpCode?:
   for (const raw of lines) {
     const line = raw.trim();
     const sc = line.match(/^#\s*-{2,}\s*Section:\s*(.*?)\s*-{2,}\s*$/i);
-    if (sc) { section = norm(sc[1]); continue; }
+    if (sc) { section = isItemAnchorId(sc[1].trim()) ? sc[1].trim() : norm(sc[1]); continue; }
     const s = line.match(/^Scenario:\s*(.*)$/);
     if (s) {
       const name = s[1].trim();
@@ -100,44 +101,55 @@ function parseFeatureSections(featurePath: string): { scenario: string; vpCode?:
 export function buildManifest(screenDir: string, screenName: string): Manifest {
   const specPath = path.join(screenDir, 'requirements', 'spec.md');
   const featureFiles = featureFilesFor(screenDir, screenName);
-  const specSections = parseSpecSections(specPath);
   const specMap: Record<string, string> = {};
-  for (const s of specSections) specMap[s.name] = s.hash;
+  for (const s of parseSpecSections(specPath)) specMap[s.name] = s.hash;
+  const specItems = parseSpecItems(specPath);
 
   const specNames = Object.keys(specMap);
-  const featScenarios = featureFiles.flatMap(parseFeatureSections);
-  const entries: ManifestEntry[] = featScenarios.map((f) => {
+  const entries: ManifestEntry[] = featureFiles.flatMap(parseFeatureSections).map((f) => {
+    const base = { scenario: f.scenario, vpCode: f.vpCode };
+    if (isItemAnchorId(f.section)) {
+      const hash = specItems[f.section];
+      return hash ? { ...base, section: f.section, specHash: hash, hashAlgo: 'sha256-12' as HashAlgo } : { ...base, section: f.section, specHash: NO_SPEC };
+    }
     const matched = matchSection(f.section, specNames);
-    return {
-      scenario: f.scenario,
-      vpCode: f.vpCode,
-      section: matched ?? f.section,         // canonical spec section when matched
-      specHash: matched ? specMap[matched] : NO_SPEC,
-    };
+    return matched
+      ? { ...base, section: matched, specHash: specMap[matched], hashAlgo: 'sha1-12' as HashAlgo } // canonical spec section when matched
+      : { ...base, section: f.section, specHash: NO_SPEC };
   });
 
   return {
+    schema: MANIFEST_SCHEMA,
     screen: screenName,
     builtAt: new Date().toISOString(),
     specSections: specMap,
+    ...(Object.keys(specItems).length ? { specItems } : {}),
     entries,
   };
 }
 
+/**
+ * Compare a stored manifest — legacy or schema 2 — with the spec now. Read-only: it never rewrites
+ * the manifest. A legacy entry has no `hashAlgo` and is a section entry hashed sha1-12, exactly what
+ * the current code computes, so real drift since the legacy build reads `regenerate` and nothing reads
+ * "changed" merely because the format moved on.
+ */
 export function diffManifest(screenDir: string, screenName: string, manifest: Manifest): ChangePlan {
+  assertNoPendingMigration(process.cwd(), reportSlug(screenName));
   const specPath = path.join(screenDir, 'requirements', 'spec.md');
-  const current = parseSpecSections(specPath);
   const currentMap: Record<string, string> = {};
-  for (const s of current) currentMap[s.name] = s.hash;
+  for (const s of parseSpecSections(specPath)) currentMap[s.name] = s.hash;
+  const currentItems = manifest.entries.some((e) => e.hashAlgo === 'sha256-12') ? parseSpecItems(specPath) : {};
 
   const scenarios = manifest.entries.map((e) => {
     let change: ChangeKind; let reason: string;
+    const what = e.hashAlgo === 'sha256-12' ? 'spec item' : 'spec section';
     if (e.specHash === NO_SPEC) { change = 'keep'; reason = 'not linked to a spec section (manual/cross-cutting)'; }
     else {
-      const now = currentMap[e.section];
-      if (now === undefined) { change = 'retire'; reason = `spec section "${e.section}" no longer exists`; }
-      else if (now !== e.specHash) { change = 'regenerate'; reason = `spec section "${e.section}" changed (${e.specHash} → ${now})`; }
-      else { change = 'keep'; reason = 'spec section unchanged'; }
+      const now = e.hashAlgo === 'sha256-12' ? currentItems[e.section] : currentMap[e.section];
+      if (now === undefined) { change = 'retire'; reason = `${what} "${e.section}" no longer exists`; }
+      else if (now !== e.specHash) { change = 'regenerate'; reason = `${what} "${e.section}" changed (${e.specHash} → ${now})`; }
+      else { change = 'keep'; reason = `${what} unchanged`; }
     }
     return { scenario: e.scenario, section: e.section, change, reason };
   });
@@ -167,9 +179,21 @@ export function loadManifest(screenName: string): Manifest | null {
   const p = manifestPath(screenName);
   return fs.existsSync(p) ? JSON.parse(readTextFile(p)) : null;
 }
-export function saveManifest(m: Manifest): string {
-  const p = manifestPath(m.screen);
+/** The manifest on disk at `p`, or null when absent or unreadable (then a save is a plain write). */
+function loadManifestFile(p: string): Manifest | null {
+  try { return fs.existsSync(p) ? JSON.parse(readTextFile(p)) : null; } catch { return null; }
+}
+function writeManifest(p: string, m: Manifest): void {
   fs.mkdirSync(path.dirname(p), { recursive: true });
   fs.writeFileSync(p, JSON.stringify(m, null, 2), 'utf-8');
+}
+/** Write a built manifest. Replacing a legacy (schema-less) file is the upgrade to schema 2, done under the sentinel. */
+export function saveManifest(m: Manifest): string {
+  const slug = reportSlug(m.screen);
+  assertNoPendingMigration(process.cwd(), slug);
+  const p = manifestPath(m.screen);
+  const upgrading = m.schema === MANIFEST_SCHEMA && (loadManifestFile(p)?.schema ?? MANIFEST_SCHEMA) !== MANIFEST_SCHEMA;
+  if (upgrading) withMigrationSentinel(process.cwd(), m.screen, slug, 'manifest upgrade to schema 2', [p], () => writeManifest(p, m));
+  else writeManifest(p, m);
   return p;
 }

package/src/harness/next-step.ts

@@ -16,10 +16,20 @@
  */
 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 type { HeadSnapshot } from '../contract/contract-git';
+import { boardHumanActions } from '../graph/board-human-actions';
+import { evaluateGraph, evaluateHumanActions, EvaluateOptions } from '../graph/evaluate-graph';
+import type { HumanAction } from '../graph/human-action';
+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';
+import { ResultsFreshness, resultsFreshness } from '../graph/unit-results-freshness';
 
 export interface NextStep {
   /** The command to run, as the operator would type it. */
@@ -34,6 +44,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 {
@@ -48,6 +65,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;
@@ -62,94 +86,57 @@ 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[];
+  /** Which run the results come from and what they are older than (#942); absent without results. Advisory, decides no step. */
+  results?: ResultsFreshness;
   steps: NextStep[];
+  /**
+   * Every pending HUMAN-ONLY action ("Waiting for you", #954): the frontier's decisions (deriveHumanActions)
+   * and the board's asks (sign-off, a waiver to give again, a decision recorded during the run). Set by
+   * readUnitState; commands canonical (`sungen …`). An agent presents them and never runs them.
+   */
+  humanActions?: HumanAction[];
+  /**
+   * The title of the blocking step that cut the frontier: past it only actions that do not depend on it
+   * are listed (sign-off, accept-in-run and the first contract approval wait). Absent when nothing cuts.
+   */
+  humanActionsHeldBy?: string;
+  /** The canonical command of that blocking step (#966) — what clears the hold. */
+  humanActionsHeldByCommand?: string;
 }
 
-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"
-  }
-}
-
-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;
+export interface ReadUnitStateOptions {
+  /** git HEAD read once for many units (`sungen next` with no unit). */
+  gitSnapshot?: HeadSnapshot;
 }
 
-/**
- * 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 };
@@ -160,13 +147,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 && !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
@@ -181,131 +171,39 @@ 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 */ }
+  try {
+    const results = resultsFreshness(projectRoot, unitDir, unit);
+    if (results) state.results = results;
+  } catch { /* advisory: results that cannot be dated add nothing */ }
   state.steps = deriveSteps(state);
+  const graph = evaluateHumanActions(CORE_NODES, state, state.testCases);
+  const seen = new Set<string>();
+  state.humanActions = [...graph.actions, ...boardHumanActions(projectRoot, unitDir, state, graph.cut)]
+    .filter((a) => !seen.has(a.command) && Boolean(seen.add(a.command)));
+  if (graph.heldBy) state.humanActionsHeldBy = graph.heldBy;
+  if (graph.heldByCommand) state.humanActionsHeldByCommand = graph.heldByCommand;
   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}`;
+export function deriveSteps(s: UnitState, opts: EvaluateOptions = {}): NextStep[] {
+  return evaluateGraph(CORE_NODES, s, s.testCases, opts);
+}
 
-  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;
+/** The human-only actions of the same frontier (#954) — the graph's part of `humanActions`, without the board. */
+export function deriveHumanActions(s: UnitState): HumanAction[] {
+  return evaluateHumanActions(CORE_NODES, s, s.testCases).actions;
 }

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 }>;
@@ -404,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));
 }
 
 /**