sillyspec 3.24.7 → 3.25.0

package/src/stages/doctor.js

@@ -77,19 +77,19 @@ subs.forEach(s => {
 
 ### 5. 配置文件检查
 \`\`\`bash
-# 检查 local.yaml 和 STACK.md
+# 检查 local.yaml 和 scan 总览文档
 for f in .sillyspec/projects/*.yaml; do
   [ -f "$f" ] || continue
   name=$(grep '^name:' "$f" | head -1 | sed 's/^name:[[:space:]]*//')
   p=$(grep '^path:' "$f" | head -1 | sed 's/^path:[[:space:]]*//')
   [ -z "$p" ] && continue
   local_yaml="$p/.sillyspec/local.yaml"
-  stack_md="$p/.sillyspec/STACK.md"
+  arch_md=".sillyspec/docs/$name/scan/ARCHITECTURE.md"
   [ -f "$local_yaml" ] && echo "✅ local.yaml ($name)" || echo "⚠️ local.yaml ($name) — 不存在"
   if [ -f "$local_yaml" ]; then
     grep -q 'test:' "$local_yaml" && echo "  ✅ test 命令已配置" || echo "  ⚠️ 缺少 test 命令"
   fi
-  [ -f "$stack_md" ] && echo "✅ STACK.md ($name)" || echo "⚠️ STACK.md ($name) — 不存在"
+  [ -f "$arch_md" ] && echo "✅ scan/ARCHITECTURE.md ($name)" || echo "⚠️ scan/ARCHITECTURE.md ($name) — 不存在（运行 sillyspec run scan）"
 done
 \`\`\`
 
@@ -167,7 +167,7 @@ echo "项目目录: $PROJECT_DIR"
 for f in pom.xml build.gradle package.json requirements.txt pyproject.toml go.mod Cargo.toml; do
   [ -f "$PROJECT_DIR/$f" ] && echo "检测到: $f"
 done
-[ -f "$PROJECT_DIR/.sillyspec/STACK.md" ] && cat "$PROJECT_DIR/.sillyspec/STACK.md" | head -30
+cat .sillyspec/docs/*/scan/ARCHITECTURE.md 2>/dev/null | head -30 || echo "（无 scan/ARCHITECTURE.md）"
 \`\`\`
 
 ### 2. 构建工具可用性
@@ -349,7 +349,7 @@ timeout 5 which docker 2>/dev/null && echo "✅ Docker 可用" || echo "ℹ️ D
 - CLI 未安装 → \`npm install -g sillyspec\`
 - 缺少 local.yaml → \`sillyspec init\` 重新生成，或手动创建
 - local.yaml 缺少 test 命令 → 补充对应命令
-- 缺少 STACK.md → \`sillyspec run scan\` 重新扫描
+- 缺少 scan 文档（ARCHITECTURE.md 等）→ \`sillyspec run scan\` 重新扫描
 - sillyspec.db 状态不一致 → \`sillyspec run <阶段> --reset\` 重置对应阶段
 - 孤儿目录 → 确认后 \`rm -rf .sillyspec/changes/<目录名>\`
 - Maven 私服不可达 → 检查 VPN、settings.xml 配置、私服状态

package/src/stages/execute.js

@@ -115,7 +115,7 @@ const fixedPrefix = [
 2. 读取 design.md（技术方案）
 3. 读取 CONVENTIONS.md、ARCHITECTURE.md
 4. 读取 local.yaml（构建命令）
-5. 加载 CODEBASE-OVERVIEW.md
+5. 加载项目总览 \`.sillyspec/docs/<project>/scan/PROJECT.md\`（如存在）
 
 ### 模块文档加载
 6. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）

package/src/stages/index.js

@@ -26,4 +26,4 @@ export const stageRegistry = {
 }
 
 // 辅助命令（在无活跃变更时也可执行）
-export const auxiliaryStages = ['scan', 'quick', 'explore', 'archive', 'status', 'doctor']
+export { AUXILIARY_STAGES as auxiliaryStages } from '../constants.js'

package/src/stages/plan.js

@@ -87,12 +87,12 @@ const stepClassify = {
 
 ### 操作
 1. 运行 \`sillyspec progress show\`，确认 currentStage 为 "plan"
-2. 读取 CODEBASE-OVERVIEW.md + 各子项目上下文
+2. 读取项目总览 \`{SPEC_ROOT}/docs/<project>/scan/PROJECT.md\` + 各子项目上下文
 3. 读取 proposal.md、design.md、requirements.md、tasks.md
 4. 如果存在 decisions.md，必须读取并提取所有当前版本 D-xxx@vN 决策 ID
    - 如果发现 priority=P0/P1 且 status=unresolved/blocking 的决策，停止生成计划，要求先回到 brainstorm 的 Design Grill 修正
    - 如果发现 superseded 决策，只引用最新版本，不引用旧版本
-5. 读取 CONVENTIONS.md、ARCHITECTURE.md、STACK.md
+5. 读取 CONVENTIONS.md、ARCHITECTURE.md（技术栈含在 ARCHITECTURE.md）
 6. 读取 local.yaml 获取构建/测试命令
 7. 读取 \`{SPEC_ROOT}/docs/<project>/modules/_module-map.yaml\`（不存在则跳过）
    - 根据 design.md 的文件变更清单匹配模块

package/src/stages/propose.js

@@ -27,7 +27,7 @@ export const definition = {
       prompt: `加载所有相关规范和代码库上下文。
 
 ### 操作
-1. 加载 CODEBASE-OVERVIEW.md 和子项目上下文
+1. 加载项目总览 \`.sillyspec/docs/<project>/scan/PROJECT.md\`（如存在）和子项目上下文
 2. 读取最新设计文档、需求文档、代码库约定
 3. 如果是子阶段变更，读取 MASTER.md 和前序阶段设计
 

package/src/stages/status.js

@@ -9,7 +9,7 @@ export const definition = {
       prompt: `收集项目基础信息。
 
 ### 操作
-1. \`cat .sillyspec/PROJECT.md 2>/dev/null || echo "未初始化"\`
+1. \`cat .sillyspec/docs/*/scan/PROJECT.md 2>/dev/null | head -20 || echo "未初始化"\`
 2. 获取 project 名
 3. \`ls .sillyspec/docs/<project>/scan/ 2>/dev/null | head -10\`
 4. \`cat .sillyspec/REQUIREMENTS.md 2>/dev/null | head -20\`

package/src/stages/verify.js

@@ -60,6 +60,8 @@ export const definition = {
 3. 加载项目信息：\`cat .sillyspec/projects/*.yaml 2>/dev/null\`
 4. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`（构建命令、测试命令、lint 命令等）
 5. 加载代码规范：\`cat .sillyspec/docs/<project>/scan/CONVENTIONS.md 2>/dev/null\`
+   - 测试现状：\`cat .sillyspec/docs/<project>/scan/TESTING.md 2>/dev/null\`（了解既有测试约定与覆盖范围，验收时对照）
+   - 技术债清单：\`cat .sillyspec/docs/<project>/scan/CONCERNS.md 2>/dev/null\`（🔴/🟡 区域；本次变更若触碰须在 verify-result.md 标注）
 6. 标注每个文件的存在/不存在状态
 
 ### Execute Evidence 传递检查

package/src/verify-postcheck.js

@@ -18,6 +18,7 @@
 import { execSync } from 'child_process'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
+import { verifyApiParity } from './contract-matrix.js'
 
 // 测试命令最长执行时间；超时视为失败（防止 CLI 被挂起的测试卡死）
 const TEST_TIMEOUT_MS = Number(process.env.SILLYSPEC_TEST_TIMEOUT_MS) || 10 * 60 * 1000
@@ -504,3 +505,43 @@ export function printVerifyTestCheck(result) {
     console.log(`📄 实测结果已写入: ${result.resultPath}`)
   }
 }
+
+/**
+ * API parity 对账（advisory）：前端调用 vs execute 提取的后端 endpoint artifact。
+ * 三态：skipped（无 provider artifact → 非全栈项目不打扰）/ warning（missingBackend>0）/ passed。
+ * 启发式正则、多假阳源 → advisory 不阻断 verify 完成（与 SillySpec 确定性校验定位一致）。
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd - 扫描前端调用的根（主工作区，verify 时代码在此）
+ * @param {string} opts.specBase
+ * @param {string|null} [opts.changeName]
+ * @param {string|null} [opts.runtimeRoot]
+ * @returns {{ status: 'skipped'|'warning'|'passed', missingBackend: Array, unusedBackend: Array, summary: string, reason: string|null }}
+ */
+export function runVerifyParityCheck({ cwd, specBase, changeName = null, runtimeRoot = null }) {
+  const r = verifyApiParity(specBase, cwd, runtimeRoot, changeName)
+  // 无 provider artifact（execute 未提取 / 非后端项目）→ 不打扰
+  if (r.backendCount === 0) {
+    return { status: 'skipped', missingBackend: [], unusedBackend: [], summary: r.summary, reason: '无后端契约 artifact（非全栈项目或 execute 未提取端点）' }
+  }
+  if (r.missingBackend.length > 0) {
+    return { status: 'warning', missingBackend: r.missingBackend, unusedBackend: r.unusedBackend, summary: r.summary, reason: null }
+  }
+  return { status: 'passed', missingBackend: [], unusedBackend: r.unusedBackend, summary: r.summary, reason: null }
+}
+
+/** 打印 parity 对账结果（advisory，不阻断） */
+export function printVerifyParityCheck(result) {
+  if (result.status === 'skipped') return  // 静默，不打扰非全栈项目
+  if (result.status === 'passed') {
+    console.log(`\n✅ API parity 对账通过：${result.summary}`)
+    return
+  }
+  // warning
+  console.warn(`\n⚠️  API parity 对账发现 ${result.missingBackend.length} 个前端调用无对应后端端点（advisory，不阻断归档）：`)
+  for (const m of result.missingBackend.slice(0, 20)) {
+    console.warn(`   - ${m.method} ${m.path}  ← ${m.consumerFile}:${m.consumerLine}`)
+  }
+  if (result.missingBackend.length > 20) console.warn(`   …还有 ${result.missingBackend.length - 20} 个`)
+  console.warn('   提示：检查是否后端漏实现，或前端调用了尚未实现的端点。确认无误可在 design.md 标注豁免。')
+}

package/src/worktree-apply.js

@@ -49,14 +49,34 @@ export function filterDeliverableFiles(files) {
 }
 
 /**
- * 获取文件在 git 中的 blob hash（基于某个 commit/tree）
- * @param {string} cwd - git 工作区路径
- * @param {string} treeish - commit hash、分支等
- * @param {string} filePath - 相对路径
- * @returns {string|null} blob hash，文件不存在返回 null
+ * 批量获取多个文件在某个 treeish 中的 blob hash（一次 git ls-tree 替代 N 次 rev-parse）。
+ *
+ * 语义等价于对每个文件调 `git rev-parse <treeish>:<path>`：
+ *   - 文件在 tree 中 → Map<f, hash>（与 rev-parse 返回的同一 blob hash）
+ *   - 文件不在 tree 中 → 不在 Map 中（调用方 map.get(f) ?? null 得 null，等同 rev-parse 失败→null）
+ * ls-tree 输出 "<mode> <type> <hash>\t<path>"。path 恒为文件路径（来自 git diff/ls-files），
+ * 非目录，故不带 -r 也正确——文件在 tree 时 rev-parse treeish:path 与 ls-tree 都给同一 hash，
+ * 不在时都不给，等价。（沿用 git() 字符串拼接模式，不引入新的引号/空格破法。）
+ *
+ * @param {string} cwd
+ * @param {string} treeish
+ * @param {string[]} files
+ * @returns {Map<string, string>} path → blob hash（仅含存在于 tree 中的文件）
  */
-function getFileBlobHash(cwd, treeish, filePath) {
-  return gitQuiet(cwd, `rev-parse ${treeish}:${filePath}`);
+function getBlobHashMap(cwd, treeish, files) {
+  const map = new Map();
+  if (files.length === 0) return map; // 空 pathspec 会让 ls-tree 列出整棵树，必须拦截
+  const raw = gitQuiet(cwd, `ls-tree ${treeish} -- ${files.join(' ')}`);
+  if (!raw) return map;
+  for (const line of raw.split('\n')) {
+    if (!line) continue;
+    const tabIdx = line.indexOf('\t');
+    if (tabIdx === -1) continue;
+    const filePath = line.slice(tabIdx + 1);
+    const hash = line.slice(0, tabIdx).split(' ')[2]; // "<mode> <type> <hash>"
+    if (hash) map.set(filePath, hash);
+  }
+  return map;
 }
 
 /**
@@ -203,10 +223,14 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
   }
 
   // 5b. 对比 worktree 的 baseHash 和主工作区 HEAD 中每个清单文件的 blob hash
+  // 批量化：两次 ls-tree（worktree 的 baseHash + 主仓库 HEAD）各建一张 path→hash Map，
+  // 替代 per-file getFileBlobHash × 2（原 2N spawn → 固定 2）。语义等价见 getBlobHashMap。
   const targetFiles = hasAllowList ? [...allowSet] : changedFiles;
+  const wtHashMap = getBlobHashMap(worktreePath, baseHash, targetFiles);
+  const mainHashMap = getBlobHashMap(projectRoot, 'HEAD', targetFiles);
   for (const f of targetFiles) {
-    const wtBlob = getFileBlobHash(worktreePath, baseHash, f);
-    const mainBlob = getFileBlobHash(projectRoot, 'HEAD', f);
+    const wtBlob = wtHashMap.get(f) ?? null;
+    const mainBlob = mainHashMap.get(f) ?? null;
 
     // 两者都为 null（文件在 base 时不存在）→ OK
     if (wtBlob === null && mainBlob === null) continue;
@@ -234,7 +258,6 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
   const patchFiles = hasAllowList
     ? [...allowSet].filter(f => changedFiles.includes(f))
     : changedFiles;
-  const fileArgs = patchFiles.length > 0 ? `-- ${patchFiles.join(' ')}` : '';
 
   // 创建临时文件
   const tmpDir = mkdtempSync(join(tmpdir(), 'sillyspec-patch-'));
@@ -245,14 +268,18 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     let patchContent = '';
 
     // 分 tracked 变更和 untracked 新文件生成 patch
-    const trackedFiles = patchFiles.filter(f => {
-      // 文件在 diffBase 的 tree 中存在 → tracked（包括 rename 目标可能的情况）
-      if (gitQuiet(worktreePath, `cat-file -e ${diffBase}:${f}`) !== null) return true;
-      // 文件在工作区 index 中已存在（比如被 git mv 处理过）→ 也视为 tracked
-      if (gitQuiet(worktreePath, `ls-files --error-unmatch ${f}`) !== null) return true;
-      return false;
-    });
-    const untrackedPatchFiles = patchFiles.filter(f => !trackedFiles.includes(f));
+    // 批量化：一次 ls-tree（diffBase tree 中存在的文件）+ 一次 ls-files（index 中存在的文件）
+    // 建集合，替代 per-file cat-file -e / ls-files --error-unmatch（原至多 2N spawn → 固定 2）。
+    // 语义等价：cat-file -e diffBase:f 成功 ⟺ f 在 ls-tree diffBase 输出（getBlobHashMap key）；
+    // ls-files --error-unmatch f 成功 ⟺ f 在 ls-files -- 输出。
+    const inTree = getBlobHashMap(worktreePath, diffBase, patchFiles);
+    const inIndexList = patchFiles.length > 0
+      ? (gitQuiet(worktreePath, `ls-files -- ${patchFiles.join(' ')}`) || '').split('\n').filter(Boolean)
+      : [];
+    const inIndex = new Set(inIndexList);
+    const trackedFiles = patchFiles.filter(f => inTree.has(f) || inIndex.has(f));
+    const trackedSet = new Set(trackedFiles);
+    const untrackedPatchFiles = patchFiles.filter(f => !trackedSet.has(f));
 
     // tracked 文件：git diff baseHash
     if (trackedFiles.length > 0) {

package/src/worktree.js

@@ -18,6 +18,11 @@ const WORKTREES_REL = '.sillyspec/.runtime/worktrees';
 const BRANCH_PREFIX = 'sillyspec/';
 const META_FILE = 'meta.json';
 
+// 进程级缓存：cwd → 主仓库根目录。避免每次 new WorktreeManager 都 spawn 一次
+// `git rev-parse --git-common-dir`（Windows 上每次 spawn 约 30-100ms，execute 一次命令
+// 会 new 多个 WorktreeManager）。git-common-dir 在进程内对同一 cwd 稳定，缓存安全。
+const _mainRepoRootByCwd = new Map();
+
 /**
  * 检测当前目录的隔离状态
  * 返回 { inWorktree: boolean, inSubmodule: boolean }
@@ -224,24 +229,27 @@ export class WorktreeManager {
    * @private
    */
   _resolveMainRepoRoot() {
+    const cached = _mainRepoRootByCwd.get(this.cwd);
+    if (cached !== undefined) return cached;
+
+    let root = this.cwd;
     try {
       // git-common-dir 在主仓库内 = <main>/.git
       // 在 linked worktree 内 = <main>/.git（git 共享 .git 目录）
       const commonDir = gitQuiet(this.cwd, 'rev-parse --git-common-dir');
-      if (!commonDir) return this.cwd;
-
       // commonDir 应该是 <main-repo>/.git
       // dirname(commonDir) = <main-repo>
-      if (existsSync(commonDir)) {
+      if (commonDir && existsSync(commonDir)) {
         const st = statSync(commonDir);
         if (st.isDirectory()) {
-          return dirname(commonDir);
+          root = dirname(commonDir);
         }
       }
     } catch (e) {
       // 静默 fallback：主仓库内执行或 git 异常
     }
-    return this.cwd;
+    _mainRepoRootByCwd.set(this.cwd, root);
+    return root;
   }
 
   /**