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

package/toolkit/skills/docs/vendor/dot-codex/specs/hd86w-pr-wait-state-closeout/SPEC.md

@@ -0,0 +1,110 @@
+# PR wait-state closeout
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 在已授权 PR convergence 的 run 里，agent 仍可能把“当前只剩外部门禁在运行”误判成一个可汇报停靠点，先输出结论和 `流程锚点`，再结束当前 turn。
+- session `019ce60d-8cc3-7623-a02a-e54290c9e52c` 已给出明确回放样例：agent 在最新 `head_sha=49ba093bef373079617fcf4a9404e1898adc4e1d` 的 fresh merge-proof 仍未拿到终态、PR `mergeable_state` 仍为 `unstable` 时，先给出“下一门禁=latest head 的 fresh merge-proof 完成”并停止；对应 JSONL 证据位于 `sessions/2026/03/13/rollout-2026-03-13T15-16-13-019ce60d-8cc3-7623-a02a-e54290c9e52c.jsonl` 约第 `3295` 行。
+- 该问题的本质不是“agent 不知道下一步做什么”，而是“当前 running gate 的完成”被错误包装成 `流程锚点.下一门禁`，导致纯等待态提前收尾。
+
+## 目标 / 非目标
+
+### Goals
+
+- 明确“当前 running checks/workflows/fresh merge-proof/mergeable 重算的完成”不是新的 `下一门禁`。
+- 明确在已授权 PR convergence 的 flow 里，纯 `外部门禁等待态` 不是合法停靠点；除非共享等待预算耗尽，否则必须留在当前 turn 继续轮询。
+- 让共享 workflow、`$flow-continue`、`$fast-flow`、`$pr-create`、`$pr-merge` 与 prompt 顶部都能在 partial read 场景下先看到同样的 stop prohibition。
+- 规定当确实因等待预算耗尽而停下时，`流程锚点.下一门禁` 必须表示“重入共享等待态继续轮询”，而不是把当前 running gate 的完成伪装成下一动作。
+
+### Non-goals
+
+- 不修改 Codex 引擎级 `task_complete` 机制。
+- 不改写 `$codex-review-loop` 的 profile 体系或执行模型。
+- 不引入新的自动化测试框架或新的 GitHub 状态模型。
+
+## 范围（Scope）
+
+### In scope
+
+- 更新 `docs/specs/README.md` 与本规格文档。
+- 更新 `$project-engineering-workflow` 的共享 PR 等待态契约与锚点语义。
+- 更新 `$flow-continue` 的恢复归一化规则。
+- 更新 `$fast-flow`、`$pr-create`、`$pr-merge` 的提前停机约束。
+- 更新 `/prompts:advance-flow` 与 `/prompts:pr-merge` 的顶部 stop prohibition。
+
+### Out of scope
+
+- 变更任何 `gh CLI` 远端操作契约。
+- 修改非仓库内的 agent runtime。
+- 对现有 flow 增加新的状态字段。
+
+## 需求（Requirements）
+
+### MUST
+
+- 纯 `外部门禁等待态` 只能有两种合法行为：在同一 turn 内继续轮询，或在共享等待预算耗尽后以明确的“等待预算耗尽”收尾。
+- `流程锚点.下一门禁` 不得写成“最新 head 的 fresh merge-proof 完成”“checks 全绿”“mergeable_state 变 clear”这类当前 running gate 的完成条件。
+- 若本轮因共享等待预算耗尽而停下，`流程锚点.下一门禁` 必须表示“重入共享等待态继续轮询”或等价表述，而不是虚构一个尚未开始的新 gate。
+- `$flow-continue` 在恢复时，若发现锚点里的 `下一门禁` 其实只是当前 running gate 的完成条件，必须把它归一化回共享 `外部门禁等待态`，而不是把该文本当作真实下一动作。
+- `partial read` 场景下最先可见的规则也必须足以阻止“先汇报再等待”的误停。
+
+### SHOULD
+
+- 用 session `019ce60d-8cc3-7623-a02a-e54290c9e52c` 作为回放样例，确保新契约能把该类输出判为不合格收尾。
+- 共享 workflow、具体 skill 与 prompt 的措辞保持一致，避免不同入口给出不同恢复语义。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- 当 PR merge/create path 只剩运行中的 checks/workflows、mergeable 重算、branch update 可见状态，或当前 `head_sha` 的 fresh proof 仍在运行时：
+  - 若当前 flow 已授权 PR convergence，则必须继续轮询共享等待预算。
+  - 若预算内任一门禁变成 clear 或 actionable blocker，必须在同一 turn 内继续后续门禁。
+  - 若预算耗尽，允许停下，但结论必须显式写出“等待预算耗尽”，并把恢复锚点指回共享等待态本身。
+- 当恢复层读到旧锚点中的“下一门禁=checks 全绿 / fresh merge-proof 完成”时，若当前事实显示这些门禁只是 still running，就要把它解释成“继续轮询共享等待态”，而不是“已知下一步所以可以停”。
+
+### Edge cases / errors
+
+- 若 fresh proof 尚未启动且启动它需要新的授权，这不是纯等待态；仍按授权阻断处理。
+- 若轮询期间 `PR.head.sha`、`PR.base.sha`、`mergeable_state` 事实变化，等待态立即失效，必须返回 freshness/mergeability gate，旧 proof 与旧 checks verdict 失效。
+
+## 验收标准（Acceptance Criteria）
+
+- Given agent 已授权 PR convergence，且唯一缺口是运行中的 checks/workflows/fresh merge-proof When agent 评估当前 stop condition Then 它不得把这类状态当作可直接收尾的“已知下一门禁”。
+
+- Given 当前 run 只因共享等待预算耗尽而停下 When agent 输出结论与 `流程锚点` Then 结论必须显式写出“等待预算耗尽”，且 `下一门禁` 只能指向“继续轮询当前外部门禁等待态”或等价共享等待处理。
+
+- Given `流程锚点.下一门禁` 文字只是当前 running gate 的完成条件 When `$flow-continue` 恢复流程 Then 必须把恢复点归一化回共享等待态，而不是把该文字当作新的可停靠 gate。
+
+- Given session `019ce60d-8cc3-7623-a02a-e54290c9e52c` 中约第 `3295` 行的输出 When 按新契约回放 Then 该输出应被判定为不合格收尾；合法行为只能是继续轮询，或在预算耗尽后明确标注“等待预算耗尽”。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- Unit tests: N/A
+- Integration tests: 通过静态契约审阅、session 回放与文本一致性检查验证
+- E2E tests (if applicable): N/A
+
+### Quality checks
+
+- `git diff --check`
+- 目标文件中的 `等待预算耗尽 / 外部门禁等待态 / 下一门禁` 文案交叉检查
+
+## 方案概述（Approach, high-level）
+
+- 把“纯等待态不能提前停机”前移到共享 workflow、具体 PR skill 和 prompt 的顶部可见区域。
+- 把“当前 running gate completion”与“下一门禁”语义拆开：前者属于继续轮询当前等待态，后者只用于真正尚未开始的下一个硬门禁。
+- 在恢复层增加归一化规则，避免旧锚点把 wait state 再次误恢复成可停靠点。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：如果后续再新增 PR skill/prompt 入口但没有同步复制 stop prohibition，仍可能在新入口复发。
+- 需要决策的问题：None
+- 假设：已授权 PR convergence 的 flow 允许在共享等待预算内保持同一 turn 继续轮询。
+
+## 参考（References）
+
+- Session `019ce60d-8cc3-7623-a02a-e54290c9e52c`
+- `sessions/2026/03/13/rollout-2026-03-13T15-16-13-019ce60d-8cc3-7623-a02a-e54290c9e52c.jsonl`

package/toolkit/skills/docs/vendor/dot-codex/specs/initiative-flow/HISTORY.md

@@ -0,0 +1,11 @@
+# Initiative Flow Context
+
+The durable boundaries behind this topic are:
+
+- Bootstrap and Delivery are distinct approvals: the former establishes one immutable execution contract; the latter only consumes published topology.
+- The initial integration frontier is activated by a single named branch-push check. Its identity is bound to the approved base or committed Bootstrap SHA according to Spec disposition.
+- Ticket topology, native task registration, and delivery cannot proceed until that activation is ready and the integration branch still names its SHA.
+- The local ledger proves transaction order but never replaces GitHub or Codex as the source of user-facing state.
+- Drift is handled by cancellation and a fresh Bootstrap, preserving approved branch history and requiring explicit owner direction for any rewrite.
+
+These constraints keep the lifecycle deterministic while leaving repository specific implementation, validation, and release evidence to the applicable delivery workflow.

package/toolkit/skills/docs/vendor/dot-codex/specs/initiative-flow/IMPLEMENTATION.md

@@ -0,0 +1,16 @@
+# Initiative Flow Implementation
+
+The implementation has four cooperating surfaces:
+
+They implement only `schema_version=5` and `initiative_contract_version=5`.
+
+- `initiative_plan_contract.py` normalizes the V5 Bootstrap and Delivery JSON contracts and derives topology, task, wave, and digest identities.
+- `plan_contract_check.sh` validates the matching human Markdown plan before it becomes runtime input.
+- `initiative_flow_guard.py` persists the untracked transactional ledger and enforces the Bootstrap, delivery, CI, and closeout state machine.
+- `initiative_flow_replay_check.py` validates compact replay evidence for the V5 activation and child-integration protocol.
+
+The guard begins at `init`. `reuse` verifies passed base-SHA activation evidence; other dispositions create a provisional ledger until the committed Bootstrap SHA receives passed `spec-bootstrap-ci` evidence. The guard exposes the next action through `status` and performs every external transition with a single-use authorization permit.
+
+Every ledger has an `activation` field. A changed-Spec provisional ledger keeps it `null` until Bootstrap Integration CI passes; all ready or externally visible states require the complete record. The named `branch-push` check's SHA is the initial integration frontier and the guard independently resolves the current remote integration branch before Bootstrap CI, Tracking Issue, or topology transitions. Delivery normalizes against that fixed Bootstrap contract and the published topology before any native Ticket task can register.
+
+Promotion, release, observation, Ticket close, receipt sealing, and retention use the same guard identity model. The script and its adjacent tests are the authoritative source for action inputs and receipts; skill prose does not copy their JSON schemas.

package/toolkit/skills/docs/vendor/dot-codex/specs/initiative-flow/SPEC.md

@@ -0,0 +1,72 @@
+# Initiative Flow
+
+Initiative Flow is the multi-Ticket lifecycle for work that needs a shared integration branch, ordered Waves, native task Worktrees, and one final promotion. It is not a substitute for direct delivery or for `$to-tickets`.
+
+## Related ADRs
+
+- [ADR 与 Topic Spec 的职责分离](../../adr/0001-compose-adrs-with-topic-specs.md)
+- [Initiative Child Integration Uses Branch-Push CI](../../adr/0009-initiative-child-integration-ci-boundary.md)
+- [Parallel Direct PR Flow](../../adr/0011-parallel-direct-pr-flow.md)
+- [PR Lifecycle Workflow Ownership](../../adr/0016-pr-lifecycle-workflow-ownership.md)
+- [V5 Bootstrap Integration CI Activation](../../adr/0018-v5-bootstrap-integration-ci-activation.md)
+
+## Scope
+
+Use `initiative` only when at least two Tickets are independently acceptable and independently mergeable, and their delivery requires a shared integration mechanism. Purely independent direct PRs use `parallel-pr`; tightly coupled work uses direct delivery.
+
+Bootstrap establishes the Initiative identity and one immutable execution contract. `$to-tickets` owns Ticket decomposition, owner approval, and Issue bodies. Delivery binds that published topology one-to-one to native task containers. Ticket-local agents use `$implement` and do not re-plan or alter the topology.
+
+## V5 Contract
+
+The only accepted contract has `schema_version=5` and `initiative_contract_version=5`. Bootstrap and Delivery freeze:
+
+- the repository, topic, `prd/<topic>` integration branch, final base, and exact `development_base`;
+- `spec_disposition=reuse|refresh|create|supersede`, canonical Spec path, and path-sorted ADR path/blob bindings;
+- `integration_ci_surface={kind: branch-push, check: <exact-name>}` and `promotion_policy=final-only|checkpointed`;
+- the published topology digest, source SHA, one Delivery task per Ticket, and each Ticket's completion gate.
+
+Bootstrap contains no Ticket tasks. Delivery cannot add, replace, or rename a Ticket. Same-Wave Ticket write scopes cannot overlap; Ticket scopes never own `docs/adr/**`.
+
+## Bootstrap Activation
+
+The first passed named branch-push check activates the Initiative:
+
+- `reuse` supplies passed evidence for `development_base` at `init`.
+- `refresh`, `create`, and `supersede` supply JSON `null` at `init`, commit the approved Bootstrap, then record passed evidence for its `bootstrap_sha`.
+
+Activation evidence always binds the exact SHA, current branch head, `prd/<topic>`, check name, `push` event, and run ID. No CI provisioning mode, workflow digest, or alternate activation plan field exists.
+
+Before `spec.status=ready`, the guard permits only Bootstrap work and a same-SHA failed-CI rerun marked `rerun=true`. Tracking Issue creation, topology publication, Delivery binding, and task creation require ready state. Tracking Issue and topology actions recheck that the branch head equals the activated SHA. Child integration CI rechecks the merged SHA against the live branch head; final promotion rechecks that head and requires current PR checks, validation, and review proofs at the same SHA.
+
+## Lifecycle
+
+```text
+init -> Spec resolve or bootstrap -> activation -> Tracking Issue
+-> approved topology -> Delivery bind -> native tasks -> child integration
+-> completion gates -> final promotion -> Tracking Issue close
+```
+
+Each external side effect is a guard transaction: `authorize -> tool call -> commit`. The common-dir ledger is an untracked execution receipt, not a product source of truth. GitHub Issues/PRs and Codex task state remain authoritative for their respective facts.
+
+A missing or activation-less ready ledger is rejected. A readable damaged provisional ledger without external topology may only be cancelled; Bootstrap content change or branch drift then requires a fresh Bootstrap. The flow does not adopt drift, reset history, or rewrite branches.
+
+## Ticket Completion And Promotion
+
+Child integration CI is bound to the exact merged integration SHA, named branch-push check, source ref, push event, and run ID. Failed integration blocks dependent work until matching repaired evidence exists. A later Ticket binds the current passed integration frontier.
+
+`integration` Ticket completion closes after matching integration CI. `published` and `observed` completion additionally require their matching promotion evidence. Final PR validation remains a separate proof and cannot substitute for Bootstrap activation or child integration.
+
+The guard records validation, review proof, owner decisions, promotion, release/observation evidence, receipt sealing, retention, and final Tracking Issue close with their current SHA identities.
+
+## Verification
+
+- Contract normalizer and Markdown checker accept only the V5 shape.
+- Guard tests cover both activation paths, failed same-SHA rerun, ready-state gating, branch-head drift, cancellation, and ledger rejection.
+- Replay fixtures cover V5 Bootstrap and child CI identity failures.
+- Static checks keep skill routing and the V5 documentation contract aligned.
+
+## References
+
+- `skills/initiative-flow/SKILL.md`
+- `skills/initiative-flow/references/ticket-envelope.md`
+- `skills/initiative-flow/scripts/initiative_flow_guard.py`

package/toolkit/skills/docs/vendor/dot-codex/specs/j4ha2-pr-conflict-auto-heal/HISTORY.md

@@ -0,0 +1,18 @@
+# PR conflict auto heal 演进历史（#j4ha2）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `b282add` fix: auto-heal PR conflict diagnostics
+- `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: `#j4ha2`.

package/toolkit/skills/docs/vendor/dot-codex/specs/j4ha2-pr-conflict-auto-heal/IMPLEMENTATION.md

@@ -0,0 +1,60 @@
+# PR conflict auto heal 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 将“Actions 缺席其实是 PR 冲突”收口到 freshness gate，并自动解冲续推
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-15
+- Legacy last-tracked: 2026-03-15
+- Current lifecycle: active
+- Catalog note: 将“Actions 缺席其实是 PR 冲突”收口到 freshness gate，并自动解冲续推
+
+## Delivery Milestones
+
+- [x] M1: 建立 `docs/specs/pr-conflict-auto-heal/SPEC.md` 规格并登记索引
+- [x] M2: 在 shared Step 5 中前置 conflict-aware absence diagnosis
+- [x] M3: 收紧 `$pr-create` / `$pr-merge` / `$flow-continue` 的 auto-heal 路径
+- [x] M4: 扩展 replay checker 与 fixtures
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `docs/specs/pr-conflict-auto-heal/SPEC.md`
+- `skills/project-engineering-workflow/references/pr-diagnosis-short-contract.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/pr-create/SKILL.md`
+- `skills/pr-merge/SKILL.md`
+- `skills/flow-continue/SKILL.md`
+- `bin/pr_skill_replay_check.py`
+- `docs/specs/pr-conflict-auto-heal/replay/*`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `b282add` fix: auto-heal PR conflict diagnostics
+- `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/j4ha2-pr-conflict-auto-heal/SPEC.md

@@ -0,0 +1,123 @@
+# PR conflict auto heal
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 当前 PR 流在 `mergeable_state=dirty` / `mergeable=false` 时，虽然共享 freshness gate 已把它定义成 conflict，但后续 checks/workflow 缺席诊断仍可能把这类 PR 当成“没有 Actions 证据”的普通等待或人工决策。
+- GitHub 官方文档明确说明：`pull_request` 事件的 workflow 在 PR 存在 merge conflict 时不会运行；相对地，`pull_request_target` 即使 PR 有冲突也会运行，但默认应谨慎使用，因为安全边界不同。
+- 现状的结果是：真正的 merge conflict 既可能被隐藏成“workflow 没出来”，也可能被升级成“请主人决定要不要处理冲突”，与 PR 自动收敛目标相违背。
+
+## 目标 / 非目标
+
+### Goals
+
+- 把“Actions/checks 缺席其实是 PR 冲突”前移成 shared Step 5 的明确诊断分支。
+- 在已进入 PR convergence / merge 授权边界的 run 中，遇到真实 conflict 时自动解冲、重跑验证、推回 PR，并继续后续收敛。
+- 保持现有 `CI-Operator` 结果枚举不变，把冲突继续表达为 freshness / mergeability gate，而不是新增第五种 CI 状态。
+- 明确冲突修复属于当前 open PR 在 freeze 下允许留存的修复白名单，而不是 scope expansion。
+
+### Non-goals
+
+- 不把仓库 workflow 统一改成 `pull_request_target`。
+- 不改 `gh CLI` 远端操作契约，也不新增新的远端自动化通道。
+- 不重写现有 review-loop 预算、wait budget 或 `blocked` 的普通语义。
+
+## 范围（Scope）
+
+### In scope
+
+- 新增本规格并更新 `docs/specs/README.md`。
+- 更新 shared PR diagnosis contract 与 `$project-engineering-workflow` 的 Step 5 文案。
+- 更新 `$pr-create`、`$pr-merge`、`$flow-continue` 的冲突分流与 auto-heal 路径。
+- 扩展 `bin/pr_skill_replay_check.py` 与新增 replay fixtures / cases。
+
+### Out of scope
+
+- 修改业务实现仓库代码。
+- 重构整个 `CI-Operator` 协议。
+- 为所有历史 session 补录真实回放。
+
+## 需求（Requirements）
+
+### MUST
+
+- 当 open PR 的最新 `head_sha` 长时间没有任何 check runs / workflow evidence 时，必须先刷新 live PR 事实，再决定是 `checks_expected=no`、dispatch/rerun，还是 freshness/conflict gate。
+- 若刷新后的 PR 命中 `mergeable_state=dirty` 或 `mergeable=false`：
+  - 在已授权 PR remote mutation / convergence / merge 的 flow 中，必须自动进入 conflict-resolution path；
+  - 不得因为“发现了冲突”本身停下要求主人继续决定。
+- 冲突修复必须遵循当前 run 已锁定的同步模式：
+  - 显式 `MODE=rebase` / linear-history-only：走本地 rebase + force-push 路径；
+  - 其他默认路径：走 merge-based sync / conflict resolution。
+- 由当前 `mergeable_state=dirty` / `mergeable=false`、`PR.base.sha` 前进或 main-sync 直接逼出的修复，必须视为当前 PR 的 allowed same-PR fix，不得误判成 scope expansion。
+- `CI-Operator` 结果枚举继续保持 `CI_GREEN | CI_NOT_EXPECTED | NEED_CODE_FIX | INFRA_BLOCKED`。
+
+### SHOULD
+
+- 对 `pull_request` 触发的仓库，规则应明确写出“冲突 PR 可能根本不会产生 workflow run”，避免后续再次把 absence 当成 `CI_NOT_EXPECTED`。
+- 对 `pull_request_target`、manual-only、label-gated 的仓库，仍应按真实 trigger facts 判断，不把所有 absence 都误判成 conflict。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- Shared Step 5 中，workflow/check absence diagnosis 必须先执行一次 live PR refresh：
+  - 若 PR 仍 `mergeable_state=behind`：回 freshness/behind gate；
+  - 若 PR 变成 `mergeable_state=dirty` 或 `mergeable=false`：回 freshness/conflict gate；
+  - 只有 freshness 仍 clear 时，才允许继续判定 `checks_expected=no` 或 dispatch/rerun。
+- Conflict-resolution gate：
+  - 复用当前 PR 的 live `BASE_REF` / `BASE_REMOTE` / `BASE_REPO` 与当前锁定的 `MODE`；
+  - 自动在可写 checkout 中完成 merge/rebase 型冲突处理；
+  - 完成后重跑必要本地验证 / spec-sync；
+  - 推回当前 PR head；
+  - 以最新 `PR.head.sha` / `PR.base.sha` 重新建立 freshness、CI、review proof 与 spec verdict。
+- `post-open scope freeze`：
+  - 冲突修复属于 allowed same-PR fix；
+  - 仅当混入新的验收/UI/Story/polish 需求时，才继续按 scope expansion 阻断。
+
+### Edge cases / errors
+
+- 若缺失 workflow evidence 的真正原因是 manual-only / label-gated / `pull_request_target`，且 live PR facts 未显示 `dirty/false`，则仍按既有 checks-expected 诊断继续。
+- 若自动解冲过程中缺少权限、`BASE_REF` / `BASE_REMOTE` / `BASE_REPO` 不能唯一解析、或代理无法给出一致的冲突解决结果，允许上抛真实 blocker。
+- 每次 conflict-repair push、rebase、merge commit 或 `PR.base.sha` 变化，都会使旧 CI/review/spec verdict 失效。
+
+## 验收标准（Acceptance Criteria）
+
+- Given open PR 的最新 `head_sha` 在 `pull_request` 路径上没有任何 Actions/check evidence When live PR refresh 发现 `mergeable_state=dirty` Then 流程必须进入 conflict-resolution path，而不是继续 absence wait、`CI_NOT_EXPECTED` 或 dispatch-only 路径。
+
+- Given 当前 run 已授权 PR convergence / merge When PR 因 `mergeable_state=dirty` 或 `mergeable=false` 命中冲突 Then 代理必须自动完成解冲收敛所需的写入路径，而不是停下要求主人决定是否继续。
+
+- Given 当前 open PR 在 freeze 状态下发生真实冲突 When 代理准备提交 conflict repair Then 这批修复必须被判为 allowed same-PR fix，而不是 scope expansion。
+
+- Given 仓库是 manual-only / label-gated，或 `pull_request_target` 仍能在冲突 PR 上运行 When checks/workflow 缺席但 live PR 未显示 `dirty/false` Then 流程不得误报 conflict auto-heal。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `python3 -m py_compile bin/pr_skill_replay_check.py`
+- `python3 bin/pr_skill_replay_check.py --cases docs/specs/pr-skill-diagnosis-thinning/replay/cases.txt`
+- `python3 bin/pr_skill_replay_check.py --cases docs/specs/pr-conflict-auto-heal/replay/cases.txt`
+- `git diff --check`
+
+### Quality checks
+
+- 受影响 skill 的前 150 行人工 spot-check，确认冲突 auto-heal 口径前置可见。
+- grep 交叉检查：`mergeable_state=dirty`、`mergeable=false`、`workflow evidence`、`scope freeze` 的新口径一致。
+
+## 方案概述（Approach, high-level）
+
+- 保持 `CI-Operator` 结果协议稳定，把冲突继续作为 freshness/mergeability gate 处理。
+- 在 absence diagnosis 前强制回读 PR 真相；只有 freshness 仍 clear 才允许继续做 no-checks 诊断。
+- 把冲突修复明确纳入 shared whitelist，避免自动解冲被 freeze gate 二次拦住。
+
+## 风险 / 假设
+
+- 风险：若某些仓库的 workflow policy 依赖额外外部状态而本地规则未覆盖，absence diagnosis 仍可能需要仓库级补充线索。
+- 风险：自动解冲只在代理能给出一致解决结果时安全；复杂冲突仍可能上抛真实 blocker。
+- 假设：GitHub 官方 `pull_request` / `pull_request_target` 触发语义可作为本仓库 PR diagnostics 的稳定事实来源。
+
+## 参考（References）
+
+- GitHub Docs, “Events that trigger workflows”: `pull_request` workflows do not run when the pull request has a merge conflict. https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows
+- GitHub Docs, “Troubleshooting required status checks”: `pull_request_target` workflows run even if the pull request has a merge conflict. https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/troubleshooting-required-status-checks

package/toolkit/skills/docs/vendor/dot-codex/specs/j4ha2-pr-conflict-auto-heal/replay/cases.txt

@@ -0,0 +1,6 @@
+fail negative-conflict-hidden-as-ci-absence.jsonl CONFLICT_HIDDEN_AS_CI_ABSENCE
+fail negative-conflict-escalated-to-owner.jsonl CONFLICT_ESCALATED_TO_OWNER
+pass positive-conflict-auto-heal-routed.jsonl -
+pass positive-merge-only-conflict-auto-heal.jsonl -
+pass positive-manual-only-no-checks.jsonl -
+pass positive-pull-request-target-conflict-runs.jsonl -

package/toolkit/skills/docs/vendor/dot-codex/specs/j4ha2-pr-conflict-auto-heal/replay/negative-conflict-escalated-to-owner.jsonl

@@ -0,0 +1,2 @@
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_pr","output":"[{\"type\":\"text\",\"text\":\"{\\\"number\\\":143,\\\"mergeable_state\\\":\\\"dirty\\\"}\"}]"}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"PR 当前是 merge conflict，请主人选择我接下来怎么做。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/j4ha2-pr-conflict-auto-heal/replay/negative-conflict-hidden-as-ci-absence.jsonl

@@ -0,0 +1,2 @@
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_pr","output":"[{\"type\":\"text\",\"text\":\"{\\\"number\\\":142,\\\"mergeable_state\\\":\\\"dirty\\\"}\"}]"}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"最新 head 还没有 workflow evidence，先按 checks 缺席处理，做一次 dispatch / rerun 再看。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/j4ha2-pr-conflict-auto-heal/replay/positive-conflict-auto-heal-routed.jsonl

@@ -0,0 +1,2 @@
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_pr","output":"[{\"type\":\"text\",\"text\":\"{\\\"number\\\":144,\\\"mergeable_state\\\":\\\"dirty\\\"}\"}]"}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"PR 当前是 merge conflict，直接进入自动解冲并续推，不走 workflow absence 诊断。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/j4ha2-pr-conflict-auto-heal/replay/positive-manual-only-no-checks.jsonl

@@ -0,0 +1 @@
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"这个仓库当前是 manual-only，没有自动 workflow evidence 仍属正常，继续按普通 PR 门禁处理。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/j4ha2-pr-conflict-auto-heal/replay/positive-merge-only-conflict-auto-heal.jsonl

@@ -0,0 +1,3 @@
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"当前 stop condition 是 merge-only。"}]}}
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_pr","output":"[{\"type\":\"text\",\"text\":\"{\\\"number\\\":144,\\\"mergeable_state\\\":\\\"dirty\\\"}\"}]"}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"当前是 merge-only merge path；PR 当前是 merge conflict，直接进入自动解冲并续推。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/j4ha2-pr-conflict-auto-heal/replay/positive-pull-request-target-conflict-runs.jsonl

@@ -0,0 +1,2 @@
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_pr","output":"[{\"type\":\"text\",\"text\":\"{\\\"number\\\":145,\\\"mergeable_state\\\":\\\"dirty\\\"}\"}]"}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"当前仓库走 pull_request_target，workflow 仍可能运行；这里仍按 merge conflict 进入自动解冲路径。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/k4n8p-dev-plan-flow-lock-options/HISTORY.md

@@ -0,0 +1,22 @@
+# Dev plan flow lock option guidance cleanup 演进历史（#k4n8p）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `df977df` fix: enforce complete flow lock options
+- `76c6b4d` fix: remove plan flow lock limitation wording
+- `46cbee3` fix: remove strict flow option validation
+- `b583666` fix: relax plan flow option guidance
+- `b39a914` docs(specs): adopt topic-level spec model
+- `#5dvcj` 接管 built-in Plan Mode 的 default auto-lock；`#k4n8p` 仅继续 owner interactive `request_user_input(flow_type)` 的选项指导与别名兼容。
+
+## Legacy Change Log
+
+- No legacy change-log section was recorded for this spec.
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#k4n8p`.

package/toolkit/skills/docs/vendor/dot-codex/specs/k4n8p-dev-plan-flow-lock-options/IMPLEMENTATION.md

@@ -0,0 +1,58 @@
+# Dev plan flow lock option guidance cleanup 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 移除 `flow_type` 选项完备性的硬约束，只保留完整列表建议与 local-merge 别名兼容
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-15
+- Legacy last-tracked: 2026-03-15
+- Current lifecycle: active
+- Catalog note: 移除 `flow_type` 选项完备性的硬约束，只保留完整列表建议与 local-merge 别名兼容
+
+## Delivery Milestones
+
+- [x] M1: 建立 spec 并登记索引
+- [x] M2: 收紧 skill 文案并移除选项完备性硬校验
+- [x] M3: 更新 replay fixtures 与 cases
+- [x] M4: 跑本地校验并收口到 merge-ready（local）
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `docs/specs/dev-plan-flow-lock-options/SPEC.md`
+- `skills/dev-plan/SKILL.md`
+- `skills/dev-plan/references/replay-cases/README.md`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `df977df` fix: enforce complete flow lock options
+- `76c6b4d` fix: remove plan flow lock limitation wording
+- `46cbee3` fix: remove strict flow option validation
+- `b583666` fix: relax plan flow option guidance
+- `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/k4n8p-dev-plan-flow-lock-options/SPEC.md

@@ -0,0 +1,70 @@
+# Dev plan flow lock option guidance cleanup
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 之前曾把 `flow_type` 的完整选项列表写成硬约束，并一度把“缺失显式选项”接进 checker，导致 agent 在计划阶段为了自证合规而反复补问或解释 UI 限制。
+- 主人要求的实际目标更简单：在 skill 中强烈建议尽量给出完整 flow 列表，但不得把这件事升级成阻断性契约。
+- 现有 checker 对 `local-merge` 的中文别名支持已经补齐，后续只需保留这一兼容性事实，不再围绕选项完备性增加门禁。
+- 后续 `docs/specs/dev-plan-default-fast-track-auto-lock/SPEC.md` 已接管显式 `$dev-plan` 路径的“无显式 flow 时默认 auto-lock `fast-track`”语义；本 spec 现在只 owner interactive flow 问题本身的选项指导，不再 owner happy-path 默认选路。
+
+## 目标 / 非目标
+
+### Goals
+
+- 把 `dev-plan` 中关于完整 flow 列表的表述收敛成非阻断性建议。
+- 明确 repo 内不再因 `flow_type` 选项数量或展示形式附加额外校验。
+- 保留 checker 对 `本地合主干` / `本地合主干流程` / `local-merge` 的识别。
+
+### Non-goals
+
+- 不修改 `normal-flow`、`fast-flow`、`local-merge-flow` 的业务执行语义。
+- 不改 Codex 内置 `request_user_input` 工具本身。
+- 不新增新的 plan sections 或输出格式要求。
+
+## 范围（Scope）
+
+### In scope
+
+- `docs/specs/README.md`
+- `docs/specs/dev-plan-flow-lock-options/SPEC.md`
+- `skills/dev-plan/SKILL.md`
+- `bin/plan_contract_check.sh`
+- `skills/dev-plan/references/replay-cases/*`
+
+### Out of scope
+
+- 其他 skill 的 wording 清洗
+- 远端 CI / GitHub 流程调整
+
+## 需求（Requirements）
+
+### MUST
+
+- checker 必须把 `本地合主干` 视为 `local-merge` 的合法中文别名。
+- 当显式 `$dev-plan` 确实需要 interactive flow 锁定问题时，必须继续使用 `request_user_input(flow_type)`，但不得因选项数量或 UI 展示形式额外判 invalid；无显式 flow 的 happy-path 默认 auto-lock 由 `docs/specs/dev-plan-default-fast-track-auto-lock/SPEC.md` 单独 owner。
+
+### SHOULD
+
+- `request_user_input(flow_type)` 在条件允许时应尽量覆盖 `implement-only / normal / fast-track / local-merge`。
+- skill 文案应把这件事表达成强烈建议，而不是硬门禁。
+
+## 验收标准（Acceptance Criteria）
+
+- Given `request_user_input(flow_type)` 因歧义/冲突而被触发，且选项标签使用 `本地合主干` When checker 解析问题和回答 Then 必须识别为 `local-merge`。
+
+- Given 更新后的 repo 文案与 checker When agent 读取显式 `$dev-plan` 相关真相源 Then 不应再把完整 flow 列表解释成阻断性要求。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `bash /Users/ivan/.codex/bin/plan_contract_check.sh /Users/ivan/.codex/skills/dev-plan/references/replay-cases/positive-flow-lock-rui.jsonl`
+- `bash /Users/ivan/.codex/bin/plan_contract_check.sh /Users/ivan/.codex/skills/dev-plan/references/replay-cases/flow-decision-mismatch-lock.jsonl`
+- `bash /Users/ivan/.codex/bin/plan_contract_check.sh --cases /Users/ivan/.codex/skills/dev-plan/references/replay-cases/CASES.txt`
+- `git diff --check`
+
+## 风险 / 假设
+
+- 假设：当前 repo 把 `plan_contract_check.sh` 与 replay fixtures 视为 `dev-plan` 契约真相源的一部分。

package/toolkit/skills/docs/vendor/dot-codex/specs/local-chat-image-snapshots/HISTORY.md

@@ -0,0 +1,20 @@
+# 本地聊天图片快照存储 演进历史（#8tmdq）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `f9ebf1c` feat(images): snapshot local chat images
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Legacy Change Log
+
+- 2026-04-11: 新建 follow-on 规格，锁定本地聊天图片必须先快照的实现方案。
+- 2026-04-11: 完成 helper、git ignore 与受影响提示词/skills 契约同步。
+- 2026-08-04: 根据 Chat 图片不显示复盘，补上 Markdown/HTML owner-facing 图片的全局快照门禁、一次 Stop hook 修复续跑，以及 Chat 快照 URL 与 PR GitHub URL 的分离契约。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#8tmdq`.