sillyspec 3.27.5 → 3.27.7

package/src/worktree-deps.js

@@ -8,8 +8,9 @@
  * 见 change 2026-06-28-worktree-deps-provision / D-005@v1, D-007@v1。
  */
 
-import { existsSync, readFileSync, realpathSync, lstatSync } from 'fs';
+import { existsSync, readFileSync, realpathSync, lstatSync, readdirSync, unlinkSync } from 'fs';
 import { join, isAbsolute, relative, resolve as resolvePath, sep as pathSep } from 'path';
+import { fileURLToPath } from 'url';
 import { execFileSync } from 'child_process';
 import { createHash } from 'crypto';
 
@@ -574,3 +575,94 @@ export function checkDepsFreshness(meta, wtPath, mainCwd) {
     wtHash, mainHash, metaLockHash,
   };
 }
+
+/**
+ * editable install 越界探测（坑 worktree-editable-install-escape，2026-08-25 用户实证
+ * gen:types 坑）：worktree 内 Python venv 的 editable install 指向 worktree 外（典型：
+ * 主仓 checkout 路径）时，gen:types / 后端命令 / pytest 静默加载 worktree 外的旧代码——
+ * 改动不生效且无任何报错，此前靠模块文档注意事项人工记忆，本函数把它 CLI 检查化
+ * （worktree doctor 调用）。
+ *
+ * 覆盖三种 editable 痕迹：
+ *   1. 路径型 .pth（setuptools 旧式）：.pth 内容行即绝对路径
+ *   2. PEP 660 __editable__.<pkg>-*.pth + __editable___<pkg>_*_finder.py（MAPPING 表绝对路径）
+ *   3. *.dist-info/direct_url.json { dir_info.editable: true, url: file:///... }
+ * 判定统一为「目标路径 resolve 后不在 worktree 内」；venv/文件读取失败按无越界处理
+ * （doctor 体检语义，不阻断）。
+ *
+ * @param {string} wtPath worktree 根目录
+ * @returns {Array<{ pkg: string, target: string, via: string }>} 越界清单（空 = 干净或无 venv）
+ */
+export function detectEditableInstallEscape(wtPath) {
+  const offenders = [];
+  if (!wtPath || !existsSync(wtPath)) return offenders;
+  const wtRoot = resolvePath(wtPath);
+  const isEscape = (target) => {
+    if (!target || !isAbsolute(target)) return false;
+    const rel = relative(wtRoot, resolvePath(target));
+    return rel.startsWith('..') || isAbsolute(rel);
+  };
+  const seen = new Set();
+  const push = (pkg, target, via) => {
+    const key = `${pkg}|${target}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    offenders.push({ pkg, target, via });
+  };
+
+  for (const venvName of ['.venv', 'venv']) {
+    const venvDir = join(wtPath, venvName);
+    if (!existsSync(venvDir)) continue;
+    // site-packages 候选：Windows Lib/site-packages + POSIX lib/python*/site-packages
+    const spCandidates = [join(venvDir, 'Lib', 'site-packages')];
+    try {
+      for (const e of readdirSync(join(venvDir, 'lib'), { withFileTypes: true })) {
+        if (e.isDirectory() && e.name.toLowerCase().startsWith('python')) {
+          spCandidates.push(join(venvDir, 'lib', e.name, 'site-packages'));
+        }
+      }
+    } catch { /* 无 lib 目录（Windows 布局）跳过 */ }
+    for (const sp of spCandidates) {
+      if (!existsSync(sp)) continue;
+      let entries = [];
+      try { entries = readdirSync(sp, { withFileTypes: true }); } catch { continue; }
+      for (const e of entries) {
+        if (!e.isFile()) continue;
+        const fp = join(sp, e.name);
+        if (e.name.endsWith('.pth')) {
+          let lines = [];
+          try { lines = readFileSync(fp, 'utf8').split('\n'); } catch { continue; }
+          for (const raw of lines) {
+            const line = raw.trim();
+            if (!line || line.startsWith('#') || line.startsWith('import ')) continue;
+            if (isEscape(line)) push(e.name.replace(/\.pth$/, ''), line, '.pth');
+          }
+        } else if (/^__editable___.+_finder\.py$/.test(e.name)) {
+          let src = '';
+          try { src = readFileSync(fp, 'utf8'); } catch { continue; }
+          const mm = /MAPPING\s*=\s*\{([\s\S]*?)\}/.exec(src);
+          if (!mm) continue;
+          const pkg = e.name.replace(/^__editable___/, '').replace(/_finder\.py$/, '');
+          for (const pm of mm[1].matchAll(/'((?:[^'\\]|\\.)*)'/g)) {
+            const target = pm[1].replace(/\\\\/g, '\\');
+            if (isEscape(target)) push(pkg, target, 'pep660-finder');
+          }
+        }
+      }
+      // direct_url.json（pip/uv 现代 editable 标记）
+      for (const e of entries) {
+        if (!e.isDirectory() || !e.name.endsWith('.dist-info')) continue;
+        const du = join(sp, e.name, 'direct_url.json');
+        if (!existsSync(du)) continue;
+        try {
+          const meta = JSON.parse(readFileSync(du, 'utf8'));
+          if (meta?.dir_info?.editable && typeof meta.url === 'string' && meta.url.startsWith('file://')) {
+            const target = fileURLToPath(meta.url);
+            if (isEscape(target)) push(e.name.replace(/\.dist-info$/, ''), target, 'direct_url');
+          }
+        } catch { /* 解析失败跳过 */ }
+      }
+    }
+  }
+  return offenders;
+}

package/src/worktree.js

@@ -12,8 +12,9 @@ import { execFileSync } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, readlinkSync, unlinkSync, copyFileSync } from 'fs';
 import { join, resolve, dirname, relative, isAbsolute } from 'path';
 import { createHash } from 'crypto';
-import { provisionDeps, checkDepsFreshness } from './worktree-deps.js';
+import { provisionDeps, checkDepsFreshness, detectEditableInstallEscape } from './worktree-deps.js';
 import { writeAtomicSync } from './fs-atomic.js';
+import { openDatabase } from './db-engine.js';
 import { git, gitQuiet } from './git-helper.js';
 
 // meta.json 会被 hook 进程与其它 CLI 进程并发读取（worktree-guard / getMeta / create 幽灵判定），
@@ -416,7 +417,7 @@ export class WorktreeManager {
    * @returns {{ branch: string, worktreePath: string, baseHash: string }}
    * @throws {Error} worktree 已存在、git 不可用、changeName 为空
    */
-  create(changeName, { base } = {}) {
+  create(changeName, { base, adoptBranch = false } = {}) {
     const name = validateChangeName(changeName);
     const worktreePath = this.getWorktreePath(name);
     const branch = BRANCH_PREFIX + name;
@@ -481,18 +482,29 @@ export class WorktreeManager {
         try { safeRemoveWorktreeDir(worktreePath); } catch (unlinkErr) {
           throw new Error(`幽灵 worktree 安全清理失败（已阻断，主仓 node_modules 未受影响）：${unlinkErr.message}`)
         }
-        // 同步清理 git worktree 注册 + 残留分支，否则目录虽删但 git 内部状态未清，
-        // 后续 git worktree add 会因「worktree 已注册」或「分支已存在」失败
+        // 同步清理 git worktree 注册（git 内部状态），否则后续 worktree add 会因「已注册」失败。
+        // 不再盲删同名分支（坑 worktree-user-branch-conflict，2026-08-24 用户反馈五期①：该分支
+        // 可能是用户有意创建的，无凭据区分遗留 vs 自建——统一交由下方分支决策菜单处置）。
         try { gitQuiet(this.cwd, ['worktree', 'prune'], { timeout: 30000 }); } catch {}
-        try { gitQuiet(this.cwd, ['branch', '-D', branch]); } catch {}
       } else {
         throw new Error(`worktree already exists: ${name}. Run cleanup first.`);
       }
     }
 
-    // 2. 检查分支是否已存在
-    if (gitQuiet(this.cwd, ['rev-parse', '--verify', `refs/heads/${branch}`])) {
-      throw new Error(`branch already exists: ${branch}. Run cleanup first.`);
+    // 2. 检查分支是否已存在（坑 worktree-user-branch-conflict，2026-08-24 用户反馈五期①：
+    // 「用户要求在指定分支上做」时既有同名分支让 execute 直接死锁，旧报错只说 Run cleanup
+    // first、修复建议无条件推荐删分支——用户自建分支被引导误删。现给决策菜单；--adopt-branch
+    // 显式收编：检出该分支为 worktree 工作分支，分支现状作 baseline，仅后续新改动计入交付。）
+    const branchExists = !!gitQuiet(this.cwd, ['rev-parse', '--verify', `refs/heads/${branch}`]);
+    let adoptedBranch = false;
+    if (branchExists && !adoptBranch) {
+      throw new Error(
+        `分支已存在：${branch}（worktree create 需新建同名分支，直接冲突）。按实际情况三选一：\n` +
+        `  ① 本变更的遗留分支（上次 execute 残留、内容已落地或作废）：确认后 git branch -D ${branch} 再重跑；\n` +
+        `  ② 该分支是你有意让本变更在其上做的（用户指定分支）：sillyspec run execute --change ${name} --adopt-branch\n` +
+        `     —— 收编为 worktree 工作分支，分支既有内容计入 baseline（仅后续新改动算交付 diff）；\n` +
+        `  ③ 换变更名重跑。`
+      );
     }
 
     // 3. 解析 base 分支
@@ -521,7 +533,17 @@ export class WorktreeManager {
 
     // 5. 创建 worktree（含版本检测 + sandbox fallback）
     try {
-      git(this.cwd, ['worktree', 'add', worktreePath, '-b', branch, baseHash], { timeout: 120000 });
+      if (branchExists && adoptBranch) {
+        // --adopt-branch 收编（坑 worktree-user-branch-conflict）：检出既有分支为工作分支（不 -b），
+        // 分支当前 HEAD 作 baseHash——分支存量内容归 baseline，仅子代理新改动计入交付 diff
+        // （与 dirty baseline overlay 同哲学）。baseBranch 仍记主仓侧锚（sync 诊断用）。
+        git(this.cwd, ['worktree', 'add', worktreePath, branch], { timeout: 120000 });
+        baseHash = git(this.cwd, ['rev-parse', branch]);
+        adoptedBranch = true;
+        console.log(`📌 已收编既有分支 ${branch} 为 worktree 工作分支（--adopt-branch）：baseline = 分支 HEAD ${String(baseHash).slice(0, 8)}，分支既有内容不计交付 diff`);
+      } else {
+        git(this.cwd, ['worktree', 'add', worktreePath, '-b', branch, baseHash], { timeout: 120000 });
+      }
     } catch (e) {
       const check = isGitWorktreeSupported(this.cwd);
       if (!check.supported) {
@@ -530,7 +552,12 @@ export class WorktreeManager {
       // 体检 BUG-16 并发竞态防御：多 agent 同时首建同名 change 时，败者的 add 失败可能只是
       // 「赢家刚建成目录/分支」。此时降级 in-place 会造成一个 worktree + 一个 in-place 的
       // 分裂状态（两 agent 各写各的基线）——先重查，并发赢家已建成则按 already exists 抛错。
-      if (existsSync(worktreePath) || gitQuiet(this.cwd, ['rev-parse', '--verify', `refs/heads/${branch}`])) {
+      // adopt 路径排除「分支存在性」判据（坑 adopt-branch-misreport-race）：分支既存是 adopt 的
+      // 前置条件（498 行已验证），此处 rev-parse 恒真——不排除时「分支已被其他 worktree 检出 /
+      // checkout 冲突 / 超时」等任何失败都被误报成「并发创建，另一进程已抢先建成」，
+      // 把用户指向完全错误的处置方向（Run cleanup first）。adopt 下仅目录存在性可作竞态判据。
+      const isAdoptPath = branchExists && adoptBranch;
+      if (existsSync(worktreePath) || (!isAdoptPath && gitQuiet(this.cwd, ['rev-parse', '--verify', `refs/heads/${branch}`]))) {
         throw new Error(`worktree already exists: ${name}（并发创建，另一进程已抢先建成，本进程不降级 in-place）. Run cleanup first.`);
       }
       // sandbox/permission fallback: 降级为 in-place + baseline protection
@@ -582,8 +609,9 @@ export class WorktreeManager {
 
     // 5.7 创建 baseline checkpoint（有 dirty baseline 时才创建）
     let baselineCommit = null;
+    if (adoptedBranch) baselineCommit = baseHash; // adopt：分支 HEAD 恒作交付 diff 锚（无 dirty overlay 也要锚定）
     if (baselineFiles.length > 0) {
-      baselineCommit = this._createBaselineCheckpoint(worktreePath, name);
+      baselineCommit = this._createBaselineCheckpoint(worktreePath, name, baselineFiles);
     }
 
     // 5.8 依赖供给（change 2026-06-28-worktree-deps-provision）
@@ -616,12 +644,13 @@ export class WorktreeManager {
       depsLockHash: deps.depsLockHash || null,
       depsCheckedAt: deps.depsCheckedAt || null,
       ...(deps.depsError ? { depsError: deps.depsError } : {}),
+      ...(adoptedBranch ? { adoptedBranch: true } : {}),
     };
 
     const metaPath = join(worktreePath, META_FILE);
     writeMetaAtomic(metaPath, meta);
 
-    return { branch, worktreePath, baseHash, mode: meta.mode, syncDiagnostic };
+    return { branch, worktreePath, baseHash, mode: meta.mode, syncDiagnostic, ...(adoptedBranch ? { adoptedBranch: true } : {}) };
   }
 
   /**
@@ -719,7 +748,7 @@ export class WorktreeManager {
 
     let baselineCommit = null;
     if (baselineFiles.length > 0) {
-      baselineCommit = this._createBaselineCheckpoint(this.cwd, name);
+      baselineCommit = this._createBaselineCheckpoint(this.cwd, name, baselineFiles);
     }
 
     const meta = {
@@ -1017,6 +1046,11 @@ export class WorktreeManager {
 
     // 4. 删除分支（fail-closed：task review 引用可达性校验。force 也不绕过——force 语义 =
     //    丢弃内容，不含丢弃审计链；确要删用 git branch -D 手动执行）
+    //    native-worktree 豁免（坑 worktree-user-branch-conflict，2026-08-24）：该模式 meta.branch
+    //    记的是用户自己的检出分支（非 sillyspec 所建），force 也不删——只清 sillyspec 侧注册。
+    if (mode === 'native-worktree') {
+      details.push(`branch kept: native-worktree 模式的 branch（${branch}）是用户自己的检出分支，不删除`);
+    } else
     //    升级（坑 cleanup-branch-review-anchor-tag，2026-08-21 实证）：分支被 review.json 引用
     //    时不再只能手动保留——打 `sillyspec-audit/<branch>` 轻量 tag 锚定分支 tip（ref 前缀独立
     //    于 sillyspec/* 分支族，doctor 孤儿分支扫描不误伤），commit 经 tag 保持可达（gc 安全），
@@ -1176,16 +1210,19 @@ export class WorktreeManager {
     // 数据源不一致——并行会话的活跃变更（meta 已清/in-place/平台模式 meta 在别处）分支会被全局
     // doctor --fix 误删。删分支前交叉核对：分支名 ∈ 活跃变更 → 保留（fixable:false 提示人工确认）。
     // 先探 DB 文件存在再实例化 ProgressManager（坑7 读路径建库：_ensureDB 不存在会建库污染）。
-    // null = 进度库存在但读失败（无法判定活跃态，保守不自动删）；空 Set = 无库/无活跃变更
-    // （git-only 工作流零回归，孤儿分支照删）。
+    // null = 无法核对（读失败 或 无进度库——坑 worktree-user-branch-conflict 2026-08-24 收紧：
+    // 无库时无法区分孤儿与用户自建分支，从「照删」改保守保留，git-only 便利让位于不误删）；
+    // Set = 进度库可读（空集=无活跃变更，非活跃孤儿仍可删）。
     let activeChanges = null;
+    let dbMissing = false;
     try {
       const specBaseOfWt = dirname(dirname(this.worktreeBase)); // <specBase>（.runtime/worktrees 上两级）
       if (existsSync(join(specBaseOfWt, '.runtime', 'sillyspec.db'))) {
         const { ProgressManager } = await import('./progress.js');
         activeChanges = new Set(new ProgressManager({ specDir: specBaseOfWt }).listChanges(this.cwd));
       } else {
-        activeChanges = new Set();
+        activeChanges = null;
+        dbMissing = true;
       }
     } catch (e) {
       console.warn(`⚠️ doctor 进度库读取失败，孤儿分支的活跃态交叉核对不可用（保守不自动删）: ${e.message}`);
@@ -1296,6 +1333,17 @@ export class WorktreeManager {
               (r.ok ? fixed : unfixable).push(r.msg);
             }
           }
+          // editable install 越界检查（坑 worktree-editable-install-escape，2026-08-25 实证
+          // gen:types 坑）：worktree venv 的 editable install 指向 worktree 外（主仓）时，
+          // gen:types/后端命令/pytest 静默加载旧代码零报错——此前靠模块文档人工记忆，内建检查化。
+          // fixable:false（重装决策留给用户：uv sync / pip install -e . 需按项目方式选）。
+          try {
+            const escapes = detectEditableInstallEscape(wtPath);
+            if (escapes.length > 0) {
+              issues.push({ type: 'editable-install-escape', name, fixable: false,
+                detail: `worktree venv 含 ${escapes.length} 个 editable install 指向 worktree 外（${escapes.slice(0, 5).map(e => `${e.pkg}→${e.target}`).join(', ')}${escapes.length > 5 ? ' 等' : ''}）——gen:types/后端命令会静默加载 worktree 外旧代码。修复：在 worktree 内重装（uv sync / uv pip install -e .）后重跑生成命令` });
+            }
+          } catch { /* 探测失败不阻断 doctor */ }
           }
         }
 
@@ -1375,9 +1423,20 @@ export class WorktreeManager {
               continue;
             }
             if (activeChanges === null) {
-              // 进度库读失败：无法判定活跃态，保守不自动删（宁可漏删不可误删并行会话分支）
+              // 无法核对活跃态（读失败 或 无进度库）：保守不自动删（宁可漏删不可误删——
+              // 坑 worktree-user-branch-conflict：无库时该分支可能是用户自建的，无凭据区分）
+              const why = dbMissing ? '无进度库，无法区分孤儿与用户自建分支' : '进度库不可读，无法交叉核对活跃态'
+              issues.push({ type: 'orphan-branch', name, fixable: false,
+                detail: `分支疑似残留（无对应 meta，且${why}）: ${branch}——保守不自动删，人工确认后 git branch -D ${branch}` });
+              continue;
+            }
+            // review 锚点复核（坑 worktree-user-branch-conflict）：分支上有 task review base/head
+            // 引用的 commit → 审计链在用，不自动删（与 cleanup 的分支删除审计保护同口径）
+            let reviewRefs = [];
+            try { reviewRefs = this._branchReviewReferences(branch); } catch { reviewRefs = [] }
+            if (reviewRefs.length > 0) {
               issues.push({ type: 'orphan-branch', name, fixable: false,
-                detail: `分支疑似残留（无对应 meta，且进度库不可读无法交叉核对活跃态）: ${branch}——保守不自动删，人工确认后 git branch -D ${branch}` });
+                detail: `分支无对应 meta 但被 ${reviewRefs.length} 个 task review.json 的 base/head 引用（审计锚点）——保留。确要删除：先归档/迁移审计引用，或手动 git branch -D ${branch}` });
               continue;
             }
             issues.push({ type: 'orphan-branch', name, detail: `分支残留（无对应 meta，且非活跃变更）: ${branch}`, fixable: true });
@@ -1583,7 +1642,6 @@ export class WorktreeManager {
     try {
       const dbPath = join(this.cwd, '.sillyspec', '.runtime', 'sillyspec.db');
       if (!existsSync(dbPath)) return false;
-      const { openDatabase } = require('./db-engine.js');
       const db = openDatabase(dbPath, { readOnly: true });
       try {
         const row = db.prepare('SELECT status FROM changes WHERE name = ?').get(name);
@@ -1748,9 +1806,13 @@ export class WorktreeManager {
    * 用于区分 "前置 dirty baseline" 和 "子代理新增改动"
    * @param {string} worktreePath
    * @param {string} changeName
+   * @param {string[]} [baselineFiles] 主仓并行在途文件清单（_overlayBaseline 返回的 files，
+   *   已排除 .sillyspec）——写入提交信息正文（坑 baseline-checkpoint-opaque-carriage，
+   *   2026-08-24 用户反馈三期③：checkpoint 把主仓并行脏文件带进分支 diff，逐任务归因要靠
+   *   人肉区分；清单入 message 后 `git log` 一眼可辨、可机械排除）
    * @returns {string} commit hash
    */
-  _createBaselineCheckpoint(worktreePath, changeName) {
+  _createBaselineCheckpoint(worktreePath, changeName, baselineFiles = []) {
     // 使用临时 git identity，避免用户未配置 user.name/user.email 导致失败
     const env = {
       GIT_AUTHOR_NAME: 'sillyspec',
@@ -1765,13 +1827,21 @@ export class WorktreeManager {
       if (!status) {
         return gitQuiet(worktreePath, ['rev-parse', 'HEAD']);
       }
+      // 提交信息正文列夹带文件（封顶 30 行，超出记总数）——清单与 meta.baselineFiles 同源
+      const CAP = 30
+      const files = Array.isArray(baselineFiles) ? baselineFiles.filter(Boolean) : []
+      const body = files.length > 0
+        ? ['\n主仓并行在途文件（非本变更改动，逐任务归因时排除）：',
+           ...files.slice(0, CAP).map(f => `- ${f}`),
+           ...(files.length > CAP ? [`…等共 ${files.length} 个`] : [])].join('\n')
+        : ''
       // --no-verify：baseline 是锚点不是交付物，只是把主仓库 dirty 文件快照到 worktree
       // 分支上以便区分「前置 baseline」与「子代理新增改动」。它不该触发项目 pre-commit
       // hook（如 ruff format），否则主仓库 dirty 文件中任一不达标的会被 hook reformat
       // 致 commit 失败 → worktree 创建失败 → execute 无法启动。
       execFileSync(
         'git',
-        ['commit', '--no-verify', '-m', `sillyspec: baseline checkpoint for ${changeName}`],
+        ['commit', '--no-verify', '-m', `sillyspec: baseline checkpoint for ${changeName}${body}`],
         { cwd: worktreePath, encoding: 'utf8', stdio: ['pipe','pipe','pipe'], env }
       );
       const hash = git(worktreePath, ['rev-parse', 'HEAD']);

package/templates/prompts/taskcard-rules.md

@@ -26,4 +26,4 @@ TaskCard 格式规则（必须严格遵守）：
   - **规范约定字段**（应填但不硬校验，缺失不阻断完成、只影响规范性）：author、created_at、priority、depends_on、blocks
   - allowed_paths 非空（至少一个真实源文件路径；回归类 task 无源码改动时填被验证的关键入口文件）
   - acceptance 与 verify 都在 frontmatter 内（漏写会被 plan-postcheck 报「缺少验收标准」/「缺少验证步骤」）
-- **生成方式**：用 `sillyspec taskcard <change-name> --task task-NN [--all]` 生成安全骨架（LF 行尾 + frontmatter 必闭合 + 九个硬校验字段齐全 + author/created_at 自动填），再往骨架里填语义内容——**勿用 Write tool 整文件手写**（CRLF / 漏闭合 `---` / 漏字段的根源，postcheck 报错大多由此来）；已存在的卡命令会跳过不覆盖，局部修改用 Edit 定点改
+- **生成方式**：由主 agent 一次性 `sillyspec taskcard <change-name> --all` 预生成全部安全骨架（LF 行尾 + frontmatter 必闭合 + 九个硬校验字段齐全 + author/created_at 自动填；幂等，已存在跳过）。**子代理不要并行跑 taskcard CLI**（2026-08-25 实证撞进度库 SQLite 锁），只往骨架里填语义内容（LF 行尾 + frontmatter 必闭合 + 九个硬校验字段齐全 + author/created_at 自动填），再往骨架里填语义内容——**勿用 Write tool 整文件手写**（CRLF / 漏闭合 `---` / 漏字段的根源，postcheck 报错大多由此来）；已存在的卡命令会跳过不覆盖，局部修改用 Edit 定点改