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

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/SPEC.md

@@ -0,0 +1,150 @@
+# PR 生命周期所有权与诊断优先级收敛
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## Related ADRs
+
+- [PR Lifecycle Workflow Ownership](../../adr/0016-pr-lifecycle-workflow-ownership.md)
+
+## 背景 / 问题陈述
+
+- session `019cecc3-be31-75e2-86f1-805dc93bd90d` 暴露出两层问题：
+  - agent 在已有 `Review Policy Gate=success` 且描述明确为 `approval not required` 的前提下，仍把空 reviews 列表推断成“最可能缺 approval”；
+  - 上一条回复已经给出“继续轮询 mergeable”或“直接继续合并流程”两个明确后续分支，用户只说泛化“继续”后，agent 没有续接该未完成分支，而是切回新的弱推断阻塞。
+- 历史 PR 续推栈曾由 `$project-engineering-workflow`、`$flow-continue`、`$pr-create`、`$pr-merge` 共同定义，但 mergeability / wait-state / approval 诊断规则在多个入口中重复铺开，正文过长且 partial-read 场景下容易抓错主线；当前需要把 direct PR 生命周期收拢到 workflow，并保留 Initiative 与视觉证据的专属边界。
+- 仓库里已存在 `docs/specs/pr-freshness-gate/SPEC.md`、`docs/specs/pr-wait-state-closeout/SPEC.md`、`docs/specs/flow-continue-lock-guard/SPEC.md`、`docs/specs/pr-post-open-scope-freeze/SPEC.md` 等多轮补丁，说明问题不再是“缺一条单独规则”，而是需要把共享规则收敛成更短、更稳定的真相源，再让入口 skill 只保留自己的职责。
+
+## 目标 / 非目标
+
+### Goals
+
+- 提炼一份共享 PR 诊断短规约，统一 `mergeable` 优先级、approval 正证据优先级、泛化 `继续` 的 promise-resume 规则，以及 wait-state 的停靠语义。
+- 让 `$project-engineering-workflow` 成为 direct PR 生命周期唯一入口：Step 4-6 读取 role-neutral publication/merge procedure；`$flow-continue` 只负责恢复路由，`$wave-thread-flow` 负责 Initiative role legality，`$ui-visual-evidence` 负责 PR 正文图片 Phase A/B。
+- 用 focused replay checker 把本次事故模式固化为可回放失败样例，并覆盖至少一个 conflict 误诊断负例和两个正例。
+- 保证相关 skill 在 partial-read 场景下，前 100-150 行即可看到本次事故相关的关键禁止项。
+
+### Non-goals
+
+- 不重写整个软件工程流程，也不对 `fast-flow` / `normal-flow` / `local-merge-flow` 做第二轮全量瘦身。
+- 不修改 `gh CLI` 远端控制面、Codex runtime 或官方 session 机制。
+- 不引入新的测试框架或外部依赖。
+
+## 范围（Scope）
+
+### In scope
+
+- 更新本规格及其实现状态，保留 `HISTORY.md` 与 replay 的历史兼容叙述。
+- 在 workflow 下新增 role-neutral PR publication/merge procedure，并保留共享 PR 诊断短规约引用资产。
+- 更新 `$project-engineering-workflow`、`$flow-continue`、`$fast-flow`、`$normal-flow`、`$wave-thread-flow`、`$wave-thread-flow` 与 `$ui-visual-evidence` 的 canonical 路由。
+- 新增 focused replay checker 与 replay fixtures / cases。
+
+### Out of scope
+
+- 修改实现代码仓库的业务逻辑。
+- 将现有所有 flow/prompt 入口统一迁移到新的资产结构。
+- 为 skills 引入复杂 AST/LLM 级自动测试。
+
+## 需求（Requirements）
+
+### MUST
+
+- 共享 PR 诊断短规约必须明确以下优先级：
+  - `mergeable == false` 或 `mergeable_state == dirty`：conflict hard-stop。
+  - `mergeable_state == behind`：先 freshness / branch-update，不得继续消耗 review/CI/spec-sync。
+  - `mergeable_state == blocked`：若无 stale/conflict 事实，仅继续普通 checks/review/spec 门禁。
+  - `PR.head.sha` 或 `PR.base.sha` 变化：旧 checks / proof / spec verdict 失效。
+- 只要存在显式 approval 正证据，例如：
+  - `Review Policy Gate` / status context 明示 `approval not required`
+  - 或明示 `approval satisfied` 则 review approval gate 必须判 clear，禁止再用“reviews 为空”、`review comments=[]` 之类弱信号覆盖。
+- 只有在存在直接负证据，或缺少更强证据且仓库规则明确要求 approval 时，才允许把“缺 approval”报告为 blocker。
+- 若上一条 agent 回复已给出明确下一步分支，用户随后只说泛化“继续 / 推进流程 / 你直接做吧”，则必须优先续接那个未完成分支，不得临时改成新的弱推断阻塞。
+- workflow 的 publication/merge procedure 必须接收标准 operation envelope（角色、repo、精确 base/head、授权、验证与视觉证据事实），只执行通用 PR 操作并返回 live facts；procedure 不授予授权，也不决定 Initiative role legality。
+- `$flow-continue` 必须恢复到 workflow procedure；`$wave-thread-flow` 必须在调用 procedure 前完成 child/checkpoint/parent 的拓扑、精确 SHA 与授权判断；`$ui-visual-evidence` 必须独占 PR body image gate 的 Phase A/B。
+- focused replay checker 至少覆盖：
+  - 真实 session `019cecc3-be31-75e2-86f1-805dc93bd90d`
+  - 一个 `dirty/conflict` 被误报成 approval blocker 的负例
+  - 一个 `blocked + approval not required` 的正例
+  - 一个 `dirty/conflict` 被正确报告为冲突的正例
+
+### SHOULD
+
+- 入口 skill 的顶部可见区域（前 100-150 行）应直接出现“approval 正证据优先于空 reviews”和“generic continue 续接已承诺分支”的禁止项。
+- 改造后，目标 skill 正文应显著缩短，重复说明集中到共享引用资产。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Shared PR diagnosis contract
+
+- 共享短规约只承担四类判断：
+  - mergeability 优先级；
+  - approval 证据优先级；
+  - promise-resume 规则；
+  - 外部门禁等待态与 `下一门禁` 的区分。
+- 共享 workflow 仍是 Step 5 的真相源，但具体 PR 诊断正文不再直接散落在每个入口 skill 中。
+
+### Canonical owners
+
+- `$project-engineering-workflow`
+  - 负责 direct PR 的 Step 4-6 状态转换，并按阶段读取 `pr-publication-procedure.md` 与 `pr-merge-procedure.md`。
+  - publication procedure 负责 PR 创建/复用、managed body、current-head convergence；merge procedure 负责 guarded merge、远端 head 处置、base 对齐与 Step 6 事实。
+- `$flow-continue`
+  - 负责恢复顺序、flow 锁定、promise-resume，并恢复到 workflow procedure；不重新引入旧 PR Skill 路由。
+- `$wave-thread-flow`
+  - 负责 child/checkpoint/parent 的拓扑、角色合法性、精确 SHA、owner approval、integration CI 与 closeout，再向共享 procedure 提供 role envelope。
+- `$ui-visual-evidence`
+  - 负责 Task Evidence Set、managed `## Visual Evidence` 与 PR body image gate Phase A/B；Phase B 在 merge SHA 确认后重新绑定并验证。
+
+### Replay checker
+
+- focused checker 读取 JSONL replay，提取：
+  - mergeability 事实；
+  - approval 正证据；
+  - assistant 已承诺的 merge-path 分支；
+  - generic continue；
+  - assistant 的 approval-blocker 假设。
+- legacy replay 中的旧 Skill 路径只允许作为历史输入被解析；active instructions、架构检查与新 procedure 路由只能使用 canonical owners。
+- 当 replay 命中以下模式时必须报错：
+  - `approval not required` / `approval satisfied` 已出现，后续 assistant 仍把 approval 报成 blocker；
+  - `mergeable_state == dirty` 或 `mergeable == false` 已出现，后续 assistant 仍把 approval 报成 blocker；
+  - assistant 已承诺 merge-path 后续，generic continue 之后却没有续接该分支而改成 approval 弱推断。
+
+## 验收标准（Acceptance Criteria）
+
+- Given session `019cecc3-be31-75e2-86f1-805dc93bd90d` When 跑 focused replay checker Then 必须至少报出 `APPROVAL_EVIDENCE_IGNORED`，且最好同时报出 `PROMISED_MERGE_BRANCH_NOT_RESUMED`。
+
+- Given replay 中已有 `mergeable_state == dirty` When assistant 结论说“最可能缺 approval” Then checker 必须报 `CONFLICT_MISDIAGNOSED_AS_APPROVAL`。
+
+- Given replay 中已有 `approval not required` When assistant 仅报告“blocked 需继续看 mergeability/checks” Then checker 必须通过。
+
+- Given replay 中已有 `mergeable_state == dirty` When assistant 结论直接报告冲突/不可合并 Then checker 必须通过。
+
+- Given workflow / `$flow-continue` / `$wave-thread-flow` / `$ui-visual-evidence` 的顶部片段 When 只读前 100-150 行 Then 应能看到共享短规约引用、approval 正证据优先级、以及 generic continue 续接 promise 的关键约束。
+
+## 非功能性验收 / 质量门槛（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/instruction_architecture_check.py --repo-root .`
+- `python3 bin/pr_body_image_contract_check.py`
+- `git diff --check`
+
+### Quality checks
+
+- 目标 skill 的前 150 行人工 spot-check
+- 重复规则 grep：确认 approval / mergeability 解释已集中到共享短规约
+
+## 风险 / 假设
+
+- 风险：若未来新增新的 PR 入口 skill/prompt，但不引用这份共享短规约，可能重新出现 partial-read 误诊断。
+- 风险：skill 瘦身若删掉过多 merge-path 特例，可能损失已有边界条件；因此仅抽走共用规则，入口 skill 独有例外保留。
+- 假设：以 focused replay checker 覆盖这次事故模式，足以替代大而全的 skill 自动化测试框架。
+
+## 参考（References）
+
+- Session `019cecc3-be31-75e2-86f1-805dc93bd90d`
+- `sessions/2026/03/14/rollout-2026-03-14T22-32-57-019cecc3-be31-75e2-86f1-805dc93bd90d.jsonl`
+- `docs/specs/pr-freshness-gate/SPEC.md`
+- `docs/specs/pr-wait-state-closeout/SPEC.md`
+- `docs/specs/flow-continue-lock-guard/SPEC.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/cases.txt

@@ -0,0 +1,12 @@
+fail negative-session-approval-evidence-ignored.jsonl APPROVAL_EVIDENCE_IGNORED
+fail negative-dirty-misread-as-approval.jsonl CONFLICT_MISDIAGNOSED_AS_APPROVAL
+fail negative-promised-merge-branch-skipped.jsonl PROMISED_MERGE_BRANCH_NOT_RESUMED
+pass positive-blocked-with-approval-evidence.jsonl -
+pass positive-dirty-conflict-reported.jsonl -
+fail negative-draft-convergence-before-owner-confirmation.jsonl DRAFT_PR_CONVERGENCE_BEFORE_VISUAL_FEEDBACK
+fail negative-draft-direct-gh-convergence-before-owner-confirmation.jsonl DRAFT_PR_CONVERGENCE_BEFORE_VISUAL_FEEDBACK
+fail negative-draft-render-surface-change-after-confirmation.jsonl DRAFT_PR_CONVERGENCE_BEFORE_VISUAL_FEEDBACK
+fail negative-draft-mixed-visual-status-cannot-clear-confirmation.jsonl DRAFT_PR_CONVERGENCE_BEFORE_VISUAL_RESPONSE
+fail negative-draft-bootstrap-and-convergence-same-event.jsonl DRAFT_PR_CONVERGENCE_BEFORE_VISUAL_FEEDBACK
+pass positive-draft-confirmation-before-convergence.jsonl -
+pass positive-draft-unchanged-feedback-before-convergence.jsonl -

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/negative-dirty-misread-as-approval.jsonl

@@ -0,0 +1,2 @@
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_pr","output":"[{\"type\":\"text\",\"text\":\"{\\\"number\\\":130,\\\"mergeable_state\\\":\\\"dirty\\\"}\"}]"}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"关键 checks 都绿了，所以最可能剩下的是 approval 门禁。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/negative-draft-bootstrap-and-convergence-same-event.jsonl

@@ -0,0 +1 @@
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"MODE=draft-bootstrap 创建 feedback-only Draft PR。视觉比较=需确认，已展示当前截图与差异热图。这些截图准确反映了本次改动吗？现在执行 bind-pr 并启动正式 review。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/negative-draft-convergence-before-owner-confirmation.jsonl

@@ -0,0 +1,2 @@
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"本地 UI 没有可用证据源；使用 MODE=draft-bootstrap 创建 feedback-only Draft PR，并等待主人确认。"}]}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"现在执行 bind-pr 并启动正式 review。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/negative-draft-direct-gh-convergence-before-owner-confirmation.jsonl

@@ -0,0 +1,2 @@
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"本地 UI 没有可用证据源；使用 MODE=draft-bootstrap 创建 feedback-only Draft PR，并等待主人确认。"}]}}
+{"type":"response_item","payload":{"type":"function_call","name":"exec_command","arguments":"{\"cmd\":\"gh pr checks 84 && gh pr review 84 --approve && gh pr merge 84 --merge\"}"}}

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/negative-draft-mixed-visual-status-cannot-clear-confirmation.jsonl

@@ -0,0 +1,4 @@
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"MODE=draft-bootstrap 创建 feedback-only Draft PR。"}]}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"视觉比较=需确认，已展示当前截图与差异热图。这些截图准确反映了本次改动吗？"}]}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"视觉比较=一致；但远端反馈仍视觉比较=需确认，等待主人确认截图。"}]}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"现在执行 bind-pr 并启动正式 review。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/negative-draft-render-surface-change-after-confirmation.jsonl

@@ -0,0 +1,5 @@
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"MODE=draft-bootstrap；反馈 Draft 已创建。"}]}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"远端反馈视觉比较=需确认，已展示当前截图与差异热图。这些截图准确反映了当前改动吗？"}]}}
+{"type":"response_item","payload":{"type":"message","role":"user","content":[{"type":"input_text","text":"可以，没问题。"}]}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"渲染面已变化，需要重新比较。"}]}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"现在执行 bind-pr 并启动正式 review。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/negative-promised-merge-branch-skipped.jsonl

@@ -0,0 +1,4 @@
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"如果你要，我下一步可以继续做其中一件：\n1. 继续轮询到 `mergeable_state` 刷新正常\n2. 直接继续处理合并流程"}]}}
+{"type":"response_item","payload":{"type":"message","role":"user","content":[{"type":"input_text","text":"继续"}]}}
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_status","output":"[{\"type\":\"text\",\"text\":\"{\\\"state\\\":\\\"success\\\",\\\"statuses\\\":[{\\\"context\\\":\\\"Review Policy Gate\\\",\\\"description\\\":\\\"Author @IvanLi-CN has admin permission; approval not required.\\\"}]}\"}]"}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"checks 还是绿的，所以最可能剩下的是 review approval 门禁。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/negative-session-approval-evidence-ignored.jsonl

@@ -0,0 +1,2 @@
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"Review Policy Gate says approval not required for this PR."}]}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"The most likely blocker is still review approval, so we should wait for approval before merge."}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/positive-blocked-with-approval-evidence.jsonl

@@ -0,0 +1,3 @@
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_status","output":"[{\"type\":\"text\",\"text\":\"{\\\"state\\\":\\\"success\\\",\\\"statuses\\\":[{\\\"context\\\":\\\"Review Policy Gate\\\",\\\"description\\\":\\\"Approval satisfied by @owner (admin).\\\"}]}\"}]"}}
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_pr","output":"[{\"type\":\"text\",\"text\":\"{\\\"number\\\":130,\\\"mergeable_state\\\":\\\"blocked\\\"}\"}]"}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"approval 已 clear；当前先继续处理 mergeability 和剩余 checks，不把它当成缺审批。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/positive-dirty-conflict-reported.jsonl

@@ -0,0 +1,2 @@
+{"type":"response_item","payload":{"type":"function_call_output","call_id":"call_pr","output":"[{\"type\":\"text\",\"text\":\"{\\\"number\\\":130,\\\"mergeable_state\\\":\\\"dirty\\\"}\"}]"}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"PR 目前是 merge conflict，先按冲突阻断处理，不继续猜 review approval。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/positive-draft-confirmation-before-convergence.jsonl

@@ -0,0 +1,4 @@
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"本地 UI 没有可用证据源；使用 MODE=draft-bootstrap 创建 feedback-only Draft PR，并等待主人确认。"}]}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"远端反馈已回传。视觉比较=需确认，已展示当前截图与差异热图。这些截图准确反映了本次改动吗？"}]}}
+{"type":"response_item","payload":{"type":"message","role":"user","content":[{"type":"input_text","text":"这些截图准确反映了当前改动。"}]}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"当前候选保持匹配；现在执行 bind-pr 并启动正式 review。"}]}}

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-skill-diagnosis-thinning/replay/positive-draft-unchanged-feedback-before-convergence.jsonl

@@ -0,0 +1,3 @@
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"本地 UI 没有可用证据源；使用 MODE=draft-bootstrap 创建 feedback-only Draft PR。"}]}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"远端反馈已回传。视觉比较=一致，与上一版视觉一致。"}]}}
+{"type":"response_item","payload":{"type":"message","role":"assistant","content":[{"type":"output_text","text":"当前候选保持匹配；现在执行 bind-pr 并启动正式 review。"}]}}

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

@@ -0,0 +1,18 @@
+# PR wait-state closeout 演进历史（#hd86w）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `dc1ffc7` fix(flow): prevent early stop in PR wait states
+- `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: `#hd86w`.

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

@@ -0,0 +1,57 @@
+# PR wait-state closeout 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 防止纯等待态被误当成可收尾停靠点
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-13
+- Legacy last-tracked: 2026-03-13
+- Current lifecycle: active
+- Catalog note: 防止纯等待态被误当成可收尾停靠点
+
+## Delivery Milestones
+
+- [x] M1: 建立 PR wait-state closeout 规格并登记索引
+- [x] M2: 收紧共享 workflow 与恢复语义
+- [x] M3: 收紧 PR skills 与 prompts 的 stop/output 契约
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/flow-continue/SKILL.md`
+- `skills/fast-flow/SKILL.md`
+- `skills/project-engineering-workflow/references/pr-publication-procedure.md`
+- `skills/project-engineering-workflow/references/pr-merge-procedure.md`
+- `prompts/advance-flow.md`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `dc1ffc7` fix(flow): prevent early stop in PR wait states
+- `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-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`、`workflow PR publication procedure`、`workflow PR merge procedure` 与 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`、`workflow PR publication procedure`、`workflow PR merge procedure` 的提前停机约束。
+- 更新 `/prompts:advance-flow` 与 workflow PR merge procedure 的顶部 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/q3wyh-cvm-imagegen-skill/HISTORY.md

@@ -0,0 +1,20 @@
+# CVM imagegen fallback skill 演进历史（#q3wyh）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- 2026-06-27: 新增 `cvm-imagegen` 作为独立 skill，而不是修改系统 `.system/imagegen`。
+- 2026-06-27: 采用薄包装 wrapper，复用系统 fallback 的参数解析与业务逻辑，只替换 `CVM_API_KEY` 校验和 OpenAI client 构造。
+- 2026-06-27: 将 skills 索引同步为可发现入口，避免该能力只存在于私有约定中。
+
+## Key Reasons / Replacements
+
+- 系统 skill 不适合作为本仓长期策略承载层，直接修改容易被更新覆盖。
+- 当前需求是自定义 BaseURL fallback，而不是重写整套 image workflow。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#q3wyh`.

package/toolkit/skills/docs/vendor/dot-codex/specs/q3wyh-cvm-imagegen-skill/IMPLEMENTATION.md

@@ -0,0 +1,33 @@
+# CVM imagegen fallback skill 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 显式 CLI fallback，固定走 `CVM_API_KEY` 与 `https://vibe-code.ivanli.cc/v1`
+
+## Coverage / rollout summary
+
+- 已新增 `skills/cvm-imagegen/` 独立 skill 目录。
+- 已新增 wrapper CLI，并复用系统 imagegen fallback 的命令接口。
+- 已补最小参考文档集合：CLI 用法与 API 参数说明。
+- 已更新 `skills/README.md`，让新 skill 可发现。
+
+## Remaining Gaps
+
+- 若系统 imagegen fallback 将来重构内部 helper 名称，wrapper 需要同步维护 patch 点。
+
+## Related Changes
+
+- `skills/cvm-imagegen/SKILL.md`
+- `skills/cvm-imagegen/scripts/image_gen.py`
+- `skills/cvm-imagegen/references/cli.md`
+- `skills/cvm-imagegen/references/image-api.md`
+- `skills/README.md`
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/q3wyh-cvm-imagegen-skill/SPEC.md

@@ -0,0 +1,151 @@
+# CVM imagegen fallback skill
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 系统 `/Users/ivan/.codex/skills/.system/imagegen/SKILL.md` 的 fallback CLI 路径默认围绕 `OPENAI_API_KEY` 与官方 OpenAI endpoint 组织，不适合直接用于当前仓库已有的 CVM OpenAI-compatible provider。
+- 当前仓库已经有 `CVM_API_KEY` 与 `https://vibe-code.ivanli.cc/v1` 的 provider 事实，但缺少一个显式、本地、可维护的 image fallback skill 入口。
+- 直接修改系统 `.system/imagegen` 会让后续更新难以维护，也违背“系统 skill 不作为本仓长期策略承载层”的规则。
+
+## 目标 / 非目标
+
+### Goals
+
+- 新增一个独立的 `cvm-imagegen` skill，作为显式调用的 CLI fallback 能力。
+- 固定该 skill 的 live client 配置为 `CVM_API_KEY` 与 `https://vibe-code.ivanli.cc/v1`。
+- 复用官方 fallback CLI 的接口心智，保留 `generate`、`edit`、`generate-batch` 与核心参数名。
+- 明确文档边界：普通生图仍优先用 built-in `image_gen`，只有显式需要自定义 BaseURL 的 CLI 路径才使用本 skill。
+
+### Non-goals
+
+- 不修改系统 `imagegen` skill 或其脚本。
+- 不把 `cvm-imagegen` 做成 built-in `image_gen` 的自动替身。
+- 不重新设计图片 prompt taxonomy、透明背景策略或 OpenAI Images API 参数契约。
+- 不改动仓库全局 provider 配置或 remote/model routing。
+
+## 范围（Scope）
+
+### In scope
+
+- `skills/cvm-imagegen/SKILL.md`
+- `skills/cvm-imagegen/scripts/image_gen.py`
+- `skills/cvm-imagegen/references/cli.md`
+- `skills/cvm-imagegen/references/image-api.md`
+- `skills/README.md` 的新 skill 发现入口
+
+### Out of scope
+
+- `/Users/ivan/.codex/skills/.system/imagegen/**`
+- built-in `image_gen` tool 的行为
+- plugin marketplace 暴露或安装流
+- 额外的 prompt/reference 套件复制
+
+## 需求（Requirements）
+
+### MUST
+
+- `cvm-imagegen` 必须是独立 skill，而不是对系统 `imagegen` 的原地覆盖。
+- 该 skill 必须只承载显式 CLI fallback，不得声称会自动接管 built-in `image_gen` 路由。
+- live API 调用必须使用 `CVM_API_KEY` 和 `https://vibe-code.ivanli.cc/v1`。
+- CLI 必须支持 `generate`、`edit`、`generate-batch` 三个子命令。
+- CLI 必须尽量复用官方 fallback 的参数形状、输出路径约定和 dry-run 语义。
+- `--dry-run` 必须在缺少 `CVM_API_KEY` 时仍可工作。
+- 非 dry-run 执行在缺少 `CVM_API_KEY` 时必须给出准确的 CVM 专属报错。
+- 文档必须明确 `OPENAI_API_KEY` 与 `OPENAI_BASE_URL` 不属于该 wrapper 的运行时契约。
+- `skills/README.md` 必须出现 `cvm-imagegen` 的可发现条目。
+
+### SHOULD
+
+- 实现应采用薄包装，而不是复制整份系统 fallback 逻辑。
+- 参考文档应聚焦 CLI 用法与 API 参数，不重复无关的 built-in 流程说明。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- `cvm-imagegen` 通过本仓 `skills/cvm-imagegen/scripts/image_gen.py` 作为唯一 CLI 入口。
+- wrapper 在运行时加载系统 imagegen fallback 脚本，并只覆写：
+  - API key 检查
+  - 同步 OpenAI client 构造
+  - 异步 OpenAI client 构造
+- 其余参数解析、payload 构造、文件输出、batch 并发、prompt augmentation 与透明背景相关校验沿用系统 fallback 逻辑。
+- `generate`、`edit`、`generate-batch` 的命令形状和核心 flags 保持兼容。
+
+### Edge cases / errors
+
+- 当 `CODEX_HOME` 未设置时，wrapper 默认回退到 `~/.codex` 查找系统 imagegen fallback 脚本。
+- 当系统 fallback 脚本不存在或无法加载时，wrapper 必须直接报错并退出。
+- 当 `CVM_API_KEY` 缺失且不是 dry-run 时，wrapper 必须阻止 live API 调用。
+- 当 `CVM_API_KEY` 缺失但处于 dry-run 时，wrapper 只给 warning，不中断 dry-run。
+
+## 接口契约（Interfaces & Contracts）
+
+### 接口清单（Inventory）
+
+| 接口（Name） | 类型（Kind） | 范围（Scope） | 变更（Change） | 契约文档（Contract Doc） | 负责人（Owner） | 使用方（Consumers） | 备注（Notes） |
+| - | - | - | - | - | - | - | - |
+| `skills/cvm-imagegen` | skill | internal | New | `skills/cvm-imagegen/SKILL.md` | codex-global | owner / agents | 显式 CLI fallback 入口 |
+| `skills/cvm-imagegen/scripts/image_gen.py` | CLI wrapper | internal | New | `skills/cvm-imagegen/references/cli.md` | codex-global | owner / agents | 复用系统 fallback 逻辑并固定 CVM client |
+| `CVM_API_KEY` | environment variable | internal | New | `skills/cvm-imagegen/SKILL.md` | runtime env | wrapper CLI | live API 调用凭证 |
+
+### 契约文档（按 Kind 拆分）
+
+- `skills/cvm-imagegen/SKILL.md`
+- `skills/cvm-imagegen/references/cli.md`
+- `skills/cvm-imagegen/references/image-api.md`
+
+## 验收标准（Acceptance Criteria）
+
+- Given owner 明确调用 `$cvm-imagegen` When 查看 `SKILL.md` Then 可以明确看到它是独立 skill、仅用于显式 CLI fallback、且固定使用 `CVM_API_KEY` 与 `https://vibe-code.ivanli.cc/v1`
+
+- Given 执行 `python3 skills/cvm-imagegen/scripts/image_gen.py generate --dry-run ...` When 环境中缺少 `CVM_API_KEY` Then 命令仍然可以完成 dry-run 并打印 payload
+
+- Given 执行非 dry-run 的 live command When 环境中缺少 `CVM_API_KEY` Then 命令必须以 CVM-specific 报错失败，而不是要求 `OPENAI_API_KEY`
+
+- Given 执行 wrapper CLI When 使用 `generate`、`edit`、`generate-batch` Then 三个子命令都能正确解析并沿用官方 fallback 的核心 flags
+
+- Given 查看 `skills/README.md` When 搜索 `cvm-imagegen` Then 可以发现该 skill，且描述与“显式自定义 BaseURL image fallback”一致
+
+## 验收清单（Acceptance checklist）
+
+- [x] 独立 skill 路径已建立。
+- [x] CLI wrapper 已固定 `CVM_API_KEY` 与 `https://vibe-code.ivanli.cc/v1`。
+- [x] dry-run 与缺失 key 的运行时边界已明确。
+- [x] skills 索引已补充新入口。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `python3 /Users/ivan/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/cvm-imagegen`
+- `python3 skills/cvm-imagegen/scripts/image_gen.py --help`
+- `python3 skills/cvm-imagegen/scripts/image_gen.py generate --prompt "Test" --out /tmp/cvm-imagegen-test.png --dry-run`
+- `python3 skills/cvm-imagegen/scripts/image_gen.py edit --image /tmp/cvm-imagegen-test.png --prompt "Test" --out /tmp/cvm-imagegen-edit.png --dry-run`
+- `python3 skills/cvm-imagegen/scripts/image_gen.py generate-batch --input /tmp/cvm-imagegen-prompts.jsonl --out-dir /tmp/cvm-imagegen-batch --dry-run`
+- `env -u CVM_API_KEY python3 skills/cvm-imagegen/scripts/image_gen.py generate --prompt "Test" --out /tmp/cvm-imagegen-live.png`
+
+### Quality checks
+
+- `git diff --check`
+- `rg -n "CVM_API_KEY|vibe-code.ivanli.cc/v1|generate-batch|OPENAI_API_KEY" skills/cvm-imagegen`
+
+## Visual Evidence
+
+None
+
+## Related PRs
+
+- None
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：系统 imagegen fallback 若未来重命名内部 helper，wrapper 需要同步调整 monkeypatch 点位。
+- 风险：该 skill 依赖系统 fallback 脚本仍存在于 `CODEX_HOME/skills/.system/imagegen/scripts/image_gen.py`。
+- 假设：`https://vibe-code.ivanli.cc/v1` 对外保持 OpenAI Images API 兼容。
+
+## 参考（References）
+
+- `/Users/ivan/.codex/skills/.system/imagegen/SKILL.md`
+- `/Users/ivan/.codex/skills/.system/imagegen/scripts/image_gen.py`
+- `skills/README.md`