sillyspec 3.25.6 → 3.25.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.25.6",
+  "version": "3.25.7",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/init.js

@@ -123,6 +123,70 @@ 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');
+
+/**
+ * 为 Claude Code 注入 CLAUDE.md（版本感知幂等）。
+ * - 不存在：写完整模板（templates/claude-instruction.md）+ 顶部版本注释
+ * - 存在无标记：追加受管段（INJECTION_CONTENT）+ 版本块标记
+ * - 存在同版本标记：跳过
+ * - 存在异版本标记：追加态刷新块 / 完整态仅 stderr 提示
+ * @param {string} projectDir - 源码项目根
+ */
+export function injectClaudeInstructions(projectDir) {
+  const filePath = join(projectDir, 'CLAUDE.md');
+  const version = getVersion();
+  // 完整态顶部注释（新文件首行，轻量、不限制后续编辑）
+  const fullHeader = `<!-- SillySpec v${version} — 由 sillyspec init 生成，可自由编辑；重跑 init 同版本不更新 -->`;
+  // 追加态受管段（包版本块标记，明确"勿手动编辑此段"）
+  const appendBlock =
+    `<!-- SillySpec v${version} START — 由 sillyspec init 注入，勿手动编辑此段 -->\n` +
+    INJECTION_CONTENT.trimEnd() +
+    `\n<!-- SillySpec END -->`;
+
+  // 状态 1：文件不存在 → 写完整模板 + 顶部版本注释
+  if (!existsSync(filePath)) {
+    let template = '';
+    try {
+      template = readFileSync(CLAUDE_TEMPLATE_PATH, 'utf8');
+    } catch {
+      console.error(`❌ [sillyspec] 未找到 Claude 模板：${CLAUDE_TEMPLATE_PATH}`);
+      return;
+    }
+    writeFileSync(filePath, fullHeader + '\n' + template);
+    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 已生成（SillySpec v${version}）`));
+    return;
+  }
+
+  const 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}）`));
+    return;
+  }
+
+  const existingVersion = markMatch[1];
+  // 状态 3：同版本 → 跳过（幂等，不写）
+  if (existingVersion === version) return;
+
+  // 状态 4：异版本（升级）。区分追加态（有 START...END 块）/ 完整态（仅顶部注释）。
+  const startBlockRe = /<!-- SillySpec v\S+\s+START[\s\S]*?<!-- SillySpec END -->/;
+  if (startBlockRe.test(content)) {
+    // 4a：追加态 → 用当前版本受管段替换该块（块外用户内容字节保留）
+    writeFileSync(filePath, content.replace(startBlockRe, appendBlock));
+    console.log(chalk.green(`    ✓ Claude Code CLAUDE.md 受管段已升级（v${existingVersion} → v${version}）`));
+  } else {
+    // 4b：完整态 → 不覆盖（保留用户改动），仅 stderr 打印升级提示
+    console.error(`⚠️ [sillyspec] SillySpec 升级 v${existingVersion}→v${version}，CLAUDE.md 未自动更新（保留你的改动）。如需采用新模板：备份后删除 CLAUDE.md 再跑 sillyspec init。`);
+  }
+}
+
 // ── 检测工具 ──
 
 function detectTools(projectDir) {
@@ -273,6 +337,11 @@ async function doInstall(projectDir, tools, subprojects = [], specDir = null) {
     }
   }
 
+  // 注入 CLAUDE.md（claude，版本感知幂等三态四分支；claude 不进 INSTRUCTION_TOOLS）
+  if (tools.includes('claude')) {
+    injectClaudeInstructions(projectDir);
+  }
+
   // 复制 skills 到各工具目录
   const skillToolDirs = {
     claude: '.claude/skills',

package/src/quicklog.js

@@ -81,6 +81,36 @@ function sanitizeDesc(description) {
   return s.length > 120 ? s.slice(0, 120) + '…' : s
 }
 
+// 从关联变更的 proposal/design 提取首个 # 标题（去「提案书（Proposal）— / 设计文档（Design）—」固定前缀）。
+// 让 quick --linked-changes 启动时（用户常不带 --input）也能拿到语义标题，而非 (quick 任务) 占位。
+// 读不到任何标题返回 ''（调用方再回退占位符，保持向后兼容）。
+export function deriveTitleFromLinkedChange(specBase, change) {
+  if (!change) return ''
+  for (const f of ['proposal.md', 'design.md']) {
+    let content
+    try { content = readFileSync(join(specBase, 'changes', change, f), 'utf8') } catch { continue }
+    const m = content.match(/^#\s+(.+?)\s*$/m)
+    if (!m) continue
+    const raw = m[1].trim()
+    // 标题惯例「# 提案书（Proposal）— <desc>」「# 设计文档（Design）— <desc>」→ 取破折号后的 desc
+    const dash = raw.match(/[—-]\s*(.+)$/)
+    return dash ? dash[1].trim() : raw
+  }
+  return ''
+}
+
+// 从 quick step3 --output 四字段提取「需求：」摘要，用于翻完成时刷新标题行
+// （覆盖启动时的占位/弱标题）。提取失败返回 ''（不刷新）。
+function extractTitleFromResult(result) {
+  if (!result) return ''
+  const m = String(result).match(/需求：([^\n\r]*?)(?:\s+根因：|$)/)
+  if (!m) return ''
+  let t = m[1].replace(/[，。；,;].*$/, '').trim() // 截到首个标点，取核心句
+  if (!t) return ''
+  if (t.length > 80) t = t.slice(0, 80) + '…'
+  return t
+}
+
 function sanitizeResult(resultText) {
   // 保留换行：结果块支持字段化结构（需求：/根因：/方案：/结果：...）。多行时 flipEntryInContent
   // 写成字段块（追加在「状态：」行下方），不是单条「结果：<长行>」。仅去首尾空白。
@@ -189,10 +219,13 @@ function tasksPath(specBase, change) {
   return join(specBase, 'changes', change, 'tasks.md')
 }
 
-// 追加未勾选 task；幂等（已含同 qlId 则跳过）
+// 追加未勾选 task；幂等（已含同 qlId 则跳过）。
+// 关联变更目录不存在（笔误 / 未建 / 仅作标签关联）→ 不 fabricate stub 目录（历史坑 quick-change-phantom：
+// mkdirSync 硬造 changes/<名>/tasks.md，致 quick --done 边界审计自造自拦 BLOCK）。关联仍记入
+// QUICKLOG「关联变更」行（allocateQuicklogEntry 独立写入，不依赖本函数）。
 function appendTaskCheckbox(specBase, change, qlId, desc) {
   const dir = join(specBase, 'changes', change)
-  mkdirSync(dir, { recursive: true })
+  if (!existsSync(dir)) return
   const p = tasksPath(specBase, change)
   let content = existsSync(p) ? readFileSync(p, 'utf8') : ''
   if (content.includes(qlId)) return
@@ -219,6 +252,12 @@ function flipEntryInContent(content, qlId, result, changedFiles = []) {
   const lines = content.split('\n')
   const startIdx = lines.findIndex(l => l.startsWith(`## ${qlId} |`))
   if (startIdx === -1) return null
+  // 翻完成时若能从结果提取「需求：」摘要，刷新标题行（覆盖启动时的占位/弱标题）
+  const newTitle = extractTitleFromResult(result)
+  if (newTitle) {
+    const headerCore = lines[startIdx].match(/^(## \S+ \| [^|]+ \| )/)
+    if (headerCore) lines[startIdx] = headerCore[1] + newTitle
+  }
   let endIdx = lines.length
   for (let i = startIdx + 1; i < lines.length; i++) {
     if (lines[i].startsWith('## ')) { endIdx = i; break }

package/src/run/complete.js

@@ -54,6 +54,22 @@ function validateMetadata(cwd, stageName, specBase) {
   }
 }
 
+/**
+ * 读取 design.md frontmatter 的 scale 字段（brainstorm 末步写入 'small'|'large'）。
+ * completeStep 的下一步提示据此分叉：small→quick，large/读不到→plan（fail-safe 走重流程）。
+ * 只解析首个 YAML frontmatter 块，避免误读正文里的 "scale:"。
+ */
+function readDesignScale(specBase, changeName) {
+  if (!changeName) return null
+  const designPath = join(specBase, 'changes', changeName, 'design.md')
+  if (!existsSync(designPath)) return null
+  const text = readFileSync(designPath, 'utf8')
+  const fm = text.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/)
+  if (!fm) return null
+  const m = fm[1].match(/^scale:[ \t]*['"]?(\w+)/m)
+  return m ? m[1] : null
+}
+
 /**
  * 验证关键文件是否存在于正确的变更目录下
  * 防止 AI 将文件写到错误的路径
@@ -100,6 +116,36 @@ function validateFileLocations(cwd, stageName, progress, changeName, specBase) {
   }
 }
 
+/**
+ * 坑1：用 --done --answer 解掉「已 waiting 的步骤」。
+ *
+ * completeStep 的 currentIdx 选择（findIndex pending||in-progress）排除 waiting，导致
+ * --done --answer 落到已 --wait 暂停的 requiresWait 步骤时跳过它、--answer 静默丢失、步骤永久
+ * 卡 WAITING、末步报「Step N 等待用户输入」无法 finish。本函数把首个 waiting 步骤拉回 pending
+ * + 补 waitAnswer（对齐 continueStep 对 requiresWait 的 shouldReturnToCurrentStep=回 pending 语义），
+ * 让主流程 requiresWait 门控见 waitAnswer 已置→不阻断→正常 completed。
+ *
+ * @param {object[]} steps - stageData.steps（原地修改）
+ * @param {string|null|undefined} doneAnswer - --answer 值；空则不触发（返回 -1）
+ * @param {string} nowStr - 时间戳字符串（用于 waitAnswers[].answeredAt）
+ * @returns {number} 被解的 waiting 步骤 idx；无 waiting 或无 answer 返回 -1
+ */
+export function resolveWaitingStepWithAnswer(steps, doneAnswer, nowStr) {
+  if (!doneAnswer) return -1
+  const waitIdx = steps.findIndex(s => s && s.status === 'waiting')
+  if (waitIdx === -1) return -1
+  const ws = steps[waitIdx]
+  ws.waitAnswer = doneAnswer
+  ws.waitAnswers = Array.isArray(ws.waitAnswers) ? ws.waitAnswers : []
+  ws.waitAnswers.push({ round: (ws.waitRound || 0) + 1, answer: doneAnswer, answeredAt: nowStr })
+  delete ws.waitReason
+  delete ws.waitOptions
+  delete ws.waitedAt
+  ws.status = 'pending'
+  ws.completedAt = null
+  return waitIdx
+}
+
 export async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
   const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, confirmMode = null, isForceBaseline = false, isAllowNew = false } = options
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
@@ -129,7 +175,17 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
   }
 
   const steps = stageData.steps
-  const currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+  let currentIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+  // ── 坑1：--done --answer 解「已 waiting 的步骤」──
+  // findIndex 仅查 pending/in-progress，排除 waiting；故 --done --answer 落到已 --wait 暂停的
+  // requiresWait 步骤时会跳过它、把 --answer 静默丢弃，步骤永久卡 WAITING、末步报「等待用户输入」。
+  // 修复：带 doneAnswer 且存在 waiting 步骤时，把首个 waiting 拉回 pending + 补 waitAnswer，主流程
+  // requiresWait 门控见 waitAnswer 已置→不阻断→正常 completed。仅 --answer 触发，普通 --done 零变化。
+  const _resolvedWaitIdx = resolveWaitingStepWithAnswer(steps, options && options.doneAnswer, new Date().toLocaleString('zh-CN', { hour12: false }))
+  if (_resolvedWaitIdx !== -1) {
+    currentIdx = _resolvedWaitIdx
+    console.log(`⚠️  Step "${steps[_resolvedWaitIdx].name}" 此前处于 waiting，--done --answer 已补回答并拉回待完成。`)
+  }
   if (currentIdx === -1) {
     console.error('没有待完成的步骤')
     process.exit(1)
@@ -332,6 +388,22 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     } else if (stageName === 'verify') {
       // verify 的"验证通过"提示延后到下方 validator 通过后才打印，
       // 避免校验失败（FAIL / 缺 verify-result.md）时仍声称"验证通过可以归档"。
+    } else if (stageName === 'brainstorm') {
+      // brainstorm 下一步按 design.md 的 scale 分叉（与末步 prompt 的 large→plan / small→quick 对齐），
+      // 不走下方 _getNextSuggestion —— 后者按全局状态机「第一个未完成且上游就绪的阶段」推荐，
+      // 当 scan 未完成时会误推 scan（回头路），与 brainstorm 已完成、应进入 plan/quick 矛盾。
+      // 历史教训：曾因此让 agent 在 brainstorm 完成后被误导去跑 scan。
+      const _bscale = readDesignScale(specBase, changeName)
+      if (_bscale === 'small') {
+        console.log(`\n👉 brainstorm 已完成（small）。下一步：sillyspec run quick --linked-changes ${changeName}`)
+      } else {
+        console.log(`\n👉 brainstorm 已完成。下一步：sillyspec run plan${changeName ? ` --change ${changeName}` : ''}（scale=large 或未标 small 走完整 plan）`)
+      }
+    } else if (stageName === 'quick') {
+      // quick 是收尾阶段（辅助流程，不走主链 scan→archive），完成后该提交，而非推 scan。
+      // 走下方 _getNextSuggestion 会因 scan 是 STAGE_ORDER 首位、永未完成而误推 scan（回头路），
+      // 与 brainstorm 同类问题（见上注释），故给 quick 专属分支。
+      console.log('\n👉 quick 已完成。下一步：提交本次改动（git commit / sillyspec-commit），或 sillyspec run <stage> 继续其他阶段。')
     } else {
       // D1 暗衔接修：阶段刚完成，CLI 本就知道状态机下一步是哪个阶段（_getNextSuggestion），
       // 却只丢一句「下一步由你决定」让 agent 自己猜命令。改为按 progress 实际状态给出精确命令。
@@ -738,7 +810,16 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
     // 阶段完成后明确下一步（agent 常卡：stageData completed 但不知要 run <下一阶段> 推进 currentStage）
     const nextStageHint = { brainstorm: 'plan', plan: 'execute', execute: 'verify', verify: 'archive' }[stageName]
     if (nextStageHint) {
-      console.log(`\n👉 ${stageName} 已完成。下一步：sillyspec run ${nextStageHint}${changeName ? ` --change ${changeName}` : ''}`)
+      // brainstorm 按 design.md frontmatter 的 scale 分叉（与末步 prompt 对齐）：
+      //   small → quick --linked-changes（小变更免走完整 plan）；large / 读不到 scale → plan（保守默认）。
+      // 修历史 bug：此处曾硬编码 brainstorm→plan 不读 scale，small 档与末步 prompt（quick）矛盾、误导小变更进 plan。
+      let hintStage = nextStageHint
+      let hintChangeFlag = changeName ? ` --change ${changeName}` : ''
+      if (stageName === 'brainstorm' && changeName && readDesignScale(specBase, changeName) === 'small') {
+        hintStage = 'quick'
+        hintChangeFlag = ` --linked-changes ${changeName}`
+      }
+      console.log(`\n👉 ${stageName} 已完成。下一步：sillyspec run ${hintStage}${hintChangeFlag}`)
       if (stageName === 'execute') {
         console.log(`   ⚠️ 若 worktree 改动还没 apply 到主工作区，先：sillyspec worktree apply ${changeName}`)
         console.log(`   （apply 不需要先 commit，支持 working tree 未提交改动）`)

package/src/run/shared.js

@@ -278,6 +278,11 @@ export function resolveChangeDir(cwd, progress, specDir = null) {
 /**
  * 触发 sync（平台模式走自己的链路，跳过；否则 await import sync.js）。
  */
+// sync 总超时熔断：sync.js 是 best-effort 后台回传（每请求已有 10s 超时），但 sync() 可能串行多次
+// fetchJson 累积等待、阻塞 --done。给 8s 总超时，超时放弃（best-effort，失败不影响正确性，下次 --done 重试）。
+// 历史痛点：--done 在 sync 慢时体感 hang，用户被迫用外部 timeout 兜底。
+const SYNC_TOTAL_TIMEOUT_MS = 8_000
+
 export async function triggerSync(cwd, changeName, platformOpts = {}) {
   // 平台模式（SillyHub）走自己的回传链路，不走 CLI 内置 sync
   if (platformOpts?.specRoot || platformOpts?.runtimeRoot) return
@@ -285,7 +290,15 @@ export async function triggerSync(cwd, changeName, platformOpts = {}) {
     if (changeName && !existsSync(join(cwd, '.sillyspec', 'changes', changeName))) return
     // shared.js 在 src/run/，sync.js 在 src/ → 退一层
     const syncMod = await import('../sync.js')
-    await syncMod.sync(changeName, cwd)
+    let timer
+    try {
+      await Promise.race([
+        syncMod.sync(changeName, cwd),
+        new Promise((resolve) => { timer = setTimeout(resolve, SYNC_TOTAL_TIMEOUT_MS) }),
+      ])
+    } finally {
+      clearTimeout(timer) // sync 先完成则清掉未触发的 timer，避免泄漏
+    }
   } catch (e) {
     // sync.js 不存在或同步失败，静默跳过
     console.warn('⚠️ 同步失败:', e.message)

package/src/run/stage.js

@@ -22,7 +22,7 @@ import { writeAtomicSync } from '../fs-atomic.js'
 import { resolveSpecDir, resolveChangeDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps } from './shared.js'
 import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
 import { outputStep } from './prompt.js'
-import { allocateQuicklogEntry } from '../quicklog.js'
+import { allocateQuicklogEntry, deriveTitleFromLinkedChange } from '../quicklog.js'
 import { checkTransition } from '../stage-contract.js'
 
 export async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false, platformOpts = {}, quickOpts = {}) {
@@ -239,8 +239,14 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         const linkedChanges = Array.isArray(quickOpts?.linkedChanges) ? quickOpts.linkedChanges : []
         // CLI 接管：分配 ql-ID + 写 QUICKLOG「进行中」条目 + 关联 tasks.md（持锁、当天唯一）
         const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
+        // 标题回退：启动 quick 不带 --input 时，从关联变更的 proposal/design 提取语义标题，
+        // 避免 QUICKLOG/tasks.md 落 (quick 任务) 占位（deriveTitleFromLinkedChange 读不到则空→sanitizeDesc 回退占位）。
+        let quickDesc = quickOpts?.taskDescription || ''
+        if (!quickDesc && linkedChanges.length > 0) {
+          quickDesc = deriveTitleFromLinkedChange(specBase, linkedChanges[0])
+        }
         const { qlId } = await allocateQuicklogEntry(specBase, gitUser, {
-          description: quickOpts?.taskDescription || '',
+          description: quickDesc,
           linkedChanges,
           allowedFiles,
         })

package/src/stage-review.js

@@ -41,7 +41,7 @@ const STAGE_REVIEW_TYPE = { brainstorm: 'design', plan: 'plan', propose: 'propos
  */
 export function renderReviewJsonContract({ stage, changeDir, reviewRunId, tier } = {}) {
   if (tier === 'self') {
-    return '> review.json 契约:tier=self(变更规模小),无需产出 review.json,当前 agent 自审即可。'
+    return '> review.json 契约:tier=self(此刻 design.md 变更文件数 ≤3,当前 agent 自审即可)。⚠️ 注意:本判定基于此刻 design.md 快照——Stage Review Gate 会以 --done 时刻的 design.md 重新判定,若 design 后续扩大到 >3 文件,tier 将升级为 independent 并硬要求独立审查子代理产出 review.json。以 gate 实际校验结果为准(FAILED 即 independent 需补 review.json),勿据本提示提前断言无需 review.json。'
   }
   const reviewType = STAGE_REVIEW_TYPE[stage] || 'design'
   const mainDoc = STAGE_MAIN_DOC[stage] || 'design.md'

package/templates/claude-instruction.md

@@ -0,0 +1,23 @@
+# Claude Code 指引
+
+## 项目说明
+本项目使用 **SillySpec** 管理变更，采用文档驱动开发。SillySpec 是给 Agent 调用的 CLI 流程控制器，不是给人类直接使用的产品，也不是处理业务逻辑的工具——你（Agent）通过 CLI 告诉它"我在哪"，它告诉你"下一步做什么"；你执行步骤，它校验产出、推进状态，人类只在关键决策点介入审批。要考虑多 agent 同时操作代码，代码随时可能变化。所有变更以稳定、可用、可维护为目标，按生产级标准处理。
+
+## 核心规则
+1. **禁止绕过本文件规则和 SillySpec 流程**。所有变更走 sillyspec 流程，不裸改裸提交。
+2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md）或现有代码依据，无依据不改。
+3. **新功能 / 大改动走完整流程**：`brainstorm → plan → execute → verify → archive`。
+4. **小修复 / 小调整走 quick**：`sillyspec run quick`。
+5. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档。
+6. **判规模选档**：≤3 文件、范围明确走 `quick`；多阶段 / 架构级走完整流程。
+7. **代码先行不补流程（倒推 B 模式）**：代码若已先写好，**不回头补 brainstorm/plan 装样子**——用 `quick --done` 收尾 + 补 quicklog 条目，把已落盘改动如实登记进进度库。
+8. **实证核验再 `--done`**：`quick --done` 前先 `npm test` + `npm run lint`，以落盘文件与测试结果为准，不信口头"已完成"。
+9. **中途停下用 `sillyspec status` / `sillyspec resume` 存进度**，不直接 commit 半成品。
+10. **实现完成后对照文档验收**（design.md / 模块文档），并检查是否影响已有测试。
+11. **非测试逻辑本身有误时，禁止改测试来"通过"**——修逻辑，不修测试。
+12. **hook 拦截提交时禁止跳过**（`.husky/pre-push`），修复问题后再提交。
+13. **代码必须兼容 Windows / Linux / macOS**（路径 / 换行 / 并发都要顾）。
+14. **任务记录隔离**：永不重置 / reset / 清零已存在的 change；多个活跃 change 各自 `--change <名>` 隔离不重叠；quick 同一 QUICKLOG 按 ql-ID 条目追加，不冲突。
+15. **quicklog 手动精修**：CLI 只写骨架，`--done` 后手动补语义化标题 / 文件多行带括注 / 结果四段。
+16. **代码可能随时在修改**（多 agent 并行），Edit 前重跑 + 查最新态；破坏性 git op 前先备份。
+17. **不奉承用户**，禁止"你说得对"类话术，直接给结论、依据、方案。

package/CLAUDE.md

@@ -1,40 +0,0 @@
-# Claude Code 指引
-
-# SillySpec工具定位
-1. 是给Agent调用的CLI工具，非人类直接使用
-2. 管理Agent工作流的CLI工具，非业务工具
-
-## 文件生命周期文档同步
-每次修改 `src/stages/` 下的阶段定义（prompt、步骤、输出文件名等）或 `src/run.js`、`src/progress.js` 等影响文件生命周期的代码后，**必须同步更新** `docs/sillyspec/file-lifecycle.md`，确保文档与代码一致。
-
-### 触发更新的典型改动
-- 新增/删除/重命名阶段步骤
-- 修改步骤 prompt 中的输出文件名（如 verify-result.md）
-- 修改阶段间的流转逻辑（如 archive 归档方式）
-- 新增/删除运行时文件类型（如 gate-status.json）
-- 修改 ProgressManager 的数据存储方式（如 SQLite 表结构变更）
-
-### 更新检查清单
-- [ ] 文件名引用一致（prompt 输出的文件名 == validateFileLocations 期望的文件名）
-- [ ] 阶段步骤描述与 `src/stages/*.js` 一致
-- [ ] 归档/清理流程描述与实际代码逻辑一致
-- [ ] 数据库 Schema 描述与 `src/db.js` 一致
-- [ ] 更新文档头部 `updated_at` 时间戳
-
-## 提示词文档同步（docs/prompt/）
-`docs/prompt/` 收录各阶段 CLI→Agent 的**逐步提示词原文**（人类可读 md 参考）。详见 `docs/prompt/README.md`。
-
-### 数据源关系（重要 — 避免双写漂移）
-- **唯一数据源 = `src/stages/*.js`**（`definition.steps[].prompt`，CLI 运行时读这里）+ `src/run/prompt.js`（注入框架：persona / 铁律 / 占位符替换 / 完成后执行命令模板）。
-- `docs/prompt/*.md` 是源码的**机械提取人类可读镜像**，由 `node docs/prompt/_extract.mjs` 一键再生（源码 → `_extracted.json` → md）。提取脚本对静态阶段直接读 `definition.steps`，对动态阶段（plan/execute）用示例输入跑 `buildPlanSteps`/`buildExecuteSteps` 得到真实 prompt。
-- **禁止手改 md 里的 prompt 原文**（下次提取会被覆盖，且与源码不一致）。要改提示词，改源码后重跑脚本。
-
-### 触发同步的改动
-- 修改 `src/stages/*.js`：`definition.steps[].prompt`、步骤名、步骤增删/重排、wait 配置、`_globalGuardrails`、title/description
-- 修改 `src/run/prompt.js`：persona / 铁律 / 占位符替换 / 完成后执行命令模板
-- 修改 `stage-review.js` / `review-tier.js` / `knowledge-match.js`：影响 `{REVIEW_JSON_CONTRACT}` / `{REVIEW_TIER}` / `{KNOWLEDGE_HIT_REPORT}` 等动态块
-
-### 同步步骤
-1. 改源码
-2. 运行 `node docs/prompt/_extract.mjs`（刷新 `docs/prompt/_extracted.json`）
-3. 按变动同步对应 `docs/prompt/<stage>.md`（prompt 正文以 `_extracted.json` 为准逐字替换）+ 必要时更新 `docs/prompt/README.md`（占位符总表 / persona 表 / CLI 注入框架）