docs(governance): gate implementation on merged intent PR

.codex/skills/development-workflow/SKILL.md

@@ -45,19 +45,22 @@ Reference contract: `docs/guides/Evidence_Truth_Implementation_Strategy.md`.
 - choose collaboration mode (OpenSpec default, TODO fallback only when OpenSpec unavailable)
 - complete global analysis before execution
 - build/update a master TODO backlog that covers the full scope
-- declare TODO ownership in the target TODO ledger before implementation (`Claim ID`, `TODO scope`, `owner`, `expires`)
+- declare ownership in the target TODO ledger before implementation (`Claim ID`, `TODO scope`, `owner`, `expires`, `change-id`)
 - update `docs/design/**` first (no implementation before design update)
 - create or refresh feature aggregation doc as the status source
 - initialize/refresh the required evidence block in feature aggregation doc before execution
 - for OpenSpec mode, select one TODO slice as current change scope
-- ensure only one active claim exists per TODO slice; resolve conflicts before coding
+- decide whether the slice needs an execution board (`multiple owners`, `shared contracts`, `Gate freeze`, or `touch-scope collision`)
+- create or refresh the docs-only intent PR payload before any implementation begins
+- require the docs-only intent PR to merge into `main` before coding
 - run `documentation-management` to validate type/path/frontmatter baseline
 
 2. execution-sync
+- begin only after the docs-only intent PR is merged
 - OpenSpec mode: execute in small increments `TODO slice item -> OpenSpec task -> implementation -> evidence`
 - TODO fallback mode: execute in small increments `TODO item -> implementation -> evidence`, and record pending OpenSpec migration mapping
 - keep master TODO status and feature aggregation evidence aligned in all modes
-- keep claim ledger aligned with execution state (`planned -> active -> done/released`)
+- keep claim ledger, execution board, and feature/OpenSpec slice aligned when ownership or scope changes
 - after each completed task, update linked design/gap/TODO docs and implementation evidence
 - append command outputs and behavior-check results to the feature evidence block at task granularity
 - for large initiatives, continue by opening the next TODO slice in a new OpenSpec change instead of overloading one change
@@ -66,7 +69,8 @@ Reference contract: `docs/guides/Evidence_Truth_Implementation_Strategy.md`.
 - OpenSpec mode checks: `openspec validate`, `openspec status`, tests, and repo doc checks
 - TODO fallback mode checks: tests, repo doc checks, TODO ledger completeness, and migration debt note completeness
 - verify current OpenSpec slice only claims TODO items actually completed in this slice
-- verify claim ownership is consistent between TODO ledger and feature/OpenSpec slice
+- verify the intent PR was merged before the first implementation commit for the slice
+- verify claim ownership is consistent between TODO ledger and any execution board
 - verify coverage of interface contracts and error branches for changed behavior
 - verify status consistency: feature doc is source of truth, linked docs are non-conflicting
 - verify `docs/**` can stand alone as the current-state record without depending on OpenSpec internals
@@ -81,7 +85,6 @@ Reference contract: `docs/guides/Evidence_Truth_Implementation_Strategy.md`.
 
 5. completion-archive
 - mark work done in feature aggregation and related ledgers
-- release or close TODO claims (`done`/`released`) and clear stale active claims
 - run `documentation-management` archive actions
 - update TODO/archive indexes (for example `docs/todos/README.md` when applicable)
 - OpenSpec mode: complete OpenSpec archive when the change is finished
@@ -96,6 +99,6 @@ For each workflow run, report:
 - evidence commands executed
 - evidence results summary (including changed happy path + error branch checks)
 - evidence file updates (design, TODO, OpenSpec tasks, feature aggregation)
-- claim updates (new/renewed/released claims with TODO scope)
+- claim updates and intent-PR status
 - review and merge-gate status
 - unresolved risks or migration debt

.codex/skills/spec-driven-collab-board/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: spec-driven-collab-board
+description: Use when a claimed spec-driven change needs an execution board, work-package structure, Gate freeze tracking, or historical-reference handling before a docs-only intent PR is merged.
+---
+
+# Spec-Driven Collab Board
+
+## Authoritative inputs
+- `docs/todos/README.md`
+- `docs/todos/templates/change_execution_todo_template.md`
+- `docs/guides/Team_Agent_Collab_Playbook.md`
+- `docs/todos/project_overall_todos.md`
+- `docs/design/TODO_INDEX.md`
+- `openspec/changes/<change-id>/tasks.md`
+- `docs/features/<change-id>.md` when present
+
+## Core rule
+
+Treat `Claim Ledger` as the outer ownership record and `docs/todos/YYYY-MM-DD_<change-id>_execution_todos.md` as the inner coordination board for an active change.
+
+Do not turn `docs/todos/project_overall_todos.md` into a work-package task board.
+Do not claim work directly from `docs/design/TODO_INDEX.md`.
+
+## Workflow
+
+1. Confirm the change state before editing any board.
+- Read `openspec/changes/<change-id>/tasks.md`.
+- Read `docs/features/<change-id>.md` when it exists.
+- Read the matching initiative entry in `docs/todos/project_overall_todos.md` when one exists.
+- Read the corresponding `Claim Ledger` entry and confirm the TODO scope is already claimed.
+- If tasks are complete and the feature or roadmap status is `done`, do not create a new active board for that change.
+
+2. Decide whether an execution board is needed.
+- If the change is single-owner, has no shared-contract risk, and does not need Gate sequencing, report that no execution board is required and stop.
+- Otherwise continue and choose exactly one board action.
+- `create`: no execution board exists for an active change.
+- `refresh`: an execution board exists but its gates, work packages, or evidence links are stale.
+- `historical-reference`: the change is completed or superseded and the old board should remain only as reference.
+
+3. Create or refresh the board from the template.
+- Use `docs/todos/templates/change_execution_todo_template.md` as the structural baseline.
+- Name the file `docs/todos/YYYY-MM-DD_<change-id>_execution_todos.md`.
+- Keep the status explicit: `active`, `blocked`, `archived`, or `historical reference`.
+- Prepare the board as part of a docs-only intent PR payload; a local-only board is not sufficient coordination.
+- Include these sections unless there is a strong reason not to:
+  - usage rules
+  - context and scope boundary
+  - Gate freeze summary
+  - work-package coordination board
+  - subtask acceptance tables
+  - interface compatibility matrix
+  - integration and closeout
+  - maintenance rules
+
+4. Split work at the work-package level, not at the bullet level.
+- Create `2-5` work packages for one change.
+- Target `0.5-2` days of work per package.
+- Give each package one owner, one main goal, one declared touch scope, and one freeze boundary.
+- Keep subtasks small for acceptance and evidence mapping, but do not use them as the default claim unit.
+
+5. Apply Gate rules before allowing parallel work.
+- Shared contracts must freeze before downstream packages begin dependent implementation.
+- A package should cross at most one Gate.
+- If two developers need the same schema, payload, enum, state machine, or audit contract, split into upstream freeze work and downstream implementation work.
+
+6. Keep the board synchronized with the surrounding governance documents.
+- `project_overall_todos.md` remains roadmap plus outer `Claim Ledger`; it must not absorb work-package detail.
+- `TODO_INDEX.md` remains backlog-only.
+- The execution board must link back to the OpenSpec change and reflect the same completion state as `tasks.md`.
+- The execution board should be ready before the docs-only intent PR is raised, and that intent PR must merge before implementation starts.
+- If a package moves to `review` or `done`, update evidence on the same day.
+
+7. Downgrade completed boards instead of pretending they are still active.
+- Change the title and status to make the historical role obvious.
+- State why the board is no longer active.
+- Point future coordination to the currently active change when one is known.
+
+## Board quality checks
+
+Before claiming the board update is complete, verify:
+- the chosen change is still active if the board is marked `active`
+- the outer `Claim Ledger` entry exists and names the same TODO scope / change-id
+- each work package has `WP`, `Goal`, `Owner`, `Depends On`, `Touch Scope`, `Freeze Gate`, `Status`, `Branch/Worktree`, `PR`, `Evidence`, and `Last Updated`
+- subtask tables map back to OpenSpec task IDs, gap IDs, or testable acceptance points
+- the board does not duplicate work-package detail into `project_overall_todos.md`
+- the board and `openspec/changes/<change-id>/tasks.md` do not contradict each other
+- the board is suitable to ship in a docs-only intent PR without implementation code
+
+## Output expectations
+
+Report:
+- which action was taken: `create`, `refresh`, or `historical-reference`
+- why this change is the correct active or historical board target
+- which files were created or updated
+- whether an execution board was actually required
+- what still needs owner assignment, evidence, Gate freeze, or intent-PR merge
+
+## Examples
+
+Use these boards as references when the structure is unclear:
+- `docs/todos/agentscope_domain_execution_todos.md`
+- `docs/todos/templates/change_execution_todo_template.md`

AGENTS.md

@@ -1,4 +1,3 @@
-
 # Additional Constraints
 
 - When writing code, add necessary comments to clarify non-obvious logic or intent.

docs/README.md

@@ -85,6 +85,8 @@
 | `Project_Architecture_and_Priorities.md` | 以“实现视角”梳理现状与优先级（阅读入口指向权威设计） | ✅ 实现视角 |
 | `todos/README.md` | TODO 目录维护规则与生命周期说明 | ✅ 全局规划 |
 | `todos/project_overall_todos.md` | 项目总体 TODO 清单（跨模块路线图） | ✅ 全局规划 |
+| `todos/templates/change_execution_todo_template.md` | 活跃 change 的 execution board 模板（大包认领，小 task 验收） | ✅ 协作模板 |
+| `plans/2026-02-28-spec-driven-collaboration-granularity-design.md` | spec-driven 协作粒度设计说明 | ✅ 协作设计 |
 
 ### 3️⃣ 附录与工程实践
 
@@ -97,6 +99,7 @@
 | `guides/Evidence_Truth_Implementation_Strategy.md` | Evidence Truth 固化策略：证据结构、审计要求、CI 分阶段落地 |
 | `governance/Documentation_Management_Model.md` | 文档管理模型：目录分层、文档类型规则、生命周期依赖、OpenSpec/无 OpenSpec 协作 |
 | `features/README.md` | 特性聚合文档规范：单一状态源、证据回写与归档迁移 |
+| `guides/Team_Agent_Collab_Playbook.md` | 团队并行开发协作手册，含 spec-driven 认领粒度与 execution board 规则 |
 | `guides/Tool_Approval_Memory.md` | 工具审批记忆使用指南：pending/grant/deny/revoke、scope/matcher、持久化与接线方式 |
 
 ---

docs/guides/Development_Constraints.md

@@ -14,7 +14,7 @@
 - 所有代码开发以 `docs/design/` 全量最新设计为准；若实现与文档冲突，必须先更新文档再改代码。
 - 设计文档必须可独立重建实现：至少显式描述总体架构、核心流程、数据结构、关键接口、异常错误处理（详见 `docs/design/Design_Doc_Minimum_Standard.md`）。
 - 任何 Bug/新增 Feature/重构，必须先执行“全局分析 + 总体 TODO 主清单 + docs 更新”，再按 TODO 切片进入 OpenSpec 流程逐项落地（大改动通常对应多个 OpenSpec change）。
-- 任何进入执行态（`doing`）的 TODO，必须先在对应 TODO 文档登记负责人与认领声明（Claim Ledger：scope/owner/expires/change-id），避免并行冲突。
+- 任何进入实现态的切片，必须先完成 `Claim Ledger` 认领声明，并先合入 docs-only `spec-sync / intent PR`；未合入前不得开始代码实现。
 - 默认采用 OpenSpec 协作；仅在 OpenSpec 不可用时允许 TODO-driven 回退模式，并必须在 OpenSpec 恢复后完成迁移回写。
 - 任何治理类文档任务必须使用双技能流程（`.codex/skills/documentation-management/SKILL.md` + `.codex/skills/development-workflow/SKILL.md`）或等价自动化流程。
 - Evidence Truth 必须结构化固化到 `docs/features/*.md`，并通过 `./scripts/ci/check_governance_evidence_truth.sh` 门禁校验（见 `docs/guides/Evidence_Truth_Implementation_Strategy.md`）。

docs/guides/Documentation_First_Development_SOP.md

@@ -14,7 +14,7 @@
    - 关键接口
    - 异常与错误处理
 4. 任何 Bug/Feature/Refactor，必须先判断是否为设计约束不清或缺失；是则先补文档。
-5. 开发闭环必须是：全局分析 -> 总体 TODO 主清单 -> docs 更新 -> 按 TODO 切片进入 OpenSpec 执行 -> TODO/证据回写 -> 文档归档。
+5. 开发闭环必须是：全局分析 -> 总体 TODO 主清单 -> 认领声明 -> docs 更新 -> 按 TODO 切片建立 OpenSpec / execution board -> docs-only intent PR 合入 -> 实现 -> TODO/证据回写 -> 文档归档。
 6. `docs/**` 是全量事实源；`openspec/**` 仅是执行过程记录。OpenSpec 结果必须回写到 `docs/**`，禁止只留在 OpenSpec。
 
 ## 2. 产物规范（必须）
@@ -47,14 +47,13 @@
 - 基于分析文档生成总体 TODO 主清单，覆盖完整目标范围。
 - 每条 TODO 必须标记切片边界（可独立执行、可独立验证、可独立回滚）。
 - 总体 TODO 必须支持映射多个 OpenSpec change（一个大特性通常对应多个 change）。
-- 每条 TODO 必须有明确 `Owner`；若暂未指定负责人，状态不得进入 `doing`。
+- 每条进入执行态的 TODO 切片必须可映射到唯一 `Claim Ledger` scope。
 
-### Step 2.5: 负责人认领声明（冲突规避，新增）
-- 在开始实现前，必须先在对应 TODO 文档的 `Claim Ledger` 写入认领声明：
-  - `Claim ID`、`TODO Scope`、`Owner`、`Status(planned/active)`、`Declared At`、`Expires At`、`OpenSpec Change`。
-- 同一 TODO ID 在同一时刻只允许一个 `planned/active` 认领。
-- 认领过期后必须续期或释放（`expired/released`），否则他人可重新认领。
-- 推荐顺序：`先认领 -> 再建/更新 OpenSpec 切片 -> 再进入代码实现`。
+### Step 2.5: 认领声明（冲突规避，强制）
+- 在开始实现前，必须先在对应 TODO 文档写入 `Claim Ledger` 认领声明。
+- 最少字段：`Claim ID`、`TODO Scope`、`Owner`、`Status`、`Declared At`、`Expires At`、`OpenSpec Change`。
+- 同一 TODO scope 在同一时刻只允许一个 `planned/active` 认领。
+- 认领只声明“这一块范围由谁推进”，不替代 active change 内部的 work package 协作板。
 
 ### Step 3: 先更新 docs（作为 OpenSpec 输入）
 - 在执行前先更新 `docs/design/**` 与相关治理文档，形成当前基线。
@@ -66,11 +65,21 @@
 - 从总体 TODO 中选择一个最小切片，创建/更新一个 OpenSpec change。
 - 每个 change 必须声明其消费的 TODO 子集与验收边界。
 - 一个 change 只处理一个切片；多切片并行时使用多个 change-id。
+- 若该切片存在多人并行、共享接口、或需要 Gate 冻结，则必须创建/更新 `docs/todos/YYYY-MM-DD_<change-id>_execution_todos.md`。
+
+### Step 4.5: 合入 docs-only intent PR（实现前门禁）
+- 在进入代码实现前，必须提交一个只包含治理文档的 `spec-sync / intent PR` 并先合入 `main`。
+- 该 PR 至少包含：
+  - `Claim Ledger` 更新；
+  - 本轮切片对应的 docs/OpenSpec artifacts；
+  - 若需要多人协作，则包含 execution board 骨架与 Gate/Touch Scope 定义。
+- `intent PR` 禁止夹带实现代码；其目的仅是把意图、边界、冻结点写入共享基线。
 
 ### Step 5: 按 OpenSpec 切片逐项执行修复
 - 每个切片在 OpenSpec 中落地为可追踪 proposal/design/tasks。
 - 推荐节奏：一条 TODO（切片子项） -> OpenSpec task -> 实现 -> 验证 -> 回写状态。
 - 禁止一次性跨多个高风险 TODO 混改。
+- 未完成 `intent PR` 合入前，不得开始实现代码或提交实现 PR。
 
 ### Step 6: 验证与回写
 - 每次切片修复后必须同步更新：
@@ -106,9 +115,10 @@
 
 - 未完成 Step 1（全局分析）不得进入切片执行。
 - 未完成 Step 2（总体 TODO）不得创建 OpenSpec change。
-- 未完成 Step 2.5（负责人认领声明）不得进入 Step 4/Step 5。
+- 未完成 Step 2.5（认领声明）不得进入 Step 4/Step 5。
 - 未完成 Step 3（docs 更新）不得进入代码提交。
 - 未完成 Step 4（切片映射）不得开始批量修复。
+- 未完成 Step 4.5（docs-only intent PR 合入）不得开始代码实现。
 - 未完成 Step 6（验证+回写）不得标记切片完成。
 - 未完成 Step 7（归档）不得关闭该轮治理任务。
 
@@ -138,19 +148,23 @@
 2. 在 TODO `Claim Ledger` 先声明认领（scope/owner/expires/change-id）。
 3. 从总体 TODO 选择一个切片，建立/选择 `openspec/changes/<change-id>/`。
 4. 创建或更新 `docs/features/<change-id>.md`，登记该切片的 proposal/design/specs/tasks 链接。
-5. 按 OpenSpec tasks 执行该切片，并回写证据到 feature 聚合文档与 TODO 文档。
-6. 重复步骤 2-5，直到总体 TODO 主清单清空。
-7. 完成后执行 verify + archive，并迁移聚合文档到 `docs/features/archive/`。
-8. 确认最终可读性以 `docs/**` 为准：架构/流程/接口变更已在 docs 中可独立理解，OpenSpec 仅保留追踪链接。
+5. 若切片需要多人并行、共享接口冻结或联调顺序控制，则创建/更新对应 execution board。
+6. 提交 docs-only `intent PR` 并先合入 `main`。
+7. 基于最新 `main` 开始实现，按 OpenSpec tasks 执行该切片，并回写证据到 feature 聚合文档与 TODO 文档。
+8. 重复步骤 2-7，直到总体 TODO 主清单清空。
+9. 完成后执行 verify + archive，并迁移聚合文档到 `docs/features/archive/`。
+10. 确认最终可读性以 `docs/**` 为准：架构/流程/接口变更已在 docs 中可独立理解，OpenSpec 仅保留追踪链接。
 
 ### Mode B: 无 OpenSpec 回退（TODO-driven）
 
 仅在 OpenSpec 不可用（工具/环境受限）时使用：
 1. 先完成分析 + 总体 TODO 主清单 + docs 基线更新。
 2. 在 TODO `Claim Ledger` 先声明认领（scope/owner/expires）。
 3. 创建 `docs/features/<topic-slug>.md`，并在 frontmatter 声明 `mode: todo_fallback` 与 `topic_slug`。
-4. 以 TODO 清单推进并持续回写 evidence（不阻塞于 OpenSpec 工具可用性）。
-5. OpenSpec 可用后，按 TODO 切片补迁移：将 fallback 资产映射到一个或多个新的 `openspec/changes/<change-id>/` 并记录迁移证据。
+4. 若该切片需要多人并行或共享接口冻结，则创建/更新 execution board。
+5. 提交 docs-only `intent PR` 并先合入 `main`。
+6. 以 TODO 清单推进并持续回写 evidence（不阻塞于 OpenSpec 工具可用性）。
+7. OpenSpec 可用后，按 TODO 切片补迁移：将 fallback 资产映射到一个或多个新的 `openspec/changes/<change-id>/` 并记录迁移证据。
 
 ## 8. SOP Skill 化（必须）