sillyspec 3.28.7 → 3.28.9

package/src/wt-commit.js

@@ -0,0 +1,128 @@
+/**
+ * sillyspec wt-commit —— worktree 内 per-task 串行化提交（提交队列）
+ *
+ * 坑 wt-parallel-commit-race（2026-08-29 用户实证×2）：同 Wave 多个 task 子代理共享同一个
+ * 主仓 worktree，各自裸跑 git add/commit 有两条竞态：① `git add -A` 把并行兄弟的 WIP 文件卷进
+ * 自己的提交；② 并发写 index 撞 index.lock。两次都靠子代理自觉救回，属结构性风险——本命令把
+ * 「自觉」换成「机制」：
+ *
+ * ① 文件锁串行化：withFileLock 排他锁 <mainRepo>/.sillyspec/.runtime/wt-commit-<change>.lock，
+ *    同 change 的 wt-commit 全局排队（per-task 提交队列效果），锁内 add→commit 原子完成；
+ * ② 强制显式 pathspec：-- 后逐路径（或 --pathspec-from-file）——命令语义上杜绝 add -A 扫入
+ *    他人 WIP；commit 带同一 pathspec（--only 语义），不动其他并行者已暂存的内容。
+ *
+ * 边界：锁只约束 wt-commit 调用方；兄弟子代理若仍裸跑 git，靠 ② 的 pathspec 隔离兜底 + git 侧
+ * index.lock 冲突时退避重试。跨仓 task 不走本命令（跨仓有独立 workdir / 直写主干，execute 指引
+ * 要求显式 pathspec 提交）。锁文件在 .runtime（运行时目录，不入 git 历史）。
+ *
+ * 成功返回 HEAD hash（review.json 的 head 锚点直接可用）；无变更 → ok=true + skipped。
+ */
+import { join, resolve } from 'node:path'
+import { existsSync, readFileSync } from 'node:fs'
+import { withFileLock } from './quicklog.js'
+import { safeGit } from './git-helper.js'
+import { WorktreeManager } from './worktree.js'
+
+const sleep = (ms) => new Promise(r => setTimeout(r, ms))
+
+/**
+ * git 子操作退避重试：撞 index.lock / HEAD 锁（锁队列外裸跑 git 的兄弟进程短暂持锁）时等待重试。
+ * 非 lock 类错误（路径不存在 / pathspec 不匹配 / 权限）直接抛，不空转。
+ */
+async function gitWithLockRetry(cwd, args, label, { retries = 6, waitMs = 1000 } = {}) {
+  for (let i = 0; ; i++) {
+    const { value, error } = safeGit(cwd, args, { timeout: 30000 })
+    if (!error) return value
+    const msg = String((error && error.message) || error)
+    if (/index\.lock|HEAD\.lock|cannot lock ref/i.test(msg) && i < retries) {
+      await sleep(waitMs)
+      continue
+    }
+    throw new Error(`${label} 失败：${msg.split('\n')[0].trim()}`)
+  }
+}
+
+/**
+ * 执行 worktree 串行化提交。
+ *
+ * @param {object} opts
+ * @param {string} opts.changeName - 变更名（worktree 名）
+ * @param {string} opts.message - 提交信息（建议 "<task-NN 摘要>"）
+ * @param {string[]} opts.pathspecs - 显式路径列表（必填，防 add -A 扫入并行兄弟 WIP）
+ * @param {string|null} [opts.pathspecFile] - --pathspec-from-file：每行一个路径（与 pathspecs 二选一或叠加）
+ * @param {string} [opts.cwd] - 调用方 cwd（主仓根或 worktree 内均可——WorktreeManager 经
+ *   git-common-dir 反推主仓根，worktree 内调用同样定位正确）
+ * @returns {Promise<{ok:boolean,skipped:boolean,head:string,shortHead:string,worktreePath:string,changeName:string,files:string[]}>}
+ *   ok=false 时抛错（调用方打错误 + exit 1），skipped=无变更可提交（HEAD 不动，不算失败）。
+ */
+export async function runWtCommit({ changeName, message, pathspecs = [], pathspecFile = null, cwd = process.cwd() }) {
+  if (!changeName) throw new Error('缺少 --change <变更名>（worktree 名；在 worktree 内运行时可省略，CLI 从 cwd 推断）')
+  if (!message || !message.trim()) throw new Error('缺少 -m/--message <提交信息>（建议 "<task-NN 摘要>"）')
+
+  // pathspec 汇总：显式路径 + 文件逐行（# 注释与空行忽略，与 git pathspec-from-file 习惯一致）
+  const files = [...pathspecs.map(p => p.trim()).filter(Boolean)]
+  if (pathspecFile) {
+    if (!existsSync(pathspecFile)) throw new Error(`--pathspec-from-file 文件不存在: ${pathspecFile}`)
+    for (const line of readFileSync(pathspecFile, 'utf8').split(/\r?\n/)) {
+      const t = line.trim()
+      if (t && !t.startsWith('#')) files.push(t)
+    }
+  }
+  if (files.length === 0) {
+    throw new Error('缺少提交路径：`--` 后逐个给出本 task 的精确路径（或 --pathspec-from-file <file>）。wt-commit 刻意不支持 add -A / 空 pathspec——同 Wave 兄弟子代理共享本 worktree，整树 add 会把对方 WIP 卷进你的提交')
+  }
+
+  const wm = new WorktreeManager({ cwd })
+  const worktreePath = wm.getWorktreePath(changeName)
+  // 隔离模式（worktree 目录存在）→ 提交目标 = worktree 本体；in-place-fallback（meta 声明无
+  // worktree 直改主仓）→ 主仓根（与 MultiRepoContext 主仓 entry 的 worktreePath 兜底口径一致）。
+  // 顺序先看目录再看 meta：worktree 目录存在即隔离态，meta 缺失/损坏不改变目标（fail-safe）。
+  let target = null
+  if (existsSync(worktreePath)) {
+    target = worktreePath
+  } else {
+    const meta = wm.getMeta(changeName)
+    if (meta && meta.mode === 'in-place-fallback') {
+      target = resolve(wm.worktreeBase, '..', '..', '..') // <main>/.sillyspec/.runtime/worktrees → <main>
+    }
+  }
+  if (!target) {
+    throw new Error(`worktree 不存在: ${worktreePath}（确认 --change 变更名；execute 尚未创建 worktree 时先跑 sillyspec run execute）`)
+  }
+
+  // 锁：主仓 .sillyspec/.runtime/ 下按 change 一把（in-place 模式同目录可达，零分叉）
+  const lockPath = join(wm.worktreeBase, '..', `wt-commit-${changeName}.lock`)
+  const envTimeout = parseInt(process.env.SILLYSPEC_WT_COMMIT_LOCK_TIMEOUT_MS || '', 10)
+  const lockTimeoutMs = Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : 120000
+
+  const result = await withFileLock(lockPath, async () => {
+    const headBefore = safeGit(target, ['rev-parse', 'HEAD'], { timeout: 10000 }).value || ''
+    await gitWithLockRetry(target, ['add', '--', ...files], 'git add')
+    // pathspec 范围内是否有 staged 变更（vs HEAD）：空 = 无可提交（task 幂等重跑场景），
+    // 跳过 commit 保持 skipped 语义——不靠解析 git commit 的 "nothing to commit" stdout
+    // （safeGit 的 error 只保留命令首行，stdout 不可得）。
+    const staged = safeGit(target, ['diff', '--cached', '--name-only', '--', ...files], { timeout: 10000 }).value || ''
+    if (!staged.trim()) {
+      return { ok: true, skipped: true, head: headBefore }
+    }
+    await gitWithLockRetry(target, ['commit', '-m', message, '--', ...files], 'git commit')
+    const head = safeGit(target, ['rev-parse', 'HEAD'], { timeout: 10000 }).value || headBefore
+    return { ok: true, skipped: false, head }
+  }, {
+    // 持有者语义：超时报错时能看出是谁卡着队列
+    content: JSON.stringify({ pid: process.pid, changeName, purpose: 'wt-commit' }),
+    staleMs: 120000, // 持锁进程崩溃残留的回收阈值（commit 通常秒级）
+    timeoutMs: lockTimeoutMs, // 排队上限：同 Wave 并行 task 全走队列，给足余量
+    retryMs: 200,
+  })
+
+  return {
+    ok: true,
+    skipped: !!result.skipped,
+    head: result.head,
+    shortHead: (result.head || '').slice(0, 8),
+    worktreePath: target,
+    changeName,
+    files,
+  }
+}

package/templates/agents-instruction.md

@@ -7,9 +7,9 @@
 1. **禁止绕过本文件规则和 SillySpec 流程**。所有变更走 sillyspec 流程，不裸改裸提交。
 2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md）或现有代码依据，无依据不改。
 3. **新功能 / 大改动走完整流程**：`brainstorm → plan → execute → verify → archive`。
-4. **小修复 / 小调整走 quick**：`sillyspec run quick`。
+4. **小修复 / 小调整走 quick**（= 无需要落盘的设计决策的改动，选道判据见第 6 条）：`sillyspec run quick`。
 5. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档。
-6. **判规模选档**：≤3 文件、范围明确走 `quick`；多阶段 / 架构级走完整流程。
+6. **判规模选档**：看本次改动有无需要落盘的设计决策——有（新能力 / 行为契约变更 / 跨模块取舍 / 多阶段推进）走完整流程，无（范围明确的局部修补）走 `quick`。文件数不是选道判据，只作出口绊线——改动大或跨模块时 quick 收尾门禁会自动加查（分级提示补文件注记 / 测试增量 / 模块文档认领）。
 7. **代码先行不补流程（倒推 B 模式）**：代码若已先写好，**不回头补 brainstorm/plan 装样子**——用 `quick --done` 收尾 + 补 quicklog 条目，把已落盘改动如实登记进进度库。
 8. **实证核验再 `--done`**：触及 `src`/`test` 的改动，CLI 会在 `quick --done` 时**亲自实测** `.sillyspec/local.yaml` 的 `commands.test` / `commands.lint`（门禁：实测失败阻断 --done 回 pending；纯 doc/配置与未配置命令自动跳过；倒推 B 模式按 --files 声明边界兜底判定）。agent 侧预跑**可选**——想省「--done 被拦→修复→重跑」一轮时才预跑；纯 doc/配置改动无需跑。以落盘文件与测试结果为准，不信口头"已完成"。
 9. **中途停下不靠额外命令存进度**——进度已由上一次 `--done` 自动落盘；恢复时用 `sillyspec progress show` 查看进度，再用 `sillyspec run <stage>` 续跑，不直接 commit 半成品。

package/templates/prompts/testcase-design.md

@@ -9,4 +9,5 @@
 3. **行为 vs 实现**：走公开 API 测行为；重构后功能不变，测试不应失败。
 4. **契约与回归**：覆盖本次改动会破坏的既有行为与相邻模块接口；改公共签名/文案/常量时同步修复受影响既有测试并跑全量，禁止删断言凑绿。
 5. **时间敏感分支**：超时/重试/并发分支别真等——超时参数做成可注入，测试传毫秒级极小值或注入可控时钟推进，再断言超时后的行为（走哪个分支/返回什么/资源是否回收）。
-6. **隔离确定性**：独立 fixture、可重复跑，不依赖共享状态/执行顺序。
+6. **隔离确定性**：独立 fixture、可重复跑，不依赖共享状态/执行顺序。
+7. **覆盖对账**：每条 TaskCard acceptance 至少对应一个测试用例，或显式标注 non-testable（文档/部署类——证据列写一句理由）；对应关系由 verify 探针 7 矩阵机械核对（判定 covered/partial 须给测试锚点）——写测试前先读卡的 acceptance 列表逐条对齐，勿只覆盖顺手的主路径。

package/templates/prompts/verify-probes.md

@@ -3,7 +3,7 @@
 > 🔧 **先跑 CLI 机械探针（一条命令）**：`sillyspec verify-probes --change <change-name> [--init]`
 > 输出已包含四个纯机械探针的结果（可直接进验证报告）：**探针 1** 未实现标记扫描（design 清单文件逐行 TODO/FIXME 命中 + 行号）、**探针 3** 测试文件递归查找（含 co-located tests/，逐 task 覆盖）、**探针 5** API 契约对账表（endpoints.json × 前端调用 diff）、**探针 6** 删除对账三态（git 事实 × design 声明）。`--init` 顺带生成 verify-result.md 九章节骨架（探针结果已预填，`<!--TODO-->` 占位替换即可）。
 >
-> 下列条目中，只有**半语义部分**需要你执行：探针 2（关键词提取）、探针 3.4 集成盲区标注、探针 3.5 断言有效性抽查、探针 4（决策追踪闭环判定）。CLI 已跑的部分勿重复手跑——对 CLI 输出的 warning 项做语义复核即可。
+> 下列条目中，只有**半语义部分**需要你执行：探针 2（关键词提取）、探针 3.4 集成盲区标注、探针 3.5 断言有效性抽查、探针 4（决策追踪闭环判定）、探针 7（验收×测试覆盖矩阵判定填槽）。CLI 已跑的部分勿重复手跑——对 CLI 输出的 warning 项做语义复核即可。
 
 **探针 2：设计关键词覆盖探针（你执行——关键词提取是语义）**
 1. 读取 design.md，从中提取所有能力关键词（如"登录"、"导出"、"批量"、"删除"、"搜索"等动作词）
@@ -31,3 +31,6 @@ CLI 的 missing backend endpoint 是 advisory（不硬阻断归档）——但 c
 
 **探针 6 补充（CLI 已出三态判定，你做终审）**
 以 git 事实为准（真实 > 声明）；CLI 的三态（合规/高风险/未声明）是机械判定，是否构成 FAIL blocker 由你诚实判定，务必如实记录——静默删除代码是 verify 的最大盲区。
+
+**探针 7 补充（CLI 已预填矩阵归属与提示，你填判定与证据）**
+验收×测试覆盖矩阵：CLI 机械半边已预填——逐 task 解析 TaskCard acceptance（frontmatter）、双源结构归属测试文件（allowed_paths 测试模式 ∪ execute review changedFiles 中 test/ 路径）、关键词命中提示（命中≠判定，仅提示）。你逐行填判定槽四枚举（covered / partial / uncovered / non-testable——non-testable 是文档/部署类显式逃生门）与证据：covered/partial 附测试锚点（`.test.` 文件或 file:line），non-testable 附一句理由；判定或证据未填 fail-closed，阻断 verify `--done`。与探针 3 口径差异：探针 3 查模块目录有没有测试文件（存在性面），探针 7 查每条 acceptance 由哪些测试承接（承接面）；两者并排冲突以 7 为准。

package/sa-rename-probe/src/new.js

@@ -1,4 +0,0 @@
-a
-b
-c
-d