sillyspec 3.27.1 → 3.27.5

package/src/plan-adopt-waves.js

@@ -0,0 +1,126 @@
+/**
+ * plan-adopt-waves.js — `sillyspec plan-adopt-waves` 把 plan.md 的 Wave 段一键重排为
+ * depends_on 拓扑分组（坑 wave-manual-mismatch-noise，2026-08-24 用户反馈二期：主控手排
+ * Wave 与 CLI 拓扑比对不一致只能手动改；依赖方向违规修复后，本命令给一条零手写出路）。
+ *
+ * 行为：
+ *   - depMap（tasks/*.md 的 depends_on，collectTaskDepMap 与 postcheck 同源）→ topoSortWaves
+ *   - 重写 plan.md 的 `## Wave N` 段块（段内按编号排序；首段「并行，无依赖」、其余「依赖前序 Wave」）
+ *   - 无显式 Wave 标题 → 插在「## 任务总表」前（无总表则文末追加）
+ *   - best-effort 同步任务总表的 W 列（仅认 7 列模板行；不匹配的行 warn 不强改）
+ *   - Wave 段内若含非引用内容（正文/表格）→ 拒绝重写（防误删），提示先手动整理
+ *   - 写后复跑 validateBlueprintConsistency 打印结果（防 adopt 把手工安全串行收敛出
+ *     同 Wave 共享路径冲突——topo 只看依赖不看文件重叠）
+ *   - --dry-run 只打印将写入的 Wave 段不落盘；幂等（重复跑产出相同结构）；行尾统一 LF
+ */
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { topoSortWaves, collectTaskDepMap, validateBlueprintConsistency } from './stages/plan-postcheck.js'
+
+const WAVE_HEADING_RE = /^#+\s*Wave\s+\d+/i
+const TASK_REF_RE = /^[-*]\s+(?:\[[ x]\]\s*)?task-\d+\s*[:：\s]*$/i
+const LEGACY_TASK_REF_RE = /^[-*]\s*\[[ x]\]\s*task-\d+/i
+const SUMMARY_HEADING_RE = /^#+\s*任务总表/
+
+/** 渲染标准 Wave 段块（段落间空行分隔，结尾不带多余空行——由调用方控制拼接） */
+function renderWaveBlock(waves) {
+  const L = []
+  waves.forEach((wave, i) => {
+    const sorted = [...wave].sort((a, b) =>
+      parseInt(String(a).replace(/\D/g, ''), 10) - parseInt(String(b).replace(/\D/g, ''), 10))
+    L.push(`## Wave ${i + 1}（${i === 0 ? '并行，无依赖' : '依赖前序 Wave'}）`)
+    for (const t of sorted) L.push(`- ${t}`)
+    if (i < waves.length - 1) L.push('')
+  })
+  return L
+}
+
+/** best-effort 更新任务总表 W 列：仅认 `| task-XX | … | W1 | … |` 形态的 7+ 列模板行 */
+function updateSummaryWaveColumn(lines, waveOf) {
+  let inSummary = false
+  let updated = 0
+  let skipped = 0
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (/^#+\s/.test(line)) { inSummary = SUMMARY_HEADING_RE.test(line); continue }
+    if (!inSummary) continue
+    const m = line.match(/^\|\s*task-(\d+)\s*\|/)
+    if (!m) continue
+    const cells = line.split('|')
+    // 模板 7 列：| 编号 | 任务 | Wave | 优先级 | 依赖 | 覆盖 FR/D | 说明 | → split 后首尾空串
+    if (cells.length < 8 || !/^\s*W\d+\s*$/.test(cells[3] || '')) { skipped++; continue }
+    const taskId = `task-${String(m[1]).padStart(2, '0')}`
+    const waveIdx = waveOf.get(taskId)
+    if (waveIdx === undefined) { skipped++; continue }
+    cells[3] = ` W${waveIdx + 1} `
+    lines[i] = cells.join('|')
+    updated++
+  }
+  return { updated, skipped }
+}
+
+/**
+ * @param {{ changeDir: string, dryRun?: boolean }} opts
+ * @returns {{ ok: boolean, error?: string, waves?: string[][], planPath: string, dryRun: boolean,
+ *             waveBlock?: string[], tableRowsUpdated?: number, tableRowsSkipped?: number,
+ *             postcheck?: { errors: string[], warnings: string[] } }}
+ */
+export function adoptPlanWaves({ changeDir, dryRun = false }) {
+  const planPath = join(changeDir, 'plan.md')
+  if (!existsSync(planPath)) return { ok: false, error: `plan.md 不存在: ${planPath}`, planPath, dryRun }
+  const tasksDir = join(changeDir, 'tasks')
+  if (!existsSync(tasksDir)) return { ok: false, error: `tasks/ 目录不存在: ${tasksDir}`, planPath, dryRun }
+  const depMap = collectTaskDepMap(tasksDir)
+  if (depMap.size === 0) return { ok: false, error: 'tasks/ 下没有 task-NN.md 卡片，无从推导 Wave 分组', planPath, dryRun }
+
+  const { waves, error: topoError } = topoSortWaves(depMap)
+  if (topoError) return { ok: false, error: `拓扑排序失败: ${topoError}`, planPath, dryRun }
+
+  const original = readFileSync(planPath, 'utf8')
+  const lines = original.split(/\r?\n/)
+  const waveBlock = renderWaveBlock(waves)
+  const waveOf = new Map()
+  waves.forEach((ws, i) => { for (const t of ws) waveOf.set(t, i) })
+
+  const firstWaveIdx = lines.findIndex(l => WAVE_HEADING_RE.test(l))
+  if (firstWaveIdx >= 0) {
+    // Wave 段块末尾 = 最后一个 Wave 标题之后连续的任务引用行（空行容忍但不断段；
+    // 遇非 Wave 标题即止）。段内混入非引用内容 → 拒绝重写（防误删正文/表格）。
+    let endIdx = firstWaveIdx
+    for (let i = firstWaveIdx; i < lines.length; i++) {
+      if (WAVE_HEADING_RE.test(lines[i])) { endIdx = i; continue }
+      if (TASK_REF_RE.test(lines[i]) || LEGACY_TASK_REF_RE.test(lines[i])) { endIdx = i; continue }
+      if (lines[i].trim() === '') continue
+      if (/^#+\s/.test(lines[i])) break
+      return { ok: false, error: `Wave 段内含非引用内容（第 ${i + 1} 行「${lines[i].slice(0, 40)}」）——为防误删拒绝重写，请先把 Wave 段整理为纯 "- task-XX" 引用行`, planPath, dryRun }
+    }
+    lines.splice(firstWaveIdx, endIdx - firstWaveIdx + 1, ...waveBlock)
+  } else {
+    // 无显式 Wave 标题：插在「## 任务总表」前；无总表则文末追加
+    const summaryIdx = lines.findIndex(l => SUMMARY_HEADING_RE.test(l))
+    if (summaryIdx >= 0) {
+      lines.splice(summaryIdx, 0, ...waveBlock, '')
+    } else {
+      while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop()
+      lines.push('', ...waveBlock)
+    }
+  }
+
+  const { updated, skipped } = updateSummaryWaveColumn(lines, waveOf)
+  const content = lines.join('\n').replace(/\n*$/, '\n')
+
+  if (dryRun) {
+    return { ok: true, waves, planPath, dryRun: true, waveBlock, tableRowsUpdated: updated, tableRowsSkipped: skipped }
+  }
+
+  writeFileSync(planPath, content, 'utf8')
+  // 复跑 blueprint 一致性（advisory 打印）：topo 只看依赖不看文件重叠——adopt 可能把手工
+  // 安全串行收敛出同 Wave 共享路径冲突，立即暴露而非留到 execute 撞
+  let postcheck = null
+  try {
+    postcheck = validateBlueprintConsistency(changeDir)
+  } catch (e) {
+    postcheck = { errors: [`复跑校验异常: ${e?.message || e}`], warnings: [] }
+  }
+  return { ok: true, waves, planPath, dryRun: false, waveBlock, tableRowsUpdated: updated, tableRowsSkipped: skipped, postcheck }
+}

package/src/quicklog.js

@@ -32,13 +32,15 @@ const sleep = (ms) => new Promise(r => setTimeout(r, ms))
  * 与 rename 之间），相比旧实现的必现双进已可忽略。
  * @param {string} lockPath 锁文件路径（建议与被保护文件同目录）
  * @param {() => (any|Promise<any>)} fn 临界区
- * @param {{staleMs?:number, timeoutMs?:number, retryMs?:number}} opts
+ * @param {{staleMs?:number, timeoutMs?:number, retryMs?:number, content?:string}} opts
+ *   content：锁文件内容（默认 pid-randomId）。供超时报错时展示持有者语义（如 apply 锁写
+ *   {pid, changeName}）——仅展示用途，抢占/偷锁逻辑只比对内容一致性不解析语义。
  */
 export async function withFileLock(lockPath, fn, opts = {}) {
-  const { staleMs = 30000, timeoutMs = 10000, retryMs = 50 } = opts
+  const { staleMs = 30000, timeoutMs = 10000, retryMs = 50, content = null } = opts
   mkdirSync(dirname(lockPath), { recursive: true })
   const start = Date.now()
-  const myId = `${process.pid}-${randomBytes(6).toString('hex')}`
+  const myId = content || `${process.pid}-${randomBytes(6).toString('hex')}`
   let fd = null
   // 抢锁循环
   while (true) {
@@ -174,6 +176,9 @@ function buildPushPayloadFromRaw(rawBlock, { ql_id, author_raw, status, linked_c
     payload.timestamp = parts[1] || null
     payload.title = parts.slice(2).join('|').trim() || payload.title
   }
+  // 顶层标签白名单（^ 行首锚定）：D-004@v1 根因块嵌套四子字段（- 现象：/- 根因：/- 护栏：/- 证据： 列表行）
+  // 因「- 」前缀不匹配本正则——它们是根因块正文内的列表行续行，不是新顶层标签，经 lastLabel 挂载
+  // 进 body_sections[根因]（见下方 inFiles 复位注释）。顶层四字段边界解析不受影响（R-03）。
   const labelRe = /^(状态|关联变更|文件|审计|需求|根因|方案|结果)\s*[：:]\s*(.*)$/
   const bulletRe = /^-\s+(.*)$/
   let inFiles = false
@@ -190,7 +195,9 @@ function buildPushPayloadFromRaw(rawBlock, { ql_id, author_raw, status, linked_c
       else if (label === '关联变更') { payload.linked_changes = value.split(/[，,、+；;]/).map(s => s.trim()).filter(Boolean); inLinked = true; inFiles = false }
       else if (label === '文件') { if (value) payload.files.push(...value.split(/[，,、+；;]/).map(s => s.trim()).filter(Boolean).map(p => ({ path: p, note: null }))); inFiles = true; inLinked = false }
       else if (label === '审计') { /* D-8 advisory 行：只进 raw_block 不进结构化段（body_sections 不扩 schema），并阻断续行误挂 */ lastLabel = null; inFiles = false; inLinked = false }
-      else { payload.body_sections[label] = value; lastLabel = label }
+      // 进入 需求/根因/方案/结果 字段块须关闭 inFiles/inLinked 续行模式（task-07 / D-004@v1）：否则根因块内
+      // 嵌套子字段列表行（- 现象：… 等）会命中下方「文件 bullet」分支被劫进 payload.files，从根因正文截断丢失。
+      else { payload.body_sections[label] = value; lastLabel = label; inFiles = false; inLinked = false }
       continue
     }
     if (bulletRe.test(stripped) && inFiles) {
@@ -265,10 +272,18 @@ export function deriveTitleFromLinkedChange(specBase, change) {
     try { content = readFileSync(join(specBase, 'changes', change, f), 'utf8') } catch { continue }
     const m = content.match(/^#\s+(.+?)\s*$/m)
     if (!m) continue
-    const raw = m[1].trim()
-    // 标题惯例「# 提案书（Proposal）— <desc>」「# 设计文档（Design）— <desc>」→ 取破折号后的 desc
+    let raw = m[1].trim()
+    // 标题惯例「# 提案书（Proposal）— <desc>」「# 设计文档（Design）— <desc>」→ 取破折号后的 desc。
+    // 固定前缀显式剥（坑 linked-task-placeholder-title，2026-08-22 实证：标题「# 提案书（Proposal）:
+    // xxx」或「# 提案书（Proposal）」无破折号时 dash 匹配失败，整串前缀落进 tasks.md 追加行）——
+    // 先剥固定模板词（含全/半角冒号分隔形态），再剥破折号；剥完为空（纯模板标题）继续找下一文档
+    for (const prefix of [/^提案书（Proposal）\s*[：:—\-]?\s*/, /^设计文档（Design）\s*[：:—\-]?\s*/, /^Proposal\s*[：:—\-]?\s*/i, /^Design\s*[：:—\-]?\s*/i]) {
+      raw = raw.replace(prefix, '').trim()
+    }
+    if (!raw) continue
     const dash = raw.match(/[—-]\s*(.+)$/)
-    return dash ? dash[1].trim() : raw
+    const title = dash ? dash[1].trim() : raw
+    if (title) return title
   }
   return ''
 }
@@ -324,6 +339,37 @@ export function parseFileNotes(raw) {
     .filter(Boolean)
 }
 
+/**
+ * 校验 --file-notes 原文格式（坑 quick-file-notes-format-silent，2026-08-24 用户反馈二期②：
+ * 多文件分隔符是 `||` 双竖线，写错成 `|`/`,` 时整段被当成第一个文件的括注静默落盘，只能手工修
+ * QUICKLOG）。命令入口 fail-fast 用：每个 `||` 段必须是 `path::括注`（`::` 必填，括注可空）；
+ * 括注内再出现 `::` 视为疑似漏写 `||` 分隔符。返回问题清单供调用方拼报错。
+ * @param {string} raw
+ * @returns {{ ok: boolean, problems: Array<{ seg: string, reason: string, hint: string }> }}
+ */
+export function validateFileNotesFormat(raw) {
+  const problems = []
+  if (!raw) return { ok: true, problems }
+  for (const seg of String(raw).split('||')) {
+    const s = seg.trim()
+    if (!s) continue
+    const idx = s.indexOf('::')
+    if (idx === -1) {
+      problems.push({ seg: s, reason: '缺 `::` 路径/括注分隔符', hint: '格式为 path::括注；不要括注也要写 path::（括注可空）' })
+      continue
+    }
+    const path = s.slice(0, idx).trim()
+    if (!path) {
+      problems.push({ seg: s, reason: '`::` 前路径为空', hint: '格式为 path::括注' })
+      continue
+    }
+    if (s.slice(idx + 2).includes('::')) {
+      problems.push({ seg: s, reason: '括注内出现 `::`', hint: '疑似多文件漏写 `||` 分隔符（双竖线）——多文件写法：path1::括注1 || path2::括注2' })
+    }
+  }
+  return { ok: problems.length === 0, problems }
+}
+
 // 结果块必填字段（quick step3 --done --output 的结构化结果模板，见 src/stages/quick.js）。
 // 4 个必填字段标签从 manifest 同源(stage-contract-spec.js quick.result-labels),prompt 事前契约与本校验单源。
 const RESULT_REQUIRED_LABELS = getRule('quick.result-labels').data.literals
@@ -336,6 +382,8 @@ const RESULT_REQUIRED_LABELS = getRule('quick.result-labels').data.literals
  * @returns {{ ok: boolean, missing: string[] }} ok=true 通过；missing=缺失的字段名列表
  */
 export function validateQuickResult(text) {
+  // 子串包含判定：根因块含嵌套四子字段列表行（- 现象：… 等，task-07 / D-004@v1 合法形态）时，
+  // 顶层四标签仍须齐备（模板契约），嵌套行不影响判定（「- 」前缀不构成顶层标签，亦不缺字段）。
   const missing = RESULT_REQUIRED_LABELS.filter(label => !String(text || '').includes(label))
   return { ok: missing.length === 0, missing }
 }
@@ -478,6 +526,9 @@ async function checkTaskCheckbox(specBase, change, qlId) {
 // 前缀」或正则 split(/(?=需求：|根因：|方案：|结果：)/)）因前导是「/|( 等非边界字符而跳过。严格失败
 // （如真实标签前导是「，」这类弱标点）退回宽松顺序扫描（上一标签之后首次出现）。缺标签返回 null → 落单行
 // 兜底（--done 契约校验仍会拦缺字段）。残余边界：正文引用标签且前导恰好是空白/句末标点时仍可能错位。
+// task-07 / D-004@v1 声明：本切分只作用于「单行四字段压缩归一」路径，嵌套四子字段（- 现象：/- 根因：/
+// - 护栏：/- 证据： 列表行）必须以多行列表行形态写入根因块正文——按序扫描先命中顶层「根因：」标签，
+// 其后的嵌套「- 根因：」等字样落在根因字段正文内不构成新边界，无需改动三个边界函数即天然兼容（Grill C-15）。
 function isFieldBoundary(body, idx) {
   if (idx <= 0) return true
   const prev = body[idx - 1]
@@ -559,6 +610,9 @@ function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes
       if (segs) body = segs.join('\n')
     }
     // 多行结果（结构化 需求/根因/方案/结果 字段块）：逐行插入为独立字段行。
+    // 根因块嵌套四子字段（- 现象：/- 根因：/- 护栏：/- 证据： 列表行，D-004@v1 postmortem 形态）属
+    // 根因块正文：在此随多行结果逐行原样落盘（带「- 」前缀、保序含换行），不被字段边界扫描误切——
+    // 单行归一切分只认「- 」前缀之外的需求：/根因：/方案：/结果： 标签，嵌套行天然不参与边界判定。
     // 单行结果：保持「结果：<一句话>」一行，向后兼容简单用例。
     const resultLines = /\r?\n/.test(body)
       ? body.split(/\r?\n/).filter(l => l.trim() !== '')

package/src/run/command.js

@@ -23,7 +23,7 @@ import { basename, join, resolve, dirname } from 'node:path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, PLATFORM_MANAGED_FILENAME } from './shared.js'
+import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, isSelfReferentialSpecRoot, PLATFORM_MANAGED_FILENAME } from './shared.js'
 import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep } from './prompt.js'
 import { completeStep, skipStep, waitStep, continueStep } from './complete.js'
@@ -163,6 +163,9 @@ sillyspec run ${stageName}${stage && stage.title ? ` — ${stage.title}` : ''}${
  * sillyspec run <stage> 主命令
  */
 export async function runCommand(args, cwd, specDir = null, opts = {}) {
+  // 原始 cwd 快照（下方 cwd 纠正前）：agent 在子目录启动时，其会话 transcript 挂在子目录
+  // 对应的 harness 项目目录下，agent-log 探测须用原始 cwd（纠正后的是项目根，探测会扑空）
+  const invokedCwd = cwd
   // W1-B: run <stage> 暂不支持 --json。之前 --json 进 knownFlags 白名单却从不读取（静默吞），
   // agent 按 gate/derive 契约期望 envelope 实则拿到混合人类文本。显式 fail-fast 杜绝歧义；
   // 完整 run envelope 待 outputStep 重构（W6）后支持（prompt + nextAction 结构化）。
@@ -316,19 +319,27 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       try {
         const { readFileSync } = await import('fs')
         const saved = JSON.parse(readFileSync(platformOptsFile, 'utf8'))
-        if (saved.specRoot) platformOpts.specRoot = saved.specRoot
-        if (saved.runtimeRoot) platformOpts.runtimeRoot = saved.runtimeRoot
-        if (saved.workspaceId) platformOpts.workspaceId = saved.workspaceId
-        if (saved.scanRunId) platformOpts.scanRunId = saved.scanRunId
-        // 平台模式 fail-fast：文件存在但缺少 specRoot
-        if (!platformOpts.specRoot && !platformOpts.runtimeRoot) {
-          console.error(`❌ 平台模式参数文件存在但缺少 specRoot/runtimeRoot: ${platformOptsFile}`)
-          console.error('   可能原因：platform-scan.json 损坏或写入不完整')
-          console.error('   解决：重新运行首次 scan 并传入 --spec-root')
-          process.exit(2) // 环境错（平台文件损坏）→ exit 2
+        // 自指指针免疫（FR-4，变更 2026-08-23-repo-native-spec-backfill）：saved.specRoot 经
+        // realpath 解析回本地 .sillyspec（repo-native junction 回环，旧模板投毒残留）→ 整体
+        // 忽略恢复（specRoot/runtimeRoot/workspaceId/scanRunId 全不回填，platformOpts 保持
+        // 无平台参数状态），按本地模式运行——内置 sync 走本地链路，specRoot 保持本地取值链。
+        if (isSelfReferentialSpecRoot(cwd, saved.specRoot)) {
+          console.warn(`⚠️ 检测到自指平台指针（repo-native junction 回环，specRoot 指回本地 .sillyspec），已忽略并按本地模式运行: ${platformOptsFile}`)
+        } else {
+          if (saved.specRoot) platformOpts.specRoot = saved.specRoot
+          if (saved.runtimeRoot) platformOpts.runtimeRoot = saved.runtimeRoot
+          if (saved.workspaceId) platformOpts.workspaceId = saved.workspaceId
+          if (saved.scanRunId) platformOpts.scanRunId = saved.scanRunId
+          // 平台模式 fail-fast：文件存在但缺少 specRoot
+          if (!platformOpts.specRoot && !platformOpts.runtimeRoot) {
+            console.error(`❌ 平台模式参数文件存在但缺少 specRoot/runtimeRoot: ${platformOptsFile}`)
+            console.error('   可能原因：platform-scan.json 损坏或写入不完整')
+            console.error('   解决：重新运行首次 scan 并传入 --spec-root')
+            process.exit(2) // 环境错（平台文件损坏）→ exit 2
+          }
+          // 恢复成功：更新 specRoot（初始值可能是 cwd/.sillyspec，恢复后应为真实 specDir）
+          specRoot = platformOpts.specRoot || specRoot
         }
-        // 恢复成功：更新 specRoot（初始值可能是 cwd/.sillyspec，恢复后应为真实 specDir）
-        specRoot = platformOpts.specRoot || specRoot
       } catch (e) {
         console.error(`❌ 平台模式参数文件读取失败: ${platformOptsFile}`)
         console.error(`   错误: ${e.message}`)
@@ -346,12 +357,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   if (!platformOpts.specRoot && !platformOpts.runtimeRoot && !platformFileExists) {
     const decl = checkPlatformManaged(cwd)
     if (decl) {
-      console.error(`❌ 平台接管声明生效：本项目已由平台托管（原 specRoot: ${decl.specRoot || '(未记录)'}），但恢复指针缺失，拒绝静默回退本地模式。`)
-      console.error(`   声明文件: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
-      console.error('   恢复：① 重跑平台 scan/init（带 --spec-root）重建指针；② 确认不再使用平台：sillyspec platform disconnect（删除接管声明）；③ 显式 --spec-dir <路径> 临时指定目录。')
-      // exit(1) 而非邻近环境错的 exit(2)：这是"状态保护阻断"（对齐 PointerUnreachableError
-      // 顶层 catch 语义），非"用法/环境错"——见 design.md §5.3 v2 复审观察 (a)
-      process.exit(1)
+      // 陈旧自指声明降级（FR-4，变更 2026-08-23-repo-native-spec-backfill）：decl.specRoot 经
+      // realpath 解析回本地 .sillyspec（repo-native junction 投毒残留、指针已被清理）→ 视为
+      // 陈旧声明，warn 后按本地模式继续（不 exit 1）——声明描述的"平台接管"物理上指向本地
+      // .sillyspec，无跨库状态分裂风险；非自指声明维持 fail-closed 原样（状态保护阻断）。
+      if (isSelfReferentialSpecRoot(cwd, decl.specRoot)) {
+        console.warn(`⚠️ 检测到陈旧的自指平台接管声明（repo-native junction 回环，原 specRoot 指回本地 .sillyspec），已降级并按本地模式运行；可 sillyspec platform disconnect 清理残留声明: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
+      } else {
+        console.error(`❌ 平台接管声明生效：本项目已由平台托管（原 specRoot: ${decl.specRoot || '(未记录)'}），但恢复指针缺失，拒绝静默回退本地模式。`)
+        console.error(`   声明文件: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
+        console.error('   恢复：① 重跑平台 scan/init（带 --spec-root）重建指针；② 确认不再使用平台：sillyspec platform disconnect（删除接管声明）；③ 显式 --spec-dir <路径> 临时指定目录。')
+        // exit(1) 而非邻近环境错的 exit(2)：这是"状态保护阻断"（对齐 PointerUnreachableError
+        // 顶层 catch 语义），非"用法/环境错"——见 design.md §5.3 v2 复审观察 (a)
+        process.exit(1)
+      }
     }
   }
   // 持久化 platformOpts
@@ -398,7 +417,11 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // ⚠️ 同 init.js：必须保护真实资产（changes/、projects/、sillyspec.db）。
   // 只在「首次」执行一次——用 cwd 下的 .sillyspec-platform-cleaned 标记文件记录已处理，
   // 后续每次 run 直接跳过，避免重复检查 + 红叉噪声（此清理不阻塞流程、不动真实资产）。
-  if (platformOpts.specRoot) {
+  // 自指守卫（FR-4，变更 2026-08-23-repo-native-spec-backfill）：显式自指 --spec-root
+  // （repo-native junction 回环）下 cwd/.sillyspec 与 specRoot 同物理目录——它就是平台
+  // 规范目录本体，绝非"旧版本残留"；跳过整个清理决策（含 marker 写入，防后续真平台
+  // 接入被误标记已清理）。否则 rmSync 会删掉 repo-native 唯一真理源并留下悬空链接。
+  if (platformOpts.specRoot && !isSelfReferentialSpecRoot(cwd, platformOpts.specRoot)) {
     const legacyDir = join(cwd, '.sillyspec')
     const cleanedMarker = join(cwd, '.sillyspec-platform-cleaned')
     if (!existsSync(cleanedMarker)) {
@@ -466,6 +489,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   const inputValue = getFlagValue('--input')
   if (inputValue !== null) inputText = inputValue
 
+  // quick 位置参数 → 任务描述（与 auto 模式建议的 `sillyspec run quick "需求"` 用法一致）。
+  // 旧行为静默忽略裸 token（QUICKLOG 标题回退占位）；现显式消费——跳过值类 flag 的值
+  // （--files src/a.js 的 src/a.js 不是位置参数），取第一个真位置 token。配合下方
+  // 「新会话必须带描述」启动门（坑 quick-no-input-placeholder-title）。
+  if (stageName === 'quick' && inputText === null) {
+    for (let i = 0; i < flags.length; i++) {
+      const t = flags[i]
+      if (typeof t !== 'string') continue
+      if (t.startsWith('--')) { if (VALUE_FLAGS.has(t)) i++; continue }
+      inputText = t
+      break
+    }
+  }
+
   // 解析 --linked-changes <a,b|none>（quick 专用：显式声明关联变更，CI/脚本友好）
   // 与 --change 解耦：--linked-changes 语义清晰（关联变更），不与「指定变更名」混淆。
   // null = 未指定（走持久化/交互/兼容回退）；[] = 显式 none（不关联）；[...] = 显式列表
@@ -520,6 +557,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   const QUICK_SID_RE = /^quick-[0-9a-f]{8}$/
   let quickSessionId = null
   let quickFallbackUsed = false  // Q7: --done 未带 --change 时 fallback 读 current-quick-run-id 命中（区别于显式 --change quick-<hex>）
+  let quickSidFresh = false      // 本轮刚生成全新 sessionId（非 --change 精确恢复 / 非 fallback）——供下方「新会话必须带 --input」门判定
   if (stageName === 'quick') {
     // 1373-1376 已把 quick 的 --change 值清进 linkedChanges、changeName 置 null。
     // 此处回看 --change 原始值：若恰好是单个 quick-<8hex> → 识别为本会话 sessionId（精确恢复），
@@ -548,6 +586,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       }
       if (!quickSessionId) {
         quickSessionId = 'quick-' + randomUUID().slice(0, 8)
+        quickSidFresh = true
       }
       changeName = quickSessionId
     } else {
@@ -556,6 +595,43 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     }
   }
 
+  // ── 本地 agent 会话日志登记 + 上报（平台会话展示用，best-effort）──
+  // 平台/daemon 模式下 SillyHub 只能看到 CLI 阶段信息，看不到本地 agent 的实际执行日志。
+  // 在此探测当前 agent 环境（Claude Code / Codex / ZCode transcript / SILLYSPEC_AGENT_LOG
+  // 覆盖），把日志本地路径登记进 <runtimeRoot>/agent-session-log.json（留底）并立即
+  // REST 上报平台（POST /api/agent-logs，与进度上报同风格；协议见
+  // docs/platform-agent-log-protocol.md）。探测不到不发不写；任何失败只 warn 一行，
+  // 绝不阻断 run 主流程。
+  // 位置（2026-08-23-agent-activity-sessions task-01）：必须在上方 changeName/quickSessionId
+  // 解析完成之后——上报携带会话化上下文 context：entry 级 changeKey/quickId（平台按
+  // (workspace, harness, entry.ctx) 聚合建会话；quick 会话 quickId 优先且与 changeKey 互斥）
+  // + body 级 hubSessionId（daemon 派发平台会话时注入 env SILLYHUB_SESSION_ID，非空才带）。
+  // 两段解析均在顶层作用域，此处统一算一次 context 两值皆可达。
+  try {
+    const isQuickSession = stageName === 'quick' && Boolean(quickSessionId)
+    const hubSessionIdEnv = typeof process.env.SILLYHUB_SESSION_ID === 'string' ? process.env.SILLYHUB_SESSION_ID.trim() : ''
+    const agentLogContext = {
+      hubSessionId: hubSessionIdEnv || null,
+      // quick 会话 → quickId（quick-<8hex> 完整原样，不剥前缀）；普通场景 → changeKey（--change 值，无则 null）
+      changeKey: isQuickSession ? null : (changeName || null),
+      quickId: isQuickSession ? quickSessionId : null,
+    }
+    const { recordAgentLogInvocation } = await import('../agent-session-log.js')
+    const r = await recordAgentLogInvocation({
+      cwd,
+      invokedCwd,
+      platformOpts,
+      specBase,
+      context: agentLogContext,
+      // 只记 flag 名不记值（--output 等 flag 值是 agent 工作文本，不进产物）
+      command: [stageName, ...flags.filter(t => typeof t === 'string' && t.startsWith('--'))].join(' '),
+    })
+    if (r && r.isNew && r.latestLogPath) {
+      const pushNote = r.pushed === true ? '已上报平台' : r.pushed === false ? '上报失败（本地已留底）' : '本地留底'
+      console.log(`📄 本地 agent 日志已登记（${pushNote}）: ${r.latestLogPath}`)
+    }
+  } catch { /* best-effort：登记失败不影响 run 主流程 */ }
+
   // quick 关联变更存在性守卫（坑 quick-change-phantom-linked）：quick 的 --change/--linked-changes
   // 被解析为关联变更后静默接受不存在的名字（quick 不建变更，链接幻影名必是笔误/语义误用——想给
   // 会话起名却传了 --change），后果是 QUICKLOG 挂悬空关联污染 change 关联图谱 + --done 时 sessionId
@@ -594,10 +670,23 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // 解析 --file-notes "path::括注 || path::括注"（quick 专用：QUICKLOG「文件：」行落盘多行括注）。
   // 旁路注入 quicklog.js（per-process setter），不经 complete 收尾路径透传（避碰多 agent 并发改的收尾热点）。
   // completeQuicklogEntry 读后即清；不传 → '' → 回填审计到的实际文件单行（向后兼容）。
+  // 格式 fail-fast（坑 quick-file-notes-format-silent，2026-08-24）：分隔符写错（`|`/`,` 等）时
+  // 整段会被静默挤进第一个文件的括注、QUICKLOG 落盘后只能手工修——解析处直接拦。
   let quickFileNotes = ''
   const fileNotesValue = getFlagValue('--file-notes')
   if (fileNotesValue !== null) {
     quickFileNotes = fileNotesValue
+    const { validateFileNotesFormat } = await import('../quicklog.js')
+    const fv = validateFileNotesFormat(quickFileNotes)
+    if (!fv.ok) {
+      console.error(`❌ --file-notes 格式不对（${fv.problems.length} 处），已拒绝执行（旧行为会静默挤错进 QUICKLOG，只能手工修）：`)
+      for (const p of fv.problems.slice(0, 5)) {
+        console.error(`   「${p.seg.slice(0, 80)}」${p.reason}——${p.hint}`)
+      }
+      if (fv.problems.length > 5) console.error(`   …等共 ${fv.problems.length} 处`)
+      console.error('   正确格式: --file-notes "path1::括注1 || path2::括注2"（`||` 双竖线分隔多文件，`::` 分隔路径与括注）')
+      process.exit(2) // 用法错（--file-notes 格式非法）→ exit 2
+    }
   }
   setQuickFileNotes(quickFileNotes)
 
@@ -667,6 +756,22 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     process.exit(0)
   }
 
+  // 坑 quick-no-input-placeholder-title（2026-08-24 用户反馈二期①）：全新 quick 会话（上方
+  // 刚生成新 sessionId）不带 --input 且无 --linked-changes 可取标题 → 拒绝启动（exit 2）。
+  // 旧行为只 warn 提示「建议放弃重启」，占位标题「(quick 任务)」已落盘、只能 reset 重来——
+  // 语义标题要拖到最终 --done 才回填，平台「快速修复」列表全程隐藏。此刻零沉没成本（progress
+  // 行/QUICKLOG/guard 均未创建），直接拒掉最便宜。放在 --help 短路之后（help 查询不该被拦）、
+  // 任何会话副作用之前。精确恢复（--change quick-<hex>）与 done-like（--done/--reset/--cancel/
+  // --status/--skip/--reopen）不受限；--linked-changes 启动可从关联变更 proposal/design 提取标题。
+  if (stageName === 'quick' && quickSidFresh
+    && !(isDone || isStatus || isSkip || isReset || isReopen || isCancel)
+    && !inputText && !(Array.isArray(linkedChanges) && linkedChanges.length > 0)) {
+    console.error('❌ 新 quick 会话必须带 --input "<一句话任务描述>"（或 --linked-changes <a,b> 从关联变更取标题）。')
+    console.error('   不带描述启动会落「(quick 任务)」占位标题：平台「快速修复」列表隐藏占位条目、语义标题要拖到最终 --done 才回填，长任务全程不可见。')
+    console.error('   用法: sillyspec run quick --input "<一句话任务描述>" [--linked-changes <a,b>] [--files <...>]')
+    process.exit(2) // 用法错（新会话无任务描述）→ exit 2
+  }
+
   const isAuxiliary = auxiliaryStages.includes(stageName)
   // scan 元数据追踪（存储在 stageData.scanMeta 中，completeStep 通过 progress 访问）
 
@@ -1076,6 +1181,20 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     progress = pm.read(cwd, effectiveChange) || progress
   }
 
+  // --file-notes 非末步静默忽略前置 warn（坑 quick-file-notes-nonfinal-ignored，2026-08-22 实证：
+  // step2 --done 传 --file-notes 被静默丢——CLI 短进程，注入随进程结束即丢，白传一轮）。
+  // 放此处：ensureStageSteps 之后 progress 已就绪可判步骤状态；仅 quick + 带了 --file-notes +
+  // 非「唯一 pending 的末步 --done」时提示。末步 --done 是消费点，不提示。
+  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 一起传。`)
+      }
+    } catch { /* 判定失败不提示（fail-open） */ }
+  }
+
   // --status
   if (isStatus) {
     // D9：状态展示末尾附「下一步该跑什么」。pm 持有状态机，按 progress 实际进度算出精确命令；

package/src/run/complete-handlers.js

@@ -25,7 +25,7 @@
 import { basename, join, resolve, relative, isAbsolute } from 'node:path'
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync } from 'node:fs'
 import { renameSyncRetry, writeAtomicSync } from '../fs-atomic.js'
-import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, resolveRuntimeRoot } from './shared.js'
+import { resolveChangeDir, resolveQuickSessionsDir, safeGit, auditQuickCompletion, triggerSync, isQuickMetadata, resolveRuntimeRoot, collectOtherQuickSessionDeclarations } from './shared.js'
 import { detectConcurrentChanges, formatConcurrentWarning, resolveConcurrentAnchor } from './concurrent-detect.js'
 import { stageRegistry } from '../stages/index.js'
 import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
@@ -431,7 +431,11 @@ export async function handleArchiveConfirmStep({ stageName, steps, currentIdx, c
     console.log('⚠️  请添加 --confirm 确认归档，例如：sillyspec run archive --done --confirm --output "确认归档"')
     return { stageCompleted: false, currentIdx, nextPendingIdx: currentIdx }
   }
-  const archivedDir = await archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts)
+  // 主仓互斥锁（坑 main-repo-no-mutex 二批）：archiveChangeDirectory 改主仓共享状态（目录
+  // rename + 共享 index 的 git add + marker 删除 + worktree 清理），与并行会话的 apply/cleanup
+  // 互踩。exit 钩子兜底：其内部 guard 失败 exit(1) 时锁也会被清（见 withMainRepoLock）。
+  const { withMainRepoLock } = await import('../worktree-apply.js')
+  const archivedDir = await withMainRepoLock(cwd, changeName, 'archive-finalize', () => archiveChangeDirectory(pm, cwd, progress, specBase, platformOpts))
   if (archivedDir && existsSync(archivedDir)) {
     // 内存快照同步（坑 archive-progress-show-stale，2026-08-21 实证）：archiveChangeDirectory 内
     // unregisterChange 已在 DB 写 current_stage='archive'（终态一致化），但本进程 progress 是命令
@@ -863,6 +867,11 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         // （平台模式 resolveSpecDir(cwd) 会 miss specRoot 静默丢信号，plan 审查 gap-5）
         specBase,
         projectName: progress?.project || null,
+        // 他者 active 会话声明索引（坑 foreign-session-declared-false-block）：多 agent 并发时
+        // 并行会话 --files 声明的文件退栈归该会话审计，不再误拦本会话。与上方 guard 读取同源
+        // （resolveQuickSessionsDir 同参，平台模式 runtimeRoot 对齐）；fail-open：采集失败 → 空
+        // → 回到无豁免现状。
+        otherSessionsDeclared: collectOtherQuickSessionDeclarations(platformOpts, specBase, changeName),
       }
       review = await auditQuickCompletion(cwd, mergedGuard, { isConfirm: confirm })
       printQuickAuditReview(review)
@@ -913,8 +922,9 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
     const isLastStep = currentIdx === steps.length - 1
     if (isLastStep && !outputText) {
       console.error('\n❌ quick 最后一步 --done 必须带 --output（四字段结果模板）。')
-      console.error('   --output 是 QUICKLOG「结果：」归档的唯一来源。补全后重跑 --done（不丢进度），照抄模板：')
-      console.error('     sillyspec run quick --done --change <changeName> --output "需求：… 根因：… 方案：… 结果：…"')
+      console.error('   --output 是 QUICKLOG「结果：」归档的唯一来源。补全后重跑 --done（不丢进度），推荐四参数形式（CLI 自动合成，无嵌套冒号事故面）：')
+      console.error('     sillyspec run quick --done --change <changeName> --req "一句话语义化短标题" --cause "为什么这样改" --solution "怎么改的" --result "验证情况（测试数 / lint / typecheck / 部署状态）"')
+      console.error('   兼容旧形式：--output "需求：… 根因：… 方案：… 结果：…"')
       steps[currentIdx].status = 'pending'
       steps[currentIdx].completedAt = null
       process.exit(1)
@@ -924,7 +934,9 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
       if (!resultCheck.ok) {
         console.error('\n' + getRule('quick.result-labels').failMessage.replaceAll('${missing}', resultCheck.missing.join('、')))
         console.error(`   --output 是 QUICKLOG「结果：」归档的唯一来源，四个标签必须放在 --output 里（不是 --input）。`)
-        console.error(`   补全后重跑 --done（不丢进度），直接照抄此模板：`)
+        console.error(`   补全后重跑 --done（不丢进度）。推荐四参数形式（CLI 自动合成结构化模板，避免旧形式嵌套全角冒号被拆分判定缺字段）：`)
+        console.error(`     sillyspec run quick --done --change <changeName> --req "一句话语义化短标题（即 QUICKLOG 条目标题）" --cause "为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）" --solution "怎么改的" --result "验证情况（测试数 / lint / typecheck / 部署状态）"`)
+        console.error(`   或照抄旧形式模板：`)
         console.error(`     sillyspec run quick --done --change <changeName> --output "需求：用户/任务要什么`)
         console.error(`     根因：为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）`)
         console.error(`     方案：怎么改的`)
@@ -1331,22 +1343,39 @@ export async function handleExecuteWorktreeCleanup({ stageName, changeName, cwd
       } else if (meta.mode === 'native-worktree') {
         console.log('🔗 Worktree: kept (外部隔离环境)');
       } else {
-        // in-place 模式不再短路：cleanup 现在能安全处理 in-place（只清 meta，不碰主工作区）
-        const check = wm.hasUnappliedChanges(changeName);
-        if (check.hasChanges) {
-          console.log(`🔗 Worktree: pending apply (${check.changedFiles.length} 个未应用变更)`);
-          console.log(`   下一步: sillyspec worktree apply ${changeName}`);
-        } else {
-          const cleanResult = wm.cleanup(changeName);
-          console.log(`🔗 Worktree: ${cleanResult.result}`);
-          if (cleanResult.residual?.length > 0) {
-            console.warn(`   ⚠️ 清理残留: ${cleanResult.residual.join('; ')}`);
-            console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`);
-          } else if (cleanResult.details?.length > 0) {
-            for (const d of cleanResult.details) {
-              if (d.startsWith('⚠️')) console.log(`   ${d}`);
+        // in-place 模式不再短路：cleanup 现在能安全处理 in-place（只清 meta，不碰主工作区）。
+        // 主仓互斥锁（坑 main-repo-no-mutex 二批）：检查+清理与并行会话的 apply/cleanup 互斥
+        // （防 TOCTOU：检查时他者正在 apply → 判定漂移）。best-effort：锁超时不阻断 execute
+        // 完成，降级为保留 worktree + 手动清理指引。
+        try {
+          const { withMainRepoLock } = await import('../worktree-apply.js')
+          const cleanResult = await withMainRepoLock(cwd, changeName, 'execute-cleanup', () => {
+            const check = wm.hasUnappliedChanges(changeName);
+            if (check.hasChanges) {
+              return { kept: true, check }
+            }
+            return { kept: false, result: wm.cleanup(changeName) }
+          })
+          if (cleanResult.kept) {
+            console.log(`🔗 Worktree: pending apply (${cleanResult.check.changedFiles.length} 个未应用变更)`);
+            console.log(`   下一步: sillyspec worktree apply ${changeName}`);
+          } else {
+            console.log(`🔗 Worktree: ${cleanResult.result.result}`);
+            if (cleanResult.result.residual?.length > 0) {
+              console.warn(`   ⚠️ 清理残留: ${cleanResult.result.residual.join('; ')}`);
+              console.warn(`   手动处理: sillyspec worktree cleanup ${changeName} --force`);
+            } else if (cleanResult.result.details?.length > 0) {
+              for (const d of cleanResult.result.details) {
+                if (d.startsWith('⚠️')) console.log(`   ${d}`);
+              }
             }
           }
+        } catch (lockErr) {
+          if (/互斥锁被占用/.test(String(lockErr.message))) {
+            console.log(`🔗 Worktree 自动清理跳过（主仓互斥锁被他者会话持有）——稍后手动: sillyspec worktree cleanup ${changeName}`);
+          } else {
+            console.warn(`⚠️ worktree 清理异常（不阻断）: ${lockErr.message}`);
+          }
         }
       }
     } catch (e) {