helloagents 3.0.12 → 3.0.16-beta.1

package/scripts/cli-messages.mjs

@@ -20,7 +20,11 @@ function codexGlobalStatus({ home, msg }) {
 }
 
 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'
+  return [
+    '    Claude Code:  /plugin marketplace add hellowind777/helloagents',
+    '                  /plugin install helloagents@helloagents',
+    '    Gemini CLI:   gemini extensions install https://github.com/hellowind777/helloagents',
+  ].join('\n')
 }
 
 function removeHint(msg) {
@@ -30,6 +34,13 @@ function removeHint(msg) {
   )
 }
 
+function restartHint(msg) {
+  return msg(
+    '重装、刷新或切换模式后，请重启对应 AI CLI 或新开会话；已运行会话不会自动重载注入规则。',
+    'After reinstalling, refreshing, or switching modes, restart the target AI CLI or open a new session; already running sessions do not reload injected rules automatically.',
+  )
+}
+
 function renderInstallMessage(context, mode, state) {
   const { msg } = context
   const install = state === 'install'
@@ -38,34 +49,34 @@ function renderInstallMessage(context, mode, state) {
   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)`,
+        `\n  ✅ HelloAGENTS 已安装（global 模式）！\n\n    Claude Code / Gemini CLI: 已自动尝试宿主原生插件/扩展安装\n    Codex:        ${codexGlobalStatus(context)}（~/.agents/plugins/marketplace.json + ~/plugins/helloagents）\n\n  ${restartHint(msg)}\n\n  若宿主命令不可用，请手动执行：\n${pluginCommands()}\n\n  切换模式：\n    helloagents --standby   标准模式（默认，非插件安装）`,
+        `\n  ✅ HelloAGENTS installed (global mode)!\n\n    Claude Code / Gemini CLI: native plugin/extension install attempted automatically\n    Codex:        ${codexGlobalStatus(context)} (~/.agents/plugins/marketplace.json + ~/plugins/helloagents)\n\n  ${restartHint(msg)}\n\n  If a host command is unavailable, run manually:\n${pluginCommands()}\n\n  Switch modes:\n    helloagents --standby   Standby mode (default, non-plugin install)`,
       )
     }
     return msg(
       refresh
-        ? '  global 模式已刷新。\n  Claude Code / Gemini 请保持插件已安装；Codex 原生本地插件已重装并同步最新文件。'
-        : '  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 请手动安装插件；Codex 已自动安装原生本地插件。',
+        ? `  global 模式已刷新。\n  Claude Code / Gemini 已自动尝试刷新宿主插件/扩展；Codex 原生本地插件已重装并同步最新文件。\n  ${restartHint(msg)}`
+        : `  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 已自动尝试安装宿主插件/扩展；Codex 已自动安装原生本地插件。\n  ${restartHint(msg)}\n\n若宿主命令不可用，请手动执行：\n${pluginCommands()}`,
       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.',
+        ? `  Global mode refreshed.\n  Claude Code / Gemini native plugin/extension refresh was attempted automatically; Codex native local-plugin files were reinstalled and synced.\n  ${restartHint(msg)}`
+        : `  All projects will use full HelloAGENTS rules.\n  Claude Code / Gemini native plugin/extension install was attempted automatically; Codex now uses the native local-plugin path automatically.\n  ${restartHint(msg)}\n\nIf a host command is unavailable, run manually:\n${pluginCommands()}`,
     )
   }
 
   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)`,
+      `\n  ✅ HelloAGENTS 已安装（standby 模式）！\n\n    Claude Code:  已自动配置（~/.claude/CLAUDE.md + hooks）\n    Gemini CLI:   已自动配置（~/.gemini/GEMINI.md）\n    Codex:        ${codexStandbyStatus(context)}\n\n  ${restartHint(msg)}\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  ${restartHint(msg)}\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 (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex)`,
     )
   }
 
   return msg(
     refresh
-      ? `  standby 模式已刷新，CLI 注入与链接已同步最新文件。\n  ${removeHint(msg)}`
-      : `  项目可通过 ~wiki 创建/同步知识库，或通过 ~init 完整初始化；未激活项目仅注入通用规则。\n  ${removeHint(msg)}`,
+      ? `  standby 模式已刷新，CLI 注入与链接已同步最新文件。\n  ${restartHint(msg)}\n  ${removeHint(msg)}`
+      : `  项目可通过 ~wiki 创建/同步知识库，或通过 ~init 完整初始化；未激活项目仅注入通用规则。\n  ${restartHint(msg)}\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)}`,
+      ? `  Standby mode refreshed; injected files and links were synchronized.\n  ${restartHint(msg)}\n  ${removeHint(msg)}`
+      : `  Projects can use ~wiki for KB-only activation or ~init for the full bootstrap. Unactivated projects get lite rules only.\n  ${restartHint(msg)}\n  ${removeHint(msg)}`,
   )
 }
 
@@ -74,11 +85,12 @@ function renderHelp({ pkgVersion, msg }) {
 HelloAGENTS v${pkgVersion} — The orchestration kernel for AI CLIs
 
 ${msg('安装', 'Install')}:
-  npm install -g helloagents  ${msg('（只安装包与命令；CLI 部署需显式执行 helloagents install ...）', '(installs the package/command only; deploy to CLIs explicitly with helloagents install ...)')}
+  npm install -g helloagents  ${msg('（安装命令并同步稳定运行根目录；CLI 部署需显式执行 helloagents install ...）', '(installs the command and syncs the stable runtime root; deploy to CLIs explicitly with helloagents install ...)')}
+  HELLOAGENTS=codex:global npm install -g helloagents
   helloagents-js             ${msg('（稳定别名，避免与系统中同名可执行文件冲突）', '(stable alias to avoid conflicts with system executables of the same name)')}
 
 ${msg('模式切换', 'Mode switching')}:
-  helloagents --global     ${msg('全局模式（Claude/Gemini 装插件；Codex 自动装原生本地插件）', 'Global mode (manual plugins for Claude/Gemini; native local plugin auto-install for Codex)')}
+  helloagents --global     ${msg('全局模式（自动尝试 Claude/Gemini 插件或扩展；Codex 自动装原生本地插件）', 'Global mode (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex)')}
   helloagents --standby    ${msg('标准模式（非插件安装，hello-* 不自动触发，默认）', "Standby mode (non-plugin install, hello-* won't auto-trigger, default)")}
 
 ${msg('单 CLI 管理', 'Scoped CLI management')}:
@@ -89,6 +101,12 @@ ${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('分支切换', 'Branch switching')}:
+  helloagents switch-branch beta
+  helloagents switch-branch beta claude --global
+  helloagents branch github:hellowind777/helloagents#beta --all --standby
+  ${msg('先通过 npm 安装指定 ref，再通过 npm 脚本同步宿主 CLI', 'Installs the requested ref with npm first, then syncs host CLIs through npm scripts')}
+
 ${msg('诊断', 'Diagnostics')}:
   helloagents doctor
   helloagents doctor codex --json
@@ -97,7 +115,7 @@ ${msg('诊断', 'Diagnostics')}:
 ${msg('卸载', 'Uninstall')}:
   helloagents cleanup      ${msg('（推荐先执行，显式清理所有 CLI 注入/链接）', '(recommended first, explicitly cleans CLI injections/links)')}
   npm uninstall -g helloagents
-  ${msg('如已安装插件，另需手动移除：', 'If plugins installed, also remove manually:')}
+  ${msg('如宿主命令不可用，另需手动移除：', 'If host commands are unavailable, also remove manually:')}
     Claude Code:  /plugin remove helloagents
     Gemini CLI:   gemini extensions uninstall helloagents
 `.trim()

package/scripts/cli-runtime-carrier.mjs

@@ -0,0 +1,15 @@
+import { join } from 'node:path'
+
+import { safeJson } from './cli-utils.mjs'
+
+export function readCarrierSettings(home) {
+  return safeJson(join(home, '.helloagents', 'helloagents.json')) || {}
+}
+
+export function buildRuntimeCarrier(bootstrapContent, settings = {}) {
+  void settings
+  const normalized = String(bootstrapContent || '').trim()
+  if (!normalized) return ''
+
+  return `${normalized}\n`
+}

package/scripts/cli-runtime-root.mjs

@@ -0,0 +1,72 @@
+import { mkdtempSync, realpathSync, renameSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+import { copyEntries, ensureDir, removeIfExists } from './cli-utils.mjs'
+
+export const RUNTIME_ROOT_ENTRIES = [
+  '.claude-plugin',
+  '.codex-plugin',
+  'assets',
+  'bootstrap-lite.md',
+  'bootstrap.md',
+  'cli.mjs',
+  'gemini-extension.json',
+  'hooks',
+  'install.ps1',
+  'install.sh',
+  'LICENSE.md',
+  'package.json',
+  'README.md',
+  'README_CN.md',
+  'scripts',
+  'skills',
+  'templates',
+]
+
+/** Return the stable per-user runtime copy used by host integrations. */
+export function getStableRuntimeRoot(home) {
+  return join(home, '.helloagents', 'helloagents')
+}
+
+function normalizePath(path) {
+  const resolved = resolve(path)
+  try {
+    return realpathSync(resolved)
+  } catch {
+    return resolved
+  }
+}
+
+function samePath(left, right) {
+  const a = normalizePath(left)
+  const b = normalizePath(right)
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b
+}
+
+/** Sync package runtime files into the stable root without copying repo-only files. */
+export function syncRuntimeRoot(sourceRoot, runtimeRoot) {
+  const source = resolve(sourceRoot)
+  const target = resolve(runtimeRoot)
+  if (samePath(source, target)) {
+    return { synced: false, root: target }
+  }
+
+  const parent = dirname(target)
+  ensureDir(parent)
+  const staging = mkdtempSync(join(parent, '.helloagents-runtime-'))
+
+  try {
+    copyEntries(source, staging, RUNTIME_ROOT_ENTRIES)
+    removeIfExists(target)
+    renameSync(staging, target)
+    return { synced: true, root: target }
+  } catch (error) {
+    removeIfExists(staging)
+    throw error
+  }
+}
+
+/** Remove the stable runtime copy while leaving user settings under ~/.helloagents intact. */
+export function removeRuntimeRoot(runtimeRoot) {
+  removeIfExists(runtimeRoot)
+}

package/scripts/cli-toml.mjs

@@ -164,85 +164,6 @@ export function ensureTopLevelTomlLine(text, key, line) {
   return upsertTopLevelTomlKey(text, key, value);
 }
 
-export function readTomlKeyInSection(text, headerLine, key) {
-  const lines = String(text || '').replace(/\r\n/g, '\n').split('\n');
-  const headerIndex = lines.findIndex((line) => line.trim() === headerLine);
-  if (headerIndex < 0) return '';
-
-  const keyRe = new RegExp(`^\\s*${key}\\s*=.*$`);
-  for (let index = headerIndex + 1; index < lines.length; index += 1) {
-    const line = lines[index];
-    if (isTomlTableHeader(line)) break;
-    if (keyRe.test(line)) return line.trim();
-  }
-  return '';
-}
-
-export function removeTomlKeyInSection(text, headerLine, key) {
-  const lines = String(text || '').replace(/\r\n/g, '\n').split('\n');
-  const headerIndex = lines.findIndex((line) => line.trim() === headerLine);
-  if (headerIndex < 0) return normalizeToml(text);
-
-  const keyRe = new RegExp(`^\\s*${key}\\s*=`);
-  const nextLines = [];
-  let removed = false;
-  for (let index = 0; index < lines.length; index += 1) {
-    const line = lines[index];
-    if (index > headerIndex && isTomlTableHeader(line)) {
-      nextLines.push(...lines.slice(index));
-      break;
-    }
-    if (index > headerIndex && keyRe.test(line)) {
-      removed = true;
-      continue;
-    }
-    nextLines.push(line);
-  }
-
-  if (!removed) return normalizeToml(text);
-  return normalizeToml(nextLines.join('\n'));
-}
-
-export function upsertTomlKeyInSection(text, headerLine, key, value) {
-  const lines = String(text || '').replace(/\r\n/g, '\n').split('\n');
-  const headerIndex = lines.findIndex((line) => line.trim() === headerLine);
-
-  if (headerIndex < 0) {
-    const base = normalizeToml(text).trimEnd();
-    return base
-      ? `${base}\n\n${headerLine}\n${key} = ${value}\n`
-      : `${headerLine}\n${key} = ${value}\n`;
-  }
-
-  let endIndex = headerIndex + 1;
-  while (endIndex < lines.length && !isTomlTableHeader(lines[endIndex])) {
-    endIndex += 1;
-  }
-
-  const keyRe = new RegExp(`^\\s*${key}\\s*=`);
-  let updated = false;
-  for (let index = headerIndex + 1; index < endIndex; index += 1) {
-    if (keyRe.test(lines[index])) {
-      lines[index] = `${key} = ${value}`;
-      updated = true;
-      break;
-    }
-  }
-
-  if (!updated) {
-    lines.splice(endIndex, 0, `${key} = ${value}`);
-  }
-
-  return normalizeToml(lines.join('\n'));
-}
-
-export function ensureTomlKeyInSection(text, headerLine, key, line) {
-  const normalized = String(line || '').trim();
-  if (!normalized) return normalizeToml(text);
-  const value = normalized.slice(normalized.indexOf('=') + 1).trim();
-  return upsertTomlKeyInSection(text, headerLine, key, value);
-}
-
 export function stripTomlSection(text, headerLine) {
   const lines = String(text || '').replace(/\r\n/g, '\n').split('\n');
   const kept = [];

package/scripts/cli-utils.mjs

@@ -130,10 +130,36 @@ export function cleanSettingsHooks(settingsPath, cleanPermissions = false) {
   }
 }
 
-/** Read hooks source file and replace path variable with absolute PKG_ROOT. */
-export function loadHooksWithAbsPath(pkgRoot, hooksFile, pathVar) {
+function rewriteHookCommandToCli(command = '', pathVar = '') {
+  const replacements = new Map([
+    [`node "${pathVar}/scripts/notify.mjs"`, 'helloagents-js notify'],
+    [`node "${pathVar}/scripts/guard.mjs"`, 'helloagents-js guard'],
+    [`node "${pathVar}/scripts/ralph-loop.mjs"`, 'helloagents-js ralph-loop'],
+  ]);
+
+  let next = command;
+  for (const [from, to] of replacements) {
+    next = next.replaceAll(from, to);
+  }
+  return next;
+}
+
+function rewriteHookCommands(value, pathVar) {
+  if (Array.isArray(value)) return value.map((item) => rewriteHookCommands(item, pathVar));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+      key,
+      key === 'command' && typeof entry === 'string'
+        ? rewriteHookCommandToCli(entry, pathVar)
+        : rewriteHookCommands(entry, pathVar),
+    ]));
+  }
+  return value;
+}
+
+/** Read hooks source file and rewrite standby hooks to the stable CLI entrypoint. */
+export function loadHooksWithCliEntry(pkgRoot, hooksFile, pathVar) {
   const src = safeRead(join(pkgRoot, 'hooks', hooksFile));
   if (!src) return null;
-  const absRoot = pkgRoot.replace(/\\/g, '/');
-  return JSON.parse(src.replace(new RegExp(pathVar.replace(/[{}$]/g, '\\$&'), 'g'), absRoot));
+  return rewriteHookCommands(JSON.parse(src), pathVar);
 }

package/scripts/closeout-state.mjs

@@ -1,11 +1,18 @@
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { readFileSync } 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
+import {
+  captureWorkspaceFingerprint,
+  clearRuntimeEvidence,
+  getRuntimeEvidencePath,
+  getRuntimeEvidenceRelativePath,
+  readRuntimeEvidence,
+  validateEvidenceFingerprint,
+  validateEvidenceTimestamp,
+  writeRuntimeEvidence,
+} from './runtime-artifacts.mjs'
+
+export const CLOSEOUT_EVIDENCE_FILE_NAME = 'closeout.json'
 const ALLOWED_STATUSES = new Set(['PASS', 'BLOCKED'])
 
 function normalizeEntry(entry = {}) {
@@ -15,20 +22,16 @@ function normalizeEntry(entry = {}) {
   }
 }
 
-export function getCloseoutEvidencePath(cwd) {
-  return join(cwd, '.helloagents', CLOSEOUT_EVIDENCE_FILE_NAME)
+export function getCloseoutEvidencePath(cwd, options = {}) {
+  return getRuntimeEvidencePath(cwd, CLOSEOUT_EVIDENCE_FILE_NAME, options)
 }
 
-export function readCloseoutEvidence(cwd) {
-  try {
-    return JSON.parse(readFileSync(getCloseoutEvidencePath(cwd), 'utf-8'))
-  } catch {
-    return null
-  }
+export function readCloseoutEvidence(cwd, options = {}) {
+  return readRuntimeEvidence(cwd, CLOSEOUT_EVIDENCE_FILE_NAME, options)
 }
 
-export function clearCloseoutEvidence(cwd) {
-  rmSync(getCloseoutEvidencePath(cwd), { force: true })
+export function clearCloseoutEvidence(cwd, options = {}) {
+  clearRuntimeEvidence(cwd, CLOSEOUT_EVIDENCE_FILE_NAME, options)
 }
 
 export function normalizeCloseoutEvidence(input = {}) {
@@ -40,8 +43,7 @@ export function normalizeCloseoutEvidence(input = {}) {
   }
 }
 
-export function writeCloseoutEvidence(cwd, input = {}) {
-  mkdirSync(join(cwd, '.helloagents'), { recursive: true })
+export function writeCloseoutEvidence(cwd, input = {}, options = {}) {
   const normalized = normalizeCloseoutEvidence(input)
   const payload = {
     updatedAt: new Date().toISOString(),
@@ -51,51 +53,35 @@ export function writeCloseoutEvidence(cwd, input = {}) {
     deliveryChecklist: normalized.deliveryChecklist,
     fingerprint: captureWorkspaceFingerprint(cwd),
   }
-  writeFileSync(getCloseoutEvidencePath(cwd), `${JSON.stringify(payload, null, 2)}\n`, 'utf-8')
+  writeRuntimeEvidence(cwd, CLOSEOUT_EVIDENCE_FILE_NAME, payload, options)
   appendReplayEvent(cwd, {
     event: 'closeout_evidence_written',
     source: normalized.source || 'manual',
     skillName: normalized.originCommand,
+    payload: options.payload || {},
     details: {
       requirementsCoverage: normalized.requirementsCoverage,
       deliveryChecklist: normalized.deliveryChecklist,
     },
-    artifacts: ['.helloagents/.ralph-closeout.json'],
+    artifacts: [getRuntimeEvidenceRelativePath(cwd, CLOSEOUT_EVIDENCE_FILE_NAME, options)],
   })
   return payload
 }
 
-function readRequiredCloseoutEvidence(cwd) {
-  const evidence = readCloseoutEvidence(cwd)
+function readRequiredCloseoutEvidence(cwd, options = {}) {
+  const evidence = readCloseoutEvidence(cwd, options)
   if (evidence) return { evidence }
   return {
     error: {
       required: true,
       status: 'missing',
-      details: ['missing closeout evidence for requirements coverage and delivery checklist'],
+      details: ['缺少需求覆盖和交付清单的收尾证据'],
     },
   }
 }
 
 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
+  return validateEvidenceTimestamp(evidence, now, '收尾证据')
 }
 
 function validateCloseoutEntries(evidence) {
@@ -112,7 +98,7 @@ function validateCloseoutEntries(evidence) {
       required: true,
       status: 'invalid',
       evidence,
-      details: ['closeout evidence must record requirements coverage and delivery checklist with explicit PASS/BLOCKED status plus summary'],
+      details: ['收尾证据必须记录需求覆盖和交付清单，并包含明确的 PASS/BLOCKED 状态和 summary'],
     }
   }
   if (requirementsCoverage.status !== 'PASS') {
@@ -120,7 +106,7 @@ function validateCloseoutEntries(evidence) {
       required: true,
       status: 'blocked',
       evidence,
-      details: ['requirements coverage is not marked as PASS in the latest closeout evidence'],
+      details: ['最新收尾证据中的需求覆盖未标记为 PASS'],
     }
   }
   if (deliveryChecklist.status !== 'PASS') {
@@ -128,7 +114,7 @@ function validateCloseoutEntries(evidence) {
       required: true,
       status: 'blocked',
       evidence,
-      details: ['delivery checklist is not marked as PASS in the latest closeout evidence'],
+      details: ['最新收尾证据中的交付清单未标记为 PASS'],
     }
   }
   return {
@@ -138,23 +124,10 @@ function validateCloseoutEntries(evidence) {
 }
 
 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
+  return validateEvidenceFingerprint(cwd, evidence, '成功收尾证据')
 }
 
-export function getCloseoutEvidenceStatus(cwd, { required = false, now = Date.now() } = {}) {
+export function getCloseoutEvidenceStatus(cwd, { required = false, now = Date.now(), ...options } = {}) {
   if (!required) {
     return {
       required: false,
@@ -162,7 +135,7 @@ export function getCloseoutEvidenceStatus(cwd, { required = false, now = Date.no
     }
   }
 
-  const requiredEvidence = readRequiredCloseoutEvidence(cwd)
+  const requiredEvidence = readRequiredCloseoutEvidence(cwd, options)
   if (requiredEvidence.error) return requiredEvidence.error
 
   const { evidence } = requiredEvidence
@@ -200,10 +173,10 @@ function main() {
 
   const input = readStdinJson()
   const cwd = input.cwd || process.cwd()
-  const payload = writeCloseoutEvidence(cwd, input)
+  const payload = writeCloseoutEvidence(cwd, input, { payload: input })
   process.stdout.write(JSON.stringify({
     suppressOutput: true,
-    path: getCloseoutEvidencePath(cwd),
+    path: getCloseoutEvidencePath(cwd, { payload: input }),
     payload,
   }))
 }

package/scripts/delivery-gate-messages.mjs

@@ -0,0 +1,70 @@
+export function buildUnderSpecifiedDetails(entry) {
+  return entry.taskSummary.underSpecifiedItems
+    .slice(0, 3)
+    .map((item) => {
+      const missing = []
+      if (item.files.length === 0) missing.push('缺少涉及文件')
+      if (!item.acceptance) missing.push('缺少完成标准')
+      if (!item.validation) missing.push('缺少验证方式')
+      return `${item.text}（${missing.join('、')}）`
+    })
+}
+
+function issueHeading(issue) {
+  switch (issue.type) {
+    case 'missing-files':
+      return '方案包缺少必需文件'
+    case 'template-placeholders':
+      return '方案包仍包含模板占位内容'
+    case 'missing-task-checklist':
+      return '方案包没有可执行任务'
+    case 'unfinished-tasks':
+      return '方案包仍有未完成任务'
+    case 'under-specified-tasks':
+      return '任务缺少可交付元数据'
+    case 'missing-contract':
+      return '方案包缺少可信的结构化契约'
+    case 'missing-verify-evidence':
+      return '当前工作流缺少最新验证证据'
+    case 'missing-review-evidence':
+      return '当前工作流缺少最新审查证据'
+    case 'missing-advisor-evidence':
+      return '当前工作流缺少最新 advisor 证据'
+    case 'missing-visual-evidence':
+      return '当前工作流缺少最新视觉验收证据'
+    case 'missing-closeout-evidence':
+      return '当前工作流缺少最新收尾证据'
+    default:
+      return '方案包尚未达到交付条件'
+  }
+}
+
+export function buildDeliveryBlockReason(issues, recommendation, gateHint) {
+  const lines = ['[Delivery Gate] 当前工作流尚未闭合，暂不能交付：']
+
+  for (const issue of issues) {
+    lines.push(`- ${issue.planName}: ${issueHeading(issue)}`)
+    for (const detail of issue.details) {
+      lines.push(`  - ${detail}`)
+    }
+    if (issue.extraCount) {
+      lines.push(`  - 另有 ${issue.extraCount} 项`)
+    }
+  }
+
+  lines.push('')
+  if (recommendation?.nextPath) {
+    lines.push(`建议路径：${recommendation.nextPath}`)
+  }
+  if (issues.some((issue) => issue.type === 'missing-closeout-evidence')) {
+    lines.push('下一步收尾：先写入当前会话 `artifacts/closeout.json`，记录 `requirementsCoverage` 和 `deliveryChecklist`，再报告完成。')
+  }
+  if (issues.some((issue) => issue.type === 'missing-visual-evidence')) {
+    lines.push('下一步视觉验收：先写入当前会话 `artifacts/visual.json`，记录 `tooling`、`screensChecked`、`statesChecked`、`status` 和 `summary`，再报告完成。')
+  }
+  if (gateHint) {
+    lines.push(gateHint)
+  }
+  lines.push('暂不要报告完成。先完成剩余任务、明确关闭任务，或修复方案包，使其成为可信的交付记录。')
+  return lines.join('\n')
+}