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

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

@@ -0,0 +1,60 @@
+# PR 续推 skill 瘦身与诊断优先级收敛 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 收拢 approval/mergeability/continue 诊断优先级，新增 focused replay checker 并瘦身 PR 续推 skill
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-15
+- Legacy last-tracked: 2026-03-15
+- Current lifecycle: active
+- Catalog note: 收拢 approval/mergeability/continue 诊断优先级，新增 focused replay checker 并瘦身 PR 续推 skill
+
+## Delivery Milestones
+
+- [x] M1: 建立规格与共享 PR 诊断短规约
+- [x] M2: 压缩共享 workflow 与 3 个入口 skill
+- [x] M3: 新增 focused replay checker 与 fixtures
+- [x] M4: 跑本地检查并收口到 merge-ready（local）
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `docs/specs/pr-skill-diagnosis-thinning/SPEC.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/project-engineering-workflow/references/pr-diagnosis-short-contract.md`
+- `skills/flow-continue/SKILL.md`
+- `skills/pr-create/SKILL.md`
+- `skills/pr-merge/SKILL.md`
+- `bin/pr_skill_replay_check.py`
+- `docs/specs/pr-skill-diagnosis-thinning/replay/*`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `97e541d` fix(skill): tighten pr diagnosis routing
+- `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/4zciv-pr-skill-diagnosis-thinning/SPEC.md

@@ -0,0 +1,142 @@
+# PR 续推 skill 瘦身与诊断优先级收敛
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.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 诊断规则在多个 skill 中重复铺开，正文过长且 partial-read 场景下容易抓错主线。
+- 仓库里已存在 `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 的停靠语义。
+- 将 `$flow-continue`、`$pr-create`、`$pr-merge` 压缩成薄入口：只保留恢复/建 PR/merge 的职责、特殊例外和输出契约，不再重复整段 PR 诊断规则。
+- 用 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
+
+- 更新 `docs/specs/README.md` 与本规格。
+- 新增共享 PR 诊断短规约引用资产。
+- 更新 `$project-engineering-workflow`、`$flow-continue`、`$pr-create`、`$pr-merge`。
+- 新增 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 回复已给出明确下一步分支，用户随后只说泛化“继续 / 推进流程 / 你直接做吧”，则必须优先续接那个未完成分支，不得临时改成新的弱推断阻塞。
+- `$flow-continue`、`$pr-create`、`$pr-merge` 都必须引用同一份共享短规约，而不是各自重写一遍。
+- 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 中。
+
+### Thin entry skills
+
+- `$flow-continue`
+  - 负责恢复顺序、flow 锁定、promise-resume、路由优先级。
+  - 进入 PR 阶段后，只根据共享短规约决定去 `$pr-create` 或 `$pr-merge`，不再重复解释 approval/blocked/dirty 语义。
+- `$pr-create`
+  - 负责 PR 创建/复用、首轮 freshness gate、CI/review/spec 并行编排、wait-budget。
+  - 仅保留“本 skill 的特殊例外”，例如本地 ahead 未 push 时允许先 push 再重读 mergeability。
+- `$pr-merge`
+  - 负责 merge 前 final refresh、behind/conflict 分流、fresh merge-proof gate、merge 与 cleanup。
+  - 仅保留 merge-path 独有 guardrail；approval 解释统一引用共享短规约。
+
+### Replay checker
+
+- focused checker 读取 JSONL replay，提取：
+  - mergeability 事实；
+  - approval 正证据；
+  - assistant 已承诺的 merge-path 分支；
+  - generic continue；
+  - assistant 的 approval-blocker 假设。
+- 当 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 `$flow-continue` / `$pr-create` / `$pr-merge` 的顶部片段 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`
+- `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/4zciv-pr-skill-diagnosis-thinning/replay/cases.txt

@@ -0,0 +1,5 @@
+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 -

package/toolkit/skills/docs/vendor/dot-codex/specs/4zciv-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/4zciv-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/4zciv-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/4zciv-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/4zciv-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/5dvcj-dev-plan-default-fast-track-auto-lock/HISTORY.md

@@ -0,0 +1,16 @@
+# Dev plan default fast-track auto-lock 演进历史（#5dvcj）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- 新建 `#5dvcj`，把显式 `$dev-plan` 的默认 auto-lock 独立成新 topic spec，避免继续挤在 `#k4n8p` 的 interactive 选项指导或 `#yr954` 的恢复优先级主题里。
+- 将主人习惯说的 `pr-ready` 映射为本 repo 共享 stop-condition 语义里的 `merge-ready / Step 5C Ready`，而不是本地 `Step 4 Ready`。
+- 保留 `yr954` 的 locked-flow precedence，不让这次 default auto-lock 反向放宽 generic `继续 / 合并 / 收尾` 的恢复边界。
+- 把 default auto-lock 的 blocker 收敛到四类：互斥 flow 信号、与 `flow_type` / routing 相关但不构成锁定的 wording、无关 interactive blocker、以及纯 generic `继续` 且无可恢复上下文；避免为了 happy path 继续强迫主人点 flow 选择。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#5dvcj`.

package/toolkit/skills/docs/vendor/dot-codex/specs/5dvcj-dev-plan-default-fast-track-auto-lock/IMPLEMENTATION.md

@@ -0,0 +1,37 @@
+# Dev plan default fast-track auto-lock 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 显式 `$dev-plan` 路径现已把无显式 flow 的 happy path 默认锁到 `fast-track + merge-ready`
+
+## Coverage / rollout summary
+
+- `AGENTS.md` 已把 built-in Plan Mode 默认路径改回官方原味，同时把 repo 的缺省 flow 规则收敛到显式 `$dev-plan` 合同。
+- `skills/dev-plan/SKILL.md` 已保留 default auto-lock 合同、`flow_source=default_fast_track` 语义，以及 direct flow-skill / standalone flow token 覆盖优先级，并明确它只在显式 `$dev-plan` 时生效。
+- `skills/project-engineering-workflow/SKILL.md` 已明确：显式 `$dev-plan` 计划中的 `Flow Decision.flow_source=default_fast_track` 与其他 locked flow 证据等价，后续恢复不得把它当成未锁定。
+- `bin/plan_contract_check.sh` 已接受 `default_fast_track` 作为合法 flow 锁定来源，并新增 default-auto-lock 场景守卫与 direct flow-skill / standalone token 锁定解析。
+- replay fixtures / `CASES.txt` 已补齐默认 auto-lock 正例、direct flow-skill 覆盖正例、以及“互斥信号 / 与 `flow_type` 或 routing 相关但不构成锁定的 wording”都不得静默默认的反例。
+- `docs/specs/dev-plan-flow-lock-options/SPEC.md` 与 `docs/specs/flow-continue-lock-guard/SPEC.md` 已做最小交叉引用清理：interactive flow 问题的 owner 仍留在 `docs/specs/dev-plan-flow-lock-options/SPEC.md`，locked-flow 恢复优先级仍留在 `docs/specs/flow-continue-lock-guard/SPEC.md`。
+
+## Remaining Gaps
+
+- None currently tracked after local contract validation.
+
+## Related Changes
+
+- `docs/specs/README.md`
+- `docs/specs/dev-plan-default-fast-track-auto-lock/SPEC.md`
+- `AGENTS.md`
+- `skills/dev-plan/SKILL.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `bin/plan_contract_check.sh`
+- `skills/dev-plan/references/replay-cases/*`
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/5dvcj-dev-plan-default-fast-track-auto-lock/SPEC.md

@@ -0,0 +1,58 @@
+# Dev plan default fast-track auto-lock
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 目前显式 `$dev-plan` 路径在 `flow_type` 未明确时，仍把 `request_user_input(flow_type)` 当成 happy path 的硬前置门，导致自定义 Plan Mode 经常为了同一个默认选择反复弹一次 flow 选择。
+- 主人的实际使用模式已经稳定：当主人明确要求仓库自定义 workflow-aligned 计划时，绝大多数无显式 flow 指令的请求，都希望直接走 `fast-track`，并停在 latest PR 可立即合并的 `merge-ready / Step 5C Ready`。
+- 现有相邻 topic spec 只覆盖了局部边界：
+  - `docs/specs/dev-plan-flow-lock-options/SPEC.md` 只负责“interactive flow 锁定问题的选项指导”，不 owner 默认无信号路径；
+  - `docs/specs/flow-continue-lock-guard/SPEC.md` 只负责“已锁定 flow 的恢复优先级”，不 owner Plan Mode 首次进入时的默认选路。
+- 因此这次需要一个新的 owner spec，把“显式 `$dev-plan` 时默认 auto-lock 到 `fast-track + merge-ready`”写成独立契约，同时明确它不会削弱 `docs/specs/flow-continue-lock-guard/SPEC.md` 的锁定优先级守卫，也不 owner 未显式引用 `$dev-plan` 时的官方原味 built-in Plan Mode。
+
+## 核心合同
+
+- 显式引用 `$dev-plan` 时，自定义 plan 路径的 flow 解析顺序固定为：显式 `flow_type:` -> 显式切 flow 文本 -> standalone flow token -> direct flow-skill 引用 -> `default_fast_track` -> `request_user_input(flow_type)`。
+- `default_fast_track` 只允许用于新的规划请求，且当前请求同时满足：无显式 flow、无互斥信号、无与 `flow_type` / routing 相关但不构成锁定的 wording、无先前 non-`flow_type` interactive blocker。
+- 该显式路径的默认 `Flow Decision` 必须是 `flow_type=fast-track`、`flow_source=default_fast_track`、`lock_status=locked`，默认 stop condition 是 `merge-ready / Step 5C Ready`。
+- 显式 `implement-only` / `normal` / `local-merge`、显式切 flow 文本、standalone flow token、以及 direct flow-skill 引用都必须覆盖默认值。
+- 至少以下 direct flow-skill 引用必须被视为合法锁定证据：`$implement-only-flow`、`$normal-flow`、`$fast-flow`、`$local-merge-flow`。
+- 多个互斥 flow 信号、仅出现与 `flow_type` / routing 相关但不构成锁定的 wording、或无可恢复上下文的 generic `继续 / continue`，都必须触发 `request_user_input(flow_type)`，不得静默落默认值。
+- 显式 `$dev-plan` 输出中的 `Flow Decision.flow_source=default_fast_track` 一旦进入 `<proposed_plan>`，后续恢复/继续语义必须把它视为合法 locked-flow 证据；这条规则不得削弱 `docs/specs/flow-continue-lock-guard/SPEC.md` 的锁定优先级守卫。
+- checker / replay / skill 文案必须与本合同保持一致。
+
+## 非目标
+
+- 不修改 `fast-track`、`normal`、`local-merge`、`implement-only` 的业务执行语义。
+- 不把默认 auto-lock 扩展成 generic continuation 的新入口。
+- 不改变 `docs/specs/flow-continue-lock-guard/SPEC.md` 已有的“已锁定 session 不得被热更新文案追溯改写”规则。
+- 不接管未显式引用 `$dev-plan` 时的官方原味 built-in Plan Mode 默认行为。
+
+## 验收标准（Acceptance Criteria）
+
+- Given 用户在 built-in Plan Mode 中显式引用 `$dev-plan`，且请求未显式指定 flow，也没有冲突或无关 interactive blocker When assistant 直接输出 `<proposed_plan>` Then `Flow Decision` 必须是 `flow_type=fast-track`、`flow_source=default_fast_track`、`lock_status=locked`，且默认 stop condition 为 `merge-ready / Step 5C Ready`。
+
+- Given 用户在显式 `$dev-plan` 请求里直接引用 `$local-merge-flow` When assistant 输出 `<proposed_plan>` Then `Flow Decision.flow_type` 必须是 `local-merge`，而不是默认 `fast-track`。
+
+- Given 同一条显式 `$dev-plan` 用户请求里同时出现 `normal` 与 `$fast-flow` 这类互斥 flow 信号 When assistant 试图规划 Then 它必须继续发起 `request_user_input(flow_type)`，而不是静默落 `default_fast_track`。
+
+- Given flow 在显式 `$dev-plan` 路径中以 `flow_source=default_fast_track` 锁定 When 后续 turn 只说 generic `继续 / 合并 / 收尾` Then 共享恢复语义必须把它当成已锁定 `fast-track` session 处理，不得因为“它不是显式提问锁的”而判成未锁定。
+
+## 风险 / 假设
+
+- 风险：如果 default auto-lock 的 blocker 识别过宽，会把正常请求重新打回追问；若识别过窄，则会在歧义请求里静默猜 flow。
+- 假设：主人当前说的 `pr-ready` 在本 repo 共享术语里应映射到 `merge-ready / Step 5C Ready`，而不是 `Step 4 Ready`。
+- 假设：default auto-lock 仅适用于显式 `$dev-plan` 的首次规划入口，不自动推广到 `flow-continue` 的 generic continuation。
+
+## Testing
+
+- `bash bin/plan_contract_check.sh --cases skills/dev-plan/references/replay-cases/CASES.txt`
+- `git diff --check`
+
+## 参考（References）
+
+- `docs/specs/dev-plan-flow-lock-options/SPEC.md`
+- `docs/specs/flow-continue-lock-guard/SPEC.md`
+- `skills/dev-plan/SKILL.md`
+- `bin/plan_contract_check.sh`

package/toolkit/skills/docs/vendor/dot-codex/specs/5fsxh-viewport-safe-browser-evidence/HISTORY.md

@@ -0,0 +1,19 @@
+# Viewport-safe browser evidence capture 演进历史（#5fsxh）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `9886a7f` docs(skills): enforce viewport-safe browser evidence capture
+- `b39a914` docs(specs): adopt topic-level spec model
+- 移动端验收在缺少主人、项目、spec 或稳定来源尺寸时采用 `393x852` CSS px，确保跨项目证据可比较；显式尺寸始终优先，避免默认值覆盖项目真实设备策略。
+
+## Legacy Change Log
+
+- 2026-05-29: 将 `ui_demo` 纳入 viewport-safe 浏览器证据契约：优先使用 demo 自身稳定场景并记录 `viewport_strategy=ui-demo-source`，缺少 source-managed viewport 时再走 `devtools-emulate`。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#5fsxh`.

package/toolkit/skills/docs/vendor/dot-codex/specs/5fsxh-viewport-safe-browser-evidence/IMPLEMENTATION.md

@@ -0,0 +1,72 @@
+# Viewport-safe browser evidence capture 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 统一浏览器证据的非改窗优先截图契约，并为未指定尺寸的移动端验收提供 `393x852` CSS px 默认 viewport
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Current lifecycle: active
+- Catalog note: 统一浏览器证据的非改窗优先截图契约，加入 `ui_demo` source-managed 场景优先，保留 resize 仅作可恢复兜底
+
+## Delivery Milestones
+
+- [x] M1: 新建 `docs/specs/viewport-safe-browser-evidence/SPEC.md` 规格并登记到 `docs/specs/README.md`
+- [x] M2: 更新 4 个主 skill 的 viewport-safe 浏览器证据契约
+- [x] M3: 同步相关 agent metadata / skills 索引并完成本地校验
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`: 新增 `docs/specs/viewport-safe-browser-evidence/SPEC.md` 索引行
+- `skills/storybook-screenshots/SKILL.md`: 新增 Storybook viewport-safe 截图契约与 metadata，并为直接移动端截图调用继承 `393x852` CSS px fallback
+- `AGENTS.md` 与 evidence skills：新增通用浏览器 viewport-safe 截图梯度与 resize fallback 约束
+- `skills/ui-visual-evidence/SKILL.md`: 统一 Storybook、`ui_demo` 与 mock 浏览器证据的 source sizing ladder；未声明移动端尺寸时使用 `393x852` CSS px，并保持主人、项目、spec 与来源 surface 的显式覆盖优先级
+- `skills/storybook-stories/SKILL.md`: 增加响应式 Storybook 入口前置要求，并在缺少显式尺寸时把 `393x852` CSS px 绑定到选定证据 surface
+- `skills/storybook-screenshots/agents/openai.yaml`: 刷新默认 prompt，并保持显式 viewport 优先于移动端 fallback
+- `skills/ui-visual-evidence/agents/openai.yaml`: 刷新默认 prompt，并保持 owner、project、spec、Storybook/demo source 的完整 viewport 优先级
+- `skills/storybook-stories/agents/openai.yaml`: 刷新默认 prompt，并传播移动端 viewport 优先级与 fallback
+- `skills/README.md`: 刷新技能索引简介，并保留 owner 锁定来源对 Storybook fallback 的约束
+
+### Plan assets
+
+- Directory: `docs/specs/viewport-safe-browser-evidence/assets/`
+- In-plan references: None
+- Visual evidence source: not used for this policy-only change
+
+### Asset promotion
+
+None
+
+### Visual evidence
+
+- Disposition: not applicable
+- Reason: policy-only Skill, Spec, and index changes do not alter a rendered surface
+- PR selector: `PR: none`
+
+## Related Changes
+
+- `9886a7f` docs(skills): enforce viewport-safe browser evidence capture
+- `b39a914` docs(specs): adopt topic-level spec model
+- Current policy update: include `ui_demo` in viewport-safe evidence ladder
+- Current policy update: add `ui-demo-source` viewport strategy for source-managed demo scenarios
+- Current policy update: use `393x852` CSS px as the fallback mobile acceptance viewport when no explicit size exists
+- Current policy update: require the fallback viewport to be applied and verified on the rendered surface before metadata is recorded
+- Current policy update: keep Storybook fallback viewport binding on the stable story/docs surface rather than capture-time emulation
+- Current policy update: remove `devtools-emulate` from Storybook-only evidence metadata because capture-time emulation is unsupported there
+- Current policy update: make Storybook coverage materialize the fallback viewport before capture
+
+## Remaining Gaps
+
+- None currently tracked.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/5fsxh-viewport-safe-browser-evidence/SPEC.md

@@ -0,0 +1,170 @@
+# Viewport-safe browser evidence capture
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 当前 Storybook / 浏览器证据链已经要求 mock-first、元素优先与稳定来源，但没有把“指定 viewport 的截图必须怎样达成”钉成硬规则。
+- 这留下了执行歧义：agent 很容易退化成“打开 Storybook canvas 页面、调整浏览器窗口尺寸、再截 browser viewport”，导致浏览器会话被持续改窗，和视觉证据本身混在一起。
+- 如果不收紧这条契约，后续 `ui_demo`、`storybook_canvas`、`storybook_docs` 与 `mock_ui` 仍可能重复走同样的坏路径，既影响主人复查，也让截图元数据缺少一致真相源。
+
+## 目标 / 非目标
+
+### Goals
+
+- 统一 `ui_demo`、`storybook_canvas`、`storybook_docs` 与 `mock_ui` 的 viewport-safe 截图契约：默认不依赖浏览器窗口 resize 来满足目标尺寸。
+- 明确浏览器证据的优先级：来源自带 viewport / `emulate.viewport` / 元素级截图优先，`browser-resize-fallback` 仅保留为末级兜底。
+- 为相关 skills 增加统一的 `requested_viewport` 与 `viewport_strategy` 元数据约定，便于后续 audit 与复盘。
+- 让 `storybook-stories` 在响应式验收场景下提供稳定的 Storybook 入口，而不是把 viewport 控制责任推迟给截图阶段。
+- 为未声明尺寸的移动端验收提供确定的 `393x852` CSS px 默认 viewport，同时保留主人、项目、spec 与来源 surface 的显式覆盖能力。
+
+### Non-goals
+
+- 不修改 `chrome-devtools-mcp`、Storybook upstream、或任何业务仓库中的具体 story/config 实现。
+- 不扩展到真实应用窗口截图（`target_app_window`）或固件显示类证据源。
+- 不引入新的截图后端、视觉回归平台或外部依赖。
+
+## 范围（Scope）
+
+### In scope
+
+- `docs/specs/README.md`
+- `skills/storybook-screenshots/SKILL.md`
+- `skills/ui-visual-evidence/SKILL.md`
+- `skills/storybook-stories/SKILL.md`
+- `AGENTS.md`
+- `skills/storybook-screenshots/agents/openai.yaml`
+- `skills/ui-visual-evidence/agents/openai.yaml`
+- `skills/storybook-stories/agents/openai.yaml`
+- `skills/README.md`
+
+### Out of scope
+
+- `AGENTS.md` 顶层提示词
+- `skills/pr-create/SKILL.md` 与其他非本轮直接使用的 flow / review skills
+- 任何 repo 外截图脚本或浏览器自动化实现
+
+## 需求（Requirements）
+
+### MUST
+
+- `storybook_canvas` 与 `storybook_docs` 的特定 viewport 证据必须优先来自 Storybook 自身可控 surface，而不是浏览器窗口 resize。
+- `ui_demo` 的特定 viewport 证据必须优先来自 demo 自身可控场景，并记录 `viewport_strategy=ui-demo-source`；若 demo 没有 source-managed viewport，则使用 `devtools-emulate`，并继续优先元素级截图。
+- `mock_ui` 的特定 viewport 证据必须优先由负责该证据源的 current-truth skill 提供稳定 viewport 控制，并继续优先元素级截图。
+- 浏览器证据统一记录 `requested_viewport=<name|WxH|none>` 与 `viewport_strategy=<ui-demo-source|storybook-viewport|devtools-emulate|browser-resize-fallback>`。
+- `capture_scope=browser-viewport` 只能在“整个浏览器渲染区域本身就是证据目标”时使用，不能替代元素级截图成为默认路径。
+- `browser-resize-fallback` 只能在来源自带 viewport 与 `devtools-emulate` 都无法满足时使用，并且必须记录原因、恢复原始窗口尺寸；恢复失败时不得把该会话当作最终 owner-facing 浏览器状态。
+- `storybook-stories` 必须要求：若验收依赖 mobile/tablet/desktop 等响应式尺寸，稳定 Storybook 入口本身就要绑定对应 viewport 或等价响应式场景，而不是把这件事留给后续截图动作。
+- 移动端证据在主人、项目、spec、Storybook story 与 demo scenario 都未声明 viewport 时，必须使用 `393x852` CSS px，并记录 `requested_viewport=393x852`；任何显式 viewport 都优先于该默认值。
+- `393x852` 只定义响应式验收的 CSS viewport，不代表设备物理像素，也不要求模拟特定 User-Agent。
+- 默认值生效时，必须先通过来源自带 viewport 或来源适用的 emulation 路径将实际渲染 surface 绑定到 `393x852` CSS px 并验证，再记录 `requested_viewport=393x852`；禁止只写元数据而保持任意渲染尺寸。
+- Storybook 证据不得用截图阶段的临时 emulation 代替稳定 story/docs viewport；默认值必须落在可复现的 Storybook surface 上，无法绑定时回到 Storybook coverage 或报告阻断。
+
+### SHOULD
+
+- skills 索引与 agent metadata 文案应同步强调 viewport-safe、element-first 的默认路径。
+- 文本示例应明确 `ui_demo` source-managed 场景优先 `ui-demo-source`，Storybook 场景优先 `storybook-viewport`，普通浏览器页面优先 `devtools-emulate`。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- 解析移动端验收 viewport 时：
+  - 优先使用主人显式尺寸，其次使用项目、spec 或来源 surface 已绑定的尺寸。
+  - 所有显式来源均缺失时，使用 `393x852` CSS px。
+  - 默认值生效时先应用并验证实际渲染 viewport，再写入 `requested_viewport=393x852`，并按所选证据源记录 `viewport_strategy`。
+
+- Storybook canvas/docs 取证时：
+  - 若截图依赖特定 viewport，先选择或建立已绑定目标 viewport 的 Storybook surface。
+  - 然后对实际渲染内容做元素级截图；只有整个浏览器渲染区域就是证据目标时才允许 `browser-viewport`。
+  - 默认 `viewport_strategy=storybook-viewport`。
+- 普通浏览器 `mock_ui` 取证时：
+  - 若截图依赖特定 viewport，先使用显式 `chrome-devtools` 例外路径的 `emulate.viewport` 设定目标尺寸。
+  - 然后优先以页面元素为目标截图；默认 `viewport_strategy=devtools-emulate`。
+- `ui_demo` 取证时：
+  - 若 demo surface 自带稳定 viewport/scenario，优先使用该 source-managed 场景；默认 `viewport_strategy=ui-demo-source`。
+  - 否则按普通浏览器 mock 证据走显式 `chrome-devtools` 例外路径的 `devtools-emulate` + 元素级截图。
+- 对这些浏览器证据：
+  - 只有在默认路径都不可行时，才允许 `browser-resize-fallback`。
+  - 一旦用到 fallback，必须先记录失败原因，再恢复窗口外尺寸，最后才能进入 handoff / 回图语义。
+
+### Edge cases / errors
+
+- 若 Storybook 仓库没有可复用的 viewport 约定，`storybook-stories` 必须要求沿用仓库现有方式建立稳定入口；不得用“先调浏览器大小再截”替代。
+- 若元素级截图无法覆盖目标（例如证据目标确实是整页浏览器渲染区域），允许 `capture_scope=browser-viewport`，但仍不得先把它降级成 resize 驱动。
+- 若 `browser-resize-fallback` 无法恢复原始窗口尺寸，相关 skills 必须报告 blocker，而不是把浏览器留在被改过的尺寸继续对外交付。
+
+## 接口契约（Interfaces & Contracts）
+
+### 接口清单（Inventory）
+
+| 接口（Name） | 类型（Kind） | 范围（Scope） | 变更（Change） | 契约文档（Contract Doc） | 负责人（Owner） | 使用方（Consumers） | 备注（Notes） |
+| - | - | - | - | - | - | - | - |
+| Storybook viewport-safe capture contract | skill | internal | Modify | in-spec | Codex skills | `storybook-screenshots`, review flows | 新增 viewport metadata 与 resize fallback 约束 |
+| Browser viewport-safe capture ladder | skill/policy | internal | Modify | in-spec | Codex skills + AGENTS | `ui_demo`, `mock_ui` evidence flows | `ui_demo` 优先 source-managed demo scenario，`mock_ui` 由 current-truth evidence path 提供稳定 viewport 控制 |
+| Visual evidence source sizing rules | skill | internal | Modify | in-spec | Codex skills | `ui-visual-evidence`, shared workflow | 统一四类浏览器证据的优先级 |
+| Responsive Storybook entry requirement | skill | internal | Modify | in-spec | Codex skills | `storybook-stories`, UI implementation turns | 响应式验收入口前置到 Storybook 覆盖阶段 |
+| Discovery / agent copy for viewport-safe evidence | doc | internal | Modify | in-spec | Codex skills | skills index, agent picker | 文案同步新默认路径 |
+
+### 契约文档（按 Kind 拆分）
+
+- None. 本计划只修改内部 skills / metadata / docs 索引，以上表与对应 `SKILL.md` / metadata 文本即为真相源。
+
+## 验收标准（Acceptance Criteria）
+
+- Given `storybook-screenshots` 需要一张 mobile/tablet/desktop 尺寸下的 Storybook 证据图 When agent 读取该 skill Then 默认路径必须是“Storybook 自带 viewport / 稳定 surface + 元素级截图”，而不是“改浏览器窗口大小再截视口”。
+
+- Given current-truth evidence path 为 `mock_ui` 生成特定 viewport 的浏览器证据 When agent 读取对应技能与策略 Then 默认路径必须优先稳定 viewport 控制，并只在整页本身是证据目标时才使用 `capture_scope=browser-viewport`。
+
+- Given current-truth evidence path 为 `ui_demo` 生成特定 viewport 的浏览器证据 When demo surface 已定义稳定 viewport/scenario Then 默认路径必须优先使用 demo 自身场景；否则才使用 `devtools-emulate`。
+
+- Given `ui-visual-evidence` 为 `ui_demo`、`storybook_docs`、`storybook_canvas` 或 `mock_ui` 选择证据来源 When agent 进入截图步骤 Then 必须沿用统一的 viewport-safe ladder，并把 `browser-resize-fallback` 保持为末级兜底而不是默认方案。
+
+- Given 当前任务要求移动端视觉验收，但主人、项目、spec 与稳定渲染来源均未指定 viewport When `ui-visual-evidence` 解析验收尺寸 Then 必须使用 `393x852` CSS px，并记录 `requested_viewport=393x852`。
+
+- Given `storybook-stories` 面对一个依赖响应式断点验收的 UI 变更 When agent 补 Storybook 覆盖 Then skill 必须要求稳定 Storybook 入口显式承载该 viewport，而不是把 viewport 决策留到截图阶段。
+
+- Given skills index 或 agent picker 文案 When 用户或 agent 查找这些 skills Then 至少能看到 viewport-safe / element-first 的新默认口径，而不是继续暗示 browser resize 是常规手法。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `python3 skills/.system/skill-creator/scripts/quick_validate.py skills/storybook-screenshots`
+- `python3 skills/.system/skill-creator/scripts/quick_validate.py skills/ui-visual-evidence`
+- `python3 skills/.system/skill-creator/scripts/quick_validate.py skills/storybook-stories`
+- `python3 skills/.system/skill-creator/scripts/quick_validate.py skills/storybook-screenshots`
+- `git diff --check`
+
+### Quality checks
+
+- `rg -n "393x852|requested_viewport|viewport_strategy|ui-demo-source|browser-resize-fallback|devtools-emulate|storybook-viewport|prefer .*element|resize_page" skills docs/specs`
+- 人工 spot-check 4 个主 skill 与相关 metadata / 索引文案的默认路径是否一致。
+
+## 方案概述（Approach, high-level）
+
+- 继续沿用现有 Storybook / browser / visual-evidence 技能边界，只收紧“viewport 如何达成”的默认路径。
+- 把 Storybook 取证与通用浏览器取证分别锚定到各自最稳定的控制面：前者优先 source-managed viewport，后者优先由 current-truth evidence path 提供的稳定 viewport 控制。
+- 把 `ui_demo` 锚定到 demo 自身稳定场景；没有 source-managed 场景时再走通用浏览器 mock 梯度。
+- 保留 `browser-resize-fallback`，但把它从默认做法降级为可审计、可恢复、可阻断的末级例外路径。
+
+## Visual Evidence
+
+PR: none
+
+本次只修改 Skill、Spec 与索引契约，不改变任何渲染界面，因此视觉证据不适用。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：部分仓库的 Storybook viewport 能力可能较弱，因此 `storybook-stories` 只能要求“稳定入口”而不能强制某一种实现写法。
+- 风险：`393x852` 不能代表所有移动设备；它只在没有显式项目尺寸时提供一致基线，不能覆盖额外的小屏、宽屏或横屏测试需求。
+- 风险：若未来需要把同一套 metadata 暴露到更多 flow/PR 输出，还需要追加联动点；本轮只覆盖直接使用的 source skills 与索引文案。
+- 假设：当前仓库已有的 `chrome-devtools` / Storybook 能力足以支撑默认路径，`browser-resize-fallback` 只会是少数例外。
+
+## 参考（References）
+
+- `docs/specs/storybook-skill-upgrade/SPEC.md`
+- `docs/specs/shared-ui-visual-evidence-gate/SPEC.md`
+- `docs/specs/visual-evidence-whitespace-trim/SPEC.md`
+- Storybook official docs: Viewport essentials, Story / Canvas doc blocks
+- Chrome DevTools MCP source: `take_screenshot`, `take_snapshot`, `includeIframes`

package/toolkit/skills/docs/vendor/dot-codex/specs/6s9b8-retire-legacy-service-manager/HISTORY.md

@@ -0,0 +1,18 @@
+# Retire zellij service manager 演进历史（#6s9b8）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `c530b57` chore: retire legacy service manager stack
+- `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: `#6s9b8`.