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

package/toolkit/skills/docs/vendor/dot-codex/specs/review-proof-dedupe-wait-guard/HISTORY.md

@@ -0,0 +1,23 @@
+# Review proof 去重与等待语义守卫 演进历史（#m3k8q）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- shared proof 生命周期从 exec-session polling 迁移为 native Agent task + `wait_agent`；旧 replay fixtures 保留为历史事故样例，不再作为 current shared gate checker。
+- completed proof 从 raw output/SHA 推断改为 execution receipt + current-head delta attestation；live proof identity 仍严格绑定当前 head。
+- 以 spec-local deterministic fixtures 取代已回收的全局 session replay，继续覆盖 exec-session wait misuse 与 non-direct review launch。
+
+- `dab0cc2` fix(flow): guard review 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: `#m3k8q`.

package/toolkit/skills/docs/vendor/dot-codex/specs/review-proof-dedupe-wait-guard/IMPLEMENTATION.md

@@ -0,0 +1,67 @@
+# Review proof 去重与等待语义守卫 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: shared review-proof contract 改按 helper-observed `thread.started` 启动态，并以 structured receipt 作为 proof 真相源
+- Receipt reuse: completed proof 可通过 current-head scoped delta attestation 复用；current-SHA CI/approval 门禁保持不变。
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-17
+- Legacy last-tracked: 2026-04-12
+- Current lifecycle: active
+- Catalog note: shared review-proof contract 改按 helper-observed `thread.started` 启动态，并以 structured receipt 作为 proof 真相源
+
+## Delivery Milestones
+
+- [x] M1: 建立规格、共享 review-proof 短规约与索引登记
+- [x] M2: 收紧 native `$review-agent` / `$flow-continue` / shared workflow / prompts，并瘦身重复规则
+- [x] M3: proof key 改为 repo/head/base/profile，统一 `wait_agent` 终态与 native receipt 去重
+- [x] M3: 新增 focused replay checker 与 replay fixtures
+- [x] M4: 跑本地检查并收口到可继续 local-merge handoff
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `docs/specs/review-proof-dedupe-wait-guard/SPEC.md`
+- `skills/project-engineering-workflow/references/review-proof-short-contract.md`
+- `skills/project-engineering-workflow/references/pr-diagnosis-short-contract.md`
+- `skills/codex-review-loop/SKILL.md`
+- `skills/flow-continue/SKILL.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/local-merge-flow/SKILL.md`
+- `prompts/advance-flow.md`
+- `prompts/pr-create.md`
+- `prompts/pr-merge.md`
+- `bin/review_proof_replay_check.py`
+- `docs/specs/review-proof-dedupe-wait-guard/replay/*`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `dab0cc2` fix(flow): guard review 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/review-proof-dedupe-wait-guard/SPEC.md

@@ -0,0 +1,62 @@
+# Review proof 去重与等待语义守卫
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- Shared review uses one read-only sub-agent per required lane in the current candidate. The receipt helper never starts that agent or reads task, child, or transcript metadata.
+- 新风险是同一 candidate 重复启动同 lane reviewer，或在 SHA 变化后误用旧结果。
+
+## 目标 / 非目标
+
+### Goals
+
+- 用 `repo_root + head_sha + base_sha + review_profile + wave_id + lane` 定义 canonical proof key。
+- 每个 `wave_id + lane` 只允许一个 live/completed 等价的 read-only sub-agent review；不同 lane 可以并行。
+- 固定使用 `wait_agent` 等待 sub-agent 终态，禁止主代理为 review 自行轮询或启动第二层 reviewer。
+- 新 SHA 明确使旧 proof stale，并创建窄上下文新任务。
+
+### Non-goals
+
+- 不治理独立手动 review/fix 工具的 exec-session 生命周期。
+- 不修改 CI tracker 或 GitHub 远端语义。
+
+## 需求（Requirements）
+
+### MUST
+
+- shared reviewer 必须是 `fork_turns=none` 的 read-only sub-agent。
+- 相同 wave/lane 去重键已有 live sub-agent 时只能 `wait_agent`；已有 valid completed receipt 时直接复用，不得重复 spawn；不同 lane 不互相阻塞。
+- 只有 matching lane 的 terminal `completed` + strict structured result + clean current HEAD 才能登记 proof。receipt 不读取或依赖 Agent/task/child/session ID。
+- head/base 改变后旧 result 应标记为 `input_stale`；新 fact set 创建新的 lane review，旧结果不能变成新 SHA proof。
+- failed、timeout、interrupted、missing-result 与 invalid-schema 都是非 clear 终态；model unavailable 必须登记 `unavailable` attempt 并只按 model fallback ladder 继续。
+- shared callers 必须统一引用 `review-proof-short-contract.md`，不得复制另一套生命周期。
+
+## 功能与行为规格
+
+- Launch: 主代理先查询/恢复同 key lane；不存在时创建一个 read-only sub-agent reviewer。
+- Wait: 主代理通过 `wait_agent` 持有到终态，不把它包装成 GitHub shared wait-state。
+- Record: completed result 使用活动 wave 的 `record --kind review --wave-id <wave> --lane <lane> --review-result-json <structured-result>` 登记；helper 只校验和持久化，不启动 reviewer 或读取 task/transcript 元数据。
+- Replay: 同一 current base/head、wave、lane、profile 与 canonical structured result 的重复登记必须返回既有 receipt；任何不匹配的重放必须拒绝，不能覆盖 lane。
+- 同一 current base/head、wave、lane、profile 与 `startup-unavailable` 分类的 unavailable attempt 也必须幂等返回既有 attempt，不得追加重复 fallback 审计记录。
+- Refresh: candidate SHA 或 base SHA 改变即生成新 key；旧 result 只作诊断，不参与 gate。
+- Repair: findings 交给 `main-agent`；reviewer 不写文件、不提交、不 push。
+
+## 验收标准
+
+- Given 同一 `proof_key + wave_id + lane` 已有 live task，When 任一 shared 入口请求 review，Then 只等待现有 task；其他声明 lane 不得被该 lane 串行阻塞。
+- Given caller 试图把 Agent/task/child/session identity 作为 receipt proof，Then replay/static guard 必须失败。
+- Given旧 task completed 后 HEAD 已变化，When 登记 proof，Then receipt 必须拒绝或标记 stale。
+- Given task 非 completed 或 result schema 不完整，When 评估 gate，Then `review=unchecked`，不得 clear。
+- Given repair push 产生新 SHA，When 重建 reviewer，Then 当前 epoch 的 `3` repair permit 不得重置；只有显式 `convergence-reopen` 才能创建新 repair epoch。
+- Given 已消费的 repair wave 因新 SHA stale，When 发放下一 permit，Then 旧 permit 保持已消费并计入上限，新 permit 从 current ledger head 起算。
+
+## 质量门槛
+
+- unit/static tests 覆盖同 key 去重、新 SHA 不复用、nonterminal、dirty head、strict schema 与 shared caller 引用审计。
+- `git diff --check` 通过。
+
+## 参考
+
+- `docs/specs/review-proof-ownership/SPEC.md`
+- `skills/project-engineering-workflow/references/review-proof-short-contract.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/review-proof-dedupe-wait-guard/replay/cases.txt

@@ -0,0 +1,6 @@
+# status path expected_code
+fail negative-exec-session-wait-misuse.jsonl EXEC_SESSION_WAIT_MISUSE
+fail negative-non-direct-review-launch.jsonl NON_DIRECT_REVIEW_LAUNCH
+fail negative-helper-review-wrapper.jsonl NON_DIRECT_REVIEW_LAUNCH
+fail negative-live-proof-duplicate-launch.jsonl DUPLICATE_LIVE_REVIEW_LAUNCH
+pass positive-single-proof-polling.jsonl -

package/toolkit/skills/docs/vendor/dot-codex/specs/review-proof-dedupe-wait-guard/replay/negative-exec-session-wait-misuse.jsonl

@@ -0,0 +1,3 @@
+{"type":"response_item","payload":{"type":"function_call","name":"exec_command","arguments":"{\"cmd\":\"codex -m gpt-5.4 -c model_reasoning_effort=\\\"high\\\" --sandbox read-only -a never review --base origin/main\",\"workdir\":\"/tmp/demo\",\"tty\":true}","call_id":"call_launch"}}
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_launch","output":"Process running with session ID 301\n"}}
+{"type":"response_item","payload":{"type":"function_call","name":"wait","arguments":"{\"ids\":[301]}","call_id":"call_wrong_wait"}}

package/toolkit/skills/docs/vendor/dot-codex/specs/review-proof-dedupe-wait-guard/replay/negative-helper-review-wrapper.jsonl

@@ -0,0 +1 @@
+{"type":"response_item","payload":{"type":"function_call","name":"exec_command","arguments":"{\"cmd\":\"true && python3 /opt/codex/bin/flow_receipt.py --repo /tmp/demo record --kind review --review-profile merge-proof --base-ref abc123 --review-model gpt-5.6-sol --review-effort low --head-sha def456\",\"workdir\":\"/tmp/demo\"}","call_id":"call_wrapped_helper"}}

package/toolkit/skills/docs/vendor/dot-codex/specs/review-proof-dedupe-wait-guard/replay/negative-live-proof-duplicate-launch.jsonl

@@ -0,0 +1,4 @@
+{"type":"response_item","payload":{"type":"function_call","name":"exec_command","arguments":"{\"cmd\":\"python3 /opt/codex/bin/flow_receipt.py --repo /tmp/demo record --kind review --review-profile merge-proof --base-ref abc123 --review-model gpt-5.6-sol --review-effort low --head-sha def456\",\"workdir\":\"/tmp/demo\"}","call_id":"call_launch_1"}}
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_launch_1","output":"Chunk ID: a1\nWall time: 1.0000 seconds\nProcess running with session ID 101\nOriginal token count: 0\nOutput:\n{\"type\":\"thread.started\",\"thread_id\":\"proof-1\"}\n"}}
+{"type":"response_item","payload":{"type":"function_call","name":"exec_command","arguments":"{\"cmd\":\"python3 /opt/codex/bin/flow_receipt.py --repo /tmp/demo record --kind review --review-profile merge-proof --base-ref abc123 --review-model gpt-5.6-sol --review-effort low --head-sha def456\",\"workdir\":\"/tmp/demo\"}","call_id":"call_launch_2"}}
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_launch_2","output":"Chunk ID: a2\nWall time: 1.0000 seconds\nProcess running with session ID 102\nOriginal token count: 0\nOutput:\n{\"type\":\"thread.started\",\"thread_id\":\"proof-2\"}\n"}}

package/toolkit/skills/docs/vendor/dot-codex/specs/review-proof-dedupe-wait-guard/replay/negative-non-direct-review-launch.jsonl

@@ -0,0 +1 @@
+{"type":"response_item","payload":{"type":"function_call","name":"exec_command","arguments":"{\"cmd\":\"sleep 1 && codex -m gpt-5.4 -c model_reasoning_effort=\\\"high\\\" --sandbox read-only -a never review --base origin/main > /tmp/review.log 2>&1\",\"workdir\":\"/tmp/demo\",\"tty\":true}","call_id":"call_wrapped_launch"}}

package/toolkit/skills/docs/vendor/dot-codex/specs/review-proof-dedupe-wait-guard/replay/positive-single-proof-polling.jsonl

@@ -0,0 +1,6 @@
+{"type":"response_item","payload":{"type":"function_call","name":"exec_command","arguments":"{\"cmd\":\"python3 /opt/codex/bin/flow_receipt.py --repo /tmp/demo record --kind review --review-profile merge-proof --base-ref abc123 --review-model gpt-5.6-sol --review-effort low --head-sha def456\",\"workdir\":\"/tmp/demo\"}","call_id":"call_launch_ok"}}
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_launch_ok","output":"Chunk ID: b1\nWall time: 1.0000 seconds\nProcess running with session ID 201\nOriginal token count: 0\nOutput:\n{\"type\":\"thread.started\",\"thread_id\":\"proof-1\"}\n"}}
+{"type":"response_item","payload":{"type":"function_call","name":"write_stdin","arguments":"{\"session_id\":201,\"chars\":\"\",\"yield_time_ms\":1000}","call_id":"call_poll_1"}}
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_poll_1","output":"Chunk ID: b2\nWall time: 1.0000 seconds\nProcess running with session ID 201\nOriginal token count: 0\nOutput:\nthinking\n"}}
+{"type":"response_item","payload":{"type":"function_call","name":"write_stdin","arguments":"{\"session_id\":201,\"chars\":\"\",\"yield_time_ms\":1000}","call_id":"call_poll_2"}}
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_poll_2","output":"Chunk ID: b3\nWall time: 1.0000 seconds\nProcess exited with code 0\nOriginal token count: 0\nOutput:\nno findings\n"}}

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

@@ -0,0 +1,22 @@
+# Review proof ownership 演进历史（#q9r2m）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- 共享 proof 从 helper 启动第二层 `codex exec` 改为原生 `$review-agent` task；原因是减少重复模型调用、消除 exec-session/agent-session 混淆，并让任务终态直接成为 ownership 边界。
+- proof identity 固定为 `repo_root + head_sha + base_sha + review_profile`；新 SHA 不复用旧结果，同 key 不重复启动。
+- review agent 永远只读，`main-agent` 统一负责 findings 聚合、修复、验证、提交和 push；repair push 不重置 `3/2` 预算。
+- `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/review-proof-ownership/IMPLEMENTATION.md

@@ -0,0 +1,60 @@
+# Review proof ownership 历史实现记录
+
+> 本主题已由 [`mandatory-local-review-proof`](../mandatory-local-review-proof/SPEC.md) 替代。本文件仅保留历史实现上下文，不定义当前路由、门禁或 proof 生产方式。
+
+## Current Status
+
+- Implementation: historical
+- Lifecycle: superseded
+- Active contract: `mandatory-local-review-proof`
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-16
+- Legacy last-tracked: 2026-04-12
+- Current lifecycle: superseded
+- Catalog note: helper-owned proof 与 native-agent receipt 均为历史实现；当前 direct flow 使用 successor contract
+
+## Delivery Milestones
+
+- [x] M1: 建立 review proof ownership 规格并登记索引
+- [x] M2: 建立 read-only sub-agent 的 terminal / schema / stale-proof 契约
+- [x] M3: 收敛共享 wait-state 规则并瘦身下游 skills/prompts
+- [x] M4: `flow_receipt.py record --kind review --wave-id <wave> --lane <lane> --review-result-json <structured-result>` 登记结构化结果
+- [x] M5: shared flow 改为 main-agent 单写入与按 SHA 短生命周期 receipt
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `bin/flow_receipt.py`
+- `bin/test_flow_receipt.py`
+- `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/review-proof-ownership/SPEC.md

@@ -0,0 +1,39 @@
+# Review proof ownership
+
+> Superseded for direct delivery by [`mandatory-local-review-proof`](../mandatory-local-review-proof/SPEC.md). This topic preserves historical ownership context only and defines no active direct-flow routing, gate, or `ReviewReceipt` producer.
+
+## Related ADRs
+
+- [0013 Review necessity tiering](../../adr/0013-review-necessity-tiering.md)
+
+## Context and Scope
+
+Earlier receipt schemas derived review provenance from native child tasks and runtime transcripts. That transport-specific model is retained only to explain historical v5 ledger fields. Schema v6 replaces it for direct delivery with the sub-agent structured receipt contract.
+
+### Goals
+
+- Preserve the meaning of historical native-agent receipt fields for audit.
+- Direct new implementation to the active transport-neutral specification.
+
+### Non-goals
+
+- Define a current delivery review gate or a review runner.
+- Change CI tracker, GitHub, or release-fact behavior.
+
+## Requirements
+
+### REQ-HISTORICAL-NATIVE-REVIEW
+
+- Historical native task, child-ID, transcript, and `agent-review` fields remain readable audit data only when carried from an active v5 ledger.
+- New direct flows must use the schema v6 sub-agent-only `record --kind review` path from the successor specification. Historical data cannot satisfy a current-head mandatory proof.
+
+## Verification
+
+### VER-HISTORICAL-OWNERSHIP covers: REQ-HISTORICAL-NATIVE-REVIEW
+
+- An active v5 ledger migrates without changing its retained review bytes; v1-v4 direct ledgers are rejected.
+- A direct v6 receipt rejects native transcript or child-provenance as proof.
+
+## Visual Evidence
+
+- Not applicable: this topic has no visual delivery surface.

package/toolkit/skills/docs/vendor/dot-codex/specs/s7gvk-pr-freshness-gate/HISTORY.md

@@ -0,0 +1,18 @@
+# PR freshness gate 演进历史（#s7gvk）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `aca3834` fix(skills): gate stale prs before convergence
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Legacy Change Log
+
+- 2026-03-13: 新增 PR freshness gate 规格并完成相关 skill 契约收敛。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#s7gvk`.

package/toolkit/skills/docs/vendor/dot-codex/specs/s7gvk-pr-freshness-gate/IMPLEMENTATION.md

@@ -0,0 +1,56 @@
+# PR freshness gate 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: PR 阶段 stale/conflict 前置门禁
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-13
+- Legacy last-tracked: 2026-03-13
+- Current lifecycle: active
+- Catalog note: PR 阶段 stale/conflict 前置门禁
+
+## Delivery Milestones
+
+- [x] M1: 建立 `docs/specs` 根目录与本次 freshness gate 规格
+- [x] M2: 更新共享 Step 5 契约，前置 PR freshness gate
+- [x] M3: 收紧 `$pr-create`、`$pr-merge`、`$fast-flow`、`$flow-continue`
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`: 新增规格索引
+- `skills/project-engineering-workflow/SKILL.md`: Step 5 freshness gate
+- `skills/pr-create/SKILL.md`: PR 创建后 freshness gate 与轮询重置
+- `skills/pr-merge/SKILL.md`: final refresh 与 stale-head merge fallback
+- `skills/fast-flow/SKILL.md`: Auto Heal 授权范围扩展
+- `skills/flow-continue/SKILL.md`: 恢复路由优先级对齐
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `aca3834` fix(skills): gate stale prs before convergence
+- `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/s7gvk-pr-freshness-gate/SPEC.md

@@ -0,0 +1,140 @@
+# PR freshness gate
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 现有 PR 流程会在 PR 已经 `mergeable_state=behind` 时，继续消耗 review-loop、CI 等高成本收敛动作。
+- `019ce2c6-a339-77b0-9044-2903ee310ee2` 已复盘出明确回归样例：`2026-03-12T19:19:40Z` 读取 PR #119 时已经得到 `mergeable_state=behind`，但流程直到 `2026-03-12T19:30:42Z` merge API 被 repository rules 拒绝后，才开始 `update_pull_request_branch`。
+- 不做前置门禁的代价是重复等待过时 checks、重复补旧 `head.sha` 的 review proof，以及在 stale branch 上做无效收敛。
+
+## 目标 / 非目标
+
+### Goals
+
+- 把 PR 代码过时、branch behind、merge conflict 从 merge 失败后的补救，前移成 Step 5A 的共享 freshness gate。
+- 让 `behind` 在授权的 PR 流里自动收敛，避免继续浪费 review/CI 资源。
+- 明确 `blocked` 不等于 conflict/stale branch，避免误判。
+- 明确 `PR.head.sha` 或 `PR.base.sha` 变化会使旧 checks、旧 review proof、旧 spec verdict 失效。
+
+### Non-goals
+
+- 不新增新的统一状态字段。
+- 不重写 `$codex-review-loop` 的 profile 体系。
+- 不改 `gh CLI` 远端控制面或引入新的远端自动化通道。
+
+## 范围（Scope）
+
+### In scope
+
+- 更新 `$project-engineering-workflow` 的 Step 5 共享契约。
+- 收紧 `$pr-create` 的 PR 创建后顺序门禁、等待语义与 stale-state 重置规则。
+- 收紧 `$pr-merge` 的 mergeable 判定、最终 merge 前刷新与 stale-head 错误回退。
+- 对齐 `$fast-flow` 与 `$flow-continue` 的授权与恢复语义。
+
+### Out of scope
+
+- 为 skills 引入新的自动化测试框架。
+- 修改实现阶段本地 Step 1-4 的基线同步策略。
+- 引入新的 PR body 字段或新的 GitHub 状态模型。
+
+## 需求（Requirements）
+
+### MUST
+
+- `mergeable_state=behind` 必须在 PR 并行收敛和 merge API 尝试之前处理。
+- `mergeable == false` 或 `mergeable_state == dirty` 必须在高成本收敛动作之前阻断。
+- 在已授权远端变更的 PR 流里，`behind` 必须自动走 branch update 或 rebase 路径。
+- 任意 `PR.head.sha` 或 `PR.base.sha` 变化，必须使旧 checks、旧 review proof、旧 spec-sync verdict 失效。
+- merge 前必须做一次最终 PR refresh；若 freshness gate 不再 clear，不得调用 merge API。
+
+### SHOULD
+
+- `blocked` 状态应继续依赖 checks/review/spec 事实判定，而不是直接按 conflict 处理。
+- 轮询中的 stale-state 变化应立即返回 freshness gate，而不是继续等待旧状态。
+
+### COULD
+
+- 后续补充更多 session 回放样例作为文档化回归集。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- PR 一旦存在，必须先跑 freshness gate，确认当前 PR 对应的 `head.sha` / `base.sha` 仍是可收敛对象。
+- 如果 PR `behind`，且当前 flow 已授权远端更新：
+  - `MODE=rebase` / linear-history-only: 走本地 `$update-baseline` rebase + force-push。
+  - 其他默认路径：走 GitHub `update_pull_request_branch`。
+- freshness gate clear 后，才允许启动或恢复 `CI-Operator`、PR-stage review-loop、spec-sync 与 PR body rewrite。
+- merge 前必须重新读取 PR；若 base 在 checks 变绿后又前进，旧绿灯作废，重新进入 freshness gate。
+
+### Edge cases / errors
+
+- `mergeable_state=blocked` 但只是 checks/reviews 未满足时，不应误判成 conflict。
+- `update_pull_request_branch` 或 rebase 后，即使 `PR.head.sha` 已变化，也必须等到 `mergeable_state != behind` 才能离开 freshness gate。
+- merge API 若返回 stale-head / expected checks / repository rule violation 类错误，必须回读 PR 再决定是 freshness gate 还是普通 checks gate，不能直接按普通失败结束。
+
+## 接口契约（Interfaces & Contracts）
+
+### 接口清单（Inventory）
+
+| 接口（Name） | 类型（Kind） | 范围（Scope） | 变更（Change） | 契约文档（Contract Doc） | 负责人（Owner） | 使用方（Consumers） | 备注（Notes） |
+| - | - | - | - | - | - | - | - |
+| `$project-engineering-workflow` Step 5 | skill contract | internal | Modify | None | main-agent | `$pr-create`, `$pr-merge`, `$fast-flow`, `$flow-continue` | 新增 shared PR freshness gate |
+| `$pr-create` PR-stage setup | skill contract | internal | Modify | None | main-agent | PR 创建与首轮收敛路径 | freshness gate 前置 |
+| `$pr-merge` merge gate | skill contract | internal | Modify | None | main-agent | merge / cleanup 路径 | merge 前最终 refresh |
+
+### 契约文档（按 Kind 拆分）
+
+None
+
+## 验收标准（Acceptance Criteria）
+
+- Given PR 已存在且 `mergeable_state=behind` When 进入 PR 阶段 Then 下一动作必须是 freshness gate 收敛，而不是继续启动或等待 review-loop / CI / spec-sync。
+
+- Given PR `mergeable == false` 或 `mergeable_state == dirty` When 刚完成 PR 读取 Then 流程必须在高成本收敛动作之前阻断。
+
+- Given PR `mergeable_state == blocked` 且只是 checks 未完成 When 进入 merge 判定 Then 流程继续 checks/review/spec 门禁，不把它误判为 conflict。
+
+- Given checks 已绿但 base 又前进 When merge 前最终 PR refresh 发现 `behind` 或 base/head 事实变化 Then 旧 checks / review proof / spec verdict 作废，流程回到 freshness gate。
+
+- Given merge API 返回 stale-head / expected checks / repository rule violation 类错误 When 重新读取 PR Then 流程必须按最新 PR 事实重新进入 freshness gate 或 checks gate，而不是停留在旧结论上。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- Unit tests: N/A
+- Integration tests: 通过静态回放与文档契约交叉审阅验证
+- E2E tests (if applicable): N/A
+
+### UI / Storybook (if applicable)
+
+- Stories to add/update: N/A
+- Visual regression baseline changes (if any): N/A
+
+### Quality checks
+
+- 文档 diff 自检
+- `git diff --check`
+
+## Visual Evidence
+
+本规格不需要 PR 图片证据。
+
+## 方案概述（Approach, high-level）
+
+- 以共享契约约束顺序，再在具体 skill 里把行为细节补齐。
+- 尽量复用现有 `update_pull_request_branch` 与 `$update-baseline` 路径，不新增新的远端变更机制。
+- 用 `head.sha` / `base.sha` 的失效语义收束“旧绿灯继续沿用”的问题。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：不同 GitHub 仓库规则对 stale-head 错误文案不同，只能按“同类信号”归并处理。
+- 需要决策的问题：None
+- 假设（需主人确认）：`Auto Heal` 仅在已授权 PR 远端变更的 flow 内自动执行。
+
+## 参考（References）
+
+- Session `019ce2c6-a339-77b0-9044-2903ee310ee2`
+- PR #119 回放证据：`2026-03-12T19:19:40Z` 已读到 `mergeable_state=behind`，`2026-03-12T19:30:42Z` merge API 才暴露 stale-branch 问题

package/toolkit/skills/docs/vendor/dot-codex/specs/shared-testbox-heavy-validation/HISTORY.md

@@ -0,0 +1,11 @@
+# Shared host history — superseded
+
+## Lifecycle / Compatibility
+
+Superseded by [Agent VM](../agent-vm/SPEC.md); no current operating entrypoint or fallback remains. [ADR 0025](../../adr/0025-native-incus-agent-vm-lifecycle.md) supersedes [ADR 0015](../../adr/0015-agent-owned-shared-testbox-workspace.md).
+
+## Historical Facts
+
+The former shared host model replaced a centralized dispatcher with Agent-owned persistent directories identified by `CODEX_THREAD_ID`. Git standard selection and rsync populated a source mirror, while ordinary Docker/Compose and native file transfer were chosen by the Agent. Runtime/tool/domain cache paths were shared by convention. Explicit targeted cleanup protected other Agent directories, and global Docker pruning was prohibited.
+
+These are historical facts, not current instructions. Original requirements, helper sources and validation records are recoverable from Git history. The successor uses isolated guests and disposable stopped-disk caches rather than shared host workspaces or cache directories.

package/toolkit/skills/docs/vendor/dot-codex/specs/shared-testbox-heavy-validation/IMPLEMENTATION.md

@@ -0,0 +1,5 @@
+# Shared host implementation — superseded
+
+Lifecycle: superseded by [Agent VM](../agent-vm/SPEC.md). The former two Skills, dedicated helpers and tests are retired. This document provides no current operating entrypoint or validation command.
+
+Historical implementation used direct Agent-owned host workspaces, Git-selected source mirrors and explicitly scoped container cleanup. Its evidence applies only to that retired model and does not establish Agent VM acceptance. The source and tests remain available in Git history before the replacement.

package/toolkit/skills/docs/vendor/dot-codex/specs/shared-testbox-heavy-validation/SPEC.md

@@ -0,0 +1,29 @@
+# Shared host execution — superseded
+
+## Context and Scope
+
+This historical topic is superseded by [Native Incus Agent VM](../agent-vm/SPEC.md). The former shared host Skills and helpers are retired; this document supplies no current operating entrypoint. Historical behavior is recorded in [HISTORY](HISTORY.md), with its original source available in Git history.
+
+## Requirements
+
+### REQ-SHARED-TESTBOX-RETIREMENT
+
+Current Linux execution and infrastructure maintenance MUST follow the successor Agent VM contract and its separate Skills. Historical shared-host directories, helpers and cache conventions MUST NOT be used as active routing or a fallback.
+
+## Verification
+
+### VER-SHARED-TESTBOX-RETIREMENT
+
+- covers: `REQ-SHARED-TESTBOX-RETIREMENT`
+- Method: active-entry migration check and successor Skill index validation.
+- Pass condition: retired Skills and helper code are absent; active routes select the successor while this topic is explicitly marked superseded.
+
+## Related ADRs
+
+None
+
+## References
+
+- [Successor requirements](../agent-vm/SPEC.md)
+- [Retirement status](IMPLEMENTATION.md)
+- [Historical facts](HISTORY.md)