@try-works/dsh-recursive-mode 0.3.1 → 0.4.0

package/scripts/live-session.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * FU-10 — THE LIVE-SESSION HARNESS.
+ *
+ * WHAT IT DOES. Opens a REAL `dsh` session in a temp folder on `E:` with a profile that mounts THIS plugin
+ * (by file URL — no install, no dependency added) and a scripted LLM, then reads the session log back.
+ *
+ * WHY IT EXISTS. FU-9 claims something the in-process harness cannot show: a delegation that reaches a
+ * REAL live Agent, because the continuable seam requires the exact Agent ("never a `{ id }` copy"). It is
+ * also the only way to measure whether a real session mounts a workflow engine at all, which is what
+ * FU-6's live half turns on.
+ *
+ * ⚠ OUTPUT GOES TO FILES, NOT PIPES. This sandbox denies a child process the piped stdio that capturing
+ * stdout needs (measured: EPERM), so the launch redirects the child's stdout/stderr to files and the
+ * harness reads those. The same constraint is why FU-5's extractor talks through a response file.
+ *
+ * ⚠ `src` MODE, because resolution comes from the HARNESS's tsconfig path mappings (`TSX_TSCONFIG_PATH`),
+ * not from a `node_modules` beside the temp profile — and `E:` has none.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, openSync, closeSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const HARNESS = 'D:\\deepseek-harness'
+const PLUGIN = 'D:\\DEV\\dsh-recursive-mode'
+const SRC_BIN = join(HARNESS, 'apps', 'cli', 'src', 'bin.ts')
+const TSCONFIG = join(HARNESS, 'tsconfig.json')
+
+const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+const base = join(existsSync('E:\\') ? 'E:\\dsh-rm-live' : join(process.env.TEMP ?? '.', 'dsh-rm-live'), 'live-' + stamp)
+const home = join(base, '.dsh')
+const repo = join(base, 'repo')
+const sessions = join(home, 'sessions')
+// ⚠ THE PROFILE IS NAMED `headless`, AND NO COMMAND WORD IS PASSED. Measured: invoking the CLI as
+// `… headless --profile live` fails with *"select a profile only once"* — the first positional is itself a
+// profile selection. The harness's own e2e therefore writes its profile to `profiles/headless` and passes
+// only `--profile headless <prompt>`.
+const profileDir = join(home, 'profiles', 'headless')
+
+const PROMPT = process.argv[2] ?? 'Run recursive_init for run live-run, then ask recursive_review to review phase 03.'
+
+function fileUrl(path) {
+  return 'file:///' + path.replace(/\\/g, '/')
+}
+
+mkdirSync(profileDir, { recursive: true })
+mkdirSync(sessions, { recursive: true })
+mkdirSync(join(repo, 'src'), { recursive: true })
+writeFileSync(join(repo, 'README.md'), '# live session scratch repo\n', 'utf8')
+spawnSync('git', ['init', '-q'], { cwd: repo, stdio: 'ignore' })
+
+// The profile: the harness's own two bundles, plus OUR plugin inserted by file URL (the pattern the
+// harness uses for its own fixture), plus the scripted LLM.
+writeFileSync(join(profileDir, 'package.json'), JSON.stringify({
+  name: 'dsh-profile-headless',
+  private: true,
+  dsh: { profile: { bundles: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'] } },
+}, undefined, 2) + '\n', 'utf8')
+
+writeFileSync(join(profileDir, 'cordis.patch.yml'), [
+  '- id: llm-deepseek',
+  '  disabled: true',
+  '- id: session-persistence-jsonl',
+  '  config:',
+  "    root: '" + sessions.replace(/\\/g, '/') + "'",
+  '    compression: none',
+  '- insert:',
+  '    - id: live-fixture-llm',
+  "      name: '" + fileUrl(join(PLUGIN, 'scripts', 'live', 'fake-llm.mjs')) + "'",
+  '    - id: recursive-mode',
+  "      name: '" + fileUrl(join(PLUGIN, 'src', 'index.ts')) + "'",
+  '',
+].join('\n'), 'utf8')
+
+/**
+ * ⚠ THE CHILD INHERITS `DSH_PROFILE=web` FROM THE SESSION THAT LAUNCHED IT, which made the CLI fail with
+ * "select a profile only once" — the environment supplied one profile and the arguments another. A live
+ * session must not inherit its parent's identity at all, so the launch env is filtered rather than spread.
+ */
+function cleanEnv() {
+  const env = { ...process.env }
+  for (const key of ['DSH_PROFILE', 'DSH_PROFILE_DIR', 'DSH_SESSION_ID', 'DSH_SHELL', 'DSH_WEB_URL']) {
+    delete env[key]
+  }
+  return env
+}
+const outFile = join(base, 'stdout.txt')
+const errFile = join(base, 'stderr.txt')
+const outFd = openSync(outFile, 'w')
+const errFd = openSync(errFile, 'w')
+
+console.log('[live] base:    ' + base)
+console.log('[live] home:    ' + home)
+console.log('[live] repo:    ' + repo)
+
+// ⚠ THE tsx **CLI**, NOT `--import tsx`. Measured: `node --import tsx` resolves the specifier relative to
+// the CWD, so a temp repo on `E:` gives `ERR_MODULE_NOT_FOUND: Cannot find package 'tsx'`, and `NODE_PATH`
+// does not help because it applies to CommonJS resolution only. Running tsx's own CLI by absolute path
+// makes it resolve its dependencies from ITS location instead of the session's.
+const TSX_LOADER = 'file:///D:/deepseek-harness/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/dist/loader.mjs'
+
+const result = spawnSync(process.execPath, [
+  '--import', TSX_LOADER,
+  SRC_BIN,
+  'headless',
+  '--profile', 'headless',
+  PROMPT,
+], {
+  cwd: repo,
+  // ⚠ Files, not pipes — see the header note.
+  stdio: ['ignore', outFd, errFd],
+  env: {
+    ...cleanEnv(),
+    DSH_HOME: home,
+    DSH_AGENTS_HOME: join(base, '.agents'),
+    DSH_TELEMETRY_DISABLED: '1',
+    DEEPSEEK_API_KEY: '',
+    TSX_TSCONFIG_PATH: TSCONFIG,
+    // tsx and the harness's own modules live in the checkout, which is not an ancestor of the temp dir.
+    NODE_PATH: join(HARNESS, 'node_modules'),
+  },
+})
+closeSync(outFd)
+closeSync(errFd)
+
+console.log('[live] exit:    ' + result.status + (result.error ? ' (spawn error: ' + result.error.message + ')' : ''))
+const stdout = existsSync(outFile) ? readFileSync(outFile, 'utf8') : ''
+const stderr = existsSync(errFile) ? readFileSync(errFile, 'utf8') : ''
+console.log('[live] stdout:  ' + stdout.length + ' bytes | stderr: ' + stderr.length + ' bytes')
+if (stdout.trim() !== '') console.log('--- stdout tail ---\n' + stdout.trim().split('\n').slice(-12).join('\n'))
+if (stderr.trim() !== '') console.log('--- stderr tail ---\n' + stderr.trim().split('\n').slice(-12).join('\n'))
+
+const logs = existsSync(sessions)
+  ? readdirSync(sessions, { recursive: true }).map(String).filter((name) => name.endsWith('.jsonl'))
+  : []
+console.log('[live] session logs: ' + logs.length)
+for (const log of logs) console.log('        ' + join(sessions, log))
+console.log('[live] reached review marker: ' + stdout.includes('LIVE_SESSION_REACHED_REVIEW'))
+process.exit(result.status ?? 1)

package/src/client/derive.ts

@@ -114,6 +114,13 @@ export interface RecursiveCardFacts {
   subagents: RecursiveSubagentChip[]
 }
 
+/** T21: the single derived positions present on a card's rows, in phase order. */
+function rowPositions(card: RecursiveRunCard): string[] {
+  return Object.values(card.phases)
+    .map((row) => row.position)
+    .filter((p): p is NonNullable<typeof p> => p !== undefined)
+}
+
 /** Derive §11.4 presentation facts from one card (no fs, no session). */
 export function cardFacts(card: RecursiveRunCard): RecursiveCardFacts {
   const groups = new Set<string>()
@@ -148,12 +155,21 @@ export function cardFacts(card: RecursiveRunCard): RecursiveCardFacts {
     }
   }
 
-  const tampered = Object.keys(card.tampers).length > 0
+  const tampered = Object.keys(card.tampers).length > 0 || rowPositions(card).includes('tampered')
   // Lock validity: tampered beats everything; else every MANDATORY phase present
   // and LOCKED -> locked; else still in-progress (01.5 stays optional).
+  //
+  // T21: when a row carries the server's single derived `position`, USE IT rather
+  // than recombining `status` here. Recombining is how this consumer came to call
+  // a LOCKED-but-gate-failing phase "locked" while the server's fold called it
+  // `invalid-lock` — two consumers, two answers, one phase. The `status` test
+  // remains as the fallback for a row produced before `position` existed.
   const allMandatoryLocked = MANDATORY_GROUPS.every((g) => {
     const row = Object.entries(card.phases).find(([key]) => phaseGroupOf(key) === g)
-    return row !== undefined && row[1].status === 'LOCKED'
+    if (row === undefined) return false
+    const phase = row[1]
+    if (phase.position !== undefined) return phase.position === 'locked'
+    return phase.status === 'LOCKED'
   })
   const lockValidity: RecursiveCardFacts['lockValidity'] = tampered
     ? 'tampered'

package/src/closeout-report.ts

@@ -0,0 +1,274 @@
+/**
+ * Closeout report (FU-12) — the closeout as a LINTER, not a writer.
+ *
+ * ⚠ THE DESIGN, in the user's words: *"closeout.ts is supposed to verify whether the phase artifact docs
+ * contain the scaffold information or not, then tell the agent to add it if not. It is not supposed to just
+ * insert section titles into the docs. It is like a linter checking if the agent missed anything. It is not
+ * supposed to edit files by itself."*
+ *
+ * ⚠ WHAT THIS MODULE THEREFORE DOES NOT DO: it opens no file for writing. The previous implementation called
+ * `mkdirSync` and `writeFileSync` to compose a stub receipt over the phase artifact — and a probe in a temp
+ * run folder showed what that costs: against a DRAFT `05-manual-qa.md` it RETURNED SUCCESS while the agent's
+ * real QA content was GONE. A closeout runs BEFORE a phase locks, so that was the ordinary case, not an edge.
+ *
+ * ⚠ AND WHERE THE STANDARD COMES FROM: `phase-rules.ts` and `ts-lint.ts` already own it — required sections
+ * (`getArtifactRequiredSections`, profile-aware), gate lines (`getGateStatus`), the artifact sequence
+ * (`RUN_ARTIFACT_SEQUENCE`), and the guidance text to hand the agent (`phaseLintRulesMessage`). This module
+ * adds no vocabulary of its own: three separate defects in this repo came from inventing a private copy of
+ * something that already had one home.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { getLockStatus } from './lock.ts'
+import { CURRENT_WORKFLOW_PROFILE, phaseLintRulesMessage } from './phase-rules.ts'
+import { RUN_ARTIFACT_SEQUENCE, getGateStatus, hasHeading } from './ts-lint.ts'
+import { getPrerequisiteBlockers } from './lock.ts'
+import { getRunTreeAddenda } from './ts-lint.ts'
+
+/** Gate lines every phase document carries, written as `Coverage: PASS` / `Approval: PASS`. */
+const UNIVERSAL_GATES = ['Coverage', 'Approval'] as const
+
+/** The phase → artifact map. A LOOKUP, not a template: nothing here is ever rendered into a file. */
+export const CLOSEOUT_PHASE_FILES: Record<string, { file: string; label: string }> = {
+  '04': { file: '04-test-summary.md', label: '04 Test Summary' },
+  '05': { file: '05-manual-qa.md', label: '05 Manual QA' },
+  '06': { file: '06-decisions-update.md', label: '06 Decisions Update' },
+  '07': { file: '07-state-update.md', label: '07 State Update' },
+  '08': { file: '08-memory-impact.md', label: '08 Memory Impact' },
+}
+
+/** One thing the agent must add or fix before the artifact can lock. */
+export interface CloseoutFinding {
+  kind: 'missing-artifact' | 'missing-section' | 'gate-not-passing'
+  /** Directory-ready: what is wrong, in the words the agent should act on. */
+  detail: string
+}
+
+export interface CloseoutReport {
+  phase: string
+  artifact: string
+  label: string
+  exists: boolean
+  /** `LOCKED`, `DRAFT`, `STALE_LOCK`, `MISSING` — from the same reader the lock tool uses. */
+  status: string
+  /** Empty means the artifact fits the standard; the caller tells the agent only when it is not. */
+  findings: CloseoutFinding[]
+  /**
+   * Advisory only: earlier artifacts that are not yet LOCKED. **Not a refusal** — the reference treats these
+   * as warnings (*"hard enforcement happens at lock time"*), and a closeout that refuses here cannot do the
+   * one thing it exists for.
+   */
+  prerequisites: Array<{ artifact: string; status: string }>
+  /** The rules text to hand the agent, straight from the rules module. */
+  guidance: string[]
+  /** Addenda found anywhere in the run tree — cited as evidence, never written to. */
+  addenda: string[]
+}
+
+export interface CloseoutReportOptions {
+  workflowProfile?: string
+  /** Include the advisory prerequisite list. Default true. */
+  checkPrerequisites?: boolean
+}
+
+/**
+ * Examine one phase artifact and report what it is missing. **Reads only.**
+ *
+ * An absent artifact is a finding rather than an error: the closeout's job is to say what should be there,
+ * and "not written yet" is the most useful thing it can tell an agent at phase entry.
+ */
+export function closeoutReport(runDir: string, phase: string, options: CloseoutReportOptions = {}): CloseoutReport {
+  const entry = CLOSEOUT_PHASE_FILES[phase]
+  if (!entry) {
+    throw new Error('Unsupported closeout phase: ' + phase + ' (expected one of '
+      + Object.keys(CLOSEOUT_PHASE_FILES).join(', ') + ')')
+  }
+  const profile = options.workflowProfile ?? CURRENT_WORKFLOW_PROFILE
+  const path = join(runDir, entry.file)
+  const exists = existsSync(path)
+  const findings: CloseoutFinding[] = []
+  let status = 'MISSING'
+  let content = ''
+
+  if (!exists) {
+    findings.push({
+      kind: 'missing-artifact',
+      detail: entry.file + ' does not exist yet; write it before this phase can lock',
+    })
+  } else {
+    status = getLockStatus(path)
+    try { content = readFileSync(path, 'utf8') } catch { content = '' }
+    // The standard, asked of the module that owns it — never a private copy.
+    const required = requiredSectionsFor(entry.file, profile)
+    for (const heading of required) {
+      if (!hasHeading(content, heading)) {
+        findings.push({ kind: 'missing-section', detail: 'add the `## ' + heading + '` section and fill it in' })
+      }
+    }
+    for (const gate of UNIVERSAL_GATES) {
+      const gateStatus = getGateStatus(content, gate)
+      if (gateStatus !== 'PASS') {
+        findings.push({ kind: 'gate-not-passing', detail: gate + ' gate reads ' + gateStatus + '; it must read PASS' })
+      }
+    }
+  }
+
+  const prerequisites = (options.checkPrerequisites ?? true)
+    ? getPrerequisiteBlockers(runDir, entry.file).map((b) => ({ artifact: b.artifact, status: b.status }))
+    : []
+
+  return {
+    phase,
+    artifact: entry.file,
+    label: entry.label,
+    exists,
+    status,
+    findings,
+    prerequisites,
+    guidance: guidanceFor(entry.file, profile),
+    addenda: getRunTreeAddenda(runDir),
+  }
+}
+
+/**
+ * The required sections for an artifact, from the rules module.
+ *
+ * Kept behind a local indirection so the report has ONE place to change if the rules API moves, and so the
+ * import stays named where a reader looks for the standard.
+ */
+function requiredSectionsFor(file: string, profile: string): string[] {
+  return getArtifactRequiredSectionsImpl(file, profile)
+}
+
+/** The guidance text for an artifact, from the rules module. */
+function guidanceFor(file: string, profile: string): string[] {
+  const message = phaseLintRulesMessage(file, profile)
+  if (Array.isArray(message)) return message.map((line) => String(line))
+  return String(message).split('\n').filter((line) => line.trim() !== '')
+}
+
+// Imported this way so the rules dependency is visible as a single seam in the two helpers above.
+import { getArtifactRequiredSections as getArtifactRequiredSectionsImpl } from './phase-rules.ts'
+
+/** Anything in the run's artifact sequence that this report does not cover, for a whole-run sweep. */
+export function uncoveredArtifacts(): string[] {
+  const covered = new Set(Object.values(CLOSEOUT_PHASE_FILES).map((e) => e.file))
+  return RUN_ARTIFACT_SEQUENCE.filter((name) => !covered.has(name))
+}
+
+/**
+ * Where a closeout receipt lives: **its own file, beside the lock receipts, never over the artifact.**
+ *
+ * ⚠ FOLLOWS `lock.ts`'s `receiptPath`, which is the convention this plugin already has: a receipt is a JSON
+ * file under `<runDir>/locks/` named after the artifact stem. The closeout receipt deliberately does NOT
+ * reuse `<stem>.receipt.json` — that name belongs to the LOCK receipt, which carries a hash and is read by
+ * `getLockStatus`. A distinct suffix keeps them together without a collision.
+ */
+export function closeoutReceiptPath(runDir: string, phase: string): string {
+  const entry = CLOSEOUT_PHASE_FILES[phase]
+  if (!entry) throw new Error('Unsupported closeout phase: ' + phase)
+  return join(runDir, 'locks', entry.file.replace(/\.md$/, '') + '.closeout.receipt.json')
+}
+
+/**
+ * Record the report as a closeout receipt. **The only write in this module, and it is never the artifact.**
+ *
+ * ⚠ WHY A RECEIPT AT ALL, in the user's words: a closeout *"should potentially create a close out receipt,
+ * that is ok and valuable, as long as it doesnt overwrite the phase docs."* So the durable trace of "the
+ * closeout examined this phase" is a file of its own, and the phase document is read and reported on but
+ * never touched.
+ *
+ * The JSON is a plain projection of the report — no timestamp, so the receipt is a pure function of the run
+ * state and two calls on the same run produce identical bytes.
+ */
+export function writeCloseoutReceipt(runDir: string, phase: string, options: CloseoutReportOptions = {}) {
+  const report = closeoutReport(runDir, phase, options)
+  const path = closeoutReceiptPath(runDir, phase)
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, JSON.stringify(report, null, 2) + '\n', 'utf8')
+  // ⚠ PHASE 08 IS THE RUN'S LAST PHASE, so its receipt is also where the RUN-level receipt belongs: a receipt
+  // that "represents what was done in the run" has to cover the whole run, and the early artifacts are most
+  // of what was done. The per-phase receipt above stays as it was; this one is the run's.
+  const runReceipt = isFinalPhase(phase) ? writeRunCloseoutReceipt(runDir, options) : null
+  return { path, report, runReceipt }
+}
+
+/** Whether this phase is the run's final one — where the run-level receipt is written. */
+function isFinalPhase(phase: string): boolean {
+  return phase === '08' || phase === '08-memory-impact.md'
+}
+
+/** Where the RUN-level closeout receipt lives: the run root, one per run. */
+export function runCloseoutReceiptPath(runDir: string): string {
+  return join(runDir, 'closeout.receipt.json')
+}
+
+/** One artifact's line in the run-level receipt. */
+export interface RunArtifactState {
+  artifact: string
+  exists: boolean
+  /** `LOCKED`, `DRAFT`, `STALE_LOCK` — or `ABSENT` when the artifact was never written. */
+  status: string
+  /** Empty when this artifact fits the standard. */
+  findings: CloseoutFinding[]
+}
+
+export interface RunCloseoutReport {
+  /** Every artifact in the run's sequence, in order — 00 through 08, not only the closeout phases. */
+  artifacts: RunArtifactState[]
+  /** How many of them fit the standard, for a one-line summary. */
+  conforming: number
+}
+
+/**
+ * The RUN-level report: every artifact in the run, not just the phases the closeout reports on.
+ *
+ * ⚠ WHY IT SPANS 00–08: the user's point, and it is the right one — a receipt *"represents what was done in
+ * the run"*, so it must include the early artifacts. The earlier correction still holds and is not undone by
+ * this: the closeout must never WRITE those documents (`recursive_init` owns them). It READS them, holds them
+ * to the same standard, and records their state. Reading a broad set and writing a narrow one is exactly the
+ * distinction that was missing.
+ */
+export function runCloseoutReport(runDir: string, options: CloseoutReportOptions = {}): RunCloseoutReport {
+  const profile = options.workflowProfile ?? CURRENT_WORKFLOW_PROFILE
+  const artifacts: RunArtifactState[] = []
+
+  for (const artifact of RUN_ARTIFACT_SEQUENCE) {
+    const path = join(runDir, artifact)
+    if (!existsSync(path)) {
+      artifacts.push({ artifact, exists: false, status: 'ABSENT', findings: [] })
+      continue
+    }
+    const findings: CloseoutFinding[] = []
+    let content = ''
+    try { content = readFileSync(path, 'utf8') } catch { content = '' }
+    for (const heading of requiredSectionsFor(artifact, profile)) {
+      if (!hasHeading(content, heading)) {
+        findings.push({ kind: 'missing-section', detail: 'missing required section: ## ' + heading })
+      }
+    }
+    for (const gate of UNIVERSAL_GATES) {
+      const gateStatus = getGateStatus(content, gate)
+      if (gateStatus !== 'PASS') {
+        findings.push({ kind: 'gate-not-passing', detail: gate + ': ' + gateStatus })
+      }
+    }
+    artifacts.push({ artifact, exists: true, status: getLockStatus(path), findings })
+  }
+
+  return { artifacts, conforming: artifacts.filter((a) => a.exists && a.findings.length === 0).length }
+}
+
+/**
+ * Record the run-level receipt. **Its own file at the run root**, never a phase document.
+ *
+ * The JSON is a pure projection of the run state — no timestamp — so two calls on the same run produce
+ * identical bytes, which is what makes it comparable between runs.
+ */
+export function writeRunCloseoutReceipt(runDir: string, options: CloseoutReportOptions = {}) {
+  const report = runCloseoutReport(runDir, options)
+  const path = runCloseoutReceiptPath(runDir)
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, JSON.stringify(report, null, 2) + '\n', 'utf8')
+  return { path, report }
+}

package/src/closeout-standards.ts

@@ -0,0 +1,102 @@
+/**
+ * Closeout standards check (FU-12b) — does every artifact in a run fit the required standard?
+ *
+ * ⚠ WHAT THIS IS FOR, in the user's words: *"phase 6 7 8 writes the state decisions memory artifacts, and
+ * closeout just makes sure that all the artifacts fit the required standards."* The closeout does not author
+ * the ledgers. It holds the run to the standard and reports what is missing.
+ *
+ * ⚠ WHY IT READS `phase-rules` INSTEAD OF KEEPING ITS OWN LIST: the required sections already have exactly
+ * one home. `phase-rules.ts` owns them and is PROFILE-AWARE — it appends `AUDIT_REQUIRED_HEADINGS` for
+ * audited artifacts under a strict workflow profile, and `Prior Recursive Evidence Reviewed` for the files
+ * that need it. A private copy cannot match that, and this session has already produced three separate
+ * defects from exactly that duplication (the closeout's own `REQUIRED_SECTIONS`, the 00–03 stubs, and the
+ * `meta` block). So this module invents nothing: it asks the rules and reports the difference.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { getLockStatus } from './lock.ts'
+import { CURRENT_WORKFLOW_PROFILE, getArtifactRequiredSections } from './phase-rules.ts'
+import { RUN_ARTIFACT_SEQUENCE, getGateStatus, hasHeading } from './ts-lint.ts'
+
+/** Gate lines every phase document carries, as `Coverage: PASS|FAIL` / `Approval: PASS|FAIL`. */
+const UNIVERSAL_GATES = ['Coverage', 'Approval'] as const
+
+export interface StandardViolation {
+  /** Run-relative artifact name, or the sequence entry that was absent. */
+  artifact: string
+  kind: 'missing-artifact' | 'missing-section' | 'gate-not-passing' | 'not-locked'
+  /** What is wrong, spelled so a caller can print it without re-deriving anything. */
+  detail: string
+}
+
+export interface StandardsReport {
+  /** How many artifacts from the sequence were present and examined. */
+  checked: number
+  /** Artifacts in the sequence that do not exist yet — informational, not necessarily a failure. */
+  absent: string[]
+  violations: StandardViolation[]
+}
+
+export interface StandardsOptions {
+  /** Workflow profile whose rules apply; defaults to the current one, as every caller does. */
+  workflowProfile?: string
+  /**
+   * Report artifacts that are present but not LOCKED. **OFF by default**: a closeout runs mid-run and a DRAFT
+   * artifact is the normal state, so treating it as a violation would make the check useless exactly when it
+   * is most wanted. Callers that need an all-locked assertion ask for it.
+   */
+  requireLocked?: boolean
+}
+
+/**
+ * Examine every artifact in the run against the phase rules.
+ *
+ * Reports, per present artifact: required headings that are missing, gate lines that are missing or FAIL, and
+ * (only when `requireLocked`) a status that is not LOCKED. Absent artifacts are listed separately — during a
+ * closeout most of the sequence legitimately does not exist yet, and conflating "not written yet" with
+ * "written wrong" would bury the findings that matter.
+ */
+export function verifyRunStandards(runDir: string, options: StandardsOptions = {}): StandardsReport {
+  const profile = options.workflowProfile ?? CURRENT_WORKFLOW_PROFILE
+  const violations: StandardViolation[] = []
+  const absent: string[] = []
+  let checked = 0
+
+  for (const artifact of RUN_ARTIFACT_SEQUENCE) {
+    const path = join(runDir, artifact)
+    if (!existsSync(path)) { absent.push(artifact); continue }
+    checked += 1
+    let content = ''
+    try { content = readFileSync(path, 'utf8') } catch { continue }
+
+    for (const heading of getArtifactRequiredSections(artifact, profile)) {
+      if (!hasHeading(content, heading)) {
+        violations.push({ artifact, kind: 'missing-section', detail: 'missing required section: ## ' + heading })
+      }
+    }
+    for (const gate of UNIVERSAL_GATES) {
+      const status = getGateStatus(content, gate)
+      if (status !== 'PASS') {
+        violations.push({ artifact, kind: 'gate-not-passing', detail: gate + ': ' + status })
+      }
+    }
+    if (options.requireLocked === true) {
+      const status = getLockStatus(path)
+      if (status !== 'LOCKED') {
+        violations.push({ artifact, kind: 'not-locked', detail: 'status is ' + status })
+      }
+    }
+  }
+
+  return { checked, absent, violations }
+}
+
+/** One line per violation, for a tool result or a CLI print. Empty when the run fits the standard. */
+export function formatStandardsReport(report: StandardsReport): string[] {
+  const lines = report.violations.map((v) => v.artifact + ': ' + v.detail)
+  if (lines.length === 0) {
+    return ['All ' + report.checked + ' present artifact(s) fit the required standards'
+      + (report.absent.length > 0 ? ' (' + report.absent.length + ' not written yet)' : '') + '.']
+  }
+  return lines
+}

package/src/closeout.ts

@@ -1,11 +1,12 @@
 /**
  * Closeout receipt scaffolding (R2) — TS port of recursive-closeout.py.
- * Creates/updates Phase 4/5/6/7/8 delta-receipt stubs with canonical headers
+ * Creates/updates Phase 0-8 receipt stubs with canonical headers
  * and required sections, gated on prerequisite phases being LOCKED.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { getPrerequisiteBlockers } from './lock.ts'
+import { getLockStatus, getPrerequisiteBlockers } from './lock.ts'
+import { getRunTreeAddenda } from './ts-lint.ts'
 
 export interface CloseoutPhaseConfig {
   file: string
@@ -68,6 +69,7 @@ export const PHASE_CONFIG: Record<string, CloseoutPhaseConfig> = {
 }
 
 const REQUIRED_SECTIONS: Record<string, string[]> = {
+  // `recursive_lint` both know; these are the stub's minimum, not a replacement for them.
   '04': ['TODO', 'Pre-Test Implementation Audit', 'Environment', 'Execution Mode', 'Commands Executed (Exact)', 'Results Summary', 'Evidence and Artifacts', 'Failures and Diagnostics (if any)', 'Flake/Rerun Notes', 'Requirement Completion Status', 'Traceability', 'Coverage Gate', 'Approval Gate'],
   '05': ['TODO', 'Execution Mode', 'QA Execution Record', 'QA Scenarios and Results', 'User Sign-Off', 'Requirement Completion Status', 'Traceability', 'Coverage Gate', 'Approval Gate'],
   '06': ['TODO', 'Decisions Changes Applied', 'Rationale', 'Resulting Decision Entry', 'Traceability', 'Coverage Gate', 'Approval Gate'],
@@ -126,6 +128,12 @@ export interface CloseoutResult {
   file: string
   created: string[]
   existing: string[]
+  /**
+   * Every addendum found anywhere in the run tree, as run-relative paths — and cited in the scaffolded
+   * receipt. Optional on the TYPE so a caller that builds its own result literal still compiles; the
+   * closeout itself always populates it.
+   */
+  addenda?: string[]
 }
 
 export interface CloseoutOptions {
@@ -137,6 +145,12 @@ export interface CloseoutOptions {
  * Create or update a closeout receipt stub for the given phase.
  * Returns the file + created/existing lists. When strict, refuses phases whose
  * prerequisite artifacts are not all LOCKED (reuses lock.ts chain validation).
+ *
+ * ⚠ ADDENDA ARE PART OF THE CLOSEOUT WORK, and they are CITED, never written. An addendum closes a gap in
+ * an artifact that is already locked, which is precisely the kind of thing a receipt must account for — and
+ * they are not always in `addenda/`: the real ones sit beside the artifact they close, in the run ROOT. So
+ * the receipt lists every addendum in the run tree (see {@link getRunTreeAddenda}), and says so explicitly
+ * when there are none, because "we looked and found none" and "we never looked" must not read alike.
  */
 export function closeoutPhase(runDir: string, phase: string, opts: CloseoutOptions = {}): CloseoutResult {
   const config = PHASE_CONFIG[phase]
@@ -156,7 +170,25 @@ export function closeoutPhase(runDir: string, phase: string, opts: CloseoutOptio
   const filePath = join(runDir, config.file)
   const existed = existsSync(filePath)
 
+  // ⚠ FU-8 — A CLOSEOUT MUST NOT SILENTLY UNLOCK ITS OWN ARTIFACT. Found by the FU-1 harness: a
+  // closeout run after the phase had locked rewrote the file to `Status: \`DRAFT\`` while its RECEIPT
+  // still said LOCKED, leaving a run whose file and receipt disagree. The plugin publishes the rule this
+  // breaks, in the policy section a model reads every turn: *"Writes to a Status: LOCKED phase doc are
+  // denied/asked; reopen explicitly to edit."* The prerequisite check above guards EARLIER phases; this
+  // guards the artifact the closeout actually writes.
+  //
+  // ⚠ IT REFUSES RATHER THAN SKIPPING QUIETLY, and it names the remedy, because the caller's next move
+  // differs: a refusal means "reopen it first if you really mean to", while a silent skip would look
+  // like a successful closeout that changed nothing.
+  if (getLockStatus(filePath) === 'LOCKED') {
+    throw new Error(
+      'Artifact is LOCKED: ' + config.file + ' — the contract denies a write to a LOCKED phase doc; '
+      + 'reopen it explicitly (recursive_lock with reopen) before scaffolding its receipt',
+    )
+  }
+
   const runId = runDir.split(/[\\/]/).filter(Boolean).pop() ?? 'unknown-run'
+  const addenda = getRunTreeAddenda(runDir)
   const lines: string[] = [
     'Run: `/.recursive/run/' + runId + '/`',
     'Phase: `' + config.label + '`',
@@ -167,6 +199,10 @@ export function closeoutPhase(runDir: string, phase: string, opts: CloseoutOptio
     'Outputs:',
     '- `/.recursive/run/' + runId + '/' + config.file + '`',
     'Scope note: ' + config.scopeNote,
+    'Addenda:',
+    ...(addenda.length > 0
+      ? addenda.map(a => '- `/.recursive/run/' + runId + '/' + a + '`')
+      : ['- none found in the run tree']),
     '',
   ]
   for (const heading of REQUIRED_SECTIONS[phase]) {
@@ -179,5 +215,6 @@ export function closeoutPhase(runDir: string, phase: string, opts: CloseoutOptio
     file: config.file,
     created: existed ? [] : [config.file],
     existing: existed ? [config.file] : [],
+    addenda,
   }
 }