sillyspec 3.27.11 → 3.28.0

package/src/init.js

@@ -8,7 +8,7 @@ import { getVersion } from './version.js';
 import { gitQuiet } from './git-helper.js';
 import { renderExample } from './config-schema.js';
 // 向后兼容：getVersion 已抽到轻量 version.js（避免 index.js 为 --version 静态加载 init.js 的 inquirer 税），
-// 此处 re-export 保持 init.js 既有导出 API 不破坏（如 test/init-claude-injection.test.mjs）。
+// 此处 re-export 保持 init.js 既有导出 API 不破坏（如 test/init-agents-injection.test.mjs）。
 export { getVersion };
 
 const __filename = fileURLToPath(import.meta.url);
@@ -87,10 +87,12 @@ const TOOL_LABELS = {
   opencode: 'OpenCode (通过 INSTRUCTIONS.md)',
 };
 
-const INSTRUCTION_TOOLS = ['codex', 'gemini', 'opencode'];
+// 小段追加工具（gemini/opencode）。codex 不在此列——AGENTS.md 是跨工具通用的标准内容源，
+// codex 与 claude 共用完整模板注入（injectAgentsInstructions）；gemini/opencode 改 @AGENTS.md
+// 指针需先验证两家对 @ 导入语法的支持，留待后续变更。
+const INSTRUCTION_TOOLS = ['gemini', 'opencode'];
 
 const INSTRUCTION_FILE_MAP = {
-  codex: 'AGENTS.md',
   gemini: 'GEMINI.md',
   opencode: 'INSTRUCTIONS.md',
 };
@@ -130,21 +132,38 @@ function injectInstructions(tool, projectDir) {
   writeFileSync(filePath, content.trimEnd() + '\n\n' + INJECTION_CONTENT);
 }
 
-// ── 注入 CLAUDE.md（claude，版本感知幂等）──
-// 与 codex/gemini/opencode 不同：claude 需要完整 CLAUDE.md 模板 + 版本感知三态。
-// 故 claude 不进 INSTRUCTION_TOOLS，单独走此函数（design: 2026-08-02-init-claude-md）。
-const CLAUDE_TEMPLATE_PATH = join(__dirname, '..', 'templates', 'claude-instruction.md');
+// ── 注入 AGENTS.md / CLAUDE.md（claude + codex，版本感知幂等）──
+// AGENTS.md 是唯一承载完整指引的内容源（跨工具通用标准）；CLAUDE.md 仅为 @AGENTS.md
+// 导入指针（Claude Code 记忆导入语法）。取代 design: 2026-08-02-init-claude-md 的
+// CLAUDE.md 单文件方案——其 D-004 预留的「marker 方案迁移」即本次变更。
+const AGENTS_TEMPLATE_PATH = join(__dirname, '..', 'templates', 'agents-instruction.md');
 
 /**
- * 为 Claude Code 注入 CLAUDE.md（版本感知幂等）。
- * - 不存在：写完整模板（templates/claude-instruction.md）+ 顶部版本注释
- * - 存在无标记：追加受管段（INJECTION_CONTENT）+ 版本块标记
- * - 存在同版本标记：跳过
- * - 存在异版本标记：追加态刷新块 / 完整态仅 stderr 提示
+ * 移除 codex 老安装的旧版小段（injectInstructions 方案：`## SillySpec` 段，追加在 EOF）。
+ * 优先精确匹配旧文本；用户编辑过 / CRLF 漂移导致匹配失败时回退按标题截到 EOF。
+ * @param {string} content - AGENTS.md 原文
+ * @returns {string} 截除旧段后的内容（已 trimEnd）
+ */
+function stripLegacyAgentsBlock(content) {
+  const exact = INJECTION_CONTENT.trimEnd();
+  const idx = content.indexOf(exact);
+  if (idx >= 0) return content.slice(0, idx).trimEnd();
+  const headingIdx = content.indexOf('## SillySpec');
+  if (headingIdx >= 0) return content.slice(0, headingIdx).trimEnd();
+  return content;
+}
+
+/**
+ * 为 AGENTS.md 注入完整指引（版本感知幂等，三态四分支 + 旧标记迁移）。
+ * - 不存在：写完整模板（templates/agents-instruction.md）+ 顶部版本注释
+ * - 存在无标记：追加受管段（INJECTION_CONTENT）+ 版本块标记；
+ *   含旧 `## SillySpec` 段（codex 老安装）先截除再追加（marker 迁移，防双段）
+ * - 存在同版本标记：跳过（不写文件）
+ * - 存在异版本标记：追加态刷新块 / 完整态仅 stderr 提示（保留用户改动）
  * @param {string} projectDir - 源码项目根
  */
-export function injectClaudeInstructions(projectDir) {
-  const filePath = join(projectDir, 'CLAUDE.md');
+export function injectAgentsInstructions(projectDir) {
+  const filePath = join(projectDir, 'AGENTS.md');
   const version = getVersion();
   // 完整态顶部注释（新文件首行，轻量、不限制后续编辑）
   const fullHeader = `<!-- SillySpec v${version} — 由 sillyspec init 生成，可自由编辑；重跑 init 同版本不更新 -->`;
@@ -158,23 +177,27 @@ export function injectClaudeInstructions(projectDir) {
   if (!existsSync(filePath)) {
     let template = '';
     try {
-      template = readFileSync(CLAUDE_TEMPLATE_PATH, 'utf8');
+      template = readFileSync(AGENTS_TEMPLATE_PATH, 'utf8');
     } catch {
-      console.error(`❌ [sillyspec] 未找到 Claude 模板：${CLAUDE_TEMPLATE_PATH}`);
+      console.error(`❌ [sillyspec] 未找到 Agent 指引模板：${AGENTS_TEMPLATE_PATH}`);
       return;
     }
     writeFileSync(filePath, fullHeader + '\n' + template);
-    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 已生成（SillySpec v${version}）`));
+    console.log(chalk.green(`    ✓ AGENTS.md 已生成（SillySpec v${version}，完整指引）`));
     return;
   }
 
-  const content = readFileSync(filePath, 'utf8');
+  let content = readFileSync(filePath, 'utf8');
 
   // 无任何 `<!-- SillySpec v` 标记 → 状态 2：追加受管段（原文字节保留）
   const markMatch = content.match(/<!-- SillySpec v(\S+)/);
   if (!markMatch) {
-    writeFileSync(filePath, content.trimEnd() + '\n\n' + appendBlock + '\n');
-    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 已追加 SillySpec 受管段（v${version}）`));
+    if (content.includes('## SillySpec')) {
+      content = stripLegacyAgentsBlock(content);
+      console.log(chalk.green('    ✓ AGENTS.md 旧版 SillySpec 小段已迁移为新受管段'));
+    }
+    writeFileSync(filePath, content + '\n\n' + appendBlock + '\n');
+    console.log(chalk.green(`    ✓ AGENTS.md 已追加 SillySpec 受管段（v${version}）`));
     return;
   }
 
@@ -187,11 +210,60 @@ export function injectClaudeInstructions(projectDir) {
   if (startBlockRe.test(content)) {
     // 4a：追加态 → 用当前版本受管段替换该块（块外用户内容字节保留）
     writeFileSync(filePath, content.replace(startBlockRe, appendBlock));
-    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 受管段已升级（v${existingVersion} → v${version}）`));
+    console.log(chalk.green(`    ✓ AGENTS.md 受管段已升级（v${existingVersion} → v${version}）`));
   } else {
     // 4b：完整态 → 不覆盖（保留用户改动），仅 stderr 打印升级提示
-    console.error(`⚠️ [sillyspec] SillySpec 升级 v${existingVersion}→v${version}，CLAUDE.md 未自动更新（保留你的改动）。如需采用新模板：备份后删除 CLAUDE.md 再跑 sillyspec init。`);
+    console.error(`⚠️ [sillyspec] SillySpec 升级 v${existingVersion}→v${version}，AGENTS.md 未自动更新（保留你的改动）。如需采用新模板：备份后删除 AGENTS.md 再跑 sillyspec init。`);
+  }
+}
+
+/**
+ * 为 Claude Code 写 CLAUDE.md 指针（@AGENTS.md 导入，薄文件）。
+ * - 不存在：写指针文件（版本头注释 + @AGENTS.md）
+ * - 存在无标记（用户自有文件）：文末追加受管指针块（原文字节保留）
+ * - 指针态：同版本跳过；异版本仅刷新标记行中的版本号
+ * - 旧完整态（2026-08-02 方案：标记在但无 @AGENTS.md）：不动，仅 stderr 提示迁移路径
+ * @param {string} projectDir - 源码项目根
+ */
+export function injectClaudePointer(projectDir) {
+  const filePath = join(projectDir, 'CLAUDE.md');
+  const version = getVersion();
+  const fullPointer = `<!-- SillySpec v${version} — CLAUDE.md 指针：内容统一维护在 AGENTS.md（@ 导入），可自由编辑 -->\n\n@AGENTS.md\n`;
+  const appendBlock =
+    `<!-- SillySpec v${version} START — 由 sillyspec init 注入，勿手动编辑此段 -->\n` +
+    `@AGENTS.md\n` +
+    `<!-- SillySpec END -->`;
+
+  // 状态 1：文件不存在 → 写指针文件
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, fullPointer);
+    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 指针已生成（@AGENTS.md，SillySpec v${version}）`));
+    return;
+  }
+
+  const content = readFileSync(filePath, 'utf8');
+  const markMatch = content.match(/<!-- SillySpec v(\S+)/);
+
+  // 状态 2：无标记（用户自有文件）→ 追加受管指针块
+  if (!markMatch) {
+    writeFileSync(filePath, content.trimEnd() + '\n\n' + appendBlock + '\n');
+    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 已追加 @AGENTS.md 受管指针块（v${version}）`));
+    return;
   }
+
+  const existingVersion = markMatch[1];
+  // 状态 3：同版本 → 跳过（幂等，不写）
+  if (existingVersion === version) return;
+
+  // 状态 4：异版本。区分指针态（含 @AGENTS.md）/ 旧完整态（无导入行）。
+  if (!content.includes('@AGENTS.md')) {
+    // 4b：旧完整态 → 不覆盖，提示迁移到 AGENTS.md 单源
+    console.error(`⚠️ [sillyspec] 检测到旧版完整 CLAUDE.md（v${existingVersion}）。当前方案以 AGENTS.md 为内容源、CLAUDE.md 仅作 @AGENTS.md 指针；为保留你的改动未自动迁移。如需迁移：备份后删除 CLAUDE.md 再跑 sillyspec init。`);
+    return;
+  }
+  // 4a：指针态 → 仅刷新标记行中的版本号（指针无用户语义内容，不动其余字节）
+  writeFileSync(filePath, content.replace(`<!-- SillySpec v${existingVersion}`, `<!-- SillySpec v${version}`));
+  console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 指针标记已升级（v${existingVersion} → v${version}）`));
 }
 
 // ── 检测工具 ──
@@ -363,7 +435,7 @@ function doInstall(projectDir, tools, subprojects = [], specDir = null, options
     }
   }
 
-  // 注入指令文件（codex/gemini/opencode）
+  // 注入指令文件（gemini/opencode 小段追加，不进 AGENTS.md 注入器）
   for (let i = 0; i < tools.length; i++) {
     const toolName = tools[i];
     if (INSTRUCTION_TOOLS.includes(toolName)) {
@@ -371,9 +443,14 @@ function doInstall(projectDir, tools, subprojects = [], specDir = null, options
     }
   }
 
-  // 注入 CLAUDE.md（claude，版本感知幂等三态四分支；claude 不进 INSTRUCTION_TOOLS）
+  // 注入 AGENTS.md 完整指引（claude/codex 共用：版本感知幂等三态四分支 + 旧 ## SillySpec 段迁移）
+  if (tools.includes('claude') || tools.includes('codex')) {
+    injectAgentsInstructions(projectDir);
+  }
+
+  // 注入 CLAUDE.md 指针（claude 专属：@AGENTS.md 导入薄文件，须在 AGENTS.md 之后）
   if (tools.includes('claude')) {
-    injectClaudeInstructions(projectDir);
+    injectClaudePointer(projectDir);
   }
 
   // 复制 skills 到各工具目录（--no-skills 可跳过：platform init 等场景勿污染项目内工具目录）
@@ -473,8 +550,8 @@ export async function cmdInit(projectDir, options = {}) {
   const version = getVersion();
   const resolvedSpecDir = specDir ? resolve(specDir) : null;
 
-  // C14c：绿地/棕地引导——必须在 doInstall 之前捕获目录状态（init 会创建 .sillyspec/CLAUDE.md/
-  // .gitignore 等，事后检测会误判）；棕地（已有非隐藏源码）建议 scan，绿地（空目录）建议 brainstorm。
+  // C14c：绿地/棕地引导——必须在 doInstall 之前捕获目录状态（init 会创建 .sillyspec/AGENTS.md/
+  // CLAUDE.md/.gitignore 等，事后检测会误判）；棕地（已有非隐藏源码）建议 scan，绿地（空目录）建议 brainstorm。
   let brownfield = false;
   try {
     const entries = readdirSync(projectDir, { withFileTypes: true });

package/src/machine-interface.js

@@ -541,3 +541,66 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot,
     return { envelope, exitCode: EXIT_UNKNOWN };
   }
 }
+
+// ============ 全局状态总览（单一状态源，2026-09-02 跨 agent 协作改进 P0-1）============
+
+/**
+ * 全局状态总览：全部活跃变更列表 + 各自阶段/步骤进度 + ghost/stall 标记。
+ *
+ * 与 gate/derive（单变更粒度）和 progress dump（单变更视角、daemon 轮询）互补——
+ * 本命令回答「这个项目现在有谁在动哪些变更」，供 SillyHub 面板 / 跨 agent 消费
+ * （`sillyspec progress show --json`）。
+ *
+ * 只读契约（同 runGate D-002@v1）：仅 ProgressManager 读路径，不写 sillyspec.db；
+ * DB 不存在 → fail-closed 返回 exit 2（项目未初始化，无从总览），不建库。
+ * 数据组装单点在 StageMachine.overview（与 show 汇总视图同源 listChanges/_stallSignal），
+ * 本函数只做 envelope 封装——沿「只聚合不新增校验」的模块定位。
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd - 项目根目录
+ * @param {string} [opts.specBase] - .sillyspec（或平台 specRoot）目录；默认 resolveSpecDir(cwd)
+ * @returns {{ envelope: object, exitCode: number }} exitCode：0 总览成功（含空列表）/ 2 无法核验
+ */
+export function runStatusOverview({ cwd, specBase } = {}) {
+  const specRoot = specBase || resolveSpecDir(cwd);
+
+  try {
+    const dbPath = join(specRoot, '.runtime', 'sillyspec.db');
+    if (!existsSync(dbPath)) {
+      const envelope = buildEnvelope({
+        command: 'progress show',
+        ok: false,
+        errors: [`无法核验：进度库不存在（${dbPath}）——项目尚未初始化进度，只读总览不会为其建库`],
+      });
+      return { envelope, exitCode: EXIT_UNKNOWN };
+    }
+
+    const pm = new ProgressManager({ specDir: specRoot });
+    const data = pm.overview(cwd);
+
+    // ghost（目录缺失残留记录）升 warnings：不阻断 ok（总览本身是成功的，ghost 是待清理事实）
+    const warnings = data.changes
+      .filter(c => c.ghost)
+      .map(c => `${c.name}: 目录缺失（残留记录，sillyspec doctor --cleanup-ghosts --confirm 可归档清理）`);
+    // P2-2-①：未决同步冲突同样升 warnings（冲突可见性——daemon/面板看顶层即知有冲突待处理）
+    for (const cf of (data.pending_conflicts || [])) {
+      warnings.push(`${cf.change}: 未决同步冲突（${cf.type === 'progress' ? '进度' : 'spec 树'}，sillyspec platform resolve 处理）`);
+    }
+
+    const envelope = buildEnvelope({
+      command: 'progress show',
+      ok: true,
+      warnings,
+      data,
+    });
+    return { envelope, exitCode: EXIT_OK };
+  } catch (e) {
+    // 内部异常兜底（同 runDerive）：stdout 永远合法 JSON，exit 2
+    const envelope = buildEnvelope({
+      command: 'progress show',
+      ok: false,
+      errors: [`internal: ${e.message}`],
+    });
+    return { envelope, exitCode: EXIT_UNKNOWN };
+  }
+}

package/src/module-changelog.js

@@ -0,0 +1,116 @@
+/**
+ * module-changelog.js — 模块卡「变更索引」解析（模块→变更历史只读索引）。
+ *
+ * 背景（2026-08-31 变更关联审计）：模块卡的变更史是全仓变更名提名密度最高的活文档
+ * （12 张卡 + 6 个 sidecar，45+ 行），但格式是 agent 归档同步时自发形成的半结构化惯例，
+ * 从未被解析消费。本模块把它变成机器可读：供 prompt.js buildModuleContextInjection
+ * 注入「最近变更」，让 brainstorm/plan/execute 免扫描地知道该模块最近被谁动过。
+ *
+ * 格式实测变体（勿按单一格式写死）：
+ *   标题：`## 变更索引（表格，初始为空）`（scan 模板）与 `## 变更索引`（手写）两种；
+ *   行体：表格 `| 日期 | 变更名 | 摘要 |` 与列表 `- <变更名> | <摘要>` 混用（同一卡可混合）；
+ *   名字：日期前缀真实变更名（2026-08-13-foo）或 ql-* quicklog id，偶见 `（quick）`后缀；
+ *   噪音：表头/分隔行、纯日期遗留行（`- 2026-06-03 | 初始文档`）、sidecar 迁出指针行
+ *   （`见 \`x.changelog.md\`——…`）——全部经「整格匹配变更名」自然排除，无需黑名单。
+ * sidecar（split-changelog 迁出产物）：`<module>.changelog.md`，frontmatter +
+ * `# <module> 变更索引（changelog sidecar）` + 同款表格。卡内表是迁出前历史保留不动，
+ * 与 sidecar 同名条目按首次出现去重（卡优先）。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 变更名整格匹配（剥 `（quick）` 类括号后缀后校验）：日期前缀真实名 / ql-* quicklog id */
+const CHANGE_NAME_RE = /^(\d{4}-\d{2}-\d{2}-[a-z0-9][a-z0-9-]*|ql-\d{8}-\d{3}-[a-z0-9]+)$/i
+
+/** 卡内小节标题：`## 变更索引` 前缀匹配（兼容「（表格，初始为空）」后缀变体） */
+const SECTION_HEADING_RE = /^##\s*变更索引/
+
+/**
+ * 单行清洗为变更名：去列表标记 / 表格竖线两侧、剥括号后缀，整格匹配不过返回 null。
+ * @param {string} raw 行内单元格或列表项原文
+ * @returns {string|null}
+ */
+function toChangeName(raw) {
+  const s = String(raw || '').trim().replace(/^[-|]\s*/, '').replace(/\s*[（(][^）)]*[)）]\s*$/, '').trim()
+  return CHANGE_NAME_RE.test(s) ? s : null
+}
+
+/**
+ * 从「变更索引」段文本解析条目（纯函数，卡内小节与 sidecar 正文共用）。
+ * 表格行取「第一个整格匹配变更名的 cell」为名、最后一个非名 cell 为摘要；
+ * 列表行 `- name | desc` 同理。表头/分隔行/纯日期遗留行/指针行均不匹配自然跳过。
+ * @param {string} text 已切出的段文本（CRLF 已归一）
+ * @returns {{ name: string, summary: string }[]}
+ */
+export function parseChangelogEntries(text) {
+  const entries = []
+  const seen = new Set()
+  for (const line of String(text || '').replace(/\r\n/g, '\n').split('\n')) {
+    if (/^\|[-:\s|]+\|$/.test(line.trim())) continue // 表格分隔行
+    let cells
+    if (line.startsWith('|')) {
+      cells = line.split('|').slice(1, -1).map(c => c.trim())
+    } else {
+      const item = line.match(/^\s*-\s+(.+)/)
+      if (!item) continue
+      cells = item[1].split('|').map(c => c.trim())
+    }
+    const nameIdx = cells.findIndex(toChangeName)
+    if (nameIdx === -1) continue
+    const name = toChangeName(cells[nameIdx])
+    if (seen.has(name)) continue
+    // 摘要 = 名字 cell 之后最后一个非空 cell（容忍行尾悬空竖线与「只有名字」的列表行）
+    let summary = ''
+    for (let i = cells.length - 1; i > nameIdx; i--) {
+      if (cells[i]) { summary = cells[i]; break }
+    }
+    entries.push({ name, summary })
+    seen.add(name)
+  }
+  return entries
+}
+
+/** 切出卡内「## 变更索引…」段（到下一个 ## 标题或文末）；无该段返回 '' */
+function extractChangelogSection(cardText) {
+  const lines = String(cardText || '').replace(/\r\n/g, '\n').split('\n')
+  const start = lines.findIndex(l => SECTION_HEADING_RE.test(l))
+  if (start === -1) return ''
+  const end = lines.findIndex((l, i) => i > start && /^##\s/.test(l))
+  return lines.slice(start + 1, end === -1 ? undefined : end).join('\n')
+}
+
+/** sidecar 正文剥 frontmatter（--- … ---）后整文即变更索引段 */
+function stripFrontmatter(text) {
+  const t = String(text || '').replace(/\r\n/g, '\n')
+  return t.startsWith('---') ? t.replace(/^---\n.*?\n---\n?/s, '') : t
+}
+
+/**
+ * 读单个模块的变更史（卡内段 + sidecar，同名去重，按名字内日期降序 = 最近在前）。
+ * 展示用途，宁可漏抓不可错抓：解析失败/文件缺失 → []（不抛，不阻断注入）。
+ * @param {string} modulesDir 模块文档目录（…/docs/<project>/modules）
+ * @param {string} moduleId
+ * @returns {{ name: string, summary: string }[]}
+ */
+export function readModuleRecentChanges(modulesDir, moduleId) {
+  if (!modulesDir || !moduleId) return []
+  const entries = []
+  const seen = new Set()
+  const absorb = list => {
+    for (const e of list) {
+      if (seen.has(e.name)) continue
+      entries.push(e)
+      seen.add(e.name)
+    }
+  }
+  try {
+    const cardPath = join(modulesDir, `${moduleId}.md`)
+    if (existsSync(cardPath)) absorb(parseChangelogEntries(extractChangelogSection(readFileSync(cardPath, 'utf8'))))
+    const sidecarPath = join(modulesDir, `${moduleId}.changelog.md`)
+    if (existsSync(sidecarPath)) absorb(parseChangelogEntries(stripFrontmatter(readFileSync(sidecarPath, 'utf8'))))
+  } catch { /* 读失败按无变更史处理 */ }
+  // 排序键 = 名字内前 8 位数字（日期前缀名 2026-08-13 与 ql-20260804 都取到各自日期；
+  // 连续 \d{8} 匹配不到带横线的日期格式，按位收集）。无数字名垫底
+  const dateKey = n => Number((n.match(/\d/g) || []).slice(0, 8).join('') || '0')
+  return entries.sort((a, b) => dateKey(b.name) - dateKey(a.name))
+}

package/src/progress/change-registry.js

@@ -273,6 +273,34 @@ export class ChangeRegistry {
     if (renamed) console.log(`✅ 变更已重命名：${oldName} → ${newName}`);
   }
 
+  /**
+   * 删除变更（change-delete 命令的 DB 侧，2026-08-30 用户反馈①）
+   * SQL: UPDATE changes SET status = 'deleted'
+   *
+   * 语义区分：此前删除靠 git rm + 借道 doctor 幽灵清理，而幽灵清理把删除行写成
+   * archived——DB 无法区分「流程正常收尾的归档」与「中途废弃的删除」，事后审计只能
+   * 回溯 git。现在两种终态在 DB 里显式分离：
+   *   - archived = archive 阶段 --confirm / quick 轻量归档（流程收尾）
+   *   - deleted  = change-delete 显式废弃（行保留供审计，status 即语义载体）
+   * 与 unregisterChange 不同：不做 archive 终态一致化——删除不是「完成」，给删除行收尾
+   * archive 阶段属伪造终态（对齐 cleanupGhostChanges 对「目录真丢失」幽灵保持 status-only
+   * 的可逆语义）；stages/steps 行不动，保留原审计价值。
+   */
+  deleteChange(cwd, changeName) {
+    if (!changeName) {
+      console.warn('⚠️  deleteChange: changeName 为空，跳过');
+      return;
+    }
+    const db = this.pm._ensureDB(cwd);
+    db.transaction(() => {
+      const sqlDb = db.getDb();
+      const now = new Date().toISOString();
+      sqlDb.prepare(`UPDATE changes SET status = 'deleted', last_active = ? WHERE name = ?`).run(now, changeName);
+      // 本地脏度（D-013 / task-04）：删除也是本地状态推进（triggerSync 据此推终态/墓碑上行）
+      this.pm._touchLocalModified(cwd, changeName, now);
+    });
+  }
+
   /**
    * 从活跃列表移除变更（归档时调用，不物理删除）
    * SQL: UPDATE changes SET status = 'archived'

package/src/progress/shared.js

@@ -29,6 +29,12 @@ export const MAIN_FLOW_ORDER = ['brainstorm', 'plan', 'execute', 'verify', 'arch
 // progress 数据版本（v3 = SQLite；v4 = changes 加 base_ts / 本地脏度两列，platform-sync §8）
 export const CURRENT_VERSION = 5;
 
+// 滞留提示阈值（天，2026-08-30 用户反馈②：7 个「代码全落地但流程没收口」的变更挂 38 天
+// 无人发现）：活跃变更 last_active 距今超该天数且流程未收口（archive 未完成）时，progress
+// show 输出滞留提示行。与 doctor-diagnostics 空壳目录 7 天门槛（GHOST_EMPTY_DIR_STALE_MS）
+// 同量级——「多久算滞留」全仓统一口径。
+export const STALL_WARN_DAYS = 7;
+
 // 空阶段骨架
 export function emptyStage() {
   return { status: 'pending', steps: [], startedAt: null, completedAt: null };