@loomhelm/multi-task-flow 0.0.0-stage → 0.2.6

package/toolkit/skills/docs/vendor/dot-codex/specs/q9r2m-review-proof-ownership/HISTORY.md

@@ -0,0 +1,19 @@
+# Review proof ownership 演进历史（#q9r2m）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `6d1ac7f` fix(review): preserve active proof lifecycle
+- `8a262c7` docs(review): align proof startup with codex runtime
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Legacy Change Log
+
+- No legacy change-log section was recorded for this spec.
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#q9r2m`.

package/toolkit/skills/docs/vendor/dot-codex/specs/q9r2m-review-proof-ownership/IMPLEMENTATION.md

@@ -0,0 +1,57 @@
+# Review proof ownership 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: startup_success 仅认真正审查进展输出，init timeout 提高到 300s；sandbox 真相源改看 runtime banner
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-16
+- Legacy last-tracked: 2026-04-12
+- Current lifecycle: active
+- Catalog note: startup_success 仅认真正审查进展输出，init timeout 提高到 300s；sandbox 真相源改看 runtime banner
+
+## Delivery Milestones
+
+- [x] M1: 建立 review proof ownership 规格并登记索引
+- [x] M2: 收紧 `$codex-review-loop` 的 startup / timeout / restart / stale-proof 契约
+- [x] M3: 收敛共享 wait-state 规则并瘦身下游 skills/prompts
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `skills/codex-review-loop/SKILL.md`
+- `skills/project-engineering-workflow/references/review-proof-short-contract.md`
+- `skills/pr-create/SKILL.md`
+- `skills/pr-merge/SKILL.md`
+- `prompts/goto-impl-branch.md`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `6d1ac7f` fix(review): preserve active proof lifecycle
+- `8a262c7` docs(review): align proof startup with codex runtime
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Remaining Gaps
+
+- None currently tracked.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/q9r2m-review-proof-ownership/SPEC.md

@@ -0,0 +1,136 @@
+# Review proof ownership
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 最近的 review 失败链路里，真正的问题不是 `codex review` 本身一定卡死，而是外层 flow 把一个已经启动并开始产生可观测 proof-side 输出的 review proof，当成了共享 `外部门禁等待态` 的一部分。
+- session `019cf1f6-91b2-7893-ad95-80830ce62973`、`019cf1fc-c964-7e31-a392-78d8e4934121`、`019cf209-cfbf-7e32-97a9-8b1a050d5cbf`、`019cf215-42d3-7883-b991-fa1f824ec42f` 共同说明：上层会因为轮询预算或“先停掉卡住 proof”的主观判断，提前向运行中的 review proof 发送 `Ctrl-C`。
+- 这与后续 `Missing environment variable: CVM_API_KEY` 属于不同故障：前者是生命周期 ownership 错了，后者是子进程启动环境缺失。
+
+## 目标 / 非目标
+
+### Goals
+
+- 明确 `codex review` 一旦成功启动并出现首条可观测 proof-side 输出，生命周期就归 review proof 自身管理，而不是归共享等待预算管理。
+- 把初始化阶段的“是否成功启动”与运行阶段的“是否超时”拆开，避免短暂无输出就被上层误判并主动中断。
+- 明确 `--sandbox read-only` 只表示请求形状；proof 的实际 sandbox 真相必须以 runtime banner / 会话输出为准。
+- 把允许的自动介入条件收窄到：初始化失败、初始化超时后的一次重启、运行超时、主人显式要求停止。
+- 让共享 workflow、PR 短规约、下游 skills 与 prompts 在 partial read 下都先看到同一条 ownership 规则。
+- 在修复契约的同时压缩重复文案，避免 skill 越修越长。
+
+### Non-goals
+
+- 不修改 Codex runtime 或 CLI 的底层进程管理实现。
+- 不解决 `CVM_API_KEY` 继承链路；该问题继续单独归类为“启动失败”。
+- 不新增新的统一状态字段。
+
+## 范围（Scope）
+
+### In scope
+
+- 更新 `docs/specs/README.md` 与本规格文档。
+- 更新 `$codex-review-loop` 的启动成功判定、初始化重启边界、运行超时与 stale-proof 处理契约。
+- 更新 `$project-engineering-workflow` 与 `pr-diagnosis-short-contract.md`，把 active review proof 从共享等待预算中剥离出来。
+- 瘦身 `$fast-flow`、`$pr-create`、`$pr-merge` 与相关 prompts 的重复 stop 规则。
+
+### Out of scope
+
+- 修改 `gh CLI` 远端操作语义。
+- 引入新的回放测试框架或会话重放脚本。
+- 更改 Step 1-4 的普通工程流程。
+
+## 需求（Requirements）
+
+### MUST
+
+- `startup_success` 必须定义为：review proof 出现首条真正审查进展输出；`thinking`、`exec`、findings 或最终结论都算，banner/header、prompt 回显、空轮询、外层包装器噪音与无关 shell chatter 不算。
+- `INIT_STALL_TIMEOUT_SEC=300` 必须成为真实的“未出现首条真正审查进展输出”的启动失败判定阈值，而不再只是 warning。
+- 初始化阶段自动重启最多 `1` 次；运行阶段不得再有自动重启预算。
+- 一旦 proof 已达到 `startup_success`，外层除了“主人显式要求停止”或“运行阶段超时”外，不得主动发送 `Ctrl-C` / kill / 其他 stop 信号。
+- 运行阶段超时保持为“连续 `15` 分钟无新业务输出”。
+- 若 proof 运行过程中 `HEAD` / `PR.head.sha` / `PR.base.sha` 变化导致该 proof 结果过期，不得主动杀掉现有 proof；只能在其终态后把结果判为 stale，并决定是否对最新事实补新的 proof。
+- `Missing environment variable: CVM_API_KEY`、命令缺失、会话启动失败等情况必须继续归类为“启动失败/硬失败”，而不是“误终止”。
+- 若 direct launch 命令请求了 `--sandbox read-only`，agent 仍必须以 runtime banner / 会话输出判断 proof 的实际 sandbox mode，不得只凭 CLI 参数断言已经处于真正的 read-only。
+- 对 pre-PR / direct proof 而言，若 runtime 事实表明该 proof 实际不是 read-only，则这次 direct proof 不能充当合格的 direct read-only gate；调用方必须阻断或升级到受治理的 writable review-loop 路径，不能把这次 writable fallback 当作“同一个 direct proof 继续有效”。
+- 所有 direct-proof caller（包括 final merge-proof / merge-path caller）都必须继承同一条 runtime sandbox 真相规则；不得只在部分入口修正，而让其他 caller 继续把 writable fallback 当作 read-only evidence。
+
+### SHOULD
+
+- 共享等待预算只覆盖 GitHub 可见的外部门禁等待，不覆盖已经成功启动的本地 review proof。
+- 下游 skills 与 prompts 应只保留薄 guardrail，并引用共享短规约，而不是各自重复整段 ownership 逻辑。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- 初始化阶段：
+  - 从 review 进程启动开始，到出现首条真正审查进展输出之前，都属于 init。
+  - `thinking`、`exec`、findings 或最终结论都算 `startup_success`；banner/header、prompt 回显（例如 `user current changes`）、空轮询、纯 shell echo、外层 provider/bootstrap 噪音都不算。
+  - 若 `300s` 内仍未出现首条真正审查进展输出，则本次 proof 视为“未成功启动”；最多允许自动重启 `1` 次。
+- 运行阶段：
+  - 一旦看到首条真正审查进展输出，立即进入 `phase=running`。
+  - 此后共享 wait budget 只能继续轮询与转述，不再拥有 stop 权限。
+  - 若先看到 banner、随后只出现 prompt 回显而没有进一步审查进展，这仍属于 init；只有出现真正审查进展输出后，后续沉默才按运行阶段规则处理。
+  - 若连续 `15min` 无新业务输出且会话仍存活，才允许按 timeout 终止并记为 `stalled/timeout`。
+- stale-proof：
+  - 如果 proof 运行期间出现新的 `HEAD` / `PR.head.sha` / `PR.base.sha`，现有 proof 只是“未来可能 stale”，不是立即可杀对象。
+  - 该 proof 自然结束后，若它绑定的事实已过期，则结果只可用作诊断证据，不可作为最新 fresh proof。
+  - 若 direct requested-read-only proof 的 runtime 实际可写，并在此过程中改变了本地 `HEAD`，则旧 direct proof 立即失去“直通 gate”资格；后续只能先刷新事实到最新 `HEAD`，再走受治理的 writable review-loop / validation 路径。
+
+### Edge cases / errors
+
+- 若会话在 init 阶段直接报环境缺失、命令错误或 session 中断，按 init hard failure 处理，可用掉仅有的一次 init restart。
+- 若 proof 已经进入 running，但随后 session 异常断开，按运行阶段硬失败/超时路径处理，不得写成“共享等待预算耗尽”。
+- 若 proof 尚未真正启动成功，只是“准备启动 fresh proof”，那仍可被共享外层流程视为尚未进入 active proof ownership。
+
+## 验收标准（Acceptance Criteria）
+
+- Given 一个 review proof 已出现首条真正审查进展输出 When 外层 flow 继续轮询 Then 外层不得因为共享等待预算、轮询次数或主观“先停掉卡住 proof”而主动中断它。
+
+- Given 一个 review proof 在 `300s` 内没有任何首条真正审查进展输出 When 外层判定启动状态 Then 该 proof 必须被视为 init failure / init timeout，且最多只允许自动重启一次。
+
+- Given 一个 review proof 已经输出 prompt 回显，但尚未出现任何真正审查进展输出 When 外层继续等待后续审查内容 Then 该 proof 仍停留在 init；若后续一直没有真正审查进展输出，必须继续按 init timeout / restart 规则处理，而不是提前转成运行阶段 stall。
+
+- Given 一个 review proof 已进入 running，随后 `HEAD` / `PR.head.sha` / `PR.base.sha` 变化 When 外层收到新鲜度变化事实 Then 不得立刻杀掉当前 proof；只能等它终态后把旧结果判 stale，并在需要时为最新事实补 proof。
+
+- Given session `019cf209-cfbf-7e32-97a9-8b1a050d5cbf` 与 `019cf215-42d3-7883-b991-fa1f824ec42f` When 按新契约回放 Then 这些在已产生业务输出后被上层 `Ctrl-C` 中断的行为应被判定为不合格。
+
+- Given session 中出现 `Missing environment variable: CVM_API_KEY` When 归类故障 Then 必须继续判为启动失败/环境失败，而不是误终止。
+
+- Given 一个 pre-PR direct proof 以 `--sandbox read-only` 形状启动 When runtime banner / 会话输出表明它实际不是 read-only Then 调用方不得把它当作合格的 direct read-only proof 继续推进；若后续仍要允许写入，必须切换到受治理的 writable review-loop 路径，并对最新 `HEAD` 重新绑定事实。
+
+- Given 一个 final merge-proof / merge-path direct proof 以 `--sandbox read-only` 形状启动 When runtime banner / 会话输出表明它实际不是 read-only Then 该 caller 同样不得把它当作合格的 direct read-only merge-proof evidence；必须阻断或切到受治理的 writable 路径，并对最新 PR/HEAD 事实重新绑定。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- Unit tests: N/A
+- Integration tests: 通过文档契约审阅与已知 session 回放样例交叉验证
+- E2E tests (if applicable): N/A
+
+### Quality checks
+
+- `git diff --check`
+- 目标文件中的 `startup_success` / `INIT_STALL_TIMEOUT_SEC=300` / `runtime banner` / `外部门禁等待态` / `等待预算耗尽` / `Ctrl-C` 文案一致性检查
+
+## 方案概述（Approach, high-level）
+
+- 先在共享短规约里明确“谁拥有运行中的 proof”，再让 `codex-review-loop` 把 init 与 running 的边界写实。
+- 把共享等待预算重新限定为 GitHub 可见外部门禁；已经启动成功的本地 proof 不再纳入这类 stop 预算。
+- 下游技能只保留必要的 thin wrapper，统一引用共享主源，减少未来再次漂移的机会。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：如果未来新增新的 PR/merge skill 入口但不复用共享短规约，仍可能在新入口复发。
+- 需要决策的问题：None
+- 假设：只要 proof 已产生业务输出，主人希望它默认跑完，除非超时或显式要求停止。
+
+## 参考（References）
+
+- Session `019cf1f6-91b2-7893-ad95-80830ce62973`
+- Session `019cf1fc-c964-7e31-a392-78d8e4934121`
+- Session `019cf209-cfbf-7e32-97a9-8b1a050d5cbf`
+- Session `019cf215-42d3-7883-b991-fa1f824ec42f`
+- Session `019cf251-17e9-7cb0-81e0-854a426d9725`

package/toolkit/skills/docs/vendor/dot-codex/specs/qyd57-agent-memory-project-docs/HISTORY.md

@@ -0,0 +1,20 @@
+# Agent memory 与项目文档 promotion 分层 演进历史（#qyd57）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `98b5045` docs(workflow): add project-doc promotion gate
+- `4ac9673` docs(workflow): close project-doc review gaps
+- `b3f69a4` docs(workflow): harden project-doc promotion gates
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Legacy Change Log
+
+- No legacy change-log section was recorded for this spec.
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#qyd57`.

package/toolkit/skills/docs/vendor/dot-codex/specs/qyd57-agent-memory-project-docs/IMPLEMENTATION.md

@@ -0,0 +1,66 @@
+# Agent memory 与项目文档 promotion 分层 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 固化 `specs + solutions` 与 human-facing project docs 分层，并新增 project-doc promotion gate / skill / docs-migrate 轨道
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-04-22
+- Legacy last-tracked: 2026-04-22
+- Current lifecycle: active
+- Catalog note: 固化 `specs + solutions` 与 human-facing project docs 分层，并新增 project-doc promotion gate / skill / docs-migrate 轨道
+
+## Delivery Milestones
+
+- [x] M1: 固化 Agent memory / human docs 分层，并补仓库级 docs 入口说明。
+- [x] M2: 在共享 workflow 与 flow skill 中加入 `project_doc_disposition` gate。
+- [x] M3: 新增 `$project-doc-promote`，并扩展 `$docs-migrate MODE=project-docs`。
+- [x] M4: 收紧 PR `References` 规则，并同步 skills/docs 索引。
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `AGENTS.md`
+- `docs/README.md`
+- `docs/specs/README.md`
+- `docs/solutions/README.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/normal-flow/SKILL.md`
+- `skills/fast-flow/SKILL.md`
+- `skills/local-merge-flow/SKILL.md`
+- `skills/pr-create/SKILL.md`
+- `skills/docs-migrate/SKILL.md`
+- `skills/docs-migrate/references/project-docs-mode.md`
+- `skills/project-doc-promote/SKILL.md`
+- `skills/README.md`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `98b5045` docs(workflow): add project-doc promotion gate
+- `4ac9673` docs(workflow): close project-doc review gaps
+- `b3f69a4` docs(workflow): harden project-doc promotion gates
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Remaining Gaps
+
+- None currently tracked.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/qyd57-agent-memory-project-docs/SPEC.md

@@ -0,0 +1,133 @@
+# Agent memory 与项目文档 promotion 分层
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 当前全局文档模型已经收敛出 `docs/specs/**` 与 `docs/solutions/**`，但它们都更偏工程流程与 Agent memory。
+- 若没有额外的 promotion 契约，项目级当前真相会持续埋在碎 spec / solution 中，人类维护者必须沿着任务历史才能理解项目。
+- 先前对 Compound 风格分层的讨论已经明确：仓库内不落 `plans/`，`notes/` 也不作为 canonical knowledge store；真正缺的是“Agent memory -> human-facing project docs”的持续治理能力。
+
+## 目标 / 非目标
+
+### Goals
+
+- 固化文档角色分层：`docs/specs/**` 与 `docs/solutions/**` 继续承担 Agent memory / engineering memory，repo 已建立的人类项目文档 / 入口文档（通常 `docs/**`，也可为根入口文档）承担 human-facing current truth。
+- 在共享工程流程里新增 `project_doc_disposition=none|update|create|defer`，并把它变成 merge-ready 前的显式 gate。
+- 新增 `$project-doc-promote` skill，负责按项目自身文档结构把稳定结论提升到合适的项目文档。
+- 扩展 `$docs-migrate`，使其同时支持历史文档 / 碎 spec / solution 到项目文档的批量 promotion。
+- 统一 PR 正文 `References` 约定：按相关性引用 `Specs`、`Solutions`、`Project Docs`。
+
+### Non-goals
+
+- 不把 `plans/` 恢复成仓库内 artifact。
+- 不把 `notes/` 恢复成 canonical knowledge store。
+- 不给所有项目强制固定同一套 `docs/` 目录骨架。
+
+## 范围（Scope）
+
+### In scope
+
+- `.codex/AGENTS.md` 的全局文档模型、PR 引用与 promotion gate 规则。
+- `skills/project-engineering-workflow/SKILL.md` 及相关 flow skill 的新 gate / 状态字段。
+- `skills/pr-create/SKILL.md` 的 PR `References` 规则。
+- 新 skill `skills/project-doc-promote/`。
+- 扩展 `skills/docs-migrate/` 及其 references。
+- `docs/README.md`、`docs/specs/README.md`、`docs/solutions/README.md` 等人类可读入口说明。
+
+### Out of scope
+
+- 批量重写外部项目仓库的人类文档结构。
+- 为项目文档引入全局固定 taxonomy。
+- 单独新增一个仓库内 `plans/` 文档空间。
+
+## 需求（Requirements）
+
+### MUST
+
+- 全局工程记忆模型继续固定为 `docs/specs/** + docs/solutions/**`，且不恢复 `notes/` / `plans/` 为 canonical。
+- `docs/specs/**` 与 `docs/solutions/**` 必须明确标注为 Agent / 工程流程导向，而不是项目文档替身。
+- 共享工程流程在 merge-ready 前必须完成 `project_doc_disposition=none|update|create|defer` 判定。
+- 若 `project_doc_disposition=update|create`，对应项目文档必须在收口前落盘并形成 `Project文档同步证据=<path@sha>`。
+- 若 `project_doc_disposition=defer`，必须记录 defer 原因、目标文档与后续动作；不能只写“以后再说”。
+- 项目文档的目标路径必须优先服从项目已有 `docs/` 结构；不得强推统一目录骨架。
+- PR 正文在相关时必须显式给出 `Specs`、`Solutions`、`Project Docs` 引用。
+- `$project-doc-promote` 必须只提升稳定项目真相，不得把整段 task log / milestone / review 过程直接复制到项目文档。
+- `$docs-migrate MODE=project-docs` 必须支持“历史迁移 + 批量提升”，且允许多个 spec / solution 汇总到一个项目文档中。
+
+### SHOULD
+
+- 仓库在缺少清晰人类文档入口时，补一个最小 index / overview 文档，便于人类查阅。
+- `skills/README.md` 与 docs 入口文案同步说明新 skill 与新 gate。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- 共享工程流程继续以 `specs + solutions` 作为 Agent memory 输入；但在 Step 4 收口前，必须额外判断是否需要把稳定结论 promotion 到项目文档。
+- `project_doc_disposition=none`：本轮没有需要进入人类项目文档的稳定真相。
+- `project_doc_disposition=update`：已有项目文档需要更新。
+- `project_doc_disposition=create`：现有项目文档没有合适承载面，需要新增人类文档。
+- `project_doc_disposition=defer`：已经确认需要 promotion，但本轮因范围或时机原因暂缓；必须留下可执行 defer 记录。
+- PR body 的 `References` 负责把本轮关联的 `Specs`、`Solutions`、`Project Docs` 串起来；`local-merge` 路径虽不创建 PR，也沿用同一引用模型作为统一口径。
+
+### Edge cases / errors
+
+- 若项目现有 `docs/` 结构无法唯一推导 promotion 目标，优先更新现有总览/索引文档；若仍无法确定，再阻断并只问 1 个关键问题。
+- 若历史 spec / solution 中混有大量一次性任务 prose，`project-docs` 迁移只能抽取稳定结论，不能整文照搬。
+
+## 接口契约（Interfaces & Contracts）
+
+### 接口清单（Inventory）
+
+| 接口（Name） | 类型（Kind） | 范围（Scope） | 变更（Change） | 契约文档（Contract Doc） | 负责人（Owner） | 使用方（Consumers） | 备注（Notes） |
+| - | - | - | - | - | - | - | - |
+| project_doc_disposition | workflow field | internal | New | None | codex-global | shared workflow / flow skills | merge-ready 前必须决议 |
+| project-doc-promote | skill | internal | New | None | codex-global | shared workflow / docs tasks | 日常 promotion |
+| docs-migrate project-docs mode | skill mode | internal | Modify | `skills/docs-migrate/references/project-docs-mode.md` | codex-global | docs taxonomy migration | 历史迁移 + 批量提升 |
+| PR References: Specs / Solutions / Project Docs | PR body contract | internal | Modify | `skills/pr-create/SKILL.md` | codex-global | PR flows | 三类引用统一口径 |
+
+## 验收标准（Acceptance Criteria）
+
+- Given 一个任务只更新 agent memory，When 进入 Step 4 收口，Then 可以显式记录 `project_doc_disposition=none` 并继续。
+- Given 一个任务改变了项目级当前真相，When 进入 Step 4 收口，Then 必须先写入或新建合适的项目文档，或者留下完整 `defer` 记录。
+- Given 仓库已有自定义的 `docs/` 结构，When `$project-doc-promote` 或 `$docs-migrate MODE=project-docs` 选择目标文档，Then 必须优先复用现有结构，而不是强制固定 taxonomy。
+- Given 一个 PR 关联了 spec、solution 与项目文档，When `pr-create` 生成/重写 PR body，Then 相关引用会显式出现在 `References` 中。
+- Given 一个历史 spec / solution 批量收敛到人类项目文档的任务，When 运行 `$docs-migrate MODE=project-docs`，Then 允许多个来源汇总到一个项目文档，但原 spec / solution 仍保留为 Agent memory。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `git diff --check`
+- `rg -n "project_doc_disposition|Project Docs|project-doc-promote|MODE=project-docs" AGENTS.md docs skills`
+- `python3 /Users/ivan/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/project-doc-promote`
+
+### Quality checks
+
+- 项目文档路径与说明不得硬编码全局目录骨架。
+- `specs/solutions` 与 `docs/**` 项目文档的职责表述必须一致。
+
+## Visual Evidence
+
+None
+
+## 方案概述（Approach, high-level）
+
+- 保持 `specs + solutions` 作为工程记忆主轴，不再新增仓库内 `plans` 或恢复 `notes`。
+- 把“需要人类直读的稳定结论”从工程记忆中提升出来，但提升目标路径交给项目自身文档结构决定。
+- 用一个轻量的日常 promotion skill + 一个批量迁移 mode 来分工治理增量与历史积累。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：若项目没有任何既有人类文档结构，promotion 目标仍可能需要一次人工判断。
+- 风险：PR flow 与 local-merge flow 若输出字段不同步，会让后续恢复语义产生偏差。
+- 假设：PR 正文继续允许 `Spec:` / `Specs:` 兼容 legacy 写法，同时新增 `Solutions:` 与 `Project Docs:`。
+
+## 参考（References）
+
+- `docs/specs/global-solutions-docs-migrate/SPEC.md`
+- `AGENTS.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/pr-create/SKILL.md`
+- `skills/docs-migrate/SKILL.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/r4m7k-fast-track-merge-intent-closeout/HISTORY.md

@@ -0,0 +1,95 @@
+# Fast-track merge intent closeout 演进历史（#r4m7k）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `ff72d05` fix(flow): align fast-track merge closeout semantics
+- `b39a914` docs(specs): adopt topic-level spec model
+- Initiative roles refine, rather than weaken, fast-track authority: direct delivery keeps its existing merge semantics; child delivery stops at integration CI and aggregate delivery requires SHA-bound owner approval.
+- current worktree: 根据 owner 反馈，明确“合并”与“合并并收尾”不是同一终点：普通“合并/merge PR”是 `merge-only`，完成 PR merge 并删除远端 PR head；只有“合并并收尾/merge and cleanup”才执行本地 cleanup。cleanup 包含删除 PR 工作区，并负责处理已合并 PR head 本地分支等本地收尾对象。
+- current worktree: 根据 owner 反馈，明确 `merge-only` / `merge+cleanup` 一旦进入 shared Step 5 merge path，就默认允许 same-PR、in-scope writable convergence；`merge-ready` 仍只表示停在 `Step 5C Ready`，不会自动携带这层可写收敛授权。
+- review follow-up: `合并 PR 并收尾` 与 `merge PR and cleanup` 必须优先归类为 `merge+cleanup`，不能被 `合并 PR` / `merge PR` 子串误归类为 `merge-only`。
+- review follow-up: `收工条件=merge+cleanup` / `stop condition=merge+cleanup` 这类流程锚点也必须触发 merge+cleanup 守卫，避免会话停在 `Step 5C Ready` 被误判通过。
+- review follow-up: `本地收尾=完成` 只是 assistant 总结，不是 cleanup 证据；replay checker 只接受 `$pr-post-merge-cleanup`、`cleanup_skill_invoked=yes` 或 `cleanup_proof`。
+- review follow-up: readiness 文案不能压过显式 `merge+cleanup` 锚点；否定句里的 `$pr-post-merge-cleanup` 名称也不能被算作 cleanup proof。
+- review follow-up: `cleanup_proof` 必须有正向值，assistant 侧只有显式 state anchor 能设置 `merge+cleanup` intent，普通选项说明不能设置。
+- review follow-up: `准备好合并 PR` 仍是 `merge-ready`；`不会/不调用 $pr-post-merge-cleanup` 是否定 proof；assistant `merge+cleanup` state anchor 不会被同句 proof-status 文案清除。
+- review follow-up: `$pr-post-merge-cleanup` 的未来承诺不是 cleanup proof；checker 只接受正向结构化 proof 字段。
+- review follow-up: 主工作区基线状态属于 merge scope，不会否定同句正向 `cleanup_proof`。
+- review follow-up: 诊断命令或搜索输出中出现 `gh pr merge` / `cleanup_proof` 不能被当作真实 merge 或 cleanup proof；checker 必须把证据绑定到实际 merge 调用与最终可信收尾状态。
+- review follow-up: `gh --repo owner/repo pr merge` 是真实 merge 证据；只读 `gh api .../merge` 不是，API merge 只有显式 mutating method 才能满足 merge proof。
+- review follow-up: cleanup guard 必须以 merge success 为前提；merge 调用被 GitHub 拒绝时，`merge+cleanup` 不能被误判为已合并但跳过收尾。
+- review follow-up: `gh pr merge --help` 不是 merge 证据；用户后续明确切回 `准备好 PR` 时，最新 `merge-ready` stop condition 覆盖之前的 merge/cleanup 意图。
+- review follow-up: shell-wrapped `gh pr merge` 是常见 exec 形态，checker 必须先解开 `sh/bash/zsh -c` 再判断 merge 证据。
+- review follow-up: shell script 中的 `set -e; cd repo && gh pr merge ...` 也是真实 merge 证据，但只能满足其后的 active intent，不能复用早先 turn 的 merge。
+- review follow-up: 同一 shell command 若先诊断再 merge，checker 必须继续扫描后续 segment，不能停在第一个非 mutating `gh`。
+- review follow-up: replay 里 `shell` tool 的 command-array 形态也要识别；`准备好合并并收尾` 中 cleanup intent 优先于 ready 子串。
+- review follow-up: `cleanup_proof=稍后生成` 仍是 pending 占位；活 proof 未终态时，即使 final closeout 写“PR 已合并”也必须失败。
+- review follow-up: `/opt/homebrew/bin/gh pr merge ...` 这类 path-qualified gh 调用按 basename 识别为真实 merge 证据。
+- review follow-up: final closeout 中的英文 `Merged pull request` 也算 merge success，不能绕过 cleanup-skipped guard。
+- owner correction: 远端 PR head 删除属于 merge scope，不属于“合并并收尾”的本地 cleanup；普通合并也必须验证 `远端分支=不存在`。
+- owner correction: 普通合并还必须对齐 Git primary worktree 的 PR target base branch，或明确报告 `主工作区基线更新=阻断/待主人决策`；本地 PR topic branch 与 PR worktree 删除仍只属于 cleanup。
+- owner correction: `对齐` 定义为 local base 包含最新 remote base，而不是必须等于 remote；dirty/ahead/diverged primary base 应进入 `待主人决策` 菜单，安全对齐必须在 stash/rebase 后把 dirty/untracked 恢复回工作区。
+- review follow-up: fork / protected head 的明确 `远端分支=不适用/阻断` 是合法 merge 结果；`gh api .../git/refs/heads/<branch> -X DELETE` 的 endpoint-before-method 写法也必须识别。
+- review follow-up: 成功 `[deleted] <branch>` 输出优先于分支名里的失败词；`不是 fork PR head` 不是远端删除豁免。
+- review follow-up: `git push origin --delete <branch>` / `git push origin -d <branch>` 是常见远端 head 删除形态，必须用 token 解析识别。
+- review follow-up: `gh api ... -X DELETE` 的 `gh:` / HTTP 4xx/5xx 输出是删除失败，不得当成远端 head 已删除。
+- review follow-up: `远端分支=不存在` 必须有工具证据支撑；assistant 自报状态不满足远端 head 删除门禁。
+- review follow-up: 工具确认 `remote branch: not found` 是远端 head 已不存在的成功证据，不受通用失败词 veto。
+- review follow-up: 删除样式输出必须绑定到已识别的删除或验证命令；无关诊断输出不能满足远端 head 删除门禁。
+- review follow-up: `gh pr merge --delete-branch` 的删除失败输出不能算远端 head 删除；已知 `headRefName` 时必须匹配被删除 ref。
+- review follow-up: PR head 取自自然语言句子时会去掉句尾标点，再与实际删除输出匹配。
+- review follow-up: 组合命令里的远端删除先按 shell segment 解析，避免后续验证命令参数污染被删除分支名。
+- review follow-up: 分支特定删除 proof 必须绑定 PR head 证据，并递归解析 shell wrapper 内的组合删除。
+- review follow-up: `git push --delete` 分支解析会截断重定向与管道后缀，避免把日志捕获参数当成 ref。
+- review follow-up: `git push origin :refs/heads/<branch>` 删除 refspec 会归一为短分支名后再匹配 PR head。
+- review follow-up: 多行 shell script 按换行分段，PR head 捕获支持 `+` 等合法 ref 字符。
+- owner follow-up: merge-scope base alignment新增专用 helper，先固定解析 Git primary worktree，再只自动执行安全的 tracking-ref / ff-only 更新；dirty、ahead、diverged 等主工作区 base 状态继续保留给主人决策。
+- owner follow-up: 在主人明确选择 `安全对齐` 后，base-alignment helper 现在也接管备份分支、`stash -u`、`rebase`、`stash apply` 与冲突恢复态输出，不再依赖临时 shell 拼接。
+- compression pass: skill 文案压缩为引用共享 stop-condition contract，减少重复展开但不改变行为。
+- owner correction: 本地 Step 4 收口和 live PR `merge-ready` 必须拆词；没有 open PR 时只能称为 `可开 PR（local）`，不得宣告 `Step 5C Ready` 或 `latest PR 可立即合并`。
+- owner correction: merge / cleanup 不是所有 run 的最终语义；若 release / deploy / publish / post-merge workflow 仍未终态，shared flow 必须继续进入 `Step 6 post-merge finality follow-up`，优先 app automation，CLI 再回退 repo-native watcher，并统一使用 `gpt-5.6-luna + xhigh`。
+- review follow-up: `merge+cleanup` 只有在拿到正向 `cleanup_proof` 后，`Step 6` 未决时才能恢复到 `$pr-merge`；`blocked|pending|unchecked` 等非正向值仍必须继续 `$git-cleanup`。
+- review follow-up: `flow_continue_replay_check.py` 与 `r4m7k` replay fixtures 现在同时覆盖“cleanup 已完成再回 Step 6”和“cleanup proof 非正向时不得跳过 cleanup”两条恢复路径。
+- owner follow-up: 根据成本约束，Step 6 改为只追踪 merge SHA 在目标分支触发的 CI；PR head 与 merge SHA 各使用一个 `gpt-5.6-luna + low` sub-agent，主 agent 通过阻塞式 `wait_agent` 等待，计划任务不再作为主动路径；共享不变量集中在 CI tracking short contract，入口 skill 只保留 phase/identity 与编排职责。
+- owner correction: target-branch CI 不是完整 post-merge 终态。`Release Snapshot` 只证明发布意图；当仓库合同与 merge-SHA live facts 表明预期发版时，流程必须继续等待实际 Release/package/container 终态，并在最终回复明确报告版本等核心发布信息。发布跟踪使用独立 short contract，30 分钟未终态仍视为流程未完成，失败仅在可证明幂等时重跑一次。
+- review follow-up: release replay 现在拦截完全漏报、expectation/status 矛盾、实际 tag/SHA 错绑与 timeout 缺恢复锚点，并接受仓库合同声明的 package/container-only 发布证据。
+- review follow-up: release evidence 进一步绑定当前 expectation/repository epoch，区分 draft creation 与 actual publication，要求实际 artifact SHA，并对未发版证据与幂等单次 rerun 进行可回放校验。
+- review follow-up: harden tracker replay evidence so real `wait_agent` tool calls, concrete SHA bindings, and historical automation compatibility are distinguished correctly
+- review follow-up: bind tracker launch, wait, and SHA evidence to one instance, include automatic topic-branch push checks, and ignore unrelated automation pause/archive calls
+- review follow-up: bind replay evidence to the launched agent identity and bound SHA, and make `defer` terminal through its explicit infra-blocked record rather than a nonexistent tracker
+- review follow-up: support real collaboration spawn output and implicit wait schemas, retain matched barrier evidence across later waits, and enforce phase identity in replay cards
+- review follow-up: require a tracker status card, prefer concrete spawned-agent identities, and scope legacy scheduled evidence to the active follow-up mode
+- review follow-up: accept PR-head result cards, validate completed wait outputs, and use checked SHA when collaboration arguments hide the encrypted tracker prompt
+
+## Legacy Change Log
+
+- review follow-up: require terminal result/disposition fields for post-merge cards and retain pre-status scheduled-launch candidates for legacy-route detection
+- review follow-up: limit phase inference to structured tracker inputs, enforce post-merge-only fields, and ignore negated automation prose
+- review follow-up: bind retry authorization to an observed failure for the tracked run and prevent batched or cross-epoch facts from contaminating release state
+- review follow-up: reject stale publication facts with a conflicting release epoch and recognize GitHub Enterprise release paths
+- review follow-up: normalize string-encoded and text-wrapped tool output before applying the release discovery contract
+- review follow-up: merge split discovery blocks and require complete publication coverage for all declared release identities
+- review follow-up: reject conflicting artifact identity, accumulate immutable same-epoch run IDs, and preserve split-block scalar conflicts
+- review follow-up: reject cross-repository release reruns without treating equivalent short/full SHA or tag forms as conflicts
+- review follow-up: bind pre-discovery target-CI rerun authorization to the repository as well as the run ID
+- review follow-up: distinguish PR-head CI reruns and support non-GHCR packages plus version-tagged container aliases
+- review follow-up: bind release decisions to the target branch and support immediate incomplete recovery when no tracker is available
+- review follow-up: count compound release reruns per command segment and accept standard MCP structured-content wrappers
+- review follow-up: same-epoch heartbeat cards cannot rebind repository/branch/SHA/tag, and unresolved `gh run rerun` targets are rejected as unsafe
+- review follow-up: snapshots and candidate package metadata cannot prove publication, reruns require a fresh terminal fact, and failure closeout names its surface and disposition
+- review follow-up: release applicability follows trusted release context and remote-merge identity rather than a generic merge phrase, preserving valid local-closeout semantics
+- review follow-up: failed `gh pr merge` attempts never establish remote release context; only matching success output does
+- review follow-up: expected/unresolved non-success closeout retains explicit owner fields, while `success=false` is distinct from `published=false` for retry evidence
+- review follow-up: structured remote merge success cannot use release-not-applicable, and target repository identity may come from a bound Actions workflow URL
+- review follow-up: direct `release_expected`/`release_enabled` conflicts are rejected, and unrelated Actions URLs do not initialize release-run identity
+- review follow-up: normalize all remote merge success result spellings into the release gate, and require complete terminal reporting fields for both published and untriggered release outcomes
+
+- No legacy change-log section was recorded for this spec.
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#r4m7k`.