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

package/scripts/live-session-stock.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * FU-10 step 1 — THE STOCK SESSION, copied VERBATIM from the harness's own e2e.
+ *
+ * WHY A SEPARATE SCRIPT. My first attempt added this plugin on the very first run, which mixed two
+ * unknowns: whether the launch works at all, and whether my plugin mounts. This script removes the second
+ * unknown completely — it is the harness's own fixture (same profile package.json, same bundles, same
+ * patch, same scripted LLM, same prompt, same invocation) with nothing of mine added. If this boots, the
+ * remaining question is only how to mount a plugin; if it does not, the route is blocked here and no
+ * amount of plugin work would have fixed it.
+ *
+ * Source of every line below: apps/cli/tests/agent-team-headless.e2e.ts (L21-78) and the invocation
+ * printed from resolveExampleLaunch.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, openSync, closeSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const HARNESS = 'D:\\deepseek-harness'
+const SRC_BIN = join(HARNESS, 'apps', 'cli', 'src', 'bin.ts')
+const TSCONFIG = join(HARNESS, 'tsconfig.json')
+// The absolute file URL to tsx's loader, exactly as resolveExampleLaunch emits it.
+const TSX_LOADER = 'file:///D:/deepseek-harness/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/dist/loader.mjs'
+const FIXTURE_LLM = join(HARNESS, 'apps', 'cli', 'tests', 'profiles', 'headless', 'tests', 'fixtures', 'team-llm.mjs')
+// The prompt the e2e uses, which is what its scripted LLM is written against.
+const PROMPT = '请先运行 workflow 检查，再使用 Agent Teams 把调研和实现拆给两个 teammate，等待完成后汇总。'
+
+const fileUrl = (path) => 'file:///' + path.replace(/\\/g, '/')
+const base = join(existsSync('E:\\') ? 'E:\\dsh-rm-live' : tmpdir(), 'stock-' + new Date().toISOString().replace(/[:.]/g, '-'))
+const home = join(base, '.dsh')
+const sessions = join(home, 'sessions')
+const profileDir = join(home, 'profiles', 'headless')
+
+mkdirSync(profileDir, { recursive: true })
+mkdirSync(sessions, { recursive: true })
+
+// 1:1 with the e2e's profile.
+writeFileSync(join(profileDir, 'package.json'), JSON.stringify({
+  name: 'dsh-profile-headless',
+  private: true,
+  dependencies: { '@deepseek-ai/dsh-experimental-agent-team-profile': 'workspace:^' },
+  dsh: {
+    profile: {
+      bundles: [
+        '@deepseek-ai/dsh-base',
+        '@deepseek-ai/dsh-headless',
+        '@deepseek-ai/dsh-experimental-agent-team-profile',
+      ],
+    },
+  },
+}, undefined, 2) + '\n', 'utf8')
+
+// 1:1 with the e2e's patch: real provider off, sessions into the temp home, fixture LLM inserted.
+writeFileSync(join(profileDir, 'cordis.patch.yml'), [
+  '- id: llm-deepseek',
+  '  disabled: true',
+  '- id: session-persistence-jsonl',
+  '  config:',
+  "    root: '" + sessions.replace(/\\/g, '/') + "'",
+  '    compression: none',
+  '- insert:',
+  '    - id: team-fixture-llm',
+  "      name: '" + fileUrl(FIXTURE_LLM) + "'",
+  '',
+].join('\n'), 'utf8')
+
+const outFile = join(base, 'stdout.txt')
+const errFile = join(base, 'stderr.txt')
+const outFd = openSync(outFile, 'w')
+const errFd = openSync(errFile, 'w')
+
+// ⚠ The child must not inherit this session's identity: DSH_PROFILE=web made the CLI see two profiles.
+const env = { ...process.env }
+for (const key of ['DSH_PROFILE', 'DSH_PROFILE_DIR', 'DSH_SESSION_ID', 'DSH_SHELL', 'DSH_WEB_URL']) delete env[key]
+
+console.log('[stock] base: ' + base)
+const result = spawnSync(process.execPath, [
+  '--import', TSX_LOADER,
+  SRC_BIN,
+  '--profile', 'headless',
+  PROMPT,
+], {
+  cwd: base,
+  stdio: ['ignore', outFd, errFd],
+  env: {
+    ...env,
+    DSH_HOME: home,
+    DSH_AGENTS_HOME: join(base, '.agents'),
+    DSH_TELEMETRY_DISABLED: '1',
+    DEEPSEEK_API_KEY: '',
+    TSX_TSCONFIG_PATH: TSCONFIG,
+  },
+})
+closeSync(outFd)
+closeSync(errFd)
+
+const stdout = existsSync(outFile) ? readFileSync(outFile, 'utf8') : ''
+const stderr = existsSync(errFile) ? readFileSync(errFile, 'utf8') : ''
+console.log('[stock] exit: ' + result.status + (result.error ? ' (spawn error: ' + result.error.message + ')' : ''))
+console.log('[stock] stdout: ' + stdout.length + ' bytes | stderr: ' + stderr.length + ' bytes')
+if (stdout.trim() !== '') console.log('--- stdout tail ---\n' + stdout.trim().split('\n').slice(-10).join('\n'))
+if (stderr.trim() !== '') console.log('--- stderr tail ---\n' + stderr.trim().split('\n').slice(-10).join('\n'))
+const logs = existsSync(sessions) ? readdirSync(sessions, { recursive: true }).map(String).filter((n) => n.endsWith('.jsonl')) : []
+console.log('[stock] session logs: ' + logs.length)
+console.log('[stock] workflow marker (TEAM_WORKFLOW_OK): ' + stdout.includes('TEAM_WORKFLOW_OK'))

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/skills/recursive-mode/SKILL.md

@@ -0,0 +1,66 @@
+# recursive-mode
+
+Drive the recursive-mode workflow: an audit-gated, phase-disciplined loop that
+carries one requirement from an AS-IS understanding through a TO-BE plan,
+implementation, test, and manual QA, to locked control-plane state and durable
+memory. Every phase follows `draft → audit → repair → re-audit → pass → lock`.
+
+## When to use
+
+- The user says "implement the run", "implement run <id>", "start a recursive
+  run", "resume <run-id>", or otherwise asks to advance a run.
+- The repo carries a `/.recursive/` control plane (RECURSIVE.md, STATE.md,
+  DECISIONS.md, memory/, run/).
+
+## Source of truth
+
+The canonical spec is `/.recursive/RECURSIVE.md`; read it before starting or
+resuming. The control plane lives under `/.recursive/`, one run under
+`/.recursive/run/<run-id>/`, and durable memory under `/.recursive/memory/`.
+Treat bridge docs (`AGENTS.md`, `CLAUDE.md`, `.codex/AGENTS.md`, `.agent/PLANS.md`)
+as harness adapters, not a second spec — on conflict, follow `/.recursive/RECURSIVE.md`.
+
+## Phases
+
+A run advances one phase at a time in order; each phase owns a Markdown artifact
+under `/.recursive/run/<run-id>/`:
+
+- Phase 0 — `00-requirements.md` (gather requirements)
+- Phase 0 (Worktree) — `00-worktree.md` (record the diff basis and scope)
+- Phase 1 — `01-as-is.md` (AS-IS analysis)
+- Phase 2 — `02-to-be-plan.md` (TO-BE plan)
+- Phase 3 — `03-implementation-summary.md` (implement, strict/pragmatic TDD)
+- Phase 3.5 — `03.5-code-review.md` (delegated or self review)
+- Phase 4 — `04-test-summary.md` (test evidence)
+- Phase 5 — `05-manual-qa.md` (manual QA)
+- Phase 6 — `06-decisions-update.md` (update `/.recursive/DECISIONS.md`)
+- Phase 7 — `07-state-update.md` (update `/.recursive/STATE.md`)
+- Phase 8 — `08-memory-impact.md` (update `/.recursive/memory/`)
+
+Use `recursive_status` to read the current phase and its state. Use `recursive_init`
+to scaffold a run, `recursive_lock` to lock a passed phase (it refuses premature
+locks), `recursive_lint` to machine-check an artifact before acceptance, and
+`recursive_closeout` to advance the receipt when the phase is done.
+
+## The audit loop
+
+Audited phases must follow `draft → audit → repair → re-audit → pass → lock`.
+Never set `Coverage: PASS` or `Approval: PASS` unless the artifact ends with
+`Audit: PASS`. When subagents are unavailable, perform the same audit as
+self-audit; do not weaken or skip it. Delegate an audit only with the full
+context bundle (phase name + artifact path, upstream artifacts reread for the
+audit, diff basis from `00-worktree.md`, changed files + code references,
+phase-specific audit questions); if the bundle is incomplete, perform the audit
+yourself and record `Audit Execution Mode: self-audit`. A `success: false` or any
+nonzero delegated exit is a failed attempt — preserve diagnostics, repair owned
+issues, rerun, and verify before acceptance.
+
+## Locking and memory
+
+Lock a phase with `recursive_lock` — it is the supported way to write
+`Status: LOCKED`, `LockedAt`, and `LockHash`, and it refuses a lock whose
+prerequisites are unmet. Phase 6 owns `/.recursive/DECISIONS.md`, Phase 7 owns
+`/.recursive/STATE.md`, Phase 8 owns `/.recursive/memory/**`. Read
+`/.recursive/memory/MEMORY.md` before loading other memory docs, and record
+durable, reusable conclusions (not raw transcripts) when a run teaches the repo
+something about capability availability, fit, or quality.

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 }
+}