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

package/toolkit/skills/docs/vendor/dot-codex/specs/dev-plan-flow-lock-options/SPEC.md

@@ -0,0 +1,74 @@
+# Dev plan flow lock option guidance cleanup
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 之前曾把 `flow_type` 的完整选项列表写成硬约束，并一度把“缺失显式选项”接进 checker，导致 agent 在计划阶段为了自证合规而反复补问或解释 UI 限制。
+- 主人要求的实际目标更简单：在 skill 中强烈建议尽量给出完整 flow 列表，但不得把这件事升级成阻断性契约。
+- 现有 checker 对 `local-merge` 的中文别名支持已经补齐，后续只需保留这一兼容性事实，不再围绕选项完备性增加门禁。
+- 后续 `docs/specs/dev-plan-default-fast-track-auto-lock/SPEC.md` 已接管显式 `$dev-plan` 路径的“无显式 flow 时默认 auto-lock `fast-track`”语义；本 spec 现在只 owner interactive flow 问题本身的选项指导，不再 owner happy-path 默认选路。
+
+## 目标 / 非目标
+
+### Goals
+
+- 把 `dev-plan` 中关于完整 flow 列表的表述收敛成非阻断性建议。
+- 明确 repo 内不再因 `flow_type` 选项数量或展示形式附加额外校验。
+- 保留 checker 对 `本地合主干` / `本地合主干流程` / `local-merge` 的识别。
+
+### Non-goals
+
+- 不修改 `normal-flow`、`fast-flow`、`local-merge-flow` 的业务执行语义。
+- 不改 Codex 内置 `request_user_input` 工具本身。
+- 不新增新的 plan sections 或输出格式要求。
+
+## 范围（Scope）
+
+### In scope
+
+- `docs/specs/README.md`
+- `docs/specs/dev-plan-flow-lock-options/SPEC.md`
+- `skills/dev-plan/SKILL.md`
+- `bin/plan_contract_check.ts`
+- `skills/dev-plan/references/replay-cases/*`
+
+### Out of scope
+
+- 其他 skill 的 wording 清洗
+- 远端 CI / GitHub 流程调整
+
+## 需求（Requirements）
+
+### MUST
+
+- checker 必须把 `本地合主干` 视为 `local-merge` 的合法中文别名。
+- 当显式 `$dev-plan` 确实需要 interactive flow 锁定问题时，必须继续使用 `request_user_input(flow_type)`，但不得因选项数量或 UI 展示形式额外判 invalid；无显式 flow 的 happy-path 默认 auto-lock 由 `docs/specs/dev-plan-default-fast-track-auto-lock/SPEC.md` 单独 owner。
+
+### SHOULD
+
+- `request_user_input(flow_type)` 在条件允许时应尽量覆盖 `implement-only / normal / fast-track / local-merge / multi-task-flow`；其中 `multi-task-flow` 是显式多任务协调的顶层选项。
+- skill 文案应把这件事表达成强烈建议，而不是硬门禁。
+
+## 验收标准（Acceptance Criteria）
+
+- Given `request_user_input(flow_type)` 因歧义/冲突而被触发，且选项标签使用 `本地合主干` When checker 解析问题和回答 Then 必须识别为 `local-merge`。
+
+- Given 更新后的 repo 文案与 checker When agent 读取显式 `$dev-plan` 相关真相源 Then 不应再把完整 flow 列表解释成阻断性要求。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `bun run /Users/ivan/.codex/bin/plan_contract_check.ts /Users/ivan/.codex/skills/dev-plan/references/replay-cases/positive-flow-lock-rui.jsonl`
+- `bun run /Users/ivan/.codex/bin/plan_contract_check.ts /Users/ivan/.codex/skills/dev-plan/references/replay-cases/flow-decision-mismatch-lock.jsonl`
+- `bun run /Users/ivan/.codex/bin/plan_contract_check.ts --cases /Users/ivan/.codex/skills/dev-plan/references/replay-cases/CASES.txt`
+- `git diff --check`
+
+## 风险 / 假设
+
+- 假设：当前 repo 把 `plan_contract_check.ts` 与 replay fixtures 视为 `dev-plan` 契约真相源的一部分。
+
+## Related ADRs
+
+- [0037: Dev-plan Multi-task Flow Routing](../../adr/0037-dev-plan-multi-task-flow-routing.md)

package/toolkit/skills/docs/vendor/dot-codex/specs/dev-plan-goals-first/HISTORY.md

@@ -0,0 +1,93 @@
+# Dev plan goals-first contract rewrite 演进历史（#dvc8g）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- Explicit `$dev-plan` finalization now uses one public `plan_review_view.py` result. Canonical raw-plan validation, projection derivation, and projection invariants resolve together to `pass` or `reject`. New v2 task display metadata stays in `Task Orchestration`. The transient nine-section projection and Mermaid graph are never persisted or reparsed. The boundary and historical JSONL exception are recorded in [ADR 0032](../../adr/0032-dev-plan-single-finalization-gate.md).
+- Review repair: owner-facing batch cards now cover canonical lifecycle metadata. Finalizer reject diagnostics do not echo raw plan content. Legacy input requires exactly one historical plan block, and fenced headings cannot shadow real sections.
+- Review repair: NUL input is rejected before raw checking. Direct profiled tasks and their `[model, effort]` values are retained in the owner view. Task and acceptance-card drift is rejected. Duplicate route sections are rejected. Absolute candidate-root traversal is no-follow, and fenced historical markers are ignored by parser and shell compatibility paths.
+- Follow-up review repair: flow aliases select the canonical Wave Thread parser. Direct-task skill annotations remain visible regardless of position. Accepted arrow-spacing variants cannot silently drop tasks. Non-regular candidate inputs are rejected without blocking. Historical extraction stops at the first valid wrapper close.
+
+- Added a separate plan release arrangement contract for explicit `$dev-plan` delivery flows. The arrangement makes release scope visible before work starts while preserving ADR 0021's runtime-derived route and post-merge release boundary. Historical JSONL is not backfilled; partial adoption is rejected only when a historical explicit `$dev-plan` starts declaring one of the new fields.
+
+- Final plans no longer expose Scope Basis, equivalent authorization/source headings, quoted owner messages, or item-to-source mappings. Scope authorization remains an internal pre-output check; validation and safety limits are represented as `C*` constraints bound to acceptance rather than synthetic Goals, and cannot be promoted into Task Orchestration work.
+
+- 最终计划正文改为通过同一 checker 的 `--plan` 单次自检；fast-track 跨章节 guard 直接阻止“Step 5C 终点”与“禁止或避免创建/复用 PR、远端写入”并存，并要求 live PR、current head 与收敛事实同属一个 `assertions=` 字段；fixtures 不再作为普通规划阶段的必经工作。
+
+- `FAST_TRACK_PR_FORBIDDEN` 同时覆盖 opening/reusing pull request、`No direct PR` 与省略 direct PR delivery 等等价排除，且继续允许明确排除 aggregate / child PR 的 direct delivery 计划。
+
+- 新建 `#dvc8g`，把 `dev-plan` 的 goals-first 合同重写独立成 topic spec，避免挤进 `k4n8p` 或 `r4m7k` 的既有主题范围。
+- 明确“不落盘 plan”是本次改造的硬边界：计划只作为当前回合的临时执行规格，长期真相仍由 spec/solution 承担。
+- 首轮 local-merge review proof 先暴露了 `CASES.txt` 相对路径依赖调用方 cwd 的问题，随后补齐 `run_cases()` 相对路径解析。
+- 第二轮 review proof 又指出：仅要求 section 存在还不足以兑现 goals-first；checker 还需要显式守住章节顺序和持久计划载体禁令，因此追加本轮 follow-up。
+- 追加 follow-up 时，review proof 又发现 persisted-artifact matcher 误伤了普通产品语义（`decision log UI`）；因此把匹配范围缩窄，并新增正例回放防回归。
+- 随后的 review proof 继续指出：缩窄后又漏拦了 plain planning `decision log` artifact；因此补成“planning artifact 命中，但产品 UI/API 语义放行”的双向规则。
+- 再下一轮 proof 发现仅放行 UI/API 仍不够，产品语义还可能表现为 `decision log entries` 这类非 UI 文案；因此进一步收敛为“必须同时命中 planning context 才视为 decision-log artifact”。
+- 最新一轮 proof 继续补齐两个边界：`handoff log` 必须被直接视为持久计划载体，同时 `workflow / task / session` 这类通用产品词不能再单独充当 `decision log` 的 planning context；因此 matcher 改成“显式 handoff log 拦截 + 仅对 planning/future-handoff 语义触发 decision-log artifact”。
+- fresh proof 随后又指出：把 `handoff log` 直接并入通用 artifact object 会误伤普通产品 `handoff log UI/API` 任务；因此进一步改成“`handoff log` 也走 planning-context / future-handoff 判定 + 产品 UI/API safe exemption”，并新增正例回放。
+- 后续 fresh proof 又补出两个漏口：一是清理遗留 `PLAN.md` 引用的任务不应仅因提到路径就被拦；二是 `next-session decision log entries API`、`future handoff log timeline` 这类带时间词的产品能力仍会被误伤。因此 path matcher 改成“路径 + 持久化动作，且排除 cleanup 动作”，同时 decision/handoff-log matcher 改成“显式 planning context 才拦截”，并补齐对应正例回放。
+- 再下一轮 proof 继续抠出两个 contract 缺口：其一，“边清理边新建 `PLAN.md`” 这种 mixed task 不能因为出现 cleanup 动词就绕过禁令；其二，`Acceptance & Validation` 不能接受 `TBD later.` 这类占位文本。因此再次把 path matcher 收紧到“只要出现 `PLAN.md` 路径 + 持久化动作就拦”，并为 acceptance 新增 placeholder-only 拒绝规则与失败样例。
+- 最新一轮 proof 又指出两类普通产品语义仍会误伤：一是泛化的 `plan file` 产品能力，二是 `agent decision log` 这种 agent-facing 功能词。因此继续缩窄 matcher：移除通用 `plan file` object 命中，并把 `agent` 从 decision-log planning context 中拿掉，同时补齐对应正例回放。
+- 最新 follow-up proof 又补出两个新边界：其一，`timeline/history/entries` 这类普通名词不能单独充当 planning artifact 的安全豁免，否则 `create decision log timeline for the next planning handoff`、`create handoff log history for the next agent session` 会漏拦；其二，placeholder matcher 不能把具体验收里的 `Pending ...` 误判成占位。因此 safe matcher 再次收紧到“需命中明确产品 surface 才放行”，同时把 placeholder 词表缩窄到真正的 filler 短语，并补齐对应正反例回放。
+- 随后 fresh proof 又指出两个更朴素的 contract 漏口：一是 `create decision log for future work`、`create handoff log for future work` 这类 plain planning artifact 仍会因缺少显式 `plan` / `agent session` 关键词而漏拦；二是 `Acceptance & Validation` 只有空 bullet (`-`) 时也会被当成有效内容。因此再次扩展 planning-context matcher 到 `future work / next work / follow-up` 语义，并把空 bullet 归类为 `ACCEPTANCE_EMPTY`，同时补齐对应失败样例。
+- 最新 proof 又抠出两类新的产品误伤：其一，处理用户上传 `PLAN.md` 文件的产品能力不应被 path matcher 当成 persisted plan artifact；其二，`agent handoff log exporter/worker` 这类 agent-facing handoff-log 功能不应因为包含 `agent` 一词就被当成 planning handoff log。因此继续为 `PLAN.md` 路径加入产品文件支持豁免，并把 handoff-log planning context 从泛化 `agent` 收紧到 `agent session` 等明确 planning 语义，再补两条正例回放防回归。
+- 最新 fresh review proof 又补出两类仍未覆盖的产品语义：其一，`update the importer to accept customer-provided PLAN.md` 这类 importer / consumer / processor wording 仍会被 `PLAN.md` path matcher 误拦；其二，`create the CSV exporter for next-session decision log entries` 这类 exporter / job / integration wording 仍会被 decision-log matcher 误判成 planning artifact。因此再次扩展产品 surface safe matcher，并补齐 importer/exporter 两条正例回放。
+- 最新 fresh review proof 随后又指出两个反向漏口：safe matcher 放得过宽，会让 `write PLAN.md handoff job for future sessions`、`create a decision log job for future handoffs` 这类 planning artifact 被错误放行；同时 action matcher 只覆盖 `write/create/update` 一类动词，导致 `generate` / `keep` 变体漏拦。因此再次收窄 safe exemption，并补齐动作词与对应失败样例。
+- 再下一轮 fresh review proof 继续指出三个结构漏口：其一，generic `workflow/pipeline` wording 仍会让 planning decision/handoff-log artifact 漏拦；其二，goal detail 只写 `TBD` / `待确认` 这类占位词也会通过；其三，`Acceptance & Validation` 只有 `Notes` / `Follow-up items` 这类标签文本时也会通过。因此再次把 `workflow/pipeline/job` 纳回 planning context，补齐 goal placeholder 与 acceptance label-only 拒绝规则，并新增对应失败样例。
+- 最新 fresh local-merge proof 又补出两类 persisted-plan matcher 偏差：其一，普通产品 `progress log` UI/API 任务被误判成 planning artifact；其二，`move generated PLAN.md into a shared handoff folder` 这类搬运式维持动作仍然漏拦。因此把 `progress log` 改成仅在 planning context 下拦截，并把 `move/copy/rename/archive` 等动作纳入 persisted-artifact action matcher，同时补齐正反例。
+- 最新 fresh local-merge proof 再次补出三类剩余漏口：其一，`prepare/setup handoff log` 这类常见 planning 动词仍会绕过 persisted-artifact matcher；其二，`Non-goals` 只写 `TBD` / `待确认` 也会通过；其三，`Goals` / `Acceptance & Validation` 里的 `TBA` / `TBC` 占位文本还没被视为 placeholder。因此继续扩展动作词与 placeholder 集，并补齐对应失败样例。
+- 再下一轮 fresh local-merge proof 指出 `PLAN.md` 的 product-safe 例外仍过宽：`create/update PLAN.md with implementation steps` 会被误当成普通产品文件操作通过。因此继续收紧 `PLAN.md` product-safe matcher，要求出现明确的产品文件/API/importer/upload 语义锚点，并补两条对应失败样例。
+- 随后的 fresh local-merge proof 又指出 `decision log` 的 product-safe surface 还缺 `plan templates` 这一类真实产品面，导致 “record workflow decision log history when users edit plan templates” 被误判成 planning artifact。因此继续把 `template/templates` 纳入 product-safe surface，并补一条对应正例样本。
+- 再下一轮 fresh local-merge proof 进一步指出 `handoff log` 在同类 `plan templates` 产品句式下也会被误伤，例如 “create agent handoff log history when users transfer plan templates”。因此继续把 `plan template(s)` 提升为 `decision log / handoff log` 的显式 product-safe surface，并补一条 handoff-log 正例样本。
+- 最新 fresh local-merge proof 又指出一个纯结构漏口：`## Goals` 里的空 bullet (`- `) 会被当成“存在 goal”，从而绕过 goals-first 合同。因此继续把 goal 校验改成“空 title 直接报错 + 仅非空 goal 才计入有效数量”，并补一条专门的失败回放。
+- 最新 fresh local-merge proof 随后又指出 persisted-plan artifact 动作仍偏写入导向：generic `read/open PLAN.md for next handoff context` 会直接通过，等于允许通过“读取旧计划”重引入持久计划依赖。因此继续把 `read/open/load/view/inspect` 纳入 artifact action matcher，并补一条对应失败回放。
+- 紧接着的 fresh local-merge proof 又指出 `PLAN.md` path matcher 的 planning-context 兜底里，泛化 `review` 会误伤真实产品任务：像 “add support for user-uploaded PLAN.md documents in import API and review page” 会因为 `review` 一词被当成 planning context。于是继续把 `review/审查` 从该 path-level planning-context 中移除，并补一条 import/review-page 正例回放。
+- 最新 fresh local-merge proof 又把 goals-first 的另外两个空洞补了出来：`Summary` 与 `Non-goals` 仍然只按 bullet 标记计数，所以单独一个 `- ` 也能假装成有效必选章节。因此继续把两处检查都改成“至少一条非空 bullet”，并让空 non-goals bullet 单独报错，再补两条对应失败回放。
+- 随后的 fresh local-merge proof 又指出 path-level planning-context 还是偏宽：即使是 `update the planning UI and import API to accept user-provided PLAN.md documents` 这种明显产品任务，也会因为 `planning` 一词被当成 persisted-plan planning context。于是继续把 `planning / 计划` 从 `PLAN.md` path 规则的覆盖条件里拿掉，只保留真正的 handoff/future/turn/wave 续推语义，并补一条 planning-UI 正例回放。
+- 最新 fresh local-merge proof 继续补出一个更细的结构绕过：`Summary` / `Goals` / `Non-goals` 里的 bare dash（单独一行 `-`）会因为 bullet 提取只剥 `- ` 而被误算成非空内容。于是把三处 bullet 归一化统一改成 `^-\\s*` 剥离，并把对应失败样例改成 bare-dash 形态，确保空 bullet 无论是否带尾随空格都不能绕过。
+- 最新 fresh local-merge proof 又指出 `skills/dev-plan/SKILL.md` 的 Operational Runbook 把 checker / replay 命令改成了相对路径，这会在 skill 从普通项目 cwd 调用时失效。因此把 runbook 命令重新锚到 `${CODEX_HOME:-$HOME/.codex}`，既保留 goals-first 语义，又恢复任意 caller cwd 下的可执行性。
+- 最新 fresh local-merge proof 继续补出 `Non-goals` placeholder 的另一个空洞：`- None`、`- N/A` 这类“没有排除项”的空语义文本不会命中现有占位词表，从而让计划在未声明任何具体 non-goal 时通过 checker。因此把 `none / n/a / no exclusions / 无` 一类表达纳入 `NON_GOAL_PLACEHOLDER`，并补一条 `non-goals-none-placeholder` 失败回放。
+- 主人发现内置 Plan Mode 生成的计划经常偏英文；根因是全局 `instruction.md` 虽有“默认简中”，但 `dev-plan` 的硬合同、示例与基础 replay 正例大量使用英文正文。因此在不改 checker 英文章节名的前提下，把 skill 语言规则收敛为“自然语言正文默认简体中文，机器合同 token 保持原文”，并把基础正例改成中文正文。
+- initiative-flow review 发现 aggregate plan 的 `integration_branch` 原先接受大写和下划线，而 Ticket envelope 只接受 lowercase kebab-case topic。为避免计划通过后才在 handoff 失败，两个阶段统一为 `prd/<lowercase-kebab-case-topic>`。
+- 将 Ticket 重规划门禁收敛到显式 `sub-agent:ticket` executor，避免普通 direct 任务仅因描述中出现 Ticket 或 Issue 就被误判为已继承计划的 Ticket 执行。
+- 将 executor 层级收敛为 `main-agent`、`sub-agent:<name>` 与 Initiative 顶层 `task:<name>`；新增紧凑 model/effort profile，保留旧格式仅供 recovery 读取，避免把独立 task 容器误标成 sub-agent。
+- 补充 repository-local Skills 索引检查，保证新增 flow skill 与配套工具在索引中可发现且不会重复登记。
+
+- Review follow-up 收紧 sub-agent 只读边界：多词 implementation imperative 不再漏过，`git stash list/show` 等纯检查命令不会被误判为写入，并为两类边界补充 replay evidence。
+
+## Key Reasons / Replacements
+
+- 将自由文本验收升级为逐项 manifest，是为了让执行 receipt 与 Step 5C 能证明计划中的每个验收项，而不是增加新的 review lane 或验证轮次。
+- 最终 receipt 收口保持同一成本边界：验收闭环复用既有 test-platform lane 与 merge proof，高风险项只收紧为单一 direct receipt。
+
+- Initiative delivery 继续复用同一份批准的 `$dev-plan`，但已从 topology 组合改为独立顶层 flow，避免每个 Ticket 重新进入 Plan Mode 或制造第二份计划真相。
+- `$initiative-flow` 与 `$fast-flow` 现为平级互斥；旧组合只为已锁定 session 提供只读恢复兼容。
+
+- 实施阶段额外把 repo-local replay case 路径改成相对路径，并同步让 `run_cases()` 按 `CASES.txt` 目录解析这些路径；这样隔离 worktree 与 repo 外绝对调用都能命中新 checkout，而归档 session 继续保留绝对路径。
+
+- `k4n8p` 只处理 flow lock 选项指导；`r4m7k` 只处理 fast-track closeout。两者都不足以承接本次 section contract 改写，因此创建独立后继 topic。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#dvc8g`.
+
+## Related Changes
+
+- Successor decision recorded in [ADR 0024](../../adr/0024-stop-condition-driven-release-decision.md): the earlier plan-level release arrangement is historical only. New plans use existing sections, while Step 5C runtime derives a decision card and requires explicit owner confirmation including the version expectation before merge continuation.
+
+- Added `release-planning-short-contract.md`, ADR 0023, and the `release_scope` / `release_reason` / `release_entrypoint` / `release_followup` raw-plan contract with scope-specific replay coverage.
+
+- Added the direct-plan `release_disposition` contract and linked ADR 0019; pre-merge routing remains separate from post-merge release facts.
+
+- Replaced the owner-facing plan field with runtime-derived pre-merge route resolution; repositories without an applicable release policy use `no-managed-route` without blocking PR publication. See ADR 0021.
+
+- Scope authority and topic Spec boundaries are recorded in [ADR 0004](../../adr/0004-scope-authority-and-topic-spec-boundaries.md); the final-plan boundary is refined by [ADR 0006](../../adr/0006-internal-plan-authorization-and-scope-constraints.md).
+- Current plan and PR associations belong in this section rather than the normative `SPEC.md`.
+- The canonical topic-Spec checker now rejects execution, status, PR-list, command-list, and unresolved-decision section headings while preserving workflow prose as requirements context.
+
+## Wave Thread 移除
+
+删除旧协调合同的读取、回放、派发与专属 Profile，现行 Spec 不再承诺历史 Wave Thread 兼容。历史直接流程的 JSONL 校验继续保留。

package/toolkit/skills/docs/vendor/dot-codex/specs/dev-plan-goals-first/IMPLEMENTATION.md

@@ -0,0 +1,131 @@
+# Dev plan goals-first contract rewrite 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: `dev-plan` 已切到 goals-first、non-persistent contract，checker 与 replay fixtures 已同步
+- 显式 `$dev-plan` 现在通过 `bin/plan-cli.sh` 将 canonical raw-plan 校验和 owner-facing projection 校验收敛为一个 `pass/reject` 结果；raw checker 只承担底层诊断，不再单独代表最终成功。
+- 新 v2 task 在 `Task Orchestration` 中声明 `title`、`purpose` 和 `outputs`。 Projection 从同一份解析事实生成九段审阅视图与 Mermaid 波次/依赖图，不创建第二份执行 manifest。
+- Projection 的 `任务卡` 同时展示 canonical task 和 batch 生命周期字段。`验收清单` 按合并前后阶段生成独立验收卡片，覆盖所有 canonical acceptance ID；长断言和证据按语义单元自然换行，不再依赖多列长文本表格，并在最终化时拒绝事实漂移。拒绝诊断不回显 raw-plan 原文，历史 JSONL 要求单一 `proposed_plan` block，章节提取忽略 fenced heading。
+- The finalizer now rejects NUL input before raw checking. It preserves direct `[model, effort]` task lines in the owner view. It rejects duplicate route-driving sections, traverses candidate roots component-by-component without following symlinks, and ignores fenced proposed-plan markers in both historical parser and JSONL validation.
+- Follow-up boundary repairs preserve direct-task skills; retired coordinator aliases are rejected. They cover optional direct-task arrow spacing without silently dropping tasks. They reject non-regular projection inputs before reading and stop historical wrapper extraction at the first valid closing marker while rejecting extras.
+- The latest repair closes the remaining v2 guard bypass. Canonical task display metadata now receives Constraint-reference and persisted-plan-artifact checks. The historical direct-plan parser and shell JSONL route share the same whitespace-tolerant wrapper boundary and ignore no contract data outside the proposed-plan block. FIFO coverage now uses a platform-neutral temporary root.
+
+## Pre-merge release decision
+
+- New plans keep release behavior in existing sections and do not add retired plan-level arrangement fields, new stop-condition values, or a final version string.
+- At Step 5C, runtime reads the target repository policy and current PR facts and returns a decision card covering publish applicability, components, channel, bump rule, predicted version, target identity, policy source, and collision policy. Route absence is routing-only and is not a no-release decision.
+- `merge-only` and `merge+cleanup` lock the target repo/branch, base-tag source, bump rule, channel, components, collision policy, and merge-SHA binding as an executable rule. Owner confirmation must include the version expectation before merge continuation.
+- After merge, `release_expected` and actual version/tag/artifact facts are evaluated only from `target_repo + target_branch + merge_sha`; missing or conflicting facts remain unknown/blocked.
+
+## Coverage / rollout summary
+
+- `skills/dev-plan/SKILL.md` 已改为 goals-first section contract，并显式禁止持久 `plan` 载体。
+- `skills/dev-plan/SKILL.md` 已明确 `<proposed_plan>` 自然语言正文默认使用简体中文，同时保留 required section 标题、固定字段、`flow_type` 值、executor、`$skill` 引用、命令、路径、代码标识符、日志与错误文本的原文。
+- `skills/dev-plan/SKILL.md` 已明确 canonical raw-plan 通过后才生成 owner-facing projection。 Projection 固定为九段视图和 Mermaid 波次/依赖图。
+- `bin/plan-cli.sh` 已加入 stdout-only 的 tool-root-bound projection 路由；普通项目使用可信安装入口和 stdin，dot-codex 开发使用当前候选入口及配套 checker。它拒绝 proposed-plan wrapper、历史 JSONL、重复 machine registry、projection section drift 和缺失 Mermaid graph。
+- `bin/plan_contract_check.ts` 已新增 `Summary / Goals / Non-goals` 相关门禁，同时保留既有 flow lock、wave/task、skill binding 与 implement-only 禁止项。
+- `bun run bin/plan_contract_check.ts --plan <file|->` 已直接检查最终 Markdown，并复用既有章节/合同校验；fast-track 的 Non-goals 与验收会跨章节校验 required PR delivery path、live PR、current head 和 Step 5C convergence，三项交付事实必须位于同一条 `assertions=` 中；其中每个 assertion unit 独立判定正向性，允许同字段同时记录“Step 4 without PR 被拒绝”的反例，并拦截创建、打开、复用或省略 direct PR delivery 的等价排除表述，同时保留 aggregate / child PR exclusion 的 direct delivery 豁免。
+- `bin/plan_contract_check.ts` 现已额外校验 required section order，并拒绝 `Task Orchestration` 中的持久计划载体任务。
+- `bin/plan_contract_check.ts` 现已为显式 `$dev-plan` 的五类交付 flow 校验发布安排字段，并为 included/deferred/not-applicable 提供稳定 finding codes；历史 JSONL 未声明新字段时保持兼容。
+- executor/profile contract now distinguishes Initiative `task:<name>` containers from read-only `sub-agent:<name>` children, validates supported model/effort pairs, and preserves old unprofiled sub-agents only through explicit recovery mode.
+- read-only validation covers Chinese and English workspace/worktree plus task-local/filesystem write declarations, splits contradictory clauses, and preserves native `$review-agent` high-requirement reviews as `gpt-5.6-sol, medium`; legacy `$codex-review-loop` bindings are rewritten during migration.
+- persisted-plan artifact matcher 已细化：既能拦截 planning `decision log` / `handoff log` artifact 与混合式 `remove ... and create ... PLAN.md` 任务，又不会把普通产品语义（如 `decision log UI`、`workflow decision log entries`、`next-session decision log entries API`、`agent decision log export API`、`handoff log UI/API`、`future handoff log timeline`、`plan file upload API`）或纯清理遗留 `PLAN.md` 引用的任务误判成 plan artifact。
+- `Acceptance & Validation` 现已拒绝 placeholder-only 文本（如 `TBD later.`），不再把任意非空占位行当作有效验收。
+- persisted-plan artifact safe matcher 进一步收紧为“必须命中明确产品 surface（如 `UI` / `page` / `API` 等）才可豁免”，避免 `decision log timeline for the next planning handoff`、`handoff log history for the next agent session` 这类带 `timeline/history` 的 planning artifact 因普通名词误放行。
+- `Acceptance & Validation` placeholder matcher 已继续缩窄：仍会拒绝 `TBD later.`、`pending validation` 一类占位表达，但不再把 `Pending jobs remain visible in the queue after refresh.` 这种具体验收误判为 placeholder。
+- `decision log` / `handoff log` artifact matcher 现已额外覆盖 `future work`、`next work/session/handoff`、`follow-up` 等 plain planning 语义，避免 `create decision log for future work`、`create handoff log for future work` 这类无显式 `plan` 字样的持久 planning artifact 漏拦。
+- `Acceptance & Validation` 现已把仅含空 bullet（如单独一行 `-`）视为无效内容；空 bullet 不再能绕过“至少一条可观察验收”门禁。
+- `PLAN.md` / `PLANS.md` path matcher 已加入产品文件支持豁免：当任务明确是在处理用户上传、导入、接受或读取这类产品文件能力时，不再误判为 persisted plan artifact；但真正的 `PLAN.md` 落盘/维护任务仍会被拦截。
+- `handoff log` matcher 已收紧为“future/next/follow-up/agent session” 等 planning 语义，而不再把泛化 `agent handoff log exporter/worker` 这类 agent-facing 产品能力误判成 planning artifact。
+- persisted-plan artifact safe matcher 现已继续放宽到 importer / consumer / processor / exporter / job / integration / connector / pipeline 等产品 surface，因此 `update the importer to accept customer-provided PLAN.md` 与 `create the CSV exporter for next-session decision log entries` 这类正常产品任务不再被误判；plain planning artifact 失败样例仍保持拦截。
+- persisted-plan artifact safe matcher 现已再次收窄：`job / workflow / pipeline` 不再单独充当 safe exemption，且 `PLAN.md` path safe 只在无 planning context 时生效；这样 `write PLAN.md handoff job for future sessions`、`create a decision log job for future handoffs` 这类 planning artifact 会重新被拦截，而 importer / exporter / API 等正例仍保持通过。
+- persisted-plan artifact 动作 matcher 现已补齐 `generate / initialize / keep`，因此 `generate a handoff log for future sessions` 与 `keep a handoff log for future sessions` 这类 planning artifact 不再漏拦。
+- decision/handoff-log matcher 现已把 generic `workflow / pipeline / job` 重新视为 planning context，但同时把 `entries` 加回 product-safe surface，避免 `workflow decision log entries` 这类产品语义被误伤。
+- `Goals` 检查现已拒绝 placeholder-only detail（如单独 `TBD` / `待确认`）；只有出现至少一条非占位的具体 detail，goal 才算满足新合同。
+- `Acceptance & Validation` 现已拒绝 label-only 文本（如单独 `Notes`、`Follow-up items`、`备注`）；只有出现非占位、非标签式的真实验证说明才计入 meaningful acceptance。
+- persisted-plan artifact matcher 现已把 `progress log` 从无条件 planning-object 匹配里拆出，改成“只有带 planning context 且不带 product-safe surface 时才拦截”，因此普通 `progress log UI/API` 功能不会再被误伤。
+- persisted-plan artifact 动作 matcher 现已继续补齐 `move / copy / rename / relocate / archive` 等搬运式维持动作，因此“把 `PLAN.md` 移到未来 handoff 目录”这类变体不再漏拦。
+- persisted-plan artifact 动作 matcher 现已继续补齐 `prepare / setup / set up` 等准备类动词，因此“prepare handoff log for next session”这类 planning artifact 不再漏拦。
+- `PLAN.md` / `PLANS.md` 的 product-safe matcher 现已从“动作 + 路径即可放行”收紧为“动作 + 产品锚点 + 路径”或“路径 + 文件/内容锚点 + user/upload/product 语义”；因此 `create/update PLAN.md with implementation steps` 这类泛化维护动作不再被误放行。
+- persisted-plan artifact 动作 matcher 现已补齐 `read / open / load / view / inspect`，因此 generic `read/open PLAN.md for next handoff context` 这类“读取持久计划”的执行安排也会被拦截；只有命中产品文件/API/importer 语义锚点时才可放行。
+- `PLAN.md` path matcher 的 planning-context 豁免判定已不再把泛化 `review` / `审查` 视为强 planning 语义；这样带 `review page` 的产品导入/展示任务会继续走 product-safe 放行，而不会因为 UI wording 被误拦。
+- `PLAN.md` path matcher 的 planning-context 豁免判定现已进一步移除泛化 `planning / 计划`；只剩 handoff / future / next / wave / turn 一类真正的执行续推语义会覆盖 product-safe 例外，因此 `planning UI + import API + user-provided PLAN.md` 这种产品任务不会再被误拦。
+- `decision log` / `handoff log` 的 product-safe surface 现已补齐 `template / templates`，因此产品 `plan templates` 场景里的 decision-log history 不会再因为包含 `plan` 而被误当成 planning context。
+- 对 `decision log` / `handoff log` 的 product-safe matcher 现已进一步显式识别 `plan template(s)`，并放宽到足以覆盖 “log history ... plan templates” 这类真实产品句式，而不需要整体放宽 `workflow/job/plan` planning-context 规则。
+- `Goals` 检查现已拒绝空 bullet（如单独 `- `）；空 goal title 会直接报错，且不会再被误计为有效 goal 项。
+- `Summary` 与 `Non-goals` 检查也不再只看 bullet 标记数量；空 bullet 现在不会充当有效摘要或有效排除项，空 `Non-goals` bullet 会直接报错。
+- `Non-goals` 检查不再只看 bullet 数量；placeholder-only bullet（如 `TBD` / `待确认`）现在会被显式拒绝。
+- `Goals` 与 `Acceptance & Validation` 的 placeholder matcher 现已补齐 `TBA / TBC` 等常见缩写，避免占位文本绕过现有 `TBD/TODO` 检查。
+- replay fixtures 已批量切到新结构，并新增 `missing-goals`、`missing-non-goals`、`goals-empty-orchestration-only`、`goal-without-detail`、`invalid-section-order`、`persisted-plan-artifact-in-orchestration`、`mixed-plan-cleanup-create-artifact`、`decision-log-artifact-in-orchestration`、`handoff-log-artifact-in-orchestration`、`placeholder-acceptance` 失败样例，以及 `positive-normal-decision-log-ui`、`positive-normal-decision-log-entries`、`positive-normal-handoff-log-ui`、`positive-normal-plan-md-cleanup`、`positive-normal-next-session-decision-log-api`、`positive-normal-future-handoff-log-timeline`、`positive-normal-plan-file-upload-api`、`positive-normal-agent-decision-log-api` 正例。
+- `positive-normal`、`positive-fast-track` 与 `positive-implement-only-pure` 三个基础正例已切为中文正文，继续保留英文机器合同标题与固定 token。
+- replay fixtures 已追加 `decision-log-timeline-planning-handoff-artifact`、`handoff-log-history-agent-session-artifact` 两个失败样例，以及 `positive-normal-pending-state-acceptance` 正例，专门守住这轮 review 暴露的两类回归。
+- replay fixtures 已继续追加 `decision-log-future-work-artifact`、`handoff-log-future-work-artifact` 与 `blank-acceptance-bullet` 失败样例，守住 plain future-work planning artifact 与空验收 bullet 两个新增边界。
+- replay fixtures 现已继续追加 `positive-normal-plan-md-user-upload`、`positive-normal-plan-md-importer`、`positive-normal-agent-handoff-log-exporter` 与 `positive-normal-next-session-decision-log-exporter`，防止产品文件支持、importer/exporter 产品 surface 与 agent-facing handoff-log 功能再次被误伤。
+- replay fixtures 现已继续追加 `plan-md-handoff-job-future-sessions-artifact`、`decision-log-job-future-handoffs-artifact`、`generate-handoff-log-future-sessions-artifact` 与 `keep-handoff-log-future-sessions-artifact`，守住 safe exemption 过宽与 action verb 过窄两类 false-negative 回归。
+- replay fixtures 现已继续追加 `decision-log-workflow-artifact`、`handoff-log-pipeline-artifact`、`goal-placeholder-detail`、`acceptance-notes-only` 与 `acceptance-follow-up-items-only`，守住 generic workflow/pipeline wording、goal 占位 detail 与 acceptance 标签文本三类回归。
+- replay fixtures 现已继续追加 `move-plan-md-handoff-artifact` 与 `positive-normal-progress-log-ui`，分别守住“搬运 persisted `PLAN.md` 仍应被拦截”与“产品 `progress log` 功能不应被误伤”两类边界。
+- replay fixtures 现已继续追加 `prepare-handoff-log-next-session-artifact`、`non-goals-placeholder`、`acceptance-tba-only` 与 `goal-tba-detail`，分别守住准备类 planning artifact、`Non-goals` 占位 bullet，以及 `TBA/TBC` 占位文本两类回归。
+- replay fixtures 现已继续追加 `create-plan-md-implementation-steps-artifact` 与 `update-plan-md-implementation-steps-artifact`，守住“generic PLAN.md create/update wording 被 product-safe 例外误放行”的回归。
+- replay fixtures 现已继续追加 `read-plan-md-handoff-context-artifact`，守住“generic PLAN.md read/open wording 重新引入持久计划依赖”的回归。
+- replay fixtures 现已继续追加 `positive-normal-plan-md-import-review-page`，守住“product-safe PLAN.md import/review page wording 被弱 planning `review` 误伤”的回归。
+- replay fixtures 现已继续追加 `positive-normal-plan-md-planning-ui-import`，守住“product-safe PLAN.md import/UI wording 被泛化 `planning/计划` 误伤”的回归。
+- replay fixtures 现已继续追加 `positive-normal-plan-template-decision-log-history`，守住“产品 plan templates 场景的 decision-log history 被 planning-context 误伤”的回归。
+- replay fixtures 现已继续追加 `positive-normal-plan-template-handoff-log-history`，守住“产品 plan templates 场景的 handoff-log history 被 planning-context 误伤”的回归。
+- replay fixtures 现已继续追加 `goal-blank-bullet`，守住“空 goal bullet 被误计为有效 goal 项”的结构回归。
+- replay fixtures 现已继续追加 `summary-blank-bullet` 与 `non-goals-blank-bullet`，守住“空 Summary / Non-goals bullet 伪装成有效必选章节”的结构回归。
+- goals-first blank-bullet 守卫现已进一步覆盖 bare dash 变体：`Summary`、`Goals`、`Non-goals` 中单独一个 `-` 不再被当成非空内容，相关失败样例也已切到 bare-dash 形态防回归。
+- `skills/dev-plan/SKILL.md` 的 Operational Runbook 现已切回 `CODEX_HOME` 锚定命令，避免 skill 从任意项目 cwd 调用时找不到 `bin/plan_contract_check.ts` 与 bundled replay set。
+- 普通规划只执行一次 raw-plan 检查；只有 checker/fixture implementation 变更的验收阶段才运行完整 `--cases`，避免把 fixture 回放加入每次计划成本。
+- `Non-goals` placeholder 守卫现已继续覆盖 `None`、`N/A`、`no exclusions` 一类“没有排除项”的空语义文本，并新增 `non-goals-none-placeholder` 回放防回归。
+- `run_cases()` 已改为按 `CASES.txt` 所在目录解析相对 fixture 路径，因此从 repo 外以绝对 `CASES.txt` 路径执行也能稳定通过。
+- `skills/implement-only-flow/SKILL.md` 已改为通过 `Goals / Non-goals` 表达范围边界。
+- 新计划只输出一个顶层 `flow_type`；checker 拒绝 `delivery_topology` 和双 flow 绑定。
+- Initiative 被 checker 强制要求 `prd/<topic>` integration branch、risk-gated child merge、owner-explicit final merge 与 Ticket 继承批准计划，并只绑定 `$initiative-flow`。
+- planner replay 已覆盖新 fast-track、Initiative、显式 normal、非法混用，以及 recovery-only legacy aggregate。
+- 当前计划合同只接受 V5 入口；旧会话与旧代际合同不再读取、迁移或恢复。
+- repository-local Skills 索引已由 `bin/skills_index_check.ts` 进行可执行校验，确保新增流程入口不会只存在于文档而遗漏索引。
+- v2 profile-bearing task lines now remain in canonical facts and share the full planning-artifact guard set. They reject malformed direct raw-plan fences. Legacy wrapper validation ignores malformed fences outside the wrapper, and projection text neutralizes bare URL autolinks. Shell/Python heading and CRLF handling remains aligned. Product tasks that import user-provided `PLAN.md` content are excluded from the persisted-plan-artifact guard. Direct finalizer calls with unencodable input return a stable rejection finding.
+- Flow Decision routing now shares unfenced, indentation-tolerant parsing across the shell checker, Python finalizer, and flow-continue replay checker.
+- The finalizer now validates the unresolved candidate entrypoint, imported contract modules, and raw checker path component by component. Symlinked source paths are rejected before candidate execution can escape into runtime or another checkout.
+
+- read-only matcher 现已拒绝 `implement the bug fix` 等多词 implementation assignment，同时允许 `git stash list/show` 等纯检查命令；对应边界已加入 replay fixtures。
+
+## Remaining Gaps
+
+- None currently tracked after the review-driven checker follow-up.
+
+## Scope Constraint Coverage
+
+- `bun run bin/plan_contract_check.ts --plan` rejects provenance sections and their source/authorization-heading variants, quoted owner messages, and owner-source mappings in final plans.
+- The checker validates optional `C*` constraint ids and their links to existing `A*` acceptance items, and rejects Task Orchestration references to declared constraints.
+- No persistent plan, authorization trace, scope ledger, or Task Evidence Set artifact is created by the implementation.
+
+## Acceptance Manifest
+
+- 新计划使用稳定 ID、类别、证据模式、验证目标和关键断言；checker 可输出规范化 manifest。
+- 历史 replay set 保持显式 legacy acceptance 解析，新输出和少量 strict unit cases 使用完整映射。
+- receipt 侧已验证 manifest 强制绑定、当前 SHA closure 与高风险单 receipt direct evidence；未增加 checker replay 或模型验证轮次。
+
+## Related Changes
+
+- `docs/specs/README.md`
+- `docs/adr/0030-dev-plan-single-source-wave-thread.md`
+- `docs/specs/dev-plan-goals-first/SPEC.md`
+- `skills/dev-plan/SKILL.md`
+- `bin/plan_contract_check.ts`
+- `skills/dev-plan/references/replay-cases/*`
+- `skills/implement-only-flow/SKILL.md`
+- `skills/initiative-flow/SKILL.md`
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`
+
+## Wave Thread 移除边界
+
+Wave Thread 的 Skill、专属历史读取、旧状态机、回放、CLI 与三档任务 Profile 已移除。现行共享多任务解析器保留独立合同；其他直接流程的历史 JSONL 校验不受此移除影响。

package/toolkit/skills/docs/vendor/dot-codex/specs/dev-plan-goals-first/SPEC.md

@@ -0,0 +1,200 @@
+# Dev plan goals-first and scope constraints
+
+## Context and Scope
+
+This topic defines the explicit `$dev-plan` output contract. It covers temporary plan structure, internal scope-authority checks, and validation boundaries. Native Plan Mode without an explicit `$dev-plan` invocation remains outside this contract.
+
+## Terms and Interfaces
+
+- `Scope Authority`: the Agent's internal check that a material Goal or Non-goal is authorized by a concrete owner request or a valid current Spec/ADR statement.
+- `Plan Constraint`: a `C*` condition that narrows an authorized Goal or `A*` acceptance without authorizing new scope.
+- `Material claim`: a Goal, Non-goal, acceptance assertion, or process gate that changes scope, behavior, evidence, or delivery authorization.
+- `Release Decision Card`: the runtime Step 5C result derived from target repository policy and current PR facts. It is not a plan field or post-merge release evidence.
+- Interface: canonical raw-plan Markdown validated by `bun run bin/plan_contract_check.ts --plan -`; explicit `$dev-plan` final output is produced by the trusted `bin/plan-cli.sh` launcher and wrapped once in `<proposed_plan>`.
+
+## Requirements
+
+### REQ-DEVPLAN-001
+
+An explicit `$dev-plan` MUST emit `Summary`, `Flow Decision`, `Goals`, `Non-goals`, `Task Orchestration`, `Acceptance & Validation`, and `Assumptions/Defaults` in that order. When a condition limits validation or delivery, it MUST emit `Constraints` after `Goals` and before `Non-goals`.
+
+### REQ-DEVPLAN-002
+
+Before emitting a plan, the Agent MUST perform Scope Authority analysis without asking the owner to locate or restate sources. Repository evidence, model inference, a generic approval, a rejection of an earlier proposal, or a validation condition MUST NOT independently authorize a material Goal, Non-goal, artifact, external action, or delivery obligation.
+
+### REQ-DEVPLAN-003
+
+Final plan text MUST NOT include a `Scope Basis`, an equivalent source/authorization/provenance heading, direct quotations of owner messages, or a mapping from plan items to their conversation, contract, ADR, derivation, or flow provenance. The plan MUST remain a temporary execution specification and MUST NOT create a persistent plan ledger.
+
+### REQ-DEVPLAN-004
+
+When present, every Constraint MUST use a stable `C*` id and bind to one or more existing `A*` acceptance items. A Constraint qualifies an authorized Goal or acceptance only; it MUST NOT be the sole basis for a Task Orchestration item or a new implementation mechanism. Task Orchestration MUST NOT reference a declared `C*` id. The checker MUST reject provenance sections or mappings, malformed constraints, duplicate constraints, constraints that reference unknown acceptance items, and task items that reference a declared Constraint.
+
+### REQ-DEVPLAN-005
+
+Flow-specific process contracts MUST remain owned by the selected flow skill. A default fast-track plan MUST retain its live PR, current-head, and Step 5C convergence assertions; a Constraint MUST NOT turn a flow gate into product scope.
+
+### REQ-DEVPLAN-006
+
+Direct `normal`, `fast-track`, and `local-merge` plans MUST NOT require an owner-supplied release disposition. The pre-merge release route MUST be derived at publication time from current repository and PR facts. When no explicit valid repository contract or adopted project-local Policy exposes a managed route, the resolver MUST return `no-managed-route` with no managed release labels and publication MUST continue. The route MUST NOT determine post-merge `release_expected`, version, tag, or publication evidence.
+
+### REQ-DEVPLAN-007
+
+New plans MUST express release behavior through the existing `Flow Decision`, `收口条件`, `Assumptions/Defaults`, and `Acceptance & Validation` sections. They MUST NOT add plan-level release arrangement fields, release stop-condition values, or a final version string. For a Step 5C stop, the plan MUST make the runtime Agent default decision card displayable: publish applicability, components, channel, bump rule, predicted version, target identity, and policy source are named as runtime outputs. For `merge-only` and `merge+cleanup`, the existing prose MUST state the complete executable rule and locked inputs: target repository/branch, base-tag source, bump rule, channel, components, collision policy, and merge-SHA binding. The plan MUST never turn a predicted version into a prefilled final version.
+
+The runtime MUST require explicit owner confirmation of the Step 5C card, including the version expectation, before merge continuation. Missing or conflicting policy/facts MUST resolve to unknown/blocked; an absent `no-managed-route` result MUST NOT be interpreted as no release. After merge, `release_expected` MUST be derived only from actual `target_repo + target_branch + merge_sha` facts and actual version/tag/artifact identity. 其他直接流程的历史 JSONL 和历史文档继续作为兼容输入或证据保留，不定义新计划语法；Wave Thread 合同不再受支持。
+
+### REQ-DEVPLAN-008
+
+Wave Thread 协调合同和历史状态兼容能力已经移除。新 raw-plan 与历史 JSONL 中的 Wave Thread flow_type 都必须被拒绝；不得恢复、派发或回放旧协调任务。共享编排解析器仅保留现行多任务流程需要的 batch、wave、task、依赖、owned surfaces 与分阶段验收能力，不构成显式 `$dev-plan` 的新入口。新 raw-plan 必须拒绝重复 `## Wave Thread Contracts`，历史 JSONL 不得通过专属兼容路径读取该区段。
+
+The human-readable sections have distinct responsibilities: `Summary` states purpose, scope, stopping point, and key decisions; `Goals` state results; and `Acceptance & Validation` names acceptance IDs and observable evidence without repeating task fields or creating a second task registry.
+
+### REQ-DEVPLAN-009
+
+An explicit `$dev-plan` MUST use one finalization result that combines canonical raw-plan validation and owner-facing projection validation.
+
+`pass` MUST emit the projection and permit the plan response.
+
+`reject` MUST return stable findings, emit no compliant projection, and block execution.
+
+The raw checker remains a diagnostic dependency and MUST NOT be treated as a separate final success state.
+
+The projection MUST be derived from the same parsed canonical facts.
+
+It MUST contain these sections in this order: `决策卡`, `目标`, `不包含的工作`, `波次与依赖`, and `执行规则`.
+
+The remaining sections are `任务卡`, `约束`, `验收清单`, and `Review、运行时门禁与收口`.
+
+Its wave/dependency graph MUST contain only canonical waves, tasks, same-wave parallelism, and explicit dependencies.
+
+Projection output MUST remain transient and MUST NOT be reparsed as an execution contract.
+
+The `任务卡` section MUST display every canonical task and every non-empty canonical batch lifecycle field.
+
+Displayed lifecycle fields include target, parent branch, child PR, topology, event protocol, release policy, condition, acceptance, and observation window.
+
+The `验收清单` section MUST display every canonical acceptance ID under the phase headings `PR 合并前验收` and `PR 合并后验收`.
+
+Each acceptance item MUST be rendered as a readable card rather than a multi-column table. The card MUST display the canonical ID, proof target, pass conditions, and evidence; it MUST display scope when the canonical item has one. Post-merge and post-deploy cards MUST display their applicable trigger. The projection MUST keep assertions and evidence as semantic lines and MUST NOT use fixed-width or equal-width columns for long acceptance text.
+
+Projection validation MUST reject a view that omits a canonical task, batch, displayed field, acceptance item, or required card field, duplicates an acceptance ID, or emits a long-text acceptance table.
+
+The finalizer MUST reject NUL-containing input before invoking the raw checker.
+
+It MUST accept every direct task form accepted by the raw checker, including optional whitespace around `=>`.
+
+It MUST preserve the canonical `[model, effort]` profile form in the owner-facing task card and reject rather than silently omit any task it cannot project.
+
+It MUST preserve direct-task skill annotations wherever the accepted task syntax places them.
+
+It MUST normalize accepted flow aliases before choosing the canonical parser.
+
+It MUST reject duplicate route-driving `Flow Decision` or `Task Orchestration` sections before deriving display facts.
+
+File traversal MUST open every absolute tool-root component without following symlinks and MUST reject non-regular inputs without blocking.
+
+Historical compatibility MUST count proposed-plan markers only outside fenced examples.
+
+It MUST stop extraction at the first valid unfenced closing marker and reject extra markers in both the parser and JSONL shell route.
+
+Flow Decision route fields MUST be parsed from the same unfenced list-item grammar in the shell checker, Python finalizer, and continuation replay checker.
+
+The grammar MUST allow leading spaces or tabs before a list item, while fenced examples MUST be ignored.
+
+The owner-facing `决策卡` MUST preserve the canonical flow lock as `流程类型`.
+
+This allows continuation to recover the locked route without reparsing the projection as an execution contract.
+
+New v2 tasks MUST declare non-empty `title`, `purpose`, and `outputs` fields in `Task Orchestration`.
+
+旧协调任务的三档 Profile allowlist 和缺失字段兼容路径不再可用。现行共享多任务解析器按自身 Profile 与字段合同验证输入。
+
+New raw-plan output MUST NOT contain a second machine-readable batch/task registry or `Wave Thread Contracts`.
+
+The shared orchestration checker MUST apply the same Constraint-reference and persisted-plan-artifact guards to canonical task display metadata as to other Task Orchestration task text.
+
+This includes task lines with their required `[model, effort]` profile.
+
+The v2 parser and projection MUST preserve that locked profile.
+
+The v2 guard MUST cover plan, progress-log, decision-log, and handoff-log planning artifacts while retaining the existing product-surface exemptions.
+
+A product task that imports or processes user-provided `PLAN.md` content is not itself a persisted planning artifact.
+
+Shell and Python contract routes MUST normalize CRLF input and accept the same whitespace-tolerant section-heading form.
+
+The historical compatibility parser MUST parse only the content between the single unfenced `<proposed_plan>` and `</proposed_plan>` markers.
+
+Content outside that block MUST NOT affect validation, and extra markers MUST reject the input.
+
+A new raw-plan checker and finalizer MUST reject an unterminated Markdown fence.
+
+Owner-facing projection text MUST prevent bare URL/autolink syntax from creating external Markdown links.
+
+Direct finalizer calls with unencodable Unicode input MUST return a stable rejection finding rather than raising an uncaught encoding error.
+
+The selected tool root is the root containing the finalizer entrypoint, its imported contract modules, and its paired raw-plan checker. For ordinary business projects, the caller MUST select a trusted installed tool root and MAY invoke its absolute entrypoint from any working directory with canonical raw-plan input on stdin. The business project root does not select the checker or extend the file-input boundary.
+
+For dot-codex development, the caller MUST select the current candidate Worktree as tool root; runtime `CODEX_HOME` and other checkouts MUST NOT provide the entrypoint or its dependencies for candidate validation.
+
+File `--input` paths MUST be inside the selected tool root; relative paths are relative to that root. Stdin permits input from outside the root without relaxing file traversal. Entrypoint, modules, checker, and file input MUST retain no-follow and regular-file protections; symlinked source paths MUST be rejected.
+
+## Verification
+
+### VER-DEVPLAN-001
+
+- Method: `bun run bin/plan_contract_check.ts --plan <fixture>`.
+- covers: `REQ-DEVPLAN-001`, `REQ-DEVPLAN-003`, `REQ-DEVPLAN-004`
+- Pass condition: plans without provenance sections pass; provenance-heading variants and mappings, malformed constraints, duplicate constraints, constraints targeting unknown acceptance items, and task references to declared Constraints fail.
+
+### VER-DEVPLAN-002
+
+- Method: `bun test bin/tests/plan` plus replay cases.
+- covers: `REQ-DEVPLAN-002`, `REQ-DEVPLAN-005`
+- Pass condition: final-plan checks reject provenance leakage while Constraint fixtures bind only existing acceptance items and fast-track gates remain enforced.
+
+### VER-DEVPLAN-003
+
+- Method: `bun run bin/plan_contract_check.ts --plan -` and focused plan fixtures.
+- covers: `REQ-DEVPLAN-006`
+- Pass condition: direct plans pass without a `release_disposition`; legacy occurrences remain readable compatibility metadata and do not create a publication gate.
+
+### VER-DEVPLAN-004
+
+- Method: `bun test bin/tests/plan`, `bun run bin/plan_contract_check.ts --cases skills/dev-plan/references/replay-cases/CASES.txt`, and `bun run bin/instruction_architecture_check.ts --repo-root .`.
+- covers: `REQ-DEVPLAN-007`.
+- Pass condition: new raw plans reject retired arrangement fields, expose a displayable Step 5C decision card, and keep merge-only/merge+cleanup inputs executable without a final version string; 其他直接流程的 historical JSONL remains readable; missing/conflicting route, policy, version-rule, component, major alignment, and tag-collision cases resolve to unknown/blocked rather than no release; shared contract consumers and the runtime boundary stay aligned.
+
+### VER-DEVPLAN-005
+
+- Method: `bun test bin/tests/plan/orchestration.test.ts`、`bun test bin/tests/plan` 与历史直接流程的 JSONL 回归集。
+- covers: `REQ-DEVPLAN-008`.
+- Pass condition: 旧 Wave Thread Skill、CLI 和状态机缺席，历史 Wave Thread 计划被拒绝；现行多任务共享解析器保留正向与错误输入验证。
+
+### VER-DEVPLAN-006
+
+- Method: `bin/plan-cli.sh --input skills/dev-plan/references/plan-cases/positive-fast-track.md`, `bun test bin/tests/plan`, the independent tool-root invocation tests, and the candidate context validation sequence.
+- covers: `REQ-DEVPLAN-009`.
+- Pass condition: the finalizer returns one `pass` with the nine-section projection, Mermaid graph, and phase-grouped acceptance cards; raw, legacy, duplicate-contract, missing-display-metadata, projection-drift, forbidden-table, and tool-root boundary failures return one `reject` with no projection or execution permission.
+
+### VER-DEVPLAN-007
+
+- Method: `bun test bin/tests/plan` and the historical replay cases.
+- covers: `REQ-DEVPLAN-004`, `REQ-DEVPLAN-008`, and the 共享编排与历史直接流程的 guard boundary.
+- Pass condition: 共享多任务 display metadata 和 Profile cannot bypass Constraint-reference or plan/progress-log/decision-log/handoff-log artifact checks; direct raw plans reject unterminated fences; historical parsing and the JSONL shell route agree on whitespace-padded wrapper markers and reject contract data outside the proposed-plan block.
+
+## Related ADRs
+
+- [Scope authority and topic Spec boundaries](../../adr/0004-scope-authority-and-topic-spec-boundaries.md)
+- [Keep plan authorization internal and model validation limits as constraints](../../adr/0006-internal-plan-authorization-and-scope-constraints.md)
+- [Runtime-derived pre-merge release route](../../adr/0021-runtime-derived-pre-merge-release-route.md)
+- [Stop-condition-driven release decision](../../adr/0024-stop-condition-driven-release-decision.md)
+- [Single source for Wave Thread v2 plans](../../adr/0030-dev-plan-single-source-wave-thread.md)
+- [Transient owner review projection for dev plans](../../adr/0031-dev-plan-owner-review-projection.md)
+- [Single finalization gate for dev-plan owner review](../../adr/0032-dev-plan-single-finalization-gate.md)
+
+## References
+
+- `./IMPLEMENTATION.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/dev-plan-standalone-typescript-finalizer/HISTORY.md

@@ -0,0 +1,5 @@
+# History
+
+## 2026-11-03
+
+建立本主题规格，记录 `$dev-plan` 与 `$multi-task-flow` 的独立边界、TypeScript 唯一实现和仅用于安全启动的 shell launcher。它取代将 multi-task flow 注册为 dev-plan 顶层路线的旧设计；历史运行账本和回放输入仍只作兼容读取，不产生新的 handoff 绑定。

package/toolkit/skills/docs/vendor/dot-codex/specs/dev-plan-standalone-typescript-finalizer/IMPLEMENTATION.md

@@ -0,0 +1,27 @@
+# Implementation Coverage
+
+## Current State
+
+已实现 TypeScript 唯一业务路径与独立 finalizer；保留的 `plan-cli.sh` 仅承担安全启动和参数/stdin/退出码转发。
+
+## Required Changes
+
+- 将 dev-plan 的 shell checker、parser、projection 和 finalizer 逻辑迁移到 TypeScript。
+- 保留一个只负责环境清理和 `exec` 转发的 `plan-cli.sh` 安全 launcher。
+- 删除 dev-plan 与 `$multi-task-flow` 的 active route、handoff、digest、ledger 和 runtime bridge 绑定。
+- 删除旧 shell 业务实现和对应的双实现测试路径。
+- 将现有 raw-plan、projection、历史回放和安全启动测试迁移到 TypeScript 入口。
+- 更新 Skill 文档、工作流文档、设计文档和索引，消除已退役的跨 Skill 绑定表述。
+
+## Verification
+
+- `bun test bin/tests/plan --timeout 30000`：74 tests passed。
+- `bun test skills/multi-task-flow/tests/engine.test.ts skills/multi-task-flow/tests/orchestrate.test.ts --timeout 30000`：26 tests passed。
+- `bun check bin/modules/plan/contract.ts bin/modules/plan/review.ts bin/plan_review_view.ts bin/plan_contract_check.ts`：无类型错误。
+- `bun run bin/spec_contract_check.ts --path docs/specs/dev-plan-standalone-typescript-finalizer/SPEC.md`：通过。
+- `git diff --check`：通过。
+- 历史 JSONL 与 retired fixture 仍由 TypeScript 兼容入口只读解析；它们不参与新的 `$dev-plan` finalization route，也不创建 runtime 状态。
+
+## Acceptance Boundary
+
+新的 `$dev-plan` finalization route 已迁移并与 `$multi-task-flow` 解耦；兼容输入仍限于只读诊断，不得重新产生 handoff、digest、ledger 或 runtime bridge。