helloagents 3.0.2-beta.1 → 3.0.7

package/scripts/cli-lifecycle.mjs

@@ -0,0 +1,213 @@
+import { existsSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { DEFAULTS, ensureConfig } from './cli-config.mjs'
+import {
+  detectHostMode as detectRuntimeHostMode,
+  getHostLabel as resolveHostLabel,
+  normalizeHost as normalizeLifecycleHost,
+} from './cli-host-detect.mjs'
+import { installAllHosts, runHostLifecycle, uninstallAllHosts } from './cli-lifecycle-hosts.mjs'
+import { ensureDir, safeJson, safeWrite } from './cli-utils.mjs'
+
+export const HOSTS = ['claude', 'gemini', 'codex']
+
+const runtime = {
+  home: '',
+  pkgRoot: '',
+  helloagentsHome: '',
+  configFile: '',
+  pkgVersion: '',
+  msg: (cn, en) => en || cn,
+  ok: console.log,
+  printInstallMsg: () => {},
+}
+
+export function initCliLifecycle(options) {
+  Object.assign(runtime, options)
+}
+
+export function readSettings(shouldEnsure = false) {
+  if (shouldEnsure) ensureConfig(runtime.helloagentsHome, runtime.configFile, safeJson, ensureDir)
+  return safeJson(runtime.configFile) || {}
+}
+
+function writeSettings(settings) {
+  ensureDir(runtime.helloagentsHome)
+  writeFileSync(runtime.configFile, JSON.stringify(settings, null, 2), 'utf-8')
+}
+
+function hasTrackedHostModes(settings) {
+  return !!settings && typeof settings.host_install_modes === 'object' && !Array.isArray(settings.host_install_modes)
+}
+
+export function getTrackedHostMode(settings, host) {
+  return hasTrackedHostModes(settings) ? settings.host_install_modes[host] || '' : ''
+}
+
+function setTrackedHostMode(settings, host, mode) {
+  if (!hasTrackedHostModes(settings)) settings.host_install_modes = {}
+  settings.host_install_modes[host] = mode
+}
+
+function clearTrackedHostMode(settings, host) {
+  if (!hasTrackedHostModes(settings)) {
+    settings.host_install_modes = {}
+    return
+  }
+  delete settings.host_install_modes[host]
+}
+
+function setAllTrackedHostModes(settings, mode) {
+  settings.host_install_modes = Object.fromEntries(HOSTS.map((host) => [host, mode]))
+}
+
+function clearAllTrackedHostModes(settings) {
+  settings.host_install_modes = {}
+}
+
+export function normalizeHost(value = '') {
+  return normalizeLifecycleHost(value)
+}
+
+function parseModeFlag(args) {
+  const hasGlobal = args.includes('--global')
+  const hasStandby = args.includes('--standby')
+  if (hasGlobal && hasStandby) {
+    throw new Error(runtime.msg('不能同时指定 --global 和 --standby', 'Cannot use --global and --standby together'))
+  }
+  if (hasGlobal) return 'global'
+  if (hasStandby) return 'standby'
+  return ''
+}
+
+function parseLifecycleArgs(args) {
+  const explicitMode = parseModeFlag(args)
+  const wantsAll = args.includes('--all')
+  const positionals = args.filter((arg) => !arg.startsWith('--'))
+  const unknownFlags = args.filter((arg) => arg.startsWith('--') && !['--global', '--standby', '--all'].includes(arg))
+  if (unknownFlags.length) {
+    throw new Error(runtime.msg(`未知参数: ${unknownFlags.join(', ')}`, `Unknown flags: ${unknownFlags.join(', ')}`))
+  }
+  if (wantsAll && positionals.length) {
+    throw new Error(runtime.msg('`--all` 不能与具体 CLI 同时使用', '`--all` cannot be combined with a specific CLI'))
+  }
+  if (positionals.length > 1) {
+    throw new Error(runtime.msg(`参数过多: ${positionals.join(' ')}`, `Too many arguments: ${positionals.join(' ')}`))
+  }
+  const host = normalizeLifecycleHost(wantsAll ? 'all' : (positionals[0] || 'all'))
+  if (!host) {
+    throw new Error(runtime.msg(`不支持的 CLI: ${positionals[0]}`, `Unsupported CLI: ${positionals[0]}`))
+  }
+  return { host, explicitMode }
+}
+
+export function detectHostMode(host) {
+  return detectRuntimeHostMode(host, runtime)
+}
+
+export function getHostLabel(host) {
+  return resolveHostLabel(host)
+}
+
+function resolveHostMode(host, explicitMode, settings) {
+  if (explicitMode) return explicitMode
+  return detectHostMode(host)
+    || getTrackedHostMode(settings, host)
+    || (!hasTrackedHostModes(settings) ? (settings.install_mode || '') : '')
+    || DEFAULTS.install_mode
+}
+
+function resolveInstallMode(explicitMode, settings) {
+  return explicitMode || settings.install_mode || DEFAULTS.install_mode
+}
+
+
+export function syncVersion() {
+  const targets = [
+    join(runtime.pkgRoot, '.claude-plugin', 'plugin.json'),
+    join(runtime.pkgRoot, '.codex-plugin', 'plugin.json'),
+    join(runtime.pkgRoot, 'gemini-extension.json'),
+  ]
+  for (const path of targets) {
+    const obj = safeJson(path)
+    if (!obj) continue
+    obj.version = runtime.pkgVersion
+    safeWrite(path, JSON.stringify(obj, null, 2) + '\n')
+  }
+  const marketPath = join(runtime.pkgRoot, '.claude-plugin', 'marketplace.json')
+  const market = safeJson(marketPath)
+  if (market?.plugins?.[0]) {
+    market.plugins[0].version = runtime.pkgVersion
+    safeWrite(marketPath, JSON.stringify(market, null, 2) + '\n')
+  }
+  runtime.ok(`Version synced to ${runtime.pkgVersion}`)
+}
+
+export function switchMode(newMode) {
+  const config = readSettings(true)
+  const oldMode = config.install_mode || DEFAULTS.install_mode
+  const isRefresh = oldMode === newMode
+
+  if (!isRefresh) {
+    config.install_mode = newMode
+    runtime.ok(runtime.msg(`模式已切换为: ${newMode}`, `Mode switched to: ${newMode}`))
+  } else {
+    runtime.ok(runtime.msg(`当前已是 ${newMode} 模式，正在刷新安装`, `Already in ${newMode} mode, refreshing installation`))
+  }
+
+  installAllHosts(runtime, newMode)
+  setAllTrackedHostModes(config, newMode)
+  writeSettings(config)
+  runtime.printInstallMsg(newMode, isRefresh ? 'refresh' : 'switch')
+}
+
+function runAllHostsLifecycle(action, explicitMode) {
+  if (action === 'cleanup' || action === 'uninstall') {
+    console.log(`\n  HelloAGENTS — ${runtime.msg('正在清理', 'Cleaning up')}\n`)
+    uninstallAllHosts(runtime)
+    if (existsSync(runtime.configFile)) {
+      const settings = readSettings()
+      clearAllTrackedHostModes(settings)
+      writeSettings(settings)
+    }
+    runtime.ok(runtime.msg('所有 CLI 配置已清理', 'All CLI configurations cleaned'))
+    console.log(runtime.msg(
+      '  ℹ ~/.helloagents/ 已保留（如需彻底清理请手动删除）\n  ℹ 如已安装 Claude Code 插件，请手动执行: /plugin remove helloagents\n  ℹ 如已安装 Gemini CLI 扩展，请手动执行: gemini extensions uninstall helloagents',
+      '  ℹ ~/.helloagents/ preserved (delete manually if desired)\n  ℹ If Claude Code plugin installed, run: /plugin remove helloagents\n  ℹ If Gemini CLI extension installed, run: gemini extensions uninstall helloagents',
+    ))
+    console.log()
+    return
+  }
+
+  const settings = readSettings(true)
+  const mode = resolveInstallMode(explicitMode, settings)
+  if (explicitMode) settings.install_mode = explicitMode
+  installAllHosts(runtime, mode)
+  setAllTrackedHostModes(settings, mode)
+  writeSettings(settings)
+  runtime.printInstallMsg(mode, action === 'update' ? 'refresh' : 'install')
+}
+
+export function runScopedLifecycle(action, rawArgs) {
+  const { host, explicitMode } = parseLifecycleArgs(rawArgs)
+  if (host === 'all') {
+    runAllHostsLifecycle(action, explicitMode)
+    return
+  }
+
+  const shouldEnsure = action === 'install' || action === 'update'
+  const settings = readSettings(shouldEnsure)
+  const mode = resolveHostMode(host, explicitMode, settings)
+  const result = runHostLifecycle(runtime, action, host, mode)
+
+  if (action === 'cleanup' || action === 'uninstall') {
+    if (existsSync(runtime.configFile)) {
+      clearTrackedHostMode(settings, host)
+      writeSettings(settings)
+    }
+  } else if (!result.skipped) {
+    setTrackedHostMode(settings, host, mode)
+    writeSettings(settings)
+  }
+}

package/scripts/cli-messages.mjs

@@ -1,63 +1,76 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
 
 export function createMessageHelpers(isCN) {
-  const msg = (cn, en) => (isCN ? cn : en);
-  const ok = (message) => console.log(`  ✓ ${message}`);
-  return { msg, ok };
+  const msg = (cn, en) => (isCN ? cn : en)
+  const ok = (message) => console.log(`  ✓ ${message}`)
+  return { msg, ok }
 }
 
-export function createInstallMessagePrinter({ home, pkgVersion, msg }) {
-  const codexStandbyStatus = () => existsSync(join(home, '.codex'))
+function codexStandbyStatus({ home, msg }) {
+  return existsSync(join(home, '.codex'))
     ? msg('已自动配置', 'Auto-configured')
-    : msg('安装 Codex CLI 后重新运行 npm install -g helloagents', 'Install Codex CLI then re-run npm install -g helloagents');
+    : msg('安装 Codex CLI 后重新运行 npm install -g helloagents', 'Install Codex CLI then re-run npm install -g helloagents')
+}
 
-  const codexGlobalStatus = () => existsSync(join(home, '.codex'))
+function codexGlobalStatus({ home, msg }) {
+  return existsSync(join(home, '.codex'))
     ? msg('已自动安装原生本地插件', 'Native local plugin auto-installed')
-    : msg('安装 Codex CLI 后重新运行 npm install -g helloagents', 'Install Codex CLI then re-run npm install -g helloagents');
+    : msg('安装 Codex CLI 后重新运行 npm install -g helloagents', 'Install Codex CLI then re-run npm install -g helloagents')
+}
+
+function pluginCommands() {
+  return '    Claude Code:  /plugin marketplace add hellowind777/helloagents\n                  /plugin install helloagents@helloagents\n    Gemini CLI:   gemini extensions install https://github.com/hellowind777/helloagents'
+}
 
-  const PLUGIN_CMDS = '    Claude Code:  /plugin marketplace add hellowind777/helloagents\n                  /plugin install helloagents@helloagents\n    Gemini CLI:   gemini extensions install https://github.com/hellowind777/helloagents';
-  const REMOVE_HINT = msg(
+function removeHint(msg) {
+  return msg(
     '如已安装 Claude Code 插件，建议手动移除: /plugin remove helloagents\n  如已安装 Gemini CLI 扩展，建议手动移除: gemini extensions uninstall helloagents',
     'If Claude Code plugin installed, consider removing: /plugin remove helloagents\n  If Gemini CLI extension installed, consider removing: gemini extensions uninstall helloagents',
-  );
-
-  function printInstallMsg(mode, context) {
-    const isSwitch = context === 'switch';
-    const isRefresh = context === 'refresh';
-    const isInstall = !isSwitch && !isRefresh;
-    if (mode === 'global') {
-      if (isInstall) console.log(msg(
-        `\n  ✅ HelloAGENTS 已安装（global 模式）！\n\n${PLUGIN_CMDS}\n    Codex:        ${codexGlobalStatus()}（~/.agents/plugins/marketplace.json + ~/plugins/helloagents）\n\n  切换模式：\n    helloagents --standby   标准模式（默认，非插件安装）`,
-        `\n  ✅ HelloAGENTS installed (global mode)!\n\n${PLUGIN_CMDS}\n    Codex:        ${codexGlobalStatus()} (~/.agents/plugins/marketplace.json + ~/plugins/helloagents)\n\n  Switch modes:\n    helloagents --standby   Standby mode (default, non-plugin install)`,
-      ));
-      else console.log(msg(
-        isRefresh
-          ? '  global 模式已刷新。\n  Claude Code / Gemini 请保持插件已安装；Codex 原生本地插件链路已重装并同步最新文件。'
-          : '  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 请手动安装插件；Codex 已自动走原生本地插件链路。',
-        isRefresh
-          ? '  Global mode refreshed.\n  Keep Claude Code / Gemini plugins installed; Codex native local-plugin files were reinstalled and synced.'
-          : '  All projects will use full HelloAGENTS rules.\n  Install Claude Code / Gemini plugins manually; Codex now uses the native local-plugin path automatically.',
-      ));
-    } else {
-      if (isInstall) console.log(msg(
-        `\n  ✅ HelloAGENTS 已安装（standby 模式）！\n\n    Claude Code:  已自动配置（~/.claude/CLAUDE.md + hooks）\n    Gemini CLI:   已自动配置（~/.gemini/GEMINI.md）\n    Codex:        ${codexStandbyStatus()}\n\n  standby 模式下，hello-* 技能不会自动触发。\n  在项目中使用 ~init 激活完整功能，或使用 ~command 按需调用。\n\n  切换模式：\n    helloagents --global    全局模式（Claude/Gemini 装插件；Codex 自动装原生本地插件）`,
-        `\n  ✅ HelloAGENTS installed (standby mode)!\n\n    Claude Code:  Auto-configured (~/.claude/CLAUDE.md + hooks)\n    Gemini CLI:   Auto-configured (~/.gemini/GEMINI.md)\n    Codex:        ${codexStandbyStatus()}\n\n  In standby mode, hello-* skills won't auto-trigger.\n  Use ~init in a project to activate full features, or use ~command on demand.\n\n  Switch modes:\n    helloagents --global    Global mode (manual plugins for Claude/Gemini; native local plugin auto-install for Codex)`,
-      ));
-      else console.log(msg(
-        isRefresh
-          ? `  standby 模式已刷新，CLI 注入与链接已同步最新文件。\n  ${REMOVE_HINT}`
-          : `  项目需通过 ~init 激活完整功能，未激活项目仅注入通用规则。\n  ${REMOVE_HINT}`,
-        isRefresh
-          ? `  Standby mode refreshed; injected files and links were synchronized.\n  ${REMOVE_HINT}`
-          : `  Projects need ~init to activate full features. Unactivated projects get lite rules only.\n  ${REMOVE_HINT}`,
-      ));
+  )
+}
+
+function renderInstallMessage(context, mode, state) {
+  const { msg } = context
+  const install = state === 'install'
+  const refresh = state === 'refresh'
+
+  if (mode === 'global') {
+    if (install) {
+      return msg(
+        `\n  ✅ HelloAGENTS 已安装（global 模式）！\n\n${pluginCommands()}\n    Codex:        ${codexGlobalStatus(context)}（~/.agents/plugins/marketplace.json + ~/plugins/helloagents）\n\n  切换模式：\n    helloagents --standby   标准模式（默认，非插件安装）`,
+        `\n  ✅ HelloAGENTS installed (global mode)!\n\n${pluginCommands()}\n    Codex:        ${codexGlobalStatus(context)} (~/.agents/plugins/marketplace.json + ~/plugins/helloagents)\n\n  Switch modes:\n    helloagents --standby   Standby mode (default, non-plugin install)`,
+      )
     }
-    if (isInstall || isRefresh) console.log();
+    return msg(
+      refresh
+        ? '  global 模式已刷新。\n  Claude Code / Gemini 请保持插件已安装；Codex 原生本地插件链路已重装并同步最新文件。'
+        : '  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 请手动安装插件；Codex 已自动走原生本地插件链路。',
+      refresh
+        ? '  Global mode refreshed.\n  Keep Claude Code / Gemini plugins installed; Codex native local-plugin files were reinstalled and synced.'
+        : '  All projects will use full HelloAGENTS rules.\n  Install Claude Code / Gemini plugins manually; Codex now uses the native local-plugin path automatically.',
+    )
   }
 
-  function printHelp() {
-    console.log(`
+  if (install) {
+    return msg(
+      `\n  ✅ HelloAGENTS 已安装（standby 模式）！\n\n    Claude Code:  已自动配置（~/.claude/CLAUDE.md + hooks）\n    Gemini CLI:   已自动配置（~/.gemini/GEMINI.md）\n    Codex:        ${codexStandbyStatus(context)}\n\n  standby 模式下，hello-* 技能不会自动触发。\n  在项目中使用 ~wiki 仅创建/同步知识库，或用 ~init 完整初始化项目；也可用 ~command 按需调用。\n\n  切换模式：\n    helloagents --global    全局模式（Claude/Gemini 装插件；Codex 自动装原生本地插件）`,
+      `\n  ✅ HelloAGENTS installed (standby mode)!\n\n    Claude Code:  Auto-configured (~/.claude/CLAUDE.md + hooks)\n    Gemini CLI:   Auto-configured (~/.gemini/GEMINI.md)\n    Codex:        ${codexStandbyStatus(context)}\n\n  In standby mode, hello-* skills won't auto-trigger.\n  Use ~wiki to create or sync the KB only, or ~init for the full project bootstrap; ~command stays available on demand.\n\n  Switch modes:\n    helloagents --global    Global mode (manual plugins for Claude/Gemini; native local plugin auto-install for Codex)`,
+    )
+  }
+
+  return msg(
+    refresh
+      ? `  standby 模式已刷新，CLI 注入与链接已同步最新文件。\n  ${removeHint(msg)}`
+      : `  项目可通过 ~wiki 创建/同步知识库，或通过 ~init 完整初始化；未激活项目仅注入通用规则。\n  ${removeHint(msg)}`,
+    refresh
+      ? `  Standby mode refreshed; injected files and links were synchronized.\n  ${removeHint(msg)}`
+      : `  Projects can use ~wiki for KB-only activation or ~init for the full bootstrap. Unactivated projects get lite rules only.\n  ${removeHint(msg)}`,
+  )
+}
+
+function renderHelp({ pkgVersion, msg }) {
+  return `
 HelloAGENTS v${pkgVersion} — The orchestration kernel for AI CLIs
 
 ${msg('安装', 'Install')}:
@@ -76,17 +89,28 @@ ${msg('单 CLI 管理', 'Scoped CLI management')}:
   helloagents uninstall gemini
   ${msg('支持: claude | gemini | codex | --all；省略模式时优先沿用该 CLI 已记录/已检测的模式，否则回退 standby', 'Hosts: claude | gemini | codex | --all; omit mode to reuse the tracked/detected mode for that CLI, then fall back to standby')}
 
+${msg('诊断', 'Diagnostics')}:
+  helloagents doctor
+  helloagents doctor codex --json
+  ${msg('检查 carrier、链接、hooks、配置注入、Codex 插件链路、model_instructions_file 遮蔽风险与版本漂移', 'Checks carriers, links, hooks, config injections, the Codex plugin chain, model_instructions_file shadowing risks, and version drift')}
+
 ${msg('卸载', 'Uninstall')}:
   helloagents cleanup      ${msg('（推荐先执行，显式清理所有 CLI 注入/链接）', '(recommended first, explicitly cleans CLI injections/links)')}
   npm uninstall -g helloagents
   ${msg('如已安装插件，另需手动移除：', 'If plugins installed, also remove manually:')}
     Claude Code:  /plugin remove helloagents
     Gemini CLI:   gemini extensions uninstall helloagents
-`.trim());
-  }
+`.trim()
+}
 
+export function createInstallMessagePrinter(context) {
   return {
-    printHelp,
-    printInstallMsg,
-  };
+    printHelp() {
+      console.log(renderHelp(context))
+    },
+    printInstallMsg(mode, state) {
+      console.log(renderInstallMessage(context, mode, state))
+      if (state === 'install' || state === 'refresh') console.log()
+    },
+  }
 }

package/scripts/closeout-state.mjs

@@ -0,0 +1,213 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import { captureWorkspaceFingerprint } from './verify-state.mjs'
+import { appendReplayEvent } from './replay-state.mjs'
+
+export const CLOSEOUT_EVIDENCE_FILE_NAME = '.ralph-closeout.json'
+const CLOSEOUT_EVIDENCE_MAX_AGE_MS = 30 * 60 * 1000
+const ALLOWED_STATUSES = new Set(['PASS', 'BLOCKED'])
+
+function normalizeEntry(entry = {}) {
+  return {
+    status: typeof entry.status === 'string' ? entry.status.trim().toUpperCase() : '',
+    summary: typeof entry.summary === 'string' ? entry.summary.trim() : '',
+  }
+}
+
+export function getCloseoutEvidencePath(cwd) {
+  return join(cwd, '.helloagents', CLOSEOUT_EVIDENCE_FILE_NAME)
+}
+
+export function readCloseoutEvidence(cwd) {
+  try {
+    return JSON.parse(readFileSync(getCloseoutEvidencePath(cwd), 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+export function clearCloseoutEvidence(cwd) {
+  rmSync(getCloseoutEvidencePath(cwd), { force: true })
+}
+
+export function normalizeCloseoutEvidence(input = {}) {
+  return {
+    source: typeof input.source === 'string' ? input.source.trim() : 'manual',
+    originCommand: typeof input.originCommand === 'string' ? input.originCommand.trim() : '',
+    requirementsCoverage: normalizeEntry(input.requirementsCoverage),
+    deliveryChecklist: normalizeEntry(input.deliveryChecklist),
+  }
+}
+
+export function writeCloseoutEvidence(cwd, input = {}) {
+  mkdirSync(join(cwd, '.helloagents'), { recursive: true })
+  const normalized = normalizeCloseoutEvidence(input)
+  const payload = {
+    updatedAt: new Date().toISOString(),
+    source: normalized.source || 'manual',
+    originCommand: normalized.originCommand,
+    requirementsCoverage: normalized.requirementsCoverage,
+    deliveryChecklist: normalized.deliveryChecklist,
+    fingerprint: captureWorkspaceFingerprint(cwd),
+  }
+  writeFileSync(getCloseoutEvidencePath(cwd), `${JSON.stringify(payload, null, 2)}\n`, 'utf-8')
+  appendReplayEvent(cwd, {
+    event: 'closeout_evidence_written',
+    source: normalized.source || 'manual',
+    skillName: normalized.originCommand,
+    details: {
+      requirementsCoverage: normalized.requirementsCoverage,
+      deliveryChecklist: normalized.deliveryChecklist,
+    },
+    artifacts: ['.helloagents/.ralph-closeout.json'],
+  })
+  return payload
+}
+
+function readRequiredCloseoutEvidence(cwd) {
+  const evidence = readCloseoutEvidence(cwd)
+  if (evidence) return { evidence }
+  return {
+    error: {
+      required: true,
+      status: 'missing',
+      details: ['missing closeout evidence for requirements coverage and delivery checklist'],
+    },
+  }
+}
+
+function validateCloseoutTimestamp(evidence, now) {
+  const updatedAt = Date.parse(evidence.updatedAt || '')
+  if (!Number.isFinite(updatedAt)) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: ['closeout evidence timestamp is invalid'],
+    }
+  }
+  if (now - updatedAt > CLOSEOUT_EVIDENCE_MAX_AGE_MS) {
+    return {
+      required: true,
+      status: 'stale-time',
+      evidence,
+      details: ['closeout evidence is older than 30 minutes'],
+    }
+  }
+  return null
+}
+
+function validateCloseoutEntries(evidence) {
+  const requirementsCoverage = normalizeEntry(evidence.requirementsCoverage)
+  const deliveryChecklist = normalizeEntry(evidence.deliveryChecklist)
+
+  if (
+    !ALLOWED_STATUSES.has(requirementsCoverage.status)
+    || !requirementsCoverage.summary
+    || !ALLOWED_STATUSES.has(deliveryChecklist.status)
+    || !deliveryChecklist.summary
+  ) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: ['closeout evidence must record requirements coverage and delivery checklist with explicit PASS/BLOCKED status plus summary'],
+    }
+  }
+  if (requirementsCoverage.status !== 'PASS') {
+    return {
+      required: true,
+      status: 'blocked',
+      evidence,
+      details: ['requirements coverage is not marked as PASS in the latest closeout evidence'],
+    }
+  }
+  if (deliveryChecklist.status !== 'PASS') {
+    return {
+      required: true,
+      status: 'blocked',
+      evidence,
+      details: ['delivery checklist is not marked as PASS in the latest closeout evidence'],
+    }
+  }
+  return {
+    requirementsCoverage,
+    deliveryChecklist,
+  }
+}
+
+function validateCloseoutFingerprint(cwd, evidence) {
+  const currentFingerprint = captureWorkspaceFingerprint(cwd)
+  if (
+    currentFingerprint.available
+    && evidence.fingerprint?.available
+    && currentFingerprint.combined !== evidence.fingerprint.combined
+  ) {
+    return {
+      required: true,
+      status: 'stale-diff',
+      evidence,
+      details: ['workspace diff changed after the last successful closeout evidence'],
+    }
+  }
+  return null
+}
+
+export function getCloseoutEvidenceStatus(cwd, { required = false, now = Date.now() } = {}) {
+  if (!required) {
+    return {
+      required: false,
+      status: 'not-applicable',
+    }
+  }
+
+  const requiredEvidence = readRequiredCloseoutEvidence(cwd)
+  if (requiredEvidence.error) return requiredEvidence.error
+
+  const { evidence } = requiredEvidence
+  const timestampError = validateCloseoutTimestamp(evidence, now)
+  if (timestampError) return timestampError
+
+  const normalizedEntries = validateCloseoutEntries(evidence)
+  if (!('requirementsCoverage' in normalizedEntries)) return normalizedEntries
+
+  const fingerprintError = validateCloseoutFingerprint(cwd, evidence)
+  if (fingerprintError) return fingerprintError
+
+  return {
+    required: true,
+    status: 'valid',
+    evidence: {
+      ...evidence,
+      requirementsCoverage: normalizedEntries.requirementsCoverage,
+      deliveryChecklist: normalizedEntries.deliveryChecklist,
+    },
+  }
+}
+
+function readStdinJson() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function main() {
+  const command = process.argv[2] || ''
+  if (command !== 'write') return
+
+  const input = readStdinJson()
+  const cwd = input.cwd || process.cwd()
+  const payload = writeCloseoutEvidence(cwd, input)
+  process.stdout.write(JSON.stringify({
+    suppressOutput: true,
+    path: getCloseoutEvidencePath(cwd),
+    payload,
+  }))
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}