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

package/src/harness/journey.ts

@@ -17,8 +17,16 @@ import * as path from 'path';
 import * as crypto from 'crypto';
 import { reportSlug } from './unit-paths';
 import { readTextFile } from './read-text';
+import { assertNoPendingMigration } from '../basis/migration-sentinel';
+import { commitWaiverSync, planWaiverSync, recordWaiver, untrustedWaiverText } from '../decisions/legacy-waiver-migration';
+import { DecisionConflictError } from '../decisions/append-decision';
+import { resolveRule } from './gates/resolve-rule';
+import { applyAuditOverrides, decisionFindingText, DecisionGateFinding, ignoredOverrideText, journeyDecisionFindings, readJourneyAudit, unitOverrides } from './gates/journey-gate-inputs';
+import { IN_RUN_RULE, uncommittedReleaseDecisions } from './gates/in-run-decision-check';
+import { PROJECT_SCOPE } from '../decisions/decision-file';
 
-export type ObStatus = 'satisfied' | 'needs-work' | 'pending' | 'waived';
+/** `overridden`: the audit recorded a gate-override on the obligation's rule (OES-11.2) — accepted like a waiver. */
+export type ObStatus = 'satisfied' | 'needs-work' | 'pending' | 'waived' | 'overridden';
 
 export interface Obligation {
   id: string;
@@ -26,6 +34,7 @@ export interface Obligation {
   status: ObStatus;
   detail: string;
   waivedReason?: string;   // S2 — set when the QA explicitly waived this obligation
+  overriddenBy?: string;   // P0 — the gate-override decision the audit applied to this obligation's rule
 }
 
 /** S5 — a parsed anchor so an IDE can jump straight to what needs review. */
@@ -42,6 +51,10 @@ export interface JourneyReport {
   obligations: Obligation[];
   needsYou: ReviewItem[];           // S5 — the review queue: human-judgment findings, each with an anchor
   nextSuggested: string;
+  /** T3 — set when an audit report exists but does not count (stale or untrusted). */
+  auditNotCounted?: string;
+  /** Decision files that do not verify, edited committed entries, rejected overrides — hard, block the gate. */
+  decisionFindings?: DecisionGateFinding[];
 }
 
 function readJSON(p: string): any {
@@ -74,7 +87,11 @@ const SAT = 0.8; // axis at/above this = satisfied (below = needs-work)
 
 function computeFresh(projectRoot: string, unit: string): JourneyReport {
   const slug = reportSlug(unit);
-  const audit = readJSON(path.join(projectRoot, '.sungen', 'reports', `${slug}-audit.json`));
+  // T3: the report is an output — read through the checks; stale or untrusted counts as never audited.
+  const read = readJourneyAudit(projectRoot, unit);
+  const notCountedReason = read.notCountedReason;
+  // The verifier checked the top-level keys and types; nested fields are read defensively below, as before.
+  const audit = read.audit as any;
   const phases = readLedgerPhases(path.join(projectRoot, '.sungen', 'ledger', `${slug}.jsonl`));
 
   const from: string[] = [];
@@ -89,10 +106,11 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
 
   if (!audit) {
     // Nothing measured yet — the journey hasn't really begun.
-    obligations.push({ id: 'OB-create', title: 'Generate test cases', status: 'pending', detail: 'No audit report yet — run /sungen:create-test.' });
+    obligations.push({ id: 'OB-create', title: 'Generate test cases', status: 'pending', detail: notCountedReason ?? 'No audit report yet — run /sungen:create-test.' });
     return {
-      unit, generatedFrom: from, youAreHere, phasesDone: phases, gateStatus: null, score: null,
-      obligations, needsYou, nextSuggested: 'Run `/sungen:create-test ' + unit + '` to begin.',
+      unit, generatedFrom: from, youAreHere, phasesDone: phases, gateStatus: null, score: null, obligations, needsYou,
+      nextSuggested: notCountedReason ?? 'Run `/sungen:create-test ' + unit + '` to begin.',
+      ...(notCountedReason ? { auditNotCounted: notCountedReason } : {}),
     };
   }
 
@@ -116,6 +134,8 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
     status: autoPending ? 'needs-work' : 'satisfied',
     detail: autoPending ? `${audit.automatableManual.automatable} @manual scenario(s) a driver could automate` : 'no capability-pending automatable cases',
   });
+  // What the audit already applied — never re-applied here, and only while that override is in force.
+  const ignored = applyAuditOverrides(obligations, audit, unitOverrides(projectRoot, unit).inForce);
 
   // Needs-you: the review queue. Prefer PRECISE per-scenario anchors from audit's structured
   // depth data — each shallow business-critical scenario carries its own VP id — over regex-parsing
@@ -128,6 +148,7 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
       anchor: extractAnchor(s.name),
     });
   }
+  for (const g of ignored) needsYou.push({ text: ignoredOverrideText(g), anchor: {} });
   const haveStructuredDepth = shallowBC.length > 0;
   for (const f of (audit.findings || [])) {
     if (!isHumanFinding(f)) continue;
@@ -143,7 +164,7 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
   });
 
   // Next suggested = first non-satisfied obligation; if all satisfied but run-test not done → run.
-  const firstGap = obligations.find((o) => o.status !== 'satisfied' && o.id !== 'OB-signoff');
+  const firstGap = obligations.find((o) => o.status !== 'satisfied' && o.status !== 'overridden' && o.id !== 'OB-signoff');
   let nextSuggested: string;
   if (firstGap) nextSuggested = `Repair "${firstGap.title}" (${firstGap.detail}).`;
   else if (!ran('run')) nextSuggested = `Quality satisfied — run \`/sungen:run-test ${unit}\`.`;
@@ -158,9 +179,9 @@ function computeFresh(projectRoot: string, unit: string): JourneyReport {
 
 // ---------------- S2: writable lifecycle — persisted waivers + reconcile ----------------
 
-interface Waiver { reason: string; at: string; auditHashAtWaive: string; }
-interface Signoff { by?: string; at: string; auditHashAtSignoff: string; }   // S5
-interface JourneyState { unit: string; auditHash: string; waivers: Record<string, Waiver>; signoff?: Signoff; }
+// Waivers live in the decision layer (DOS-13.5); this file keeps a dual-written copy for one release.
+interface Signoff { by?: string; at: string; auditHashAtSignoff: string; }   // S5 — stays here in P0
+interface JourneyState { unit: string; auditHash: string; waivers: Record<string, unknown>; signoff?: Signoff; }
 
 function statePath(projectRoot: string, slug: string): string {
   return path.join(projectRoot, '.sungen', 'journey', `${slug}.state.json`);
@@ -176,9 +197,14 @@ function saveState(p: string, s: JourneyState): void {
   fs.writeFileSync(p, JSON.stringify(s, null, 2), 'utf-8');
 }
 
+/** An obligation that does not block: met, waived by a human, or overridden by the audit's gate-override. */
+const accepted = (s: ObStatus): boolean => s === 'satisfied' || s === 'waived' || s === 'overridden';
+
 /** Recompute nextSuggested AFTER waivers are applied (a waived obligation is not a gap). */
 function computeNext(r: JourneyReport, unit: string): string {
-  const gap = r.obligations.find((o) => o.status !== 'satisfied' && o.status !== 'waived' && o.id !== 'OB-signoff');
+  const bad = r.decisionFindings?.[0];
+  if (bad) return `Resolve ${r.decisionFindings!.length} decision problem(s) first — ${bad.rule} on ${bad.path}.`;
+  const gap = r.obligations.find((o) => !accepted(o.status) && o.id !== 'OB-signoff');
   if (gap) return `Repair "${gap.title}" (${gap.detail}).`;
   if (!r.phasesDone.some((s) => s === 'run' || s.startsWith('run'))) return `Quality satisfied — run \`/sungen:run-test ${unit}\`.`;
   return `All obligations satisfied/waived — review the ${r.needsYou.length} queued item(s), then sign off & deliver.`;
@@ -190,16 +216,25 @@ function computeNext(r: JourneyReport, unit: string): string {
  *  - an active waiver (evidence unchanged) sets status='waived' (carries the reason);
  *  - a STALE waiver (audit changed since it was waived) is re-surfaced for re-decision (anti-amnesia).
  * Then persist the current evidence cursor.
+ * Waivers in force come from the decision layer; legacy waivers that match git HEAD are imported once,
+ * others are UNTRUSTED (not counted, listed for a human), and the result is dual-written back.
+ * A read-only checkout gets the same board without throwing.
  */
 export function runJourney(projectRoot: string, unit: string): JourneyReport {
   const slug = reportSlug(unit);
+  assertNoPendingMigration(projectRoot, slug);
   const report = computeFresh(projectRoot, unit);
   const sp = statePath(projectRoot, slug);
   const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
   const curHash = auditHashOf(projectRoot, slug);
+  const sync = planWaiverSync(projectRoot, unit, slug, sp, state.waivers);
+  for (const u of sync.untrusted) {
+    const title = report.obligations.find((o) => o.id === u.obligation)?.title ?? u.obligation;
+    report.needsYou.unshift({ text: untrustedWaiverText(unit, slug, title, u), anchor: { vpId: u.obligation } });
+  }
 
   for (const ob of report.obligations) {
-    const w = state.waivers[ob.id];
+    const w = sync.waivers[ob.id];
     if (!w) continue;
     if (w.auditHashAtWaive === curHash) {
       ob.status = 'waived';
@@ -220,8 +255,21 @@ export function runJourney(projectRoot: string, unit: string): JourneyReport {
       report.needsYou.unshift({ text: `⚠️ Sign-off is STALE (suite changed since ${state.signoff.at}) — re-review and sign off again.`, anchor: { vpId: 'OB-signoff' } });
     }
   }
+  // Phase-03 carry-over: a decision that does not verify is a FINDING the gate blocks on, not a crash.
+  const decisionFindings = journeyDecisionFindings(projectRoot, unitOverrides(projectRoot, unit));
+  const next: JourneyState = { unit, auditHash: curHash, waivers: sync.stateWaivers, signoff: state.signoff };
+  try {
+    commitWaiverSync(projectRoot, unit, slug, sync, sp, JSON.stringify(next, null, 2));
+  } catch (err) {
+    if (!(err instanceof DecisionConflictError)) throw err;
+    const rel = path.relative(projectRoot, err.path).split(path.sep).join('/');
+    if (!decisionFindings.some((f) => f.path === rel)) decisionFindings.push({ rule: 'decision.mutated', path: rel, message: err.message });
+  }
+  if (decisionFindings.length) {
+    report.decisionFindings = decisionFindings;
+    for (const f of [...decisionFindings].reverse()) report.needsYou.unshift({ text: decisionFindingText(f), anchor: { file: f.path } });
+  }
   report.nextSuggested = computeNext(report, unit);
-  saveState(sp, { unit, auditHash: curHash, waivers: state.waivers, signoff: state.signoff });
   return report;
 }
 
@@ -234,16 +282,14 @@ export function waive(projectRoot: string, unit: string, obId: string, reason: s
     throw new Error('A reason is required to waive (anti-amnesia: a waiver must record WHY). Use --reason "...".');
   }
   const slug = reportSlug(unit);
-  const fresh = computeFresh(projectRoot, unit);
+  const fresh = runJourney(projectRoot, unit);   // stops on a pending migration; imports legacy waivers first
   const valid = fresh.obligations.map((o) => o.id);
   if (!valid.includes(obId)) {
     throw new Error(`Unknown obligation "${obId}". Valid: ${valid.join(', ')}`);
   }
-  const sp = statePath(projectRoot, slug);
-  const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
-  state.waivers[obId] = { reason: reason.trim(), at: new Date().toISOString(), auditHashAtWaive: auditHashOf(projectRoot, slug) };
-  saveState(sp, state);
-  return runJourney(projectRoot, unit);
+  const given = { reason: reason.trim(), at: new Date().toISOString(), auditHashAtWaive: auditHashOf(projectRoot, slug) };
+  recordWaiver(projectRoot, unit, obId, given);   // DOS-13.5: the decision layer is the record …
+  return runJourney(projectRoot, unit);           // … and runJourney dual-writes it to the legacy file
 }
 
 /**
@@ -253,7 +299,10 @@ export function waive(projectRoot: string, unit: string, obId: string, reason: s
  */
 export function signoff(projectRoot: string, unit: string, by?: string): JourneyReport {
   const before = runJourney(projectRoot, unit);
-  const blockers = before.obligations.filter((o) => o.id !== 'OB-signoff' && o.status !== 'satisfied' && o.status !== 'waived');
+  const blockers = before.obligations.filter((o) => o.id !== 'OB-signoff' && !accepted(o.status));
+  if (before.decisionFindings?.length) {
+    throw new Error(`Cannot sign off — ${before.decisionFindings.length} decision problem(s): ${before.decisionFindings.map((f) => `${f.rule} ${f.path}`).join(', ')}.`);
+  }
   if (blockers.length) {
     throw new Error(`Cannot sign off — still open: ${blockers.map((b) => b.id).join(', ')}. Fix, or waive each with a reason, first.`);
   }
@@ -265,7 +314,24 @@ export function signoff(projectRoot: string, unit: string, by?: string): Journey
   return runJourney(projectRoot, unit);
 }
 
-const ICON: Record<ObStatus, string> = { satisfied: '✅', 'needs-work': '⚠️ ', pending: '⏳', waived: '🚫' };
+const UNWRITABLE = new Set(['EACCES', 'EROFS', 'ENOSPC', 'EPERM']);
+
+/**
+ * Write a DERIVED journey file (board, report, roll-up). Best-effort by contract (DOS-13.3): a read-only
+ * or full checkout still shows the board — the file is skipped and null returned; any other error throws.
+ */
+export function writeJourneyFileBestEffort(file: string, text: string): string | null {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, text, 'utf-8');
+    return file;
+  } catch (err) {
+    if (UNWRITABLE.has((err as NodeJS.ErrnoException)?.code ?? '')) return null;
+    throw err;
+  }
+}
+
+const ICON: Record<ObStatus, string> = { satisfied: '✅', 'needs-work': '⚠️ ', pending: '⏳', waived: '🚫', overridden: '🔓' };
 
 export function renderJourneyBoard(r: JourneyReport): string {
   const L: string[] = [];
@@ -308,6 +374,10 @@ export interface GateVerdict {
   required: string[];
   blockers: { id: string; title: string; detail: string }[];
   waivedCredit: { id: string; title: string }[]; // required obligations accepted via an explicit waiver
+  /** Required obligations accepted because the audit applied a gate-override to their rule. */
+  overriddenCredit?: { id: string; title: string; by: string }[];
+  /** The phase rule itself was lowered by this gate-override: the open obligations do not halt. */
+  phaseOverriddenBy?: string;
 }
 
 const PHASE_REQUIRED: Record<GatePhase, string[]> = {
@@ -319,23 +389,48 @@ const PHASE_REQUIRED: Record<GatePhase, string[]> = {
   deliver: ['OB-spec', 'OB-coverage', 'OB-depth', 'OB-trace', 'OB-automation', 'OB-signoff'],
 };
 
+/** The catalog rule each phase boundary halts by (OES-11.2): soft, so a reasoned override may lower it. */
+const PHASE_RULE: Record<GatePhase, string> = { create: 'journey.phase-create', run: 'journey.phase-run', deliver: 'journey.phase-deliver' };
+
 export function runGate(projectRoot: string, unit: string, phase: GatePhase): GateVerdict {
   const r = runJourney(projectRoot, unit);
   const required = PHASE_REQUIRED[phase];
-  const reqObs = r.obligations.filter((o) => required.includes(o.id));
-  const blockers = reqObs
-    .filter((o) => o.status !== 'satisfied' && o.status !== 'waived')
-    .map((o) => ({ id: o.id, title: o.title, detail: o.detail }));
+  // T3: a unit never audited (or whose report does not count) is never clean — OB-create blocks every phase.
+  const reqObs = r.obligations.filter((o) => required.includes(o.id) || o.id === 'OB-create');
+  const asBlocker = (o: Obligation) => ({ id: o.id, title: o.title, detail: o.detail });
+  // Never audited is not something a lowered phase rule may wave through (review M4).
+  const neverAudited = reqObs.filter((o) => o.id === 'OB-create' && !accepted(o.status)).map(asBlocker);
+  const open = reqObs.filter((o) => o.id !== 'OB-create' && !accepted(o.status)).map(asBlocker);
+  const overrides = unitOverrides(projectRoot, unit);
+  // Decision problems are hard rules: no phase override lowers them. At the release boundary an
+  // override, waiver or approval git HEAD does not hold is refused too (decision.in-run, review H1).
+  const scopes = [PROJECT_SCOPE, ...(overrides.unitScope ? [overrides.unitScope] : [])];
+  const hard = [
+    ...(r.decisionFindings ?? []).filter((f) => resolveRule(f.rule).blocking)
+      .map((f) => ({ id: f.rule, title: 'Decision integrity', detail: `${f.path} — ${f.message}` })),
+    ...(phase === 'deliver' && resolveRule(IN_RUN_RULE).blocking ? uncommittedReleaseDecisions(projectRoot, scopes) : [])
+      .map((d) => ({ id: IN_RUN_RULE, title: 'Decision not reviewed', detail: `${d.kind} ${d.id} (${d.path}) — ${d.why.join('; ')}` })),
+    ...neverAudited,
+  ];
+  const phaseRule = resolveRule(PHASE_RULE[phase], overrides.context);
+  const blockers = [...hard, ...open];
+  const halt = hard.length > 0 || (open.length > 0 && phaseRule.blocking);
   const waivedCredit = reqObs.filter((o) => o.status === 'waived').map((o) => ({ id: o.id, title: o.title }));
-  return { unit, phase, status: blockers.length ? 'halt' : 'pass', required, blockers, waivedCredit };
+  const overriddenCredit = reqObs.filter((o) => o.status === 'overridden').map((o) => ({ id: o.id, title: o.title, by: o.overriddenBy ?? '' }));
+  return {
+    unit, phase, status: halt ? 'halt' : 'pass', required, blockers, waivedCredit,
+    ...(overriddenCredit.length ? { overriddenCredit } : {}),
+    ...(open.length && phaseRule.overriddenBy ? { phaseOverriddenBy: phaseRule.overriddenBy } : {}),
+  };
 }
 
 export function renderGate(v: GateVerdict): string {
   const L: string[] = [];
   L.push('');
   L.push(`━━━ Gate: ${v.unit} @ phase "${v.phase}" → ${v.status === 'pass' ? '✅ PASS' : '⛔ HALT'} ━━━`);
+  if (v.phaseOverriddenBy) L.push(`  Phase rule lowered by ${v.phaseOverriddenBy}: open obligations are advisory (decision problems still block).`);
   if (v.blockers.length) {
-    L.push('  Blocking obligations (must be satisfied or explicitly waived):');
+    L.push(v.phaseOverriddenBy ? '  Open obligations:' : '  Blocking obligations (must be satisfied or explicitly waived):');
     for (const b of v.blockers) L.push(`   • ${b.id} ${b.title} — ${b.detail}`);
     L.push('  → Self-correct (repair / run-test), or `sungen journey --screen ' + v.unit + ' --waive <OB> --reason "..."` if accepted.');
   } else {
@@ -388,7 +483,7 @@ export function rollupJourney(projectRoot: string): UnitSummary[] {
     const r = runJourney(projectRoot, unit);
     const signedOff = r.obligations.find((o) => o.id === 'OB-signoff')?.status === 'satisfied';
     const obligationsOpen = r.obligations.filter(
-      (o) => o.id !== 'OB-signoff' && o.status !== 'satisfied' && o.status !== 'waived',
+      (o) => o.id !== 'OB-signoff' && !accepted(o.status),
     ).length;
     return {
       unit, kind, score: r.score, gateStatus: r.gateStatus, youAreHere: r.youAreHere,

package/src/harness/manifest.ts

@@ -6,20 +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
 }
 
@@ -32,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)';
 
 /**
@@ -60,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. */
@@ -86,12 +88,11 @@ 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();
-      const code = name.match(/\bVP-[A-Z]+-\d+/i)?.[0];
-      out.push({ scenario: name, vpCode: code, section });
+      out.push({ scenario: name, vpCode: vpCodeOf(name).vpCode, section });
     }
   }
   return out;
@@ -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;
 }