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

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

@@ -0,0 +1,56 @@
+# Retire zellij service manager 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 删除已废弃服务托管 skill 与 repo 内配套辅助链，保留本机运行态残留为 out of scope
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-04-10
+- Legacy last-tracked: 2026-04-10
+- Current lifecycle: active
+- Catalog note: 删除已废弃服务托管 skill 与 repo 内配套辅助链，保留本机运行态残留为 out of scope
+
+## Delivery Milestones
+
+- [x] M1: 建立退役 spec、更新索引并写清范围边界
+- [x] M2: 删除 skill、本仓库 `devctl` / launchd 辅助链与相关 bin 文档
+- [x] M3: 清理现行技能/规格中的活跃引用并完成本地验证
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`: 新增索引项
+- `docs/specs/retire-legacy-service-manager/SPEC.md`: 记录退役范围与验收口径
+- `docs/specs/global-port-preview-governance/SPEC.md`: 去掉已删除能力的点名引用
+- `skills/README.md`: 移除 retired skill 条目
+- `skills/storybook-stories/SKILL.md`: 去掉 `$zellij-service-manager` 回退路径
+
+### Plan assets
+
+- Directory: `docs/specs/retire-legacy-service-manager/assets/`
+- Visual evidence source: none required for this non-UI retirement task.
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `c530b57` chore: retire legacy service manager stack
+- `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/6s9b8-retire-legacy-service-manager/SPEC.md

@@ -0,0 +1,48 @@
+# Retire zellij service manager
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## Context and Scope
+
+This compatibility-path specification preserves the historical `#6s9b8` identity for the repository-owned retirement of `zellij-service-manager`. It covers the retired skill, `devctl` helpers, launchd templates, active consumer references, and the related catalog entry. Host launchd jobs, logs, state, and other runtime residue remain outside this repository contract.
+
+## Requirements
+
+### REQ-ZELLIJ-RETIRE-001
+
+The repository MUST NOT retain the `zellij-service-manager` skill or the `devctl` and launchd helper files that existed only to support that workflow.
+
+### REQ-ZELLIJ-RETIRE-002
+
+Current skills and topic specifications MUST describe Codex native background terminals and live task ownership for long-running work. They MUST NOT present the retired service manager or its helpers as an active capability, fallback, or required dependency.
+
+### REQ-ZELLIJ-RETIRE-003
+
+The topic catalog and direct consumer documentation MUST remain consistent with the retired repository surface. Unrelated Storybook, port governance, and other shared workflow requirements MUST remain intact. Runtime residue outside the repository MUST NOT be removed by this topic.
+
+## Verification
+
+### VER-ZELLIJ-RETIRE-001 covers: REQ-ZELLIJ-RETIRE-001
+
+- Method: inspect the tracked file set and the deletion diff for the retired skill, `devctl` helpers, and launchd templates.
+- Pass condition: no retired repository-owned capability or helper remains in the source tree.
+
+### VER-ZELLIJ-RETIRE-002 covers: REQ-ZELLIJ-RETIRE-002
+
+- Method: search tracked current skills and specifications for active `zellij-service-manager`, `devctl`, or `devctl-gc` references and inspect the long-task wording in the direct consumers.
+- Pass condition: current consumers use Codex native background terminals and live task ownership; any retained old-name hit is limited to the retirement specification or necessary historical evidence.
+
+### VER-ZELLIJ-RETIRE-003 covers: REQ-ZELLIJ-RETIRE-003
+
+- Method: validate the catalog entry, the shared Storybook and port-governance requirements, and the documented runtime boundary.
+- Pass condition: the catalog matches the repository surface, unrelated shared requirements remain present, and host runtime residue is explicitly out of scope.
+
+## Related ADRs
+
+None
+
+## References
+
+- `./IMPLEMENTATION.md`
+- `./HISTORY.md`
+- `docs/specs/global-port-preview-governance/SPEC.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/7uqp8-mainline-baseline-topic-branch-freshness/HISTORY.md

@@ -0,0 +1,15 @@
+# Mainline baseline and topic branch freshness contract 演进历史（#7uqp8）
+
+> 这里记录关键演进原因；规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- 新建 `#7uqp8`，因为“显式 `$dev-plan` 的具体开发基线输出合同”与“shared workflow 的 topic branch freshness 准备”跨越了 planner 与 execution 两个层面，不能继续挤在 `#5dvcj` 或 `#w7yqp` 的边角里。
+- 默认策略改用“目标仓库主干基线”而不是硬编码 `origin/main` 作为长期语义；但 owner-facing 最终计划值必须仍然落成具体 ref，不能把抽象策略词直接冒充最终答案。
+- Step 1 被重新定义为“建立正确且新鲜的 topic-branch 执行上下文”，而不是单纯检查“当前是不是在 topic branch”。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#7uqp8`.

package/toolkit/skills/docs/vendor/dot-codex/specs/7uqp8-mainline-baseline-topic-branch-freshness/IMPLEMENTATION.md

@@ -0,0 +1,68 @@
+# Mainline baseline and topic branch freshness contract 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 规格已建立，等待 skill / checker / replay / solution 全量收敛
+
+## Coverage / rollout summary
+
+- 已创建独立 topic spec，明确这次规则不再硬塞进 `docs/specs/dev-plan-default-fast-track-auto-lock/SPEC.md` 或 `docs/specs/git-skill-convergence/SPEC.md`。
+- `AGENTS.md` 已补齐 owner-facing current truth：
+  - 显式 `$dev-plan` 必须输出具体 `开发基线`
+  - shared workflow 的“无 topic branch 自动建 / 已有 topic branch Step 1 预同步 / Step 4 再复核”合同
+- `skills/dev-plan/SKILL.md` 已新增 `开发基线` 必填约束、默认解析规则与 skeleton 示例。
+- `skills/project-engineering-workflow/SKILL.md` 已把 Step 1 改成“建立正确且新鲜的 topic-branch 执行上下文”，并补了 Step 1 预同步与 Step 4 二次复核的口径。
+- `skills/git-branch/SKILL.md`、`skills/git-sync/SKILL.md`、`skills/fast-flow/SKILL.md` 已完成最小依赖文案对齐。
+- `bin/plan_contract_check.sh` 已新增：
+  - 缺失 `开发基线` 的拦截
+  - 抽象主干词作为最终值的拦截
+  - 主人显式 baseline 与计划最终值不一致的拦截
+- checker 的 planning-session reset 逻辑已收紧：
+  - 已锁定计划中的 standalone flow restatement 不再清空主人显式 baseline
+  - 普通 scope clarification 里的产品词组（如 `new plan file upload API`）不再误判成新的独立计划请求
+- checker 的 owner baseline 抽取已补足自然语言显式基线：
+  - ``基于 \``...\` 开发``/``from ...` 这类 directional wording 会被识别为主人显式 baseline
+  - `请把导入页面也规划进去，其他不变` 这类 scope clarification 不再误清当前 planning session
+- checker 的 baseline / session 误报边界已继续收紧：
+  - `BASE_REF=...` 形式现在也会被识别为主人显式 baseline
+  - bare `base=...` / `base:...` 形式现在也会被识别为主人显式 baseline
+  - ``branch protection``、``use \``main.ts\` as the parser reference` 这类普通产品/文件短语不再被误抽成 baseline
+  - `plan.md` / `planning UI` 这类 scope clarification 不再因为包含 `plan` 词根而误触发新 planning session reset
+  - `开发基线用 upstream/release-2026q3` 这类中文简写现在也会被识别为主人显式 baseline，不再漏掉 mismatch
+  - owner baseline 比较会接受 `origin/main` 与 `refs/remotes/origin/main` 这类等价 remote ref 表达
+  - `开发基线从 A 改为 B` / `开发基线改为 B` 这类 replace clause 现在会以新的显式 baseline 为准，不再错误沿用被替换掉的旧值
+  - `请重新规划这个任务` 这类 verb-form re-plan 请求现在会正确打开新的 planning window，不再把上一轮显式 baseline 泄漏到下一轮计划
+  - `重新规划这个任务，收口改为 merge-ready` 这类同时带 re-plan 与 continuation 词的请求，现在会优先按新的 planning window 处理，而不是被 continuation 词提前截走
+  - `请帮我规划这个任务：...` 这类 plain-language 新计划请求现在会正确打开新的 planning window，不再被上一轮 flow/baseline 污染
+  - `请用 $dev-plan 给我一份 merge queue API 的计划` 这类任务名含 `merge` 词根的新请求，不再被误当成 continuation
+  - `开发基线使用 qa`、`base=rc` 这类 1-2 字符的 plain short ref baseline，现在也会被识别成主人显式 baseline，不再漏掉 mismatch
+  - plain baseline 末尾如果是 Git 允许的 `,` / `;` 这类合法字符，现在会原样保留；只有真正的 continuation 子句（如 `, 并继续`）才会被裁掉
+  - `基于 new plan file upload API 规划这个任务` 这类 directional 产品词组，不再被误抽成 owner baseline；plain directional baseline 只有在值显式带 `branch/ref/commit` 限定词，或本身长得像真实 ref/commit 时才会进入比较
+  - ``基于 \``docs/specs/.../SPEC.md\` 规划这个任务``这类 backtick 包裹的 spec/doc 输入，不再被 plain directional baseline 分支误抽成 owner baseline；需要显式``开发基线...``/``BASE_REF=...``/``基于 ... 开发` 这类更强 Git 语义才会锁定 baseline
+  - `请按 normal 把计划页面上传 API 也规划进去，flow 和开发基线都不变` 这类 scope clarification，不再因为产品词里的 `计划` 两字误触发新的 planning window reset
+  - 合法 git ref 即使包含 `default` / `mainline` / `todo` 等词根，也不会再被 placeholder / abstract-baseline 规则误伤
+  - `目标仓库主干基线` / `远程主干基线` 这类组合抽象词组，现在会继续被视为抽象默认策略词，而不是被误当成合法 ref
+  - `origin/HEAD` / `upstream/HEAD` 这类常见 bare remote symbolic HEAD alias，以及 `refs/remotes/origin/HEAD` 这类 fully-qualified remote HEAD alias，现在都会被稳定拒绝，不再依赖 checker 当前仓库里恰好存在同名 remote
+  - 合法 branch ref 即使最后一个 path component 恰好是 `HEAD`（如 `feature/HEAD`），也不会再被 remote symbolic HEAD alias 规则误伤
+  - `bin/plan_contract_check.sh` 已去掉会依赖临时写盘的 here-string 输入路径，使 fresh review proof 在 read-only sandbox 下也能直接执行 checker，而不会因为 shell 临时文件失败而误报 `NO_PROPOSED_PLAN`
+- review proof 暴露的后续边界问题也已补齐：
+  - `topic/foo`、`feature/todo-cleanup` 这类 ref 内部包含 `to` 词根的合法 branch baseline，不会再被 replace-clause regex 截断成尾巴
+  - 在 `request_user_input(flow_type)` 之后，`请按 normal 继续出计划` 这类自然语言 flow 回答不再清空先前显式 baseline
+  - 显式 `$dev-plan` 新请求现在会先于 continuation heuristics 判定；像 `请用 $dev-plan 继续给我一份新的可执行计划` 这类同句带 `继续` 的 fresh request，也会正确打开新的 planning window
+  - `todo` / `default` / `pending` 这类与 placeholder 词根重合但本身是合法 git ref 的 baseline，现在会优先按 concrete ref 接受；真正的 `TBD` 类占位词仍然拒绝
+  - `feature/README.md` 这类“看起来像文档路径”但语法上合法的 git ref baseline，现在也会按 concrete ref 保留；只有真正的文件系统路径（如 `./docs/specs/foo/SPEC.md`）仍会被拒绝
+- replay fixtures / `CASES.txt` 已补齐默认主干 concrete ref、显式 branch、显式 commit、缺失基线、抽象基线、忽略主人 baseline、standalone flow restatement、directional 产品词误报与 scope clarification false-positive 的 focused coverage，并已通过全套回放。
+- `docs/solutions/workflow-issues/git-skill-convergence.md` 已刷新 reusable guidance。
+
+## Remaining Gaps
+
+- None currently tracked after local validation.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/7uqp8-mainline-baseline-topic-branch-freshness/SPEC.md

@@ -0,0 +1,166 @@
+# Mainline baseline and topic branch freshness contract
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- repo 现有合同已经分别覆盖了显式 `$dev-plan` 的 flow lock（如 `docs/specs/dev-plan-default-fast-track-auto-lock/SPEC.md`）与 canonical git skill surface（如 `docs/specs/git-skill-convergence/SPEC.md`），但还没有一个长期主题专门定义“开发基线默认值”和“topic branch 新鲜度”的统一真相。
+- 结果是三层语义可能分裂：运行时文案说“默认按主干”，计划输出里却可能只写抽象词，实际执行又可能继续停留在 detached HEAD、默认分支，或已经过时的 topic branch 上。
+- 主人要求默认按“目标仓库主干基线”推进；若主人显式指定了 branch 或 commit，就必须原样尊重；若没有指定，则只有非常强的 Git 事实才应触发“也许不是主干”的确认。
+- 这条规则既涉及显式 `$dev-plan` 的 owner-facing 合同，也涉及 shared workflow 在 Step 1/Step 4 如何准备并维持一个正确且不过时的开发上下文，因此需要独立 topic spec 统一收敛。
+
+## 目标 / 非目标
+
+### Goals
+
+- 为显式 `$dev-plan` 新增“具体开发基线”合同：`Flow Decision` 必须写出 concrete branch 或 commit，不能只停留在“远程主干”“目标仓库主干”之类抽象表述。
+- 固化默认基线决策：主人显式给 branch/commit 时原样保留；主人未指定时，默认解析为目标仓库主干的具体 ref，并优先输出 branch，只有 branch 不可用或主人明确给 commit 时才输出 commit SHA。
+- 把计划阶段的非主干确认触发器收紧到两类强 Git 事实：唯一 open PR base，或显式 upstream 集成分支；除此之外默认按目标仓库主干基线规划。
+- 把 shared workflow 的 Step 1 改成“先拿到正确且新鲜的执行上下文”：
+  - 没有 topic branch 时，基于已解析基线通过 `$git-branch` 自动创建 topic branch；
+  - 已有 topic branch 时，进入 spec/实现前先做一次 `$git-sync` 预同步；
+  - Step 4 继续按既有 confirmed-base gate 复核并必要时再次同步。
+- 保持 planner 合同、运行时文案、checker、replay fixtures 与 reusable solution 同口径，避免同一条规则在不同入口说法不同。
+
+### Non-goals
+
+- 不把 Step 4 的 factual `BASE_REF` 解析硬编码成永远优先 `origin/main`；release 分支、open PR base、upstream 集成分支等既有强事实优先级仍然保留。
+- 不把“计划里必须声明开发基线”扩展到未显式 `$dev-plan` 的普通规划回复。
+- 不引入新的 branch naming policy，也不修改 remote URL、upstream、push 目标、认证或传输配置。
+- 不为这次规则调整新增 workflow glossary 或 ADR；长期真相继续放在 spec、solution 与 active workflow docs。
+
+## 范围（Scope）
+
+### In scope
+
+- `docs/specs/README.md`
+- `docs/specs/mainline-baseline-topic-branch-freshness/*`
+- `AGENTS.md`
+- `skills/dev-plan/SKILL.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/fast-flow/SKILL.md`
+- `skills/git-branch/SKILL.md`
+- `skills/git-sync/SKILL.md`
+- `bin/plan_contract_check.sh`
+- `skills/dev-plan/references/replay-cases/*`
+- `docs/solutions/workflow-issues/git-skill-convergence.md`
+
+### Out of scope
+
+- `normal` / `fast-track` / `local-merge` 的业务终点语义重写
+- GitHub PR merge/runtime 逻辑
+- remote/auth/transport 配置变更
+- `CONTEXT.md` 或 browser-only 术语扩写
+
+## 需求（Requirements）
+
+### MUST
+
+- 显式 `$dev-plan` 产出的每个 `<proposed_plan>` 都必须在 `Flow Decision` 中声明 `开发基线`，且最终值只能是具体 branch/ref 或 commit SHA。
+- `开发基线` 不得只写抽象默认策略词，例如“远程主干”“目标仓库主干”“主干基线”；若需要表达默认策略，可在说明文字中出现，但最终值必须落到具体 ref。
+- 当主人显式指定 branch 或 commit 作为 base 时，计划输出必须原样保留该事实，不能被默认主干 ref 覆盖。
+- 当主人未显式指定 base 时，计划阶段只允许以下两类强 Git 事实触发“可能不是主干基线”的确认：
+  - 当前 topic branch 关联的唯一 open PR base；
+  - 明确指向非 topic 集成分支的 upstream。
+- 除上述两类强事实外，显式 `$dev-plan` 默认按目标仓库主干基线规划，并在最终计划中输出解析后的具体 ref。
+- shared workflow 的 Step 1 必须支持两条路径：
+  - 若当前没有 topic branch，且工作区状态允许安全切换，则先解析开发基线，再通过 `$git-branch` 从该基线创建 topic branch；
+  - 若当前已经在 topic branch 上，则在进入 Step 2 前先完成一次 `$git-sync` 预同步。
+- shared workflow 的 Step 1 若处于 detached HEAD、默认分支或其他“需要移动当前工作副本”的场景，而工作区又存在 dirty/歧义风险，仍必须阻断并只问 1 个关键问题。
+- shared workflow 的 Step 4 必须继续执行既有 confirmed-base gate，并明确它是对 Step 1 上下文准备结果的第二次复核；若 branch 在 Step 1 已同步但到 Step 4 又落后，仍需再次 `$git-sync`。
+- `git-branch` 必须允许调用方把“已解析开发基线”作为 `BASE_REF` 传入，用于从正确 ref 建立 topic branch，而不是默认假设 detached `HEAD` 就是正确起点。
+- `git-sync` 必须明确：shared workflow 的 Step 1 topic-branch 预同步，与 Step 4 confirmed-base 同步一样，都属于可复用的“confirmed base sync”路径；Step 1 只是更早执行，不代表可以跳过 Step 4 复核。
+- `AGENTS.md`、`skills/dev-plan/SKILL.md`、`skills/project-engineering-workflow/SKILL.md`、相关 flow/git skills、`bin/plan_contract_check.sh` 与 replay fixtures 必须表达同一条规则。
+
+### SHOULD
+
+- owner-facing 文案可以使用“目标仓库主干基线”描述默认策略，但要同时清楚区分：这只是默认决策规则，不是最终 `开发基线` 字段允许输出的抽象值。
+- 新的 replay fixtures 应同时覆盖 branch 与 commit 两类正例，避免后续 checker 只偏向某一种 ref 形态。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### 显式 `$dev-plan` 的开发基线合同
+
+- `Flow Decision` 固定字段仍包含 `flow_type`、`flow_source`、`lock_status`；在此基础上新增 owner-facing 必填行：`开发基线`。
+- `开发基线` 的允许值：
+  - fully-qualified remote branch/ref，例如 `origin/main`、`upstream/release/2026-q3`
+  - local branch/ref，仅当主人显式指定或当前上下文明确要求保留该本地 ref
+  - full commit SHA
+- `开发基线` 的禁止值：
+  - 纯抽象策略词，如“远程主干”“目标仓库主干”“默认主干”“mainline baseline”
+  - 缺失值、空值、`TBD`/`待确认`
+- 解析优先级固定为：
+  1. 主人显式给出的 base branch / commit
+  2. 唯一 open PR base
+  3. 显式 upstream 集成分支
+  4. 目标仓库主干基线的具体 ref
+- 当解析结果同时存在“默认主干策略说明”和“具体 ref”时，owner-facing 计划的最终值只写具体 ref；策略说明可以出现在 Summary / Assumptions 中，但不能替代最终值。
+
+### shared workflow 的 topic branch / freshness 合同
+
+- Step 1 的目标不再只是“确认当前就在 topic branch 上”，而是“让当前 run 在进入 spec / 实现前拿到一个安全、正确、不过时的 topic-branch 执行上下文”。
+- 若当前没有 topic branch：
+  - clean 且无风险时，先解析开发基线，再调用 `$git-branch ACTION=create-topic BASE_REF=<resolved-base>` 建立 topic branch；
+  - dirty 或存在切换风险时，阻断并只问 1 个关键问题。
+- 若当前已在 topic branch：
+  - Step 1 先解析一个 provisional-to-confirmed 的开发基线；
+  - 若该基线已经足够确认，则通过 `$git-sync` 先做一次预同步；
+  - 若连 Step 1 都无法唯一确认真实 base，则阻断并只问 1 个关键问题，而不是带着旧 branch 继续实现。
+- Step 4 仍然是 `可开 PR（local）` 的 confirmed-base gate：
+  - 它必须重新 fetch / 复核 canonical `BASE_REF`；
+  - 若 branch 相对该 `BASE_REF` 再次落后，必须再次 `$git-sync`；
+  - Step 1 的预同步永远不能被当作 Step 4 已完成的替代证据。
+
+## 验收标准（Acceptance Criteria）
+
+- Given 显式 `$dev-plan` 计划里缺少 `开发基线` When `bin/plan_contract_check.sh` 检查该回放 Then 必须报出缺失开发基线的 finding。
+
+- Given 显式 `$dev-plan` 计划把 `开发基线` 写成“目标仓库主干”或“远程主干” When checker 检查该回放 Then 必须报出抽象开发基线不合法的 finding。
+
+- Given 主人没有显式指定 base，且仓库没有 open PR base / 显式 upstream 集成分支 When agent 产出显式 `$dev-plan` Then 最终计划应按目标仓库主干基线解析为具体 ref，而不是只写抽象词。
+
+- Given 主人显式给出 branch 或 commit When agent 产出显式 `$dev-plan` Then `开发基线` 必须原样保留该 branch 或 commit。
+
+- Given 当前 run 处于 detached/default branch 且没有 topic branch，工作区干净 When shared workflow 进入 Step 1 Then 它必须先解析正确 base，再通过 `$git-branch` 从该 base 创建 topic branch，而不是直接阻断。
+
+- Given 当前 run 已在 topic branch 上 When shared workflow 进入 Step 1 然后 Step 4 Then Step 1 必须先做一次 `$git-sync` 预同步，Step 4 仍必须继续 confirmed-base 复核并在需要时再次同步。
+
+- Given 当前 run 处于 detached/default branch 或需要移动当前工作副本，但工作区 dirty 或存在歧义风险 When shared workflow 进入 Step 1 Then 它仍然必须阻断并只问 1 个关键问题，而不是静默建分支或静默切换。
+
+## 验收清单（Acceptance checklist）
+
+- [x] 显式 `$dev-plan` 的 `开发基线` 合同已写清楚并落到 checker。
+- [x] 默认主干策略与最终具体 ref 输出的区别已写清楚。
+- [x] shared Step 1 自动建 branch / Step 1 预同步 / Step 4 再复核的双阶段 freshness 合同已写清楚。
+- [x] dirty / detached/default-branch 风险场景仍保持单问题阻断。
+- [x] replay fixtures 覆盖无显式 base、显式 branch、显式 commit、缺失基线、抽象基线五类场景。
+- [x] reusable solution 与 owner-facing current truth 已同步。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `bash bin/plan_contract_check.sh --cases skills/dev-plan/references/replay-cases/CASES.txt`
+- `git diff --check`
+- active runtime grep：确认 `AGENTS.md`、`skills/dev-plan/SKILL.md`、`skills/project-engineering-workflow/SKILL.md`、`skills/git-branch/SKILL.md`、`skills/git-sync/SKILL.md`、`skills/fast-flow/SKILL.md` 对该规则的说法一致
+
+### Quality checks
+
+- spot-check `Flow Decision` 示例，确认最终值只写具体 branch/commit
+- spot-check Step 1/Step 4 文字，确认双阶段 sync 没被写成一次性 shortcut
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：如果只收紧 `dev-plan` checker、不修改 shared workflow，agent 仍可能在 stale branch 上继续实现，导致“计划写对了，执行上下文还是错的”。
+- 风险：如果把“目标仓库主干基线”误写成永远等于 `origin/main`，会破坏 release / upstream / PR base 等既有强事实优先级。
+- 假设：显式 `$dev-plan` 的 owner-facing 合同允许新增 1 条中文固定行 `开发基线`，而不需要再引入新的英文字段 schema。
+
+## 参考（References）
+
+- `docs/specs/dev-plan-default-fast-track-auto-lock/SPEC.md`
+- `docs/specs/git-skill-convergence/SPEC.md`
+- `skills/dev-plan/SKILL.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/git-branch/SKILL.md`
+- `skills/git-sync/SKILL.md`
+- `bin/plan_contract_check.sh`

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

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

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

@@ -0,0 +1,60 @@
+# 本地聊天图片快照存储 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 为 owner-facing 本地聊天图片新增不可变快照 helper、提示词契约与 git ignore 规则
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-04-11
+- Legacy last-tracked: 2026-04-11
+- Current lifecycle: active
+- Catalog note: 为 owner-facing 本地聊天图片新增不可变快照 helper、提示词契约与 git ignore 规则
+
+## Delivery Milestones
+
+- [x] M1: 新建 `docs/specs/local-chat-image-snapshots/SPEC.md` 规格并更新 specs 索引
+- [x] M2: 新增本地聊天图片快照 helper 与自测
+- [x] M3: 为 `user-inline-assets/` 补 git ignore 规则
+- [x] M4: 同步全局提示词、AGENTS 与受影响 skills 的聊天图片契约
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `instruction.md`: 新增全局本地聊天图片快照规则
+- `AGENTS.md`: 新增 owner-facing 本地 Markdown 图片快照硬规则
+- `skills/ui-visual-evidence/SKILL.md`: 视觉证据聊天回图改为快照路径
+- `skills/storybook-screenshots/SKILL.md`: Storybook 本地聊天图改为快照路径
+- `skills/ui-visual-evidence/SKILL.md`: mock/browser 本地截图聊天回图改为快照路径
+- `skills/firmware-display-preview/SKILL.md`: `preview.png` 与聊天展示路径分离
+- `docs/specs/README.md`: 新增 `docs/specs/local-chat-image-snapshots/SPEC.md` 索引
+
+### Plan assets
+
+- Directory: `docs/specs/local-chat-image-snapshots/assets/`
+- In-plan references: None
+- Visual evidence source: not used for this prompt/script change
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `f9ebf1c` feat(images): snapshot local chat images
+- `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/8tmdq-local-chat-image-snapshots/SPEC.md

@@ -0,0 +1,151 @@
+# 本地聊天图片快照存储
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- Codex Desktop 对本地聊天图片按绝对文件系统路径渲染；一旦 agent 直接把可变工作文件路径写进 Markdown，后续同路径覆盖就会污染历史消息里的图片内容。
+- 当前自定义 prompt / skill 栈没有定义“聊天图片必须先快照”的统一出口，导致 `preview.png`、repo 里的规范图片、临时截图文件都可能被直接拿去聊天回图。
+- 如果继续允许 agent 直接引用这些可变路径，主人翻旧对话时看到的图片将不再是发送当时的状态，既影响验收，也会放大桌面端同路径缓存问题。
+
+## 目标 / 非目标
+
+### Goals
+
+- 为 owner-facing 本地聊天图片引入统一的不可变快照 helper，默认落到 `$CODEX_HOME/user-inline-assets/`。
+- 明确全局提示词、AGENTS 与相关 skills 的规则：聊天图片路径与 repo/spec/project 的规范图片路径分离。
+- 确保 `user-inline-assets/` 被 git 忽略，不污染仓库状态。
+- 保持首版实现简单可用：只新增快照，不做自动清理。
+
+### Non-goals
+
+- 不修改官方 Codex App 的缓存或渲染逻辑。
+- 不迁移或修复旧聊天记录中的历史图片引用。
+- 不实现自动 GC、按天数清理或按容量清理。
+- 不改变 spec / plan / PR 里规范图片的既有落盘语义。
+
+## 范围（Scope）
+
+### In scope
+
+- `bin/snapshot_local_image.py`
+- `.gitignore`
+- `instruction.md`
+- `AGENTS.md`
+- `skills/ui-visual-evidence/SKILL.md`
+- `skills/storybook-screenshots/SKILL.md`
+- `skills/firmware-display-preview/SKILL.md`
+- `docs/specs/README.md`
+
+### Out of scope
+
+- `prompts/**` 的 flow / PR 文案结构
+- 官方桌面应用代码
+- 自动清理逻辑与后台守护进程
+
+## 需求（Requirements）
+
+### MUST
+
+- owner-facing 本地聊天图片在 Markdown 回图前必须先复制成唯一快照，聊天里只能引用快照绝对路径。
+- 快照根目录固定为 `$CODEX_HOME/user-inline-assets/`，并按 `repo_slug__repo_hash8/YYYY/MM/DD/` 分片。
+- 快照文件名必须唯一、ASCII-safe，并保留源图扩展名的小写形式。
+- helper 必须是字节复制语义；禁止 symlink、hardlink、覆盖已有快照或内容去重。
+- repo/spec/project 的规范图片仍保留原路径语义，但不得再直接拿这些路径做聊天 Markdown 图片引用。
+- `user-inline-assets/` 必须被 git 忽略。
+
+### SHOULD
+
+- helper 应该只依赖标准 `python3` 运行环境。
+- repo 作用域应优先来自 `git rev-parse --show-toplevel`，不在 git repo 时再退回 `--cwd`。
+- 相关 skills 的文案应给出同一条 helper 用法，避免不同 skill 各写一套口径。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- 当 agent 需要在聊天里回传本地图片时：
+  - 先准备好最终源图（例如规范 `assets/` 文件、裁剪后的 Storybook 图、固件 `preview.png`）；
+  - 再运行 `python3 "${CODEX_HOME:-$HOME/.codex}/bin/snapshot_local_image.py" --source <image-path> --cwd <working-dir>`；
+  - 使用返回 JSON 里的 `snapshot_path` 生成 Markdown 图片；
+  - 原始工作文件继续留在原路径供项目/规范复用，但聊天只引用快照。
+- helper 的默认路径规则：
+  - 根目录：`$CODEX_HOME/user-inline-assets/`
+  - repo scope：`<repo_slug>__<repo_hash8>/`
+  - 日期目录：`YYYY/MM/DD/`
+  - 文件名：`<utc_ts>-<safe_source_stem>-<rand8>.<ext>`
+
+### Edge cases / errors
+
+- 若源图不存在、不是文件或没有扩展名，helper 必须失败并给出明确错误，而不是生成不确定的聊天路径。
+- 若当前 `--cwd` 不在 git repo 内，helper 仍可工作，但 repo 作用域退回到 `--cwd`。
+- 若随机 token 恰好撞名，helper 必须重新生成路径；若调用者显式注入固定 token 且目标已存在，则应报错而不是覆盖。
+
+## 接口契约（Interfaces & Contracts）
+
+### 接口清单（Inventory）
+
+| 接口（Name） | 类型（Kind） | 范围（Scope） | 变更（Change） | 契约文档（Contract Doc） | 负责人（Owner） | 使用方（Consumers） | 备注（Notes） |
+| - | - | - | - | - | - | - | - |
+| `snapshot_local_image.py` | script | internal | New | in-spec | Codex config repo | owner-facing local image flows | 输出 JSON，提供不可变快照路径 |
+| Local chat image snapshot rule | prompt/skill rule | internal | Modify | in-spec | `instruction.md` + `AGENTS.md` | default agent + skills | 统一“聊天路径 != 工作路径” |
+| Visual evidence / screenshot return contract | skill | internal | Modify | in-spec | `ui-visual-evidence`, `storybook-screenshots`, `firmware-display-preview` | UI / preview evidence flows | 所有本地聊天图片改用 helper |
+
+### 契约文档（按 Kind 拆分）
+
+- None. 本规格只涉及内部脚本与提示词/skill 契约，以上表和相应文件正文即为真相源。
+
+## 验收标准（Acceptance Criteria）
+
+- Given 同一张本地源图被连续快照两次 When helper 运行两次 Then 两次返回的 `snapshot_path` 必须不同，且都位于 `$CODEX_HOME/user-inline-assets/` 下。
+
+- Given 源图在第一次快照后被同路径覆盖 When 再次读取第一次生成的快照文件 Then 第一次快照的字节内容必须保持不变。
+
+- Given repo 路径或源图文件名包含空格或非 ASCII 字符 When helper 生成快照路径 Then 生成出来的 repo scope、日期目录和文件名都必须是 ASCII-safe。
+
+- Given `ui-visual-evidence`、`storybook-screenshots` 或 `firmware-display-preview` 要把本地图片回给主人 When 按更新后的契约执行 Then 聊天里必须使用 helper 返回的 `snapshot_path`，而不是原始工作文件路径。
+
+- Given `user-inline-assets/probe.png` When 运行 `git check-ignore -v` Then 结果必须显示该路径由仓库 `.gitignore` 忽略。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `python3 bin/test_snapshot_local_image.py`
+- `python3 bin/snapshot_local_image.py --help`
+- `git diff --check`
+- `git check-ignore -v user-inline-assets/probe.png`
+
+### UI / Storybook (if applicable)
+
+- Stories to add/update: None
+- Docs pages / state galleries to add/update: None
+- `play` / interaction coverage to add/update: None
+- Visual regression baseline changes (if any): None
+
+### Quality checks
+
+- `rg -n "snapshot_local_image|user-inline-assets|snapshot_path" instruction.md AGENTS.md skills docs/specs/local-chat-image-snapshots`
+
+## Visual Evidence
+
+## 方案概述（Approach, high-level）
+
+- 用一个轻量、可直接从 prompt/skills 调用的 Python helper 统一生成不可变聊天图片快照，避免不同 skill 自己拼路径。
+- 让 repo/spec/project 的规范图片继续按既有路径落盘，再由 helper 复制出聊天专用快照，彻底切断“历史消息依赖可变工作文件”的耦合。
+- 首版故意不做自动清理，优先保证历史聊天图片不会因为误删或复用路径而失真。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：若某个源图没有扩展名，helper 会失败；这是刻意的保守边界，避免生成桌面端不易识别的聊天图片路径。
+- 风险：首版不清理快照目录，长期会积累文件；这是有意识地换取历史消息稳定性。
+- 假设：owner-facing 本地聊天图片主要来自带明确扩展名的 PNG/JPG/WebP/GIF 等常见文件。
+
+## 参考（References）
+
+- `config.toml`
+- `instruction.md`
+- `AGENTS.md`
+- `skills/ui-visual-evidence/SKILL.md`
+- `skills/storybook-screenshots/SKILL.md`
+- `skills/firmware-display-preview/SKILL.md`