sillyspec 3.28.7 → 3.28.9

package/src/index.js

@@ -6,7 +6,7 @@
  * 只负责两件事：init（安装命令模板）和 setup（安装 MCP 工具）。
  * 状态管理通过 sillyspec.db（SQLite）完成，使用 `sillyspec progress` 命令。
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, unlinkSync } from 'fs';
 import { writeAtomicSync } from './fs-atomic.js';
 import { basename, dirname, extname, join, resolve, isAbsolute, sep, relative } from 'path';
 import { safeGit, git } from './git-helper.js';
@@ -60,6 +60,9 @@ SillySpec CLI — 规范驱动开发工具包
              --force-rescan              覆盖已有 scan 文档保护
              --diff [--base <commit>] [--full] [--report]   scan 文档 vs 源码漂移清单（纯只读）
              （子命令: sillyspec scan diff 等价 --diff）
+             refresh [--project <名>] [--force] [--json]   增量刷新①拍：门控+受影响文档手术工单
+             refresh --done [--docs a.md,b.md] [--force]    增量刷新②拍：内容比对+per-doc 基线推进+postcheck
+             （检出极限：refresh 只覆盖带 file:line 引用的检出项，不声称文档与源码一致）
     archive: --confirm                   归档确认（必须）
     auto:    --mode <模式>               显式指定流程模式
     平台:    --runtime-root <path> / --workspace-id <id> / --scan-run-id <id>
@@ -70,6 +73,9 @@ SillySpec CLI — 规范驱动开发工具包
     check | repair [--apply] | validate | reset [--stage X] |
     batch --total N --completed M [--failed F] [--skipped K] | batch --status
 
+  sillyspec wt-commit [--change <名>] -m <信息> [--pathspec-from-file <f>] -- <path...>
+                                      worktree 内 per-task 串行化提交（文件锁排队 + 强制显式 pathspec，
+                                      防 add -A 卷入并行兄弟 WIP；worktree 内可省 --change，从 cwd 推断）
   sillyspec worktree <cmd>     git worktree 隔离管理（execute 阶段相关）
     create <change> [--base <branch>]   创建隔离 worktree
     apply <change> [--check-only]       校验并应用变更到主工作区
@@ -198,7 +204,7 @@ async function main() {
 
   // E22：重路径统一加载（轻路径 --version/help 已早退，未付此税）。
   const { ProgressManager, resolvePlatformSpecDir, resolvePlatformOpts } = await import('./progress.js');
-  const { didYouMean, assertSafeChangeName, assertDatedChangeName, resolveSpecDir, detectWorktreeSpecDrift } = await import('./run/shared.js');
+  const { didYouMean, assertSafeChangeName, assertDatedChangeName, resolveSpecDir, detectWorktreeSpecDrift, detectCwdInsideWorktree } = await import('./run/shared.js');
 
   // 解析全局选项
   let json = false;
@@ -221,13 +227,13 @@ async function main() {
       json = true;
     } else if (args[i] === '--save') {
       saveWorkflowRunFlag = true;
-    } else if (args[i] === '--dir' && args[i + 1]) {
+    } else if (args[i] === '--dir' && args[i + 1] && !args[i + 1].startsWith('--')) {
       targetDir = resolve(args[i + 1]);
       i++;
-    } else if (args[i] === '--spec-dir' && args[i + 1]) {
+    } else if (args[i] === '--spec-dir' && args[i + 1] && !args[i + 1].startsWith('--')) {
       specDir = resolve(args[i + 1]);
       i++;
-    } else if (args[i] === '--tool' && args[i + 1]) {
+    } else if (args[i] === '--tool' && args[i + 1] && !args[i + 1].startsWith('--')) {
       // 多值支持：逗号分隔（--tool claude,codex）与重复 flag（--tool a --tool b）都收集进数组
       for (const v of args[i + 1].split(',')) {
         const t = v.trim();
@@ -237,18 +243,21 @@ async function main() {
     } else if (args[i] === '--no-skills') {
       // init 专属：跳过 skills 复制段（吞进变量，不透传 filteredArgs）
       noSkills = true;
-    } else if (args[i] === '--workspace-id' && args[i + 1]) {
+    } else if (args[i] === '--workspace-id' && args[i + 1] && !args[i + 1].startsWith('--')) {
       // 平台模式专属 flag（init 落平台指针用；--runtime-root/--scan-run-id 保持在
       // filteredArgs 由 runCommand 解析，init 侧只需要 workspaceId 作为平台信号 + runtimeRoot）
       platformWorkspaceId = args[i + 1];
       filteredArgs.push(args[i], args[i + 1]);
       i++;
-    } else if (args[i] === '--runtime-root' && args[i + 1]) {
+    } else if (args[i] === '--runtime-root' && args[i + 1] && !args[i + 1].startsWith('--')) {
       platformRuntimeRoot = resolve(args[i + 1]);
       filteredArgs.push(args[i], args[i + 1]);
       i++;
     } else if (args[i] === '--interactive' || args[i] === '-i') {
       interactive = true;
+    } else if (args[i] === '--allow-worktree-cwd') {
+      // worktree cwd 硬拦逃生门：默认阻止在 .sillyspec/.runtime/worktrees/* 内跑 CLI，
+      // 此 flag 显式放行（坑 worktree-cwd-silent-split）
     } else if (args[i] === '--list' || args[i] === '-l') {
       filteredArgs.push('--list');
     } else {
@@ -311,6 +320,22 @@ async function main() {
     process.exit(1);
   }
 
+  // ── worktree cwd 硬拦（坑 worktree-cwd-silent-split，2026-08-29 用户实证）──
+  // Bash cwd 残留让 agent 两次误在 worktree 内跑 sillyspec：status 类完全静默、进度写进
+  // worktree 副本 .sillyspec 与主仓进度库分裂。守卫在命令分发前拦截，--dir 显式指向主仓
+  // 或 --allow-worktree-cwd 逃生门放行；wt-commit 命令豁免（子代理 workdir=worktree 内合法）。
+  if (!args.includes('--allow-worktree-cwd') && command !== 'wt-commit') {
+    const guardDir = args.includes('--dir') ? dir : process.cwd();
+    const wtInfo = detectCwdInsideWorktree(guardDir);
+    if (wtInfo) {
+      console.error(`\n❌ 当前在隔离 worktree 内（${wtInfo.changeName}）：${guardDir}`);
+      console.error(`   主仓根：${wtInfo.mainRepoRoot}`);
+      console.error('   SillySpec 进度库只存在于主仓，worktree 内跑会产生分裂进度（坑 worktree-cwd-silent-split）。');
+      console.error('   修复：cd 到主仓根后重跑，或用 --dir <主仓根>，或用 --allow-worktree-cwd 强制放行。');
+      process.exit(2);
+    }
+  }
+
   switch (command) {
     case 'init':
       await (await import('./init.js')).cmdInit(dir, { tool, tools: toolValues.length > 0 ? toolValues : null, interactive, specDir, noSkills, platformOpts: (platformWorkspaceId || platformRuntimeRoot) ? { workspaceId: platformWorkspaceId, runtimeRoot: platformRuntimeRoot } : null });
@@ -324,10 +349,10 @@ async function main() {
       const progDir = specDir ? dir : resolveEffectiveDir(dir);
       const subCommand = filteredArgs[1];
       const stageIdx = filteredArgs.indexOf('--stage');
-      const stage = stageIdx >= 0 && filteredArgs[stageIdx + 1] ? filteredArgs[stageIdx + 1] : null;
+      const stage = stageIdx >= 0 && filteredArgs[stageIdx + 1] && !String(filteredArgs[stageIdx + 1]).startsWith("--") ? filteredArgs[stageIdx + 1] : null;
       // 解析 --change 参数
       const progChangeIdx = args.indexOf('--change');
-      const progChangeName = progChangeIdx >= 0 && args[progChangeIdx + 1] ? args[progChangeIdx + 1] : null;
+      const progChangeName = progChangeIdx >= 0 && args[progChangeIdx + 1] && !String(args[progChangeIdx + 1]).startsWith("--") ? args[progChangeIdx + 1] : null;
       // 与 run 入口同源消毒（防路径穿越；progress 下游 completeStage 写 history 文件名拼 change 名）
       if (progChangeName) assertSafeChangeName(progChangeName, '--change 变更名');
 
@@ -469,7 +494,7 @@ async function main() {
       // 只读查询，不依赖 worktree、不写状态（D-002@v1）。
       const gateStage = filteredArgs[1];
       const gateChangeIdx = args.indexOf('--change');
-      const gateChange = gateChangeIdx >= 0 && args[gateChangeIdx + 1] ? args[gateChangeIdx + 1] : null;
+      const gateChange = gateChangeIdx >= 0 && args[gateChangeIdx + 1] && !String(args[gateChangeIdx + 1]).startsWith("--") ? args[gateChangeIdx + 1] : null;
       if (!gateStage || gateStage.startsWith('-') || !gateChange) {
         console.error('用法: sillyspec gate <stage> --change <name> [--json]\n  stage: brainstorm | plan | execute | verify | archive | ...');
         process.exit(2);
@@ -529,7 +554,7 @@ async function main() {
       // 单项事实核验（machine-interface v1）：查询变更某一 facet 的真实状态，返回结构化 data。
       const facet = filteredArgs[1];
       const deriveChangeIdx = args.indexOf('--change');
-      const deriveChange = deriveChangeIdx >= 0 && args[deriveChangeIdx + 1] ? args[deriveChangeIdx + 1] : null;
+      const deriveChange = deriveChangeIdx >= 0 && args[deriveChangeIdx + 1] && !String(args[deriveChangeIdx + 1]).startsWith("--") ? args[deriveChangeIdx + 1] : null;
       if (!facet || facet.startsWith('-') || !deriveChange) {
         console.error('用法: sillyspec derive <facet> --change <name> [--json]\n  facet: execute-evidence | verify-test | task-reviews | artifacts');
         process.exit(2);
@@ -587,7 +612,7 @@ async function main() {
       }
       const rwVal = (flag) => {
         const i = filteredArgs.indexOf(flag);
-        return i >= 0 && filteredArgs[i + 1] ? filteredArgs[i + 1] : null;
+        return i >= 0 && filteredArgs[i + 1] && !String(filteredArgs[i + 1]).startsWith("--") ? filteredArgs[i + 1] : null;
       };
       const rwChange = rwVal('--change');
       const rwTask = rwVal('--task');
@@ -645,6 +670,63 @@ async function main() {
       }
       break;
     }
+    case 'task': {
+      // task 级进行中状态标记（2026-09-12 驾驭第十四批②，用户实证「中断续跑时半成品无主，
+      // 主代理接管审查负担重」）：开工/完工各一条命令落 .runtime/task-progress/<change>/<task-NN>.json
+      // （startedAt + note），list 带陈旧标红（>2h 视为中断遗留——续跑时主代理据此点名接管审查，
+      // 不再靠翻 git 工作区猜半成品）。轻量 marker：不进 DB、不设门禁（状态可见性工具，非流程卡点）。
+      const taskSub = filteredArgs[1];
+      if (!taskSub || ['help', '--help', '-h'].includes(taskSub)) {
+        console.log(`用法:
+  sillyspec task start --change <名> --task task-NN [--note "一句话在做什么"]
+  sillyspec task finish --change <名> --task task-NN
+  sillyspec task list --change <名>
+task 进行中状态标记：开工/完工落 .runtime/task-progress/，list 标红 >2h 中断遗留（接管审查点名用）`);
+        break;
+      }
+      const tChangeIdx = filteredArgs.indexOf('--change');
+      const tChange = tChangeIdx >= 0 && filteredArgs[tChangeIdx + 1] && !String(filteredArgs[tChangeIdx + 1]).startsWith("--") ? filteredArgs[tChangeIdx + 1] : null;
+      const tTaskIdx = filteredArgs.indexOf('--task');
+      const tTask = tTaskIdx >= 0 && filteredArgs[tTaskIdx + 1] && !String(filteredArgs[tTaskIdx + 1]).startsWith("--") ? filteredArgs[tTaskIdx + 1] : null;
+      const tNoteIdx = filteredArgs.indexOf('--note');
+      const tNote = tNoteIdx >= 0 && filteredArgs[tNoteIdx + 1] && !String(filteredArgs[tNoteIdx + 1]).startsWith("--") ? filteredArgs[tNoteIdx + 1] : null;
+      if (!tChange) { console.error('❌ 缺 --change <变更名>'); process.exit(2); }
+      if (taskSub !== 'list') {
+        if (!tTask || !/^task-\d+$/.test(tTask)) { console.error('❌ --task 格式应为 task-NN'); process.exit(2); }
+      }
+      const tSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const tRuntime = join(tSpecBase, '.runtime');
+      const tDir = join(tRuntime, 'task-progress', tChange);
+      if (taskSub === 'start') {
+        mkdirSync(tDir, { recursive: true });
+        writeFileSync(join(tDir, `${tTask}.json`), JSON.stringify({
+          task: tTask, change: tChange, note: tNote || '', startedAt: new Date().toISOString(),
+        }, null, 2) + '\n');
+        console.log(`📌 ${tTask} 已标记进行中${tNote ? '（' + tNote + '）' : ''}——完工时 sillyspec task finish --change ${tChange} --task ${tTask}`);
+      } else if (taskSub === 'finish') {
+        try { unlinkSync(join(tDir, `${tTask}.json`)); console.log(`✅ ${tTask} 进行中标记已清除（完工）`); }
+        catch { console.log(`ℹ️ ${tTask} 无进行中标记（已完工或从未 start）`); }
+      } else if (taskSub === 'list') {
+        if (!existsSync(tDir)) { console.log(`ℹ️ 无 ${tChange} 的进行中 task 标记`); break; }
+        const entries = readdirSync(tDir).filter(f => f.endsWith('.json'));
+        if (entries.length === 0) { console.log(`ℹ️ 无进行中标记（全部完工）`); break; }
+        console.log(`📋 ${tChange} 进行中 task（${entries.length} 个）——中断遗留接管审查点名用：`);
+        let stale = 0;
+        for (const f of entries.sort()) {
+          try {
+            const m = JSON.parse(readFileSync(join(tDir, f), 'utf8'));
+            const ageMin = Math.round((Date.now() - new Date(m.startedAt).getTime()) / 60000);
+            const isStale = ageMin > 120;
+            if (isStale) stale++;
+            console.log(`   ${isStale ? '🔴' : '🟢'} ${m.task}: 开始于 ${m.startedAt}（${ageMin >= 60 ? Math.floor(ageMin / 60) + 'h' + ageMin % 60 + 'm' : ageMin + 'm'} 前）${m.note ? '——' + m.note : ''}${isStale ? ' ⚠️ 超过 2h，疑似中断遗留（接管者：对照 task 卡 + git 工作区半成品审查）' : ''}`);
+          } catch { console.log(`   ⚠️ ${f} 标记损坏（忽略）`); }
+        }
+        if (stale > 0) console.log(`   共 ${stale} 个疑似中断遗留——主代理接管时逐一审查（半成品无主的痛点出口）`);
+      } else {
+        console.error(`❌ 未知子命令「${taskSub}」（start | finish | list）`); process.exit(2);
+      }
+      break;
+    }
     case 'backfill-reviews': {
       // 手动补 task（reopen execute / 直接实现）缺 review.json 的官方入口（坑 verify-archive-flow-pitfalls 坑2）。
       // 复用 generateTaskReviewDrafts（execute --done 同源兜底，幂等、fail-open）：据 git diff base..head + working-tree
@@ -657,7 +739,7 @@ async function main() {
       // verdict——手算 hash、手抄 diff 清单是纯错误面，gate 校验的恰是这些字段。与草稿互补：
       // 草稿补「缺失」，adopt 修「已存在但 mechanics 错/缺」，verdict 原样保留。
       const brChangeIdx = args.indexOf('--change');
-      const brChange = brChangeIdx >= 0 && args[brChangeIdx + 1] ? args[brChangeIdx + 1] : null;
+      const brChange = brChangeIdx >= 0 && args[brChangeIdx + 1] && !String(args[brChangeIdx + 1]).startsWith("--") ? args[brChangeIdx + 1] : null;
       const brAdopt = args.includes('--adopt');
       if (!brChange) {
         console.error('用法: sillyspec backfill-reviews --change <name> [--adopt] [--json] [--spec-dir <path>]\n  缺失 review.json → 生成 cannot_verify 草稿（解 archive 客观完成度阻断）\n  --adopt → 已存在 review.json 的 base/head/changedFiles/diffPaths 等 mechanics 字段一键重算代填（verdict 保留；统一 commit 模式 diffPaths=task 卡 allowed_paths）');
@@ -739,7 +821,7 @@ async function main() {
       const wsArgs = filteredArgs.slice(2);
       const wsFlag = (name) => {
         const i = wsArgs.indexOf(name);
-        return i >= 0 && wsArgs[i + 1] ? wsArgs[i + 1] : null;
+        return i >= 0 && wsArgs[i + 1] && !String(wsArgs[i + 1]).startsWith("--") ? wsArgs[i + 1] : null;
       };
       const { workspaceAdd, workspaceRemove, workspaceStatus } = await import('./workspace.js');
       if (wsSub === 'add') {
@@ -838,7 +920,9 @@ async function main() {
         const childArgs = m[1].trim().split(/\s+/);
         console.log(`🤖 next --apply 代跑：sillyspec ${childArgs.join(' ')}\n`);
         const { spawnSync } = await import('node:child_process');
-        const r = spawnSync(process.execPath, [join(__dirname, '..', 'bin', 'sillyspec.js'), '--dir', dir, ...childArgs], { stdio: 'inherit' });
+        const { fileURLToPath } = await import('node:url');
+        // ESM 无 __dirname（ql-20260911-029：此处曾直接引用，--apply 常态路径必 ReferenceError）
+        const r = spawnSync(process.execPath, [fileURLToPath(new URL('../bin/sillyspec.js', import.meta.url)), '--dir', dir, ...childArgs], { stdio: 'inherit' });
         process.exit(r.status === null ? 1 : r.status);
       }
       if (json) {
@@ -868,7 +952,7 @@ async function main() {
       // 通用自动 git 在多会话仓是历史重灾区，故收窄到这一处。
       if (args.includes('--apply')) {
         const apChangeIdx = args.indexOf('--change');
-        const apChange = apChangeIdx >= 0 && args[apChangeIdx + 1] ? args[apChangeIdx + 1] : null;
+        const apChange = apChangeIdx >= 0 && args[apChangeIdx + 1] && !String(args[apChangeIdx + 1]).startsWith("--") ? args[apChangeIdx + 1] : null;
         if (!apChange) {
           console.error('用法: sillyspec commit --apply --change <名>\n  只限归档语境（changes.status=archived 或 current_stage=archive）执行归档产物提交');
           process.exit(2);
@@ -947,7 +1031,7 @@ async function main() {
       // --init 顺带生成 verify-result.md 七章节骨架（探针结果预填；结论留「待填」——gate 找
       // 不到 PASS/FAIL 即判不过，骨架不能直接过门）。已存在不覆盖。
       const vpChangeIdx = args.indexOf('--change');
-      const vpChange = vpChangeIdx >= 0 && args[vpChangeIdx + 1] ? args[vpChangeIdx + 1] : null;
+      const vpChange = vpChangeIdx >= 0 && args[vpChangeIdx + 1] && !String(args[vpChangeIdx + 1]).startsWith("--") ? args[vpChangeIdx + 1] : null;
       const vpInit = args.includes('--init');
       if (!vpChange) {
         console.error('用法: sillyspec verify-probes --change <name> [--init] [--json] [--spec-dir <path>]\n  跑机械探针（TODO 标记/测试覆盖/API 对账/删除对账）输出 markdown；--init 生成 verify-result.md 骨架（探针预填，已存在不覆盖）');
@@ -1031,6 +1115,18 @@ async function main() {
             console.log(`📄 已补齐缺失槽段（不触碰既有正文）: ${vpAdded.added.join('、')}`)
           }
         }
+        // 2026-09-14-acceptance-test-matrix：探针 7 验收×测试覆盖矩阵骨架幂等补段——
+        // verify-result.md 已存在但缺「#### 探针 7」段且 applicable（有 TaskCard）时补矩阵
+        // 骨架（学 backfillMissingEvidenceSlots 形态，不触既有正文；判定/证据槽 fail-closed
+        // 由 verify 门禁负责）。本变更自举：verify-result.md 先于特性存在的存量走此补段。
+        try {
+          const { ensureAcceptanceMatrixSection } = await import('./verify-probes.js')
+          const vpMatrix = ensureAcceptanceMatrixSection(vpReportPath, vpResult.probe7)
+          if (vpMatrix.added) {
+            try { await mirrorInitArtifact(vpReportPath, 'verify-result.md', readFileSync(vpReportPath, 'utf8')) } catch { /* 镜像失败不阻断 */ }
+            console.log(`🧩 探针 7 验收×测试覆盖矩阵骨架段已补齐（判定=四选一/证据两槽待填，命中≠判定；不触碰既有正文）: ${vpReportPath}${vpPlatformNote}`)
+          }
+        } catch { /* 矩阵补段失败不阻断 --init */ }
         // P0-1（noai-ir-roadmap §3）两件机械预填，均幂等 fail-soft：
         //   ①决策追踪矩阵机械半边——D→FR→task 链自 decisions.md × tasks/*.md frontmatter
         //     结构化字段构建，Evidence/状态两列留 agent 逐格复核；
@@ -1071,9 +1167,9 @@ async function main() {
       // stage-reviews 路径）、--kill=清在途记录+平台处置指引（处置权在人）。薄壳：全部逻辑在
       // src/review-dispatch.js（可测核心），此处只做 flag 解析与退出码。
       const rdChangeIdx = args.indexOf('--change');
-      const rdChange = rdChangeIdx >= 0 && args[rdChangeIdx + 1] ? args[rdChangeIdx + 1] : null;
+      const rdChange = rdChangeIdx >= 0 && args[rdChangeIdx + 1] && !String(args[rdChangeIdx + 1]).startsWith("--") ? args[rdChangeIdx + 1] : null;
       const rdStageIdx = args.indexOf('--stage');
-      const rdStage = rdStageIdx >= 0 && args[rdStageIdx + 1] ? args[rdStageIdx + 1] : null;
+      const rdStage = rdStageIdx >= 0 && args[rdStageIdx + 1] && !String(args[rdStageIdx + 1]).startsWith("--") ? args[rdStageIdx + 1] : null;
       const rdStatus = args.includes('--status');
       const rdKill = args.includes('--kill');
       const rdMode = rdKill ? 'kill' : rdStatus ? 'status' : 'create';
@@ -1124,9 +1220,9 @@ async function main() {
       // 模块文档 sidecar 同步命令化（2026-09-09 刀批）：diff 归属模块 → sidecar 追加变更索引行 +
       // 卡 updated_at 戳——机械部分 CLI 代算，卡片正文语义更新仍归 agent/归档流程。幂等。
       const mdsChangeIdx = args.indexOf('--change');
-      const mdsChange = mdsChangeIdx >= 0 && args[mdsChangeIdx + 1] ? args[mdsChangeIdx + 1] : null;
+      const mdsChange = mdsChangeIdx >= 0 && args[mdsChangeIdx + 1] && !String(args[mdsChangeIdx + 1]).startsWith("--") ? args[mdsChangeIdx + 1] : null;
       const mdsNoteIdx = args.indexOf('--note');
-      const mdsNote = mdsNoteIdx >= 0 && args[mdsNoteIdx + 1] ? args[mdsNoteIdx + 1] : null;
+      const mdsNote = mdsNoteIdx >= 0 && args[mdsNoteIdx + 1] && !String(args[mdsNoteIdx + 1]).startsWith("--") ? args[mdsNoteIdx + 1] : null;
       if (!mdsChange) {
         console.error('用法: sillyspec module-docs-sync --change <name> [--note "一句话"] [--json]\n  diff 归属模块 → sidecar 追加变更索引行 + 卡 updated_at 戳（幂等；卡片正文语义更新仍归 agent）');
         process.exit(2);
@@ -1151,7 +1247,7 @@ async function main() {
       // 手排 Wave 与拓扑比对不一致需手改；依赖方向硬拦（plan-postcheck）落地后给一条零手写出路。
       // depMap 与 postcheck 同源（collectTaskDepMap）→ topoSortWaves → 重写 Wave 段 + 同步任务总表 W 列。
       const pawChangeIdx = args.indexOf('--change');
-      const pawChange = pawChangeIdx >= 0 && args[pawChangeIdx + 1] ? args[pawChangeIdx + 1] : null;
+      const pawChange = pawChangeIdx >= 0 && args[pawChangeIdx + 1] && !String(args[pawChangeIdx + 1]).startsWith("--") ? args[pawChangeIdx + 1] : null;
       const pawDryRun = args.includes('--dry-run');
       if (!pawChange) {
         console.error('用法: sillyspec plan-adopt-waves --change <name> [--dry-run] [--json] [--spec-dir <path>]\n  把 plan.md 的 Wave 段一键重排为 depends_on 拓扑分组（同步任务总表 W 列；--dry-run 只看不写）');
@@ -1196,7 +1292,7 @@ async function main() {
       // archive 模块影响矩阵骨架（2026-08-21 审计第三批 D3）：文件×模块归属按 _module-map.yaml
       // paths 前缀匹配预填（机械），影响类型/review 标记留 <!--TODO-->（语义）。已存在不覆盖。
       const miChangeIdx = args.indexOf('--change');
-      const miChange = miChangeIdx >= 0 && args[miChangeIdx + 1] ? args[miChangeIdx + 1] : null;
+      const miChange = miChangeIdx >= 0 && args[miChangeIdx + 1] && !String(args[miChangeIdx + 1]).startsWith("--") ? args[miChangeIdx + 1] : null;
       if (!miChange) {
         console.error('用法: sillyspec module-impact --change <name> [--json] [--spec-dir <path>]\n  生成 module-impact.md 骨架（模块影响矩阵按 module-map 预填 + 未匹配文件清单；已存在不覆盖）');
         process.exit(2);
@@ -1231,10 +1327,14 @@ async function main() {
       // 路由形态对齐 verify-probes（:897）/ module-impact（:1041）先例——--change 必填缺参
       // 用法错 exit 2、assertSafeChangeName 消毒、动态 import、--json 结构化输出、运行错
       // fail-soft 出错误摘要 exit 1 不抛栈。
+      // 画像双出口（2026-09-14-quick-exit-tiered-gates task-03，FR-04 / D-008）：quick 会话的
+      // gateProfile 由 computeChangeScopeAudit 结果对象携带——--json 出口经 ...saResult 展开
+      // 自动透出（gateProfile-json）、表格出口经 renderScopeAuditTable 按存在性追加 [gate]
+      // 画像段（gate-table-section），本层零分支零新解析；--file 子命令行为不变。
       const saChangeIdx = args.indexOf('--change');
-      const saChange = saChangeIdx >= 0 && args[saChangeIdx + 1] ? args[saChangeIdx + 1] : null;
+      const saChange = saChangeIdx >= 0 && args[saChangeIdx + 1] && !String(args[saChangeIdx + 1]).startsWith("--") ? args[saChangeIdx + 1] : null;
       if (!saChange) {
-        console.error('用法: sillyspec scope-audit --change <name> [--file <path>] [--json] [--spec-dir <path>]\n  变更范围对账：计划×实际三态全表 + 行数（quick 会话传 quick-<8hex> 出归属表；已归档变更可查——快照冻结记录态）；--file <path> 看单文件变化内容（对账同源锚点的 git diff）；advisory 只读展示，不构成门禁');
+        console.error('用法: sillyspec scope-audit --change <name> [--file <path>] [--json] [--spec-dir <path>]\n  变更范围对账：计划×实际三态全表 + 行数（quick 会话传 quick-<8hex> 出归属表，附 [gate] 分级门禁画像——表格画像段与 --json gateProfile 字段；已归档变更可查——快照冻结记录态）；--file <path> 看单文件变化内容（对账同源锚点的 git diff）；advisory 只读展示，不构成门禁');
         process.exit(2);
       }
       assertSafeChangeName(saChange, '--change 变更名');
@@ -1262,10 +1362,12 @@ async function main() {
       }
       // full-flow 变更目录存在性预检（endpoints baseline 先例同款）：post-apply 形态下实际侧三源
       // 对「变更不存在」不敏感（status 成功即 ok=true，会把主仓脏区误当实际侧），靠预检给明确
-      // 错误摘要 exit 1；quick 会话 id 无 changes/ 目录（guard 祖先链定位），不预检。
+      // 错误摘要 exit 1；quick 会话 id 无 changes/ 目录（guard 祖先链定位），不预检；ql-xxx
+      // 条目号同 quick 会话 id（ql-xxx 反查走 quicklog/patches，亦无 changes/ 目录）不预检。
       // 归档形态兼容（quick-8aa52289）：changes/<名> 不在 → 接受 changes/archive/<名>（scope-audit
       // 内部走快照记录态/HEAD 未提交窗口兜底）。
       if (!/^quick-[0-9a-f]{8}$/.test(saChange)
+        && !/^ql-\d{8}-\d{3}-[0-9a-f]{4}$/.test(saChange)
         && !existsSync(join(saSpecBase, 'changes', saChange))
         && !existsSync(join(saSpecBase, 'changes', 'archive', saChange))) {
         console.error(`❌ 变更目录不存在（活跃与归档区均未找到）: ${join(saSpecBase, 'changes', saChange)}（确认 --change 名，或 --spec-dir 指向主仓 .sillyspec）`);
@@ -1329,7 +1431,7 @@ async function main() {
         // 端点增删的 before 侧；扫描/落盘在 endpoint-baseline.js 纯函数，此处只做参数解析 +
         // worktree 主仓锚定 + 输出。
         const ebChangeIdx = args.indexOf('--change');
-        const ebChange = ebChangeIdx >= 0 && args[ebChangeIdx + 1] ? args[ebChangeIdx + 1] : null;
+        const ebChange = ebChangeIdx >= 0 && args[ebChangeIdx + 1] && !String(args[ebChangeIdx + 1]).startsWith("--") ? args[ebChangeIdx + 1] : null;
         if (!ebChange) {
           console.error('用法: sillyspec endpoints baseline --change <name> [--spec-dir <path>] [--json]\n  拍变更前端点基线（全仓现扫，幂等已拍过不覆盖）→ .runtime/endpoint-baselines/<change>.json；归档 delta 端点增删的 before 侧。\n  execute worktree 内跑：扫描根与落点自动锚定主仓（变更前代码在主仓；worktree 内是交付态且其 .runtime 随清理丢失）');
           process.exit(2);
@@ -1397,14 +1499,14 @@ async function main() {
         process.exit(2);
       }
       const epChangeIdx = args.indexOf('--change');
-      const epChange = epChangeIdx >= 0 && args[epChangeIdx + 1] ? args[epChangeIdx + 1] : null;
+      const epChange = epChangeIdx >= 0 && args[epChangeIdx + 1] && !String(args[epChangeIdx + 1]).startsWith("--") ? args[epChangeIdx + 1] : null;
       const epTaskIdx = args.indexOf('--task');
-      const epTask = epTaskIdx >= 0 && args[epTaskIdx + 1] ? args[epTaskIdx + 1] : null;
+      const epTask = epTaskIdx >= 0 && args[epTaskIdx + 1] && !String(args[epTaskIdx + 1]).startsWith("--") ? args[epTaskIdx + 1] : null;
       const epAllTasks = args.includes('--all-tasks');
       const epDirIdx = args.indexOf('--dir');
-      const epDir = epDirIdx >= 0 && args[epDirIdx + 1] ? args[epDirIdx + 1] : null;
+      const epDir = epDirIdx >= 0 && args[epDirIdx + 1] && !String(args[epDirIdx + 1]).startsWith("--") ? args[epDirIdx + 1] : null;
       const epFilesIdx = args.indexOf('--files');
-      const epFilesRaw = epFilesIdx >= 0 && args[epFilesIdx + 1] ? args[epFilesIdx + 1] : null;
+      const epFilesRaw = epFilesIdx >= 0 && args[epFilesIdx + 1] && !String(args[epFilesIdx + 1]).startsWith("--") ? args[epFilesIdx + 1] : null;
       if (!epChange) {
         console.error('❌ 缺 --change <变更名>');
         process.exit(2);
@@ -1552,7 +1654,7 @@ async function main() {
       // author/created_at 只 warning，agent 手改还常忘。本命令补齐（git user + 当前时间），
       // 已有两键的文件不动；有 frontmatter 就地插入，无则补一段。
       const sfhProjectIdx = args.indexOf('--project');
-      const sfhProject = sfhProjectIdx >= 0 && args[sfhProjectIdx + 1] ? args[sfhProjectIdx + 1] : null;
+      const sfhProject = sfhProjectIdx >= 0 && args[sfhProjectIdx + 1] && !String(args[sfhProjectIdx + 1]).startsWith("--") ? args[sfhProjectIdx + 1] : null;
       const { fixScanDocHeaders } = await import('./scan-postcheck.js');
       const sfhResult = fixScanDocHeaders({ cwd: dir, specDir, project: sfhProject });
       if (json) {
@@ -1572,7 +1674,7 @@ async function main() {
       // plan.md）注册表生成逐 task <!--TODO--> 骨架；gate 拒绝未替换的占位（防骨架直接过门），
       // agent 只需逐行填结论。已存在不覆盖（幂等，agent 产出优先）。
       const siChangeIdx = args.indexOf('--change');
-      const siChange = siChangeIdx >= 0 && args[siChangeIdx + 1] ? args[siChangeIdx + 1] : null;
+      const siChange = siChangeIdx >= 0 && args[siChangeIdx + 1] && !String(args[siChangeIdx + 1]).startsWith("--") ? args[siChangeIdx + 1] : null;
       if (!siChange) {
         console.error('用法: sillyspec symbol-impact --change <name> [--spec-dir <path>]\n  生成 symbol-impact.md 逐 task <!--TODO--> 骨架（已存在不覆盖）；gate 拒绝未替换的占位行');
         process.exit(2);
@@ -1608,7 +1710,7 @@ async function main() {
       // 手写 proposal/requirements/decisions 的 frontmatter/章节骨架是格式返工根源——本命令
       // 逐文件生成骨架（已存在不覆盖），agent 只填语义。与 design-init 同族（幂等）。
       const fpChangeIdx = args.indexOf('--change');
-      const fpChange = fpChangeIdx >= 0 && args[fpChangeIdx + 1] ? args[fpChangeIdx + 1] : null;
+      const fpChange = fpChangeIdx >= 0 && args[fpChangeIdx + 1] && !String(args[fpChangeIdx + 1]).startsWith("--") ? args[fpChangeIdx + 1] : null;
       if (!fpChange) {
         console.error('用法: sillyspec fourpiece-init --change <name> [--json] [--spec-dir <path>]\n  生成 proposal.md/requirements.md/decisions.md 骨架（frontmatter+章节标题+模板占位；已存在不覆盖；design.md 归 design-init）');
         process.exit(2);
@@ -1701,7 +1803,7 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
       // design-facts.js generateDesignSkeleton——本 case 只负责读盘/幂等保护/落盘）。已存在不覆盖
       // （幂等，agent 产出优先），--force 覆盖重生成。
       const diChangeIdx = args.indexOf('--change');
-      const diChange = diChangeIdx >= 0 && args[diChangeIdx + 1] ? args[diChangeIdx + 1] : null;
+      const diChange = diChangeIdx >= 0 && args[diChangeIdx + 1] && !String(args[diChangeIdx + 1]).startsWith("--") ? args[diChangeIdx + 1] : null;
       const diForce = args.includes('--force');
       if (!diChange) {
         console.error('用法: sillyspec design-init --change <name> [--force] [--json] [--spec-dir <path>]\n  从变更 decisions.md 生成 design.md 十三章节骨架（决策追踪表按当前版本 D 条目预填；已存在不覆盖，--force 覆盖）');
@@ -1765,7 +1867,7 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
       // （重跑即刷新）：与 design-init「agent 产出优先不覆盖」语义相反——delta 是源数据
       // （verify-runs/module-map）时点快照，旧报告天然过期，重新生成即对齐。
       const dlChangeIdx = args.indexOf('--change');
-      const dlChange = dlChangeIdx >= 0 && args[dlChangeIdx + 1] ? args[dlChangeIdx + 1] : null;
+      const dlChange = dlChangeIdx >= 0 && args[dlChangeIdx + 1] && !String(args[dlChangeIdx + 1]).startsWith("--") ? args[dlChangeIdx + 1] : null;
       if (!dlChange) {
         console.error('用法: sillyspec delta --change <name> [--spec-dir <path>] [--json]\n  生成变更 delta.md（Before/Delta/After 三段式；四源 fail-soft，缺源逐段降级注记；幂等覆盖重跑即刷新）');
         process.exit(2);
@@ -1827,11 +1929,11 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
       // 调度者手动派独立子代理不写 marker 的死锁。docHash 由 CLI computeDocHash 算（部分实现 P6.1b defer）。
       // 纯新增，不改 gate 语义。与 task 级 backfill-reviews 对称（stage 级等价物）。
       const rsrChangeIdx = args.indexOf('--change');
-      const rsrChange = rsrChangeIdx >= 0 && args[rsrChangeIdx + 1] ? args[rsrChangeIdx + 1] : null;
+      const rsrChange = rsrChangeIdx >= 0 && args[rsrChangeIdx + 1] && !String(args[rsrChangeIdx + 1]).startsWith("--") ? args[rsrChangeIdx + 1] : null;
       const rsrStageIdx = args.indexOf('--stage');
-      const rsrStage = rsrStageIdx >= 0 && args[rsrStageIdx + 1] ? args[rsrStageIdx + 1] : null;
+      const rsrStage = rsrStageIdx >= 0 && args[rsrStageIdx + 1] && !String(args[rsrStageIdx + 1]).startsWith("--") ? args[rsrStageIdx + 1] : null;
       const rsrFromIdx = args.indexOf('--from');
-      const rsrFrom = rsrFromIdx >= 0 && args[rsrFromIdx + 1] ? args[rsrFromIdx + 1] : null;
+      const rsrFrom = rsrFromIdx >= 0 && args[rsrFromIdx + 1] && !String(args[rsrFromIdx + 1]).startsWith("--") ? args[rsrFromIdx + 1] : null;
       // docHash 联动（坑 stage-review-dochash-manual-resync，2026-08-21 实证）：改一版 design 要
       // 重算 2-3 个 stage review 的 docHash，手工易漏、gate 报错才补。--refresh-hash 就地刷新单个
       // 既有 review 的 hash（保留结论）；--all 一次处理三个 stage（有 review 刷 hash，无 review
@@ -1940,13 +2042,14 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
         // --dry-run 列独立存在（「报告修复预览 + exit 1」），即 dryRun 置位 = fix 语义自动生效
         // 但零写盘（本口径记录于此，防歧义）。
         const BARE_FLAGS = ['--fix', '--dry-run', '--no-exempt'];
-        const PAIRED_FLAGS = ['--paths'];
+        const PAIRED_FLAGS = ['--paths', '--against'];
         const rawDocsArgs = filteredArgs.slice(2);
         const docsCheckFlags = [];
         let cliPaths = null;
         let fix = false;
         let dryRun = false;
         let noExempt = false;
+        let againstRef = null;
         for (let i = 0; i < rawDocsArgs.length; i++) {
           const a = rawDocsArgs[i];
           if (a === '--paths' && rawDocsArgs[i + 1] !== undefined) {
@@ -1955,6 +2058,13 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
           } else if (a === '--paths') {
             console.error('❌ docs check: --paths 缺值（逗号分隔 glob，如 --paths "docs/**/*.md"）');
             process.exit(2);
+          } else if (a === '--against' && rawDocsArgs[i + 1] !== undefined && !rawDocsArgs[i + 1].startsWith('--')) {
+            // 坑 docs-gate-shared-worktree-parallel-block：按提交树校验，隔离并行在途编辑（移动靶）
+            againstRef = rawDocsArgs[i + 1];
+            i++;
+          } else if (a === '--against') {
+            console.error('❌ docs check: --against 缺值（如 --against HEAD）');
+            process.exit(2);
           } else if (BARE_FLAGS.includes(a)) {
             if (a === '--fix') fix = true;
             else if (a === '--dry-run') dryRun = true;
@@ -1966,6 +2076,11 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
             docsCheckFlags.push(a);
           }
         }
+        if ((fix || dryRun) && againstRef) {
+          // --fix 操作工作区磁盘内容，against 语义与其矛盾（修的是未提交文本、校验的是提交树）
+          console.error('❌ docs check: --fix/--dry-run 与 --against 互斥（fix 恒操作工作区，against 恒校验提交树）');
+          process.exit(2);
+        }
         const { runDocsCheck, readDocsCheckConfig, DocsCheckConfigError, applyFixes, runChangeNameAdvisory } = await import('./docs-check.js');
         try {
           // 配置优先级：--paths > local.yaml docs-check.paths > 缺省 docs/**/*.md
@@ -1978,6 +2093,7 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
             keywordAssert: cfg.keywordAssert,
             crossRepoRoots: cfg.crossRepoRoots,
             exempt: !noExempt,
+            against: againstRef,
           });
           // task-03 修复链路（FR-04，platform-map-auto-anchors）：fixActive 才构造 fixes——
           // 仅 fix.fixable===true 且 newLine 为整数的条目可重锚；newRef = ref 的行号部分替换为
@@ -2152,11 +2268,14 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
         // usage 输出且 exit 0——gate 形同虚设（docs-signals 范围内文件+hook 已就位，仅此分支缺）。
         // B9（2026-08-16）：flag 白名单化（对齐 docs check 分支）——未知 --xxx 显式 exit 2
         // （interface-contract §1.3b 宣称），并接线 --paths 透传 runDocsGate.checkOpts（原被忽略）。
+        // 坑 docs-gate-stale-baseline（ql-20260915-004）：超基线分支实测 origin/main 兜底——
+        // 未劣于远端放行 + 提示重锚；--json 输出含 originCount 字段（null=未实测/快路径）。
         const GATE_BARE_FLAGS = ['--init-baseline'];
-        const GATE_PAIRED_FLAGS = ['--paths'];
+        const GATE_PAIRED_FLAGS = ['--paths', '--against'];
         const rawGateArgs = filteredArgs.slice(2);
         let initBaseline = false;
         let cliGatePaths = null;
+        let gateAgainst = null;
         for (let i = 0; i < rawGateArgs.length; i++) {
           const a = rawGateArgs[i];
           if (a === '--paths' && rawGateArgs[i + 1] !== undefined) {
@@ -2165,13 +2284,21 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
           } else if (a === '--paths') {
             console.error('❌ docs gate: --paths 缺值（逗号分隔 glob，如 --paths "docs/**/*.md"）');
             process.exit(2);
+          } else if (a === '--against' && rawGateArgs[i + 1] !== undefined && !rawGateArgs[i + 1].startsWith('--')) {
+            // 坑 docs-gate-shared-worktree-parallel-block：按提交树校验（pre-push 语义——推的
+            // 是提交不是工作区），隔离并行会话在途编辑造成的锚点瞬时漂移（移动靶）
+            gateAgainst = rawGateArgs[i + 1];
+            i++;
+          } else if (a === '--against') {
+            console.error('❌ docs gate: --against 缺值（如 --against HEAD）');
+            process.exit(2);
           } else if (GATE_BARE_FLAGS.includes(a)) {
             if (a === '--init-baseline') initBaseline = true;
           } else if (a.startsWith('--')) {
             console.error(`❌ docs gate: 未知 flag「${a}」。已知 flag：${[...GATE_BARE_FLAGS, ...GATE_PAIRED_FLAGS].join(' ')}（--json 为全局 flag）`);
             process.exit(2);
           } else {
-            console.error(`❌ docs gate: 多余位置参数「${a}」。用法：sillyspec docs gate [--init-baseline] [--paths <glob,...>] [--json]`);
+            console.error(`❌ docs gate: 多余位置参数「${a}」。用法：sillyspec docs gate [--init-baseline] [--paths <glob,...>] [--against HEAD] [--json]`);
             process.exit(2);
           }
         }
@@ -2181,7 +2308,7 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
         const gateSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
         const g = await runDocsGate(
           { projectRoot: dir, specBase: gateSpecBase, initBaseline },
-          cliGatePaths ? { paths: cliGatePaths } : undefined
+          { ...(cliGatePaths ? { paths: cliGatePaths } : {}), ...(gateAgainst ? { against: gateAgainst } : {}) }
         );
         if (json) {
           console.log(JSON.stringify(g, null, 2));
@@ -2237,7 +2364,7 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
       const dumpDbFlag = filteredArgs.includes('--dump-db');
       const doctorConfirm = filteredArgs.includes('--confirm');
       const pathIdx = filteredArgs.indexOf('--path');
-      const dbPath = pathIdx >= 0 && filteredArgs[pathIdx + 1] ? filteredArgs[pathIdx + 1] : null;
+      const dbPath = pathIdx >= 0 && filteredArgs[pathIdx + 1] && !String(filteredArgs[pathIdx + 1]).startsWith("--") ? filteredArgs[pathIdx + 1] : null;
 
       // --align-execute-progress：基于 plan.md 声明对齐 execute 派生戳（仿 --cleanup-remnant 范式）
       // 默认 dry-run（只报告将补哪些 step），加 --confirm 才写。命中即 break，绝不 fall-through。
@@ -2245,7 +2372,7 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
       if (alignFlag) {
         // --change 解析：显式优先，缺省用单活跃变更自动兜底（与 run.js resolveChangeNameAuto 同逻辑）
         const alignChangeIdx = filteredArgs.indexOf('--change');
-        let alignChange = alignChangeIdx >= 0 && filteredArgs[alignChangeIdx + 1] ? filteredArgs[alignChangeIdx + 1] : null;
+        let alignChange = alignChangeIdx >= 0 && filteredArgs[alignChangeIdx + 1] && !String(filteredArgs[alignChangeIdx + 1]).startsWith("--") ? filteredArgs[alignChangeIdx + 1] : null;
         if (!alignChange) {
           const changesDir = join(resolvePlatformSpecDir(doctorEffectiveDir, specDir) || join(doctorEffectiveDir, '.sillyspec'), 'changes');
           if (existsSync(changesDir)) {
@@ -2417,8 +2544,8 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
         const r = buildAndWriteScanFacts({
           cwd: factsEffectiveDir,
           specDir: resolvePlatformSpecDir(dir, specDir) || join(factsEffectiveDir, '.sillyspec'),
-          projectName: projIdx >= 0 && filteredArgs[projIdx + 1] ? filteredArgs[projIdx + 1] : basename(factsEffectiveDir),
-          projectPath: pathIdx >= 0 && filteredArgs[pathIdx + 1] ? filteredArgs[pathIdx + 1] : null,
+          projectName: projIdx >= 0 && filteredArgs[projIdx + 1] && !String(filteredArgs[projIdx + 1]).startsWith("--") ? filteredArgs[projIdx + 1] : basename(factsEffectiveDir),
+          projectPath: pathIdx >= 0 && filteredArgs[pathIdx + 1] && !String(filteredArgs[pathIdx + 1]).startsWith("--") ? filteredArgs[pathIdx + 1] : null,
         })
         const f = r.facts
         console.log(`scan facts 已写入: ${r.outPath}`)
@@ -2431,7 +2558,7 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
       if (filteredArgs[1] === 'diff') {
         const { runScanDiff } = await import('./scan-diff.js')
         const diffBaseIdx = filteredArgs.indexOf('--base')
-        const diffBase = diffBaseIdx >= 0 && filteredArgs[diffBaseIdx + 1] ? filteredArgs[diffBaseIdx + 1] : null
+        const diffBase = diffBaseIdx >= 0 && filteredArgs[diffBaseIdx + 1] && !String(filteredArgs[diffBaseIdx + 1]).startsWith("--") ? filteredArgs[diffBaseIdx + 1] : null
         // specBase/projectName 与 scan 主流程同口径（scan-profile.js：specBase=进度库根，projectName=仓库根 basename）。
         // A4 同族：平台指针 / 显式 --spec-dir / 本地 fallback 三合一，平台模式下 diff 不落本地孤儿库。
         const diffEffectiveDir = specDir ? dir : resolveEffectiveDir(dir)
@@ -2445,6 +2572,40 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
         })
         break
       }
+      // scan refresh 子命令（2026-09-14-scan-incremental-refresh D-002@v1：增量刷新两拍交互）。
+      // ①拍纯读出工单（含 guard 握手写）；②拍 --done 盖章收尾。与 diff 同为旁路：跳过
+      // triggerPullActiveChange、不走 scan 主流程。--project 支持子项目（缺省仓库根 basename，
+      // 与 scan facts 同口径）。
+      if (filteredArgs[1] === 'refresh') {
+        const { runRefresh, finalizeRefresh } = await import('./scan-refresh.js')
+        const refreshEffectiveDir = specDir ? dir : resolveEffectiveDir(dir)
+        const refreshSpecBase = resolvePlatformSpecDir(dir, specDir) || join(refreshEffectiveDir, '.sillyspec')
+        const projIdxR = filteredArgs.indexOf('--project')
+        const refreshProjectName = projIdxR >= 0 && filteredArgs[projIdxR + 1] && !String(filteredArgs[projIdxR + 1]).startsWith("--") ? filteredArgs[projIdxR + 1] : basename(refreshEffectiveDir)
+        if (filteredArgs.includes('--done')) {
+          const docsIdx = filteredArgs.indexOf('--docs')
+          const docsList = docsIdx >= 0 && filteredArgs[docsIdx + 1] && !String(filteredArgs[docsIdx + 1]).startsWith("--")
+            ? filteredArgs[docsIdx + 1].split(',').map(s => s.trim()).filter(Boolean) : null
+          const r = await finalizeRefresh({
+            projectRoot: refreshEffectiveDir,
+            specBase: refreshSpecBase,
+            projectName: refreshProjectName,
+            docs: docsList,
+            force: filteredArgs.includes('--force'),
+            platformOpts: platformWorkspaceId || platformRuntimeRoot ? { workspaceId: platformWorkspaceId, runtimeRoot: platformRuntimeRoot, specRoot: resolvePlatformSpecDir(dir, specDir) } : null,
+          })
+          process.exitCode = r.code
+        } else {
+          process.exitCode = await runRefresh({
+            projectRoot: refreshEffectiveDir,
+            specBase: refreshSpecBase,
+            projectName: refreshProjectName,
+            force: filteredArgs.includes('--force'),
+            json: filteredArgs.includes('--json'),
+          })
+        }
+        break
+      }
     }
     case 'status':
     case 'quick':
@@ -2496,14 +2657,82 @@ ${generated.length} 个骨架已就绪——逐节把 <!--TODO--> 替换为语
       console.log('按 Ctrl+C 停止服务器');
       break;
     }
+    case 'wt-commit': {
+      // 坑 wt-commit-ghost-dispatch：runWtCommit 模块自 bd1cb91 存在但 dispatch 从未接线——
+      // execute Wave prompt 指示的 `sillyspec wt-commit` 一直报「未知命令」（2026-09-14
+      // knowledge-loop-close execute W1 实证，ql-20260914-016-8786 根治）。参数面见模块头：
+      // wt-commit [--change <名>] -m <信息> [--pathspec-from-file <f>] -- <path...>；
+      // worktree 内可省 --change（从 cwd 的 worktrees/<名> 段推断）。
+      const wtCommitRest = filteredArgs.slice(1);
+      const wtCommitDd = wtCommitRest.indexOf('--');
+      const wtCommitFlags = wtCommitDd === -1 ? wtCommitRest : wtCommitRest.slice(0, wtCommitDd);
+      const wtCommitPaths = wtCommitDd === -1 ? [] : wtCommitRest.slice(wtCommitDd + 1);
+      let wtCommitChange = null;
+      let wtCommitMessage = null;
+      let wtCommitPathspecFile = null;
+      for (let i = 0; i < wtCommitFlags.length; i++) {
+        if (wtCommitFlags[i] === '--change' && wtCommitFlags[i + 1]) wtCommitChange = wtCommitFlags[++i];
+        else if ((wtCommitFlags[i] === '-m' || wtCommitFlags[i] === '--message') && wtCommitFlags[i + 1]) wtCommitMessage = wtCommitFlags[++i];
+        else if (wtCommitFlags[i] === '--pathspec-from-file' && wtCommitFlags[i + 1]) wtCommitPathspecFile = wtCommitFlags[++i];
+      }
+      if (!wtCommitChange) {
+        const inferred = String(dir).match(/[\\/]worktrees[\\/]([^\\/]+)/);
+        wtCommitChange = inferred ? inferred[1] : null;
+      }
+      try {
+        const { runWtCommit } = await import('./wt-commit.js');
+        const r = await runWtCommit({
+          changeName: wtCommitChange,
+          message: wtCommitMessage,
+          pathspecs: wtCommitPaths,
+          pathspecFile: wtCommitPathspecFile,
+          cwd: dir,
+        });
+        if (json) console.log(JSON.stringify({ command: 'wt-commit', ...r }, null, 2));
+        else if (r.skipped) console.log(`⏭️  wt-commit 无变更跳过（HEAD 不动）：${r.shortHead}`);
+        else console.log(`✅ wt-commit 完成：${r.shortHead}（${r.files.length} 文件，worktree=${r.worktreePath}）`);
+      } catch (e) {
+        console.error(`❌ wt-commit 失败：${e.message}`);
+        process.exit(1);
+      }
+      break;
+    }
     case 'worktree': {
       const { WorktreeManager } = await import('./worktree.js');
-      const { ProgressManager } = await import('./progress.js');
+      const { ProgressManager, resolveSessionIdentity } = await import('./progress.js');
       const wtSubCmd = filteredArgs[1];
       const wtName = filteredArgs.slice(2).find(a => !a.startsWith('-'));
       const wm = new WorktreeManager({ cwd: dir });
       const pm = new ProgressManager({ specDir: resolvePlatformSpecDir(dir, specDir) });
 
+      // ── 所有权护栏公共件（2026-09-14-change-ownership-guards task-02 / FR-01 / D-001@v1）──
+      // 接管类操作（apply / cleanup / assess 自动 apply）改主仓前校验 change 归属：
+      // 他人且活跃（活跃窗内，heartbeat_minutes 缺省 15min）→ 拒绝；无主 / 窗口外 / 本会话
+      // 自有 / --takeover → 放行，接管分支重写 owner=本会话（setChangeOwner 含 last_active
+      // 心跳起算）。调用点必须在 withMainRepoLock 锁内（判定与执行无 TOCTOU）；只读路径
+      // （diff/list/meta/doctor/--check-only）不接。会话标识三级解析：--session flag >
+      // env SILLYSPEC_SESSION_ID > anon@host 机器级降级（同机并行不设防是 R-01 明示局限）。
+      const sessionFlagIdx = args.indexOf('--session');
+      const sessionFlagValue = (sessionFlagIdx !== -1 && args[sessionFlagIdx + 1]
+        && !String(args[sessionFlagIdx + 1]).startsWith('--')) ? String(args[sessionFlagIdx + 1]).trim() : null;
+      // soft=true：assess 自动路径拒绝语义（跳过自动落盘 + warning 不抛错，同 overlapSkipped 软跳）；
+      // soft=false：显式 apply/cleanup 拒绝（结构化错误，调用方 exit 非零）。
+      function _guardChangeOwnership(changeName, { forced = false, soft = false } = {}) {
+        const { session } = resolveSessionIdentity({ flagSession: sessionFlagValue, cwd: dir });
+        const check = pm.assertChangeOwnership(dir, changeName, { selfSession: session, nowMs: Date.now(), forced });
+        if (check.allowed) {
+          if (check.action !== 'self') pm.setChangeOwner(dir, changeName, session);
+          return { allowed: true, action: check.action };
+        }
+        const lines = [
+          `变更 ${changeName} 正被其他会话持有（owner: ${check.owner}，最后活跃: ${check.lastActive || '未知'}），活跃窗口 ${Math.round(check.heartbeatMs / 60000)} 分钟内拒绝接管类操作`,
+          `确认对方已放弃且本会话应接管：加 --takeover 显式强制接管（重写 owner 并留痕）；或等对方会话收尾后重试`,
+        ];
+        if (soft) { for (const l of lines) console.warn(`⚠️  ${l}`); }
+        else { for (const l of lines) console.error(`🚫 ${l}`); }
+        return { allowed: false, action: check.action };
+      }
+
       // isolation 写入 DB 的辅助函数
       function _writeIsolationToDB(cwd, changeName, info) {
         if (info.blocked) {
@@ -2528,17 +2757,19 @@ SillySpec worktree — git worktree 隔离管理
 
 用法:
   sillyspec worktree create <change-name> [--base <branch>] [--adopt-branch]   创建隔离 worktree（--adopt-branch：收编既有同名分支为工作分支，分支现状作 baseline）
-  sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge] [--skip-overlap] [--stash-dirty]   校验并应用变更到主工作区（--stash-dirty：主仓在途改动自动 stash→apply→恢复，SHA 兜底可审计）
-  sillyspec worktree assess <change-name>                     风险审计 + 自动 apply
+  sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge] [--skip-overlap] [--stash-dirty] [--force] [--takeover]   校验并应用变更到主工作区（--stash-dirty：主仓在途改动自动 stash→apply→恢复，SHA 兜底可审计；--force：越过活跃 quick 会话 guard 相交预检，overlapForced 留痕；--takeover：越过所有权护栏显式强制接管，owner 重写留痕）
+  sillyspec worktree assess <change-name>                     风险审计 + 自动 apply（自动路径受所有权护栏约束：他人活跃 change 跳过自动落盘并 warning）
   sillyspec worktree diff <change-name> [--base <commit>]      查看 worktree 相对 base 的变更
   sillyspec worktree list                                      列出所有活跃 worktree
   sillyspec worktree meta <change-name>                        读取 worktree meta.json
-  sillyspec worktree cleanup <change-name> [--force]           强制清理 worktree
+  sillyspec worktree cleanup <change-name> [--force] [--takeover]   强制清理 worktree（受所有权护栏约束：他人活跃 change 拒绝，--takeover 显式接管）
   sillyspec worktree doctor [--fix] [--stale-hours N] [--change <name>]   健康检查 + 修复（--change 仅扫指定 change）
 
 选项:
   --base <branch>       create: 指定基础分支（默认当前 HEAD）
   --check-only          apply: 只输出检查结果，不实际 apply
+  --takeover            apply/cleanup: 所有权护栏拒绝时的显式强制接管口（owner 他人且活跃时解锁，重写 owner 留痕）
+  --session <id>        显式会话标识（所有权三级解析最高优先级；缺省 env SILLYSPEC_SESSION_ID，再缺省 anon@<host> 机器级降级——同机并行不设防）
 `);
         break;
       }
@@ -2553,7 +2784,7 @@ SillySpec worktree — git worktree 隔离管理
           try { assertSafeChangeName(wtName, 'worktree 变更名'); }
           catch (e) { console.error(`❌ ${e.message}`); process.exit(2); }
           const baseIdx = args.indexOf('--base');
-          const base = baseIdx >= 0 && args[baseIdx + 1] ? args[baseIdx + 1] : undefined;
+          const base = baseIdx >= 0 && args[baseIdx + 1] && !String(args[baseIdx + 1]).startsWith("--") ? args[baseIdx + 1] : undefined;
           const adoptBranch = args.includes('--adopt-branch'); // 收编既有同名分支为工作分支（坑 worktree-user-branch-conflict）
           try {
             const info = wm.create(wtName, { base, adoptBranch });
@@ -2576,13 +2807,15 @@ SillySpec worktree — git worktree 隔离管理
         }
         case 'apply': {
           if (!wtName) {
-            console.error('❌ 用法: sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge] [--skip-overlap] [--stash-dirty]');
+            console.error('❌ 用法: sillyspec worktree apply <change-name> [--check-only] [--base merge-base|baseline] [--merge] [--skip-overlap] [--stash-dirty] [--force] [--takeover]');
             process.exit(1);
           }
           const checkOnly = args.includes('--check-only');
           const merge = args.includes('--merge');
           const skipOverlap = args.includes('--skip-overlap');
           const stashDirty = args.includes('--stash-dirty');
+          const force = args.includes('--force'); // guard 相交预检显式解锁（task-02 / FR-03；人工 flag，自动路径永不带）
+          const takeover = args.includes('--takeover'); // 所有权护栏显式强制接管（2026-09-14-change-ownership-guards task-02 / FR-01；人工 flag，自动路径永不带）
 
           // 解析 --base 参数（默认 merge-base）
           let base = 'merge-base';
@@ -2610,15 +2843,22 @@ SillySpec worktree — git worktree 隔离管理
           }
           // 主仓 apply 互斥锁（坑 main-apply-no-mutex）：真 apply（非 checkOnly）在锁内跑——
           // apply 链（rollback/merge/cleanup）直接改主仓工作区，两会话并发互踩会互相清文件。
+          // 所有权护栏（2026-09-14-change-ownership-guards task-02 / FR-01）：锁内、实际 apply 前
+          // 判归属——他人且活跃（活跃窗内）拒绝；--check-only 是只读路径不校验（铁律：只读命令不接）。
+          // 拒绝时结构化错误已在护栏内打印，经哨兵返回值带出锁外统一 exit 1（不进结果展示分支）。
           let result;
           try {
             result = checkOnly
-              ? applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx, skipOverlap, stashDirty })
-              : await withMainRepoLock(dir, wtName, 'apply', () => applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx, skipOverlap, stashDirty }));
+              ? applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx, skipOverlap, stashDirty, force })
+              : await withMainRepoLock(dir, wtName, 'apply', () => {
+                if (!_guardChangeOwnership(wtName, { forced: takeover }).allowed) return { __ownershipDenied: true };
+                return applyWorktree(wtName, { cwd: dir, checkOnly, merge, base, ctx: _applyCtx, skipOverlap, stashDirty, force });
+              });
           } catch (lockErr) {
             console.error(`❌ ${lockErr.message}`);
             process.exit(1);
           }
+          if (result && result.__ownershipDenied) process.exit(1);
 
           if (result.errors.length > 0) {
             console.error(`❌ 校验失败:`);
@@ -2754,15 +2994,29 @@ SillySpec worktree — git worktree 隔离管理
           if (assessment.decision === 'SAFE' || assessment.decision === 'WARNING') {
             console.log('Action: auto-applying...');
             const { applyWorktree, withMainRepoLock } = await import('./worktree-apply.js');
-            // 主仓互斥锁（与手动 apply 同款）：自动 apply 同样改主仓工作区，必须互斥
+            // 主仓互斥锁（与手动 apply 同款）：自动 apply 同样改主仓工作区，必须互斥。
+            // 所有权护栏（2026-09-14-change-ownership-guards task-02 / FR-01）：assess 自动 apply
+            // 是护栏①最可能的旁路（SAFE/WARNING 即自动改主仓+链内 cleanup）——锁内、实际动作前
+            // 判归属。自动路径永不带 --takeover；他人活跃 change 拒绝 = 跳过自动落盘 + warning
+            // 不抛错（同 overlapSkipped 软跳语义：无人值守不越权也不阻断审计流）。
             let applyResult;
             try {
-              applyResult = await withMainRepoLock(dir, wtName, 'assess-auto-apply', () => applyWorktree(wtName, { cwd: dir, ctx: _assessCtx }));
+              applyResult = await withMainRepoLock(dir, wtName, 'assess-auto-apply', () => {
+                if (!_guardChangeOwnership(wtName, { soft: true }).allowed) return { ownershipSkipped: true };
+                return applyWorktree(wtName, { cwd: dir, ctx: _assessCtx, autoApply: true });
+              });
             } catch (lockErr) {
               console.error(`❌ 自动 apply 未执行：${lockErr.message}`);
               break;
             }
-            if (applyResult.errors.length > 0) {
+            if (applyResult.ownershipSkipped) {
+              // 所有权拒绝（结构化 warning 已在护栏内打印）：跳过自动落盘，指引人工显式接管
+              console.log('   → 确认对方会话已放弃：人工评估后显式接管 sillyspec worktree apply ' + wtName + ' --takeover（或等对方收尾后重跑 assess）');
+            } else if (applyResult.overlapSkipped) {
+              // guard 相交软跳过（task-02 / FR-03）：无人值守不越权也不阻断审计流——不落盘，亮 warning 指引人工评估
+              for (const w of applyResult.warnings || []) console.log(`⚠️  ${w}`);
+              console.log('   → 人工评估后显式 apply: sillyspec worktree apply ' + wtName + '（确认与活跃 quick 会话无冲突；或等对方 --done 后重跑 assess）');
+            } else if (applyResult.errors.length > 0) {
               console.error('❌ apply 失败:', applyResult.errors.join('; '));
             } else {
               console.log(`✅ 已自动应用 ${applyResult.changedFiles.length} 个文件变更：`);
@@ -2855,15 +3109,23 @@ SillySpec worktree — git worktree 隔离管理
         }
         case 'cleanup': {
           if (!wtName) {
-            console.error('❌ 用法: sillyspec worktree cleanup <change-name>');
+            console.error('❌ 用法: sillyspec worktree cleanup <change-name> [--force] [--takeover]');
             process.exit(1);
           }
           const forceFlag = args.includes('--force');
+          const takeover = args.includes('--takeover'); // 所有权护栏显式强制接管（task-02 / FR-01）
           try {
             // 主仓互斥锁（坑 main-repo-no-mutex 二批）：cleanup 删 worktree 注册表/分支/目录，
-            // 与并行会话的 apply/cleanup 互踩会互相清——与其他写主仓操作共用一把 main-repo.lock
+            // 与并行会话的 apply/cleanup 互踩会互相清——与其他写主仓操作共用一把 main-repo.lock。
+            // 所有权护栏（2026-09-14-change-ownership-guards task-02 / FR-01）：锁内、实际清理前
+            // 判归属——他人且活跃拒绝（结构化错误在护栏内打印，哨兵带出统一 exit 1，跨仓清理
+            // 同步跳过）；--takeover 显式强制接管放行。
             const { withMainRepoLock } = await import('./worktree-apply.js');
-            const result = await withMainRepoLock(dir, wtName, 'worktree-cleanup', () => wm.cleanup(wtName, { force: forceFlag }));
+            const result = await withMainRepoLock(dir, wtName, 'worktree-cleanup', () => {
+              if (!_guardChangeOwnership(wtName, { forced: takeover }).allowed) return { __ownershipDenied: true };
+              return wm.cleanup(wtName, { force: forceFlag });
+            });
+            if (result && result.__ownershipDenied) process.exit(1);
             // 跨仓 worktree（坑 cross-repo-no-worktree-isolation）：与主仓同锁清理——跨仓 worktree
             // 注册在各跨仓仓 .git 内，但目录/meta 在主仓 .sillyspec 运行时区，同样怕并发互踩
             const { cleanupCrossWorktrees } = await import('./worktree-cross.js');
@@ -2885,7 +3147,16 @@ SillySpec worktree — git worktree 隔离管理
               }
             } else if (result.result === 'skipped') {
               console.log(`⏭️  worktree 跳过清理: ${wtName} (mode: ${result.mode})`);
-              console.log(`   原因: in-place 模式没有隔离目录需要清理`);
+              // ql-20260915-003 修复②（坑 cleanup-meta-fallback，2026-09-15 实证「mode: null
+              // 跳过清理」但 worktree 实际创建过）：早退跳过（meta/目录/git 注册三路探针全未
+              // 命中）时，误导性的「in-place 模式」文案升级为诊断式——列三路探针路径 + meta
+              // 丢失可能原因 + doctor 指引。probePaths 由 cleanup 兜底探测带回。
+              if (Array.isArray(result.probePaths) && result.probePaths.length > 0) {
+                for (const p of result.probePaths) console.log(`   探针: ${p}`);
+                console.log(`   meta 丢失可能原因：apply/cleanup 后随目录删除、并行会话已清理、cwd/specDir 漂移。可用 sillyspec worktree doctor 检查 git 注册与分支残留。`);
+              } else {
+                console.log(`   原因: in-place 模式没有隔离目录需要清理`);
+              }
             } else if (result.result === 'blocked') {
               console.error(`🚫 拒绝清理：有未落主仓交付变更，请先 sillyspec worktree apply ${wtName} 或 --force`);
             } else if (result.result === 'partial') {
@@ -2907,7 +3178,7 @@ SillySpec worktree — git worktree 隔离管理
           const staleIdx = args.indexOf('--stale-hours');
           const staleHours = staleIdx !== -1 && args[staleIdx + 1] ? parseInt(args[staleIdx + 1], 10) : 24;
           const changeIdx = args.indexOf('--change');
-          const changeName = changeIdx !== -1 && args[changeIdx + 1] ? args[changeIdx + 1] : null;
+          const changeName = changeIdx !== -1 && args[changeIdx + 1] && !String(args[changeIdx + 1]).startsWith("--") ? args[changeIdx + 1] : null;
           const diag = await wm.doctor({ fix: fixFlag, staleHours, changeName });
           if (diag.issues.length === 0) {
             console.log('✅ worktree 健康检查通过，无异常');
@@ -2990,7 +3261,7 @@ SillySpec dispatch — SillyHub 派发能力探测与策略生成（agent 调用
       if (dispatchSubCmd === 'hint') {
         // 解析 --contract <json>（仿 worktree 用 args.indexOf 取 flag 后一个值）
         const contractIdx = args.indexOf('--contract');
-        const contractRaw = contractIdx >= 0 && args[contractIdx + 1] ? args[contractIdx + 1] : null;
+        const contractRaw = contractIdx >= 0 && args[contractIdx + 1] && !String(args[contractIdx + 1]).startsWith("--") ? args[contractIdx + 1] : null;
         if (!contractRaw) {
           console.error('用法: sillyspec dispatch hint --contract <json> [--json]\n  生成派发指令（DispatchContract：brief/worktreePath/branch/allowedPaths/readOnly/...）');
           process.exit(2);
@@ -3062,7 +3333,7 @@ SillySpec platform — SillyHub 平台同步
       // join(runtimeDir, `sync-conflict-${changeName}.json`) 可被 ../ 穿越出 .runtime
       {
         const pChangeIdx = args.indexOf('--change');
-        const pChangeVal = pChangeIdx >= 0 && args[pChangeIdx + 1] ? args[pChangeIdx + 1] : null;
+        const pChangeVal = pChangeIdx >= 0 && args[pChangeIdx + 1] && !String(args[pChangeIdx + 1]).startsWith("--") ? args[pChangeIdx + 1] : null;
         if (pChangeVal) assertSafeChangeName(pChangeVal, 'platform --change 变更名');
       }
 
@@ -3130,7 +3401,7 @@ SillySpec platform — SillyHub 平台同步
             process.exit(1);
           }
           const tokenIdx = args.indexOf('--token');
-          const token = tokenIdx >= 0 && args[tokenIdx + 1] ? args[tokenIdx + 1] : undefined;
+          const token = tokenIdx >= 0 && args[tokenIdx + 1] && !String(args[tokenIdx + 1]).startsWith("--") ? args[tokenIdx + 1] : undefined;
           if (!token) {
             // 缺 token 直接终止（体检 HUB-02）：交互式输入尚未实现（task-11），此前
             // 继续执行会把 undefined 序列化成字符串 "undefined" 写入 local.yaml，
@@ -3142,17 +3413,20 @@ SillySpec platform — SillyHub 平台同步
           break;
         }
         case 'disconnect':
-          await syncModule.disconnect(dir);
+          // --keep-pointer（坑 platform-sync-progress-rollback-and-db-corruption 坑1③）：只清
+          // local.yaml platform 段，保留指针/声明给 daemon 内嵌 CLI——回滚环恢复序列正规出口
+          await syncModule.disconnect(dir, { keepPointer: filteredArgs.includes('--keep-pointer') });
           break;
         case 'sync': {
           const syncChangeIdx = args.indexOf('--change');
-          const syncChangeName = syncChangeIdx >= 0 && args[syncChangeIdx + 1] ? args[syncChangeIdx + 1] : null;
-          await syncModule.sync(syncChangeName, dir);
+          const syncChangeName = syncChangeIdx >= 0 && args[syncChangeIdx + 1] && !String(args[syncChangeIdx + 1]).startsWith("--") ? args[syncChangeIdx + 1] : null;
+          // manual：用户显式同步，change_deleted 回执噪音闸旁路（显式动作的回执必须可见）
+          await syncModule.sync(syncChangeName, dir, { manual: true });
           break;
         }
         case 'sync-docs': {
           const syncDocsChangeIdx = args.indexOf('--change');
-          const syncDocsChangeName = syncDocsChangeIdx >= 0 && args[syncDocsChangeIdx + 1] ? args[syncDocsChangeIdx + 1] : null;
+          const syncDocsChangeName = syncDocsChangeIdx >= 0 && args[syncDocsChangeIdx + 1] && !String(args[syncDocsChangeIdx + 1]).startsWith("--") ? args[syncDocsChangeIdx + 1] : null;
           await syncModule.syncDocuments(syncDocsChangeName, dir);
           break;
         }
@@ -3187,7 +3461,7 @@ SillySpec platform — SillyHub 平台同步
           // task-11 / D-006 / D-009 / FR-03：手动下行拉取平台进度到本地。
           // 与自动 triggerPull 共用 syncModule.pull（SyncManager.pull 实例方法），行为一致。
           const pullChangeIdx = args.indexOf('--change');
-          const pullChangeName = pullChangeIdx >= 0 && args[pullChangeIdx + 1] ? args[pullChangeIdx + 1] : null;
+          const pullChangeName = pullChangeIdx >= 0 && args[pullChangeIdx + 1] && !String(args[pullChangeIdx + 1]).startsWith("--") ? args[pullChangeIdx + 1] : null;
           // 未连接明确提示不崩（acceptance：未连接平台输出明确提示）
           const smForCheck = new syncModule.SyncManager(dir);
           if (!smForCheck._getPlatform()) {
@@ -3231,7 +3505,7 @@ SillySpec platform — SillyHub 平台同步
           // 第一个非 flag 位置参数 → 唯一未决冲突自动选中。修复：旧实现盲取 platformArgs[0]，
           // flag 放前面时（resolve --keep-local --change x）把 '--keep-local' 当变更名去读冲突文件。
           const changeIdx = args.indexOf('--change');
-          let resolveName = changeIdx >= 0 && args[changeIdx + 1] ? args[changeIdx + 1] : null;
+          let resolveName = changeIdx >= 0 && args[changeIdx + 1] && !String(args[changeIdx + 1]).startsWith("--") ? args[changeIdx + 1] : null;
           if (!resolveName) {
             resolveName = platformArgs.find((a) => a && !a.startsWith('--')) || null;
           }
@@ -3297,7 +3571,7 @@ SillySpec platform — SillyHub 平台同步
             process.exit(1);
           }
           const reasonIdx = args.indexOf('--reason');
-          const reason = reasonIdx >= 0 && args[reasonIdx + 1] ? args[reasonIdx + 1] : undefined;
+          const reason = reasonIdx >= 0 && args[reasonIdx + 1] && !String(args[reasonIdx + 1]).startsWith("--") ? args[reasonIdx + 1] : undefined;
           await syncModule.reject(rejectName, reason, dir);
           break;
         }
@@ -3321,7 +3595,7 @@ SillySpec platform — SillyHub 平台同步
       // task review / stage review / module-map）+ 轻形状检查（required-evidence / endpoints）
       // 为一把伞——「新解析器写之前先过 schema」的统一落点。skip = 未生成不算失败。
       const vaChangeIdx = args.indexOf('--change');
-      const vaChange = vaChangeIdx >= 0 && args[vaChangeIdx + 1] ? args[vaChangeIdx + 1] : null;
+      const vaChange = vaChangeIdx >= 0 && args[vaChangeIdx + 1] && !String(args[vaChangeIdx + 1]).startsWith("--") ? args[vaChangeIdx + 1] : null;
       if (!vaChange) {
         console.error('用法: sillyspec validate --change <名> [--json]');
         console.error('  校验该变更的全部结构化产物（verify-facts/required-evidence/task reviews/stage reviews/endpoints + module-map）');
@@ -3350,7 +3624,7 @@ SillySpec platform — SillyHub 平台同步
       //   decisions list --change <c>——parseDecisions 只读视图（id/状态/类型/模块域/标题）。
       const decSub = filteredArgs[1];
       const decChangeIdx = args.indexOf('--change');
-      const decChange = decChangeIdx >= 0 && args[decChangeIdx + 1] ? args[decChangeIdx + 1] : null;
+      const decChange = decChangeIdx >= 0 && args[decChangeIdx + 1] && !String(args[decChangeIdx + 1]).startsWith("--") ? args[decChangeIdx + 1] : null;
       if (!decChange || !['add', 'list'].includes(decSub)) {
         console.error('用法: sillyspec decisions add --change <名> --id D-001 --title "…" [--version N] [--status confirmed] [--type architecture] [--domain x（可重复）] [--question/--answer/--anchor/--reject-reason/--revisit-when/--supersedes/--impacts/--note]\n  sillyspec decisions list --change <名>');
         process.exit(2);
@@ -3649,12 +3923,12 @@ SillySpec workflow — 工作流管理
         }
         // 解析 --project
         const projectIdx = filteredArgs.indexOf('--project');
-        const project = projectIdx !== -1 && filteredArgs[projectIdx + 1] ? filteredArgs[projectIdx + 1] : null;
+        const project = projectIdx !== -1 && filteredArgs[projectIdx + 1] && !String(filteredArgs[projectIdx + 1]).startsWith("--") ? filteredArgs[projectIdx + 1] : null;
         // 解析 --json（已在顶层解析）
         const isJson = json;
         // 解析 --change
         const changeIdx = filteredArgs.indexOf('--change');
-        const changeName = changeIdx !== -1 && filteredArgs[changeIdx + 1] ? filteredArgs[changeIdx + 1] : null;
+        const changeName = changeIdx !== -1 && filteredArgs[changeIdx + 1] && !String(filteredArgs[changeIdx + 1]).startsWith("--") ? filteredArgs[changeIdx + 1] : null;
 
         if (!project && wfName !== 'archive-impact') {
           console.error('❌ 请指定 --project，例如：--project sillyspec');
@@ -3757,7 +4031,7 @@ SillySpec modules — 模块文档管理
         // per-task 模块卡级联解析（token 成本优化 P0a）：execute「加载上下文」步的
         // {MODULE_RESOLVE_TABLE} 注入同源；独立命令供 agent/人随时查（细卡优先，防整读大卡）
         const mrChangeIdx = args.indexOf('--change');
-        const mrChange = mrChangeIdx >= 0 && args[mrChangeIdx + 1] ? args[mrChangeIdx + 1] : null;
+        const mrChange = mrChangeIdx >= 0 && args[mrChangeIdx + 1] && !String(args[mrChangeIdx + 1]).startsWith("--") ? args[mrChangeIdx + 1] : null;
         if (!mrChange) {
           console.error('用法: sillyspec modules resolve --change <名> [--spec-dir <path>] [--json]\n  输出 per-task 最优模块卡表（跨全部 _module-map.yaml 最长前缀匹配，细卡优先）');
           process.exit(2);
@@ -3765,7 +4039,8 @@ SillySpec modules — 模块文档管理
         assertSafeChangeName(mrChange, '--change 变更名');
         const mrSpecBase = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
         const { resolveChangeModuleCards, renderModuleResolveTable } = await import('./module-resolve.js');
-        if (filteredArgs.includes('--json')) {
+        if (json) {
+          // 全局解析器把 --json 收进顶层 json 变量、不进 filteredArgs——查 filteredArgs 恒 false（ql-20260911-029）
           const r = resolveChangeModuleCards({ cwd: dir, specBase: mrSpecBase, changeName: mrChange });
           console.log(JSON.stringify(r, null, 2));
         } else {
@@ -3818,7 +4093,7 @@ SillySpec modules — 模块文档管理
         const { registerRepoInLocalYaml } = await import('./local-register.js');
         let rrResult;
         try {
-          rrResult = registerRepoInLocalYaml(target.path, rrKey, absRepo);
+          rrResult = await registerRepoInLocalYaml(target.path, rrKey, absRepo);
         } catch (e) {
           console.error(`❌ 注册失败: ${e.message}`);
           process.exit(1);