sillyspec 3.15.2 → 3.16.1

package/src/stage-contract.js

@@ -0,0 +1,347 @@
+/**
+ * StageContract — 阶段协议
+ *
+ * 每个阶段声明：允许的前置阶段、必须的产出、校验器、后续阶段。
+ * CLI 不再相信 prompt 完成，completeStep 后必须过 validator。
+ */
+
+import { existsSync, readdirSync } from 'fs'
+import { join, basename } from 'path'
+
+/**
+ * 校验结果
+ * @typedef {{ ok: boolean, errors: string[], warnings: string[] }} ValidationResult
+ */
+
+/**
+ * 阶段合约
+ * @typedef {{
+ *   stage: string,
+ *   description: string,
+ *   allowedFrom: string[],
+ *   allowedTo: string[],
+ *   validators: Function[],
+ * }} StageContract
+ */
+
+// ============ Validators ============
+
+/**
+ * scan 完成校验：检查 7 份 scan 文档 + manifest
+ */
+function validateScanOutputs(cwd, changeName, context = {}) {
+  const { projectName } = context
+  const docsRoot = projectName
+    ? join(cwd, '.sillyspec', 'docs', projectName, 'scan')
+    : join(cwd, '.sillyspec', 'docs', 'scan')
+
+  const requiredDocs = [
+    'ARCHITECTURE.md',
+    'CONVENTIONS.md',
+    'STRUCTURE.md',
+    'INTEGRATIONS.md',
+    'TESTING.md',
+    'CONCERNS.md',
+    'PROJECT.md',
+  ]
+
+  const errors = []
+  const warnings = []
+
+  for (const doc of requiredDocs) {
+    if (!existsSync(join(docsRoot, doc))) {
+      errors.push(`scan 文档缺失: ${docsRoot}/${doc}`)
+    }
+  }
+
+  // 检查 modules 目录
+  const modulesRoot = projectName
+    ? join(cwd, '.sillyspec', 'docs', projectName, 'modules')
+    : join(cwd, '.sillyspec', 'docs', 'modules')
+  if (!existsSync(modulesRoot)) {
+    warnings.push('modules 目录不存在')
+  } else {
+    const modules = readdirSync(modulesRoot).filter(f => f.endsWith('.md'))
+    if (modules.length === 0) {
+      warnings.push('modules 目录为空')
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+/**
+ * plan 完成校验：检查 plan.md 生成
+ */
+function validatePlanOutputs(cwd, changeName) {
+  const planDir = join(cwd, '.sillyspec', 'changes', changeName)
+  const planFile = join(planDir, 'plan.md')
+  const errors = []
+
+  if (!existsSync(planFile)) {
+    errors.push(`plan.md 缺失: ${planFile}`)
+  }
+
+  const warnings = []
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+/**
+ * verify 完成校验：检查 verify 报告存在
+ */
+function validateVerifyOutputs(cwd, changeName) {
+  const planDir = join(cwd, '.sillyspec', 'changes', changeName)
+  const errors = []
+  const warnings = []
+
+  // verify 至少应该有 run 记录
+  if (!existsSync(join(planDir, 'plan.md'))) {
+    errors.push(`变更目录缺失: ${planDir}`)
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+/**
+ * archive 完成校验：检查归档目录完整性
+ */
+function validateArchiveOutputs(cwd, changeName) {
+  const errors = []
+  const warnings = []
+  const archiveDir = join(cwd, '.sillyspec', 'changes', 'archive')
+  const date = new Date().toISOString().slice(0, 10)
+  const destDir = join(archiveDir, `${date}-${changeName}`)
+
+  // 检查归档目录是否存在
+  if (!existsSync(destDir)) {
+    errors.push(`归档目录缺失: ${destDir}`)
+    return { ok: false, errors, warnings }
+  }
+
+  // 检查核心文档
+  const requiredDocs = ['plan.md']
+  const recommendedDocs = ['design.md', 'module-impact.md']
+
+  for (const doc of requiredDocs) {
+    if (!existsSync(join(destDir, doc))) {
+      errors.push(`归档目录缺失核心文档: ${doc}`)
+    }
+  }
+
+  for (const doc of recommendedDocs) {
+    if (!existsSync(join(destDir, doc))) {
+      warnings.push(`归档目录缺少推荐文档: ${doc}`)
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+/**
+ * archive 前置校验：所有主流程阶段完成
+ */
+function validateChangeClosed(cwd, changeName) {
+  const errors = []
+  const warnings = []
+
+  // 检查前置阶段状态
+  const progressDir = join(cwd, '.sillyspec', '.runtime')
+  // 这里只做文件层面的检查，DB 检查在 run.js 里做
+  const changeDir = join(cwd, '.sillyspec', 'changes', changeName)
+  if (!existsSync(changeDir)) {
+    errors.push(`变更目录不存在: ${changeDir}`)
+    return { ok: false, errors, warnings }
+  }
+
+  if (!existsSync(join(changeDir, 'plan.md'))) {
+    errors.push(`plan.md 缺失 — 请确保 plan 阶段已完成`)
+  }
+
+  return { ok: errors.length === 0, errors, warnings }
+}
+
+// ============ Contract Registry ============
+
+/**
+ * 主流程阶段（有严格转换顺序）
+ */
+const mainFlowStages = ['brainstorm', 'plan', 'execute', 'verify']
+
+/**
+ * 辅助阶段（可独立运行，无严格转换顺序）
+ */
+const auxiliaryStages = ['scan', 'quick', 'explore', 'archive', 'status', 'doctor']
+
+/**
+ * @type {Object<string, StageContract>}
+ */
+const contracts = {
+  // === 主流程 ===
+  brainstorm: {
+    stage: 'brainstorm',
+    description: '需求分析与设计',
+    allowedFrom: [],           // 任何变更的起始阶段
+    allowedTo: ['plan'],
+    validators: [],
+  },
+  plan: {
+    stage: 'plan',
+    description: '任务拆解与规划',
+    allowedFrom: ['brainstorm'],
+    allowedTo: ['execute'],
+    validators: [validatePlanOutputs],
+  },
+  execute: {
+    stage: 'execute',
+    description: '代码实现',
+    allowedFrom: ['plan'],
+    allowedTo: ['verify'],
+    validators: [],
+  },
+  verify: {
+    stage: 'verify',
+    description: '验证与测试',
+    allowedFrom: ['execute'],
+    allowedTo: ['archive'],
+    validators: [validateVerifyOutputs],
+  },
+  archive: {
+    stage: 'archive',
+    description: '归档与收口',
+    allowedFrom: ['verify'],
+    allowedTo: [],
+    validators: [validateChangeClosed, validateArchiveOutputs],
+  },
+
+  // === 辅助阶段 ===
+  scan: {
+    stage: 'scan',
+    description: '项目扫描',
+    allowedFrom: [],           // 无前置要求
+    allowedTo: [],             // 不进入主流程
+    validators: [validateScanOutputs],
+  },
+  quick: {
+    stage: 'quick',
+    description: '快速任务',
+    allowedFrom: [],           // 无前置要求
+    allowedTo: [],             // 不进入主流程
+    validators: [],
+  },
+  explore: {
+    stage: 'explore',
+    description: '代码探索',
+    allowedFrom: [],
+    allowedTo: [],
+    validators: [],
+  },
+  status: {
+    stage: 'status',
+    description: '状态查看',
+    allowedFrom: [],
+    allowedTo: [],
+    validators: [],
+  },
+  doctor: {
+    stage: 'doctor',
+    description: '环境诊断',
+    allowedFrom: [],
+    allowedTo: [],
+    validators: [],
+  },
+}
+
+// ============ Public API ============
+
+/**
+ * 获取阶段合约
+ */
+export function getContract(stageName) {
+  return contracts[stageName] || null
+}
+
+/**
+ * 校验状态转换是否允许
+ * @param {string} fromStage - 当前阶段（空字符串表示变更起始）
+ * @param {string} toStage - 目标阶段
+ * @returns {{ allowed: boolean, reason?: string }}
+ */
+export function checkTransition(fromStage, toStage) {
+  const contract = contracts[toStage]
+  if (!contract) {
+    return { allowed: false, reason: `未知阶段: ${toStage}` }
+  }
+
+  // 辅助阶段随时可执行（archive 除外：从主流程进入 archive 需要校验）
+  if (auxiliaryStages.includes(toStage) && toStage !== 'archive') {
+    return { allowed: true }
+  }
+
+  // archive 特殊处理：从 verify 来的允许，从其他主流程阶段来的需要校验
+  if (toStage === 'archive') {
+    if (fromStage === 'verify') {
+      return { allowed: true }
+    }
+    // 独立运行 archive（无前置）也允许
+    if (!fromStage || auxiliaryStages.includes(fromStage)) {
+      return { allowed: true }
+    }
+    return { allowed: false, reason: 'archive 的前置阶段是 verify，不能从 ' + fromStage + ' 跳转' }
+  }
+
+  // 从辅助阶段进入主流程：允许（用户可能 scan 完直接 brainstorm 或 plan）
+  if (auxiliaryStages.includes(fromStage)) {
+    return { allowed: true }
+  }
+
+  // 无前置阶段（变更起始）：只能开始 brainstorm 或辅助阶段
+  if (!fromStage) {
+    // 主流程必须从 brainstorm 开始
+    if (contract.allowedFrom.length === 0) {
+      return { allowed: true }
+    }
+    return { allowed: false, reason: `${toStage} 需要先完成 ${contract.allowedFrom.join(' 或 ')}` }
+  }
+
+  // 主流程内部跳转：检查目标阶段的 allowedFrom 是否包含 fromStage
+  if (contract.allowedFrom.includes(fromStage)) {
+    return { allowed: true }
+  }
+
+  return { allowed: false, reason: `${toStage} 的前置阶段是 ${contract.allowedFrom.join(' 或 ')}，不能从 ${fromStage} 跳转` }
+}
+
+/**
+ * 执行阶段完成校验
+ * @param {string} stageName
+ * @param {string} cwd
+ * @param {string} changeName
+ * @param {object} context - 额外上下文（如 projectName）
+ * @returns {ValidationResult}
+ */
+export function runValidators(stageName, cwd, changeName, context = {}) {
+  const contract = contracts[stageName]
+  if (!contract || contract.validators.length === 0) {
+    return { ok: true, errors: [], warnings: [] }
+  }
+
+  const allErrors = []
+  const allWarnings = []
+
+  for (const validator of contract.validators) {
+    try {
+      const result = validator(cwd, changeName, context)
+      allErrors.push(...(result.errors || []))
+      allWarnings.push(...(result.warnings || []))
+    } catch (e) {
+      allErrors.push(`校验器 ${validator.name || 'unknown'} 异常: ${e.message}`)
+    }
+  }
+
+  return { ok: allErrors.length === 0, errors: allErrors, warnings: allWarnings }
+}
+
+/**
+ * 获取所有主流程阶段
+ */
+export { mainFlowStages, auxiliaryStages }

package/src/stages/archive.js

@@ -124,15 +124,14 @@ module_id: <module-id>
     },
     {
       name: '确认归档',
-      prompt: `确认归档内容并执行目录移动。
+      prompt: `确认归档内容，由 CLI 执行目录移动。
 
 ### 操作
 1. 展示：变更目录名、包含的文件列表（含 module-impact.md）、生成总结
-2. **直接执行归档**（本步骤完成后自动移动）：
-   - 创建 archive 目录：\`mkdir -p .sillyspec/changes/archive\`
-   - 移动变更目录：\`mv .sillyspec/changes/<change-name> .sillyspec/changes/archive/<change-name>\`
-   - 确认移动成功：\`ls .sillyspec/changes/archive/<change-name>/\`
-3. 确保所有 checkbox 都已勾选
+2. 确保所有 checkbox 都已勾选
+3. 让用户确认后，用 \`--confirm\` 完成本步骤：
+   \`sillyspec run archive --done --confirm --output "确认归档"\`
+4. CLI 会创建 \`.sillyspec/changes/archive/\`，并将变更目录移动到 \`.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/\`
 
 ### 输出
 归档完成 + archive 目录路径`,
@@ -147,10 +146,7 @@ module_id: <module-id>
 1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
 2. \`git add .sillyspec/changes/\` — 暂存归档结果（不要 commit，由用户通过统一提交工具处理）
 3. \`git add .sillyspec/docs/\` — 暂存模块文档更新（如有）
-4. 更新 sillyspec.db 中的阶段状态：
-   - 清除当前变更信息（归档后不再活跃）
-   - 如果是主变更（有 MASTER.md），标记所有阶段为 ✅，然后清除
-   - 历史记录追加时间 + 归档完成
+4. 确认 sillyspec.db 中该变更已不再 active（确认归档步骤由 CLI 调用 unregisterChange）
 
 ### 输出
 归档完成确认 + 累积规范统计`,

package/src/stages/brainstorm.js

@@ -274,7 +274,10 @@ design.md 文件路径 + 自审结果
 ### 注意
 - 自审不通过不要进入下一步
 - 不确定的问题标注「⚠️ 自审存疑」`,
-
+      outputHint: 'design.md 文件路径 + 自审结果',
+      optional: false
+    },
+    {
       name: '用户确认并生成规范文件',
       prompt: `用户确认设计方案，生成规范文件。
 

package/src/stages/doctor.js

@@ -84,13 +84,54 @@ for f in .sillyspec/projects/*.yaml; do
   stack_md="$p/.sillyspec/STACK.md"
   [ -f "$local_yaml" ] && echo "✅ local.yaml ($name)" || echo "⚠️ local.yaml ($name) — 不存在"
   if [ -f "$local_yaml" ]; then
-    grep -q 'build:' "$local_yaml" && echo "  ✅ build 命令已配置" || echo "  ⚠️ 缺少 build 命令"
     grep -q 'test:' "$local_yaml" && echo "  ✅ test 命令已配置" || echo "  ⚠️ 缺少 test 命令"
   fi
   [ -f "$stack_md" ] && echo "✅ STACK.md ($name)" || echo "⚠️ STACK.md ($name) — 不存在"
 done
 \`\`\`
 
+### 6. Worktree 隔离环境检查
+\`\`\`bash
+# 检测当前目录是否在 submodule 中
+SUPERPROJECT=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
+if [ -n "$SUPERPROJECT" ]; then
+  echo "⚠️ 当前目录在 git submodule 内，worktree 隔离不可用"
+else
+  echo "✅ 不在 submodule 中"
+fi
+
+# 检测是否已在 linked worktree 中
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+if [ "$GIT_DIR" != "$GIT_COMMON" ] && [ -z "$SUPERPROJECT" ]; then
+  echo "✅ 已在 linked worktree 中"
+else
+  echo "ℹ️ 在主仓库中（非 worktree）"
+fi
+
+# 检查 worktree 存储目录是否被 .gitignore 忽略
+WT_DIR='.sillyspec/.runtime/worktrees'
+if git check-ignore -q "$WT_DIR" 2>/dev/null; then
+  echo "✅ worktree 目录已被 .gitignore 忽略 ($WT_DIR)"
+else
+  echo "❌ worktree 目录未被 .gitignore 忽略 ($WT_DIR) — worktree 创建将被阻断"
+  echo "   修复: 在 .gitignore 中添加 $WT_DIR/"
+fi
+
+# 检查 DB 中的 isolation 状态
+DB_FILE='.sillyspec/.runtime/sillyspec.db'
+if [ -f "$DB_FILE" ]; then
+  echo ""
+  echo "isolation 状态（来自 sillyspec.db）:"
+  sqlite3 -header -column "$DB_FILE" "SELECT name, isolation_status AS status, isolation_mode AS mode, isolation_reason AS reason FROM changes WHERE status='active'" 2>/dev/null || echo "⚠️ 查询 isolation 失败"
+else
+  echo ""
+  echo "ℹ️ sillyspec.db 不存在（尚未初始化）"
+fi
+else
+  echo "ℹ️ gate-status.json 不存在（尚未进入 execute 阶段）"
+fi
+\`\`\`\n
 ### 输出
 汇总所有检查结果，按以下格式：
 \`\`\`
@@ -304,7 +345,7 @@ timeout 5 which docker 2>/dev/null && echo "✅ Docker 可用" || echo "ℹ️ D
 **常见问题及修复：**
 - CLI 未安装 → \`npm install -g sillyspec\`
 - 缺少 local.yaml → \`sillyspec init\` 重新生成，或手动创建
-- local.yaml 缺少 build/test → 补充对应命令
+- local.yaml 缺少 test 命令 → 补充对应命令
 - 缺少 STACK.md → \`sillyspec run scan\` 重新扫描
 - sillyspec.db 状态不一致 → \`sillyspec run <阶段> --reset\` 重置对应阶段
 - 孤儿目录 → 确认后 \`rm -rf .sillyspec/changes/<目录名>\`

package/src/stages/execute.js

@@ -61,8 +61,14 @@ const fixedPrefix = [
 3. 后续所有子代理的 cwd 设为该 worktree 路径
 4. 如果创建失败 → 报错并停止（不要在无隔离状态下继续）
 
+### 降级模式
+CLI 可能自动降级（sandbox 限制、已在 linked worktree 中）：
+- \`mode: native-worktree\` — 已在 linked worktree，直接复用
+- \`mode: in-place-fallback\` — git worktree add 失败，降级为 in-place + baseline protection
+- 这两种模式都会输出 worktree 路径和分支名，正常继续即可
+
 ### 输出
-worktree 路径 + 分支名
+worktree 路径 + 分支名 + 模式（如果有）
 
 ### 完成后执行
 sillyspec run execute --done --output "worktree 路径 + 分支名"`,
@@ -184,19 +190,40 @@ const fixedSuffix = [
     name: '完成确认',
     prompt: `所有任务完成后的收尾。
 
-### 操作（有 worktree）
+先检查当前 worktree 的隔离模式：
+\`\`\`bash
+node -e "import('./src/worktree.js').then(w => { const wm = new w.WorktreeManager(); const m = wm.getMeta('<change-name>'); console.log(m ? JSON.stringify({mode: m.mode, path: m.worktreePath}) : 'no meta'); })"
+# 或从 DB 读取：
+sqlite3 -json .sillyspec/.runtime/sillyspec.db "SELECT isolation_status, isolation_mode, isolation_reason FROM changes WHERE name='<change-name>'" 2>/dev/null
+\`\`\`
+
+### 操作（mode = worktree，SillySpec 创建的隔离 worktree）
 1. 运行 \`sillyspec worktree apply --check-only <change-name>\`
 2. 展示 diff 摘要（文件列表 + 变更统计）
 3. 检查结果说明（是否通过文件清单校验）
 4. 用户确认后运行 \`sillyspec worktree apply <change-name>\`
-5. apply 成功 → 自动 cleanup
+5. apply 成功 → 运行 \`sillyspec worktree cleanup <change-name>\` → 输出 Worktree: cleaned
 6. apply 失败 → 展示错误详情，用户选择重试或手动处理
 7. 如果用户不想 apply → 运行 \`sillyspec worktree cleanup <change-name>\` 丢弃
 8. 建议下一步：\`sillyspec run verify\`
 
+### 操作（mode = native-worktree，用户已有的 linked worktree）
+1. 运行 \`sillyspec worktree apply --check-only <change-name>\`
+2. 展示 diff 摘要
+3. 用户确认后运行 \`sillyspec worktree apply <change-name>\`
+4. **不要运行 cleanup** — 这是用户自己的 worktree，SillySpec 不能删除
+5. 输出 Worktree: kept（SillySpec 未创建此 worktree，保留不动）
+6. 建议下一步：\`sillyspec run verify\`
+
+### 操作（mode = in-place-fallback，降级模式无隔离目录）
+1. 展示本次执行摘要（\`git diff\` 查看变更）
+2. 跳过 apply 和 cleanup（没有隔离 worktree）
+3. 输出 Worktree: none（降级为 in-place，无隔离目录需要清理）
+4. 建议下一步：\`sillyspec run verify\`
+
 ### 操作（无 worktree / --no-worktree 模式）
-1. 跳过 apply 和 cleanup 步骤（因为没有 worktree）
-2. 展示本次执行摘要
+1. 展示本次执行摘要
+2. 输出 Worktree: none
 3. 提示用户直接使用 \`git diff\` 查看变更
 4. 建议下一步：\`sillyspec run verify\`
 

package/src/stages/propose.js

@@ -109,7 +109,10 @@ export const definition = {
 - 表名/字段名/类名必须来自真实代码或标注"新增"
 - 用户场景必须用 Given/When/Then 格式
 - tasks.md 只列任务名，细节在 plan 阶段展开`,
-
+      outputHint: '四个文件路径',
+      optional: false
+    },
+    {
       name: '自检门控',
       prompt: `自检生成的规范文件。
 

package/src/stages/quick.js

@@ -27,12 +27,12 @@ export const definition = {
 1. 使用预注入的 git 用户名：\`<git-user>\`
 2. 无 \`--change\`：创建 .sillyspec/quicklog/QUICKLOG-\`<git-user>\`.md\`（已存在则追加），写入：
    \`\`\`
-   ## ql-<YYYYMMDD>-<NNN>-<short4> | <now-datetime> | <一句话任务描述>
+   ## ql-<YYYYMMDD>-<NNN>-<XXXX> | <now-datetime> | <一句话任务描述>
    状态：进行中
    文件：<预估要改的文件>
    \`\`\`
-   - ID 格式：\`ql-YYYYMMDD-NNN-XXXX\`（如 ql-20260603-001-a3f2）
-   - \`XXXX\` 是 4 位随机十六进制（防多文件/并发冲突）
+   - ID 格式：\`ql-YYYYMMDD-NNN-XXXX\`
+   - \`XXXX\` 是 4 位随机十六进制字符（如 a3f2、b7c1、00ef），**不是描述词缩写**
    - 追加前扫描文件中已有的 \`ql-<当天日期>-\` 前缀的最大序号，+1 作为新序号
    - 每天从 001 开始，跨日重新计数
    - 此 ID 可被 design.md / plan.md / archive / module 变更索引引用

package/src/stages/scan.js

@@ -12,7 +12,7 @@ export const definition = {
 1. 列出项目顶层目录：\`ls -d */ 2>/dev/null | grep -v node_modules | grep -v '.git' | grep -v '.sillyspec'\`
 2. 对每个顶层目录，快速判断是否为独立项目（检查 package.json / pom.xml / build.gradle / pyproject.toml / go.mod 等构建文件）
 3. 对每个疑似独立项目，检测技术栈：\`cat <dir>/package.json 2>/dev/null | head -5\` 或类似
-4. 对比 \`.sillyspec/projects/\` 已有配置，找出未注册的子项目
+4. 对比 \`{PROJECTS_ROOT}/\` 已有配置，找出未注册的子项目
 
 ### 判断标准（满足任一即为子项目）
 - 有独立的构建文件（package.json, pom.xml, build.gradle, pyproject.toml 等）
@@ -41,8 +41,8 @@ export const definition = {
       prompt: `确定本次要扫描的项目列表。
 
 ### 操作
-1. \`ls .sillyspec/projects/*.yaml 2>/dev/null\` — 列出所有已注册项目
-2. 对每个项目，检查已有的 scan 文档状态：\`ls .sillyspec/docs/<project>/scan/*.md 2>/dev/null\`
+1. \`ls {PROJECTS_ROOT}/*.yaml 2>/dev/null\` — 列出所有已注册项目
+2. 对每个项目，检查已有的 scan 文档状态：\`ls {DOCS_ROOT}/scan/*.md 2>/dev/null\`
 3. 按以下格式展示：
 
 \`\`\`
@@ -75,7 +75,7 @@ export const definition = {
 1. 进入项目目录（子项目用其 path，如 \`packages/dashboard/\`）
 2. \`cat package.json pom.xml build.gradle go.mod Cargo.toml requirements.txt pyproject.toml Gemfile composer.json 2>/dev/null\`
 3. \`find <project-dir> -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null\`
-4. 结果保存到 \`.sillyspec/docs/<project>/scan/_env-detect.md\`（临时文件，扫描完删除）
+4. 结果保存到 \`{DOCS_ROOT}/scan/_env-detect.md\`（临时文件，扫描完删除）
 
 ### 输出
 每个项目的环境探测结果摘要`,
@@ -90,7 +90,7 @@ export const definition = {
 ### 操作
 对扫描列表中的每个项目分别执行：
 1. 检查 7 份文档是否存在：ARCHITECTURE、STRUCTURE、CONVENTIONS、INTEGRATIONS、TESTING、CONCERNS、PROJECT
-   路径：\`.sillyspec/docs/<project>/scan/<DOC>.md\`
+   路径：\`{DOCS_ROOT}/scan/<DOC>.md\`
 2. 列出已有 ✅ 和缺失 ⬜
 
 ### 输出
@@ -139,16 +139,16 @@ export const definition = {
     },
     {
       name: '生成本地配置',
-      prompt: `自动生成 .sillyspec/.runtime/local.yaml 本地配置文件。
+      prompt: `自动生成 .sillyspec/local.yaml 本地配置文件。
 
 ### 操作
-1. 检查 .sillyspec/.runtime/local.yaml 是否已存在，已存在则跳过（提示"local.yaml 已存在，跳过生成"）
+1. 检查 .sillyspec/local.yaml 是否已存在，已存在则跳过（提示"local.yaml 已存在，跳过生成"）
 2. 根据项目类型生成默认配置：
    - **Node.js**（有 package.json）：build: "npm run build", test: "npm test", lint: "npm run lint", type: nodejs
    - **Maven**（有 pom.xml）：build: "mvn compile", test: "mvn test", lint: "mvn checkstyle:check", type: maven
    - **Gradle**（有 build.gradle）：build: "./gradlew build", test: "./gradlew test", type: gradle
    - **通用项目**：只写注释模板, type: generic
-3. 确保目录存在：mkdir -p .sillyspec/.runtime
+3. 确保目录存在：mkdir -p .sillyspec
 4. 原子写入（先写 tmp 文件再 rename）
 
 ### 文件格式
@@ -187,7 +187,7 @@ local.yaml 生成结果（已存在/已生成）`,
 
 ### 操作
 对扫描列表中的每个项目分别执行：
-1. 检查 \`.sillyspec/docs/<project>/modules/_module-map.yaml\` 是否已存在，已存在则跳过
+1. 检查 \`{DOCS_ROOT}/modules/_module-map.yaml\` 是否已存在，已存在则跳过
 2. 分析项目源码目录结构，识别模块划分：
    - 用 \`find . -maxdepth 3 -type d -not -path "*/node_modules/*" -not -path "*/.git/*"\` 查看目录结构
    - 每个有明确职责的独立目录识别为一个模块
@@ -200,7 +200,7 @@ local.yaml 生成结果（已存在/已生成）`,
 4. 分析跨模块依赖关系：
    - 用 grep import/require 分析模块间的引用链
    - 填充 depends_on（本模块依赖谁）和 used_by（谁依赖本模块）
-5. 生成 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`
+5. 生成 \`{DOCS_ROOT}/modules/_module-map.yaml\`
 6. 如果 modules/ 目录不存在，先创建
 7. 原子写入（先写 tmp 文件再 rename）
 
@@ -305,8 +305,8 @@ _module-map.yaml 生成结果（已存在/已生成/模块列表）`,
 
 ### 操作
 对扫描列表中的每个项目分别执行：
-1. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`，获取模块列表和路径
-2. 检查 \`.sillyspec/docs/<project>/modules/\` 下已有的模块文档（<module>.md）
+1. 读取 \`{DOCS_ROOT}/modules/_module-map.yaml\`，获取模块列表和路径
+2. 检查 \`{DOCS_ROOT}/modules/\` 下已有的模块文档（<module>.md）
 3. 列出每个模块的状态：已有文档 / 缺失
 4. **必须停下来问用户**：
    - 展示模块列表及现有文档状态
@@ -323,7 +323,7 @@ _module-map.yaml 生成结果（已存在/已生成/模块列表）`,
 \`\`\`
 模块名：<module-id>
 模块路径：<glob patterns>
-目标文件：.sillyspec/docs/<project>/modules/<module-id>.md
+目标文件：{DOCS_ROOT}/modules/<module-id>.md
 
 操作：
 1. 用 grep/rg 搜索模块路径范围内的源码（禁止读源码全文）
@@ -380,7 +380,7 @@ module_id: <module-id>
 ⚠️ 这一步是可选的。如果项目模块简单、流程不明显，可以跳过。
 
 ### flows/ 目录
-目标目录：\`.sillyspec/docs/<project>/flows/\`
+目标目录：\`{DOCS_ROOT}/flows/\`
 
 根据 _module-map.yaml 中的模块依赖关系，识别跨模块业务流程：
 1. 读取 \`_module-map.yaml\`，分析 used_by 链条
@@ -410,7 +410,7 @@ step1 → step2 → step3
 \`\`\`
 
 ### glossary.md
-目标文件：\`.sillyspec/docs/<project>/glossary.md\`
+目标文件：\`{DOCS_ROOT}/glossary.md\`
 
 提取项目专有术语：
 1. 用 grep 搜索 TODO/FIXME 注释中的术语定义
@@ -446,11 +446,11 @@ step1 → step2 → step3
 
 ### 操作
 对扫描列表中的每个项目分别执行：
-1. 检查 7 份 scan 文档是否全部生成（\`.sillyspec/docs/<project>/scan/\`）
-2. 检查模块文档状态（\`.sillyspec/docs/<project>/modules/\`）
+1. 检查 7 份 scan 文档是否全部生成（\`{DOCS_ROOT}/scan/\`）
+2. 检查模块文档状态（\`{DOCS_ROOT}/modules/\`）
 3. 自检门控：ARCHITECTURE（技术栈+Schema摘要）、CONVENTIONS（隐形规则+代码风格）、STRUCTURE（目录结构）、INTEGRATIONS（外部依赖）、TESTING（测试现状）、CONCERNS（技术债务）、PROJECT（项目概览）
 4. 检查 flows/ 和 glossary.md 是否已生成（如有）
-5. 清理：\`rm -f .sillyspec/docs/<project>/scan/_env-detect.md\`
+5. 清理：\`rm -f {DOCS_ROOT}/scan/_env-detect.md\`
 6. \`git add .sillyspec/\` — 暂存扫描结果（不要 commit，由用户通过统一提交工具处理）
 
 ### 输出