agent-project-sdlc 0.1.9 → 0.1.11

package/README.md

@@ -25,8 +25,9 @@ npx sdlc-harness init --adopt
 | Managed file sync | `npx sdlc-harness sync` | Materializes package canonical assets into the configured Harness root while preserving project state, docs and local overrides. |
 | Upgrade | `npx sdlc-harness upgrade` | Runs migrations and sync for already-adopted projects. |
 | Diagnostics | `npx sdlc-harness doctor` | Reports Harness root, package version, schema version and key managed paths. |
-| Validators | `npx sdlc-harness validate-*`, `make validate-current`, `make validate-harness` | Checks phase deliverables, active plan shape, prompt language contract and generated overview freshness. |
+| Validators | `npx sdlc-harness validate-*`, `make validate-current`, `make validate-harness` | Checks product, design slicing, development, review, test, release, RFC, active plan shape, prompt language contract and generated overview freshness. |
 | Lifecycle workflow | `<harnessRoot>/state/lifecycle.yaml`, `<harnessRoot>/state/plan.yaml`, `.docs/**` | Tracks REQUIREMENT_GATHERING, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING and RFC_RECALIBRATION facts. |
+| Stage task control | `plan.yaml`, `make validate-plan`, `npx sdlc-harness validate-plan` | Keeps each stage's agent work in small `TASK-*` tasks with `phase` metadata and scoped paths/gates. |
 | Natural-language control | `AGENTS.md` plus workflow skills | Lets users say things like "continue", "start development", "run tests" or "requirements changed"; agents map these to workflow actions. |
 | Optional parallel execution contract | `plan.yaml#parallel_execution` | Enabled only when users explicitly request multi-agent, parallel or multi-worktree execution; supports runtime-managed subagents or user-orchestrated worker prompts. |
 | Workflow skills | `<harnessRoot>/skills/pjsdlc_*/SKILL.md` | Provides role prompts for product, architecture, development, implementation docs, review, testing, release and RFC recalibration. |
@@ -67,8 +68,18 @@ The default workflow is serial. Agents should only create `parallel_execution` i
 - `runtime_managed`: use only when the current agent runtime can spawn subagents. The main agent assigns workers, waits for results, reviews, merges or cherry-picks, and runs the total gate.
 - `user_orchestrated`: use when the runtime cannot spawn subagents. The main agent generates copyable worker prompts, and the user manually opens Codex conversations or worktrees and pastes them.
 
+`parallel_execution` does not store duplicate current phase or current task fields. Agents read phase from `<harnessRoot>/state/lifecycle.yaml#current_phase` and task selection from `<harnessRoot>/state/plan.yaml#current_task_id`.
+
 The CLI does not promise to automatically launch Codex agents. Workers do not need to communicate with each other; the main agent owns final fact-source updates such as PRD, plan, implementation docs, test results and generated overviews.
 
+## Stage Task Control
+
+Every stage's agent work is plan-controlled. Conversational PRD or design creation, existing document slicing, fact-source-based synthesis, development, review, testing, release preparation and RFC recalibration should create or resume one small `TASK-*` task in `plan.yaml` with a valid `phase`, write the current task's `result_docs` or `implementation_doc`, update indexes/overviews, run `validate-plan`, and remove the task after completion. Phase exit validators reject remaining open tasks.
+
+Before development starts, `ARCHITECTING` can return to `REQUIREMENT_GATHERING` for PRD edits. The manager uses `python3 tools/transition.py --to REQUIREMENT_GATHERING`, the PM workflow updates the PRD through one `TASK-*`, then `validate-pm` and `python3 tools/transition.py --to ARCHITECTING` return the project to design. Requirement changes after `SPRINTING` still use RFC recalibration.
+
+`validate-design` treats semantic slicing as a hard gate. Generated `overview.md` files do not count as deliverables, development draft tasks in `plan.draft.yaml` must reference existing tech plan slices through `docs.tech_plan`, multiple development draft tasks need distinct primary tech plan slices, and explicit AI provider/copilot, external-system, or compliance/permission/audit themes require dedicated architecture slices.
+
 ## Common Commands
 
 ```sh
@@ -77,6 +88,11 @@ npx sdlc-harness init --adopt
 npx sdlc-harness sync
 npx sdlc-harness upgrade
 npx sdlc-harness doctor
+npx sdlc-harness validate-plan
+npx sdlc-harness validate-review
+npx sdlc-harness validate-test
+npx sdlc-harness validate-release
+npx sdlc-harness validate-rfc
 make validate-current
 make validate-harness
 make docs-overview

package/assets/agents/AGENTS_CORE.md

@@ -30,10 +30,14 @@
 
 ## Plan Protocol
 
-- `plan.yaml` 是当前和未来任务的短期执行计划事实源。open task 直接包含 `allowed_paths`、`required_gates`、`acceptance_criteria` 和必要的 `working_notes`。
-- `next_task_sequence` 记录下一个可分配的 `DEV-*` 序号，避免删除历史 task 后发生 id 冲突。
-- task 完成并写入或更新相关 implementation doc 后，从 `plan.yaml` 的 `tasks` 列表移除该 task；不要长期保留 done/cancelled task 摘要。
+- `plan.yaml` 是当前和未来任务的短期执行计划事实源。每个阶段的每个 Agent 主任务都应先检查是否过长，必要时拆成大小合适的 open task；open task 直接包含 `phase`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和必要的 `working_notes`。
+- `current_phase` 只保存在 `lifecycle.yaml`；不要在 `plan.yaml`、`plan.draft.yaml` 或 `parallel_execution` 中重复保存当前阶段。
+- 新建任务统一使用 `TASK-*` id，并通过 `phase` 标明属于 `REQUIREMENT_GATHERING`、`ARCHITECTING`、`SPRINTING`、`REVIEWING`、`TESTING`、`RELEASING` 或 `RFC_RECALIBRATION`；历史 `PRD-*`、`DES-*`、`DEV-*` 只作为兼容旧记录和旧提交的 provenance。
+- `next_task_sequence` 记录下一个可分配的 `TASK-*` 序号，避免删除历史 task 后发生 id 冲突。
+- 文档、Review、测试、发布和 RFC 类 task 使用 `result_docs` 指向本 task 产出的 PRD、architecture、tech plan、ADR、review report、test plan、release note、RFC 或 `plan.draft.yaml`；开发 task 使用 `implementation_doc` 指向模块级实现事实。
+- task 完成并写入或更新相关事实源后，从 `plan.yaml` 的 `tasks` 列表移除该 task；不要长期保留 done/cancelled task 摘要。
 - `plan.draft.yaml` 是架构阶段生成的计划草案，不自动覆盖 `plan.yaml`。
+- `plan.draft.yaml` 不保存 `current_phase` 或 `current_task_id`，只保存待采用的 task 草案和必要的 `next_task_sequence`。
 - 不维护 checkpoint 文件；任务现场只存在于 open task 的 plan 条目里。
 - 历史动作记录以 git commit 为准，产物结果以模块、子系统或核心数据流级 implementation doc 为准。
 - `SPRINTING` 阶段每完成一个 task，先在 task 仍位于 `plan.yaml` 时创建 task implementation commit；随后再从 `plan.yaml` 移除该 task 并创建 task completion ledger commit。两段提交 push 成功前不进入下一个 task。
@@ -124,7 +128,7 @@ Strong success criteria 可以让你 independent loop。Weak criteria，例如
 ### Harness 补充原则
 
 1. 阶段约束优先：除非用户明确要求其它工作流动作，否则使用 `active_skill` 指定的 workflow skill，并服从当前阶段的 allowed paths、required gates 和交付物边界。
-2. 文档先于实现：产品文档和技术方案未形成前，不写业务代码；需求变更必须进入 RFC 工作流。
+2. 文档先于实现：产品文档和技术方案未形成前，不写业务代码；尚未进入 `SPRINTING` 且仍在 `ARCHITECTING` 时，可以通过 `transition.py --to REQUIREMENT_GATHERING` 回到 PM/PRD 工作流修改产品事实；进入 `SPRINTING` 后的需求变更必须进入 RFC 工作流。
 3. 验证闭环：多步骤工作先给出简短计划，并为关键步骤绑定验证方式。除非被阻塞，否则持续迭代到对应 `required_gates`、阶段 gate 或明确的人工验收标准满足。
 4. 派生物可再生成：`overview.md`、包内 assets 等 generated artifact 必须由对应命令刷新，不手写局部补丁。
 
@@ -133,16 +137,16 @@ Strong success criteria 可以让你 independent loop。Weak criteria，例如
 1. 选择任何角色或 skill 前，先读取 `.codex/state/lifecycle.yaml`。
 2. 除非用户明确要求其它工作流动作，否则使用 `active_skill` 指定的 workflow skill。
 3. 产品文档和技术方案未形成前，不写业务代码。
-4. 在 `SPRINTING` 阶段，一次只执行一个任务。
-5. 在 `SPRINTING` 阶段，只编辑当前 open task 的 `allowed_paths` 允许的文件。
+4. 每个阶段一次只执行一个 open task；如果任务过长，先拆成多个 `TASK-*`，当前轮只推进 `current_task_id`。
+5. 每个阶段只编辑当前 open task 的 `allowed_paths` 允许的文件；只读角色仍不得修改源码。
 6. 不要在当前 open task 的 `required_gates` 通过前把任务标记为 `done`。
 7. 代码 gate 通过后，更新相关 implementation doc 和 `.docs/INDEX.md`。
 8. `reviewer` 角色只读，不直接修改源码。
-9. 需求变更必须进入 RFC 工作流。
+9. 进入 `SPRINTING` 后的需求变更必须进入 RFC 工作流；`ARCHITECTING` 阶段发现 PRD 需要修改时，可以先回到 `REQUIREMENT_GATHERING`。
 10. task/release 历史动作记录使用 git commit、tag 或外部 release 系统，不维护 `<harnessRoot>/archive/` 常规归档。
 11. 在 `SPRINTING` 阶段，task 完成闭环必须先创建 task implementation commit，再提交移除该 task 后的 task completion ledger commit；如果没有 remote/upstream、权限或凭证导致无法 push，不要开始下一个 task，先报告 blocker。
 12. 文档 slice 发生变化后，运行 `make docs-overview` 刷新对应 `overview.md`。
-13. open task 必须在 `plan.yaml` 中包含完整执行合同，再继续推进或交接。
+13. open task 必须在 `plan.yaml` 中包含完整执行合同，再继续推进或交接；方案生成、现有文档切片、基于上一阶段事实源生成、Review、测试、发布和 RFC 处理都必须先落到 `plan.yaml` task。
 14. 默认不读取过去 task 或 phase 执行流水；修 bug、补功能和阶段交付以当前代码、测试、PRD、技术方案和模块级 implementation doc 为准。
 15. gate 证据写入当前 task `working_notes` 或相关 implementation doc 的 `Verification`；不要维护独立 gate results state。
 16. 如果信息缺失，或 gate 因基础设施原因失败，停止推进并报告 blocker。
@@ -156,9 +160,9 @@ Strong success criteria 可以让你 independent loop。Weak criteria，例如
 - “现在到哪了 / 状态如何” → 等价 `/status`。
 - “继续 / 下一步 / 推进” → 等价 `/next`。
 - “能进入下一阶段吗 / 进入下一步” → 等价 `/advance`。
-- “需求变了 / 这个设计要改” → 进入 RFC workflow。
-- “完善产品方案 / 写 PRD / 我提供信息，你帮我完善产品方案” → 等价 `/prd`。
-- “设计技术方案 / 做架构方案 / 根据 PRD 做技术方案” → 等价 `/design`。
+- “需求变了 / 这个设计要改” → 如果当前仍在 `ARCHITECTING` 且尚未进入开发，可回到 `REQUIREMENT_GATHERING` 修改 PRD；如果已经进入 `SPRINTING` 或之后，进入 RFC workflow。
+- “完善产品方案 / 写 PRD / 文档切片 / 我提供信息，你帮我完善产品方案” → 在 `REQUIREMENT_GATHERING` 等价 `/prd`；在 `ARCHITECTING` 且尚未进入开发时，先流转回 `REQUIREMENT_GATHERING`，再一次只执行一个 `phase: "REQUIREMENT_GATHERING"` 的 `TASK-*`。
+- “设计技术方案 / 做架构方案 / 根据 PRD 做技术方案 / 切技术方案” → 等价 `/design`，一次只执行一个 `phase: "ARCHITECTING"` 的 `TASK-*`。
 - “开始开发 / 做当前任务 / 做下一个任务” → 等价 `/dev`。
 - “开始循环：写任务，执行任务 / 把开发循环跑完” → 等价 `/devloop`。
 - “跑测试 / 验证一下” → 运行当前 task 或阶段对应 gate。
@@ -167,17 +171,17 @@ Strong success criteria 可以让你 independent loop。Weak criteria，例如
 - “刷新文档总览 / 同步 overview” → 等价 `/overview`。
 - `/plan` 和 `/goal` 是客户端模式入口，不由 Harness 自动开启；用户可以手动组合，例如 `/plan /prd`、`/plan 完善产品方案`、`/goal /devloop` 或 `/goal 开始循环：写任务，执行任务`。
 
-Parallel Execution 是可选协作协议，不是默认模式，也不是 CLI 自动启动 Agent 的承诺。只有用户明确要求多 agent、并行或多 worktree，且当前阶段适合拆分时，Agent 才能在 `plan.yaml` 增加 `parallel_execution`。如果当前 runtime 支持 subagent，由主 Agent 使用 `runtime_managed` 模式编排；否则使用 `user_orchestrated` 模式，主 Agent 生成每个 worker 的可复制 prompt，用户手动打开对话或 worktree 后粘贴执行。worker 之间不要求通信，最终事实源更新、review、merge/cherry-pick 和总 gate 由主 Agent 负责。
+Parallel Execution 是可选协作协议，不是默认模式，也不是 CLI 自动启动 Agent 的承诺。只有用户明确要求多 agent、并行或多 worktree，且当前阶段适合拆分时，Agent 才能在 `plan.yaml` 增加 `parallel_execution`。`parallel_execution` 不保存 `phase` 或 `linked_task_id`；当前阶段读取 `lifecycle.yaml#current_phase`，当前任务读取 `plan.yaml#current_task_id`。如果当前 runtime 支持 subagent，由主 Agent 使用 `runtime_managed` 模式编排；否则使用 `user_orchestrated` 模式，主 Agent 生成每个 worker 的可复制 prompt，用户手动打开对话或 worktree 后粘贴执行。worker 之间不要求通信，最终事实源更新、review、merge/cherry-pick 和总 gate 由主 Agent 负责。
 
 如果自然语言意图会改变阶段、创建或删除 task、提交、push 或发布，Agent 先用一句话说明将执行的动作和验证方式，再继续。
 
 - `/status`：报告当前阶段、角色、任务、阻塞项和下一步动作。
 - `/next`：运行当前阶段映射的 workflow skill。
-- `/advance`：校验当前阶段出口 gate，通过后才尝试流转。
+- `/advance`：校验当前阶段出口 gate，通过后才尝试流转；`ARCHITECTING` 的可选返回目标是 `REQUIREMENT_GATHERING`，用于开发前修改 PRD。
 - `/rfc <file>`：挂起当前流程并进入 RFC recalibration。
-- `/prd`：在 `REQUIREMENT_GATHERING` 调用产品方案工作流，澄清需求并更新 PRD、验收标准、open questions、`.docs/INDEX.md` 和 overview。
-- `/design`：在 `ARCHITECTING` 调用架构和技术方案工作流，基于 PRD 更新 architecture、tech plan 和 `plan.draft.yaml`。
-- `/dev`：在 `SPRINTING` 创建或选择下一个最小 DEV task，执行一个 task，跑 gate，更新模块级 implementation doc，按两段 commit/push 闭环后停止。
+- `/prd`：在 `REQUIREMENT_GATHERING` 创建或选择一个最小 `TASK-*` task，澄清需求或切片文档，并只更新当前 task 对应的 PRD、验收标准、open questions、`.docs/INDEX.md` 和 overview；如果当前是 `ARCHITECTING` 且尚未进入开发，可先回到 `REQUIREMENT_GATHERING`。
+- `/design`：在 `ARCHITECTING` 创建或选择一个最小 `TASK-*` task，基于 PRD 生成或切分当前 task 对应的 architecture、tech plan 和 `plan.draft.yaml`。
+- `/dev`：在 `SPRINTING` 创建或选择下一个最小 `TASK-*` development task，执行一个 task，跑 gate，更新模块级 implementation doc，按两段 commit/push 闭环后停止。
 - `/devloop`：在 `SPRINTING` 连续运行 `/dev` 循环，直到没有明确可创建/执行的任务，或遇到需求、架构、allowed_paths、gate、commit/push blocker。
 - `/syncdocs`：同步 `.docs/INDEX.md` 与当前文档事实源。
 - `/overview`：运行 `make docs-overview`，刷新 `.docs/<stage>/overview.md` 派生视图。

package/assets/docs/README.md

@@ -60,8 +60,9 @@ npx sdlc-harness init --adopt
 | 同步 managed workflow 文件 | `npx sdlc-harness sync` | 从包内 canonical assets 物化 `AGENTS.md` managed block、workflow skills、templates、policies、Makefile 片段和 GitHub workflow |
 | 升级已接入项目 | `npx sdlc-harness upgrade` | 执行迁移并自动 `sync`，保留 state、docs、业务代码和本地 override |
 | 接入诊断 | `npx sdlc-harness doctor` | 检查 harness root、版本、schema、关键文件和 managed paths |
-| 阶段 gate | `npx sdlc-harness validate-*`、`make validate-current`、`make validate-harness` | 校验需求、设计、开发计划、Harness 骨架、提示词语言契约和 overview freshness |
+| 阶段 gate | `npx sdlc-harness validate-*`、`make validate-current`、`make validate-harness` | 校验需求、设计切片、开发、Review、测试、发布、RFC、Harness 骨架、提示词语言契约和 overview freshness |
 | 生命周期工作流 | `lifecycle.yaml`、`plan.yaml`、`.docs/**` | 固定 REQUIREMENT_GATHERING、ARCHITECTING、SPRINTING、REVIEWING、TESTING、RELEASING、RFC_RECALIBRATION 等阶段事实链 |
+| 阶段小任务管控 | `plan.yaml`、`make validate-plan` | 每个阶段的 Agent 主任务都应拆成足够小的 `TASK-*` open task，并用 `phase` 标明所属阶段 |
 | 自然语言控制 | `AGENTS.md` + workflow skills | 用户可说“继续”“开始开发”“跑测试”“需求变了”等，由 Agent 映射到 `/next`、`/dev`、`/test`、RFC 等动作 |
 | 可选并行执行合同 | `plan.yaml#parallel_execution` | 用户明确要求多 agent/并行/多 worktree 时启用；支持 runtime-managed subagents 或 user-orchestrated worker prompts |
 | Workflow skills | `<harnessRoot>/skills/pjsdlc_*/SKILL.md` | 提供 PM、架构、开发、实现文档、Review、测试、发布、RFC 等阶段角色提示词 |
@@ -81,7 +82,9 @@ npx sdlc-harness init --adopt
 现在到哪一步了？
 继续推进。
 我提供这些信息，帮我完善产品方案。
+把这个长产品方案切成 slices。
 根据 PRD 做技术方案。
+把现有技术方案切片。
 根据技术方案拆 task。
 开始开发当前 task。
 继续开发下一个任务。
@@ -92,7 +95,11 @@ npx sdlc-harness init --adopt
 准备 review。
 ```
 
-Agent 会读取 `<harnessRoot>/state/lifecycle.yaml` 和 `<harnessRoot>/state/plan.yaml`，再按当前阶段选择对应 workflow skill、产物和 gate。
+Agent 会读取 `<harnessRoot>/state/lifecycle.yaml` 和 `<harnessRoot>/state/plan.yaml`，再按当前阶段选择对应 workflow skill、产物和 gate。任何阶段的 Agent 主任务都不是一次性长生成：产品方案、技术方案、文档切片、基于上一阶段事实源生成、Review、测试、发布和 RFC 处理，都应先落成一个最小 `TASK-*` open task，并设置对应 `phase`；当前轮只执行一个 task，写入 `result_docs` 或 `implementation_doc`、更新索引和 overview，运行 `make validate-plan`，任务完成后再从 `plan.yaml` 移除。
+
+在尚未进入开发前，`ARCHITECTING` 可以回到 `REQUIREMENT_GATHERING` 修改 PRD：Manager 使用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 切回 PM/PRD 工作流，完成 PRD task 和 `validate-pm` 后，再用 `python3 tools/transition.py --to ARCHITECTING` 回到设计阶段。进入 `SPRINTING` 后的需求变化仍走 RFC workflow。
+
+`validate-design` 会把架构阶段的语义切片作为硬 gate：`overview.md` 不计入 deliverables，`plan.draft.yaml` 中每个开发 draft task 必须通过 `docs.tech_plan` 指向存在的 tech plan slice；多个开发 draft task 默认需要不同 primary tech plan slice。PRD、tech plan 或 draft task 明确出现 AI provider / copilot、外部系统边界、合规 / 权限 / 审计等横切主题时，也需要对应的专门 architecture slice。
 
 ### Workflow skill 如何生效
 
@@ -136,6 +143,8 @@ override 文件支持两种写法：普通项目追加片段，或带 `name`/`de
 - `runtime_managed`：当前 Agent runtime 支持创建 subagent 时，由主 Agent 分配 worker、等待结果、review、merge/cherry-pick 并跑总 gate。
 - `user_orchestrated`：runtime 不能自动创建 subagent 时，主 Agent 生成每个 worker 的可复制 prompt；用户手动打开多个对话或 worktree 后粘贴执行。
 
+`parallel_execution` 不保存当前阶段或当前任务副本；阶段只从 `lifecycle.yaml#current_phase` 读取，当前任务只从 `plan.yaml#current_task_id` 读取。
+
 Harness CLI v1 不承诺自动启动 Codex agent，也不要求 worker 之间通信。worker 只处理自己的 `owned_paths` 和 gate，最终 PRD、plan、implementation doc、test result、overview 等事实源由主 Agent 集成。
 
 常用快捷入口：
@@ -144,9 +153,9 @@ Harness CLI v1 不承诺自动启动 Codex agent，也不要求 worker 之间通
 |---|---|---|
 | `/status` | 现在到哪一步了 | 读取 lifecycle/plan，报告当前阶段、任务、阻塞项和下一步 |
 | `/next` | 继续推进 | 按当前阶段的 `active_skill` 执行下一步 |
-| `/prd` | 完善产品方案 | 在需求阶段澄清用户目标、补齐 PRD、验收标准和 open questions |
-| `/design` | 设计技术方案 | 在架构阶段基于 PRD 生成或更新架构、技术方案和 `plan.draft.yaml` |
-| `/dev` | 做下一个任务 | 创建或选择下一个最小 DEV task，完成一个 task 闭环后停止 |
+| `/prd` | 完善产品方案 | 在需求阶段创建或选择一个最小 `TASK-*` task；如果当前仍在架构阶段且未进入开发，可先回到 `REQUIREMENT_GATHERING` 修改 PRD |
+| `/design` | 设计技术方案 | 在架构阶段创建或选择一个最小 `TASK-*` task，生成或切分当前 architecture / tech plan / `plan.draft.yaml` 产物 |
+| `/dev` | 做下一个任务 | 创建或选择下一个最小 `TASK-*` development task，完成一个 task 闭环后停止 |
 | `/devloop` | 开始循环：写任务，执行任务 | 连续运行 `/dev`，直到没有明确任务或遇到 blocker |
 | `/test` | 跑一下当前验证 | 运行当前 task 或阶段对应 gate |
 | `/review` | 准备 review | 进入只读 Review workflow |
@@ -179,6 +188,12 @@ npx sdlc-harness upgrade
 make validate-current
 ```
 
+校验当前 open task 合同：
+
+```sh
+make validate-plan
+```
+
 校验整个 Harness：
 
 ```sh

package/assets/make/sdlc-harness.mk

@@ -1,6 +1,6 @@
 PYTHON ?= python3
 
-.PHONY: help status docs-overview validate-doc-overviews validate-harness validate-current validate-pm validate-design validate-dev validate-review validate-test validate-release validate-rfc lint test-current-domain test-all build
+.PHONY: help status docs-overview validate-doc-overviews validate-harness validate-current validate-plan validate-pm validate-design validate-dev validate-review validate-test validate-release validate-rfc lint test-current-domain test-all build
 
 help:
 	@echo "AI SDLC Harness commands"
@@ -9,6 +9,7 @@ help:
 	@echo "  make validate-doc-overviews 校验 .docs 各阶段 overview.md 是否最新"
 	@echo "  make validate-harness    校验 Harness 骨架、配置和提示词语言契约"
 	@echo "  make validate-current    运行当前 lifecycle phase 的 gate"
+	@echo "  make validate-plan       校验 plan.yaml task 合同，允许当前 open task"
 	@echo "  make validate-pm         校验产品需求产物"
 	@echo "  make validate-design     校验架构设计、技术方案和任务草案"
 	@echo "  make validate-dev        校验 sprint 任务状态、路径、代码 gate 和实现文档"
@@ -34,6 +35,10 @@ validate-harness:
 validate-current:
 	$(PYTHON) tools/run_current_gate.py
 
+validate-plan:
+	$(PYTHON) tools/validate_plan.py --allow-open
+	$(PYTHON) tools/validate_allowed_paths.py
+
 validate-pm:
 	test -f .docs/INDEX.md
 	$(PYTHON) tools/validate_prd.py

package/assets/policies/allowed_paths.yaml

@@ -31,17 +31,20 @@ phases:
   REVIEWING:
     read_only_source: true
     write:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/06_review/**"
       - ".docs/INDEX.md"
 
   TESTING:
     write:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/07_test/**"
       - "tests/**"
       - ".docs/INDEX.md"
 
   RELEASING:
     write:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/08_release/**"
       - ".docs/INDEX.md"
 

package/assets/policies/gates.yaml

@@ -5,6 +5,18 @@ gates:
     required_for:
       - "all"
 
+  validate-plan:
+    command: "make validate-plan"
+    purpose: "验证当前 open task 合同，允许任务执行中保留 open task"
+    required_for:
+      - "REQUIREMENT_GATHERING"
+      - "ARCHITECTING"
+      - "SPRINTING"
+      - "REVIEWING"
+      - "TESTING"
+      - "RELEASING"
+      - "RFC_RECALIBRATION"
+
   validate-pm:
     command: "make validate-pm"
     purpose: "验证 PRD、验收标准、Out of Scope 和 Open Questions"

package/assets/policies/phase_contracts.yaml

@@ -15,8 +15,10 @@ phases:
     role: "pm"
     skill: "pjsdlc_pm_prd"
     inputs:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/00_raw/"
     outputs:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/01_product/"
       - ".docs/INDEX.md"
     gates:
@@ -28,15 +30,19 @@ phases:
     role: "architect"
     skill: "pjsdlc_architect_design"
     inputs:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/01_product/"
       - ".docs/02_architecture/"
     outputs:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/02_architecture/"
       - ".docs/03_tech_plan/"
       - "<harnessRoot>/state/plan.draft.yaml"
     gates:
       - "make validate-design"
     next: "SPRINTING"
+    returns:
+      - "REQUIREMENT_GATHERING"
 
   SPRINTING:
     goal: "按任务状态执行开发、测试和实现文档沉淀"
@@ -60,11 +66,13 @@ phases:
     role: "reviewer"
     skill: "pjsdlc_reviewer"
     inputs:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/01_product/"
       - ".docs/03_tech_plan/"
       - ".docs/04_implementation/"
       - "git diff"
     outputs:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/06_review/REVIEW_REPORT.md"
     gates:
       - "make validate-review"
@@ -75,11 +83,13 @@ phases:
     role: "tester"
     skill: "pjsdlc_tester"
     inputs:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/01_product/"
       - ".docs/03_tech_plan/"
       - ".docs/04_implementation/"
       - ".docs/06_review/"
     outputs:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/07_test/"
       - "tests/"
     gates:
@@ -91,9 +101,11 @@ phases:
     role: "release_manager"
     skill: "pjsdlc_release_manager"
     inputs:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/07_test/"
       - "build artifacts"
     outputs:
+      - "<harnessRoot>/state/plan.yaml"
       - ".docs/08_release/"
     gates:
       - "make validate-release"

package/assets/skills/pjsdlc_architect_design/SKILL.md

@@ -17,9 +17,14 @@ description: Use during ARCHITECTING to create architecture docs, technical plan
 
 架构产物应区分稳定边界和实现计划：architecture slice 记录领域边界、子系统、关键风险和长期约束；tech plan slice 记录接口契约、数据模型、模块方案、任务拆分和 gate。不要把重大架构变化藏在 task 描述里。
 
+架构和技术方案产出本身也是 workflow task，而不是一次性长文档生成。无论来源是对话式设计、既有完整技术方案切片，还是根据 PRD/architecture 事实源生成新方案，都要先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "ARCHITECTING"`，只完成当前 `current_task_id` 对应的一片 architecture / tech plan / ADR / `plan.draft.yaml` 产物。不要在一个任务里连续创建大量设计文件；如果需要多个 slices，先拆出 pending tasks，当前轮只执行一个 task。
+
+如果在 `ARCHITECTING` 中发现 PRD 缺失、验收标准不清或产品边界需要调整，且项目尚未进入 `SPRINTING`，不要用架构文档替代产品事实。先收尾或移除当前 open design task，再请 Manager 使用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 回到 PM/PRD 工作流修改 `.docs/01_product/**`。进入 `SPRINTING` 后的需求变化走 RFC workflow。
+
 ## 输入
 
 - `.docs/INDEX.md`
+- `<harnessRoot>/state/plan.yaml`
 - 相关 `.docs/01_product/` PRD
 - 现有 `.docs/02_architecture/`
 - 当前代码结构概览
@@ -32,6 +37,7 @@ description: Use during ARCHITECTING to create architecture docs, technical plan
 - `.docs/03_tech_plan/` 下的技术方案
 - 需要长期保留的 ADR 写入 `.docs/05_decisions/`
 - `<harnessRoot>/state/plan.draft.yaml`
+- 更新后的 `<harnessRoot>/state/plan.yaml`
 - 更新后的 `.docs/INDEX.md`
 
 ## 语义切片
@@ -40,22 +46,45 @@ description: Use during ARCHITECTING to create architecture docs, technical plan
 - `.docs/03_tech_plan/` 按可实现范围、接口契约、数据模型、模块方案或任务组切片。
 - `.docs/05_decisions/` 按单个架构决策切片，即一份 ADR 只记录一个 durable decision。
 - 如果一个技术方案跨越多个独立模块，应拆成多个 tech plan slice，并在 `plan.draft.yaml` 中分别引用。
+- `plan.draft.yaml` 中每个开发 draft task 必须在 `docs.tech_plan` 引用已有 `.docs/03_tech_plan/` slice；多个开发 draft task 默认应引用不同的 primary tech plan slice，不能用一个总纲 tech plan 覆盖全部模块任务。
+- `overview.md` 是 generated artifact，不算 architecture / tech plan deliverable，也不能作为 `docs.tech_plan` 引用。
+- 如果 PRD、tech plan 或 draft task 明确出现 AI provider / AI copilot、外部系统边界、合规 / 权限 / 审计等横切主题，应各自有专门的 architecture slice；不要把多个横切架构问题都塞进一个总览文档。
 - 如果实现计划改变了已有模块边界，应更新相关 architecture slice，而不是只在 task 描述里补一句。
+- 如果用户明确要求把既有完整技术方案文件切成多个 `.docs/03_tech_plan/` slices，先确认 replacement slices 覆盖原文件中仍有效的接口契约、数据模型、模块方案、任务组和 gate；切片完成并更新 `plan.draft.yaml` 引用、`.docs/INDEX.md`、刷新 `overview.md` 后，删除被替代的完整 tech plan file，避免同一事实由完整文件和 slices 双重保留。
 - 每次新增、拆分、合并或废弃 slice 后，都要更新 `.docs/INDEX.md`。
 
+## Plan Protocol
+
+架构和技术方案阶段的方案生成、既有文档切片和上一阶段事实源合成都受 `plan.yaml` 管控：
+
+1. 没有 open task 时，先创建一个最小 `TASK-*` task，设置 `phase: "ARCHITECTING"` 和 `current_task_id`。
+2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 `.docs/02_architecture/`、`.docs/03_tech_plan/`、`.docs/05_decisions/` 或 `<harnessRoot>/state/plan.draft.yaml`。
+3. 单个 task 的目标应足够小：一个子系统 architecture slice、一个 tech plan slice、一个接口契约、一组开发任务草案，或从完整技术方案中切出的一个语义 slice。
+4. 如果需要多个 architecture / tech plan slices，先生成多个 pending `TASK-*` tasks 或至少创建当前 task 并在 `working_notes` 写明剩余 slices；当前轮只执行一个 task。
+5. 执行当前 task 时只编辑 `allowed_paths` 中的文件，完成后更新 `.docs/INDEX.md`、运行 `make docs-overview`，并至少运行 `make validate-plan`；阶段出口前再运行 `make validate-design`。
+6. task 完成后，从 `plan.yaml.tasks` 移除该 task；如果仍有 pending `TASK-*` design task，下一轮 `/design` 或 `/next` 再继续。
+7. 如果网络或上下文中断，新会话先读取 `current_task_id` 和当前 open task，按 `working_notes` 恢复，而不是重新生成全量技术方案。
+8. `make validate-design` 会硬性检查 `plan.draft.yaml` 的 task shape、`docs.tech_plan` 引用、tech plan primary slice 去重，以及横切 architecture slice；不要把这些要求只写成自然语言建议。
+
 ## 规则
 
 1. 技术方案必须引用 PRD 路径和 requirement IDs。
-2. 每个 open task 必须包含 `id`、`title`、`status`、`summary`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `implementation_doc`。
+2. 每个 open task 必须包含 `id`、`phase`、`title`、`status`、`summary`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；开发阶段 task 继续使用 `implementation_doc`。
 3. `plan.draft.yaml` 不得自动覆盖 `plan.yaml`。
-4. 风险或不清晰的问题按 `<harnessRoot>/pjsdlc_managed/policies/risk_matrix.yaml` 标记。
-5. 任务边界应足够小，能在一次开发执行内闭环；`implementation_doc` 应指向将被更新或新增的模块、子系统或核心数据流文档。
+4. `plan.draft.yaml` 中开发 draft task 的 `docs.tech_plan` 必须指向存在的 tech plan slice；如果 task 数量超过一个，不能全部指向同一个 primary tech plan 文件。
+5. 风险或不清晰的问题按 `<harnessRoot>/pjsdlc_managed/policies/risk_matrix.yaml` 标记。
+6. 任务边界应足够小，能在一次设计执行内闭环；`result_docs` 应指向将被更新或新增的 architecture、tech plan、ADR 或 `plan.draft.yaml` 文件。
+7. `make validate-design` 是阶段出口 gate；如果还有 open `TASK-*` design task，不要请求进入 `SPRINTING`。
 
 ## 完成检查
 
 - [ ] 架构文档和技术方案已生成。
 - [ ] 相关接口契约和数据结构已明确。
+- [ ] 当前设计产出或切片工作已绑定 `plan.yaml` 中一个最小 `TASK-*` task，并设置 `phase: "ARCHITECTING"`。
+- [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] 已判断 architecture / tech plan / ADR 的语义切片边界。
+- [ ] `plan.draft.yaml` 中每个开发 draft task 已通过 `docs.tech_plan` 绑定到对应 tech plan slice。
+- [ ] 如果用户要求把完整技术方案切成 tech plan slices，已删除被替代的完整 tech plan file，并同步 `plan.draft.yaml` 引用。
 - [ ] task draft 字段完整且范围清晰。
 - [ ] `.docs/INDEX.md` 已链接新增产物。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。

package/assets/skills/pjsdlc_dev_sprint/SKILL.md

@@ -15,7 +15,7 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 开始编码前，先确认当前 open task 是否完整，修改范围是否覆盖必要文件，验收标准是否能被测试或 gate 验证。如果发现任务边界、产品行为或技术方案不清晰，要停下来说明 blocker、给出可能解释和推荐下一步，而不是扩大范围继续写。
 
-`/dev` 和 `/devloop` 是开发阶段的两个入口。`/dev` 创建或选择下一个最小 DEV task，并只完成一个 task 闭环后停止。`/devloop` 连续运行 `/dev`，直到技术方案中没有明确可创建/执行的任务，或遇到需求、架构、allowed_paths、gate、commit/push blocker。
+`/dev` 和 `/devloop` 是开发阶段的两个入口。`/dev` 创建或选择下一个最小 `TASK-*` development task，设置 `phase: "SPRINTING"`，并只完成一个 task 闭环后停止。`/devloop` 连续运行 `/dev`，直到技术方案中没有明确可创建/执行的任务，或遇到需求、架构、allowed_paths、gate、commit/push blocker。
 
 实现时遵循小步闭环：先检查 `git status`，确认工作区没有未归属到当前 task 的脏变更；再定位相关代码和测试，做必要修改，运行 gate，修复失败，写入或更新相关 implementation doc 并刷新文档派生视图。此时先不要从 `plan.yaml` 移除当前 task，要在当前 task 仍位于 `plan.yaml` 时创建 task implementation commit；随后再移除 task，创建 task completion ledger commit，并 push 两个 commit。不要顺手重构、重排格式或处理无关问题；如果发现无关风险，只记录或报告。
 
@@ -44,23 +44,23 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 - `SPRINTING` 阶段的执行单元是 `current_task_id`，不要在开发中重新生成整个 Sprint 计划。
 - 当前 task 是开发阶段的执行单元、修改边界和提交边界；implementation doc 的长期语义切片是模块、子系统或核心数据流。
-- open task 在 `plan.yaml` 中直接保存 `docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和必要的 `working_notes`。
+- open task 在 `plan.yaml` 中直接保存 `phase: "SPRINTING"`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria`、`implementation_doc` 和必要的 `working_notes`。
 - task implementation commit 必须发生在 task 移除之前，避免实现变更和计划短期化混在同一个提交里。
 - task completion ledger commit 发生在 implementation commit 之后，只负责将该 task 从当前 `plan.yaml` 移除。
-- 一个开发 task 默认对应一个主要 implementation commit 和一个轻量 completion ledger commit。implementation commit message 应包含 task id，例如 `DEV-003: implement login rate limit`；push 成功前，不进入下一个 task。
+- 一个开发 task 默认对应一个主要 implementation commit 和一个轻量 completion ledger commit。implementation commit message 应包含 task id，例如 `TASK-003: implement login rate limit`；push 成功前，不进入下一个 task。
 - 本 Skill 不直接重切 PRD 或 tech plan；如果发现上游语义边界错误，进入 `BLOCKED`、创建 RFC，或请求回到 `ARCHITECTING`。
 - gate 通过后调用 `pjsdlc_implementation_doc`，由该 Skill 按真实实现更新或新增 `.docs/04_implementation/` 模块级 slice。
 - 如果一个任务实际变成多个独立实现边界，应停止扩大范围，拆分后续任务或回到任务规划。
-- `/dev` 是单任务执行入口：没有 open task 时，先根据 PRD、architecture、tech plan 和 `plan.draft.yaml` 创建一个最小 open task；已有 open task 时，直接执行该 task；完成后停止。
+- `/dev` 是单任务执行入口：没有 open task 时，先根据 PRD、architecture、tech plan 和 `plan.draft.yaml` 创建一个最小 `TASK-*` open task；已有 open task 时，直接执行该 task；完成后停止。
 - `/devloop` 是连续执行入口：每完成一个 task 并 push 两段提交后，重新读取 lifecycle、plan、PRD、architecture 和 tech plan，再决定是否创建/执行下一个最小 task；没有明确任务或出现 blocker 时停止并报告。
-- Parallel Execution 是当前 task 的可选协作方式，不替代 task completion protocol；`SPRINTING` 并行必须用 `parallel_execution.linked_task_id` 绑定当前 `current_task_id`。
+- Parallel Execution 是当前 task 的可选协作方式，不替代 task completion protocol；`SPRINTING` 并行从 lifecycle 的 `current_phase` 和 plan 的 `current_task_id` 推断上下文，不在 `parallel_execution` 内重复保存。
 
 ## Plan Protocol
 
 每个 open task 都必须在 `plan.yaml` 中包含完整执行合同：
 
 1. `current_task_id` 指向正在执行的 open task。
-2. open task 直接声明 `docs`、`allowed_paths`、`required_gates`、`acceptance_criteria`。
+2. open task 直接声明 `phase: "SPRINTING"`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `implementation_doc`。
 3. 任务执行中只保留恢复所需的简短 `working_notes`。
 4. gate、implementation doc、`.docs/INDEX.md` 和 `overview.md` 完成后，在当前 task 仍位于 `plan.yaml` 时创建 task implementation commit。
 5. implementation commit 完成后，再把该 task 从 `plan.yaml` 的 `tasks` 列表移除，并保留/递增 `next_task_sequence`。

package/assets/skills/pjsdlc_manager/SKILL.md

@@ -44,24 +44,26 @@ Parallel Execution 是显式 opt-in：只有用户明确提出“并行”“多
 11. 用户自然语言询问状态时，等价执行 `/status`。
 12. 用户自然语言要求继续、推进或下一步时，等价执行 `/next`。
 13. 用户自然语言要求进入下一阶段或检查是否可进入下一阶段时，等价执行 `/advance`。
-14. 用户自然语言表达需求或设计变化时，进入 RFC workflow。
-15. 用户输入 `/prd`，或自然语言要求“完善产品方案”“写 PRD”“我提供信息，你帮我完善产品方案”时，如果 `current_phase` 是 `REQUIREMENT_GATHERING`，调用产品方案工作流并更新 PRD、验收标准和 open questions；否则说明当前阶段冲突和推荐路径。
-16. 用户输入 `/design`，或自然语言要求“设计技术方案”“做架构方案”“根据 PRD 做技术方案”时，如果 `current_phase` 是 `ARCHITECTING`，调用架构和技术方案工作流并更新 architecture、tech plan 和 `plan.draft.yaml`；否则说明当前阶段冲突和推荐路径。
-17. 用户输入 `/dev`，或自然语言要求“开始开发”“做当前任务”“做下一个任务”“继续开发下一个任务”时，如果 `current_phase` 是 `SPRINTING`，创建或选择一个最小 DEV task 并执行一个 task 闭环；否则说明当前阶段冲突和推荐路径。
+14. 用户自然语言表达需求或设计变化时，先判断阶段：如果当前是 `ARCHITECTING` 且尚未进入开发，可以说明将回到 `REQUIREMENT_GATHERING` 并用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 切回 PM/PRD 工作流；如果当前是 `SPRINTING` 或之后，进入 RFC workflow。
+15. 用户输入 `/prd`，或自然语言要求“完善产品方案”“写 PRD”“文档切片”“我提供信息，你帮我完善产品方案”时，如果 `current_phase` 是 `REQUIREMENT_GATHERING`，调用产品方案工作流；如果 `current_phase` 是 `ARCHITECTING`，先确认没有 open design task 需要收尾，说明将开发前回退到 `REQUIREMENT_GATHERING`，再用 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 切换到 PM/PRD 工作流；该工作流必须先创建或选择一个最小 `TASK-*` open task，并设置 `phase: "REQUIREMENT_GATHERING"`，再执行一个 PRD 生成或切片 task；否则说明当前阶段冲突和推荐路径。
+16. 用户输入 `/design`，或自然语言要求“设计技术方案”“做架构方案”“根据 PRD 做技术方案”“切技术方案”时，如果 `current_phase` 是 `ARCHITECTING`，调用架构和技术方案工作流；该工作流必须先创建或选择一个最小 `TASK-*` open task，并设置 `phase: "ARCHITECTING"`，再执行一个 architecture / tech plan / `plan.draft.yaml` 生成或切片 task；否则说明当前阶段冲突和推荐路径。
+17. 用户输入 `/dev`，或自然语言要求“开始开发”“做当前任务”“做下一个任务”“继续开发下一个任务”时，如果 `current_phase` 是 `SPRINTING`，创建或选择一个最小 `TASK-*` development task 并执行一个 task 闭环；否则说明当前阶段冲突和推荐路径。
 18. 用户输入 `/devloop`，或自然语言要求“开始循环：写任务，执行任务”“把开发循环跑完”“连续开发”时，如果 `current_phase` 是 `SPRINTING`，连续运行 `/dev` 循环，直到没有明确可做任务或遇到 blocker；否则说明当前阶段冲突和推荐路径。
 19. 用户自然语言要求跑测试或验证时，运行当前 task 或当前阶段的对应 gate。
 20. 用户明确要求并行、多 agent 或多 worktree 时，先判断当前阶段是否是 `REQUIREMENT_GATHERING`、`SPRINTING` 或 `TESTING`；如果是，生成或使用 `parallel_execution.trigger: "user_requested"` 合同；否则说明当前阶段不支持并行合同。
 21. `runtime_managed` 模式只在当前 Agent runtime 真实具备 subagent 能力时使用；否则使用 `user_orchestrated` 并输出每个 worker 的可复制 prompt。
-22. 用户自然语言要求 review 时，进入只读 Review workflow，不直接改源码。
+22. 用户自然语言要求 review 时，如果 `current_phase` 是 `REVIEWING`，创建或选择一个最小 `TASK-*` review task，并设置 `phase: "REVIEWING"`；reviewer 只读源码，不直接改源码。
 23. 用户自然语言要求刷新文档总览时，运行 `make docs-overview`。
 24. `/plan` 和 `/goal` 是客户端模式入口，不由 Harness 自动开启；如果用户手动组合 `/plan` 或 `/goal` 与自然语言或宏指令，应按对应 workflow action 继续执行。
 25. 如果动作会改变阶段、创建或删除 task、提交、push 或发布，先用一句话说明即将执行的动作和验证方式，再继续。
 
 ## Plan Protocol
 
-每个 open task 都必须在 `plan.yaml` 中包含 `docs`、`allowed_paths`、`required_gates` 和 `acceptance_criteria`；done/cancelled task 不长期留在当前 `plan.yaml`。完成后的产物事实以模块、子系统或核心数据流级 implementation doc 为准，动作历史以 git/PR/CI/release 系统作为 cold archive，`next_task_sequence` 负责继续分配后续 task id。
+每个 open task 都必须在 `plan.yaml` 中包含 `id`、`phase`、`docs`、`allowed_paths`、`required_gates` 和 `acceptance_criteria`；新 task 统一使用 `TASK-*` id，历史 `DEV-*`、`PRD-*`、`DES-*` task 只作为兼容输入保留。文档和流程产物 task 使用 `result_docs` 指向本 task 产出的 PRD、architecture、tech plan、ADR、review、test、release、RFC 或 `plan.draft.yaml`，开发 task 使用 `implementation_doc` 指向模块级实现事实。done/cancelled task 不长期留在当前 `plan.yaml`。完成后的产物事实以对应 `.docs/**` slice、`plan.draft.yaml` 或模块级 implementation doc 为准，动作历史以 git/PR/CI/release 系统作为 cold archive，`next_task_sequence` 负责继续分配后续 task id。
 
-`parallel_execution` 是可选顶层合同，缺省表示串行。启用后必须声明 `enabled`、`trigger`、`mode`、`phase`、`coordinator`、`workers` 和 `integration`；`SPRINTING` 并行还必须通过 `linked_task_id` 绑定当前 `current_task_id`。
+`/prd`、`/design`、`/dev`、`/review`、`/test`、`/release` 和 `/rfc` 都是单 task 推进：默认只完成一个 `TASK-*`。`validate-plan` 用于检查当前 open task 合同是否完整；阶段出口 gate `validate-pm`、`validate-design`、`validate-dev`、`validate-review`、`validate-test`、`validate-release` 和 `validate-rfc` 都要求没有 open task 残留。
+
+`parallel_execution` 是可选顶层合同，缺省表示串行。启用后必须声明 `enabled`、`trigger`、`mode`、`coordinator`、`workers` 和 `integration`；不要在合同内重复保存 `phase` 或 `linked_task_id`，当前阶段来自 lifecycle 的 `current_phase`，当前任务来自 plan 的 `current_task_id`。
 
 `lifecycle.yaml` 和 `plan.yaml` 只用于当前可执行状态。默认不要读取过去 phase/task/gate 执行流水；只有用户明确要求 forensic/audit/regression 追溯时，才临时查询 git、PR、CI 或 release 记录。
 

package/assets/skills/pjsdlc_pm_prd/SKILL.md

@@ -17,10 +17,15 @@ description: Use during REQUIREMENT_GATHERING to turn raw input into PRD slices
 
 产出 PRD 时，优先让后续架构和测试能直接使用：每条需求应有清晰 requirement ID、验收条件、Out of Scope、风险或依赖。对话中出现新范围时，要判断是更新当前 slice、拆出新 slice，还是进入 RFC。
 
+PRD 产出本身是 workflow task，而不是一次性长文档生成。无论来源是对话式需求澄清、既有完整文档切片，还是根据 `.docs/00_raw/` 等事实源合成产品方案，都要先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "REQUIREMENT_GATHERING"`，只完成当前 `current_task_id` 对应的一片产物。不要在一个任务里连续创建大量 PRD 文件；如果需要多个 slices，先把后续 slices 拆成 pending tasks，当前轮只执行一个 task，方便网络中断后按 `plan.yaml` 恢复。
+
+如果项目已经进入 `ARCHITECTING` 但尚未进入 `SPRINTING`，用户发现 PRD 需要补充或调整时，Manager 可以先通过 `python3 tools/transition.py --to REQUIREMENT_GATHERING` 回到本 Skill。此时按正常 PRD task protocol 修改 `.docs/01_product/**`，完成后再通过 `validate-pm` 回到 `ARCHITECTING`；进入 `SPRINTING` 后的需求变化仍走 RFC workflow。
+
 如果用户在需求阶段明确要求并行、多 agent 或多 worktree，Parallel Execution 只能用于调研、草稿、场景拆解、风险列表或 open questions 收集。worker 不直接写最终 PRD；主 Agent 必须合成最终 `.docs/01_product/**`，并把假设、分歧和未决项写入 PRD。没有用户显式要求时，不要启用 `parallel_execution`。
 
 ## 输入
 
+- `<harnessRoot>/state/plan.yaml`
 - 用户需求或原始记录
 - `.docs/00_raw/`
 - 现有 `.docs/01_product/`
@@ -31,6 +36,7 @@ description: Use during REQUIREMENT_GATHERING to turn raw input into PRD slices
 
 - `.docs/00_raw/` 下的原始需求记录
 - `.docs/01_product/` 下的一个或多个 PRD slice
+- 更新后的 `<harnessRoot>/state/plan.yaml`
 - 更新后的 `.docs/INDEX.md`
 
 ## 语义切片
@@ -39,16 +45,31 @@ description: Use during REQUIREMENT_GATHERING to turn raw input into PRD slices
 - `.docs/01_product/` 按业务能力、用户场景、验收边界切片。
 - 如果新增内容仍属于同一业务能力，只更新原 PRD slice。
 - 如果新增内容形成独立用户场景、独立验收标准或独立 Out of Scope，应创建新的 PRD slice。
+- 如果用户明确要求把既有完整 PRD/产品方案文件切成多个 `.docs/01_product/` slices，先确认 replacement slices 覆盖原文件中仍有效的全部需求事实；切片完成并更新 `.docs/INDEX.md`、刷新 `overview.md` 后，删除被替代的完整文件，避免同一事实由完整文件和 slices 双重保留。不要因此删除 `.docs/00_raw/` 原始记录，除非用户明确要求。
 - 每次新增、拆分、合并或废弃 slice 后，都要更新 `.docs/INDEX.md`。
 
+## Plan Protocol
+
+需求阶段的 PRD 生成、既有文档切片和事实源合成都受 `plan.yaml` 管控：
+
+1. 没有 open task 时，先创建一个最小 `TASK-*` task，设置 `phase: "REQUIREMENT_GATHERING"` 和 `current_task_id`。
+2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 `.docs/00_raw/` 或 `.docs/01_product/` 文件。
+3. 单个 task 的目标应足够小：一段原始需求归档、一个用户场景 PRD slice、一个验收边界、一个 open questions 集合，或从完整文档中切出的一个语义 slice。
+4. 如果用户要求切成多个 slices，先生成多个 pending `TASK-*` tasks 或至少创建当前 task 并在 `working_notes` 写明剩余 slices；当前轮只执行一个 task。
+5. 执行当前 task 时只编辑 `allowed_paths` 中的文件，完成后更新 `.docs/INDEX.md`、运行 `make docs-overview`，并至少运行 `make validate-plan`；阶段出口前再运行 `make validate-pm`。
+6. task 完成后，从 `plan.yaml.tasks` 移除该 task；如果仍有 pending `TASK-*` PRD task，下一轮 `/prd` 或 `/next` 再继续。
+7. 如果网络或上下文中断，新会话先读取 `current_task_id` 和当前 open task，按 `working_notes` 恢复，而不是重新生成全量 PRD。
+
 ## 规则
 
 1. 有价值的用户原始表述应保存在 `.docs/00_raw/`。
 2. 每个 PRD 必须包含目标、用户场景、功能需求、验收标准、Out of Scope 和 Open Questions。
 3. 不确定内容必须写入 `Open Questions`，不要静默假设。
 4. 如果需求与既有架构或已接受决策冲突，先写冲突说明，不要直接编写技术方案。
-5. 需求阶段并行必须使用 `parallel_execution.trigger: "user_requested"`；`runtime_managed` 只在当前 runtime 支持 subagent 时使用，否则输出 `user_orchestrated` worker prompt。
-6. 本 Skill 不直接进入开发；PRD 完成后请求 `manager` 运行阶段出口 gate。
+5. 需求阶段一次只执行一个 `TASK-*` task；不要在单次回复里创建或改写大量 PRD slices。
+6. `make validate-pm` 是阶段出口 gate；如果还有 open `TASK-*` PRD task，不要请求进入 `ARCHITECTING`。
+7. 需求阶段并行必须使用 `parallel_execution.trigger: "user_requested"`；`runtime_managed` 只在当前 runtime 支持 subagent 时使用，否则输出 `user_orchestrated` worker prompt。
+8. 本 Skill 不直接进入开发；PRD 完成后请求 `manager` 运行阶段出口 gate。
 
 ## 完成检查
 
@@ -56,7 +77,10 @@ description: Use during REQUIREMENT_GATHERING to turn raw input into PRD slices
 - [ ] Acceptance Criteria 可测试。
 - [ ] Out of Scope 明确。
 - [ ] Open Questions 有 owner/status。
+- [ ] 当前 PRD 产出或切片工作已绑定 `plan.yaml` 中一个最小 `TASK-*` task，并设置 `phase: "REQUIREMENT_GATHERING"`。
+- [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] 已判断是否需要新增、拆分、合并或废弃 PRD slice。
+- [ ] 如果用户要求把完整 PRD/产品方案切成 slices，已删除被替代的完整文件，并保留必要的 `.docs/00_raw/` 原始记录。
 - [ ] 如果用户要求并行，worker output 已由主 Agent 合成，最终 PRD 不由 worker 直接写入。
 - [ ] `.docs/INDEX.md` 已链接新增产物。
 - [ ] 已运行 `make docs-overview` 刷新 `.docs/<stage>/overview.md`。