sillyspec 3.29.5 → 3.31.0

package/src/worktree-apply.js

@@ -16,7 +16,7 @@ import { existsSync, unlinkSync, writeFileSync, mkdtempSync, rmSync, readdirSync
 import { join, resolve } from 'path';
 import { tmpdir } from 'os';
 import { createHash } from 'crypto';
-import { WorktreeManager } from './worktree.js';
+import { WorktreeManager, detectDeliverableContained } from './worktree.js';
 import { getCrossWorktreeMeta, cleanupCrossWorktrees } from './worktree-cross.js';
 import { parseFileChangeList, parseFileChangeListDetailed, pathMatches } from './change-list.js';
 import { parseAllowedPaths, parseRepo } from './stages/plan-postcheck.js';
@@ -25,6 +25,7 @@ import { resolveLatestExecuteRunId, resolveLatestExecuteRunIdWithTasks, readRevi
 import { collectActiveQuickGuardFiles } from './quicklog.js';
 import { appendWriteAudit, WRITE_AUDIT_FILE_CAP } from './write-audit.js';
 import { detectCommittedDrift, formatCommittedDriftWarning } from './run/concurrent-detect.js';
+import { readWorktreePolicy } from './worktree-policy.js';
 
 const CHANGES_REL = '.sillyspec/changes';
 
@@ -1254,6 +1255,21 @@ function applyCrossRepoWorktrees(changeName, projectRoot, ctx, { checkOnly = fal
 
 export function applyWorktree(changeName, { cwd, checkOnly = false, merge = false, base = 'merge-base', ctx = null, skipOverlap = false, stashDirty = false, force = false, autoApply = false } = {}) {
   const projectRoot = cwd || process.cwd();
+  // ── worktree.policy 选择记忆（R16 减负批次，2026-09-24）──
+  // 显式 flag > policy > fail-closed 缺省；policy 触发的 force/skip 走同一条留痕路径
+  //（overlapForced/overlapSkipped），不开新权限面——只消「同一冲突每次重拦重问」的摩擦轮。
+  let policyOverlapForced = false;
+  try {
+    const policy = readWorktreePolicy(projectRoot);
+    if (policy.applyOverlap === 'force' && !force && !autoApply) {
+      force = true;
+      policyOverlapForced = true;
+    }
+    if (policy.stashDirty && !stashDirty) {
+      stashDirty = true;
+      console.log(`📦 worktree.policy.stash_dirty=true：主仓在途改动将自动 stash（等效常备 --stash-dirty，local.yaml 选择记忆）`);
+    }
+  } catch { /* policy 读失败 → 全缺省 fail-closed，行为与无 policy 完全一致 */ }
   const wm = new WorktreeManager({ cwd: projectRoot });
   const meta = wm.getMeta(changeName);
   const result = {
@@ -1571,10 +1587,11 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
       const files = [...new Set(guardCheck.overlaps.map(o => o.file))];
       const pairLines = guardCheck.overlaps.map(o => `  [${o.sessionId}] ${o.file}`);
       if (force) {
-        // 显式解锁：放行并留痕（审计可见——自动路径永不带 force，overlapForced 只可能来自人工 --force）
-        result.overlapForced = { sessions, files };
+        // 显式解锁：放行并留痕（审计可见——自动路径永不带 force，overlapForced 只可能来自人工 --force
+        // 或 worktree.policy.apply_overlap=force 的选择记忆[R16 减负批次]，两种来源均留痕）
+        result.overlapForced = { sessions, files, ...(policyOverlapForced ? { via: 'worktree.policy.apply_overlap=force' } : {}) };
         result.warnings = (result.warnings || []).concat([
-          `--force 越过 guard 相交预检：${guardCheck.overlaps.length} 个会话×文件对与活跃 quick 会话声明重叠——` +
+          `${policyOverlapForced ? 'worktree.policy.apply_overlap=force 选择记忆放行（local.yaml）' : '--force 越过 guard 相交预检'}：${guardCheck.overlaps.length} 个会话×文件对与活跃 quick 会话声明重叠——` +
           pairLines.join('；') + `（对方会话在途改动可能被覆盖，overlapForced 留痕）`
         ]);
       } else if (autoApply) {
@@ -1874,6 +1891,29 @@ export function applyWorktree(changeName, { cwd, checkOnly = false, merge = fals
 
     // 5b hashMismatch 计算已前移到 step3.5（Grill P0），见上
 
+    // ── 合并感知包含清理（ql-20260921-010 修复，ql-20260921-009② 的晚置重接线）──
+    // 4.5/4.5b 合并管线跑完之后、patch 生成/checkOnly 返回之前：对 changedFiles 残余面逐文件
+    // 只读三方包含测试（merge(base, ours=主仓现状, theirs=worktree) clean 且===主仓现状 ⟺
+    // 交付 delta 已全在主仓——差异纯属并行增量）。命中者剔出 changedFiles（面清：归档/清理门
+    // 的「未 apply」判定不再误拦三方合并落地件），审计入 result.mergeContainedFiles。
+    // 早于合并步做（009② 原形态）会抢占 EXCLUDE-DIRTY/MISMATCH 管线——mergedDirtyFiles 审计
+    // 与合并写回被短路（apply-dirty-threeway 主仓红实证），故必须晚置。
+    try {
+      if (changedFiles.length > 0) {
+        const containedFiles = detectDeliverableContained(
+          { projectRoot, worktreePath, baseRef: deliverableBase }, changedFiles);
+        if (containedFiles.length > 0) {
+          const containedSet = new Set(containedFiles);
+          changedFiles = changedFiles.filter(f => !containedSet.has(f));
+          result.mergeContainedFiles = containedFiles;
+          result.warnings = result.warnings || [];
+          result.warnings.push(
+            containedFiles.length + ' 个文件交付已包含于主仓当前内容（差异为并行会话增量，合并感知判定不计入未 apply 面）：' +
+            containedFiles.slice(0, 5).join(', ') + (containedFiles.length > 5 ? ' 等' : ''));
+        }
+      }
+    } catch { /* 包含判定异常 → 保守保留（宁误拦不误放） */ }
+
     // --- 6. checkOnly 模式：到此返回 ---
     if (checkOnly) {
       result.ok = true;

package/src/worktree-deps.js

@@ -74,8 +74,22 @@ const ECOSYSTEMS = [
     marker: null,
     detect: (d) => existsSync(join(d, 'pyproject.toml')) || existsSync(join(d, 'requirements.txt')),
     // uv 优先（现代 Python 工具链，pyproject/uv.lock 项目走 uv sync 建 .venv + 装依赖，
-    // 与 execute worktree 环境预告一致）；纯 requirements.txt（无 pyproject）回退 pip
-    install: (d) => (existsSync(join(d, 'uv.lock')) || existsSync(join(d, 'pyproject.toml')) ? 'uv sync' : 'pip install -r requirements.txt'),
+    // 与 execute worktree 环境预告一致）；纯 requirements.txt（无 pyproject）回退 pip。
+    // extras 探测（R14/R15 对撞实证 2026-09-24）：裸 uv sync 不装 [project.optional-dependencies]
+    // extras，worktree / verify deps 门重建的 .venv 缺 dev extras → `uv run pytest` 回落全局
+    // 环境报批量 ModuleNotFoundError（R14-OS 244 个，每次 6 轮自愈）。声明了 optional-dependencies
+    // 的仓补 --all-extras；[dependency-groups] 的 dev 组 uv sync 缺省已含，不加 flag。
+    // 白名单（INSTALL_BINARY_WHITELIST）按 binary 首 token 判定，--all-extras 无元字符天然放行。
+    install: (d) => {
+      if (existsSync(join(d, 'uv.lock')) || existsSync(join(d, 'pyproject.toml'))) {
+        try {
+          const py = readFileSync(join(d, 'pyproject.toml'), 'utf8')
+          if (/^\s*\[project\.optional-dependencies\]/m.test(py)) return 'uv sync --all-extras'
+        } catch { /* pyproject 读不到（纯 uv.lock 残缺 checkout）按裸 uv sync */ }
+        return 'uv sync'
+      }
+      return 'pip install -r requirements.txt'
+    },
   },
   {
     type: 'go',
@@ -229,7 +243,7 @@ function tryLink(mainNodeModules, linkPath) {
   try {
     if (lstatSync(linkPath).isSymbolicLink()) {
       if (process.platform === 'win32') {
-        execFileSync('cmd.exe', ['/c', 'rmdir', linkPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+        execFileSync('cmd.exe', ['/c', 'rmdir', linkPath], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
       } else {
         unlinkSync(linkPath);
       }
@@ -239,9 +253,9 @@ function tryLink(mainNodeModules, linkPath) {
     if (process.platform === 'win32') {
       // execFileSync 数组形式不经 shell：POSIX 双引号内 `/$() 会执行、cmd.exe 双引号内 %VAR% 仍展开，
       // linkPath 含 local.yaml 模块 path，属项目内可配置值（安全收敛，与 git-helper 同范式）
-      execFileSync('cmd.exe', ['/c', 'mklink', '/J', linkPath, mainNodeModules], { stdio: ['pipe', 'pipe', 'pipe'] });
+      execFileSync('cmd.exe', ['/c', 'mklink', '/J', linkPath, mainNodeModules], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
     } else {
-      execFileSync('ln', ['-s', mainNodeModules, linkPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+      execFileSync('ln', ['-s', mainNodeModules, linkPath], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
     }
     // 创建后实物复核（坑 provision-silent-fake-installed 第②层，2026-08-21 实证：doctor 报
     // re-provisioned 成功但 junction 实际没建）——mklink/ln 退出码 0 不等于链接落盘（cmd.exe
@@ -325,9 +339,9 @@ function tryInstall(cmd, cwd, timeout) {
       if (process.platform === 'win32') {
         // Windows 包管理器是 .cmd 垫片，无 shell 的 spawn 无法解析——经 cmd.exe /c 传参；
         // 元字符（含 %）已拦，残余风险与 tryLink 的 mklink 同款
-        execFileSync('cmd.exe', ['/c', ...argv], { cwd: curCwd, timeout, stdio: ['pipe', 'pipe', 'pipe'] });
+        execFileSync('cmd.exe', ['/c', ...argv], { cwd: curCwd, timeout, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
       } else {
-        execFileSync(argv[0], argv.slice(1), { cwd: curCwd, timeout, stdio: ['pipe', 'pipe', 'pipe'] });
+        execFileSync(argv[0], argv.slice(1), { cwd: curCwd, timeout, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
       }
     } catch (e) {
       const raw = e.killed ? `timeout after ${timeout}ms` : ((e.stderr && e.stderr.toString()) || e.message);
@@ -454,7 +468,7 @@ export function sweepForeignNodeModulesJunctions(mainDir, { worktreesRoot, specB
       if (dryRun) continue;
       try {
         if (process.platform === 'win32') {
-          execFileSync('cmd.exe', ['/c', 'rmdir', linkPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+          execFileSync('cmd.exe', ['/c', 'rmdir', linkPath], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
         } else {
           unlinkSync(linkPath);
         }

package/src/worktree-policy.js

@@ -0,0 +1,42 @@
+/**
+ * worktree-policy.js — worktree 守卫选择记忆（R16 减负批次，2026-09-24）
+ *
+ * 背景：worktree/apply 三处守卫（分支冲突三选一 / guard 相交三态 / 主仓脏树 stash）此前
+ * 全是 fail-closed 抛错 + 文字菜单，选择只活在当次 flag 里不落任何配置——同一冲突下次
+ * 原样重拦重问（对撞 R15 实证：无人值守跑批时这类重拦是纯摩擦轮）。
+ *
+ * 本模块读 local.yaml `worktree.policy` 段（js-yaml，best-effort 绝不抛）：
+ *   adopt_branch:  true   → 分支已存在冲突时自动按「收编既有分支」处置（等效常备 --adopt-branch）
+ *   apply_overlap: force | skip | manual（缺省 manual = 既有 fail-closed）
+ *                          → guard 相交拦截的无人值守处置（force=放行留痕 / skip=软跳过）
+ *   stash_dirty:   true   → 主仓脏树时自动 stash（等效常备 --stash-dirty）
+ *
+ * 优先级铁律：显式 flag > policy > fail-closed 缺省。policy 只消「重复选择」，不开新权限面
+ * ——force/skip 经 policy 触发时同样落 overlapForced/overlapSkipped 留痕（审计可见）。
+ */
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import jsYaml from 'js-yaml'
+
+/**
+ * 读 worktree.policy 段。
+ * @param {string} repoRoot - 主仓根（local.yaml 在 <repoRoot>/.sillyspec/local.yaml）
+ * @returns {{ adoptBranch: boolean, applyOverlap: 'manual'|'force'|'skip', stashDirty: boolean }}
+ *   文件缺/解析失败/段缺 → 全缺省（adoptBranch=false, applyOverlap='manual', stashDirty=false）。
+ */
+export function readWorktreePolicy(repoRoot) {
+  const fallback = { adoptBranch: false, applyOverlap: 'manual', stashDirty: false }
+  try {
+    const text = readFileSync(join(repoRoot, '.sillyspec', 'local.yaml'), 'utf8')
+    const doc = jsYaml.load(text) || {}
+    const policy = doc && doc.worktree && doc.worktree.policy
+    if (!policy || typeof policy !== 'object') return fallback
+    return {
+      adoptBranch: policy.adopt_branch === true,
+      applyOverlap: policy.apply_overlap === 'force' || policy.apply_overlap === 'skip' ? policy.apply_overlap : 'manual',
+      stashDirty: policy.stash_dirty === true,
+    }
+  } catch {
+    return fallback
+  }
+}

package/src/worktree.js

@@ -9,8 +9,9 @@
  */
 
 import { execFileSync } from 'child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, readlinkSync, unlinkSync, copyFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, readlinkSync, unlinkSync, copyFileSync, mkdtempSync } from 'fs';
 import { join, resolve, dirname, relative, isAbsolute, basename } from 'path';
+import { tmpdir } from 'os';
 import { createHash } from 'crypto';
 import { provisionDeps, checkDepsFreshness, detectEditableInstallEscape, sweepForeignNodeModulesJunctions } from './worktree-deps.js';
 import { resolveRuntimeRoot } from './run/shared.js';
@@ -20,6 +21,7 @@ import { git, gitQuiet, unquoteGitPath } from './git-helper.js';
 // foreign-declared 零环独立模块（仅依赖 change-list/git-helper/stages/plan-postcheck，
 // 链上无回边）——contract-matrix/verify-probes/task-review 等处已有同款 import 先例
 import { splitOwnVsForeignDiffFiles } from './foreign-declared.js';
+import { readWorktreePolicy } from './worktree-policy.js';
 
 // meta.json 会被 hook 进程与其它 CLI 进程并发读取（worktree-guard / getMeta / create 幽灵判定），
 // 必须原子写：半截 JSON 会让 getMeta 返回 null → 触发幽灵 worktree 强删（可能丢 gitignored 改动）。
@@ -47,6 +49,62 @@ function _chunkPathsPrivate(paths, maxChars = 8000) {
   return batches
 }
 
+/**
+ * 交付包含判定（合并感知「未 apply」口径，ql-20260921-009 ②，2026-09-21 batch2 归档实证）。
+ *
+ * 语义：worktree 交付文件与主仓**当前工作区**内容不等时，做只读三方合并测试——
+ * base=交付锚点（baselineCommit||baseHash）版本、ours=主仓工作区内容、theirs=worktree
+ * 交付内容；clean 合并且结果 === 主仓工作区内容 ⟺ worktree 的全部改动已被主仓包含
+ * （差异全是并行会话在主仓的增量）→ 该文件视为已 apply。实证形态：交付文件经
+ * EXCLUDE-DIRTY/MISMATCH 三方合并落地后天然含并行增量，字节等值口径的归档/清理门
+ * 恒误拦「未 apply」（分支非 merge 落地时可达性短路也不命中），人工 grep 自证后才
+ * 走 --skip-apply/--force 逃生口。
+ *
+ * 与 worktree-apply.js mergeDirtyOverlapThreeWay 的差异：**只读不写回**（判定专用，
+ * 无备份/暂存面）；冲突/取不到 base/异常 fail-safe 不剔（宁误拦不误放）。放本文件
+ * 导出供 worktree-apply.js 消费（那边 import 本文件是既有方向，反向会成环——
+ * _lsTreeBlobs 注释同款约束）。成本：仅对「内容不等」的残余交付文件逐个一次
+ * git merge-file（正常收尾路径 0 个文件触发），生命周期边界点一次性开销。
+ *
+ * @param {{ projectRoot: string, worktreePath: string, baseRef: string }} ctx
+ * @param {string[]} files 待判文件（仓库根相对路径；不可读/base 缺席者自动跳过）
+ * @returns {string[]} 判定为「已包含于主仓当前内容」的文件子集（files 原字面）
+ */
+export function detectDeliverableContained({ projectRoot, worktreePath, baseRef }, files) {
+  const contained = []
+  if (!Array.isArray(files) || files.length === 0 || !baseRef) return contained
+  let tmpDir = null
+  try {
+    for (const f of files) {
+      if (!f || typeof f !== 'string') continue
+      try {
+        const wtRaw = readFileSync(join(worktreePath, f))
+        const mainRaw = readFileSync(join(projectRoot, f))
+        if (wtRaw.equals(mainRaw)) { contained.push(f); continue } // 快路径：内容相等天然已含
+        const baseRaw = git(projectRoot, ['show', `${baseRef}:${f}`], { encoding: 'buffer', timeout: 15000 })
+        if (!tmpDir) tmpDir = mkdtempSync(join(tmpdir(), 'sillyspec-contain-'))
+        const p = (tag) => join(tmpDir, `${tag}-${Math.random().toString(36).slice(2, 8)}`)
+        const baseP = p('base'); const oursP = p('ours'); const theirsP = p('theirs')
+        writeFileSync(baseP, baseRaw); writeFileSync(oursP, mainRaw); writeFileSync(theirsP, wtRaw)
+        // merge-file <current=ours(主仓现状)> <base> <other=theirs(worktree 交付)> -p：
+        // stdout=合并结果；exit 0=clean。结果===主仓现状 ⟺ 交付 delta 已全在主仓。
+        let outBuf, code = 0
+        try {
+          outBuf = git(projectRoot, ['merge-file', '-p', oursP, baseP, theirsP], { encoding: 'buffer', timeout: 15000 })
+        } catch (e) {
+          code = (typeof e.status === 'number') ? e.status : -1
+          outBuf = (e.stdout instanceof Buffer) ? e.stdout : Buffer.alloc(0)
+          if (code < 0) continue // merge-file 不可用 → 保守不剔
+        }
+        if (code === 0 && outBuf.equals(mainRaw)) contained.push(f)
+      } catch { /* 该文件判定不可得 → 保守不剔 */ }
+    }
+  } finally {
+    if (tmpDir) { try { rmSync(tmpDir, { recursive: true, force: true }) } catch {} }
+  }
+  return contained
+}
+
 // ── supplyFiles 生成物供给（坑③ / FR-03 / D-003@v1）──
 // .gitignore 生成物（如 src/build-id.ts）不在 git 树也不进 untracked overlay
 // （ls-files --others --exclude-standard 尊重 .gitignore），worktree 缺失致构建炸
@@ -163,7 +221,7 @@ export function unlinkNodeModulesLinks(worktreePath, meta = null, details = null
     try {
       if (process.platform === 'win32') {
         // Windows rmdir 删 junction（reparse point）不跟随目标；execFileSync 数组形式不经 shell
-        execFileSync('cmd.exe', ['/c', 'rmdir', nm]);
+        execFileSync('cmd.exe', ['/c', 'rmdir', nm], { windowsHide: true });
       } else {
         unlinkSync(nm);
       }
@@ -695,17 +753,28 @@ export class WorktreeManager {
     // 2. 检查分支是否已存在（坑 worktree-user-branch-conflict，2026-08-24 用户反馈五期①：
     // 「用户要求在指定分支上做」时既有同名分支让 execute 直接死锁，旧报错只说 Run cleanup
     // first、修复建议无条件推荐删分支——用户自建分支被引导误删。现给决策菜单；--adopt-branch
-    // 显式收编：检出该分支为 worktree 工作分支，分支现状作 baseline，仅后续新改动计入交付。）
+    // 显式收编：检出该分支为 worktree 工作分支，分支现状作 baseline，仅后续新改动计入交付。
+    // worktree.policy.adopt_branch（R16 减负批次 2026-09-24）：选择记忆——显式 flag 缺席时
+    // policy=true 等效常备 --adopt-branch（adoption 留痕同款），消「同一冲突每次重拦重问」。
     const branchExists = !!gitQuiet(this.cwd, ['rev-parse', '--verify', `refs/heads/${branch}`]);
     let adoptedBranch = false;
+    let adoptViaPolicy = 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` +
-        `  ③ 换变更名重跑。`
-      );
+      const policy = readWorktreePolicy(this.cwd);
+      if (policy.adoptBranch) {
+        adoptBranch = true;
+        adoptViaPolicy = true;
+        console.log(`📌 worktree.policy.adopt_branch=true：分支 ${branch} 已存在，自动收编（等效 --adopt-branch，local.yaml 选择记忆）`);
+      } else {
+        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` +
+          `     （每次都选②可在 local.yaml 配 worktree.policy.adopt_branch: true 记忆该选择）\n` +
+          `  ③ 换变更名重跑。`
+        );
+      }
     }
 
     // 3. 解析 base 分支
@@ -865,12 +934,13 @@ export class WorktreeManager {
       // 5.9 实供清单（纯记录面，doctor/审计可读；空供给省略字段——存量 meta 缺省兼容）
       ...(suppliedFiles.length > 0 ? { supplyFiles: suppliedFiles } : {}),
       ...(adoptedBranch ? { adoptedBranch: true } : {}),
+      ...(adoptViaPolicy ? { adoptViaPolicy: true } : {}),
     };
 
     const metaPath = join(worktreePath, META_FILE);
     writeMetaAtomic(metaPath, meta);
 
-    return { branch, worktreePath, baseHash, mode: meta.mode, syncDiagnostic, ...(adoptedBranch ? { adoptedBranch: true } : {}) };
+    return { branch, worktreePath, baseHash, mode: meta.mode, syncDiagnostic, ...(adoptedBranch ? { adoptedBranch: true } : {}), ...(adoptViaPolicy ? { adoptViaPolicy: true } : {}) };
   }
 
   /**
@@ -1957,7 +2027,7 @@ export class WorktreeManager {
       }
 
       // 2) 候选集中尚未落到主工作区 HEAD 的子集
-      const pending = this._changesAlreadyOnMain(worktreePath, tracked, untracked);
+      const pending = this._changesAlreadyOnMain(worktreePath, tracked, untracked, diffBase);
       // 3) main 工作区副本降噪层（坑 unapplied-false-positive-workspace-copy，2026-08-21 实证：
       // apply 后 main 工作区有逐字节一致副本但未 commit → HEAD-only 判定报「未落仓」虚警拦
       // doctor）。原注释「不查 main 工作区未提交副本（防误删）」的保护意图是内容未落地——
@@ -1995,9 +2065,9 @@ export class WorktreeManager {
    * @param {string[]} untrackedFiles
    * @returns {string[]} 尚未落到 main HEAD 的文件
    */
-  _changesAlreadyOnMain(worktreePath, trackedFiles, untrackedFiles) {
+  _changesAlreadyOnMain(worktreePath, trackedFiles, untrackedFiles, diffBase = null) {
     const mainHead = git(this.cwd, ['rev-parse', 'HEAD']); // 失败即抛 → 外层 catch fail-safe
-    const pending = [];
+    let pending = [];
 
     if (trackedFiles.length > 0) {
       const diverged = (gitQuiet(worktreePath,
@@ -2024,7 +2094,24 @@ export class WorktreeManager {
       }
     }
 
-    return [...new Set(pending)];
+    pending = [...new Set(pending)];
+
+    // 合并感知包含剔除（ql-20260921-009 ②）：pending 文件（≠主仓 HEAD）与主仓**当前工作区**
+    // 内容逐个只读三方合并测试——worktree delta 已全在主仓（差异=并行增量，如三方合并落地后
+    // 形态）→ 视为已落地剔除。字节等值口径对该形态恒误拦（2026-09-21 batch2 归档实证），
+    // 分支非 merge 落地时上方可达性短路也不命中。冲突/异常 fail-safe 不剔。
+    if (diffBase && pending.length > 0) {
+      const contained = detectDeliverableContained(
+        { projectRoot: this.cwd, worktreePath, baseRef: diffBase },
+        pending,
+      );
+      if (contained.length > 0) {
+        const containedSet = new Set(contained);
+        pending = pending.filter(f => !containedSet.has(f));
+      }
+    }
+
+    return pending;
   }
 
   /**

package/templates/agents-instruction.md

@@ -1,24 +1,43 @@
 # Agent 指引
 
 ## 项目说明
-本项目使用 **SillySpec** 管理变更，采用文档驱动开发。SillySpec 是给 Agent 调用的 CLI 流程控制器，不是给人类直接使用的产品，也不是处理业务逻辑的工具——你（Agent）通过 CLI 告诉它"我在哪"，它告诉你"下一步做什么"；你执行步骤，它校验产出、推进状态，人类只在关键决策点介入审批。要考虑多 agent 同时操作代码，代码随时可能变化。所有变更以稳定、可用、可维护为目标，按生产级标准处理。
+本项目使用 **SillySpec** 管理变更，采用文档驱动开发。SillySpec 是给 Agent 调用的 CLI 流程控制器：你通过 CLI 告诉它"我在哪"，它告诉你"下一步做什么"；你执行步骤，它校验产出、推进状态，人类只在关键决策点介入审批。要考虑多 agent 同时操作代码，代码随时可能变化。所有变更以稳定、可用、可维护为目标，按生产级标准处理。
+
+## 选道（动手前先对号入座）
+| 需求形态 | 走法 |
+|---|---|
+| 需求已含决策（改什么、成功标准说得清） | **轻量变更（默认快道）**：`flow start` → 直接干活 → `flow done`，全程 2 次协议调用 |
+| 需求不清晰 / 需要方案探索 | 头脑风暴预段：`run brainstorm --change <名>` → 完成后 `flow start --change <名>` 收编续跑（产物自动接管，不重复起草；design 以头脑风暴版为准） |
+| 大改动：跨模块取舍 / 需要 Wave 计划编排 / 多阶段治理 / 设计期人机对抗 | 完整流程：`run brainstorm → plan → execute → verify → archive` 五阶段（每阶段一次渲染 + 一次 --done 收口；local.yaml 开 stage.burst 时一次下发全部步骤说明书；verify 用 `verify-probes --init --draft` 机器预填） |
+| 代码已先写好（倒推收尾） | 不回头补 brainstorm/plan 装样子：`flow start --change <名> --input "<已做改动的描述＋成功标准>"` → `flow done`，实测门+测试绑定+patch 留档一步收口 |
+
+选道看流程形态需求，不看技术关键词——风险面由收口评审按证据（承诺词/diff 原语/盲维作答）判定。轻量→完整转道是用户决策：须征得用户同意并带 `--upgrade-thick`（同意门留痕，无 flag 拒跑）；轻量变更实测失败自动升厚。
+
+## 轻量变更（默认快道）
+`sillyspec flow start --change <名> --input "<需求>"` → 改代码、写测试（治理工件 CLI 机器起草，不用你写）→ `sillyspec flow done --change <名>`。
+
+`--input` 过门格式（清晰度门按此提取，缺「成功标准」条目会被拦下）：
+先写动机/背景；随后独立一行只写「成功标准：」；再每行一条「- <可验证标准>」。
+
+start 之后：按提示填 design.md 四节 AGENT 槽（做法/接口契约/边界并发四问/风险，每节至少一行，写「不适用：<理由>」也算答——空槽 flow done 拒收）；干活时逐条勾 tasks.md 的 task-NN（勾选是收口哨兵证据面）；收口前交付代码先用显式 pathspec 提交（patch 冻结面=baseline..HEAD 提交面，未提交的代码不进审计件）。
+
+## 常用命令速查
+- 看进度：`sillyspec progress show`；轻量变更恢复：重跑 `sillyspec flow start --change <名>`（输出恢复简报）或 `sillyspec flow status --change <名>`；完整流程恢复：`run <stage> --change <名>` 续跑。不直接 commit 半成品
+- 跨会话交接：`sillyspec handoff --change <名>`（生成交接块，新会话零背景可续）
+- 变更列表 / 状态：`sillyspec status`
+- 自检修复：`sillyspec doctor`
+- 知识库：`sillyspec knowledge search "<关键词>"`（命中知识 CLI 会自动注入 prompt，勿自行重复检索）
 
 ## 核心规则
 1. **禁止绕过本文件规则和 SillySpec 流程**。所有变更走 sillyspec 流程，不裸改裸提交。
-2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md）或现有代码依据，无依据不改。
-3. **新功能 / 大改动走完整流程**：`brainstorm → plan → execute → verify → archive`。
-4. **小修复 / 小调整走 quick**（= 无需要落盘的设计决策的改动，选道判据见第 6 条）：`sillyspec run quick`。
-5. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档。
-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 半成品。
-10. **实现完成后对照文档验收**（design.md / 模块文档），并检查是否影响已有测试。
-11. **非测试逻辑本身有误时，禁止改测试来"通过"**——修逻辑，不修测试。
-12. **git hook 拦截提交时禁止跳过**（如 `.husky/pre-push`），修复问题后再提交。
-13. **代码必须兼容 Windows / Linux / macOS**（路径 / 换行 / 并发都要顾）。
-14. **任务记录隔离**：永不重置 / reset / 清零已存在的 change；多个活跃 change 各自 `--change <名>` 隔离不重叠；quick 同一 QUICKLOG 按 ql-ID 条目追加，不冲突。
-15. **quicklog 结构化落盘**：末步 `--done` 用四参数 `--req/--cause/--solution/--result`（CLI 合成结构化 output 并自动提取标题/四段分行）；文件括注用 `--file-notes "path::注 || path2"`。骨架由 CLI 接管，`--done` 后按需核对即可，勿手拼模板。
-16. **代码可能随时在修改**（多 agent 并行），Edit 前重跑 + 查最新态；破坏性 git op 前先备份。
-17. **不奉承用户**，禁止"你说得对"类话术，直接给结论、依据、方案。
-18. **禁止目录级 git add / git add -A**（多会话共享仓）：.sillyspec/ 等目录里有并行会话的进行中文件与已提交文档，目录级暂存会夹带他者改动甚至误删已提交文件（2026-09-10 实证）。提交一律用显式 pathspec（git add -- 文件1 文件2），提交前 git status 核对暂存面只含本会话文件。
+2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md（如有））或现有代码依据，无依据不改。
+3. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档。
+4. **实证核验再收口**：触及 `src`/`test` 的改动，CLI 会在收口时亲自实测（实测失败阻断收口；纯 doc/配置自动跳过）。测试面按变更动态推断（本变更测试 ∪ FR 关联回归 ∪ import 依赖，runner 自项目结构推断——无需配置）；lint 走 `.sillyspec/local.yaml` 的 `commands.lint`。以落盘文件与测试结果为准，不信口头"已完成"。
+5. **非测试逻辑本身有误时，禁止改测试来"通过"**——修逻辑，不修测试。
+6. **git hook 拦截提交时禁止跳过**（如 `.husky/pre-push`），修复问题后再提交。
+7. **代码必须兼容 Windows / Linux / macOS**（路径 / 换行 / 并发都要顾）。
+8. **任务记录隔离**：永不重置 / reset / 清零已存在的 change；多个活跃 change 各自 `--change <名>` 隔离不重叠。
+9. **代码可能随时在修改**（多 agent 并行），Edit 前重跑 + 查最新态；破坏性 git op 前先备份。
+10. **会话启动先立身份**：`export SILLYSPEC_SESSION_ID=<唯一标识>`（如 agent 名+任务名）——多会话并行时 change 所有权判定（apply / cleanup / 归档对他会话活跃变更的接管拒绝）依赖此标识；缺省降级为 `anon@<主机名>` 机器级标识（只拦他机，同机并行不设防）。部分 harness 的 shell 状态不持久（env 随命令丢失），此时接管类命令每条显式带 flag：`sillyspec worktree apply <change> --session <唯一标识>`（`--session` 优先级高于 env）。
+11. **禁止目录级 git add / git add -A**（多会话共享仓）：目录级暂存会夹带并行会话的进行中文件甚至误删已提交文件。提交一律用显式 pathspec，且 **add 与 commit 用同一份清单**：`git commit -m "..." -- 文件1 文件2`——带 pathspec 的 commit 只提交这些路径，他侧已 staged 的条目既不被带走、也原样留给对方；裸 `git commit` 提交的是整个共享暂存区，他会话 add 过的文件会被一并扫入。核对暂存面固定用 `git diff --cached --name-only` 全量读取，禁用过滤式核对（过滤正是致盲原因）；核对与提交分开两条命令执行，不得链在同一命令里（链行没有拦截点）。安装了 commit-guard hook 的仓会对超声明面的 staged 文件警告（只警告不阻断）。
+12. **不奉承用户**，禁止"你说得对"类话术，直接给结论、依据、方案。