sillyspec 3.28.8 → 3.28.10

package/src/run/command.js

@@ -30,7 +30,7 @@ import { outputStep, collectStageWaitHistory } from './prompt.js'
 import { completeStep, skipStep, waitStep, continueStep, synthesizeStepOutput } from './complete.js'
 import { runStage } from './stage.js'
 import { sanitizeDesc } from '../quicklog.js'
-import { ProgressManager } from '../progress.js'
+import { ProgressManager, resolveSessionIdentity } from '../progress.js'
 import { validateChangeExists, checkTransition } from '../stage-contract.js'
 import { READONLY_AUXILIARY_STAGES } from '../constants.js'
 import { stageRegistry, auxiliaryStages } from '../stages/index.js'
@@ -48,6 +48,7 @@ const VALUE_FLAGS = new Set([
   '--req', '--cause', '--solution', '--result', // quick 末步四字段参数（合成 --output，见 outputText 解析段）
   '--ql', // quick --cancel 显式指定 qlId（缺省读会话 guard.json）
   '--base', // scan diff 基线 commit（吃值；只在 run scan --diff 转发路径消费）
+  '--session', // 显式会话标识（吃值；2026-09-14-change-ownership-guards task-02 所有权三级解析最高优先级层，启动 claim 消费）
 ])
 
 /**
@@ -329,6 +330,10 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     process.exit(2)
   }
   const fromStepValue = getFlagValue('--from-step')
+  // 意图断言（坑 execute-concurrent-done-skips-next-wave 终解，2026-09-08 实证）：--done --step
+  // <名|序号> 显式声明本次要完成的步骤——CLI 校验与当前待完成步一致才放行。并发 --done 落到
+  // 错误 Wave（后到会话用旧摘要完成未实现的下一步）只有显式声明能硬拦（CLI 短进程无法读心）。
+  const stepAssertValue = getFlagValue('--step')
   const isConfirm = flags.includes('--confirm')
   const isSkipApproval = flags.includes('--skip-approval')
   const isWait = flags.includes('--wait')
@@ -622,6 +627,9 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // 历史写法，语义与「指定变更名」冲突，新用法建议改用 --linked-changes）
   let changeName = null
   let linkedChanges = []
+  // 机器自动关联溯源（坑 quick-single-change-auto-link）：resolveQuickLinkedChanges 单候选
+  // 信号门控命中时标记，guard 落 linkedChangesAuto，--done 归档闸对这类变更不触发轻量归档
+  let linkedAuto = []
   const changeValue = getFlagValue('--change')
   if (changeValue !== null) {
     changeName = changeValue
@@ -692,6 +700,11 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       if (!quickSessionId) {
         quickSessionId = 'quick-' + randomUUID().slice(0, 8)
         quickSidFresh = true
+        // 坑 quick-sync-block-filenotes-and-quicklog-mixed-commit 坑1③：新会话 ID 生成即打印
+        // 第一行——后续 agent-log push / spec-sync 等 best-effort 网络动作（平台慢时分钟级）
+        // 若把命令拖过 exec 超时，调用方仍能从输出头部拿到 sessionId 续用（--status / guard.json
+        // 核对），不会误开空壳新会话。
+        console.log(`📌 quick 会话已建立: ${quickSessionId}（后续若超时/中断，用 --change ${quickSessionId} 续用）`)
       }
       changeName = quickSessionId
     } else {
@@ -799,17 +812,29 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   const isAllowDelete = flags.includes('--allow-delete')
   const isForceBaseline = flags.includes('--force-baseline')
   const isForceRescan = flags.includes('--force-rescan')
+  // --no-docs（2026-09-14-quick-exit-tiered-gates task-02，no-docs-flag）：L2 门禁文档认领的显式
+  // 豁免布尔 flag（先例上方同款 includes 解析）——只影响 gate 画像 docClaim（exempt-no-docs）
+  // 与 [gate] 落账留痕，不改 status/exit code（D-003 advisory），审计链经 completeStep options 透传。
+  const isNoDocs = flags.includes('--no-docs')
+  // --skip-apply（2026-09-14-change-ownership-guards task-03，D-002@v1）：归档收口门（archive
+  // step3 归档移动前 applyWorktree checkOnly 探测未 apply 交付面）的显式跳过布尔 flag——
+  // 语义出口在 completeStep → handleArchiveConfirmStep → archiveChangeDirectory（task-02 只
+  // 注册白名单透传，本行补 includes 解析进 completeStep options，isNoDocs 同款先例）。
+  const isSkipApply = flags.includes('--skip-apply')
 
   // F10b（ql-20260818-010）：语义别名定向提示。did-you-mean 按编辑距离猜形近 flag，猜中的常是
   // 形近但语义错的（--title → --files，ql-20260818-003 负面③实证）。常见「语义别名」在此登记
   // 定向指引：命中时替代 did-you-mean 打印，引导到真正承载该语义的 flag/机制。
+  // 2026-09-14-change-ownership-guards task-02：原 '--session' 条目（quick 会话名提示）随
+  // --session 升格为真实 flag（所有权会话标识）而移除——提示只对未知 flag 生效，已知 flag
+  // 挂提示是死代码；'--session-id' 是最常见形近拼法，改挂新语义指引（所有权三级标识）。
   const FLAG_SEMANTIC_HINTS = {
     '--title': 'QUICKLOG 条目标题无独立参数——从 --output 的「需求：」字段自动提取（写成一句语义化短标题即可）',
     '--message': '结果摘要用 --output（quick 末步须含 需求：/根因：/方案：/结果： 四字段）',
     '--summary': '结果摘要用 --output（quick 末步须含 需求：/根因：/方案：/结果： 四字段）',
     '--result': '结果摘要用 --output（quick 末步须含 需求：/根因：/方案：/结果： 四字段）',
     '--name': 'quick 会话名由 CLI 自动分配（quick-<hash>），恢复会话用 --change <quick-session-id>；关联变更用 --linked-changes',
-    '--session': 'quick 会话名由 CLI 自动分配（quick-<hash>），恢复会话用 --change <quick-session-id>',
+    '--session-id': '会话标识用 --session <id>（所有权三级解析最高优先级层；缺省 env SILLYSPEC_SESSION_ID，再缺省 anon@<host> 机器级降级）',
     '--note': '文件括注用 --file-notes "path::注 || path::注"；启动时任务描述用 --input',
     '--notes': '文件括注用 --file-notes "path::注 || path::注"',
     '--desc': '启动时任务描述用 --input；QUICKLOG 标题从 --output「需求：」自动提取',
@@ -826,12 +851,16 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     '--req', '--cause', '--solution', '--result',
     '--spec-dir', '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
     '--files', '--file-notes', '--allow-new', '--allow-delete', '--force-baseline', '--force-rescan',
+    '--no-docs', // L2 门禁文档认领显式豁免（task-02：布尔 flag 不吃值，audit 链 docClaim → exempt-no-docs）
     '--json', '--dir', '--help',
     '--reopen', '--from-step', '--mode',
     '--deep', '--quick', '--standard', // scan profile 三档显式选择（scan-profile.js 从 argv 读；互斥见下方 PROFILE_FLAGS 检测）
     '--adopt-branch', // execute 显式收编既有 sillyspec/<change> 分支为 worktree 工作分支（坑 worktree-user-branch-conflict）
     '--diff', '--base', '--full', '--report', // scan diff（D-001：command.js 只补 flag，裸 token 解析归 index.js 子命令拦截）
     '--meta', // P1-3：渲染 SS-META 机器块（布尔 flag，不吃值）
+    '--session', // 显式会话标识（吃值，VALUE_FLAGS 同步登记；2026-09-14-change-ownership-guards task-02：启动 claim 消费，所有权三级解析最高优先级层）
+    '--takeover', // 所有权护栏显式强制接管（task-02 / FR-01：本层只注册透传，实际消费在 index.js apply/cleanup 子命令层——run 侧带上不报未知参数，语义出口在 worktree 命令）
+    '--skip-apply', // 归档收口跳过 apply 校验（task-02 只注册透传不改行为，消费归 task-03 archive 接线）
     '-h',
   ])
   for (let i = 0; i < flags.length; i++) {
@@ -894,6 +923,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     // D-002：guard 按 session 存（.runtime/quick-sessions/<sessionId>/guard.json）。
     // sessionId == changeName == quick-<uuid8>（上面参数解析已确定）。回退读旧单文件 quick-guard.json（task-03 前兼容）。
     let persistedLinked = null
+    let persistedAuto = null
     try {
       const sessionGuardFile = join(specRoot, '.runtime', 'quick-sessions', changeName, 'guard.json')
       const legacyGuardFile = join(specRoot, '.runtime', 'quick-guard.json')
@@ -901,15 +931,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         ? JSON.parse(readFileSync(sessionGuardFile, 'utf8'))
         : (existsSync(legacyGuardFile) ? JSON.parse(readFileSync(legacyGuardFile, 'utf8')) : null)
       if (g && Array.isArray(g.linkedChanges)) persistedLinked = g.linkedChanges
+      if (g && Array.isArray(g.linkedChangesAuto)) persistedAuto = g.linkedChangesAuto
     } catch {}
     if (persistedLinked) {
       linkedChanges = persistedLinked
+      // autoLinked 溯源同步恢复（--done 复用启动 guard 的关联时，归档闸同样要看到「机器猜的」标记）
+      if (persistedAuto) linkedAuto = persistedAuto
     } else {
-      linkedChanges = await resolveQuickLinkedChanges({
+      const resolved = await resolveQuickLinkedChanges({
         pm, cwd, specDir: specRoot, quickFiles,
         taskDescription: inputText || '',
         nonInteractive: isNonInteractive,
       })
+      linkedChanges = resolved.changes
+      linkedAuto = resolved.autoLinked
     }
   }
 
@@ -1011,12 +1046,27 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   }
 
   if (!progress) {
+    // ── 辅助阶段 default 行亲和（坑 default-empty-dir-materialized 配套，2026-09-14 用户反馈①）──
+    // default 行是辅助阶段（explore 等）不带 --change 启动时的进度容器（下方 isAuxiliary
+    // 兜底 'default'）。此前「续跑也锚回 default」靠的是 changes/default/ 目录在目录计数
+    // 解析里的存在感——目录停建后（initChange 对系统 key 不再物化）该隐式锚定失效，
+    // 「default 在途 + 恰好一个其他变更目录」会把辅助阶段挂到别人的变更行。这里显式化：
+    // 无 --change 且 default 行有在途（非 completed）的本阶段 steps → 锚回 default。
+    // 显式 --change 恒优先；非辅助阶段（brainstorm/execute 等）从不落 default，不适用。
+    if (!changeName && isAuxiliary) {
+      const affinity = resolveAuxiliaryDefaultAffinity(pm, cwd, stageName)
+      if (affinity) {
+        changeName = affinity
+        progress = pm.read(cwd, affinity)
+      }
+    }
     // ── done-like 存在性守卫（坑 done-phantom-change-silent-create，2026-09-04 事故元凶①）──
     // --done/--skip/--wait/--continue/--reset/--reopen 都预设「目标 change 已存在于当前进度库」。
     // 此前 !progress 时无条件 initChange 静默新建——接管指针切库/换库后 --change 指向旧库的
     // 变更名，新库里凭空建幻影变更再把动作记上去。目标已物化（changes/ 目录或 quick 会话
     // guard 存在）仍放行走下方 initChange 自愈（DB 重建/迁移后从目录物化是合法恢复路径）。
-    if (isDone || isSkip || isWait || isContinue || isReset || isReopen) {
+    // !progress 前置：上方亲和已锚到 default 行（DB 在途）时目标已确证存在，不走磁盘物化判据。
+    if (!progress && (isDone || isSkip || isWait || isContinue || isReset || isReopen)) {
       const actionFlag = isDone ? '--done' : isSkip ? '--skip' : isWait ? '--wait'
         : isContinue ? '--continue' : isReset ? '--reset' : '--reopen'
       const guardTarget = changeName || resolveChangeNameAuto(cwd, specRoot)
@@ -1042,6 +1092,13 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
         }
         if (stageName === 'quick' || /^quick-[0-9a-f]{8}$/.test(guardTarget || '')) {
           console.error(`   ③ quick 会话跨进程恢复须带 --change <quick-session-id>；本库无该会话 guard——会话可能属于旧库`)
+        } else if (stageName === 'explore' && activeList.includes('default')) {
+          // 坑 explore-done-change-default-hint（2026-09-14 用户反馈①）：explore 不带 --change 启动
+          // 时进度按约定挂 default 变更行（isAuxiliary 兜底），多活跃变更库（多 agent 并行常态）
+          // 目标解析失败被拒时，③ 只指 brainstorm 新建路径——对「进度就在 default 行」的 explore
+          // 会话是误导（用户实证要靠 --status 才摸出来）。default 在活跃列表 = 有辅助阶段在途，
+          // 补指向自身的 --change default 出口。
+          console.error(`   ③ explore 阶段进度默认挂在 default 变更行——本库 default 在活跃列表，重试加 --change default`)
         } else {
           console.error(`   ③ 确要新建变更：先 sillyspec run brainstorm --change <名>（不带 ${actionFlag}）`)
         }
@@ -1190,6 +1247,28 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // 注册变更到全局活跃列表（如果尚未注册）
   if (effectiveChange) {
     pm.registerChange(cwd, effectiveChange)
+    // ── 所有权首建 claim（2026-09-14-change-ownership-guards task-02 / FR-01 / D-001@v1）──
+    // run <stage> 启动即认领 owner（claimChangeOwner 守卫语义：已有值不覆盖——他人持有不抢
+    // 也不拒；拒绝语义只锁接管类操作，见 index.js apply/cleanup/assess 接线）。会话标识三级：
+    // quick 会话=changeName 本身（quick-<8hex>，既有 sessionId 机制——guard 按 change 名落盘
+    // 天然跨进程，selfSession==changeName 恒 self）；full-flow=--session > env
+    // SILLYSPEC_SESSION_ID > anon@host 机器级降级（降级时一次性教学 warning）。
+    // default 容器行不认领：辅助阶段共享容器非真实变更，挂伪所有权没有消费者还添噪声。
+    // fail-open：claim 失败不阻断启动（护栏判定退回 no-owner 放行）。
+    try {
+      if (effectiveChange !== 'default') {
+        const ident = resolveSessionIdentity({
+          flagSession: getFlagValue('--session'),
+          quickChangeName: stageName === 'quick' ? effectiveChange : null,
+          // anon 降级教学 marker 落盘根用 dirname(specRoot)（锚定后的主仓根）而非裸 cwd：
+          // worktree 副本 cwd（execute 在 .sillyspec/.runtime/worktrees/<c>/ 内跑）会把
+          // marker mkdir 进副本 .runtime（worktree-execute-spec-drift AC-A6 副本零写入实证），
+          // 且副本随 cleanup 删除、marker 永不跨会话去重——落到持久主仓根才是教学降频语义。
+          cwd: dirname(specRoot),
+        })
+        pm.claimChangeOwner(cwd, effectiveChange, ident.session)
+      }
+    } catch { /* claim 失败不阻断启动 */ }
   }
 
   // --reset
@@ -1306,7 +1385,26 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       } catch { /* guard 损坏 → 下面按找不到报错 */ }
     }
     if (!qlId) {
-      console.error(`❌ 无法定位会话 ${cancelSessionRaw} 的 qlId（guard.json 缺失/损坏）——显式传 --ql <ql-xxx>（QUICKLOG 条目头）`)
+      // 坑 quick-cancel-blind-after-quicklog-rotation ②③（2026-09-16 实证）：空壳会话
+      //（启动即被拒/未写任何条目）无 ql-ID 可传，「显式传 --ql」指引逻辑上不可执行。
+      // 两层出口：① guard 缺失但进度库会话行零步骤完成 → 空壳直清（进度注销+目录清理即
+      // 成功，条目定位对无条目会话本无意义）；② 仍有疑虑时 --force 跳过条目清理强清。
+      const forceCancel = flags.includes('--force')
+      let emptyShell = false
+      try {
+        const sessProgress = pm.read(cwd, cancelSessionRaw)
+        const qSteps = sessProgress?.stages?.quick?.steps
+        const doneCount = Array.isArray(qSteps) ? qSteps.filter(s => s?.status === 'completed' || s?.status === 'skipped').length : 0
+        emptyShell = doneCount === 0
+      } catch { /* 读不到进度 → 按非空壳走原报错 */ }
+      if (forceCancel || emptyShell) {
+        try { pm.unregisterChange(cwd, cancelSessionRaw) } catch { /* 无行可注销不算失败 */ }
+        try { rmSync(join(resolveQuickSessionsDir(platformOpts, specBase), cancelSessionRaw), { recursive: true, force: true }) } catch { /* 目录不存在即无事 */ }
+        console.log(`🗑️ 已${emptyShell ? '清空壳会话（零步骤完成，无 QUICKLOG 条目可清）' : '强制取消（--force，跳过条目清理）'}: ${cancelSessionRaw}`)
+        console.log('   进度行注销 + 会话目录清理完成')
+        return
+      }
+      console.error(`❌ 无法定位会话 ${cancelSessionRaw} 的 qlId（guard.json 缺失/损坏）——显式传 --ql <ql-xxx>（QUICKLOG 条目头）；确认该会话确无条目可清时可用 --force 跳过条目清理`)
       process.exit(1)
     }
     let gitUser = 'unknown'
@@ -1391,18 +1489,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     }
   }
 
-  // --file-notes 非末步静默忽略前置 warn（坑 quick-file-notes-nonfinal-ignored，2026-08-22 实证：
-  // step2 --done 传 --file-notes 被静默丢——CLI 短进程，注入随进程结束即丢，白传一轮）。
-  // 放此处：ensureStageSteps 之后 progress 已就绪可判步骤状态；仅 quick + 带了 --file-notes +
-  // 非「唯一 pending 的末步 --done」时提示。末步 --done 是消费点，不提示。
+  // --file-notes 非末步硬拒绝（坑 quick-file-notes-nonfinal-ignored → quick-sync-block
+  // 坑2 升级，2026-09-13 实证：warn 版仍「先收下再丢弃再告知」——9 条括注静默丢失需凭记忆
+  // 重传）。改为 exit 2 直接拒绝：调用方立刻知道参数传错了时机，不做静默丢弃。末步 --done
+  //（唯一 pending）是消费点，正常消费。
   if (quickFileNotes !== '' && stageName === 'quick' && !isStatus) {
     try {
       const qSteps = progress?.stages?.quick?.steps
       const pendingCount = Array.isArray(qSteps) ? qSteps.filter(st => ['pending', 'in-progress'].includes(st?.status)).length : 0
       if (!isDone || pendingCount > 1) {
-        console.warn(`⚠️ --file-notes 本次不会生效：它只在 quick 末步（暂存和更新记录）--done 时随收尾消费——CLI 是短进程，本次注入随进程结束即丢。请在末步 --done 时连同 --output 一起传。`)
+        console.error(`❌ --file-notes 此时不生效（拒绝执行而非静默丢弃）：它只在 quick 末步 --done 时随收尾消费——CLI 是短进程，非末步注入随进程结束即丢。`)
+        console.error(`   请去掉 --file-notes 重跑本条命令；括注内容留到末步 --done 时连同 --output 一起传。`)
+        process.exit(2)
       }
-    } catch { /* 判定失败不提示（fail-open） */ }
+    } catch { /* 判定失败不阻断（fail-open 维持旧行为） */ }
   }
 
   // --status
@@ -1447,11 +1547,29 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       }
     }
     const doneAnswer = getFlagValue('--answer')
-    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, doneAnswer, isForceBaseline, isAllowNew, isAllowDelete, quickFiles })
+    // isSkipApply/sessionFlag（task-03）：--skip-apply 归档收口跳过 + --session 所有权会话标识，
+    // 随 completeStep options 透传（isNoDocs 同款链路）——消费点 archive/quick 收尾 handler。
+    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, doneAnswer, isForceBaseline, isAllowNew, isAllowDelete, isNoDocs, isSkipApply, sessionFlag: getFlagValue('--session'), quickFiles, stepAssert: stepAssertValue })
   }
 
   // 默认：输出当前步骤
-  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isAllowDelete, isForceBaseline, isForceRescan, linkedChanges, taskDescription: inputText, adoptBranch: stageName === 'execute' && flags.includes('--adopt-branch') })
+  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts, { quickFiles, isAllowNew, isAllowDelete, isForceBaseline, isForceRescan, linkedChanges, linkedChangesAuto: linkedAuto, taskDescription: inputText, adoptBranch: stageName === 'execute' && flags.includes('--adopt-branch') })
+}
+
+/**
+ * 辅助阶段 default 行亲和：default 行有在途（非 completed、steps 已物化）的本阶段时返回 'default'。
+ * steps>0 门槛排除「从未跑过」的空壳行（initChange 播的 pending 空表）——那种行不是在途会话，
+ * 不锚（防凭空把 --done 记上去）。只读不抛（无行/读失败 → null）。目录停建后辅助阶段续跑的
+ * 显式锚定（见 !progress 块内注释）。completed 永不锚（辅助阶段收尾会 reset 回 pending 可重跑，
+ * 见 gates.js auxiliary 重置——reset 后 pending+steps>0 照样锚，即「下一轮 explore 续用 default 行」）。
+ */
+function resolveAuxiliaryDefaultAffinity(pm, cwd, stageName) {
+  try {
+    const p = pm.read(cwd, 'default')
+    const st = p && p.stages && p.stages[stageName]
+    if (st && st.status && st.status !== 'completed' && Array.isArray(st.steps) && st.steps.length > 0) return 'default'
+  } catch { /* 读失败不猜（fail-closed，走原解析链） */ }
+  return null
 }
 
 /**