cadence-handoff

cadence-handoff（v0.4）

定位(v0.3 重构)

v0.3 前 handoff 承担"决策/待决/约束/TODO/incidents"五类提取 + 9 步写链;writer subagent context 随 session 大而膨胀。

v0.3/v0.4 后记/整/查三阶段覆盖这些职责:

• 记 阶段（α 流式）记录已承载"讨论内容持久化"(五类提取不再需要)
• recall-retriever 查 阶段（ρ）<500 tokens 契约负责跨 session 检索(注入历史不再需要)
• 整 阶段（ε 整合）触发(含 handoff 兜底)自动收敛零散
• handoff 写书签前执行 fidelity sweep,补齐"对话已承接但尚未落档"的稳定语义

新本质:短小书签——提供"游标"(讨论到哪 / 卡在哪)、canonical 指针和 "soft context"(语气、未明说的注意事项)。详细内容不复制进 handoff,体量目标 15-30 行。

路径约定

所有 handoff 产物必须位于 <project-root>/cadence/.handoff/。不得在项目根创建或读取裸 .handoff/;发现时只提示迁移(见 cadence-resume/SKILL.md Step 1 前置检测)。

5 步流程(主 agent 执行,不派 writer subagent)

Step 1:fidelity sweep + 整 阶段（ε 整合）兜底

对账当前 session 已承接的持久语义与本 session 新增 streaming entry
  → 范围明确的漏记:按 project-discuss 保真规则自动 append,告知用户
  → 指向不明或有多个候选方案:询问用户,不得猜测
  → Glob cadence/streaming/*.md
  → 读每个文件 front-matter
  → 对每个 status: active 文件,检查 entry 保真等级、收尾语义、数量与时间新鲜度
  → High / 显式收尾 / 成熟主题 → 派 recall-consolidator(trigger_reason: handoff_sweep)
  → 接收 plan → 走两阶段写(复用 project-discuss 整 阶段流程)
  → 验证 source_entries 与 coverage 完全对应,否则保持 active
  → 把整合产出的 discussion doc 路径收集到 `produced[]`

只有不是当前 continuation、且未收尾的 Light/Standard 主题可因 entry <2 条 / 距今 <10 分钟 跳过。当前 continuation、High 或用户已明确收尾的 主题即使只有一条 entry 也必须尝试整合,确保新 handoff 至少有一个 canonical ref。

Partial success 语义:若至少一个主题整合成功 → consolidation.triggered: true,produced[] 仅含成功项;全部失败或跳过 → triggered: false,produced: []。

Step 2:扫对话产生 cursor + soft_context

主 agent 自己做(不派 subagent,因为新 schema 体量小,主 context 胜任):

• cursor.last_discussed:session 最近一段讨论话题,一句话
• cursor.pending_questions:未决问题,0-3 个
• cursor.next_step:下次接着做什么,一句话(可空)
• soft_context.tone:对话语气(如"紧凑" / "探索中")(可空)
• soft_context.notes:特殊注意事项,0-N 条(可空)

Step 3:计算 content_hashes + continuation_refs

使用 git hash-object -w --stdin 跨平台计算(跨平台首选,cadence 项目已依赖 git):

INDEX_HASH=$(git hash-object cadence/_INDEX.md)
ACTIVE_HASH=$(git hash-object cadence/_ACTIVE.md)

备用路径(若 git 不可用):

• Windows(PowerShell):(certutil -hashfile <path> SHA1 | Select-String -NotMatch "SHA1\|CertUtil").Line.Trim().Replace(" ","") — 取哈希行,剥离空格
• Windows(cmd):for /f "tokens=1" %%i in ('certutil -hashfile ^<path^> SHA1 ^| findstr /v ":"') do @echo %%i — 取无冒号行第一列
• Linux:sha1sum <path> | awk '{print $1}' — 取前 40 字符字段
• macOS:shasum -a 1 <path> | awk '{print $1}' — Mac 默认无 sha1sum,用 shasum
• Python fallback:python -c "import hashlib,sys; print(hashlib.sha1(open(sys.argv[1],'rb').read()).hexdigest())" <path>(命令名:Windows python / macOS,Linux python3)