sillyspec 3.25.9 → 3.25.11

package/src/version.js

@@ -0,0 +1,19 @@
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * 读取 package.json 版本号。
+ * 独立轻量模块：只依赖 fs/path/url，不拖入 init.js 的 @inquirer/prompts 等重型交互库。
+ * 供 index.js 顶部静态 import——--version 等高频路径不再为 getVersion 付 init.js 加载税。
+ */
+export function getVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8'));
+    return pkg.version;
+  } catch {
+    return '?.?.?';
+  }
+}

package/src/worktree-apply.js

@@ -12,29 +12,17 @@
  * 8. 成功后自动 cleanup
  */
 
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { existsSync, unlinkSync, writeFileSync, mkdtempSync, rmSync, readdirSync, readFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { tmpdir } from 'os';
-import { createHash } from 'crypto';
 import { WorktreeManager } from './worktree.js';
 import { parseFileChangeList, parseFileChangeListDetailed, pathMatches } from './change-list.js';
 import { parseAllowedPaths } from './stages/plan-postcheck.js';
+import { git, gitQuiet } from './git-helper.js';
 
 const CHANGES_REL = '.sillyspec/changes';
 
-function git(cwd, args) {
-  return execSync(`git ${args}`, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-}
-
-function gitQuiet(cwd, args) {
-  try {
-    return execSync(`git ${args}`, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-  } catch {
-    return null;
-  }
-}
-
 /**
  * 过滤掉 worktree 基础设施文件（非交付物），让 apply 只关心真正的变更产出：
  *   - meta.json：worktree 元数据，baseline commit 中被跟踪、working-tree 被 CLI 改写
@@ -42,11 +30,19 @@ function gitQuiet(cwd, args) {
  *     的锚点，保证 baseline overlay 文件不被误判为变更）。若不排除，modified-tracked 的
  *     meta.json 会落入 changedFiles，触发「不在 design.md 清单」误判，导致每个 execute 的
  *     assess 恒 BLOCKED。
- *   - .sillyspec/：变更文档 / 运行时产物，不属于源码交付。
+ *   - .sillyspec/changes/：变更文档（worktree 专属，apply 回主仓污染进度库）。
+ *   - .sillyspec/.runtime/：运行时产物（进度库/锁/review 产物，非源码）。
+ *   - .sillyspec/quicklog/：quicklog 条目（worktree 进度，非交付物）。
+ *   保留 .sillyspec/docs/（dogfood 模块规范文档 = 交付物，apply 回主仓）。
  * 对 modified-tracked（git diff）与 untracked（ls-files --others）一视同仁。
  */
 export function filterDeliverableFiles(files) {
-  return files.filter(f => !f.startsWith('.sillyspec/') && f !== 'meta.json');
+  return files.filter(f =>
+    !f.startsWith('.sillyspec/changes/') &&
+    !f.startsWith('.sillyspec/.runtime/') &&
+    !f.startsWith('.sillyspec/quicklog/') &&
+    f !== 'meta.json'
+  );
 }
 
 /**
@@ -63,6 +59,23 @@ export function classifyAllowListViolations(changedFiles, allowSet) {
   return changedFiles.filter(f => !allow.some(ap => pathMatches(f, ap)));
 }
 
+/**
+ * 确定进 patch 的文件：有清单取「实际变更 ∩ 清单（pathMatches 容差）」，无清单取全部变更。
+ *
+ * 口径须与 classifyAllowListViolations 一致——否则 design §6 用 glob（如 test_*.py）或多路径
+ * 单 cell 覆盖的文件过 manifest 校验（Gate1 用 pathMatches 放行），却因字面 includes 不在
+ * changedFiles → 被滤出 patchFiles → patch 不含 → 主工作区静默丢失（坑 apply-glob-manifest）。
+ * 以 changedFiles 为基按容差圈定，glob/前缀覆盖的具体文件都能进 patch。
+ *
+ * @param {string[]} changedFiles  filterDeliverableFiles 已过滤的实际变更路径
+ * @param {Set<string>} allowSet   design §6 清单 ∪ task allowed_paths（可含 glob / 目录前缀）
+ * @param {boolean} hasAllowList   是否有清单
+ * @returns {string[]} 进 patch 的文件
+ */
+export function resolvePatchFiles(changedFiles, allowSet, hasAllowList) {
+  if (!hasAllowList) return changedFiles;
+  return changedFiles.filter(f => [...allowSet].some(ap => pathMatches(f, ap)));
+}
 /**
  * 批量获取多个文件在某个 treeish 中的 blob hash（一次 git ls-tree 替代 N 次 rev-parse）。
  *
@@ -71,7 +84,7 @@ export function classifyAllowListViolations(changedFiles, allowSet) {
  *   - 文件不在 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() 字符串拼接模式，不引入新的引号/空格破法。）
+ * 不在时都不给，等价。（沿用公共 git() 数组形式，不经 shell、不引入引号/空格破法。）
  *
  * @param {string} cwd
  * @param {string} treeish
@@ -81,7 +94,7 @@ export function classifyAllowListViolations(changedFiles, allowSet) {
 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(' ')}`);
+  const raw = gitQuiet(cwd, ['ls-tree', treeish, '--', ...files]);
   if (!raw) return map;
   for (const line of raw.split('\n')) {
     if (!line) continue;
@@ -107,7 +120,7 @@ function getBlobHashMap(cwd, treeish, files) {
  * @returns {Set<string>} 并集清单（无 design 清单且无 task 卡片时为空集）
  */
 export function resolveApplyAllowSet(projectRoot, changeName) {
-  const allowSet = parseFileChangeList(join(projectRoot, CHANGES_REL, changeName, 'design.md'));
+  const allowSet = parseFileChangeList(join(projectRoot, CHANGES_REL, changeName, 'design.md'), { keepSillyspecDocs: true });
   const tasksDir = join(projectRoot, CHANGES_REL, changeName, 'tasks');
   if (existsSync(tasksDir)) {
     for (const tf of readdirSync(tasksDir).filter(f => /^task-\d+\.md$/.test(f))) {
@@ -166,7 +179,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
   let changedFiles;
   try {
     // 用 --name-status 捕获 rename/delete（--name-only 会丢失 rename 源文件）
-    const statusRaw = git(worktreePath, `diff --name-status ${diffBase}`);
+    const statusRaw = git(worktreePath, ['diff', '--name-status', diffBase]);
     const statusFiles = new Set();
     if (statusRaw) {
       for (const line of statusRaw.split('\n').filter(Boolean)) {
@@ -178,7 +191,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     }
 
     // untracked 新文件（diffBase 中不存在的文件）
-    const untrackedRaw = gitQuiet(worktreePath, `ls-files --others --exclude-standard`);
+    const untrackedRaw = gitQuiet(worktreePath, ['ls-files', '--others', '--exclude-standard']);
     const untrackedFiles = untrackedRaw ? untrackedRaw.split('\n').filter(Boolean) : [];
 
     // 排除 worktree 基础设施文件（meta.json / .sillyspec/，见 filterDeliverableFiles）。
@@ -227,31 +240,33 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
   }
 
   // --- 4.5 校验：主工作区是否有「未提交」脏改动（未提交 dirty 是 git apply --3way 危险区，必须拦）---
-  // 分工：4.5（整树 baselineHash）+ 5a（脏∩changedFiles）挡「未提交」dirty；5b 管「已提交」HEAD 分叉（已放宽，见下）。
+  // 分工：4.5（排除规则下当前 dirty）+ 5a（脏∩changedFiles）挡「未提交」dirty；5b 管「已提交」HEAD 分叉（已放宽，见下）。
   // 实测：主干未提交 dirty 时，git apply --3way 报 `does not match index` 且行为不一致（可能报错/可能半应用，
   // 哪怕脏文件与 patch 不重叠）——这是 git 硬约束，故此处友好拦截，引导用户先 commit/stash。
   // 排除非交付物的元数据/文档 churn（execute 自身改的 + 多操作者常改的 agent 指引/文档），
-  // 否则别人改 CLAUDE.md/docs/.claude → 整树 hash 变 → apply 误阻断（多操作者仓库高频踩坑）。
-  // 注意：必须和 computeBaselineHash (worktree.js) 使用相同的排除规则。
+  // 否则别人改 CLAUDE.md/docs/.claude → 判定 dirty → apply 误阻断（多操作者仓库高频踩坑）。
+  // 注意：排除规则必须和 computeBaselineHash (worktree.js) 一致（虽已不比对 hash，仍用同一口径判当前 dirty）。
   if (meta.baselineHash) {
-    const exclude = '-- . ":(exclude).sillyspec/" ":(exclude).claude/" ":(exclude)docs/" ":(exclude)CLAUDE.md"';
-    const staged = gitQuiet(projectRoot, `diff --cached ${exclude}`) || '';
-    const unstaged = gitQuiet(projectRoot, `diff ${exclude}`) || '';
-    const untracked = gitQuiet(projectRoot, `ls-files --others --exclude-standard ${exclude}`) || '';
-    const raw = `staged:${staged}\nunstaged:${unstaged}\nuntracked:${untracked}`;
-    const currentHash = createHash('sha256').update(raw).digest('hex').slice(0, 16);
-    if (currentHash !== meta.baselineHash) {
+    // pathspec：`--` 结束选项，`.` 包含全部，后续 :(exclude) 排除非交付物元数据/文档 churn
+    // （与 computeBaselineHash 同口径）。数组形式逐元素传递，:(exclude) magic 字面直传不经 shell。
+    const exclude = ['--', '.', ':(exclude).sillyspec/', ':(exclude).claude/', ':(exclude)docs/', ':(exclude)CLAUDE.md'];
+    const staged = gitQuiet(projectRoot, ['diff', '--cached', ...exclude]) || '';
+    const unstaged = gitQuiet(projectRoot, ['diff', ...exclude]) || '';
+    const untracked = gitQuiet(projectRoot, ['ls-files', '--others', '--exclude-standard', ...exclude]) || '';
+    // 意图（与 computeBaselineHash 注释一致）：只挡「未提交 dirty」——git apply --3way 对 dirty 工作区不稳。
+    // 不比对 hash 是否等于 execute 启动时 baselineHash：主仓 dirty→clean（execute 期间 commit 无关文件）后
+    // hash 必变，若仍比对会永久死锁（须手改 meta.baselineHash）。改判「排除规则下当前是否有未提交 dirty」。
+    const hasUncommittedDirty = staged !== '' || unstaged !== '' || untracked !== '';
+    if (hasUncommittedDirty) {
       // 未提交 dirty 拦截：列脏文件 + 指引先 commit/stash（git --3way 对 dirty 工作区不稳，merge 同理，故不再提 --merge）
       const dirtyFiles = [...new Set(
-        ((gitQuiet(projectRoot, 'diff --name-only HEAD') || '').split('\n').filter(Boolean))
-          .concat((gitQuiet(projectRoot, 'ls-files --others --exclude-standard') || '').split('\n').filter(Boolean))
+        ((gitQuiet(projectRoot, ['diff', '--name-only', 'HEAD']) || '').split('\n').filter(Boolean))
+          .concat((gitQuiet(projectRoot, ['ls-files', '--others', '--exclude-standard']) || '').split('\n').filter(Boolean))
       )].filter(f => !f.startsWith('.sillyspec/') && f !== 'meta.json');
       result.errors.push(
-        `主工作区有未提交的改动（execute 前后 baseline 不一致），git apply 无法安全应用。\n` +
+        `主工作区有未提交的改动，git apply 无法安全应用。\n` +
         (dirtyFiles.length > 0 ? `未提交文件：\n  ${dirtyFiles.join('\n  ')}\n` : '') +
-        `请先提交或暂存这些改动，再重新 apply：\n  git add -A && git commit -m "..."   或   git stash\n` +
-        `execute 前 baseline: ${meta.baselineHash}\n` +
-        `当前 baseline: ${currentHash}`
+        `请先提交或暂存这些改动，再重新 apply：\n  git add -A && git commit -m "..."   或   git stash\n`
       );
       if (!checkOnly) return result; // checkOnly 收集不短路（一次报全）；真实 apply 短路
     }
@@ -259,7 +274,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
 
   // --- 5. 校验：主工作区文件 base hash 一致 ---
   // 5a. 检查主工作区是否有未 commit 的脏文件（会影响 apply）
-  const mainDirtyRaw = gitQuiet(projectRoot, 'diff --name-only HEAD');
+  const mainDirtyRaw = gitQuiet(projectRoot, ['diff', '--name-only', 'HEAD']);
   const mainDirtyFiles = mainDirtyRaw ? mainDirtyRaw.split('\n').filter(Boolean) : [];
   if (mainDirtyFiles.length > 0) {
     // 如果脏文件和本次 apply 的文件有交集 → 报错
@@ -301,10 +316,9 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
   }
 
   // --- 7. 生成 patch 并 apply ---
-  // 确定要包含在 patch 中的文件：有清单用清单交集，无清单用全部变更
-  const patchFiles = hasAllowList
-    ? [...allowSet].filter(f => changedFiles.includes(f))
-    : changedFiles;
+  // 确定要包含在 patch 中的文件：有清单用「实际变更 ∩ 清单（pathMatches 容差）」，无清单用全部变更。
+  // 口径与 classifyAllowListViolations 一致（坑 apply-glob-manifest-passes-check-but-not-patch）。
+  const patchFiles = resolvePatchFiles(changedFiles, allowSet, hasAllowList);
 
   // 创建临时文件
   const tmpDir = mkdtempSync(join(tmpdir(), 'sillyspec-patch-'));
@@ -321,35 +335,36 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     // 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)
+      ? (gitQuiet(worktreePath, ['ls-files', '--', ...patchFiles]) || '').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
+    // tracked 文件：git diff baseHash（数组形式，文件名逐个展开为独立 argv，不经 shell；
+    // trim:false 保留二进制补丁原样，timeout 放大到 60s 防大 diff 超时——原裸 execSync 无 timeout）
     if (trackedFiles.length > 0) {
-      const trackedArgs = trackedFiles.length > 0 ? `-- ${trackedFiles.join(' ')}` : '';
-      patchContent += execSync(
-        `git diff --binary ${diffBase} ${trackedArgs}`,
-        { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+      patchContent += git(
+        worktreePath,
+        ['diff', '--binary', diffBase, '--', ...trackedFiles],
+        { trim: false, timeout: 60000 }
       );
     }
 
-    // untracked 新文件：git add 到 index，git diff --cached，然后 reset
+    // untracked 新文件：git add 到 index，git diff --cached，然后 reset（均数组形式，文件名逐个展开）
     if (untrackedPatchFiles.length > 0) {
-      const addArgs = untrackedPatchFiles.length > 0 ? `-- ${untrackedPatchFiles.join(' ')}` : '';
-      git(worktreePath, `add ${addArgs}`);
+      git(worktreePath, ['add', '--', ...untrackedPatchFiles]);
       try {
-        const diffCachedArgs = untrackedPatchFiles.length > 0 ? `-- ${untrackedPatchFiles.join(' ')}` : '';
-        patchContent += execSync(
-          `git diff --binary --cached ${diffCachedArgs}`,
-          { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+        // trim:false 保留二进制补丁原样，timeout 放大到 60s 防大 diff 超时
+        patchContent += git(
+          worktreePath,
+          ['diff', '--binary', '--cached', '--', ...untrackedPatchFiles],
+          { trim: false, timeout: 60000 }
         );
       } finally {
         // 重置 index（不保留 staged 状态）
-        gitQuiet(worktreePath, `reset HEAD -- ${addArgs}`);
+        gitQuiet(worktreePath, ['reset', 'HEAD', '--', ...untrackedPatchFiles]);
       }
     }
 
@@ -370,13 +385,13 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
     // 但若 --3way 部分成功后冲突，已创建的新文件需删，故记录 untracked 集合。
     const trackedPatchFiles = patchFiles.filter(f => {
       // 该文件在主仓库 HEAD 存在 → 是 tracked（--3way 冲突时留标记需 checkout 还原）
-      return gitQuiet(projectRoot, `cat-file -e HEAD:${f}`) === null ? false : true;
+      return gitQuiet(projectRoot, ['cat-file', '-e', `HEAD:${f}`]) === null ? false : true;
     });
     const newPatchFiles = patchFiles.filter(f => !trackedPatchFiles.includes(f));
 
     // apply --3way 正式应用（主干已提交推进时自动三路合并）
     try {
-      git(projectRoot, `apply --3way ${patchPath}`);
+      git(projectRoot, ['apply', '--3way', patchPath], { timeout: 30000 });
     } catch (e) {
       // --3way 冲突（exit 1，工作区已留冲突标记）：回滚到 apply 前干净状态，不留半成品
       const rollback = rollbackApply(projectRoot, trackedPatchFiles, newPatchFiles);
@@ -427,13 +442,13 @@ function rollbackApply(projectRoot, trackedFiles, newFiles) {
   // 冲突文件：git status 里带冲突标记（UU/AA 等）的文件
   let conflicts = [];
   try {
-    const unmerged = gitQuiet(projectRoot, 'diff --name-only --diff-filter=U') || '';
+    const unmerged = gitQuiet(projectRoot, ['diff', '--name-only', '--diff-filter=U']) || '';
     conflicts = unmerged.split('\n').filter(Boolean);
   } catch {}
   // 回滚 tracked 文件到 HEAD（强制从 HEAD 还原——--3way 冲突标记同时污染工作区和 index，
   // `checkout -- f` 从 index 还原会拿到冲突版，必须 `checkout HEAD -- f` 才能还原干净）
   for (const f of trackedFiles) {
-    try { gitQuiet(projectRoot, `checkout HEAD -- ${f}`); } catch (e) { error = (error ? error + '; ' : '') + `checkout ${f}: ${e.message}`; }
+    try { gitQuiet(projectRoot, ['checkout', 'HEAD', '--', f]); } catch (e) { error = (error ? error + '; ' : '') + `checkout ${f}: ${e.message}`; }
   }
   // 删除 --3way 可能新建的文件（apply 前不存在）
   for (const f of newFiles) {
@@ -443,7 +458,7 @@ function rollbackApply(projectRoot, trackedFiles, newFiles) {
     } catch (e) { error = (error ? error + '; ' : '') + `delete ${f}: ${e.message}`; }
   }
   // 兜底：若 index 处于 unmerged 状态，重置 index（不影响工作区已还原的文件）
-  try { gitQuiet(projectRoot, 'reset --quiet'); } catch {}
+  try { gitQuiet(projectRoot, ['reset', '--quiet']); } catch {}
   return { conflicts, error };
 }
 
@@ -471,15 +486,15 @@ function applyByMerge(result, changeName, projectRoot, wm) {
   const branch = meta.branch || `sillyspec/${changeName}`;
 
   try {
-    git(projectRoot, `merge --no-ff ${branch}`);
+    git(projectRoot, ['merge', '--no-ff', branch], { timeout: 30000 });
   } catch (e) {
     // merge 冲突：取冲突文件列表 + abort 回滚（不 cleanup，保留 worktree）
     let conflictFiles = [];
     try {
-      const cf = gitQuiet(projectRoot, `diff --name-only --diff-filter=U`);
+      const cf = gitQuiet(projectRoot, ['diff', '--name-only', '--diff-filter=U']);
       conflictFiles = cf ? cf.split('\n').filter(Boolean) : [];
     } catch {}
-    try { gitQuiet(projectRoot, `merge --abort`); } catch {}
+    try { gitQuiet(projectRoot, ['merge', '--abort']); } catch {}
     result.errors.push(
       `git merge ${branch} 冲突，请手动解决。冲突文件：\n` +
       (conflictFiles.length ? `  ${conflictFiles.join('\n  ')}\n` : `  (未能获取冲突文件列表)\n`) +
@@ -492,7 +507,7 @@ function applyByMerge(result, changeName, projectRoot, wm) {
   // 分支可能只含 baseline checkpoint（子代理改动未 commit），merge 产生空内容合并，文件零落地。
   // 逐个确认 changedFiles 在 main HEAD 存在。任一缺失 → 不 cleanup（fail-open：保留 worktree 唯一副本）。
   result.merged = true;
-  const notLanded = changedFiles.filter(f => gitQuiet(projectRoot, `cat-file -e HEAD:${f}`) === null);
+  const notLanded = changedFiles.filter(f => gitQuiet(projectRoot, ['cat-file', '-e', `HEAD:${f}`]) === null);
   if (notLanded.length > 0) {
     result.ok = false;
     result.errors.push(
@@ -504,7 +519,7 @@ function applyByMerge(result, changeName, projectRoot, wm) {
   }
 
   result.ok = true;
-  try { result.mergeSummary = git(projectRoot, `log --oneline -1`); } catch {}
+  try { result.mergeSummary = git(projectRoot, ['log', '--oneline', '-1']); } catch {}
   try {
     wm.cleanup(changeName);
   } catch (cleanupErr) {
@@ -632,7 +647,7 @@ export function assessApplyRisk(changeName, { cwd } = {}) {
   let additions = 0, deletions = 0;
   if (wtPath && diffBase) {
     try {
-      const shortstat = gitQuiet(wtPath, `diff --shortstat ${diffBase}`);
+      const shortstat = gitQuiet(wtPath, ['diff', '--shortstat', diffBase]);
       const insMatch = shortstat?.match(/(\d+) insertion/);
       const delMatch = shortstat?.match(/(\d+) deletion/);
       additions = insMatch ? parseInt(insMatch[1]) : 0;
@@ -721,7 +736,9 @@ export function formatExecuteSummary({ changeName, stepsCompleted, stepsTotal, a
     // worktree 还在，用 baselineCommit 或 baseHash 做 diff
     try {
       const diffBase = meta.baselineCommit || meta.baseHash;
-      const filesRaw = execSync(`git -C ${meta.worktreePath} diff --name-only ${diffBase} 2>/dev/null`, { encoding: 'utf8' });
+      // execFileSync 数组形式：路径无需引号化（含空格也安全）；stdio stderr=ignore
+      // 替代 `2>/dev/null`（Windows cmd.exe 无法解析该重定向，导致 Windows 上恒抛错→Changed Files 空）
+      const filesRaw = execFileSync('git', ['-C', meta.worktreePath, 'diff', '--name-only', diffBase], { encoding: 'utf8', stdio: ['ignore','pipe','ignore'] });
       const files = filesRaw ? filesRaw.trim().split('\n').filter(Boolean) : [];
       if (files.length > 0) {
         lines.push(``);

package/src/worktree-deps.js

@@ -66,7 +66,7 @@ function extractUserInstall(yamlText) {
 }
 
 /** 从 local.yaml 提取 project.type；缺失时按文件特征推断 */
-function detectProjectType(worktreePath, specBase) {
+export function detectProjectType(worktreePath, specBase) {
   const yamlText = readLocalYaml(specBase, worktreePath);
   if (yamlText) {
     const m = yamlText.match(/type:\s*(\S+)/);
@@ -75,11 +75,14 @@ function detectProjectType(worktreePath, specBase) {
   if (existsSync(join(worktreePath, 'pom.xml'))) return 'maven';
   if (existsSync(join(worktreePath, 'build.gradle')) || existsSync(join(worktreePath, 'build.gradle.kts'))) return 'gradle';
   if (existsSync(join(worktreePath, 'package.json'))) return 'nodejs';
+  // Python：pyproject.toml（uv/poetry/pdm）或 requirements.txt（pip）——治 worktree 内 ruff/pre-commit 等
+  // 二进制不供给（exec 复盘 3-②：detectProjectType 原无 python 分支，python 项目根被误判 generic → n/a）
+  if (existsSync(join(worktreePath, 'pyproject.toml')) || existsSync(join(worktreePath, 'requirements.txt'))) return 'python';
   return 'generic';
 }
 
 /** 按 project.type + lockfile 推断 install 命令（无 commands.install 时）*/
-function inferInstallCommand(projectType, worktreePath, userInstall) {
+export function inferInstallCommand(projectType, worktreePath, userInstall) {
   if (userInstall) return userInstall;
   switch (projectType) {
     case 'nodejs':
@@ -91,6 +94,11 @@ function inferInstallCommand(projectType, worktreePath, userInstall) {
       return 'mvn -o test';
     case 'gradle':
       return './gradlew test';
+    case 'python':
+      // uv 优先（现代 Python 工具链，pyproject.toml/uv.lock 项目走 uv sync 建 .venv + 装依赖，
+      // 与 execute worktree 环境预告一致）；纯 requirements.txt（无 pyproject）回退 pip
+      if (existsSync(join(worktreePath, 'uv.lock')) || existsSync(join(worktreePath, 'pyproject.toml'))) return 'uv sync';
+      return 'pip install -r requirements.txt';
     default:
       return null; // generic → n/a
   }
@@ -190,11 +198,16 @@ function linkOneDir(wtDir, mainDir) {
  *
  * @param {string} worktreePath - worktree 根目录
  * @param {string} mainCwd - 主 checkout 根目录（node_modules 来源）
- * @param {{ specBase?: string, timeout?: number }} opts
+ * @param {{ specBase?: string, timeout?: number, force?: boolean }} opts
+ *   - force=true（doctor --fix 强制重装）：绕过根目录 lockfile 一致快路径（下方 line 216 区块），
+ *     强制走 install 分支重装。该快路径是 tryLink 的唯一根调用点，绕过它即同时绕过 tryLink
+ *     的 preexisting 幂等短路（101-110），实现"强制重装"语义。配合调用方先解 junction
+ *     （worktree.js _doctorReprovision），避免 install 经 junction 误改主仓 node_modules。
+ *     modules 子模块 link 不受 force 影响（仅根 install）。
  * @returns {{ depsStatus, depsMethod, depsSource, depsLockHash, depsCheckedAt, depsError?, depsModules? }}
  */
 export function provisionDeps(worktreePath, mainCwd, opts = {}) {
-  const { specBase = null, timeout = DEFAULT_TIMEOUT_MS } = opts;
+  const { specBase = null, timeout = DEFAULT_TIMEOUT_MS, force = false } = opts;
   const depsCheckedAt = new Date().toISOString();
   const yamlText = readLocalYaml(specBase, worktreePath);
   const wtHash = lockfileHash(worktreePath);
@@ -210,10 +223,11 @@ export function provisionDeps(worktreePath, mainCwd, opts = {}) {
     result = { depsStatus: 'n/a', depsMethod: null, depsSource: null, depsLockHash: wtHash };
   } else {
     // 快路径：main 有 node_modules 且 lockfile hash 一致 → junction/symlink
+    // force=true 时绕过（doctor --fix 强制重装；绕过此块即同时绕过 tryLink 101-110 幂等短路）
     const mainNodeModules = mainCwd ? join(mainCwd, 'node_modules') : null;
     const mainHash = lockfileHash(mainCwd);
     let linked = false;
-    if (mainNodeModules && existsSync(mainNodeModules) && mainHash && wtHash && mainHash === wtHash) {
+    if (!force && mainNodeModules && existsSync(mainNodeModules) && mainHash && wtHash && mainHash === wtHash) {
       const linkResult = tryLink(mainNodeModules, join(worktreePath, 'node_modules'));
       if (linkResult.ok) {
         result = {
@@ -265,3 +279,73 @@ export function provisionDeps(worktreePath, mainCwd, opts = {}) {
 
   return result;
 }
+
+/**
+ * 统一的 worktree deps 新鲜度判定（H1，change 2026-08-05-tooling-feedback-fixes）。
+ * 供 doctor（worktree.js）与 ensureDepsFreshness（run/stage.js）共用，消除两处双写漂移。
+ *
+ * 判定优先级：failed → missing → stale → main-drift → fresh
+ *   - failed: meta.depsStatus==='failed'（上次供给失败，占最高优先级）
+ *   - missing: depsStatus ∈ {linked, installed} 且 node_modules 不存在
+ *   - stale: wtHash 与 meta.depsLockHash 不一致（worktree 自身 lockfile 在上次供给后变化）
+ *   - main-drift: wtHash 与主仓 mainHash 不一致（主仓 lockfile 漂移；复用 linkOneDir 177-178 的 mismatch 判据）
+ *   - fresh: 其余情况
+ *
+ * lockfileHash 返回 null（无 lockfile/package.json）时相关比较优雅降级——不报 stale / main-drift，
+ * 避免无 lockfile 项目（如纯 generic / 非 nodejs）误判漂移。
+ *
+ * @param {object} [meta] - worktree meta（读 depsStatus / depsLockHash / depsError）
+ * @param {string} wtPath - worktree 根目录
+ * @param {string} mainCwd - 主 checkout 根目录
+ * @returns {{ status: 'fresh'|'missing'|'stale'|'main-drift'|'failed', detail: string, wtHash: (string|null), mainHash: (string|null), metaLockHash: (string|null) }}
+ */
+export function checkDepsFreshness(meta, wtPath, mainCwd) {
+  const depsStatus = meta && meta.depsStatus ? meta.depsStatus : null;
+  const metaLockHash = meta && meta.depsLockHash ? meta.depsLockHash : null;
+  const wtHash = lockfileHash(wtPath);
+  const mainHash = lockfileHash(mainCwd);
+
+  // 1. failed 最高优先级（对齐 task-01 蓝图：failed → missing → stale → main-drift → fresh）
+  if (depsStatus === 'failed') {
+    return {
+      status: 'failed',
+      detail: '上次依赖供给失败' + (meta && meta.depsError ? ': ' + meta.depsError : ''),
+      wtHash, mainHash, metaLockHash,
+    };
+  }
+
+  // 2. missing：曾 link/install 但 node_modules 已丢失（对齐 doctor 914-915 / ensure 403）
+  const nmExists = wtPath ? existsSync(join(wtPath, 'node_modules')) : false;
+  if (['linked', 'installed'].includes(depsStatus) && !nmExists) {
+    return {
+      status: 'missing',
+      detail: `meta.depsStatus=${depsStatus} 但 node_modules 缺失`,
+      wtHash, mainHash, metaLockHash,
+    };
+  }
+
+  // 3. stale：worktree 自身 lockfile 与 meta 快照不一致（对齐 doctor 916-917 / ensure 404）
+  if (metaLockHash && wtHash && wtHash !== metaLockHash) {
+    return {
+      status: 'stale',
+      detail: `lockfile 变化 (${metaLockHash} -> ${wtHash})`,
+      wtHash, mainHash, metaLockHash,
+    };
+  }
+
+  // 4. main-drift（新增）：wtHash 与主仓 mainHash 不一致——主仓 lockfile 更新过、worktree 未跟
+  if (wtHash && mainHash && wtHash !== mainHash) {
+    return {
+      status: 'main-drift',
+      detail: `worktree lockfile 与主仓不一致 (wt=${wtHash} main=${mainHash})`,
+      wtHash, mainHash, metaLockHash,
+    };
+  }
+
+  // 5. fresh
+  return {
+    status: 'fresh',
+    detail: '依赖新鲜',
+    wtHash, mainHash, metaLockHash,
+  };
+}