sillyspec 3.25.11 → 3.26.0

package/src/stages/scan.js

@@ -191,24 +191,63 @@ export const definition = {
 2. 调用 \`sillyspec local detect\` 命令生成 local.yaml（该命令封装了纯 fs 项目类型嗅探：package.json→nodejs / pom.xml→maven / build.gradle→gradle / Makefile→make / 否则 generic，对应默认 commands）。**不要自行嗅探 package.json/pom.xml/build.gradle 等文件**——探测逻辑唯一归属 local-detect.js，本步骤只负责调用命令并报告结果。
 3. 该命令内部已处理：确保目录存在（mkdir -p）、已存在则跳过、原子写入（先写 tmp 再 rename）。
 4. 报告生成的 project.type 与 local.yaml 路径。
-
-### 输出格式参考（由 \`sillyspec local detect\` 自动产出）
+5. **detect 只生成 \`project.type\` / \`commands.{build,test,lint}\`（存在性核验驱动）/ \`test_strategy\` 骨架**，以下策略字段由你（agent）按项目实际情况补充——能在 package.json / lockfile / 构建文件 / CI 配置 / README 中找到依据就填，不确定留空或注释：
+   - \`commands.install\`：依赖安装命令（如 \`npm install\` / \`pnpm install\` / \`yarn\`）
+   - \`env\`：构建/测试所需环境变量键值（仅从 README / CI 配置 / .env.example 能确证的）
+   - \`test_strategy\`：detect 未注入时按项目实际补（full=全量 / module=只测变更模块 / skip=跳过测试）
+   - \`modules\`：模块路径根（module_paths，如 \`src/\` / \`packages/\`）
+   - \`known_failures\`：已知失败/不稳定测试清单（仅从 CI 历史 / 测试注释能确证的）
+
+### platform / dispatch / mcp 段检查（FR-08，可选补充）
+detect 不写这三段，由你按项目是否接入 sillyhub 平台决定是否补：
+- **platform 段缺失**（要接入 sillyhub 平台）→ 运行 \`sillyspec platform connect <url> <token>\` 自动写入（推荐）
+- **dispatch 段调参缺失**（启用 sillyhub 派发且需调优）→ 手填示例 \`probe_ttl_ms\` / \`poll_interval_ms\` / \`worker_timeout_ms\`（仅在你确知调优值时填，否则留默认）
+- **mcp 段缺失**（dispatch worker 走 MCP 协议连 sillyhub）→ 优先 \`sillyspec platform connect\`（同源假设，platform+mcp 同写）；不同源则手填 \`mcp.url\` / \`mcp.token\`，或设环境变量 \`SILLYHUB_MCP_URL\` / \`SILLYHUB_MCP_TOKEN\`（不入盘）
+
+### ⛔ 铁律（R-04，防编造）
+只写能从 package.json / lockfile / 构建文件 / CI 配置 / README 中确证的事实。不确定的字段一律留空或写注释占位，**绝不编造命令、路径或凭据**。commands 键的存在性已由 detect 核验，不要重复核验。
+
+### 输出格式参考（detect 自动产出骨架 + agent 补充策略字段）
 \`\`\`yaml
 # SillySpec 本地配置（自动生成，可手动修改）
 project:
   type: nodejs  # nodejs/maven/gradle/make/generic
 
+# commands 键存在性由 detect 核验 package.json scripts 驱动：
+# 有 scripts.build 才写 build，有 scripts.test 才写 test，有 scripts.lint 才写 lint
+# （仅 test/lint 无 build 的项目，build 键不写）
 commands:
-  build: "npm run build"
+  build: "npm run build"   # 仅 scripts.build 存在时由 detect 写入
   test: "npm test"
   lint: "npm run lint"
+  # install: "npm install"   # ← agent 补：依赖安装命令
 
 # 测试策略：full=全量测试, module=只测变更模块, skip=跳过测试
 test_strategy: module
+
+# ↓ 以下为 agent 按项目实际补充的策略字段（不确定留空或注释）
+# env:                       # ← agent 补：构建/测试所需环境变量
+#   NODE_ENV: test
+# modules:                    # ← agent 补：模块路径根（module_paths）
+#   - src/
+# known_failures:             # ← agent 补：已知失败/不稳定测试
+#   - "test/flaky.test.mjs"
+
+# ↓ 外部连接段（接入 sillyhub 平台时补，detect 不写）
+# platform:                   # ← sillyspec platform connect <url> <token> 写入
+#   url: ...
+#   token: ...
+# mcp:                        # ← platform connect 同源写入 或 手填 或 env(SILLYHUB_MCP_URL/TOKEN)
+#   url: ...
+#   token: ...
+# dispatch:                   # ← agent 按需调参（确知调优值才填）
+#   probe_ttl_ms: 30000
+#   poll_interval_ms: 2000
+#   worker_timeout_ms: 60000
 \`\`\`
 
 ### 输出
-local.yaml 生成结果（已存在/已生成 + project.type）`,
+local.yaml 生成结果（已存在/已生成 + project.type + agent 补充的策略字段摘要）`,
       outputHint: 'local.yaml 生成状态',
       optional: false
     },
@@ -538,7 +577,7 @@ INDEX.md 维护索引，格式（每行：关键词1|关键词2 → [条目名](
 7. 确认所有文档都写入 \`{DOCS_ROOT}/\`（spec-root 下），**而非源码目录下的 .sillyspec/**
 8. 检查是否出现 tool_use_error 或 API Error 未恢复
 9. 检查 7 份文档 header 是否包含 author 和 created_at
-10. 检查 local.yaml 中 commands 是否在 package.json scripts 中真实存在，不存在的必须标记 unavailable
+10. 复查 detect 核验结果——commands 键已由 detect 核验 scripts 存在性，agent 无需重复核验或标 unavailable，仅确认 local.yaml 与 detect 产出一致
 
 ### ⛔ API 错误处理
 - 遇到 API Error 529（服务过载）或 rate_limit 时，**停止当前操作并报告**，不要自动重试

package/src/stages/verify.js

@@ -66,7 +66,7 @@ export const definition = {
    - 如果存在 P0/P1 unresolved/blocking 决策，验证结论不能为 PASS
    - 如果发现 superseded 决策被下游引用，标记为 ⚠️ stale decision reference
 3. 加载项目信息：\`cat .sillyspec/projects/*.yaml 2>/dev/null\`
-4. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`（构建命令、测试命令、lint 命令等）
+4. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`（构建命令、测试命令、lint 命令等）若 local.yaml 不存在，先 \`sillyspec local detect\` 生成骨架再读取
 5. 加载代码规范：\`cat .sillyspec/docs/<project>/scan/CONVENTIONS.md 2>/dev/null\`
    - 测试现状：\`cat .sillyspec/docs/<project>/scan/TESTING.md 2>/dev/null\`（了解既有测试约定与覆盖范围，验收时对照）
    - 技术债清单：\`cat .sillyspec/docs/<project>/scan/CONCERNS.md 2>/dev/null\`（🔴/🟡 区域；本次变更若触碰须在 verify-result.md 标注）
@@ -164,7 +164,7 @@ export const definition = {
       prompt: `运行代码质量扫描（测试实测统一由 CLI 对账执行，本步不重复手动跑全量）。
 
 ### 操作
-1. 读取 \`.sillyspec/local.yaml\` 获取构建、测试和 lint 命令
+1. 读取 \`.sillyspec/local.yaml\` 获取构建、测试和 lint 命令若 local.yaml 不存在，先 \`sillyspec local detect\` 生成骨架再读取
 2. **不要手动重复跑 commands.test**——CLI 会在最终 --done 时统一执行一次（按变更命中模块子集），本步再跑 = 与 CLI 对账重复耗时（实测 198s×2）。如为提前发现实现问题，可对变更模块做**针对性快速冒烟**（可选，非必需）：
    - Maven：\`mvn test -pl <变更模块> -am\`（仅编译变更模块及其依赖）
    - Gradle：\`./gradlew :<模块>:test\`

package/src/sync.js

@@ -8,9 +8,10 @@
  * HTTP 请求：Node.js 原生 fetch（Node 22+）
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { resolvePlatformSpecDir } from './progress.js';
+import { safeGit } from './git-helper.js';
 
 // sync 是 best-effort（网络失败只 warn）：平台指针失效时不抛，跳过平台、回退本地。
 function safePlatformSpecDir(cwd) {
@@ -107,6 +108,23 @@ function parseSimpleYaml(content) {
   return result;
 }
 
+/**
+ * 解析推送者身份（user）：区分多用户，供 push 时 X-SillySpec-User 标识（design D-004）。
+ * 优先级：显式参数 > git user.name（与 quicklog / prompt <git-user> 同口径）> process.env.USER
+ * （Unix）/ USERNAME（Windows）。Best effort：全失败返回 null，调用方据此决定是否写 user 字段
+ * （缺字段等价于「未知推送者」，平台侧自行兜底，不报错）。
+ */
+function resolvePlatformUser(cwd, explicitUser) {
+  if (typeof explicitUser === 'string' && explicitUser.trim()) {
+    return explicitUser.trim();
+  }
+  // 回退 1：git user.name（safeGit 失败返回 null，不抛）
+  const gitUser = safeGit(cwd, ['config', 'user.name']).value;
+  if (gitUser) return gitUser;
+  // 回退 2：环境变量（USER=Unix / USERNAME=Windows；跨平台兼容 CLAUDE.md #13）
+  return process.env.USER || process.env.USERNAME || null;
+}
+
 // ── HTTP 辅助 ──
 
 async function fetchJson(url, options = {}) {
@@ -136,6 +154,37 @@ async function fetchJson(url, options = {}) {
   }
 }
 
+/**
+ * 带状态码的 fetch：不吞非 2xx（fetchJson 在 !res.ok 时返回 null 丢状态，无法区分 409 冲突）。
+ * 返回 { ok, status, body }：body 尽力 JSON.parse（平台冲突响应带 progress JSON，读回给调用方）。
+ * 仅 sync() 的 progress POST 使用（识别 base_ts 乐观锁冲突，D-015 / task-09）；其余调用仍走 fetchJson。
+ */
+async function fetchJsonWithStatus(url, options = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { ...options, signal: controller.signal });
+    const text = await res.text().catch(() => '');
+    let body = null;
+    if (text) {
+      try { body = JSON.parse(text); } catch { body = null; }
+    }
+    if (!res.ok) {
+      console.warn(`[sync] ${options.method || 'GET'} ${url} → ${res.status} ${text.slice(0, 200)}`);
+    }
+    return { ok: res.ok, status: res.status, body };
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      console.warn(`[sync] ${url} 请求超时 (${REQUEST_TIMEOUT_MS}ms)`);
+    } else {
+      console.warn(`[sync] ${url} 请求失败: ${err.message}`);
+    }
+    return { ok: false, status: 0, body: null };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // ── SyncManager ──
 
 export class SyncManager {
@@ -146,8 +195,11 @@ export class SyncManager {
   /**
    * 连接 SillyHub 平台。
    * 保存配置到 .sillyspec/local.yaml，发送 ping 验证连接。
+   * @param {string} url - 平台地址
+   * @param {string} token - 认证 token
+   * @param {string} [user] - 推送者身份（可空，回退 git user.name / env，见 resolvePlatformUser）
    */
-  async connect(url, token) {
+  async connect(url, token, user) {
     // 验证连接
     const healthUrl = `${url.replace(/\/+$/, '')}/api/health`;
     const result = await fetchJson(healthUrl);
@@ -157,6 +209,9 @@ export class SyncManager {
     }
     console.log(`[sync] 平台连接成功: ${url}`);
 
+    // 解析推送者身份（D-004）：显式 > git user.name > env；全失败留空不写 user 字段
+    const resolvedUser = resolvePlatformUser(this.cwd, user);
+
     // 写入 local.yaml
     const config = readLocalYaml(this.cwd);
     config.platform = {
@@ -164,6 +219,13 @@ export class SyncManager {
       token,
       last_connected: new Date().toISOString(),
     };
+    if (resolvedUser) {
+      config.platform.user = resolvedUser;
+    }
+    // mcp 段同源假设（design §7.4）：复用 platform 的 url/token；用户已手填 mcp 段则保留不覆盖（R-09）
+    if (!config.mcp) {
+      config.mcp = { url: url.replace(/\/+$/, ''), token };
+    }
     writeLocalYaml(this.cwd, config);
   }
 
@@ -194,8 +256,9 @@ export class SyncManager {
 
   /**
    * 增量同步变更的 progress 状态到平台。
-   * 读取 ProgressManager.read() 的数据，POST 到平台。
-   * 同步完成后更新 changes 表的 platform_last_sync 字段。
+   * 读取 ProgressManager.serializeForSync() 的六表 JSON，POST 到平台。
+   * 元字段（user/base_ts/pushed_at）走 HTTP header，body 保持裸 JSON（D-015，sillyhub 老版零回归）。
+   * 同步完成后更新 changes 表的 platform_last_sync 字段；409 冲突读回平台最新 JSON（task-12 完整冲突处理）。
    */
   async sync(changeName) {
     const platform = this._getPlatform();
@@ -216,29 +279,58 @@ export class SyncManager {
       return { synced: 0, errors: [`变更不存在: ${changeName}`] };
     }
 
-    // 读取 progress 数据（通过导入 ProgressManager 动态调用）
+    // 读取 progress 数据（serializeForSync 六表裸 JSON，task-02 / D-005@v2，替代 read() 聚合视图）
     let progressData;
     try {
       const { ProgressManager } = await import('./progress.js');
       const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
-      progressData = pm.read(this.cwd, changeName);
+      progressData = pm.serializeForSync(this.cwd, changeName);
     } catch (err) {
       console.warn(`[sync] 读取 progress 失败 (${changeName}): ${err.message}`);
       return { synced: 0, errors: [`读取 progress 失败: ${err.message}`] };
     }
+    if (progressData === null) {
+      console.warn(`[sync] 变更无进度数据 (无活跃进度): ${changeName}`);
+      return { synced: 0, errors: [`变更无进度数据: ${changeName}`] };
+    }
+
+    // 元字段走 HTTP header（D-015 / task-09）：body 保持裸六表 JSON，sillyhub 老版忽略 header 零回归
+    const headers = {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${platform.token}`,
+    };
+    const pushedAt = new Date().toISOString();
+    if (platform.user) headers['X-SillySpec-User'] = platform.user; // 推送者身份（task-08 local.yaml platform.user）
+    const baseTs = progressData.changes && progressData.changes[0] && progressData.changes[0].last_synced_platform_ts;
+    if (baseTs) headers['X-SillySpec-Base-Ts'] = baseTs; // base_ts 乐观锁（NULL=首次同步不设，平台接受首次 push）
+    headers['X-SillySpec-Pushed-At'] = pushedAt; // 平台存 last_pushed_at，作下次其他用户 push 的 base_ts 比对基准
 
-    // POST 到平台
+    // POST 到平台（带状态码版本：识别 409 冲突，读回平台最新 JSON）
     const syncUrl = `${platform.url}/api/changes/${changeName}/progress`;
-    const result = await fetchJson(syncUrl, {
+    const res = await fetchJsonWithStatus(syncUrl, {
       method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${platform.token}`,
-      },
+      headers,
       body: JSON.stringify(progressData),
     });
 
-    if (!result) {
+    if (!res.ok) {
+      // 409 = base_ts 乐观锁冲突（平台已有更新）；读回平台最新 JSON 供 task-12 完整冲突处理
+      if (res.status === 409) {
+        console.warn(`[sync] 冲突: ${changeName} 平台已有更新（base_ts 过期），请 platform status / resolve 处理`);
+        // 平台 409 响应 { conflict:true, platform_progress, last_pushed_at }，platform_progress 即平台最新 progress JSON
+        const platformProgress = res.body && res.body.platform_progress ? res.body.platform_progress : res.body;
+        const platformLastPushedAt = (res.body && res.body.last_pushed_at) || null;
+        // 本地脏度（progressData 是 serializeForSync 输出，changes[0] 含 last_local_modified_ts）
+        const localModified = (progressData.changes && progressData.changes[0] && progressData.changes[0].last_local_modified_ts) || null;
+        // 写冲突文件（task-12 / D-002）：base_ts=本次 push 的 base，强制提示走 resolve
+        const conflictPath = this._writeConflictFile(changeName, {
+          base_ts: baseTs || null,
+          local_modified_ts: localModified,
+          platform_last_pushed_at: platformLastPushedAt,
+          platform_progress: platformProgress,
+        });
+        return { synced: 0, errors: [`冲突: ${changeName}`], conflict: true, platform_progress: platformProgress, conflictPath };
+      }
       return { synced: 0, errors: [`同步请求失败: ${changeName}`] };
     }
 
@@ -381,6 +473,310 @@ export class SyncManager {
     const config = readLocalYaml(this.cwd);
     return config.platform || null;
   }
+
+  /**
+   * 写冲突文件 .runtime/sync-conflict-<change>.json（task-12 / D-002 / D-008 / D-010 / FR-05）。
+   * push 409 与 pull 本地脏度双向冲突命中时调用，强制提示用户走 platform resolve 三选一。
+   * 绝不字段级 auto-merge；文件在 .runtime 下不入版本控制（gitignore）。
+   * @param {string} changeName
+   * @param {{base_ts?: string|null, local_modified_ts?: string|null, platform_last_pushed_at?: string|null, platform_progress?: object|null}} info
+   * @returns {string|null} 冲突文件路径（specDir 不可达返回 null）
+   */
+  _writeConflictFile(changeName, info = {}) {
+    const specDir = safePlatformSpecDir(this.cwd);
+    if (!specDir) return null;
+    const runtimeDir = join(specDir, '.runtime');
+    if (!existsSync(runtimeDir)) mkdirSync(runtimeDir, { recursive: true });
+    const conflictPath = join(runtimeDir, `sync-conflict-${changeName}.json`);
+    const payload = {
+      change: changeName,
+      base_ts: info.base_ts ?? null,
+      local_modified_ts: info.local_modified_ts ?? null,
+      platform_last_pushed_at: info.platform_last_pushed_at ?? null,
+      created_at: new Date().toISOString(),
+      // 额外存平台最新 progress JSON，供 resolve --take-platform 直接 import（无需再 pull）
+      platform_progress: info.platform_progress ?? null,
+    };
+    writeFileSync(conflictPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+    return conflictPath;
+  }
+
+  /**
+   * 读取冲突文件（task-13 resolve / task-14 status 用）。
+   * @returns {object|null} 冲突文件内容；无文件返回 null
+   */
+  readConflictFile(changeName) {
+    const specDir = safePlatformSpecDir(this.cwd);
+    if (!specDir) return null;
+    const conflictPath = join(specDir, '.runtime', `sync-conflict-${changeName}.json`);
+    if (!existsSync(conflictPath)) return null;
+    try {
+      return JSON.parse(readFileSync(conflictPath, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * 删除冲突文件（resolve 完成后清理，task-13 用）。
+   * @returns {boolean} 是否删除（文件不存在返回 false）
+   */
+  clearConflictFile(changeName) {
+    const specDir = safePlatformSpecDir(this.cwd);
+    if (!specDir) return false;
+    const conflictPath = join(specDir, '.runtime', `sync-conflict-${changeName}.json`);
+    if (!existsSync(conflictPath)) return false;
+    try { unlinkSync(conflictPath); return true; }
+    catch { return false; }
+  }
+
+  /**
+   * 两级 pull 第一级：轻量 change 列表（design §7 / D-001 / D-006 / task-06 / FR-01 / FR-03）。
+   * GET {url}/api/changes → [{ name, current_stage, last_pushed_at, last_pusher }]（兼容 { changes: [...] } 包裹）。
+   * CLI 比对本地决定哪些 change 需更新，控制 pull 性能（不每次全量拉单 change JSON）。
+   * Best Effort：未连接 / 网络失败 console.warn 不抛，返回 PullListResult { ok, changes, reason? }。
+   * @returns {Promise<{ok: boolean, changes: Array<object>, reason?: string}>}
+   */
+  async pullList() {
+    const platform = this._getPlatform();
+    if (!platform) {
+      debugLog('[sync] 未连接平台（本地合法状态）；pullList 跳过');
+      return { ok: false, changes: [], reason: '未连接平台' };
+    }
+
+    const listUrl = `${platform.url}/api/changes`;
+    const result = await fetchJson(listUrl, {
+      headers: { Authorization: `Bearer ${platform.token}` },
+    });
+
+    if (result === null) {
+      console.warn(`[sync] 拉取变更列表失败: ${listUrl}`);
+      return { ok: false, changes: [], reason: '拉取变更列表失败' };
+    }
+
+    // 兼容两种响应形态：裸数组 / { changes: [...] } 包裹（sillyhub 后端实际 API 而定）
+    const changes = Array.isArray(result) ? result : (Array.isArray(result.changes) ? result.changes : []);
+    return { ok: true, changes, reason: undefined };
+  }
+
+  /**
+   * 两级 pull 第二级：按需拉平台单 change 完整 JSON 并 import 重建本地 DB 行（design §7 / D-001 / D-006 / D-014 / task-07 / FR-01 / FR-03 / FR-09）。
+   * GET {url}/api/changes/{name}/progress → 平台权威 JSON（serializeForSync 六表 + 顶层 last_pushed_at）。
+   * 本地脏度比对：last_local_modified_ts > last_synced_platform_ts（本地有未同步改动）且 平台 last_pushed_at 更新 → 冲突，不 import 返回 conflict:true（task-12 负责写 sync-conflict 文件）。
+   * 无冲突 → import() 重建 DB 行；import 后本地 base_ts/脏度重置为 pushed_at（D-013）。
+   * Best Effort：未连接 / 网络失败 / 404 console.warn 不抛，返回 PullResult { ok, imported, conflict, reason? }。
+   * @param {string} changeName
+   * @param {{force?: boolean}} [opts] - force 跳过本地脏度冲突检测直接 import（task-12 resolve --take-platform 用）
+   * @returns {Promise<{ok: boolean, imported: boolean, conflict: boolean, reason?: string}>}
+   */
+  async pull(changeName, opts = {}) {
+    const { force = false } = opts;
+    const platform = this._getPlatform();
+    if (!platform) {
+      debugLog('[sync] 未连接平台（本地合法状态）；pull 跳过');
+      return { ok: false, imported: false, conflict: false, reason: '未连接平台' };
+    }
+    if (!changeName) {
+      console.warn('[sync] pull 需要指定变更名称 (changeName)');
+      return { ok: false, imported: false, conflict: false, reason: '未指定变更名称' };
+    }
+
+    // 1. GET 平台完整 progress JSON
+    const progressUrl = `${platform.url}/api/changes/${encodeURIComponent(changeName)}/progress`;
+    const result = await fetchJson(progressUrl, {
+      headers: { Authorization: `Bearer ${platform.token}` },
+    });
+    if (result === null) {
+      // sillyhub 未就绪 / 404 / 网络失败均 fetchJson 返回 null → Best Effort 降级
+      console.warn(`[sync] 拉取变更进度失败: ${changeName}（sillyhub 未就绪或变更不存在）`);
+      return { ok: false, imported: false, conflict: false, reason: '拉取变更进度失败' };
+    }
+
+    // 平台响应：serializeForSync 六表 + 顶层 last_pushed_at（兼容 { progress: {...} } 包裹）
+    const platformProgress = (result && result.project && result.changes) ? result : (result.progress || result);
+    const platformPushedAt = (result && result.last_pushed_at) || null;
+
+    // 2. 本地脏度比对（非 force 时）：本地脏 AND 平台更新 → 冲突
+    if (!force) {
+      let localLastModified = null;
+      let localLastSynced = null;
+      try {
+        const { ProgressManager } = await import('./progress.js');
+        const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+        const row = pm._ensureDB(this.cwd).getDb().prepare(
+          'SELECT last_local_modified_ts, last_synced_platform_ts FROM changes WHERE name = ?'
+        ).get(changeName);
+        if (row) {
+          localLastModified = row.last_local_modified_ts;
+          localLastSynced = row.last_synced_platform_ts;
+        }
+      } catch (err) {
+        console.warn(`[sync] 读取本地脏度失败 (${changeName}): ${err.message}`);
+      }
+      const localDirty = localLastModified && localLastSynced && localLastModified > localLastSynced;
+      const platformNewer = platformPushedAt && (!localLastSynced || platformPushedAt > localLastSynced);
+      if (localDirty && platformNewer) {
+        console.warn(`[sync] pull 冲突: ${changeName} 本地有未同步改动且平台已更新（base_ts 过期），请 platform resolve 处理`);
+        // 写冲突文件（task-12 / D-002）：强制提示，绝不 auto-merge
+        const conflictPath = this._writeConflictFile(changeName, {
+          base_ts: localLastSynced,
+          local_modified_ts: localLastModified,
+          platform_last_pushed_at: platformPushedAt,
+          platform_progress: platformProgress,
+        });
+        return { ok: false, imported: false, conflict: true, reason: `冲突: ${changeName} 本地脏且平台更新`, conflictPath };
+      }
+    }
+
+    // 3. 无冲突（或 force）→ import 平台 JSON 重建本地 DB 行
+    try {
+      const { ProgressManager } = await import('./progress.js');
+      const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+      const importInput = { ...platformProgress, pushed_at: platformPushedAt || new Date().toISOString() };
+      pm.import(this.cwd, importInput, changeName);
+      console.log(`[sync] 已拉取变更进度: ${changeName}`);
+      return { ok: true, imported: true, conflict: false, reason: undefined };
+    } catch (err) {
+      console.warn(`[sync] import 失败 (${changeName}): ${err.message}`);
+      return { ok: false, imported: false, conflict: false, reason: `import 失败: ${err.message}` };
+    }
+  }
+
+  /**
+   * 冲突解决三选一（task-13 / D-002 / D-010 / D-013 / FR-05）。
+   * 读 task-12 写的 sync-conflict-<change>.json，按 mode 处理后必清冲突文件防累积（R-04 / constraints）。
+   *
+   * 三种语义（design 生命周期契约表）：
+   * - keep-local：本地 DB 不变，仅把 last_synced_platform_ts（base_ts）推进到平台 last_pushed_at
+   *   （表示「已知平台最新，本地为准」），用户后续手动 platform sync push 本地。
+   * - take-platform：用冲突文件存的 platform_progress 调 import() 覆盖本地（保隔离状态，D-013 重置脏度）。
+   * - abort：本地 DB 与 base_ts 均不变，仅清冲突文件（放弃本次同步）。
+   *
+   * 无冲突文件 → ok:false resolved:false（index.js 据此提示「无可解决冲突」）。
+   * 绝不字段级 auto-merge（D-002）。
+   * @param {string} changeName
+   * @param {'keep-local'|'take-platform'|'abort'} mode
+   * @returns {Promise<{ok: boolean, resolved: boolean, mode?: string, reason: string}>}
+   */
+  async resolve(changeName, mode) {
+    const cf = this.readConflictFile(changeName);
+    if (!cf) {
+      return { ok: false, resolved: false, reason: `无可解决冲突: ${changeName}（无 sync-conflict 文件）` };
+    }
+    const platformPushedAt = cf.platform_last_pushed_at || null;
+
+    if (mode === 'keep-local') {
+      // base_ts 推进到平台最新 last_pushed_at；本地 DB 不 import（用户本地为准，后续手动 push）
+      try {
+        const { ProgressManager } = await import('./progress.js');
+        const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+        const db = pm._ensureDB(this.cwd).getDb();
+        db.prepare('UPDATE changes SET last_synced_platform_ts = ? WHERE name = ?')
+          .run(platformPushedAt, changeName);
+      } catch (err) {
+        return { ok: false, resolved: false, reason: `keep-local 更新 base_ts 失败: ${err.message}` };
+      }
+      this.clearConflictFile(changeName);
+      return { ok: true, resolved: true, mode: 'keep-local', reason: '保留本地，base_ts 已推进到平台最新（后续请 platform sync push 本地）' };
+    }
+
+    if (mode === 'take-platform') {
+      // 用冲突文件的 platform_progress 调 import 覆盖本地（保隔离：import 不覆盖 isolation_*）
+      if (!cf.platform_progress) {
+        return { ok: false, resolved: false, reason: '冲突文件缺 platform_progress，无法 take-platform（建议先 platform pull）' };
+      }
+      try {
+        const { ProgressManager } = await import('./progress.js');
+        const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+        pm.import(this.cwd, { ...cf.platform_progress, pushed_at: platformPushedAt || new Date().toISOString() }, changeName);
+      } catch (err) {
+        return { ok: false, resolved: false, reason: `take-platform import 失败: ${err.message}` };
+      }
+      this.clearConflictFile(changeName);
+      return { ok: true, resolved: true, mode: 'take-platform', reason: '已用平台进度覆盖本地' };
+    }
+
+    if (mode === 'abort') {
+      // 本地 DB 与 base_ts 均不变，仅清冲突文件（放弃本次同步，下次 push/pull 会重新检测）
+      this.clearConflictFile(changeName);
+      return { ok: true, resolved: true, mode: 'abort', reason: '放弃本次同步，本地不变' };
+    }
+
+    return { ok: false, resolved: false, reason: `未知 resolve 模式: ${mode}（--keep-local / --take-platform / --abort）` };
+  }
+
+  /**
+   * 扫描 .runtime/sync-conflict-*.json 列出未决冲突（task-14 / D-002 / D-010 / FR-05）。
+   * 只读 + 容错：损坏文件跳过不崩（constraints）。供 collectStatus / platform status 展示。
+   * @returns {Array<{change: string, created_at: string|null, path: string}>}
+   */
+  listConflictFiles() {
+    const specDir = safePlatformSpecDir(this.cwd);
+    if (!specDir) return [];
+    const runtimeDir = join(specDir, '.runtime');
+    if (!existsSync(runtimeDir)) return [];
+    let files = [];
+    try { files = readdirSync(runtimeDir); }
+    catch { return []; }
+    const conflicts = [];
+    for (const f of files) {
+      if (!f.startsWith('sync-conflict-') || !f.endsWith('.json')) continue;
+      const filePath = join(runtimeDir, f);
+      try {
+        const cf = JSON.parse(readFileSync(filePath, 'utf8'));
+        conflicts.push({
+          change: cf.change || f.replace(/^sync-conflict-/, '').replace(/\.json$/, ''),
+          created_at: cf.created_at || null,
+          path: filePath,
+        });
+      } catch {
+        // 损坏文件跳过不崩（constraints：容错）
+      }
+    }
+    return conflicts;
+  }
+
+  /**
+   * 扩展 status（task-14 / FR-05）：连接信息 + 落后标记 + 未决冲突列表。
+   * 只读展示，不修改任何进度（constraints）。未连接返回 base.status（connected:false，behind/conflicts 空）。
+   * 连接时调 pullList（轻量 GET）拿平台各 change last_pushed_at，比对本地 last_synced_platform_ts
+   * 标记本地可能落后；扫描 sync-conflict-*.json 列未决冲突。网络失败 listFailed=true 不崩。
+   * @returns {Promise<{connected: boolean, url?: string, lastSync?: string|null, behind: Array<object>, conflicts: Array<object>, listFailed: boolean}>}
+   */
+  async collectStatus() {
+    const base = this.status();
+    if (!base.connected) {
+      return { ...base, behind: [], conflicts: [], listFailed: false };
+    }
+    const behind = [];
+    let listFailed = false;
+    const list = await this.pullList();
+    if (list.ok) {
+      for (const ch of list.changes) {
+        const name = typeof ch === 'string' ? ch : ch.name;
+        if (!name) continue;
+        const platformPushedAt = (typeof ch === 'object' && (ch.last_pushed_at || ch.last_active)) || null;
+        if (!platformPushedAt) continue;
+        let localSynced = null;
+        try {
+          const { ProgressManager } = await import('./progress.js');
+          const pm = new ProgressManager({ specDir: safePlatformSpecDir(this.cwd) });
+          const row = pm._ensureDB(this.cwd).getDb().prepare('SELECT last_synced_platform_ts FROM changes WHERE name = ?').get(name);
+          if (row) localSynced = row.last_synced_platform_ts;
+        } catch {
+          // 本地无该 change 记录 / DB 不可达 → 不算落后，跳过
+        }
+        // 仅本地有同步基准（last_synced_platform_ts）且平台更新晚于本地 → 落后
+        if (localSynced && platformPushedAt > localSynced) {
+          behind.push({ name, local_synced: localSynced, platform_pushed_at: platformPushedAt });
+        }
+      }
+    } else {
+      listFailed = true;
+    }
+    const conflicts = this.listConflictFiles();
+    return { ...base, behind, conflicts, listFailed };
+  }
 }
 
 // ── CLI 入口函数 ──
@@ -422,6 +818,27 @@ export async function checkApproval(changeName, cwd) {
   return new SyncManager(cwd).checkApproval(changeName);
 }
 
+// task-11 / D-006 / D-009 / FR-03：手动 pull 便捷导出（index.js platform pull 子命令用，
+// 与自动 triggerPull 共用 SyncManager.pull 实例方法，行为一致）
+export async function pull(changeName, opts, cwd) {
+  return new SyncManager(cwd).pull(changeName, opts);
+}
+
+// 两级 pull 第一级（轻量 change 列表），platform pull 无 --change 时先拉列表再按需 pull
+export async function pullList(cwd) {
+  return new SyncManager(cwd).pullList();
+}
+
+// task-13 / D-002 / D-010 / D-013 / FR-05：冲突解决三选一（index.js platform resolve 子命令用）
+export async function resolve(changeName, mode, cwd) {
+  return new SyncManager(cwd).resolve(changeName, mode);
+}
+
+// task-14 / FR-05：扩展 status（连接信息 + 落后标记 + 未决冲突列表），index.js platform status 用
+export async function collectStatus(cwd) {
+  return new SyncManager(cwd).collectStatus();
+}
+
 // TBD-hub-api: approve/reject 端点路径与请求体以 SillyHub 仓库实际 API 为准；
 // 对齐时只改本函数（_submitApproval），无需动 approve/reject 入口。
 /**

package/src/task-review.js

@@ -611,6 +611,35 @@ export function generateExecuteRunId() {
  * @param {{ runtimeRoot: string, changeName: string }} opts
  * @returns {string|null} runId（exec- 前缀），无则 null
  */
+/**
+ * 扫描 execute-runs/，返回 mtime 最新且真正含 tasks/ 子目录的 runId。
+ *
+ * 专治 execute run marker 漂移（prompt-control-debt.md gate-atom-a）：generateExecuteRunId 只写
+ * marker 字符串、run 目录由 ensureTaskReviewDir 在写 review.json 时才建，marker 漂到「尚未建目录 /
+ * 未写任何 task review」的新 run 后，旧 run 里齐备的 review.json 全部失联。resolveLatestExecuteRunId
+ * 见 marker 非空即原样返回（不校验目录），接不住这种漂移；本函数无视 marker、只看真实目录内容，
+ * 供 enforceReviewJsonGate 在 marker 指向的 run 缺 tasks/ 时兜底重定位，避免误报「review.json 不存在」。
+ * 全部 run 都无 tasks/（真没写 review）返回 null——调用方维持原阻断，不误放行。
+ *
+ * @param {{ runtimeRoot: string }} opts
+ * @returns {string|null} 含 tasks/ 的最新 runId，无则 null
+ */
+export function resolveLatestExecuteRunIdWithTasks({ runtimeRoot }) {
+  try {
+    const runsDir = join(runtimeRoot, 'execute-runs')
+    if (!existsSync(runsDir)) return null
+    const entries = readdirSync(runsDir)
+      .map(e => ({ e, p: join(runsDir, e) }))
+      .filter(x => { try { return statSync(x.p).isDirectory() } catch { return false } })
+      .filter(x => { try { return statSync(join(x.p, 'tasks')).isDirectory() } catch { return false } })
+      .map(x => ({ e: x.e, mtime: statSync(x.p).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime)
+    return entries.length > 0 ? entries[0].e : null
+  } catch {
+    return null
+  }
+}
+
 export function resolveLatestExecuteRunId({ runtimeRoot, changeName }) {
   const marker = join(runtimeRoot, `current-execute-run-id-${changeName}`)
   try { if (existsSync(marker)) { const c = readFileSync(marker, 'utf8').trim(); if (c) return c } } catch {}