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

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

@@ -0,0 +1,61 @@
+# 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: 收紧 `workflow PR publication procedure` / `workflow PR merge procedure` / `$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/references/ci-tracking-short-contract.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/project-engineering-workflow/references/pr-publication-procedure.md`
+- `skills/project-engineering-workflow/references/pr-merge-procedure.md`
+- `skills/flow-continue/SKILL.md`
+- `bin/pr_skill_replay_check.ts`
+- `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/pr-conflict-auto-heal/SPEC.md

@@ -0,0 +1,154 @@
+# PR conflict auto heal
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## Context and Scope
+
+- 当前 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 文案。
+- 更新 `workflow PR publication procedure`、`workflow PR merge procedure`、`$flow-continue` 的冲突分流与 auto-heal 路径。
+- 扩展 `bin/pr_skill_replay_check.ts` 与新增 replay fixtures / cases。
+
+### Out of scope
+
+- 修改业务实现仓库代码。
+- 重构整个 `CI-Operator` 协议。
+- 为所有历史 session 补录真实回放。
+
+## Requirements
+
+### REQ-PR-CONFLICT-001
+
+系统 MUST 在 checks/workflow 缺席诊断前刷新 live PR mergeability； `DIRTY|CONFLICTING` 必须进入 freshness/conflict path，不能被归类为 `CI_NOT_EXPECTED` 或普通 absence wait。
+
+### REQ-PR-CONFLICT-002
+
+系统 MUST 将冲突修复限制在当前授权的 same-PR convergence 范围，并在修复后以新的 head/base SHA 重新建立 validation、CI、review proof 和 Spec evidence。
+
+### REQ-PR-CONFLICT-003
+
+系统 MUST 使用 shared CI tracking contract 判断 manual-only、label-gated、 `pull_request_target` 和其他 trigger facts；手动 workflow 不得被用来制造缺失的自动 PR/push evidence。
+
+- 系统 MUST 将 policy `unknown|unavailable`、queued provider suite 和 pending exact-SHA evidence 保留为 live observation；它们不能在 conflict/freshness 已清除前被降级为 `checks_expected=no` 或 `CI_NOT_EXPECTED`。
+
+### MUST
+
+- 当 open PR 的最新 `head_sha` 长时间没有任何 check runs / workflow evidence 时，必须先刷新 live PR 事实，再按 `../../../skills/project-engineering-workflow/references/ci-tracking-short-contract.md` 区分 `policy_state`、`checks_expected`、`ci_evidence` 和 `gate_effect`；手动 dispatch 不是缺席证据的恢复路径。
+- 若刷新后的 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 时，才允许继续按 shared CI contract 判定 CI 缺席；确认无 required contexts 之前不得写成 `checks_expected=no`，也不得触发手动 workflow。
+- 若当前 head 仍有 queued provider suite 或 pending exact-SHA evidence，absence diagnosis 必须等待该 evidence 或进入真实的 infrastructure observation path；不能因为没有 check-run rows 就判断“没有适用 CI”。
+- 重复 context 的 freshness 归约必须遵循 timestamp、attempt、run identity 的共享顺序； timestamp 部分缺失且 attempt 相同时，不能让较旧失败结果覆盖较新的成功 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`，则仍按 shared CI contract 的 trigger 与 policy facts 诊断；手动 Actions 成功不能替代自动 PR/push evidence。
+- 若自动解冲过程中缺少权限、`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。
+
+## Verification
+
+### VER-PR-CONFLICT-001
+
+- Method: live conflict and CI-absence replay fixtures cover dirty/conflicting, manual-only, label-gated, and pull-request-target paths.
+- covers: `REQ-PR-CONFLICT-001`, `REQ-PR-CONFLICT-003`
+- Pass condition: conflict precedence is preserved, while clean manual-only absence remains non-blocking under the shared CI contract.
+
+### VER-PR-CONFLICT-002
+
+- Method: convergence validation and exact-SHA evidence checks cover conflict repair rebinding.
+- covers: `REQ-PR-CONFLICT-002`
+- Pass condition: every conflict repair invalidates old head-bound evidence and creates a new current-head binding before continuation.
+
+### Testing
+
+- `bun bin/pr_skill_replay_check.ts --cases docs/specs/pr-skill-diagnosis-thinning/replay/cases.txt`
+- `bun test bin/tests/checks/checks.test.ts --test-name-pattern="historical domain adapters cover the canonical case tables"`
+- `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 的稳定事实来源。
+
+## Related ADRs
+
+None
+
+## 参考（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/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/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/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/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/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/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/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/pr-convergence-batching/HISTORY.md

@@ -0,0 +1,61 @@
+# PR convergence batching 演进历史（#syj6s）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- Review rounds are defined as bound review/CI execution, with disposition and repair outside. The parent owns one cumulative three-batch repair budget; child reviewers do not nest independent loops, and the third repair still receives verification. Ordinary mainline advancement is batched at the round boundary rather than restarting live work.
+- Historical first-round parser replay is now explicitly separated from live candidate proof. Its original PR/base/branch remain provenance; the test no longer compares them or a tracked whole-tree digest to the mutable checkout. Isolated digest safeguards and runtime candidate evidence remain in place.
+- Evidence result placement is separated from tracked contract updates to avoid candidate-SHA refresh loops. The workflow owns placement, review-proof owns cumulative repair accounting, and diagnosis owns freshness; duplicated entry prose was folded into these owners, with concise-rewording coverage replacing full-sentence checks.
+- UI 在可本地验证时先完成证据展示与关联基线比较，再冻结 candidate 进入 PR 收敛；一致时无需主人回复，有变化或不可比较时确认展示截图。无本地证据源的 Draft 被收窄为 feedback-only 状态，远端反馈比较完成前不绑定 receipt 或启动 CI/review/merge。
+
+- shared convergence 不再调用独立 review/fix loop；每个 candidate SHA 创建一个窄上下文 native review task，`main-agent` 负责所有写入和一轮一次 push。
+- formal review now waits for Review Readiness and creates fresh runtime reviewers; plans no longer predeclare lanes or model identities, and Repair Batches use provable delta refresh with conservative full-refresh triggers.
+- The PR path now has an explicit stage boundary: `Step 4 Ready` records readiness and applicable pre-PR proof without completed PR-stage findings; exact live PR base/head binding starts CI tracking and fresh PR-stage formal review in the same first round, and main-agent convergence waits for both terminal states. Local-merge formal review remains before Step 5L.
+- The first-round barrier now has a replay fixture and focused false-positive protection: required phrases come from active operative prose, active quoted legacy serial-gate wording is rejected, long/indented/lazy non-operative text cannot satisfy required phrases, and historical snapshot wording is ignored.
+- Follow-up parser hardening now treats thematic breaks as the end of lazy blockquote continuation and keeps quote markers inside top-level fenced code literal; focused regressions cover both boundaries.
+- The follow-up replay fixture now owns the parser boundary cases, including all thematic-break marker families, so focused tests fail closed when a parser case is removed from the fixture or implementation.
+- The next follow-up hardening requires quote-prefixed fence content to remain quote-prefixed, routes required-contract checks through operative text, and binds replay evidence to the current candidate's repository/base/head facts.
+- The following parser hardening closes blank and explicit thematic-break blockquotes, handles explicit and unprefixed quote-fence boundaries with top-level fence reopening, surfaces unclosed-fence text to forbidden-gate scans, rejects non-canonical GitHub remotes, and binds the follow-up replay to repository identity, a resolvable base ref/SHA, a fixed head ref with runtime exact head SHA, actual tracked worktree content/mode, and an immutable clean-Git-tree digest including entry modes with length framing that normalizes only its own field.
+- The next parser hardening aligns fence and blockquote indentation with CommonMark, rejects backticks in backtick fence info strings, keeps four-space lazy quote continuations quoted, and rejects intermediate directory symlinks while binding the candidate worktree.
+- The follow-up binding hardening uses CommonMark tab-stop indentation for mixed-space/tab lazy continuations, checks entry stability and clean state before and after the digest walk, and locks the replay fixture to a unique complete parser-case name set.
+- The active-text contract explicitly keeps inline-code stage and field names operative while continuing to exclude fenced, indented, quoted, and historical text.
+- The final replay hardening tracks whether an active block is a paragraph before accepting lazy quote continuation, covers heading/HTML boundaries, and rechecks the fixed head ref and `HEAD` around digest traversal; `repo_root` remains portable runtime Git-top-level evidence.
+- The replay binding now pins its PR locator and keeps exact `head_sha` as runtime PR/formal evidence (avoiding a self-referential tracked field), while the parser distinguishes block HTML from inline tags and consumes a tab after a quote marker as paragraph indentation.
+- After the follow-up parser PR was merged into its parent, the replay fixture and focused binding test were rebound to the parent PR and current main base before the parent convergence review.
+- The parser review then closed an HTML block lazy-continuation bypass by distinguishing block HTML starts from inline HTML and adding a dedicated unprefixed boundary fixture.
+- The parser follow-up now recognizes standalone arbitrary HTML tags and excludes multiline comments, `script`, and `style` blocks from operative contract text while retaining them for forbidden serial-gate scanning.
+- Tier-consistent direct-plan guidance, complete readiness vocabulary, and clear structured lane evidence are now enforced before convergence can clear; scope mismatches, unknown fields, and unchanged base-drift bindings fail closed.
+- Direct-plan gates now fail closed for strategy text that merely co-occurs readiness/runtime terms or profile text that omits a concrete model/effort pair.
+- Malformed review dispositions now fail closed rather than being inferred as report-only or in-scope repair evidence.
+- Omitted readiness and empty In-Scope evidence now fail closed at the replay boundary.
+- Terminal replay evidence now rejects unsupported actual profiles and unknown embedded finding dispositions.
+- Observation-only terminal evidence cannot authorize an In-Scope Repair Batch; duplicate formal policy fields are rejected.
+- Missing or unknown structured finding kinds are rejected before evidence can become terminal.
+- A blocking finding in valid terminal clear evidence follows disposition; only unavailable or malformed output remains `unchecked`.
+- CI/review 按 SHA 短生命周期，Spec/Solutions 使用按需 docs sidecar；新 SHA 重建 SHA-bound tracking，但继承同一 PR 的 `3/2` 预算。
+- 收敛预算改为一次 initial review 加最多三轮 repair 的单调 fingerprint 合同：无进展只允许一次诊断，之后以 `NON_CONVERGENT` 终止；内层 invocation 不重置预算。
+- CI tracker 的 bounded wait/polling budget 统一为从启动计时的 `600 seconds (10 minutes)`；预算调整不改变 bound SHA、一次 transient retry、terminal state 或 recovery-card 语义。
+- Review repair eligibility now distinguishes the initial Formal Review Wave from later waves: an initial P2-only repair is optional, later P2 repair needs a P0/P1 or qualifying current-Candidate CI trigger, and low-priority findings may clear with an explicit non-blocking resolution.
+
+- 统一首轮 `CI-Operator` sub-agent 的模型偏好为 `gpt-5.6-luna + low`，绑定单一 PR head SHA，并要求主 agent 通过阻塞式等待接收结果；模型或 effort override 在 child start 前不可用时只可改用不同的完整显式 pair，同时保持 review profile 不变；重复的 tracker 不变量集中到 CI tracking short contract。
+- `d443ac1` fix(flow): batch PR convergence before remote churn
+- `71c44e5` fix(review): preserve convergence budgets across repair pushes
+- `f565cff` fix(flow): enforce resumable PR convergence gates
+- `281b1cd` fix(flow): honor no-write PR proof gates
+- `b4544c8` fix(review): rerun stale pre-pr proofs on new heads
+- `3b0afb3` fix(review): bind proof budget to current PR batch
+- `90e80dd` fix(docs): persist PR budget bindings consistently
+- `2c11073` fix(review): harden proof-only convergence rules
+- `4895098` docs(review): add pragmatic stop-loss after repeated reviews
+- `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: `#syj6s`.

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-convergence-batching/IMPLEMENTATION.md

@@ -0,0 +1,106 @@
+# PR convergence batching 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+Review-permit and receipt details below are historical rollout snapshots. Current direct flow uses the Formal Review Wave, finding disposition, and Repair Batch contract described in the active specification.
+
+## Current Status
+
+- Late PR resolution applies when a concrete deferral is considered after validation and a complete review/CI round. Eligible PR-introduced P0/P1 remain current-PR priorities; other qualified findings can carry explicit authorized deferrals. After source merge/closeout, one independent fast-flow follow-up reaches Step 5C Ready with separate evidence and count, source traceability and duplicate-safe continuation.
+
+- The shared review-proof reference presents execution in order: readiness, parallel launch, complete-round wait, disposition, pre-write batch accounting, and final-candidate refresh. It explains partial returns from native batch-wait next to the all-terminal rule; live-reviewer uniqueness is explicitly per Candidate and lane. CI tracking, fresh-reviewer requirements, cumulative limits, and delta-based refresh retain their existing owners and semantics.
+- The shared review-proof reference now applies a priority-aware repair threshold: an initial Formal Review Wave may optionally repair a P2-only finding; later P2 repair requires a P0/P1 or qualifying current-Candidate CI trigger. P2/P3-only results can clear with `repair_not_required_low_priority` and a next-stop owner report.
+- The shared workflow owns candidate freeze/result placement; review-proof owns readiness and cumulative CI/review repair accounting; PR diagnosis owns freshness admission. Entry skills route to these owners, and the optional receipt reference owns ledger behavior only.
+- Architecture checks cover operative rule relationships and permit concise rewording; native tool-call replay rejects new formal review or CI tracking during actual conflicts while allowing ordinary target drift. These are offline checks, not live write interception.
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: runtime-created fresh review 按 SHA 提供 proof，main-agent 批量收敛，checks 缺席快速诊断
+- Current convergence: Formal Review Wave 是固定 base/head 上 review 与 CI 从启动到全部终态的区间；父流程随后分类 findings、处理累计主干变化并执行必要修复。只有 In-Scope Review Finding 进入 Repair Batch，Design-Returning 停止普通收敛，Observation 只报告。父流程保留累计修复计数；接近三批或根因反复出现时先诊断，再自主继续范围内修复，子调用不嵌套修复循环。
+- CI tracker 现在以启动时刻为起点保留 `600 seconds (10 minutes)` 的 bounded wait/polling budget；确定性 contract tests 同时守住 bound SHA、一次 retry、terminal state 与 recovery-card 语义。
+- Formal Review Wave starts after Review Readiness with fresh runtime reviewers. Delta-proven local repairs retain unaffected results; shared-contract, unknown, high-risk, or actual review-base adoption refreshes all lanes. Observed target advancement follows the diagnosis round-boundary rule.
+- Direct PR timing is now explicit: `Step 4 Ready` records readiness and applicable pre-PR proof without completed PR-stage findings; exact live PR base/head binding starts CI tracking and fresh PR-stage formal review in the same first round, and main-agent convergence waits for both terminal states. Local-merge still completes formal review before Step 5L.
+- Replay coverage binds the same Candidate to its lane, scope, review profile, locked flow, ownership promise, and cumulative Repair Batch count; mismatches fail closed instead of resetting the repair count.
+- The active Spec checker enforces the same disposition, `unchecked` evidence, and complete continuation-anchor contract used by PR convergence.
+- Retired disposition terms are regression-tested as failures for this active Spec as well as the other review Specs.
+- Repair replay exercises autonomous fourth and later batches and preserves the active Candidate anchor and cumulative count across continuation.
+- Migration replay distinguishes accepted baseline limits, candidate regressions, unknown attribution, new guarantees and failed acceptance; recurring roots and a third repair require diagnosis before the replay writes.
+- Instruction architecture checks cover the shared disposition contract, all direct-flow consumers, and the review anchor boundaries.
+- The first-round PR barrier replay fixture and focused architecture test cover the active consumer contract, active quoted legacy Step 4 serial-gate rejection, long-fence/indented-code/thematic-break/lazy-quote non-operative required-text rejection, four-space and mixed-tab lazy quote continuation, invalid backtick fence info strings, inline-code contract text, tab-indented fence markers, quote block boundaries after headings and HTML blocks, inline HTML and quote-marker-after-tab paragraphs, quote markers inside top-level fences, and historical snapshot wording without false-positive findings. The replay fixture now feeds these parser cases directly into the focused test, including thematic-break marker families, leading/inner spacing variants, quote-prefixed fence boundaries, explicit thematic-break blockquote closure, explicit and unprefixed quote-fence boundary handling with top-level fence reopening, blank-quote closure, unclosed-fence forbidden-gate scanning. The focused test requires the fixture's parser case names to be unique and complete. Inline code remains operative because canonical stage and field names use that form; only fenced, indented, quoted, or historical text is non-operative. The fixture declares `evidence_role=historical-scenario` and keeps its original PR/base/branch under `historical_binding`; it carries no current candidate digest. Its test validates historical provenance without resolving those refs against the current checkout. Branch switches, detached HEAD, dirty candidate edits, and base advancement therefore do not require fixture-refresh commits. Live PR open/base/head and runtime Git-top-level evidence remain adapter/flow responsibilities. Isolated repository tests retain canonical GitHub remote parsing and digest safeguards for content, entry mode, index-hidden edits, symlinked parent directories, traversal stability, and clean state. Required contract checks use operative text only; forbidden serial-gate scans retain active quoted text and malformed unclosed-fence content so legacy wording cannot bypass detection.
+- Isolated-copy architecture checks cover readiness language and the active `0017` ADR relationship.
+- Direct plan semantic checks reject tier/strategy/profile contradictions, and the replay seam rejects incomplete, scope-forged, or unknown-field structured lane evidence.
+- Direct plan semantic checks also require a concrete supported model/effort recommendation and an explicit runtime formal-lane launch/create action; reviewer identity and Repair Batch lane count remain runtime decisions.
+- ReviewReplay rejects unknown disposition tokens before deciding whether a candidate may enter a Repair Batch or remain report-only.
+- ReviewReplay fail-closes omitted readiness and empty In-Scope evidence before launching or mutating a candidate.
+- ReviewReplay also fail-closes unsupported actual profiles and unknown dispositions embedded in structured findings.
+- In-Scope repair now requires a demonstrated finding kind, and direct formal policy fields are rejected when duplicated.
+- Terminal finding objects must declare a supported demonstrated or observation kind.
+- UI entry: 本地可测候选先完成关联基线比较；一致时无需主人回复，有可见变化或不可比较时确认展示截图。无本地证据源仅使用不绑定、不收敛的 feedback-only Draft，直到远端反馈完成同一比较。
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-14
+- Legacy last-tracked: 2026-03-14
+- Current lifecycle: active
+- Catalog note: 风险触发 pre-PR local proof、PR 批量收敛与 checks 缺席快速诊断
+- Legacy receipt convergence: validation receipt 绑定 current candidate evidence；每个 epoch 最多三次 repair permit，final merge proof 的 blocker 回到剩余 permit。
+
+## Delivery Milestones
+
+- [x] M1: 建立 `docs/specs/pr-convergence-batching/SPEC.md` 规格并登记索引
+- [x] M2: 在 shared Step 4/5 中前置风险触发的 `pre-PR local proof`
+- [x] M3: 固化 PR 批量收敛、current-SHA validation evidence 与 checks 缺席诊断门
+- [x] M4: 为自动收敛增加 `3` 次 repair permit 止损
+- [x] M5: 统一 `CI-Operator` sub-agent 的首选模型为 `gpt-5.6-luna + low`，绑定单一 PR head SHA，将主 agent CI 等待改为阻塞式 barrier，并把共享不变量集中到 CI tracking contract
+- [x] M6: review proof 改为按 candidate SHA 的原生只读 task，main-agent 成为唯一写入者
+- [x] M7: Spec/Solutions 合并为按需 docs sidecar，仅在有效输入变化时重跑
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `skills/project-engineering-workflow/references/ci-tracking-short-contract.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/project-engineering-workflow/references/review-proof-short-contract.md`
+- `bin/flow_receipt.py`
+- `skills/project-engineering-workflow/references/pr-publication-procedure.md`
+- `skills/fast-flow/SKILL.md`
+- `skills/flow-continue/SKILL.md`
+- `skills/ui-visual-evidence/SKILL.md`
+- `bin/pr_skill_replay_check.py`
+- `docs/specs/mandatory-local-review-proof/SPEC.md`
+- `docs/adr/0017-review-readiness-and-runtime-launch.md`
+- `bin/instruction_architecture_check.py`
+- `bin/test_instruction_architecture_check.py`
+- `docs/specs/pr-convergence-batching/replay/first-round-parallel-barrier.json`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `d443ac1` fix(flow): batch PR convergence before remote churn
+- `71c44e5` fix(review): preserve convergence budgets across repair pushes
+- `f565cff` fix(flow): enforce resumable PR convergence gates
+- `281b1cd` fix(flow): honor no-write PR proof gates
+- `b4544c8` fix(review): rerun stale pre-pr proofs on new heads
+- `3b0afb3` fix(review): bind proof budget to current PR batch
+- `90e80dd` fix(docs): persist PR budget bindings consistently
+- `2c11073` fix(review): harden proof-only convergence rules
+- `4895098` docs(review): add pragmatic stop-loss after repeated reviews
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Remaining Gaps
+
+- None currently tracked.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`