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

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

@@ -0,0 +1,78 @@
+# Dev-plan Standalone TypeScript Finalizer
+
+## Context and Scope
+
+This topic defines the standalone `$dev-plan` validation and owner-review boundary, including its TypeScript migration and trusted launcher. It does not define runtime task orchestration, ledgers, task conversations, dashboards, or `$multi-task-flow` behavior.
+
+## Terms and Interfaces
+
+- `Dev-plan finalizer`: the single public operation that validates a canonical raw plan and emits either a compliant transient projection or a rejection.
+- `Security launcher`: the minimal pre-main launcher that removes unsafe Bun and Node preload environment variables before executing the TypeScript finalizer.
+- `Runtime orchestration`: an independent execution capability such as `$multi-task-flow`; it is outside the dev-plan boundary.
+
+## Requirements
+
+### REQ-DPF-001
+
+The explicit `$dev-plan` route MUST use only its own checker, parser, projection and finalizer. A successful finalization MUST terminate the dev-plan route after emitting one transient `<proposed_plan>`.
+
+### REQ-DPF-002
+
+The finalizer MUST return exactly one machine result: `pass` with the owner-facing projection or `reject` with stable findings and no compliant projection. The projection MUST be derived from the same canonical facts that passed raw-plan validation.
+
+### REQ-DPF-003
+
+The dev-plan implementation MUST NOT invoke, import, route to, or exchange machine-readable fields with `$multi-task-flow` or any other runtime coordinator. It MUST NOT create or modify a runtime ledger, task conversation, dashboard state, handoff envelope or execution digest.
+
+### REQ-DPF-004
+
+Checker, parser, projection and finalizer logic MUST be maintained in TypeScript under the pinned Bun runtime. The old shell implementations MUST be removed rather than retained as alternate business-logic paths.
+
+### REQ-DPF-005
+
+The trusted launcher MAY remain a shell script only as a security boundary. It MUST clear `BUN_OPTIONS` and `NODE_OPTIONS`, forward arguments and stdin unchanged, execute the TypeScript finalizer, and forward its exit status. It MUST contain no plan parsing or validation logic.
+
+### REQ-DPF-006
+
+The canonical finalizer interface MUST support file and stdin input, preserve stable diagnostics and exit semantics, and produce no persistent plan or runtime artifact.
+
+### REQ-DPF-007
+
+The checker MUST continue to enforce the complete dev-plan contract, including required sections, locked flow decision fields, task orchestration structure, wave/task syntax, acceptance coverage and projection completeness.
+
+### REQ-DPF-008
+
+Tests MUST prove the TypeScript finalizer rejects malformed plans, emits one projection for valid plans, remains independent from `$multi-task-flow`, and preserves hostile-environment launcher behavior.
+
+## Verification
+
+### VER-DPF-001
+
+- Method: TypeScript unit and fixture tests for canonical parsing, raw-plan validation and projection validation.
+- covers: `REQ-DPF-001`, `REQ-DPF-002`, `REQ-DPF-006`, `REQ-DPF-007`
+- Pass condition: Invalid flow decisions, missing waves, malformed tasks and incomplete acceptance are rejected; valid plans produce one compliant transient projection.
+
+### VER-DPF-002
+
+- Method: Repository reference scan and isolated integration tests.
+- covers: `REQ-DPF-003`
+- Pass condition: The dev-plan package has no active multi-task-flow imports, handoff fields, ledger writes or runtime coordinator calls.
+
+### VER-DPF-003
+
+- Method: Bun launcher tests with hostile `BUN_OPTIONS` and `NODE_OPTIONS`, argument/stdin forwarding and exit-code checks.
+- covers: `REQ-DPF-004`, `REQ-DPF-005`
+- Pass condition: Only the TypeScript implementation executes, preload injection is prevented, and launcher behavior is transparent.
+
+### VER-DPF-004
+
+- Method: Bun regression suite covering malformed plans, valid projection count, forbidden runtime references and launcher behavior.
+- covers: `REQ-DPF-008`
+- Pass condition: The migrated TypeScript path rejects invalid plans, emits exactly one projection for valid input, remains independent from `$multi-task-flow`, and preserves the security launcher contract.
+
+## Related ADRs
+
+- [0032: One Finalization Gate for Dev-Plan Owner Review](../../adr/0032-dev-plan-single-finalization-gate.md)
+- [0033: Bun + TypeScript Script Runtime](../../adr/0033-bun-typescript-script-runtime.md)
+- [0034: Trusted Bun CLI Launch Boundary](../../adr/0034-bun-cli-launch-boundary.md)
+- [0040: Keep Dev-plan Standalone and Move Its Implementation to TypeScript](../../adr/0040-dev-plan-standalone-typescript-finalizer.md)

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

@@ -0,0 +1,54 @@
+# Dev plan goals-first contract rewrite 演进历史（#dvc8g）
+
+> Legacy compatibility history. 当前规范正文见 `../dev-plan-goals-first/SPEC.md`。
+
+## Decision Trace
+
+- 新建 `#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 执行。
+
+## Key Reasons / Replacements
+
+- Initiative delivery 复用同一份批准的 `$dev-plan`：拓扑字段只在 aggregate-stack 中增加执行约束，避免每个 Ticket 重新进入 Plan Mode 或制造第二份计划真相。
+
+- 实施阶段额外把 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`.

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

@@ -0,0 +1,87 @@
+# Dev plan goals-first contract rewrite 实现状态
+
+> Legacy compatibility snapshot. 当前实现状态见 `../dev-plan-goals-first/IMPLEMENTATION.md`。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: legacy-read-only
+- Catalog note: `dev-plan` 已切到 goals-first、non-persistent contract，checker 与 replay fixtures 已同步
+
+## 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` 引用、命令、路径、代码标识符、日志与错误文本的原文。
+- `bin/plan_contract_check.sh` 已新增 `Summary / Goals / Non-goals` 相关门禁，同时保留既有 flow lock、wave/task、skill binding 与 implement-only 禁止项。
+- `bin/plan_contract_check.sh` 现已额外校验 required section order，并拒绝 `Task Orchestration` 中的持久计划载体任务。
+- 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.sh` 与 bundled replay set。
+- `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` 表达范围边界。
+- `delivery_topology` 已进入 Flow Decision：新计划显式选择 `direct|aggregate-stack`；aggregate-stack 被 checker 强制要求 `prd/<topic>` integration branch、risk-gated child merge、owner-explicit final merge 与 Ticket 继承批准计划。
+- aggregate-stack 的 `prd/<topic>` 已与 initiative envelope 收敛为同一 lowercase kebab-case topic 规则，计划阶段不会再批准后续 Ticket 无法接收的 branch。
+- planner replay 已覆盖完整 aggregate-stack、缺 final merge policy，以及显式 `sub-agent:ticket` 再次调用 `$dev-plan` 的拒绝路径；普通 direct Issue/Ticket 解析任务不会只因描述文字被误判，无 topology 的历史计划继续按 direct 兼容。
+
+## Remaining Gaps
+
+- None currently tracked after the review-driven checker follow-up.
+
+## Related Changes
+
+- `docs/specs/README.md`
+- `docs/specs/dev-plan-goals-first/SPEC.md`
+- `skills/dev-plan/SKILL.md`
+- `bin/plan_contract_check.sh`
+- `skills/dev-plan/references/replay-cases/*`
+- `skills/implement-only-flow/SKILL.md`
+- `skills/initiative-flow/SKILL.md`
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

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

@@ -0,0 +1,171 @@
+# Dev plan goals-first contract rewrite
+
+> Legacy compatibility snapshot. 当前有效规范见 `../dev-plan-goals-first/SPEC.md`；本文只保留旧 `#dvc8g` 身份与历史合同供恢复读取。
+
+## 背景 / 问题陈述
+
+- 现有 `dev-plan` 更强调 `Task Orchestration` 波次格式与 `Scope & Boundaries` 占位章节，导致计划容易“格式合规但目标不够锁定”。
+- 主人明确要求新的显式 `$dev-plan` `<proposed_plan>` 回到“不落盘的临时执行规格”定位：前半段先讲摘要、目标与非目标，后半段才讲执行安排；长期知识仍只进入 `docs/specs/**` 或 `docs/solutions/**`。
+- repo 内已经有两个相邻 topic spec：`docs/specs/dev-plan-flow-lock-options/SPEC.md` 处理 flow lock 选项指导，`docs/specs/fast-track-merge-intent-closeout/SPEC.md` 处理 fast-track merge intent closeout；它们都不是这次 goals-first 合同重写的直接 owner，因此本次需要单独建一个新 topic spec。
+
+## 目标 / 非目标
+
+### Goals
+
+- 把显式 `$dev-plan` 的输出契约改成 goals-first：`Summary`、`Flow Decision`、`Goals`、`Non-goals`、`Task Orchestration`、`Acceptance & Validation`、`Assumptions/Defaults`。
+- 明确 `<proposed_plan>` 只是当前回合的临时执行规格，不得引入 `PLAN.md`、`PLANS.md` 或其他持久计划载体。
+- 强化“goals-first”不仅是章节集合，还包括章节顺序：`Goals / Non-goals` 必须在 `Task Orchestration` 之前出现。
+- 默认使用简体中文撰写 `<proposed_plan>` 的自然语言正文，除非主人显式要求其他语言。
+- 保留现有 `flow_type` 锁定、wave/task 编排、`$skill` 绑定、`implement-only` 禁止 spec 任务、`fast-track` / `local-merge` flow-specific 守卫。
+- 为交付拓扑增加显式 `delivery_topology=direct|aggregate-stack`：旧计划缺字段按 direct 读取，aggregate-stack 必须一次写清 integration branch、child merge、final merge 与 Ticket plan 继承策略。
+- 让 checker 与 replay fixtures 一起切到新口径，避免 skill 文案、校验器与样例互相漂移。
+
+### Non-goals
+
+- 不修改 `normal-flow`、`fast-flow`、`local-merge-flow` 的业务终点语义。
+- 不把 checker 升级成“计划质量评分器”或重型语义分析器。
+- 不新增第三类长期记忆载体；长期主题契约继续放 `docs/specs/**`，复用知识继续放 `docs/solutions/**`。
+- 不把 required section 标题、固定字段、`flow_type` 值、executor、`$skill` 引用、命令、路径、代码标识符、日志或错误文本翻译成中文。
+- 不接管未显式引用 `$dev-plan` 时的官方原味 built-in Plan Mode 默认结构。
+
+## 范围（Scope）
+
+### In scope
+
+- `docs/specs/README.md`
+- `docs/specs/dev-plan-goals-first/*`
+- `skills/dev-plan/SKILL.md`
+- `bin/plan_contract_check.sh`
+- `skills/dev-plan/references/replay-cases/*`
+- `skills/implement-only-flow/SKILL.md` 的最小 wording 对齐
+
+### Out of scope
+
+- 其他 flow skill 的终点语义重写
+- GitHub / PR / merge runtime 逻辑
+- 新增外部 plan 存储、plan 历史日志或进度账本
+
+## 需求（Requirements）
+
+### MUST
+
+- `dev-plan` 必须把 `Goals` 与 `Non-goals` 设为必选章节，且 `Goals` 中每个 goal 都需要标题与后续关键细节说明。
+- `dev-plan` 必须明确：除主人显式要求英文或其他语言外，`<proposed_plan>` 的自然语言正文默认使用简体中文。
+- `dev-plan` 必须明确：required section 标题、固定字段、`flow_type` 值、executor、`$skill` 引用、命令、路径、代码标识符、日志与错误文本保持原文，不因中文优先规则被翻译。
+- `dev-plan` 的推荐 skeleton 与主要正例应使用中文正文，避免示例把 Agent 输出带回英文。
+- `Summary`、`Goals` 与 `Non-goals` 的必选 bullet 都必须包含非空内容；单独的空 bullet 不能充当有效章节内容。
+- `Task Orchestration` 必须继续使用 wave/task 二维编排和 `$skill` 绑定，但章节职责仅限执行安排，不再承载设计说明；新计划使用 flow-scoped `main-agent` / `sub-agent:<name>` / `task:<name>` executor 与 `[model, effort]` profile。
+- `Scope & Boundaries` 不再是必选章节；范围语义默认由 `Goals` 与 `Non-goals` 承担。
+- checker 必须拦截：缺失 `Goals`、缺失 `Non-goals`、`Goals` 为空、goal 空标题 bullet、goal 只有标题没有细节。
+- checker 必须拦截：`Summary` 只有空 bullet，以及 `Non-goals` 只有空 bullet 或空 exclusion 项。
+- checker 必须拦截：goal detail 只有占位词（如 `TBD`、`待确认`）而没有具体范围/约束/成功信号的计划。
+- checker 必须把常见占位缩写（如 `TBA`、`TBC`）视作与 `TBD` 同类的无效 detail / acceptance 文本。
+- checker 必须拦截：章节顺序退回 execution-first、以及 `Task Orchestration` 中出现 `PLAN.md` / `PLANS.md` / progress ledger / planning decision log / handoff log 等持久计划载体。
+- persisted-plan artifact matcher 必须避免误伤正常产品语义；例如 `decision log UI`、customer-provided `PLAN.md` importer，以及 `next-session decision log` exporter / integration 这类功能词汇不能仅因包含 `decision log` 或 `PLAN.md` 就被判成落盘计划载体；但带明确 planning context 的 `job/workflow/pipeline` 等 generic wording 仍必须继续拦截。
+- persisted-plan artifact matcher 也必须允许产品 `plan template(s)` 相关的 decision-log/history 功能；`plan template` 属于产品面，不等于 planning context。
+- 对 `decision log` / `handoff log` 来说，`plan template(s)` 应被当成显式 product-safe surface，而不是被 `plan|workflow|job` 一类 planning-context 词误吞。
+- persisted-plan artifact matcher 的动作覆盖必须包含 `write/create/update` 之外的常见等价动作，例如 `generate`、`initialize`、`keep`，避免 planning artifact 因动词变体漏拦。
+- checker 必须允许正常产品 `progress log` UI/API/export 功能，不得把泛化 product-facing `progress log` 任务一律判成 persisted plan artifact；但带 planning context 的 `progress log` 仍应继续拦截。
+- checker 必须继续拦截对 persisted `PLAN.md` / planning artifact 的搬运式维持动作，例如 `move`、`copy`、`rename`、`archive`，不能只拦“创建/更新”。
+- checker 必须继续拦截 planning artifact 的常见准备类动词，例如 `prepare` / `setup` / `set up`，避免 persisted handoff log 仅因动词变化漏拦。
+- checker 对 `PLAN.md` / `PLANS.md` 的 product-safe 例外必须要求明确的产品文件/API/importer/upload 等语义锚点；单独的 `create/update/read PLAN.md` 之类泛化文件操作仍必须被拦截。
+- checker 必须拒绝 `Non-goals` 中的占位 bullet（如 `TBD`、`待确认`），不能仅因为“有 bullet”就通过。
+- checker 必须拦截：`Acceptance & Validation` 只有 `Notes`、`Follow-up items`、`备注` 等标签式说明，而没有真实验证活动或通过条件的计划。
+- checker 必须继续保留现有 flow lock、`Flow Decision`、wave/task、`$skill`、`implement-only` 禁止项等 guardrail。
+- checker 必须拒绝 aggregate-stack 缺少任一 required strategy 字段，并拒绝显式 `sub-agent:ticket` 在 Task Orchestration 中再次绑定 `$dev-plan`；同时校验 flow-scoped executor、profile 与 sub-agent 只读边界。普通 direct task 仅因提及 Ticket 或 Issue 不得被误判。
+- replay fixtures 与 `CASES.txt` 必须更新到新合同，并新增至少一组 goals-first 专用失败样例。
+
+### SHOULD
+
+- `Summary` 保持高度概括：一句结论加少量高价值要点，不把设计细节塞进摘要。
+- `Acceptance & Validation` 至少保留一条可观察的完成判据或验证方式。
+- `implement-only-flow` wording 应改成通过 `Goals / Non-goals` 承担范围表达，避免继续暗示旧 section 名。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### `<proposed_plan>` section contract
+
+- `<proposed_plan>` 的主阅读顺序应是：`Summary -> Flow Decision -> Goals -> Non-goals -> Task Orchestration -> Acceptance & Validation -> Assumptions/Defaults`。
+- 以上 section contract 只在主人显式引用 `$dev-plan` 时生效；未显式引用时，built-in Plan Mode 保持官方原味结构。
+- `Goals` 承担结果、范围边界、接口/数据流、关键约束、成功条件等可确定细节；`Non-goals` 只承担排除范围。
+- `Task Orchestration` 只回答“谁在什么波次做什么”，不重复解释目标和接口。
+- 若 `Task Orchestration` 出现在 `Goals / Non-goals` 之前，则视为违反 goals-first 合同，即使章节都存在也不得通过。
+- section 标题和固定字段继续作为机器合同使用英文；标题下的 owner-facing 说明、goal 细节、non-goal、任务描述、验收标准和假设默认使用简体中文。
+
+### Non-persistent plan boundary
+
+- `dev-plan` 产生的计划不落盘，不创建 `PLAN.md`、`PLANS.md`、planning decision log、progress ledger 等持久计划文档。
+- `Task Orchestration` 若显式要求写入、维护、同步、追加上述持久计划文档，也必须被 checker 拦截。
+- 如果实现过程中出现需要长期保留的稳定契约，必须写入 spec；如果出现跨任务复用经验，必须写入 solution。
+
+### Checker contract
+
+- `bin/plan_contract_check.sh` 继续定位为结构契约检查器。
+- `run_cases()` 必须把相对 fixture 路径解析到 `CASES.txt` 所在目录，而不是依赖调用方当前工作目录。
+- 新增的 goals-first 检查只验证最低结构充分性，不自动评价计划是否“最佳”。
+- checker 必须显式验证 required section order，不能只检查 section 是否“存在 somewhere”。
+- checker 必须显式拒绝 `Task Orchestration` 中的持久计划载体任务，而不是只依赖 skill prose。
+- checker 对持久计划载体的匹配必须足够窄，避免把正常功能实现词汇误判成 plan artifact。
+- 已有 flow 绑定与实现安全边界不得因本次 section 改名而退化。
+- aggregate-stack 只能在已声明 `delivery_topology` 时启用；缺失 topology 的历史计划继续按 legacy direct 通过，避免把新增合同反向施加给旧会话。
+
+## 验收标准（Acceptance Criteria）
+
+- Given 更新后的 `skills/dev-plan/SKILL.md` When 主人或 agent 阅读 contract Then 必须能看到 goals-first、non-persistent plan 和 `Task Orchestration` 仅负责安排的明确规则。
+
+- Given 主人在 built-in Plan Mode 中显式引用 `$dev-plan`，且没有显式要求英文计划 When agent 输出 `<proposed_plan>` Then 自然语言正文应以简体中文为主，同时保留 required section 标题、固定字段、`flow_type` 值、executor、`$skill` 引用、命令、路径、代码标识符、日志与错误文本的原文。
+
+- Given 更新后的 `bin/plan_contract_check.sh` When 检查缺失 `Goals`、缺失 `Non-goals`、`Goals` 为空、goal 无细节的 replay fixture Then 必须分别报出对应 finding，并让案例按预期失败。
+
+- Given 更新后的 `bin/plan_contract_check.sh` When 检查 `Task Orchestration` 早于 `Goals / Non-goals` 或 orchestration 中出现 `PLAN.md` / progress ledger 的 replay fixture Then 必须分别报出 section order 与 persisted artifact 对应 finding，并让案例按预期失败。
+
+- Given 现有 flow lock / wave / skill binding / implement-only 禁止项 replay fixtures When 跑完整 replay 套件 Then 既有 required code 仍然成立，不得因为 goals-first 改造而失去原本 guardrail。
+
+- Given 一个 aggregate-stack `<proposed_plan>` When 缺少 `integration_branch`、`child_merge_policy`、`final_merge_policy` 或 `ticket_plan_policy` 任一字段 Then checker 必须给出对应 finding；完整 aggregate 计划与 legacy direct 计划必须通过。
+
+- Given 一个 aggregate-stack `<proposed_plan>` 使用 `prd/My_Topic` 这类非 lowercase kebab-case integration branch When checker 解析 Flow Decision Then 它必须在计划阶段拒绝该 branch，避免后续 Ticket envelope 才发现不兼容的 initiative identity。
+
+- Given 一个显式 `sub-agent:ticket` 实现任务 When Task Orchestration 让它再次调用 `$dev-plan` Then checker 必须拒绝该计划；Ticket 必须继承批准计划并由 `$implement` 执行。
+
+- Given 一个 `delivery_topology=direct` 的 `main-agent` 任务 When 该任务实现 `$dev-plan` 的 Issue/Ticket 解析能力并绑定 `$dev-plan` Then checker 必须接受它，不能只因描述文本包含 Ticket 或 Issue 而套用 Ticket 重规划禁令。
+
+## 验收清单（Acceptance checklist）
+
+- [ ] goals-first 章节顺序与职责已经在 skill 中写清楚。
+- [ ] 不落盘计划的边界已经显式写入 contract。
+- [ ] 简体中文优先与机器合同 token 不翻译的语言边界已经写入 skill。
+- [ ] checker 已能识别 goals-first 最低结构错误。
+- [ ] checker 已能拦截 execution-first 章节顺序回退。
+- [ ] checker 已能拦截持久计划载体任务。
+- [ ] replay fixtures 已覆盖新老 guardrail。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `bash bin/plan_contract_check.sh --cases skills/dev-plan/references/replay-cases/CASES.txt`
+- `git diff --check`
+
+### Quality checks
+
+- 人工 spot-check `skills/dev-plan/SKILL.md` 的前 200 行，确认没有继续暗示持久 plan 文件。
+- 人工 spot-check 正例与失败样例，确认 `Goals / Non-goals` 已成为计划主体。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：若只改 skill 文案、不改 checker 与 fixtures，repo 会重新出现多个“真相源”互相打架。
+- 风险：若 goals 检查写得过重，可能把 checker 误推成计划质量评估器，因此本次只做最低结构门禁。
+- 假设：现有实现方接受 `Goals` 使用“标题 bullet + 后续说明行”这种轻量结构，不需要引入表格或额外 schema。
+
+## 参考（References）
+
+- `docs/specs/dev-plan-flow-lock-options/SPEC.md`
+- `docs/specs/fast-track-merge-intent-closeout/SPEC.md`
+- `skills/dev-plan/SKILL.md`
+- `bin/plan_contract_check.sh`
+
+## Visual Evidence
+
+PR: none
+
+本兼容规范只描述计划合同、checker、迁移器与 replay fixtures，不产生 UI 或其他视觉交付面。

package/toolkit/skills/docs/vendor/dot-codex/specs/empirical-acceptance-review-gate/HISTORY.md

@@ -0,0 +1,25 @@
+# Empirical Acceptance Review Gate History
+
+> This document records topic-local lifecycle and compatibility facts. The current decision is in `docs/adr/0033-empirical-acceptance-and-repair-autonomy.md`; ADR 0020 is historical.
+
+## Lifecycle / Compatibility
+
+- Exact Candidate binding remains required; result placement follows the workflow invariant so a successful observation does not create another SHA. The optional receipt contract carries no universal placement policy.
+- This active topic defines a shared direct-flow contract. It supplements, and does not replace, current validation, CI, visual evidence, or local review proof requirements.
+- HIL and other external-system checks are instances of the same proofability boundary; no hardware-specific compatibility mode is introduced.
+
+## Replacements / Background
+
+- The topic closes the gap between generic Review Readiness wording and empirical acceptance that can be invalidated by a review repair.
+- Direct review remains independent of receipt-led review orchestration.
+
+## Related Changes
+
+- [ADR 0020](../../adr/0020-empirical-acceptance-review-gate.md)
+- Direct plan, review readiness, continuation, and replay contracts now consume the Candidate-bound evidence card; external-system execution remains owned by the calling project.
+- Evidence hardening now rejects same-Candidate regressions, sentinel or blank locators, and decorated scenario/expected placeholders before diagnosis-only classification.
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/empirical-acceptance-review-gate/IMPLEMENTATION.md

@@ -0,0 +1,43 @@
+# Empirical Acceptance Review Gate Implementation
+
+> Current requirements remain in `./SPEC.md`. This document records the intended implementation boundary and verification coverage for the accepted contract.
+
+## Current Status
+
+- Implementation: 已完成 phase-aware contract (4/4)
+- Lifecycle: active
+- Catalog note: Candidate-bound empirical acceptance is required before review and delivery readiness when deterministic local validation cannot prove the criterion.
+
+## Implementation Coverage
+
+- Evidence cards follow the shared workflow's evidence-placement invariant. The legacy single Candidate card remains compatible only as `pre_merge`. The existing flow receipt records later-phase evidence with `merge_sha` and, when applicable, `deployment_identity`.
+- `CONTEXT.md`: defines the shared empirical-acceptance vocabulary.
+- `skills/dev-plan/SKILL.md` and `bin/plan_contract_check.ts`: require a proofability disposition and rationale; required plans name observable scenarios and expected results.
+- `skills/project-engineering-workflow/references/empirical-acceptance-short-contract.md` defines the phase-aware evidence card, admission, regression, and anchor rules; the shared workflow and direct-flow consumers point to it.
+- `bin/flow_receipt.py`: normalizes explicit acceptance phases, rejects ambiguous historical manifests, and binds pre-merge evidence to the Candidate. It records post-merge/post-deploy evidence only after the matching Merge Receipt exists. Post-deploy evidence requires a structured `deployment_identity` whose source and bound SHA both equal the Merge Receipt SHA.
+- `bin/plan_review_view.ts`: derives separate pre-merge and post-merge acceptance cards from the one canonical manifest; each card preserves ID, scope, proof target, pass conditions, evidence, and the applicable trigger without creating a second machine registry.
+- `bin/test_agent_profiles.py`: models current evidence, stale identity, diagnosis-only regressions, and anchor matching.
+- The migration disposition replay retains failed acceptance as a blocker even when the baseline limitation was accepted.
+- `bin/instruction_architecture_check.py` and plan fixtures: guard every direct consumer and the new topic contract.
+- `bin/plan_acceptance_manifest.py` rejects exact or embedded empirical scenario/expected assertion placeholders; direct manifest tests cover that parser boundary.
+- `ReviewReplay` in `bin/test_agent_profiles.py` rejects blank/sentinel evidence locators and same-Candidate regression comparisons before diagnosis-only classification.
+
+## Verification Coverage
+
+- Contract checks assert that every direct-flow consumer carries the same empirical readiness and regression semantics.
+- Lifecycle replay checks assert phase, Candidate/merge/deployment identity SHA lineage, acceptance-contract digest freshness, required scenario evidence, and complete continuation anchors. `replay/phase-closeout-cases.jsonl` drives closeout negatives for pending post-merge evidence, a mismatched merge SHA, and Candidate-only evidence presented after merge.
+- Disposition replay checks assert that external-behavior changes return to design and that empirical regressions remain diagnosis-only.
+
+## Remaining Gaps
+
+- Deterministic direct-plan, receipt, projection, and replay coverage is implemented. Live external-system execution remains intentionally outside dot-codex and is supplied by the calling project when an obligation is applicable.
+
+## Related Changes
+
+- [ADR 0033](../../adr/0033-empirical-acceptance-and-repair-autonomy.md)
+- [ADR 0032](../../adr/0032-phase-aware-acceptance-gates.md)
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/empirical-acceptance-review-gate/SPEC.md

@@ -0,0 +1,99 @@
+# Empirical Acceptance Review Gate
+
+> This file is the durable topic requirements contract. Current implementation facts belong in `IMPLEMENTATION.md`; lifecycle and change references belong in `HISTORY.md`.
+
+## Context and Scope
+
+- Context: Direct delivery needs a current-Candidate gate for acceptance criteria whose truth depends on observing an external system or environment.
+- In scope: obligation assessment, phase-aware Candidate/merge/deployment evidence, review admission, finding disposition, regression handling, and continuation.
+- Out of scope: executing a particular hardware rig, defining a vendor protocol, storing device data in the repository, or replacing CI/review evidence.
+
+## Terms and Interfaces
+
+- `Empirical Acceptance Obligation`: a declaration that external observation is required because deterministic repository-local validation cannot prove an acceptance criterion.
+- `Empirical Acceptance Evidence`: active Candidate/flow evidence containing `acceptance_id`, `phase`, the phase-appropriate identity (`candidate_sha`, `merge_sha`, and optionally a structured `deployment_identity`), `acceptance_contract_digest`, required scenarios, outcome, `scenario_set_digest`, and an inspectable evidence locator. A legacy Candidate-only card is compatible only as `pre_merge` evidence.
+- `Empirical Regression`: failed evidence for a Candidate after a comparable Candidate passed the same acceptance contract.
+- Interface: the current Candidate evidence and continuation anchor consumed by `$project-engineering-workflow`, direct delivery flows, and `$flow-continue`.
+
+## Requirements
+
+### REQ-EMPIRICAL-GATE-001
+
+- Every direct flow MUST assess whether each acceptance criterion is provable by deterministic repository-local validation. An unprovable criterion creates an Empirical Acceptance Obligation before formal review can launch.
+- Inputs: approved behavior, acceptance criteria, required contracts, and the available deterministic validation boundary.
+- Outputs: an explicit `required` or `not_required` disposition and rationale.
+- The assessment MUST NOT infer `not_required` solely from task type, file path, reviewer opinion, or prior Candidate evidence.
+
+### REQ-EMPIRICAL-GATE-002
+
+- Every applicable obligation MUST have current phase-appropriate Empirical Acceptance Evidence. Each record MUST bind its phase identity, `acceptance_contract_digest`, required scenarios, outcome, and an inspectable evidence locator. `pre_merge` evidence MUST bind `candidate_sha` to the exact Candidate; later phases use the Merge Receipt `merge_sha` and, for `post_deploy`, the structured deployment identity defined below.
+- Evidence outcomes are `passed`, `failed`, or `unavailable`. `unavailable` is a blocker, not a passing result or an empirical regression.
+- A Candidate SHA, acceptance-contract, or scenario-set change MUST invalidate affected passed evidence.
+
+### REQ-EMPIRICAL-GATE-003
+
+- Evidence placement MUST follow the shared workflow's evidence-placement invariant; collecting an observation preserves the tested candidate.
+- Review Readiness, Step 5C, and Step 5L MUST require passed current evidence for every applicable `pre_merge` obligation before claiming the Candidate is ready. `post_merge` evidence MUST wait for a Merge Receipt and actual `merge_sha`. `post_deploy` evidence MUST additionally bind a structured `deployment_identity` whose source and bound SHA equal that `merge_sha`. The evidence MUST NOT be reported as complete before that phase.
+- Formal reviewers MAY inspect the evidence but MUST NOT treat it as a review receipt, transcript substitute, or evidence of a clear review lane.
+- A missing, stale, failed, or unavailable empirical record MUST block the relevant gate without creating a Repair Batch.
+
+### REQ-EMPIRICAL-GATE-004
+
+- A demonstrated review finding MUST be classified as Design-Returning when its remedy changes external-response assumptions, timing deadlines, retry semantics, permission/state transitions, or acceptance semantics, unless the settled contract already specifies the exact correction and current evidence demonstrates a violation.
+- A Design-Returning finding MUST stop ordinary repair/review convergence and return to design. It cannot be reclassified as an In-Scope Review Finding by generic continuation.
+
+### REQ-EMPIRICAL-GATE-005
+
+- A failed empirical run after a comparable passed Candidate MUST enter diagnosis-only handling. The flow MUST identify the exact passing and failing Candidate SHAs and compare their relevant delta before a new design decision.
+- Diagnosis-only handling MUST NOT attribute the failure to review or a repair without evidence, launch another ordinary Repair Batch, relaunch formal review, or weaken the acceptance criterion to regain a pass.
+
+### REQ-EMPIRICAL-GATE-006
+
+- A non-terminal continuation anchor for an applicable obligation MUST carry the obligation disposition, current evidence identity and outcome, Candidate SHA, acceptance-contract digest, and cumulative Repair Batch count.
+- A generic continuation with any missing or mismatched field MUST block rather than infer the evidence state, reset the Repair Batch count, or start a new review wave. Repair authorization follows the selected flow and approved scope; the count is a diagnostic fact, not an additional authorization gate.
+
+### REQ-EMPIRICAL-GATE-007
+
+- Every new direct/v1 acceptance item MUST declare `scope=plan` and exactly one of `phase=pre_merge|post_merge|post_deploy`. Historical items without phase may be read as `plan/pre_merge` only when their text has no merge, release, deployment, or observation ambiguity; ambiguous history MUST be rejected.
+- Review Readiness, PR convergence, and Step 5C MUST consume only `pre_merge` evidence. `post_merge` and `post_deploy` are closeout evidence and cannot unblock a pre-merge gate.
+- Missing merge or deployment authority MUST remain an explicit owner-action blocker. It MUST NOT be converted to `not_required`, and `merge-ready` MUST NOT be reported as `Flow Complete`.
+- A PR-bound Flow Complete MUST have a registered canonical acceptance manifest. A missing manifest MUST remain an owner-action blocker and MUST NOT be treated as an empty acceptance set.
+
+## Verification
+
+### VER-EMPIRICAL-GATE-001
+
+- Method: direct-flow contract and instruction-architecture checks.
+- covers: `REQ-EMPIRICAL-GATE-001`, `REQ-EMPIRICAL-GATE-003`
+- Pass condition: a formal review launch without an explicit passed applicable obligation is rejected; a deterministically provable criterion may be marked `not_required` only with its rationale.
+
+### VER-EMPIRICAL-GATE-002
+
+- Method: Candidate-evidence replay fixtures.
+- covers: `REQ-EMPIRICAL-GATE-002`, `REQ-EMPIRICAL-GATE-006`
+- Pass condition: stale SHA, changed contract digest, absent scenario evidence, or a missing continuation field blocks review/convergence and cannot reset the repair count.
+
+### VER-EMPIRICAL-GATE-003
+
+- Method: finding-disposition and regression replay fixtures.
+- covers: `REQ-EMPIRICAL-GATE-004`, `REQ-EMPIRICAL-GATE-005`
+- Pass condition: an external-contract change is Design-Returning; a failed run after a comparable pass enters diagnosis-only handling and does not open a new ordinary Repair Batch or formal review wave.
+
+### VER-EMPIRICAL-GATE-004
+
+- Method: phase-aware manifest, receipt, and replay contract tests.
+- covers: `REQ-EMPIRICAL-GATE-007`
+- Pass condition: pre-merge readiness rejects missing/ambiguous phase syntax. Post-merge evidence without the actual merge SHA, mismatched merge-SHA closeout replay, and post-deploy evidence without deployment identity are rejected. A Candidate-only card cannot satisfy a later phase.
+
+## Related ADRs
+
+- [0033 Empirical Acceptance and Repair Autonomy](../../adr/0033-empirical-acceptance-and-repair-autonomy.md)
+
+## Visual Evidence
+
+- None
+
+## References
+
+- `./IMPLEMENTATION.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/empirical-acceptance-review-gate/replay/phase-closeout-cases.jsonl

@@ -0,0 +1,3 @@
+{"case":"pending-post-merge","expected_error":"owner-action blocker: post_merge acceptance is pending"}
+{"case":"wrong-merge-sha","expected_error":"owner-action blocker: phase acceptance evidence is invalid"}
+{"case":"candidate-only-after-merge","expected_error":"owner-action blocker: phase acceptance evidence is invalid"}