sillyspec 3.26.9 → 3.26.10

package/src/run/concurrent-detect.js

@@ -30,6 +30,28 @@ function normalizeGitPath(p) {
   return String(p).replace(/\\/g, '/')
 }
 
+/**
+ * 并发预检 ownFiles 锚点（2026-08-18 误归属修复）。
+ *
+ * 未声明会话（allowedFiles 空）维持旧口径 changedFiles ∪ baselineFiles——无声明即无归属信息，
+ * 收窄锚点会把本会话每次未声明的自身改动全误报他者。声明会话锚点 = baselineFiles ∪ allowedFiles
+ * （声明即归属）：窗口 diff（changedFiles）在多 agent 并发仓库可能含他者污染（ql-20260818-003
+ * 实证：并行会话窗口内改的文件被算进本会话 changedFiles 再被 ownFiles 自吞），超出声明集的
+ * 窗口新脏文件才作为 foreign 信号报出（= 他者或漏声明，歧义由 advisory 文案兜住）。
+ *
+ * 纯函数：不查盘不调 git，调用点（complete-handlers task-02 钩子）传入三个列表。
+ * @param {{ changedFiles?: string[], baselineFiles?: string[], allowedFiles?: string[] }} opts
+ * @returns {string[]} ownFiles 锚点集合（去重）
+ */
+export function resolveConcurrentAnchor({ changedFiles = [], baselineFiles = [], allowedFiles = [] } = {}) {
+  const arr = (x) => (Array.isArray(x) ? x : [])
+  const declared = arr(allowedFiles).map(normalizeGitPath).filter(Boolean)
+  if (declared.length === 0) {
+    return [...arr(changedFiles).map(normalizeGitPath), ...arr(baselineFiles).map(normalizeGitPath)]
+  }
+  return [...new Set([...arr(baselineFiles).map(normalizeGitPath), ...declared])]
+}
+
 /**
  * 检测工作树里的并发他者改动（非阻塞 advisory 用）。
  *

package/src/run/prompt.js

@@ -605,6 +605,46 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
     }
   }
 
+  // verify Step2「加载规范并锚定」worktree 基线锚点注入：execute 在 worktree 分支上 commit，
+  // verify 的 diff 对账基点 = worktree 分支的真实基点（git merge-base），不是主仓当前 HEAD。
+  // agent 拿不到基点时会拿主仓 HEAD / 旧 release commit 兜底——主仓在 execute 期间推进时
+  // （并行 session commit）会把别人的演进误判为本变更越权新增（2026-08-17 实录：误用 d192f89
+  // 而实际 merge-base 49ade71，第 6/7 条铁律被误判新增）。注入 fail-soft：worktree/分支/meta
+  // 读不到时降级为自查指引，绝不阻断 verify。
+  if (stageName === 'verify' && promptText.includes('{WORKTREE_BASELINE_INFO}')) {
+    let baselineInfo
+    try {
+      const { WorktreeManager } = await import('../worktree.js')
+      const wm = new WorktreeManager({ cwd })
+      const meta = changeName ? wm.getMeta(changeName) : null
+      const branch = meta?.branch || (changeName ? 'sillyspec/' + changeName : null)
+      const branchExists = branch
+        ? safeGit(cwd, ['rev-parse', '--verify', '--quiet', branch + '^{commit}']).error === null
+        : false
+      if (branchExists) {
+        const baseBranch = meta?.baseBranch || 'main'
+        const mergeBase = safeGit(cwd, ['merge-base', baseBranch, branch]).value
+        baselineInfo =
+          `- 本变更 worktree 分支：${branch}（存在）\n` +
+          (meta
+            ? `- worktree 基点（创建时锚定）：baseHash=${meta.baseHash || '未知'}，actualBaseHash=${meta.actualBaseHash || '未知'}（含 dirty overlay 后的 worktree 起点）\n`
+            : '- worktree meta 已不可读（可能已被 cleanup），用下方 merge-base 即可\n') +
+          `- ⚠️ diff 对账基点：\`git merge-base ${baseBranch} ${branch}\` = ${mergeBase || '（计算失败，手动跑上面命令）'}\n` +
+          `  不要用主仓当前 HEAD / 最近 release commit 当基点——主仓在 execute 期间可能已被并行 session 推进，用错基点会把别人的演进误判为本变更越权改动。\n` +
+          `- task review 的 base/head 引用分支上的 commit，逐 task 核验 diff 用 \`git diff <base>..<head>\`（分支 ref 若已被 cleanup 删除，hash 仍可直达，但不要主动删分支）。`
+      } else if (meta) {
+        baselineInfo =
+          '- 本变更 worktree meta 存在但分支不可达（可能已被 cleanup）：按主仓 git log 对照本变更各 commit 核验；task review 的 base/head 若悬空，在 verify-result.md 标注审计链风险。'
+      } else {
+        baselineInfo =
+          '- 本变更无 worktree（in-place / 纯文档变更 / worktree 已清理且 meta 不可读）：按主仓 git log 最近提交对照核验。'
+      }
+    } catch (e) {
+      baselineInfo = '（worktree 基线注入失败：' + e.message + '——diff 对账前先 git branch -a 查 sillyspec/<change> 分支并用 git merge-base <main> <branch> 自查基点，勿用主仓 HEAD 当基点）'
+    }
+    promptText = promptText.split('{WORKTREE_BASELINE_INFO}').join(baselineInfo)
+  }
+
   // 注入模块上下文（brainstorm/plan/execute 阶段，基于 Module Context Index）
   if (['brainstorm', 'plan', 'execute'].includes(stageName) && projectName) {
     const effectiveSpecBase = resolvePromptSpecBase(platformOpts, cwd)

package/src/run/quick-audit.js

@@ -58,7 +58,7 @@ export function printQuickAuditReview(review) {
     if (Array.isArray(review.docSyncHint.modules) && review.docSyncHint.modules.length > 0) {
       console.warn(`   涉及模块：${review.docSyncHint.modules.map(m => m.id).join(' · ')}（模块卡待同步，execute 场景详见 [docs-debt] 块）`)
     }
-    console.warn(`   quick 不强制文档同步，但欠账已记录（QUICKLOG reasons）。若改动触及接口/契约，建议顺手同步模块文档。`)
+    console.warn(`   quick 不强制文档同步，欠账已随本条 QUICKLOG「审计：」行落盘（可事后追溯）。若改动触及接口/契约，建议顺手同步模块文档。`)
   }
   if (review.docsCheckHint && review.docsCheckHint.invalid > 0) {
     console.warn(`\n📎 文档引用失效（docs check）：本次改动的文档含 ${review.docsCheckHint.invalid}/${review.docsCheckHint.total} 处失效 file:line 引用。`)

package/src/run/shared.js

@@ -579,7 +579,7 @@ export function isQuickMetadata(p, linkedChanges = []) {
 
 /**
  * quick 完成审计：对比 baseline 与实际变更。
- * @returns {{ status: 'safe'|'warning'|'blocked', reasons: string[], changedFiles: string[], newFiles: string[], deletedFiles: string[], baselineHit: string[], stagedTotal: number }}
+ * @returns {{ status: 'safe'|'warning'|'blocked', reasons: string[], changedFiles: string[], newFiles: string[], deletedFiles: string[], baselineHit: string[], stagedTotal: number, attributedFiles: string[], undeclaredFiles: string[] }}
  */
 /**
  * D-8 O-1 模块归属（2026-08-15 docs-signals-o12）：quick 欠账 hint 从"改了 N 文件"升级为
@@ -669,7 +669,7 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
   // stagedTotal：当前所有非 quick 元数据的未提交条目（含前序 baseline 残留）。
   // 与 changedFiles（扣 baseline 后的本轮新增）区分，供审计文案同时展示「本轮新增 vs 累计暂存」，
   // 避免叠加 quick 会话时把前序会话未提交文件误读为「本会话只动了 N 个」。
-  const result = { status: 'safe', reasons: [], changedFiles: [], newFiles: [], deletedFiles: [], baselineHit: [], stagedTotal: 0 }
+  const result = { status: 'safe', reasons: [], changedFiles: [], newFiles: [], deletedFiles: [], baselineHit: [], stagedTotal: 0, attributedFiles: [], undeclaredFiles: [] }
 
   try {
     // safeGit 带 -c safe.directory，避免 linked worktree/容器异 uid/挂载点下裸 `git status` 抛错被
@@ -879,8 +879,10 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
 
     // task-02: 同文件并发检测——allowedFile 在 baseline（他者改过）且当前 hash ≠ step1 hash（我也改了）
     // → commit 整文件 pathspec 会夹带他者 hunk，warn 给分离指引（advisory，不阻断，D-002）
+    // sameFileHits 提升到本层作用域：下方归属切分要把「baseline 声明文件且我也改了」并入
+    // attributedFiles（这类文件先被 isBaselineFile 跳过不进 changedFiles，但确属本会话产物）。
+    const sameFileHits = []
     if (allowedFiles.length > 0 && guard.allowedFilesHash) {
-      const sameFileHits = []
       for (const f of allowedFiles) {
         if (isBaselineFile(f) && guard.allowedFilesHash[f] !== undefined) {
           try {
@@ -899,6 +901,22 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
       }
     }
 
+    // 归属切分（2026-08-18 误归属修复，ql-20260818-003 实证）：窗口 diff（changedFiles）在多 agent
+    // 并发仓库分不清「本会话改」与「他者窗口内改」，他者文件会污染 QUICKLOG「文件：」行。声明即归属：
+    // allowedFiles 非空时 attributedFiles = 窗口∩声明 ∪ sameFileHits（同文件并发 = 我也改了），
+    // undeclaredFiles = 窗口−声明（他者或漏声明，供「审计：」行落盘追溯——不静默丢，防漏声明时
+    // 真实改动被挤走无痕）。未声明会话无归属信息不猜，维持全量口径（attributed = changed）。
+    const declaredNorm = new Set(allowedFiles.map(f => normalizeGitPath(f)))
+    if (declaredNorm.size > 0) {
+      const own = result.changedFiles.filter(f => declaredNorm.has(normalizeGitPath(f)))
+      for (const f of sameFileHits) if (!own.includes(f)) own.push(f)
+      result.attributedFiles = own
+      result.undeclaredFiles = result.changedFiles.filter(f => !declaredNorm.has(normalizeGitPath(f)))
+    } else {
+      result.attributedFiles = result.changedFiles
+      result.undeclaredFiles = []
+    }
+
     // --confirm 模式：展示 diff 并等待确认
     if (isConfirm && (result.status === 'warning' || result.status === 'blocked')) {
       console.log(`\n📋 quick 变更概览：`)

package/src/spec-sync.js

@@ -0,0 +1,319 @@
+/**
+ * CLI 直跑 spec 文件增量同步模块。
+ *
+ * Change 2026-08-17-spec-file-incremental-sync：daemon↔后端已有增量同步协议，但 CLI
+ * 直跑场景（本地 agent 直接跑 sillyspec 无 daemon）只有四件套直推到 documents 列。
+ * 本模块补齐 CLI 直跑的文件树增量同步：以服务器清单为锚，walk/hash/diff 后只推送
+ * 变化文件（add/update/delete/rename），无差异时短路不发请求。
+ *
+ * 复用 daemon 已验证的排除口径（UPLOAD_EXCLUDE_TOP_BASE / UPLOAD_PRUNE_NAMES_BASE），
+ * 与 daemon 共用同一套清单语义（base_version 乐观锁、conflict 提示但不阻塞）。
+ */
+
+import { createHash } from 'crypto';
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join, relative, sep } from 'path';
+
+// 与 sillyhub-daemon/src/spec-sync.ts 共用排除口径（task-07 / FR-06 / D-008@v2）：
+// .runtime（有点）/ runtime（无点）/ projects（本地环境文件）在顶层排除；
+// worktrees 在任意深度按 basename 剪枝（可能嵌在 .runtime/worktrees 下）。
+const UPLOAD_EXCLUDE_TOP_BASE = new Set(['.runtime', 'runtime', 'projects']);
+const UPLOAD_PRUNE_NAMES_BASE = new Set(['worktrees']);
+// ql-20260818-002：local.yaml 是本机连接配置（platform/mcp 段含 shpsync_ token），
+// 不上传——与服务器侧过滤（backend spec_workspace SERVER_EXCLUDED_FILENAMES）双侧
+// 对齐。服务器清单残留 local.yaml 行时，本地 walk 不含它 → 生成 delete op，
+// 服务器放行 delete 清存量（token 不落 landing 树、不随 bundle 跨机分发）。
+const UPLOAD_EXCLUDE_FILENAMES = new Set(['local.yaml']);
+
+function isUploadExcludedPath(relPath) {
+  const segs = relPath.split('/');
+  if (UPLOAD_EXCLUDE_TOP_BASE.has(segs[0] ?? '')) return true;
+  if (UPLOAD_EXCLUDE_FILENAMES.has(segs[segs.length - 1] ?? '')) return true;
+  return segs.some((s) => UPLOAD_PRUNE_NAMES_BASE.has(s));
+}
+
+function toPosix(p) {
+  return p.replace(/\\/g, '/');
+}
+
+function debugLog(msg) {
+  if (process.env.SILLYSPEC_DEBUG_SYNC) console.warn(msg);
+}
+
+function _hashBuffer(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * 单遍 walk 本地 .sillyspec 树。
+ *
+ * 返回 { path, absPath, mtimeMs } 列表；path 已统一为 POSIX。
+ * 不收集目录项（只关心文件）；命中排除规则的路径直接跳过不递归。
+ */
+export function walkSpecTree(specRoot) {
+  const out = [];
+  if (!existsSync(specRoot)) return out;
+
+  function recurse(dir) {
+    let names;
+    try {
+      names = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const abs = join(dir, name);
+      let st;
+      try {
+        st = statSync(abs);
+      } catch {
+        continue;
+      }
+      const relToRoot = toPosix(relative(specRoot, abs));
+      if (isUploadExcludedPath(relToRoot)) continue;
+      // pruneNames：任意深度按 basename 命中即不收集/不递归
+      if (UPLOAD_PRUNE_NAMES_BASE.has(name)) continue;
+
+      if (st.isDirectory()) {
+        recurse(abs);
+      } else if (st.isFile()) {
+        out.push({ path: relToRoot, absPath: abs, mtimeMs: st.mtimeMs });
+      }
+      // symlink / 其他：跳过
+    }
+  }
+
+  recurse(specRoot);
+  return out;
+}
+
+/**
+ * 计算本地文件哈希。
+ *
+ * 返回 { path, hash, mtime, absPath }（mtime 为 Unix 秒，供 os.utime；absPath
+ * 保留给 computeSpecOps 读 content 用，避免按相对路径回退错位）。
+ */
+export function hashFiles(entries) {
+  return entries.map((e) => {
+    const buf = readFileSync(e.absPath);
+    return {
+      path: e.path,
+      hash: _hashBuffer(buf),
+      mtime: Math.floor(e.mtimeMs / 1000),
+      absPath: e.absPath,
+    };
+  });
+}
+
+/**
+ * 根据服务器清单与本地文件差异生成 FileOp[]。
+ *
+ * 服务器清单格式：{ [path]: { hash, version, exists } }
+ * 本地文件格式：hashFiles 结果 { path, hash, mtime }
+ *
+ * 规则（与 daemon computeIncrementalOps 对齐）：
+ * - 本地有、服务器无 → add（base_version=0）
+ * - 服务器有 exists=true、本地无 → delete（base_version=服务器 version）
+ * - 服务器有 exists=false、本地无 → 不生成 delete（已软删）
+ * - 同路径 hash 不同 → update（base_version=服务器 version）
+ * - 服务器旧路径有、本地新路径有且 hash 相同 → rename（base_version=服务器旧路径 version）
+ */
+export function computeSpecOps(serverManifest, localFiles) {
+  const server = serverManifest || {};
+  const localMap = new Map(localFiles.map((f) => [f.path, f]));
+  const localSet = new Set(localMap.keys());
+
+  // 只拿服务器 exists=true 的行参与 diff；exists=false 视为已删除，不生成 delete
+  const serverPaths = Object.keys(server).filter((p) => server[p]?.exists !== false);
+  const serverSet = new Set(serverPaths);
+
+  // rename 检测：旧路径（服务器有、本地无）↔ 新路径（本地有、服务器无）hash 相同
+  const renames = [];
+  const consumedNew = new Set();
+  for (const oldPath of serverPaths) {
+    if (localSet.has(oldPath)) continue;
+    const cachedEntry = server[oldPath];
+    for (const newPath of localMap.keys()) {
+      if (serverSet.has(newPath)) continue;
+      if (consumedNew.has(newPath)) continue;
+      if (localMap.get(newPath).hash === cachedEntry.hash) {
+        renames.push({ oldPath, newPath });
+        consumedNew.add(newPath);
+        break;
+      }
+    }
+  }
+  const renamedOld = new Set(renames.map((r) => r.oldPath));
+  const renamedNew = new Set(renames.map((r) => r.newPath));
+
+  const ops = [];
+
+  for (const r of renames) {
+    ops.push({
+      op: 'rename',
+      path: r.oldPath,
+      new_path: r.newPath,
+      base_version: server[r.oldPath].version,
+    });
+  }
+
+  for (const p of serverPaths) {
+    if (renamedOld.has(p)) continue;
+    if (localSet.has(p)) {
+      const localEntry = localMap.get(p);
+      if (localEntry.hash !== server[p].hash) {
+        const content = readFileSync(localEntry.absPath ?? join('.', p)).toString('base64');
+        ops.push({
+          op: 'update',
+          path: p,
+          hash: localEntry.hash,
+          content,
+          base_version: server[p].version,
+          mtime: localEntry.mtime,
+        });
+      }
+    } else {
+      ops.push({
+        op: 'delete',
+        path: p,
+        base_version: server[p].version,
+      });
+    }
+  }
+
+  for (const p of localMap.keys()) {
+    if (renamedNew.has(p)) continue;
+    if (!serverSet.has(p)) {
+      const localEntry = localMap.get(p);
+      const content = readFileSync(localEntry.absPath ?? join('.', p)).toString('base64');
+      ops.push({
+        op: 'add',
+        path: p,
+        hash: localEntry.hash,
+        content,
+        base_version: 0,
+        mtime: localEntry.mtime,
+      });
+    }
+  }
+
+  return ops;
+}
+
+/**
+ * 从 ops 提取本次涉及的变更目录名集合（change_dirs 标注，D-005@v1）。
+ *
+ * 对每个 op 的 path（rename 含新旧 path），取 `changes/<name>/` 或
+ * `changes/archive/<name>/` 前缀分组的 key（去掉前缀、取第一段目录名），去重。
+ * 非 changes 前缀路径不进结果。best-effort，失败降级 []。
+ */
+export function extractChangeDirs(ops) {
+  const dirs = new Set();
+  for (const op of ops) {
+    collectChangeDir(dirs, op.path);
+    if (op.new_path) collectChangeDir(dirs, op.new_path);
+  }
+  return [...dirs];
+}
+
+function collectChangeDir(dirs, p) {
+  const norm = p.split(/[\\/]/).join('/');
+  let rest = null;
+  if (norm.startsWith('changes/')) {
+    rest = norm.slice('changes/'.length);
+  } else if (norm.startsWith('changes\\')) {
+    rest = norm.slice('changes\\'.length).replace(/\\/g, '/');
+  }
+  if (!rest) return;
+
+  if (rest.startsWith('archive/')) {
+    rest = rest.slice('archive/'.length);
+  }
+  const first = rest.split('/', 1)[0];
+  if (first && first !== 'archive' && !first.includes('/')) {
+    dirs.add(first);
+  }
+}
+
+/**
+ * 同步本地 .sillyspec 树到平台（CLI 直跑增量同步入口）。
+ *
+ * @param {string} specRoot - 本地 .sillyspec 目录绝对路径
+ * @param {object} platform - { url, token }
+ * @param {string} changeName - 当前变更名
+ * @returns {Promise<{synced: number, conflict?: boolean, serverVersions?: object}>}
+ */
+export async function syncSpecTree(specRoot, platform, changeName) {
+  if (!platform || !platform.url || !platform.token) {
+    debugLog('[spec-sync] 未连接平台（本地合法状态）；跳过 spec 树增量同步');
+    return { synced: 0 };
+  }
+
+  const manifestUrl = `${platform.url.replace(/\/$/, '')}/api/changes/-/spec-manifest`;
+  const syncUrl = `${platform.url.replace(/\/$/, '')}/api/changes/-/spec-sync`;
+
+  // 1. GET 服务器清单
+  let serverManifest = {};
+  try {
+    const res = await fetch(manifestUrl, {
+      headers: { Authorization: `Bearer ${platform.token}` },
+      signal: AbortSignal.timeout(10000),
+    });
+    if (!res.ok) {
+      debugLog(`[spec-sync] 拉取清单失败 ${res.status}: ${changeName}`);
+      return { synced: 0 };
+    }
+    const body = await res.json().catch(() => ({}));
+    serverManifest = body.files || {};
+  } catch (err) {
+    debugLog(`[spec-sync] 拉取清单异常（不影响进度）: ${changeName}: ${err.message}`);
+    return { synced: 0 };
+  }
+
+  // 2. walk/hash/diff
+  const entries = walkSpecTree(specRoot);
+  const localFiles = hashFiles(entries);
+  const ops = computeSpecOps(serverManifest, localFiles);
+
+  if (ops.length === 0) {
+    debugLog(`[spec-sync] 无差异，跳过同步: ${changeName}`);
+    return { synced: 0 };
+  }
+
+  // 3. POST ops
+  try {
+    const res = await fetch(syncUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${platform.token}`,
+      },
+      body: JSON.stringify({ ops }),
+      signal: AbortSignal.timeout(30000),
+    });
+    if (!res.ok) {
+      debugLog(`[spec-sync] 同步请求失败 ${res.status}: ${changeName}`);
+      return { synced: 0 };
+    }
+    const body = await res.json().catch(() => ({}));
+    if (body.conflict) {
+      console.warn(
+        `[spec-sync] 检测到冲突，请人工拍板。服务器版本: ${JSON.stringify(body.server_versions || {})}`
+      );
+      return { synced: 0, conflict: true, serverVersions: body.server_versions };
+    }
+    console.log(`[spec-sync] 已同步 ${ops.length} 个文件变更: ${changeName}`);
+    return { synced: ops.length };
+  } catch (err) {
+    debugLog(`[spec-sync] 同步异常（不影响进度）: ${changeName}: ${err.message}`);
+    return { synced: 0 };
+  }
+}
+
+export default {
+  walkSpecTree,
+  hashFiles,
+  computeSpecOps,
+  extractChangeDirs,
+  syncSpecTree,
+};

package/src/stages/archive.js

@@ -81,6 +81,7 @@ export const definition = {
 3. 如果标记缺失或重复 → 在 _module-map.yaml 中标记 needs_review: true
 
 #### 新建模块卡片模板
+一级标题格式 \`# <中文名>（<module-id>）\`——中文名从模块职责提炼 2-8 字，括号内保留 module-id 原样（sillyhub 平台解析识别用，与 scan 生成约定一致）。
 \`\`\`markdown
 ---
 schema_version: 1
@@ -88,7 +89,7 @@ doc_type: module-card
 module_id: <module-id>
 ---
 
-# <module-id>
+# <中文名>（<module-id>）
 
 ## 定位
 

package/src/stages/execute.js

@@ -843,15 +843,24 @@ ${workdirLines}
 
 ## 执行方式
 
-**每个任务必须由独立子代理执行，你不要自己写代码。**
+**默认每个任务由独立子代理执行，你不要自己写代码。**
 
-你的角色是调度者 + 审查者：
-1. 为每个任务启动一个子代理（Agent tool），同 Wave 内可并行
-2. 子代理完成后审查结果
+可选 batch（合并实现）：同一 Wave 内，若一组任务同时满足以下三个条件，可把它们合并为一个 batch（最多 3 个 task），交给单个子代理串行逐个完成实现：
+- 组内任意两个 task 的 allowed_paths 无交集（文件正交）
+- 组内任意两个 task 之间无 provides / expects_from 契约链（契约 task 禁止同批——串行实现会读到半成品，契约 task 由独立子代理并行处理或落在不同 Wave）
+- 组大小不超过 3 个 task
+
+任一条件不满足，该 task 走独立子代理（默认形态）；拿不准就不合并。无论独立还是 batch，实现一律由子代理完成，你不要自己写代码。
+
+你的角色是调度者 + 审查者（batch 只合并实现、不合并审查）：
+1. 为每个任务启动一个子代理（Agent tool），或按上述三条件把多个任务合并为一个 batch 子代理，同 Wave 内可并行
+2. 子代理完成后审查结果——batch 子代理只做实现与自验，task 审查、review.json 产出与 checkbox 勾选仍归你（主 agent），在子代理返回后逐 task 进行；审查 batch 报告时逐 task 对照 allowed_paths 检查改动文件清单有无越权
 3. 勾选 plan.md 中的 checkbox
 4. 记录改动文件和测试结果
 
 ${worktreeSection}${crossRepoCommitSection}${dispatchSection}
+**SillyHub 派发互斥**：SillyHub 派发模式下按派发段执行（一 Wave 一 mission），不按 batch 分组；batch 分组指导仅适用于本地 Agent tool 派发。
+
 ### 任务摘要（按需读取完整蓝图）
 为每个任务启动子代理时，**只需告知任务目标和蓝图文件路径，让子代理按需读取**：
 
@@ -863,6 +872,9 @@ ${taskSummary}
 3. 编码铁律：先读后写、TDD、不编造方法、只做蓝图里写的事、遵守边界处理规则、不超出 allowed_paths
 4. 如存在模块文档（.sillyspec/docs/*/modules/），按需读取涉及模块的 <module>.md 参考接口约定和数据流
 5. 任务含测试代码时，把下方「测试用例设计」整段复制进子代理 prompt，要求子代理按此设计测试用例
+6. **增量落盘与中断接手指引**：每完成一个可见产出（代码/测试/文档），立即写盘并执行一次最小验证（如语法检查、单跑相关测试）。工作过程中如被 429/API 配额/会话中断，应在最终回复里输出「已完成清单」（含文件路径、测试命令、当前卡点），不要只输出结论——主代理会依据磁盘产物和该清单判断哪些部分已完成，哪些需接手补做，避免重做已落盘的工作
+7. **任务边界铁律**：严格只实现本 task 的 \`allowed_paths\` 内文件；若 design.md/plan.md 明确指定了接口/回调/钩子接入位置，必须逐字遵守；不允许顺手实现其他 task 的内容（如 task-01 不要把 task-02 的接入也做了）。如发现必须改其他 task 文件才能继续，先回到主代理由主代理决定是否重分 Wave 或调整 plan，禁止子代理私自越界
+8. **batch 子代理协议**（仅当按「执行方式」节条件合并 batch 时附加进该子代理 prompt）：按 batch 内 task 顺序逐个完成实现闭环——读取 tasks/task-N.md → 实现 → 跑该 task 的 verify 命令 → 记录该 task 报告（改动文件清单 / verify 结果 / 卡点）→ 才开始下一个 task；最终回复输出逐 task 报告清单。禁止写 review.json、禁止勾选 plan.md checkbox——task 审查与勾选归主 agent，在子代理返回后逐 task 进行。越权即停：发现必须改 batch 内其他 task 或任何 batch 外 task 的 allowed_paths 文件 → 立即停止本 task 及后续，报告冲突文件与卡点，回主 agent 裁决（重分 Wave / 调整 plan / 回退独立子代理）。第 7 条任务边界铁律在 batch 语境下的「本 task」= 当前正在实现的 task
 
 {{include: testcase-design}}
 
@@ -887,7 +899,7 @@ ${contractInjection}${prototypeInjection}
 ${taskList}
 
 ### 调度要求
-1. **同一 Wave 内的任务必须并行启动子代理**（Wave 定义=无依赖可并行，不自行分析依赖关系；有依赖应在 plan.md 的不同 Wave 中）。
+1. **同一 Wave 的多个子代理（独立或 batch）必须并行启动，batch 内部串行**（batch 分组仅按文件正交 / 无契约链判定，不改变 Wave 依赖语义——Wave 定义=无依赖可并行；有依赖应在 plan.md 的不同 Wave 中）。
 2. **Reverse Sync**：子代理报告实现与 design.md 不一致时，先检查是代码错了还是文档有遗漏
 3. **不要频繁编译！** 编译很慢，只在以下情况运行：
    - 写了大量代码后需要验证语法正确性

package/src/stages/plan-postcheck.js

@@ -14,7 +14,7 @@ import { existsSync, readFileSync as _readFileSync, readdirSync, mkdtempSync, wr
 // frontmatter/字段正则（`^---\n`、`allowed_paths:\s*\n…`、`^goal:` 等）失配，报「缺 frontmatter
 // /缺字段」假错误（见缺陷 windows-python-crlf-taskcard）。读取时统一转 LF，一处覆盖全部正则。
 const readFileSync = (filePath, encoding) => _readFileSync(filePath, encoding).replace(/\r\n/g, '\n')
-import { join as pJoin } from 'path'
+import { join as pJoin, basename } from 'path'
 import { tmpdir } from 'os'
 import jsYaml from 'js-yaml'
 import { parseFileChangeList, pathMatches } from '../change-list.js'
@@ -1178,6 +1178,27 @@ export async function executePlanPostcheck(context) {
     console.log(`  ✅ design.md ${coverage.designFiles.length} 个文件全部被 task allowed_paths 覆盖`)
   }
 
+  // ── 1e. 阶段完成产物校验（plan stage contract）──
+  // plan 完成 gate 还会跑 stage-contract.validatePlanOutputs；为免「postcheck 通过 →
+  // stage gate 又报 module-impact 缺失/entry-point-wiring 未覆盖」的修一层撞一层，
+  // 在此把 stage contract 的 error/warning 也聚合进本轮输出。
+  const { validatePlanOutputs } = await import('../stage-contract.js')
+  if (typeof validatePlanOutputs === 'function') {
+    const contract = validatePlanOutputs(context.cwd, basename(changeDir), { specRoot })
+    if (contract.errors.length > 0) {
+      failures.push({
+        name: 'plan 阶段产物契约校验（stage-contract validatePlanOutputs）',
+        errors: contract.errors,
+        hint: '修复方式：补缺失产物（如 module-impact.md）、在 design.md 明示不改理由、或修正 task allowed_paths 覆盖 design.md 提及的入口文件。',
+      })
+    }
+    if (contract.warnings.length > 0) {
+      for (const w of contract.warnings) {
+        console.warn(`\n  ⚠️  ${w}`)
+      }
+    }
+  }
+
   // ── 聚合输出：一轮 --done 暴露全部失败项（坑6③）──
   if (failures.length > 0) {
     console.error(`\n❌ plan postcheck 失败（${failures.length} 类问题，已全部列出——一次修复后重跑，无需逐个迭代）：`)