comet-dsh-plugin 0.0.0-stage → 0.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/LICENSE +21 -0
  2. package/README.en.md +176 -0
  3. package/README.md +152 -2
  4. package/client.js +349 -0
  5. package/cordis.patch.yml +4 -0
  6. package/icon.png +0 -0
  7. package/index.js +183 -0
  8. package/locale/en.json +7 -0
  9. package/locale/zh.json +7 -0
  10. package/package.json +58 -4
  11. package/rules/comet-workflow-guard.md +65 -0
  12. package/rules/migration-assets.json +218 -0
  13. package/server/comet-plugin-setup.mjs +192 -0
  14. package/skills/comet/SKILL.md +37 -0
  15. package/skills/comet/agents/openai.yaml +3 -0
  16. package/skills/comet/reference/change-walkthrough.md +77 -0
  17. package/skills/comet/reference/edit-review.md +26 -0
  18. package/skills/comet/reference/host-check.md +11 -0
  19. package/skills/comet/reference/platform-execution.md +34 -0
  20. package/skills/comet/reference/task-learning.md +39 -0
  21. package/skills/comet/runtime/classic/checks.yaml +6 -0
  22. package/skills/comet/runtime/classic/guardrails.yaml +13 -0
  23. package/skills/comet/runtime/classic/skill.yaml +122 -0
  24. package/skills/comet/scripts/comet-archive.mjs +310 -0
  25. package/skills/comet/scripts/comet-check.mjs +179 -0
  26. package/skills/comet/scripts/comet-entry-runtime.mjs +151 -0
  27. package/skills/comet/scripts/comet-env.mjs +15 -0
  28. package/skills/comet/scripts/comet-guard.mjs +335 -0
  29. package/skills/comet/scripts/comet-handoff.mjs +289 -0
  30. package/skills/comet/scripts/comet-hook-guard.mjs +295 -0
  31. package/skills/comet/scripts/comet-hook-router-guard.mjs +629 -0
  32. package/skills/comet/scripts/comet-hook-router.mjs +17 -0
  33. package/skills/comet/scripts/comet-intent.mjs +181 -0
  34. package/skills/comet/scripts/comet-plugin-hook.mjs +213 -0
  35. package/skills/comet/scripts/comet-resume-probe.mjs +205 -0
  36. package/skills/comet/scripts/comet-runtime.mjs +572 -0
  37. package/skills/comet/scripts/comet-state.mjs +381 -0
  38. package/skills/comet/scripts/comet-yaml-validate.mjs +182 -0
  39. package/skills/comet-any/SKILL.md +47 -0
  40. package/skills/comet-any/agents/openai.yaml +5 -0
  41. package/skills/comet-any/reference/sdk-creation.md +100 -0
  42. package/skills/comet-archive/SKILL.md +28 -0
  43. package/skills/comet-archive/agents/openai.yaml +5 -0
  44. package/skills/comet-archive/reference/compat.md +188 -0
  45. package/skills/comet-build/SKILL.md +35 -0
  46. package/skills/comet-build/agents/openai.yaml +5 -0
  47. package/skills/comet-build/reference/compat.md +191 -0
  48. package/skills/comet-classic/SKILL.md +98 -0
  49. package/skills/comet-classic/agents/openai.yaml +3 -0
  50. package/skills/comet-classic/reference/auto-transition.md +34 -0
  51. package/skills/comet-classic/reference/classic-layout.md +36 -0
  52. package/skills/comet-classic/reference/comet-yaml-fields.md +82 -0
  53. package/skills/comet-classic/reference/context-recovery.md +128 -0
  54. package/skills/comet-classic/reference/debug-gate.md +30 -0
  55. package/skills/comet-classic/reference/decision-point.md +109 -0
  56. package/skills/comet-classic/reference/dirty-worktree.md +59 -0
  57. package/skills/comet-classic/reference/file-structure.md +32 -0
  58. package/skills/comet-classic/reference/intent-frame.md +132 -0
  59. package/skills/comet-classic/reference/scripts.md +144 -0
  60. package/skills/comet-classic/reference/sdk-methods.md +136 -0
  61. package/skills/comet-classic/reference/subagent-dispatch.md +75 -0
  62. package/skills/comet-classic/reference/workspace.md +23 -0
  63. package/skills/comet-design/SKILL.md +25 -0
  64. package/skills/comet-design/agents/openai.yaml +5 -0
  65. package/skills/comet-design/reference/compat.md +191 -0
  66. package/skills/comet-hotfix/SKILL.md +46 -0
  67. package/skills/comet-hotfix/agents/openai.yaml +5 -0
  68. package/skills/comet-hotfix/reference/compat.md +240 -0
  69. package/skills/comet-memory/SKILL.md +68 -0
  70. package/skills/comet-memory/agents/openai.yaml +5 -0
  71. package/skills/comet-native/SKILL.md +139 -0
  72. package/skills/comet-native/agents/openai.yaml +3 -0
  73. package/skills/comet-native/reference/artifacts.md +118 -0
  74. package/skills/comet-native/reference/clarification.md +120 -0
  75. package/skills/comet-native/reference/commands.md +321 -0
  76. package/skills/comet-native/reference/edit-review.md +26 -0
  77. package/skills/comet-native/reference/recovery.md +64 -0
  78. package/skills/comet-native/reference/workspace.md +70 -0
  79. package/skills/comet-native/scripts/comet-native-archive.mjs +475 -0
  80. package/skills/comet-native/scripts/comet-native-cancel.mjs +461 -0
  81. package/skills/comet-native/scripts/comet-native-doctor.mjs +475 -0
  82. package/skills/comet-native/scripts/comet-native-hook-guard.mjs +470 -0
  83. package/skills/comet-native/scripts/comet-native-init.mjs +465 -0
  84. package/skills/comet-native/scripts/comet-native-new.mjs +478 -0
  85. package/skills/comet-native/scripts/comet-native-next.mjs +470 -0
  86. package/skills/comet-native/scripts/comet-native-root.mjs +472 -0
  87. package/skills/comet-native/scripts/comet-native-runtime.mjs +525 -0
  88. package/skills/comet-native/scripts/comet-native-select.mjs +468 -0
  89. package/skills/comet-native/scripts/comet-native-show.mjs +462 -0
  90. package/skills/comet-native/scripts/comet-native-spec.mjs +468 -0
  91. package/skills/comet-native/scripts/comet-native-status.mjs +467 -0
  92. package/skills/comet-native/scripts/comet-native-transfer.mjs +466 -0
  93. package/skills/comet-open/SKILL.md +265 -0
  94. package/skills/comet-open/agents/openai.yaml +5 -0
  95. package/skills/comet-open/reference/batch-changes.md +51 -0
  96. package/skills/comet-review/SKILL.md +121 -0
  97. package/skills/comet-review/agents/openai.yaml +5 -0
  98. package/skills/comet-tweak/SKILL.md +49 -0
  99. package/skills/comet-tweak/agents/openai.yaml +5 -0
  100. package/skills/comet-tweak/reference/compat.md +232 -0
  101. package/skills/comet-verify/SKILL.md +30 -0
  102. package/skills/comet-verify/agents/openai.yaml +5 -0
  103. package/skills/comet-verify/reference/compat.md +202 -0
@@ -0,0 +1,321 @@
1
+ # Native 命令与执行参考
2
+
3
+ Runtime 不再以 PID、进程创建身份或线程绑定决定恢复。进程退出会释放本机事务锁;旧格式锁需确认原操作停止后退役一次。检查中断时沿用原 Run、实际结果和日志;结果未知时先核对副作用,明确确认停止后处理原 Action,不按历史 PID 杀进程、不自动重跑。移除 PID 只消除该机制的恢复阻塞,不能把执行到一半的 Git 或文件操作变成已完成。
4
+
5
+ 只读取当前操作需要的章节。Supervisor 协作、记忆接入和异常处理各有适用条件,遇到对应情况时再读取。
6
+
7
+ ## SDK Run
8
+
9
+ ### 任务结果回报
10
+
11
+ 新建内置 SDK 的普通任务与 Supervisor 任务用 `comet native next <change> --session <实际会话标识> --json` 领取。当前响应是 `comet.native.task-result.v1` 时直接使用 `task`、`resultTemplate` 和 `next.commandArgs`;`--details` 才附带完整 SDK 状态。结果文件只保存实际 `status`、`output` 和需要的业务结果字段,命令中的 `--action` 绑定原任务,`--session` 绑定实际领取者。结果文件放在临时目录;没有 Git 跟踪信息时放在项目之外,避免它成为候选输入。
12
+
13
+ `shape.prepare` 任务由 Agent 从正式文档整理验收项,按 `resultTemplate` 提交 `output.acceptance`,每项填写实际 `source` 与 `text`。来源使用 brief 或已声明的目标 Spec;CLI 分配稳定验收 ID。自由格式文档无需补固定章节,提交后仍须展示完整方案并取得用户确认。
14
+
15
+ Supervisor 响应中的 `task.child`、`task.scope` 和 `workspace.projectRoot` 确定实际执行范围;多个候选任务从 `availableTasks` 选择并用真实会话领取。子任务只验收自身条目,父级覆盖全部已确认要求。集成修复使用集成工作区;独立 Verifier 不会自动领取实现或集成修复任务。
16
+
17
+ 普通任务、Child 和父级任务由 Agent 使用平台工具执行检查,读取真实结果后填写 checks 的 name/result/note,记录命令、目录、结果和日志引用。Builder 一次提交实现与结果;Verifier 普通任务填写 output.checks,Child 填写 evidence.checks。checks 可为空,但未运行与失败不能当作通过;验收者负责判断证据是否充分。v4 不提交 verificationChecks、integrationChecks、request-checks 或自制收据,Runtime 不再重复执行普通检查。旧 Run 自动适配业务数据,沿用原批准、任务和候选,使用当前返回的报告模板。`--review current-session` 由当前真实会话领取 Verify;`--review independent` 保留待领取任务,由独立接收者填写自己的会话身份后执行返回命令。用户明确要求独立审查时选择后者。一次响应只执行其当前下一步,完整验收正文不能裁掉。
18
+
19
+ Verify 回报默认停在用户接受结果。只有用户已明确委托“全部通过后接受并归档”时,才添加 `--accept-on-pass <授权摘要>`;Runtime 只在本次结果通过且对应当前确认时接受,保存该摘要,并连续归档。该选项不授权 Git merge、push、PR 或清理,也不改变旧 `--accept-result` 的提案绑定。重复结果使用原 Action 和相同内容,错误会话、不同结果、候选漂移按原 Runtime 协议拒绝。
20
+
21
+ 以下底层协议只供旧 Run、固定应用、明确异常或调试使用。当前高层响应已充分时直接继续。
22
+
23
+ 响应的 `runtimeFormat` 为 `sdk`,或 `data.schema` 为 `comet.native.sdk-status.v1`、`comet.native.dispatch-result.v1`、`comet.native.run-view.v1` 时使用本节,直接识别当前响应,不额外查询 status。Run ID 使用当前响应的 `data.run.id` 或 `data.runId`;最新 `pendingActions`、`activeActions`、`action` 和 `stateVersion` 决定当前工作。领取响应已经包含当前 Action 输入和回报模板,直接使用;只有缺少实际所需正文时才读取同一响应给出的详情命令。SDK 请求保存为临时 UTF-8 JSON,通过 `comet runtime dispatch --application native --project-root <projectRoot> --request <file>` 提交,不放进 change 产物、提交或报告。命令返回 `status: succeeded` 后,核对同一 Action 的领取或已持久化结果身份;相同领取或结果的幂等确认可以保留原 revision,不要求重复提交产生状态变化。提交后沿用返回的当前身份和 continuation。
24
+
25
+ ### Shape 与 SDK 自有 Action
26
+
27
+ 普通 `status` 只读取当前业务状态;需要历史执行记录时使用 `--details` 或 `doctor`。正常推进直接使用当前响应,遇到实际错误再读取恢复说明。本地 SDK Run 保存每次推进;Portable 检查点在用户等待、Agent 交接和结束等边界写入,内部无副作用步骤不要求同步投影,外部命令执行前仍保存恢复边界。不要手动修改检查点来推进流程。
28
+
29
+ 新 Run 的 Verify 通过后直接等待接受,报告由 Runtime 生成阅读视图。报告写入失败时按 warning 继续或重试 `next`,保留已保存的验收结论。接受后普通流程在 Archive 准备时核对候选和实际输入;候选变化必须重新处理。Supervisor 交付仍使用自己的执行步骤。
30
+
31
+ 完成正式 brief 和完整目标 Spec 后,运行 `comet native next <change> --json`,直到 `run.waits` 出现待处理的 `shape.confirm` 或 `supervisor.shape.confirm`。向用户展示完整 Shape;Supervisor 还要展示 Child 计划,并让用户选择多会话或单会话推进。得到明确确认后,按当前 `continuation.commandAlternatives` 的状态版本和动作执行对应命令;Agent 判断目标、验收或授权发生实质变化时重新提案。之后一次 `next` 连续执行已获授权的 Runtime 内部 Action,遇到用户决定、Agent 任务、失败或未知结果时返回;查看返回的 `pendingActions` 处理全部待办,`pendingAction` 只表示其中第一项。对 `build.builder`、`verify.verifier`、`supervisor.child.builder`、`supervisor.child.verifier`、`supervisor.child.integration-repair` 和 `supervisor.parent.builder`,按下文协议领取并回报各自的 Action;多个 Child 可以并行工作,但集成 Action 与集成结果提交按 Run 顺序串行推进。每次提交后重新读取 Action、Wait 和状态。
32
+
33
+ Supervisor Child 的 Verifier 明确判定失败时,在原 Child worktree 修复并提交新的候选,再提交平台检查与验收结果。结果未知时先核对原平台任务。Git 集成冲突或中断沿同一 Action 和原现场恢复,不把未知结果当作失败后重放合并;Runtime 继续核对实际提交、分支和祖先关系。
34
+
35
+ Supervisor 父级 Verifier 明确判定失败,或用户拒绝当前父级验收结果时,Run 会生成新的 `supervisor.parent.builder`。在原集成 worktree 修复并提交后,Builder 回报须携带新的 `candidateCommit`;Runtime 将该提交绑定到后续检查、独立验收和交付。未改动代码时仍需提交新的 Builder 结果和检查,不复用旧候选的验收。
36
+
37
+ ### SDK Action 领取与回报
38
+
39
+ Builder 开始本轮实现前、Verifier 开始验收前,复制当前 Action 的 `claimRequest`,填写接收会话并保留已提供的稳定领取标识,先提交 `claim`。独立 Action 的领取按 `actionId`、`attempt` 和 `inputHash` 校验,不自行补入旧的全局 revision;其他任务推进不要求重派本任务。请求包含 `operation: "claim"`、`runId`、`actionId`、`attempt`、`inputHash`、`executorId: "native-host"`、`sessionId` 和本次唯一且恢复时保持不变的 `claimToken`。`sessionId` 使用平台会话或任务标识;若平台没有可读标识,使用本次工作稳定唯一的执行引用,并明确其只是关联标识,不能据此宣称执行者身份已认证。只有返回的同一 Action 为 `running`、领取标识匹配,才执行或继续本次工作。已由别的执行者领取时,先核对该工作,不能重新领取或另起同一任务。
40
+
41
+ 领取响应提供 `resultRequest` 时,整体保留其中的 `receipt`,只填写 `result.status` 与真实业务 `result.output`,通过同一 dispatch 命令提交;无需拆装 Action 身份或生成结果 ID。重复提交相同结果沿用原收据。旧 `outcomeRequest` 继续可用,不能混用两种输入。`claimRequest` 中已填好的领取令牌原样保留,只填写实际会话标识。提交时间由 Runtime 补记;`addressedAcceptanceIds` 可选,用于本轮处理重点,省略不代表修改了全部验收项。
42
+
43
+ 没有 `resultRequest` 的旧响应中,执行者完成后用同一 `runId` 提交 `record-outcome`:`outcome` 包含原 `actionId`、`attempt`、`inputHash`、`claimToken`,本次唯一的 `outcomeId`、真实的 `status` 和 `output`。不得把尚未完成、未运行或结果未知的工作写成 `succeeded`。SDK 校验结果并保存收据后才按新的 Run 继续。
44
+
45
+ ### SDK Builder 交接
46
+
47
+ 新 Run 的 Builder 结果含可选布尔字段 `requireIndependentReview`。用户明确要求独立审查,或 Agent 已决定交给独立审查者时填 `true`,该要求随实际 Builder 结果保存,后续领取省略参数也不能取消。普通高层命令的 `--review independent` 自动保存同一要求。Supervisor Child 与主任务也按此选择,当前模板未提供该字段的旧 Run 沿用原规则。验收者始终只读,以实际会话领取;同会话结论显示为 `self-reviewed`。
48
+
49
+ `build.builder` 和 `supervisor.parent.builder` 的完成结果填写实际 `summary`、实际 `checks`(每项 `name`、`result`、`note`)和 `knownLimits`。当前模板不含 `acceptanceReview` 时直接提交这些内容,完整逐项验收在 Verify 完成。旧模板要求该表时,对每个验收 ID 提供 `{id,status,evidence,note}`,全部为 `implemented-with-evidence` 且证据非空才提交;显式提供的表仍须完整、真实。
50
+
51
+ 按[普通命令与检查](../../comet/reference/platform-execution.md)使用平台工具执行普通命令、核对原任务与副作用、判断结果是否适用,并提交实际报告。Comet 不重复执行检查,不维护普通命令的内容快照、进程监管或恢复机制。 不提交 `request-checks`、检查计划或普通检查收据。
52
+
53
+ ### SDK Verify 协议
54
+
55
+ `verify.verifier` 和 `supervisor.child.verifier` 的执行者按当前 `sessionRequirements.independent` 确定。为 `false` 时可由当前会话领取,并根据不确定性、交叉核对的价值和用户要求决定是否安排独立审查;为 `true` 时由不同于 Builder 的只读会话领取。只读要求适用于所有验收执行者。安排独立审查时传入当前候选 ID、验收项及引用、工作区和 实际检查报告位置,让它使用真实会话身份领取。平台仅接受派发、尚无 Verifier 领取回执时,状态是“已派发未确认启动”。等待工具超时继续跟踪同一任务。Verifier 读取全部当前验收项并独立核验后,成功 `output` 包含当前 `candidateId`、与领取时相同的 `verifierExecutionRef`,以及 `response`:完整结论使用 `final-result`,实际检查填写 `output.checks`(Child 使用 `evidence.checks`)。缺少证据时通过平台工具补足,沿用同一验收任务。
56
+
57
+ 只有平台确认 Verifier 任务未启动、执行失败、执行超时、丢失或结束后没有可用结果,才将其 Action 提交为 `status: "failed"`,`output` 写真实的非空 `summary`。SDK 保留候选和已完成检查,限次生成新 Action;达到上限后等待用户决定。当前 Action 要求独立会话但无法安排时,停止并报告;始终如实提交实际验收结论。
58
+
59
+ ### 用户决定、Archive 与恢复
60
+
61
+ `verify.confirm` 待处理时,先展示实际验收结论并等待用户决定。只用当前 `run.waits[].proposalHash`、`stateVersion` 和对应 `--expected-action`,执行 `native next <change> --accept-result|--revise-implementation --summary <text> --proposal-hash <hash> --expected-state-version <n> --expected-action <action>`;Runtime 将接受决定绑定到当前候选和结构化验收结果。新 Run 的 Markdown 报告作为阅读视图;旧 Run 保留原报告与执行关联,不根据当前文件字节重新验收。用户修改需求或验收标准时,先说明重新确认 Shape 的影响,得到明确选择后使用当前状态版本执行 `native next <change> --revise-requirements --summary <text> --expected-state-version <n> --expected-action revise-requirements`;该 SDK 命令通过版本化命令替换当前未领取的工作,不使用 Verify 的提案哈希。从新的 Shape 继续,不复用原验收。Archive 中 `archive.execute` 尚未成功时也可修订;已执行归档后不得倒退修改。`verify.retry` 待处理时,用户明确选择重试后才以相同保护参数执行 `--retry-verifier`,继续使用原候选和有效检查。
62
+
63
+ 进入 Archive 后直接执行当前 continuation 返回的 `native archive <change> --json` 命令;Runtime 会按顺序组合执行可安全推进的 `archive.prepare`、`archive.execute`、`archive.finalize`,并保留每个 Action 的真实结果。仅需预览或诊断时使用 `native archive <change> --dry-run --json`。每次只按返回的最新 continuation 继续,不固定重复 Archive,不用旧状态版本重放。Supervisor 还会有 `supervisor.cleanup`:Runtime 只在目标分支仍是已验收提交、临时 worktree 干净且分支已合入时清理本次创建的 Child 和集成 worktree;遇到脏 worktree 或结果未知,保留现场并按原 Action 核对,不强制删除。只有 SDK Run 为 `completed` 且业务状态为 `done` 才说 SDK 归档完成。merge、push、PR 和非 Supervisor 临时工作区的收尾仍按用户授权分别执行和核对,SDK 归档不自动证明这些外部交付已完成。
64
+
65
+ 中断恢复时先读取 `native status <change> --details --json`,必要时用 `runtime dispatch` 的 `inspect` 请求取得完整 Run。待处理 Action 可继续;`running` 或 `unknown` 的平台 Action 先查原平台会话、任务句柄与原 `claimToken`。实际结果已知时由原领取者提交原 Action 的结果;只有权威证据证明未执行,才按 SDK 的 `retry`/reconciliation 协议重新开放。结果未知时保留现场并报告阻塞,不重派 Builder、Verifier 或其他有外部副作用的工作。旧 Runtime 的 `continuation` 和 `--runner-input` 指令不适用于 SDK Run;整个本地 Run 记录丢失时,按主 Skill 的显式恢复步骤处理。
66
+
67
+ Builder 已部分执行且原 Action 已提交 `failed` 时,保留工作区和原失败结果;不要把它核对成“未执行”后重试,也不要自行重新派发。运行 `native next <change> --json`,从 `pendingBuilderDecisions` 读取对应的 `build.resume`、`supervisor.child.resume` 或 `supervisor.parent.resume` Wait。先向用户说明已完成的修改、失败原因与继续工作的风险,得到明确决定后,填写 `commandArgs` 中的 `--summary` 并原样保留提案摘要、状态版本和预期动作,再执行 `--continue-builder`。Runtime 会创建绑定原失败 Action 的新 Builder Action;在原工作区领取并继续它,完成后重新执行检查和验收。用户尚未决定或提案已过期时停下,重新读取当前 Run,不修改原失败结果。
68
+
69
+ 若 `supervisor.parent.deliver`、`archive.execute`、`archive.finalize` 或 `supervisor.cleanup` 是唯一的 `unknown` Action,且已确认原执行进程停止,可运行 `native archive <change> --recover --json`。交付恢复只在目标分支仍精确指向已验证集成提交时,向原 Action 提交结果;目标尚未交付或分支已漂移时拒绝,不重新执行快进。归档与清理恢复会核对原领取、持久化证据和工作区,必要时完成剩余的安全操作,再向同一 Action 提交结果;恢复不会创建新尝试。证据不足、worktree 有未保存修改,或原执行进程仍可能运行时,保留现场并先处理这些事实。成功返回后重新读取 Run,继续处理新产生的待办 Action。
70
+
71
+ ## 记忆接入
72
+
73
+ 领取响应含 `data.contextDelivery` 时,读取 `data.context[].text` 后直接工作,无需再执行 `contextRequest`;`empty` 表示没有新增交付,`unavailable` 时按明确任务继续。需要正文时使用 `data.contextActions.expand`,上下文丢失时使用 `data.contextActions.restore`,收尾时使用 `data.contextActions.complete` 并填写实际学习文件。新 Agent 使用自己的会话标识,不复用其他执行者的上下文回执。
74
+
75
+ 没有自动交付时,进入 change 工作区并取得当前 `phase` 后,优先执行当前任务包的 `contextRequest`(包括 Compat 的 `supervisorTask.contextRequest`);没有任务专属请求时使用 `continuation.contextRequest`。SDK 的 Builder、Verifier 和子任务使用对应 `pendingActions[]` 或 `activeActions[]` 中的 `contextRequest`,由接收方在领取成功后执行。命令中的任务填用户原始请求,会话填接收 Agent 自己的稳定标识;原始请求缺失时先从当前 brief 恢复目标。
76
+
77
+ 首次进入阶段、交接给新 Agent、上下文压缩或新会话恢复后,各执行一次完整读取。旧响应没有 `contextRequest` 时使用:
78
+
79
+ ```text
80
+ comet task <project-root> --task "<用户原始请求>" --phase "<phase>" --session "<接收 Agent 的稳定标识>" --context-mode snapshot --json
81
+ ```
82
+
83
+ 把返回 JSON 中 `context[].text` 加入当前上下文。完整读取返回当前阶段适用的内容,不受本会话此前已交付记录的去重影响;重复读取不代表重复使用或成功执行。`manifest`(注入文本中的 `<context_manifest>`)是 Context Manifest,即上下文条目清单,只包含摘要、使用原因和固定 ID。
84
+
85
+ 当前任务需要正文、来源或验证方式时,运行 `comet task <project-root> --task "<用户原始请求>" --phase "<phase>" --session "<同一标识>" --expand-context "<id>" --json`。同一阶段连续执行时复用已取得的内容;路径或操作变化时保留会话标识,按新的 `--path`、`--operation` 重新检索,默认增量模式只返回尚未交付的适用内容。
86
+
87
+ 交接时附上接收方的 `contextRequest`,保留用户原话、适用条件和来源;Verifier 只接收适用的验收偏好、项目约束和客观证据,不把 Builder 的自评当作结论。按平台实际可用的技能加载接口执行适用的 Skill 偏好;不可用、与当前指令冲突或不符合只读角色时说明原因。记忆已交付、Skill 已加载和实际遵循分别核对;Skill 不代替 Runtime 检查、用户授权或独立验收。获取为空或失败时,沿用明确指令继续,不循环重试,也不为检索结果变化回滚工作流阶段。
88
+
89
+ 若 `<active_policies>` 中包含 `<verification command="...">`,将这些命令加入当前 Verify 的检查,并记录实际结果。只有对应命令成功执行后,Runtime 才会将该策略设为强制执行。
90
+
91
+ 记忆按以下规则保存:
92
+
93
+ 本次确有可复用观察或经验时,按[任务学习收尾](../../comet/reference/task-learning.md)准备学习文件,用 `comet task --complete --learning-file <file>` 一次提交个人观察、项目经验、待评审动作和实际使用反馈。下面的分步保存、评审与完成命令供即时保存、单项纠正及旧版兼容;采用学习文件时无需重复执行。
94
+
95
+ - 用户明确要求长期记住偏好或项目约定时,调用 `comet memory remember <project-root> --text "<偏好或约定>" --scope global|project --json`,立即保存为用户明确指定的记忆。用户明确限定阶段时追加可重复的 `--phase`,例如 `--phase build --phase verify`;纠正适用阶段使用 `comet memory correct <project-root> --id <id> --phase <phase> --json`。保留用户原话,不把当前阶段自动当作长期适用条件。
96
+ - 用户没有提出长期记忆要求,但协作方式已经稳定、可供以后任务复用时,才调用 `comet memory observe <project-root> --text "<协作方式>" --workflow <workflow> --change <change-id> --candidate-key <stable-topic-key> --json`。
97
+ - 两者都不得保存任务摘要、实现进展、命令输出或测试结果。
98
+
99
+ ### 项目记忆
100
+
101
+ 项目记忆与个人记忆独立保存。当前项目中已经验证、未来任务仍可复用的事实、决策、模式、步骤、约束或失败处理,任务结束前写入项目记忆:
102
+
103
+ ```text
104
+ comet knowledge remember <project-root> --title "<简明标题>" --text "<现象、做法、验证结果>" --type <fact|decision|pattern|procedure|constraint|failure-resolution> --workflow native --change <change-id> --evidence "<来源文件,逗号分隔>" --json
105
+ ```
106
+
107
+ 同一标题默认更新已有条目,不重复创建;没有可复用经验时跳过。`--evidence` 绑定实际支持结论的项目内文件;没有文件依据的协作决策可省略。返回的 `slug` 是本次写入回执。采用已有经验前,用同一任务参数追加 `--expand-context "project-memory:<slug>"` 展开并核对当前来源;来源变化或不可读取时,先验证并更新经验。任务摘要、一次性命令输出和未验证的猜测不得写入。
108
+
109
+ 只有明确的用户纠正、长期记忆要求或已验证的可复用经验才触发学习提交。没有这些内容时直接记录任务完成,学习标记使用 `not-run`,不另查队列或提交空评审来证明没有观察。已提交内容保留真实回执;待评审和反思队列留给异步维护,学习失败不阻断已完成的开发任务。用户明确要求维护记忆时,再查询和处理相关队列。
110
+
111
+ 观察命令的 JSON `learning.result` 是本次处理结果:`candidate-created` 表示已记录候选,`candidate-promoted` 表示已晋级,`deduplicated` 表示同一 change 重试,`ignored` 或 `skipped` 表示被策略、暂停或安全筛选跳过。若 `status.learning.lastCheck` 显示 `not-run`,说明当前入口没有提交本次学习检查,不能推断为“没有值得学习的内容”。
112
+
113
+ 实际使用某条上下文后,从 JSON 的 `applications[].applicationId`(Hook 文本中的 `application_id`)取得标识。使用结果明确时,运行 `comet task <project-root> --task "<用户原始请求>" --application "<application-id>" --outcome used-successfully|ignored|overridden|corrected|contributed-to-failure --json` 记录结果;没有实际使用的条目不能标为成功。
114
+
115
+ 验证、编译或 linter 失败时,按错误信息修复并重跑。任务结束时,调用 `comet task <project-root> --task "<用户原始请求>" --complete --workflow native --change <change-id> --learning-check submitted|no-observation|not-run --project-learning-check submitted|no-observation|not-run [--memory <slug>] --json` 保存任务完成记录。两个检查分别表示个人记忆和项目经验,不能互相替代。命令不可用、没有返回内容或自动检索失败时,继续处理任务。没有 Hook 的平台由本 Skill 调用相同接口;`comet memory context` 只作为兼容入口。
116
+
117
+ ## 用户 Hook 写入
118
+
119
+ Comet Hook Router 只检查写入目标,不会替换或调用项目自己的其他 Hook。写入项目目录之外的目标会直接放行。用户 Hook 如果在 Shape、Verify 或 Archive 等阶段向项目内的共享目录写文件,应在 `.comet/config.yaml` 配置专用目录:
120
+
121
+ ```yaml
122
+ hook:
123
+ allow_paths:
124
+ - .my-hook-output
125
+ - docs/team-notes
126
+ ```
127
+
128
+ 路径必须是项目相对目录;目录本身及其后代路径都会放行,Native 和 Classic 共用这项配置。即使同时存在多个 active change、还没有当前选择,明确配置的目录也不会要求先选择 change;`.comet/config.yaml` 也属于可写的控制文件。
129
+
130
+ `.comet/`、Native 的 `native.artifact_root/comet/` 以及 Classic 的工作流产物目录始终由工作流管理,不能通过 `allow_paths` 绕过。一次 Hook 事件包含多个目标时,未配置的目标仍会继续接受阶段检查;建议把用户 Hook 的输出放在独立目录中。
131
+
132
+ Native 正式产物只能由 `comet native new <name> --json` 登记后创建。Runtime 初始化 brief;Agent 使用响应中的 `artifacts.briefPath`、`artifacts.specsDir` 和其他路径编辑对应文件。拒绝信息会列出原因、错误目标、正确目标和下一动作:直接执行其中的 CLI 命令或修正原目标后重试,不要查询其他目录的同名文件,也不要把自定义 Hook 或普通开发文件强行归为 Comet。
133
+
134
+ 用户明确要求撤销能力关联时,先执行 `comet native status <change> --json`,再使用最新响应中的 `data.stateVersion` 执行 `comet native spec disassociate <change> --expected-state-version <data.stateVersion> --expected-action disassociate-capability`,并按新 continuation 继续。其他关联文件写入意图只查询 status,不猜测为撤销;不要手工删除关联文件。
135
+
136
+ ## 填写命令输入
137
+
138
+ 本节的 Runner 模板只用于 Compat。SDK 领取与回报使用上面的平台 Action 协议及当前响应的 `claimRequest`、`outcomeRequest`,不使用 `--runner-input`。
139
+
140
+ 首次填写 Runtime 模板或通过 `returnAction` 回传结果前必须读取本节。
141
+
142
+ 把 `inputOptions.template` 复制到系统临时 JSON 文件,只替换模板要求填写的内容,然后执行 `continuation.commandArgs` 或所选 `commandAlternative.commandArgs`。Runtime 接受输入后删除临时文件;输入被拒绝时保留原文件,按错误修正后重提。模板中已有的验收轮次、Verifier 尝试次数、状态版本和任务标识都原样保留;只填写模板公开的字段。
143
+
144
+ `inputOptions` 中同一 `exclusiveGroup` 的选项互斥:选择其中一个,将它的 `template` 作为单个 JSON 对象填入临时文件。字段校验失败时,按 `error.issues` 指出的 JSON 路径、缺失字段和未知字段修正原文件。
145
+
146
+ Supervisor 子任务只在任务包指定的 `projectRoot` 工作,把填写好的结果交给主 Agent。主 Agent 在 `returnAction` 指定的控制目录,按原命令和模板逐个提交;保留原 `runId`、候选及实际子会话身份,子任务不直接写父级状态。
147
+
148
+ 按 `inputOptions` 模板填写完整后直接正式提交;Runtime 在提交时校验输入,无需先跑预检。`comet native next <change> --runner-input <file> --validate-only --json` 只在提交被拒且需要区分 JSON 结构错误与业务校验错误时使用;该校验不写入工作流状态(comet-state.yaml)或启动检查。正式提交时,仍要使用当前 `continuation` 指定的状态版本、任务标识和命令参数。
149
+
150
+ ### 枚举字段合法值
151
+
152
+ 模板占位符和校验错误都会列出下列字段的全部合法值。每个字段的取值集合只对该字段有效,不能把一个字段的值套用到另一个字段。
153
+
154
+ | 输入 | 字段 | 合法值 |
155
+ | ------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------ |
156
+ | `builder-handoff` | `checks[].result` | `passed` / `failed` / `not-run`:Builder 实际运行或未运行的开发检查 |
157
+ | `builder-handoff` | `acceptance_review[].status` | `implemented-with-evidence` / `implemented-no-evidence` / `not-implemented` / `known-fail` |
158
+ | `builder-handoff` | `review.status` | `passed` |
159
+ | `verifier-response`(`final-result`) | `result.verdict` | `pass` / `fail` / `blocked`:Verifier 总判定 |
160
+ | `verifier-response`(`final-result`) | `result.acceptance[].result` | `passed` / `failed` / `blocked`:逐项验收结论 |
161
+ | `supervisor-verifier-result` | `verdict` | `pass` / `fail` / `blocked` |
162
+ | `supervisor-verifier-result` | `evidence.acceptance[].result` | `passed` / `failed` / `blocked` |
163
+
164
+ 逐项结论和 Builder 检查结果用完成时(`passed`、`failed`),总判定用原形(`pass`、`fail`)。`not-run` 只用于 Builder 的开发检查,`blocked` 只用于 Verifier 字段,`pending` 是 Runtime 内部状态值,不出现在任何输入中。
165
+
166
+ ## Builder 交接
167
+
168
+ 仅用于 Compat。SDK 使用 [SDK Builder 交接](#sdk-builder-交接) 及当前 `outcomeRequest`。
169
+
170
+ 提交 `builder-handoff` 前必须读取本节。
171
+
172
+ 普通 change 和 Supervisor 主任务进入 Verify 前,不需要额外安排一次只读复核。如果已有独立复核结果,可以按 Runtime 模板填写可选的 `review.status=passed`、`review.summary`、`review.reviewer_execution_ref`;复核执行标识不能与 Builder 执行标识相同。
173
+
174
+ Builder 的交接摘要必须写明本轮修改、处理的验收项、实际运行和未运行的开发期检查,以及已知限制。前面的复核不能替代正式 Verifier;正式 Verifier 仍须独立检查全部验收项。
175
+
176
+ 交接前逐项核对当前 brief、完整目标 Spec 和所有已确认验收 ID,按 Runtime 模板填写 `acceptance_review`;每个 ID 恰好一项。`id` 沿用模板,`status` 如实填写,`evidence` 列出具体文件位置、检查记录或可复核的观察,`note` 说明实现如何满足该项。只有全部为 `implemented-with-evidence` 且每项证据非空时才提交。`implemented-no-evidence`、`not-implemented`、`known-fail` 对应尚缺证据、尚未实现和已知失败,先据此补齐剩余工作,不把未完成候选交给 Verifier 试探反馈。修复模板会保留未受影响项的上轮证据,受影响项提示补充本轮证据;提交前核对每项证据仍适用,并更新失效内容。预填内容不是新的检查结果。自查不代表独立验收通过。
177
+
178
+ 按[普通命令与检查](../../comet/reference/platform-execution.md)使用平台工具执行普通命令、核对原任务与副作用、判断结果是否适用,并提交实际报告。Comet 不重复执行检查,不维护普通命令的内容快照、进程监管或恢复机制。 `builder-handoff.checks` 保存实际检查与日志引用,交接不触发命令。
179
+
180
+ 交接摘要保存在 `comet-state.yaml` 中,不会生成单独文件,也不表示验收已经通过。Runtime 会将必要摘要交给 Verifier,Builder 提交一次即可。
181
+
182
+ 完成标准:实现和相关检查已准备好交给 Verifier,全部验收项已重新核对,Runtime 接受交接摘要并进入 Verify。
183
+
184
+ ## Verify 协议
185
+
186
+ 仅用于 Compat。SDK 使用 [SDK Verify 协议](#sdk-verify-协议),领取回执代替下面的 `startupInput`,不提交旧 Runner 响应。
187
+
188
+ 启动、追加检查或等待 Verifier 前必须读取本节;填写输入遵循[填写命令输入](#填写命令输入)。
189
+
190
+ ### 平台任务与任务包
191
+
192
+ 沿用 `verifierDispatch` 的实际工作区、候选 ID、Verifier 执行引用、验收条目及 brief/Spec 引用;正文缺失时按分页读取全部 `scopeIds`。通过平台启动所需的只读任务,以真实会话提交 `verifier-started`;该回报只登记业务任务,不启动或监管进程。平台接受后持续等待同一任务,工具等待超时不代表执行失败。按[普通命令与检查](../../comet/reference/platform-execution.md)使用平台工具执行普通命令、核对原任务与副作用、判断结果是否适用,并提交实际报告。Comet 不重复执行检查,不维护普通命令的内容快照、进程监管或恢复机制。
193
+
194
+ ### 独立验收与结果
195
+
196
+ Verifier 全程只读,先提交任务包的 `startupInput`(`verifier-started`,重复无副作用)。读取当前 scope 的全部验收文字、brief、完整目标 Spec、实现和实际检查报告,核对版本、工作区、输入及覆盖范围。使用平台工具补充必要检查;独立判断 `scopeIds` 中每项。
197
+
198
+ Verifier 最后再阅读 Builder 交接,将其作为调查线索。Builder 只提供本轮实现的位置、验收项的编号与引用、检查记录位置、已知限制和相关文件位置;日志正文按需读取。
199
+
200
+ 等待工具超时后,继续等待同一个 Verifier。只有平台确认执行失败、执行超时、任务丢失或结束后没有可用结果时,才登记执行错误并重试。
201
+
202
+ 通过 `verifier-response` 提交结果时,响应只列出当前 `scopeIds`,每项恰好标记一次为 `passed`、`failed` 或 `blocked`;后两种情况写明原因。已通过且仍报告通过的合法超集会由 Runtime 过滤;不存在或重复的 ID、缺少当前 scope,以及 scope 外的 `failed` 或 `blocked` 仍会被拒绝。
203
+
204
+ 结果或检查请求因字段、格式或验收范围被拒绝时,按错误修正原输入,并使用返回的当前 `continuation` 重提;仍在运行的 Verifier 继续使用,不登记 `verifier-execution-error` 或重新派发。候选或执行绑定不匹配时先核对派发身份,旧任务的结果不能改成新任务身份后重提。实际检查执行失败、平台任务失败等情况,仍按对应失败路径处理。
205
+
206
+ 提交修复后的实现时,保留仍然适用的实际检查报告,并让新的正式 Verifier 在一轮内检查全部验收场景。全部通过后,直接等待用户接受验收结果;不会自动清空结果,再追加一轮相同的完整验收。
207
+
208
+ Verifier 无法完成任务时,区分以下情况:
209
+
210
+ - 平台支持 subagent,但本次任务未启动、执行失败、超时或结束后没有返回时,报告 `verifier-execution-error`。
211
+ - 只有当前平台确实没有可用的 subagent 能力时,才报告 `verifier-unavailable`。
212
+ - Runtime 因 Verifier 不可用而等待用户决定时,用户要求重试就执行 `commandAlternatives` 中的 `retry-verifier`。只有用户明确接受未经过独立验收的结果,才执行 `confirm-verifier-unavailable`。重试会保留本轮代码和已完成检查,不要要求用户恢复文件、服务、进程或回调。
213
+
214
+ 无法启动 Verifier、执行报错、缺少外部信息,或需要用户决定是否接受不完整验收时,必须先读取[命令输入与异常](#命令输入与异常),再按最新 `continuation` 处理。
215
+
216
+ 由 Skill 启动的最终 Verifier 判定通过、Runtime 等待用户决定时,只有用户接受当前结果,才使用 `--accept-result` 进入 Archive。用户要求修改实现或验收标准时,分别使用 `--revise-implementation` 或 `--revise-requirements`。
217
+
218
+ ### 中断检查
219
+
220
+ 按[普通命令与检查](../../comet/reference/platform-execution.md)使用平台工具执行普通命令、核对原任务与副作用、判断结果是否适用,并提交实际报告。Comet 不重复执行检查,不维护普通命令的内容快照、进程监管或恢复机制。 旧 `retry-checks` 不再执行命令。失败、超时、未执行和未知结果不能算通过。完成标准是 Runtime 已接受完整结果,返回实际的 Build、Archive、等待、阻塞或完成状态。
221
+
222
+ ## Supervisor 协作
223
+
224
+ 仅用于 Compat 的 `childSummary`、`readyChildren` 和 Runner 任务包。SDK 的 Child、集成与恢复使用 [SDK Run](#sdk-run) 的 Action 协议。
225
+
226
+ 分配任务、接收结果或集成前必须读取本节;首次填写输入或执行 `returnAction` 前必须读取[填写命令输入](#填写命令输入)。
227
+
228
+ ### 分配任务与核对任务标识
229
+
230
+ 用户确认一次 Supervisor Change 的 Shape,就授权执行已确认范围内的全部子任务,不要求用户重复确认相同范围。Skill 只执行 Runtime 在 `continuation` 中返回的动作,每个任务完成后重新读取 `readyChildren`。每个子任务都必须经过 `active → verified → integrated`;验证未通过、Verifier 失联登记失败、或 Agent 明确将已有候选退回重验时进入 `needs-reverify`,Runtime 会在下一次 `next` 自动为它重派 Verifier,`childSummary` 里计入 blocked。最后,Supervisor 主任务仍要在集成 worktree 检查全部验收项。
231
+
232
+ 处理 `childSummary` 时,不要运行 Supervisor Change Builder,只处理 `readyChildren` 列出的当前可执行子任务和 Supervisor 统筹动作。存在在途任务时,`readyChildren` 列出的是在途任务本身;容量未满且还有未派发子任务时,下一次 `next` 会在任务完成后自动派发。需要某个子任务的完整状态时再读取详情。
233
+
234
+ Runtime 为每个子任务返回 worktree、集成分支的当前提交、角色、任务包和 `runId`。Builder 与 Verifier 返回结果时必须携带当前 `runId`;Runtime 会拒绝重复提交或已经失效的任务结果。子任务检查中断时先核对原平台任务和副作用,再判断需补跑的检查。
235
+
236
+ 子任务不单独执行 Archive;原先通过 `finish=merge` 完成的合入步骤现由 Runtime 负责。只有经过 `active → verified → integrated`,且所选集成检查通过,才算完成集成。执行任务的 Agent 声称完成,或 worktree 中仍有未提交修改,都不能证明已经集成。
237
+
238
+ 选择多会话协作时,当前会话只负责分配任务、检查进度、处理阻塞、集成和 Supervisor 主任务的最终 Verify,不直接实现子任务。需要修改文件的子任务,只能使用 Runtime 为它创建的 worktree。不得为同一子任务另建 worktree,也不得写入 Supervisor 主任务或其他子任务的 worktree。
239
+
240
+ 分配任务时必须说明子任务角色、任务包、worktree、基线提交、`runId`、验收项的编号与引用、依赖关系和停止条件,并明确结果返回主 Agent,由主 Agent 顺序提交。主 Agent 使用实际接收者的会话身份领取,保留原 Action、领取身份和结果模板;子任务只写自己的 worktree,不直接推进父 Run。只启动 `readyChildren` 中列出的任务;不得让独立会话中的 Agent 或团队成员自行领取尚未满足启动条件的子任务。执行期间持续查看各会话的进度。发现实现偏离需求、权限或环境阻塞、需求范围不明确,或出现会改变用户可见结果的新决定时,立即反馈并处理,不等全部任务结束后再检查。
241
+
242
+ - 等待外部输入时,必须读取恢复参考中的[等待外部输入与监控](recovery.md#等待外部输入与监控):停止回复消息不等于暂停监控。只保留仍有任务可推进或外部状态需检查的监控,并及时告知用户阻塞原因和恢复条件。
243
+ - 在 Codex 中,如果可以管理用户可见的独立会话,就为每个当前可执行子任务新建一个独立会话,不要只启动当前会话内的 subagent。创建会话时沿用现有项目,不要让 Codex 另外创建 worktree;新会话必须先进入 Runtime 为该子任务创建的 worktree,后续所有文件和 Git 操作只在该目录执行。当前会话保存会话信息,通过等待或读取会话检查进度,并在需要修正或补充信息时发送后续指令。
244
+ - 在 Claude Code 中,如果可以使用 Claude Code Agent Team 且当前为交互式会话,就创建一个 Claude Code Agent Team。当前会话负责统筹,每个当前可执行子任务分配给一个有明确名称的团队成员。团队成员进入 Runtime 为该子任务创建的 worktree;团队任务列表只加入 Runtime 已允许开始的子任务。子任务是否可以开始、是否已经完成,最终以 Runtime 为准。团队成员不得创建新的 Claude Code Agent Team、直接集成父分支或自行扩大范围;当前会话持续读取消息和任务状态并及时引导。
245
+ - 如果 Codex 独立会话或 Claude Code Agent Team 不可用,或者恢复后已经找不到原来的会话或团队,先重新读取 Runtime 状态并说明原因,然后在 `multi-session` 下改用 subagent,不再询问推进方式。尚未分配的任务直接按最新 `readyChildren` 创建任务包。已分配任务的会话丢失时,先运行 `next --summary` 取得全部在途任务的完整任务包(含 `runId`、worktree 和基线提交),再通过原平台核对原执行及其后代是否已停止;会话不可访问和迟到结果被拒收都不能证明执行已停止。只有平台确认原执行及其后代已停止后,才用当前 `runId` 提交 `supervisor-cancel`,按最新 `continuation` 取得新任务包和新 `runId`,交给 subagent 执行。无法确认停止时,保留原 `runId` 和 worktree,报告阻塞原因及所需停止证据,等待核对;不得取消或重新派发,也不得继续修改该 worktree。subagent 也不可用时,如实报告任务无法执行的原因;不得自动改为单会话推进。
246
+
247
+ ### Supervisor 主任务最终验收
248
+
249
+ 全部子任务都进入 `integrated` 后,立即按 Runtime 返回的 `parentAdvance` 继续,并通知用户 Supervisor Change 进入最终 Verify,不要求用户再次说“推进”。最终 Verify 在集成 worktree 检查全部验收项。
250
+
251
+ 验收失败后,Agent 根据实际失败选择修复安排,父级可以修复其集成范围,也可追加名称唯一、引用有效验收 ID 的修复子任务。保留失败记录和预算,不重新打开已归档或 integrated 的子任务。需要修改计划时显式执行返回的 --revise-requirements,展示完整方案并确认;文件编辑不会自动退回 Shape。
252
+
253
+ 最终交付前不修改目标分支。最终 Archive、工作区收尾、merge、push 和 PR 各自仍须遵守用户的授权。
254
+
255
+ ### 子任务验收与集成
256
+
257
+ Builder 与 Verifier 沿用原任务的 `child`、`runId`、候选和实际 worktree,提交实际实现、检查及逐项验收报告。`supervisor-verifier-result` 的 `verdict` 为 `pass`、`fail` 或 `blocked`;`evidence` 保存真实摘要、检查和每项 `{id,result,reason}`。每个验收 ID 恰好出现一次,总结论与逐项结论一致,不提交普通检查 `receiptRef` 或内容快照。
258
+
259
+ SDK 的 Git 集成沿当前 Action 继续;Compat 由 Agent 在指定集成 worktree 通过平台工具完成合并与必要检查,再按 `supervisor-integrate` 模板提交实际 `integrationCommit` 和报告。没有实际提交时只返回平台操作指引,不执行检查或声称集成成功。冲突保留原现场,不在父分支或其他子任务工作区处理。集成后父级仍覆盖全部验收项。
260
+
261
+ ## 命令输入与异常
262
+
263
+ SDK 按 [SDK Run](#sdk-run) 与当前 continuation 核对同一 Action、领取和结果;以下 Runner 模板、`verifier-unavailable` 及 `--finish` 选项只用于 Compat,不能用于 SDK 恢复。
264
+
265
+ 正常流程直接执行 Runtime 在 `continuation` 中给出的命令。恢复时未提交动作输入的 `next --summary` 会返回当前模板并保留阶段,直接填写该模板继续,无需再查询一次 status。本节解释返回字段,并说明如何处理以下情况:命令输入被拒绝、无法启动 Verifier、Verifier 任务执行出错、Verifier 因缺少外部信息无法判断,或 Runtime 要求用户决定是否接受未完成独立验收的结果。`continuation.disposition` 说明现在应继续、等待用户、处理阻塞还是结束。只有用户明确确认后,才执行含 `--confirmed` 的后续命令。CLI 文本先给出用户可读的 `summary`、唯一 `NEXT:` 和可选的 `RELAY TO USER:`;用 `--json` 读取结构化响应,`--verbose` 仅用于排查本机执行状态。
266
+
267
+ 命令签名和当前参数始终以 CLI 为准:
268
+
269
+ ```text
270
+ comet native --help
271
+ comet native <command> --help
272
+ comet native <group> <command> --help
273
+ ```
274
+
275
+ ### Runtime 返回的下一步
276
+
277
+ - `disposition`:说明现在应该继续、等待用户、处理阻塞还是结束;`requiresUserDecision` 为 true 时转述消息并等待决定;`userCommunication.required` 也可能只是要求通知恢复进展,此时按已有授权继续;
278
+ - `commandArgs` / `commandAlternatives`:Runtime 要求执行的完整命令参数;每个备选操作对应一个互斥的用户决定,选择匹配项执行,不要合并多个备选操作;
279
+ - `inputOptions`:这次命令需要填写的字段和 JSON 模板;
280
+ - `workspace` / `preparation`:实际工作目录和 change 创建结果;
281
+ - `stateVersion` / `loop`:当前状态版本和验收循环进度;
282
+ - `acceptance` / `childSummary` / `readyChildren` / `supervisor` / `details.nextPageArgs`:验收计数、Supervisor Change 的子任务计数、当前可执行子任务、集成分支与当前任务包摘要,以及详情下一页命令;
283
+ - `verifierDispatch`:启动独立 Verifier 所需的工作区与证据位置、当前 `scopeIds`、`scopeCount`、全部验收项数量、正文引用、详情分页参数、复核摘要和检查结果;如果存在 `recoveryContext`,也要把它作为最近一次恢复或用户补充的信息直接传给 Verifier;
284
+ - `workspaceFinishResult` / `recoveryArgs`:归档后的工作区收尾结果和恢复命令。
285
+
286
+ Archive-ready 时执行最新 continuation。使用隔离工作区、且尚未选择收尾方式(finish)时,等待用户选择,然后执行对应的 `--confirmed --finish` 完整备选命令,保留状态版本参数;Runtime 记录选择并完成预检和事务内复验。用户在接受结果时已选择 finish 的,沿用该选择,不再询问。需要预览自定义提交说明时可先 dry-run;不要自行补其他参数。dry-run 会同时检查归档内容和 Git 收尾涉及的分支及文件;`ready: false` 时在同一响应中处理 `blockers` 和 `workspaceFinishBlockers[].paths` 的完整路径清单,不要额外运行 `status` 或手工提交 change 的状态/verification 文件。只有 `ready: true` 才执行返回的唯一 `archive --confirmed` 命令。
287
+
288
+ 模板中的尖括号表示需要填写的值。`await-user` 表示先等待用户决定,此时不执行推进命令。若 `commandArgs` 为 `null` 且返回了 `commandAlternatives`,先确认用户决定,再执行对应备选操作的完整 `commandArgs`,保留其中的 `--expected-state-version` 和 `--expected-action`。命令因状态过期或动作不匹配失败时,重新读取最新 `continuation`,按当前状态继续;不要自行拼接缺少状态校验参数的命令。平台任务是否仍在运行须通过原平台核对,不能仅凭本地文件缺失判断。
289
+
290
+ ### 异常动作输入
291
+
292
+ - `verifier-execution-error` / `verifier-unavailable`:平台支持 subagent,但本次任务未启动、执行失败、超时或结束后没有返回时使用前者;只有当前平台确实没有可用的 subagent 能力时才使用后者。模板中的任务关联字段必须原样保留,避免旧任务的迟到消息影响新的 Verifier。
293
+ - `retry-verifier` / `confirm-verifier-unavailable`:Runtime 在 Verifier 不可用状态返回这两个 `commandAlternatives`。用户要求重试时选择前者,本轮代码和已完成检查会保留;只有用户明确接受“仅完成自动检查、没有独立验收”的结果时,才选择后者。
294
+
295
+ ### 异常情况
296
+
297
+ - 无法启动独立 Verifier:先确认适用检查已经列明,且 Runtime 检查全部通过;随后按模板报告 unavailable,等待用户决定是否接受“只有命令检查通过、没有 Verifier 独立核验需求”的结果。
298
+ - Verifier 暂时无法判断(`semantic blocked`):如果只缺用户或外部信息,执行 Runtime 返回的解决动作;如果需要修改实现,回到 Build。
299
+ - 由 Skill 启动的 Verifier 判断全部通过(`skill-coordinated pass`):这表示检查已经完成,但系统无法确认验证者是否独立;Runtime 会显示“已完成检查,但需要你确认验证结果”,用户确认后再执行返回的命令。
300
+ - 如果显示“无法完成完整验证,只完成了自动检查”,表示没有 Verifier 独立核验需求,只有 Runtime 自动检查结果;只有用户明确确认后才能继续归档。
301
+ - 用户确认接受这种不完整结果后,显示“你已确认接受不完整验证结果”;这只表示用户接受了不完整的验收结果,不能据此宣称已经完成独立验证。
302
+ - Verifier 任务执行出错(`execution error`):按模板提交错误,再读取新的 `continuation`。Agent 根据当前候选和实际检查结果判断复用或重试。
303
+
304
+ ### 诊断
305
+
306
+ 正式项目规格必须通过当前 change 的完整目标规格和 Archive 更新,不能直接修改已发布的规格。
307
+
308
+ 只修正已确认目标规格中的本地 Markdown 链接目标时,可以执行 `spec sync`:
309
+
310
+ - 输入包含 `expectedStateVersion`、`actor`、`reason`、`affectedAcceptanceIds` 和 `replacements: [{from, to}]`。
311
+ - `affectedAcceptanceIds` 须包含受影响 Spec 的全部验收项。正文、示例或验收含义发生变化时,仍须回到 Shape。
312
+ - Runtime 保存修改前后的内容及原因,保留未受影响的验收结论,并回 Build 重新验证受影响内容。
313
+ - 同步中进程突然中断、状态尚未保存时,恢复流程会发现规格与已保存状态不一致,并回到 Shape;尚未保存的修正不能当作已确认结果。
314
+
315
+ Verifier 失联时,使用普通 `next --summary` 恢复。Runtime 返回恢复指引(await-user),不会自动转换状态;按指引登记 `verifier-execution-error` 后,Runtime 才把中断的任务转为可重新验收的状态。不要无限等待旧 Verifier 任务,也不要反复重跑 `next`。
316
+
317
+ 在原 worktree 使用返回的明确目录读取状态,不自动搜索其他 worktree。当前工作区出现 active 与 archive 记录冲突时,按只读诊断和明确恢复入口处理;不能仅凭名称相同或版本号更大就认定任务完成。
318
+
319
+ 先运行只读 `doctor`。只有 `doctor` 明确给出修复命令时才执行;Runtime 维护跨设备业务状态和实际文件事务,普通流程不恢复锁。
320
+
321
+ Agent 根据当前候选和环境判断原检查结果是否适用,保留真实执行来源,只补缺失或失效的检查。按当前结果模板提交报告,不提交旧检查计划、文件指纹或 edit-review 记录。
@@ -0,0 +1,26 @@
1
+ # 编辑后继续原流程
2
+
3
+ Build、Verify 或待归档阶段发生编辑时,由当前 Agent 判断实际影响。文件内容变化不自动撤回批准、作废检查或重置阶段;不提交文件指纹、hash 或逐文件保留证明。
4
+
5
+ 1. 读取实际改动、当前需求、相关调用和已有检查结果。可使用 Git 差异和当前文件;缺少必要上下文时补读原文,不以文件大小、扩展名或摘要替代判断。连续保存合并处理,不逐次增加审查或确认。
6
+ 2. 根据实际影响继续工作:说明、注释或排版未改变行为和验收含义时,保留原 Run、阶段、批准、报告和检查;实际实现变化时,沿当前流程修订实现并验收;目标、验收标准、方案或授权范围变化且原决定未覆盖时,只请求受影响的决定。
7
+ 3. Agent 使用平台工具执行必要检查并读取实际结果。原检查仍适用时保留其真实来源;需要补查时只执行所需命令。不要求 observe、prepare-applied、record、retainedChecks 或内容证明链。按当前 Action 模板向 CLI 提交实际检查报告,普通编辑不增加独立审查会话。
8
+ 4. 新失败、中断、超时、结果未知和未执行均如实保留。修复后用实际新结果更新结论,不能用旧成功覆盖最新失败,也不能把历史检查描述成本轮执行。已经完成的单次操作不自动重放。
9
+ 5. 已接受结果尚未归档时,Agent 确认当前改动仍符合原需求和验收结论,再继续原归档;需要修复或补查时按实际影响处理。归档中断沿原事务继续,Runtime 记录哪些写入和目录移动已完成,避免重复副作用。
10
+
11
+ 用户确认、明确要求的独立验收、阶段权限、路径和工作区隔离继续生效。Runtime 维护步骤、执行者、命令、退出状态、日志路径、用户决定和归档进度;共享 SDK 的 Action 请求标识、安装包摘要和 Git 提交 ID 保留。
12
+
13
+ 完成条件:Agent 已核对改动影响,必要检查有实际结果,当前结论与用户要求一致,原流程能够继续。没有新增信息时不为记账重开 Build 或 Verify。
14
+
15
+ ## Agent 判断与 CLI 执行
16
+
17
+ Native 与 Classic 由当前 Agent 判断需求、文档和开发进展;CLI 执行明确选择的操作,保存原 Run、用户决定、真实结果和恢复进度。
18
+
19
+ - 文档是否完整、需求是否明确、是否需要目标 Spec,由 Agent 对照用户请求与项目要求判断。模板是写作参考,固定标题、措辞、语言比例和设计文档 frontmatter 不作为完成证明。机器需要的验收项、任务 ID、路径和结果字段按当前响应填写;存在未解决的用户决定时先处理该决定。
20
+ - 选择与任务匹配的现有 workflow/preset。Classic full 保留设计、实施计划和用户批准;外部工具真正要求的材料继续满足。已有 Run 和正式材料可供交接时直接使用,不为阶段切换重复抄写相同内容。需要独立材料供人阅读或外部工具使用时再生成。
21
+ - Agent 明确选择检查命令、工作目录及本次范围,使用平台工具执行并读取真实退出状态,再向 CLI 提交报告。状态查询和 Guard 只读取结果,不自行猜测并启动 Build。原命令仍在运行或结果未知时,先核对同一执行。
22
+ - 每轮失败后结合实际修改与结果决定继续修复、换方案或请求帮助。验收项 ID 集合未缩小不等于没有进展。使用现有说明表达判断,无需评分或进展证明;用户预算和实际执行上限仍生效。
23
+ - 优先使用当前 workflow 的业务入口和返回模板。CLI 装配 SDK 的 Action、领取和并发控制参数,并连续处理已经授权的内部步骤;用户决定、不同执行者、真实失败或外部等待仍返回当前实际下一步。恢复沿用原 Run 和原执行。
24
+ - Agent 判断是否值得并行及如何拆分任务。Runtime 维护实际依赖、工作区、任务状态和 Git 操作;父级验收覆盖全部已确认验收项,复用适用的子任务结果并补足缺口。用户选定的协作方式和独立验收要求继续保留。
25
+
26
+ 完成条件:需要的用户决定已有明确记录,当前任务的实际结果可核对,验收覆盖已确认要求,归档与交付按原授权和真实进度完成。缺少检查、执行失败、超时或未知结果时如实说明,不能写成通过。
@@ -0,0 +1,64 @@
1
+ # Native 恢复参考
2
+
3
+ 只读取当前阻塞对应的章节。
4
+
5
+ ## 等待外部输入与监控
6
+
7
+ - 暂停条件:相关工作只等待用户答复或外部资料,且没有可执行子任务、没有仍在执行的相关任务,也没有需要定期检查的外部状态时,暂停当前工作的定期监控。保留独立任务及其监控。仍在执行的任务,或仍需查看结果的 CI 和外部作业,继续使用平台的等待或监控功能。
8
+ - 暂停操作:能够确定哪个自动化任务属于当前工作、且平台允许管理时,调用平台功能实际暂停监控,并核对返回状态。返回信息不足时,再查询该自动化任务的状态。无法识别、权限不足或暂停失败时,明确说明监控尚未确认暂停,以及需要用户执行什么操作。停止回复消息不等于停止定期触发任务;不得操作归属不明或无关的自动化。
9
+ - 等待说明:首次进入等待时,一次性告知用户阻塞原因、缺少的资料、实际暂停了哪些监控、哪些任务仍在运行,以及恢复条件。将这些信息、对应监控标识和暂停结果写入已有的任务记录,不另建一种正式文件格式。
10
+ - 恢复条件:收到相关新输入,或确认所需条件已经满足后,重新读取 Runtime 状态,沿用原 change、任务标识和已完成结果,按最新 `continuation` 继续。普通进度消息不能解除阻塞,也不能因此重新分配已经完成的任务。只有仍需定期检查时,才恢复对应监控,并核对是否恢复成功。
11
+ - 区分状态:平台任务空闲或定期监控暂停,不等同于 Runtime 的 `blocked` / `await-user`。只有现有公开命令适用于当前阶段和阻塞原因时,才通过命令更新 Runtime 状态。否则记录任务被什么问题阻塞,并暂停依赖该信息的工作;不得直接修改状态文件,也不得用 Verifier 状态表示缺少实现所需的资料。
12
+
13
+ ## 故障恢复
14
+
15
+ 若 SDK change 的本机 Run 记录丢失,先用 `comet native doctor <change-name> --json` 只读检查,再按返回的明确恢复或导入动作继续。原 `comet-state.yaml` 中的 `run_checkpoint` 或已知旧业务来源用于恢复已保存的阶段、Action、领取和有效批准;`status` 不写入或恢复记录。缺少可信来源时保留现场,不自行回到 Shape 或重做批准。继续外部工作前,通过原平台核对尚未结束或结果未知的任务,不能重放可能已发生的副作用。
16
+
17
+ 命令已返回具体错误、当前状态和恢复动作时,先按该响应处理。Runner 输入校验失败按[填写命令输入](commands.md#填写命令输入)修正,归档提交或合并失败按[Archive 收尾](workspace.md#archive-收尾)继续,仍在运行的任务保持原标识。没有当前状态、调用中断或现场与响应不一致时,先停止依赖该状态的修改,运行一次 `status --details --json`;状态或恢复记录仍无法解释问题时,再运行只读 `doctor`。只执行 `continuation` 或 `doctor` 明确返回的恢复动作。业务状态和真实归档事务由 Runtime 管理,平台任务由 Agent 通过原平台核对与清理;无法确定自动恢复是否安全时,保留现场并等待用户决定。
18
+
19
+ 仅等待外部输入时,按[等待外部输入与监控](#等待外部输入与监控)处理,独立工作继续。恢复后重新分配 Supervisor 任务前,必须读取[Supervisor 协作](commands.md#supervisor-协作);重新启动 Verifier 前,必须读取[Verify 协议](commands.md#verify-协议),核对当前任务标识、待验收的实现版本和执行状态。
20
+
21
+ SDK 恢复时只读取 commands.md 的 SDK Run 与 SDK Verify 协议;以下 Compat Runner、启动回执和工作区收尾字段不用于 SDK。
22
+
23
+ ### 工作区
24
+
25
+ 在当前工作区使用已知 change 或 Run 继续。目标位于其他 worktree 时,进入其已知目录再执行 `select`;普通状态命令不自动搜索所有 worktree。恢复时沿用找到的 change 和工作目录,不复制 change,也不在其他目录重建同名 change。
26
+
27
+ 如果项目根目录、分支、工作区类型或 Git 状态与 `comet-state.yaml` 中的记录不一致,Runtime 会阻止写入。Runtime 能安全找到或创建已声明的 worktree 时,按返回动作继续;否则进入阻塞等待用户决定(`disposition: blocked`,recovery action 为 `await-user`)。原目录或分支确实丢失时,由用户决定使用哪个恢复目录、是否从可信备份重建,或是否放弃 change。
28
+
29
+ ### 旧版本业务记录
30
+
31
+ 在原 change 和原 Run 继续。入口自动适配旧业务数据,保留已接受的 Shape、用户决定、任务与候选;使用新版返回的任务模板。旧检查执行器、PID、停止握手和内容快照不再恢复。尚未结束或结果未知的任务先通过原平台核对,不把取消业务调度解释为进程已经停止,不盲目重跑可能产生副作用的命令。
32
+
33
+ SDK Run 缺失时使用原 `run_checkpoint` 或已知旧数据源恢复业务记录;缺少可信来源时保留现场,按 `doctor` 返回的明确导入或恢复入口处理,不搜索其他工作区猜测进度。报告是业务状态的阅读视图,不能代替原批准或真实检查结果。
34
+
35
+ ### 没有聊天记录时跨设备恢复
36
+
37
+ 在没有聊天记录的新设备上恢复时,需要取得同一份已同步项目代码、`comet-state.yaml`、brief 和目标 Spec。如果 change 使用非默认产物目录,还需要同步 `.comet/config.yaml`。SDK change 的 `run_checkpoint` 随状态文件一起复制,恢复时保留已完成的 Shape、Build 及仍有效的决定;本机执行中的 Action 需要核对实际结果。
38
+
39
+ 先停止旧设备上的推进并完成同步。发现 Git 冲突,或同一状态版本出现两份不同内容时,进入阻塞状态并交给用户处理。
40
+
41
+ 旧设备上尚未同步的代码不能仅靠业务状态恢复。先通过原平台核对任务和副作用,再判断同步后的实现、环境和已有结果是否仍适用,只补缺失或失效的验收证据。
42
+
43
+ 恢复沿用原任务和轮次;只有实际重新提交候选、启动验收或收到失败结论时才按相应业务规则更新计数。已经接受的 Shape 和 Build 不因机器变化自动重做。
44
+
45
+ ### Verify 未通过与执行失败
46
+
47
+ 读取实际失败或无法验证的条目和检查结果,由 Agent 判断修复方向与进展,完成必要修改后提交新的 Builder handoff。验收编号重复、交替或集合未缩小不触发额外暂停。
48
+
49
+ 真实失败达到 `native.max_verify_failures`,或 Verifier 多次执行出错时,按当前响应处理预算或恢复原执行。不能将未知或失败结果记为通过;沿用原 Run、有效批准和已有结果。用户确认新的目标周期时按原协议记录需求变化。
50
+
51
+ ### 规格与 Archive 冲突
52
+
53
+ 如果项目中已经归档的正式 Spec 在当前 change 期间发生变化,重读最新正式 Spec、brief 和当前 change 的完整目标规格,按用户意图改写后执行 Runtime 冲突信息中给出的重新对齐(rebase)动作,再重新实现和验收。并发产生的新内容应保留。
54
+
55
+ 多个工作区的 active change 可以修改同一功能区域(capability)。Archive 只处理当前正式 Spec 的实际冲突;按返回的冲突与重新对齐动作保留双方内容。原 Run 已有待决定的提案时,仍保留该提案并等待原用户决定。
56
+
57
+ Archive 或 change 目录移动中断时,以 `doctor` 返回的事务状态和允许动作作为恢复依据。路径、工作流状态和实际文件互相对不上时,保留两侧现场并等待明确的恢复动作。
58
+
59
+ 若工作区收尾结果 `workspaceFinishResult.status` 为阻塞(`blocked`),change 可能已经完成归档或 Git 提交。先执行 `recoveryArgs` 检查实际 Git 状态,再根据返回结果决定下一步。
60
+
61
+ ### 损坏状态
62
+
63
+ - config、change、brief、规格或 verification 损坏时,保留原文件并等待 `doctor` 或用户给出恢复来源。
64
+ - 同一个 change 同时出现在 active 和 archive、无法确定文件归属,或无法判断事务进行到哪一步时,保留现场并停止写入。
@@ -0,0 +1,70 @@
1
+ # Native 工作区参考
2
+
3
+ ## 创建 change
4
+
5
+ 先确定 change 名称,使用小写字母、数字和连字符(kebab-case),并采用配置指定的产物目录。创建前,CLI 会关联分支或 worktree,复用或重建已登记的 change worktree,维护仓库本地排除规则,并核对配置。准备失败时,保留已创建的分支和目录,按 `preparation` 返回的原因和恢复建议处理。
6
+
7
+ 只在创建 change 时读取本节,确定使用哪个工作目录。创建后进入 `preparation.projectRoot`。`comet init` 会按所选 Skill 的语言初始化 `native.language`;后续文档使用项目配置中的语言,只有用户明确要求改用其他语言时,才传入 `--language`。
8
+
9
+ Supervisor Change 中由 `readyChildren` 返回的子任务固定使用独立 `worktree`,并以 Supervisor Change 的 `workspace.changeBranch` 为目标分支;其他 change 在用户已经指定 `current`、`branch` 或 `worktree` 时直接采用。
10
+
11
+ 明确表达并行、同时处理或多个会话时,直接使用 `worktree`,不再询问三种方式。未指定隔离方式且没有明确并行意图时,出现以下任一情况才询问用户:
12
+
13
+ - 当前目录有未提交工作;
14
+ - 已有其他 active Native change;
15
+ - 用户要求并行开发或隔离工作,但没有指定方式。
16
+
17
+ 没有这些情况时使用 Runtime 默认的 `current`。
18
+
19
+ 需要询问时,用单选题让用户选择工作区隔离方式:
20
+
21
+ | 选项 | 方式 | 实际影响 |
22
+ | ---- | ------------------------- | ---------------------------------------------------------------------- |
23
+ | A | 当前目录(`current`) | 沿用当前分支和目录,不创建新的 Git 分支或工作目录 |
24
+ | B | 新分支(`branch`) | 在当前目录切换到新的 change 分支;要求当前工作区干净 |
25
+ | C | 新 worktree(`worktree`) | 创建或复用独立分支和工作目录,适合并行 change 或当前目录已有未提交工作 |
26
+
27
+ 展示符合当前状态和用户要求的全部选项,不要仅凭推测后续命令可能失败就删去选项。用户明确要沿用当前分支时推荐 A;需要独立分支且无需并行工作时推荐 B;需要并行开发、当前目录已有工作,或已有 active Native change 时推荐 C。
28
+
29
+ 推荐不能代替用户选择;用户选择后再创建工作区。已登记的 `worktree` 仍与 change 分支关联时,Runtime 会复用它;分支仍存在但对应 `worktree` 已移除时,Runtime 会重建它。
30
+
31
+ 只有分支已重命名、被用户接管或无法确认归属时,必须先读取[工作区恢复](recovery.md#工作区),再按 Runtime 指令请求用户重新绑定工作区(rebind)。提问前必须读取[提问方式与模式](clarification.md#提问方式与模式):优先使用结构化单选工具;工具不可用时使用编号文本并等待回答。只有一个符合当前条件的选项时,说明原因并直接采用。
32
+
33
+ ## Archive 收尾
34
+
35
+ SDK:执行 continuation 的 Archive 命令,不携带 Compat 的 finish 或 confirmed 参数。Run completed 与业务 done 只证明 SDK 归档;先读取 Run 保存的交付结果并核对实际 Git,只补未完成动作,不重复已完成的提交或集成。归档后核对当前绑定分支、目标与本 change 改动,显式暂存并审查 staged diff,按已有授权完成提交、merge、push 或 PR。分别核对提交 SHA、目标分支、远端 SHA 和真实 PR;结果未知先只读核对再恢复。保留无关改动与脏工作区。没有外部交付授权时只说明已归档及当前保留位置;已有授权时继续完成,不再询问相同选择。
36
+
37
+ 以下收尾选项、workspaceFinishResult 与恢复命令仅用于 Compat。
38
+
39
+ 只有 `continuation` 允许 Archive 时才继续。归档直接使用已接受的验收结果。用户接受结果时已经选择了收尾方式的,沿用该选择,不再次询问。使用 `current` 工作区时,不需要选择收尾方式:展示当前分支和目录,说明不会执行 merge、push 或创建 PR,再按最新 `continuation` 继续。
40
+
41
+ 使用 `branch` 或 `worktree`、且需要选择收尾方式时,一次展示实际 change 分支、目标分支和目录,用单选题提供以下全部选项。文本提问必须使用下表;结构化提问必须将“方式”作为短标签、“实际影响”作为说明,不得只显示 `merge`、`push`、`pull-request` 或 `keep`。
42
+
43
+ | 选项 | 方式 | 实际影响 |
44
+ | ---- | ------------------------------------- | ----------------------------------------------------------------------------------- |
45
+ | A | 仅归档并保留工作区(`keep`) | 完成归档并在 change 分支创建归档提交;不合并、不推送、不创建 PR,保留当前分支和目录 |
46
+ | B | 本地合并(`merge`) | 完成归档并创建归档提交,再把 change 分支本地合并到目标分支;不推送、不创建 PR |
47
+ | C | 归档并推送(`push`) | 完成归档并创建归档提交,再推送 change 分支;不合并到目标分支、不创建 PR |
48
+ | D | 归档、推送并创建 PR(`pull-request`) | 完成归档并创建归档提交,推送 change 分支,再以目标分支作为基础分支创建 PR |
49
+ | E | 暂不归档 | 不执行归档或工作区收尾,保留当前仍在进行的 change 和工作区,等待稍后继续 |
50
+
51
+ 用户选择 A、B、C 或 D 后,分别按 `keep`、`merge`、`push` 或 `pull-request` 执行 Runtime 返回的完整命令;选择 E 后停止。Archive-ready 时按以下顺序操作:
52
+
53
+ 归档前沿用已生效的项目提交规范,准备归档提交说明;选择本地合并时也准备合并说明。格式、语言和正文要求已有明确规范时直接采用,无需再次询问;存在冲突或缺少必须由用户提供的信息时,只询问缺失内容。通过公开的 `--commit-message <text>` 传入归档说明,`--merge-message <text>` 仅用于 merge。中文和多行正文须作为一个完整参数传入。没有项目约定或用户要求时可沿用默认说明,项目 Git Hooks 始终正常执行。
54
+
55
+ 1. 执行最新 continuation。隔离工作区尚未选择 finish 时,等待用户选择后执行对应的 `--confirmed --finish` 完整备选命令,保留状态版本参数;Runtime 一次完成预检和事务内复查。需要预览自定义说明时,执行 `archive --dry-run --finish` 并补入上述消息参数,选择 merge 时同时核对合并说明。除公开消息参数外,保留 Runtime 给出的工作区、确认和串行归档参数,不自行增删。
56
+ 2. dry-run 返回 `ready: false` 时,只处理同一响应列出的阻塞。不要先额外运行 `status`、重复 Archive,或手工提交 Native 的状态和 verification 文件。
57
+ 3. dry-run 返回 `ready: true` 后,核对 `commitMessages` 与已准备的说明一致,执行它返回的唯一 `archive --confirmed` 命令,完整保留消息内容;不再重跑相同预览或重新拼接说明。
58
+ 4. dry-run 或 confirmed 失败时,只按最新结构化 `continuation` 和 `workspaceFinishResult.recoveryArgs` 继续,不从错误文本猜测下一步。
59
+
60
+ 选择 A 表示保留当前分支和目录,同一次归档不得删除该 worktree。其他普通 change 归档后,如果该 change 的 worktree 已没有未提交修改,向用户提供清理选项;Runtime 已清理的无需再次询问。只有用户确认后才执行 `git worktree remove`,存在未提交修改或仍在使用的 worktree 必须保留。
61
+
62
+ Supervisor 最终交付后,Runtime 只自动清理没有未提交修改、且不再使用的子任务 worktree、集成 worktree 及其分支。发现未提交文件、当前进程仍在其中或 Git 步骤未完成时,保留现场并返回阻塞原因,绝不强制删除。
63
+
64
+ 只提交属于当前 change 的实现和正式文件,保留其他用户改动。执行 Runtime 返回的 `commandArgs` 后,检查工作区收尾结果 `workspaceFinishResult`。结果为阻塞(`blocked`)时,保留现场,说明原因,并在已有交付授权内修复后执行 `recoveryArgs`,不要求用户再次说“重试”。只有恢复需要新的权限、用户信息或交付方式时才询问;恢复完成前保持交付待完成。
65
+
66
+ 项目 Git Hook 拒绝提交或合并说明时,卷宗可能已封存而 Git 收尾尚未完成。按项目规范修正尚未完成步骤的说明,在返回的恢复命令中传入对应消息参数;Runtime 复用已完成的归档提交、Spec 发布和合并。已完成提交的说明不能通过恢复改写,也不绕过 Hook 或重新创建 change。
67
+
68
+ 用户或 Agent 已按授权手动完成 Git 收尾时,先运行 `comet native doctor <change-name> --json`,按返回的恢复命令继续。`doctor --repair` 对本地 keep / merge 收尾只在卷宗身份、提交内容和所选收尾条件得到证明后清理记录;push / pull-request 仍通过 Archive 核对远端和平台结果。Doctor 不代替提交、合并或推送。归档目录存在或 portable 状态为 done 不代表工作区交付完成;以公开状态和收尾结果为准。
69
+
70
+ 完成标准:状态为 `done`,用户授权的工作区收尾结果为已完成(`completed`)或已保留(`kept`);其他结果按 `continuation` 继续。任务结束时,用启动时保存的原始请求、workflow、change 和同一个 session 调用 `comet task --complete`。不要运行 `printenv COMET_TASK` 或读取其他未声明的环境变量来猜测任务内容。