agent-project-sdlc 0.1.11 → 0.1.12

package/README.md

@@ -76,10 +76,18 @@ The CLI does not promise to automatically launch Codex agents. Workers do not ne
 
 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.
 
+The generic rule is that any workflow promoting a draft task into a formal `TASK-*` in `plan.yaml` must remove the source draft from its draft queue in the same state update. The formal task is then recovered only from `plan.yaml`; completed history lives in implementation docs, git, PR and CI records. The built-in Harness draft queue is currently `plan.draft.yaml.tasks[]`, which means unadopted development drafts only. `/devloop` treats the development queue as exhausted only when both `plan.yaml.tasks[]` and `plan.draft.yaml.tasks[]` have no executable task.
+
 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.
 
+## ADR And Memory Boundaries
+
+`.docs/05_decisions/` stores ADRs, or Architecture Decision Records. ADRs answer why a key architecture choice was made instead of another option. Architecture and tech plan slices may include local design rationale; create an ADR when a decision has real alternatives, affects multiple modules or stages, is likely to be challenged later, or would be expensive to reverse.
+
+`<harnessRoot>/state/memory.md` is only a short cross-stage reminder and navigation surface. It answers what an agent should remember next time and where to find the source. Memory may link to ADRs, PRDs, tech plans or implementation docs; full context, alternatives, tradeoffs and long-term consequences belong in `.docs/05_decisions/` ADRs or other formal `.docs/**` fact sources.
+
 ## Common Commands
 
 ```sh

package/assets/agents/AGENTS_CORE.md

@@ -38,6 +38,8 @@
 - 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`。
+- 通用规则：任何阶段或工作流如果把 draft task promote 成 `plan.yaml` 中的正式 `TASK-*`，必须同次从源 draft queue 删除该 draft；draft queue 永远表示尚未采用的草案，不承担完成历史。
+- 当前内置 draft queue 只有 `plan.draft.yaml.tasks[]`，默认用于 `ARCHITECTING` 产出开发草案、`SPRINTING` 消费开发草案。
 - 不维护 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。
@@ -181,8 +183,8 @@ Parallel Execution 是可选协作协议，不是默认模式，也不是 CLI
 - `/rfc <file>`：挂起当前流程并进入 RFC recalibration。
 - `/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。
+- `/dev`：在 `SPRINTING` 创建或选择下一个最小 `TASK-*` development task；如果从 `plan.draft.yaml.tasks[]` promote draft，必须同次消费并删除该 draft；随后执行一个 task，跑 gate，更新模块级 implementation doc，按两段 commit/push 闭环后停止。
+- `/devloop`：在 `SPRINTING` 连续运行 `/dev` 循环，直到 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可执行任务，或遇到需求、架构、allowed_paths、gate、commit/push blocker。
 - `/syncdocs`：同步 `.docs/INDEX.md` 与当前文档事实源。
 - `/overview`：运行 `make docs-overview`，刷新 `.docs/<stage>/overview.md` 派生视图。
 - `/review`：运行只读 Review 工作流。

package/assets/docs/README.md

@@ -97,10 +97,20 @@ npx sdlc-harness init --adopt
 
 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` 移除。
 
+通用规则是：任何阶段或工作流如果把 draft task promote 成 `plan.yaml` 中的正式 `TASK-*`，必须在同一次状态更新里从源 draft queue 删除该 draft；正式 task 的恢复现场只保存在 `plan.yaml`，完成历史由 implementation docs、git/PR/CI 记录承担。当前 Harness 内置的 draft queue 只有 `plan.draft.yaml.tasks[]`，它表示尚未采用的开发草案；`/devloop` 只有在 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可执行任务时，才把开发队列视为耗尽。
+
+技术方案阶段需要产出 `plan.draft.yaml`，是为了解决跨阶段交接和当前执行队列纯净性的冲突。`ARCHITECTING` 必须在进入开发前证明方案可以拆成具体、可验证的开发单元，包括修改范围、gate、implementation doc 和执行顺序；但这些未来开发 task 如果直接进入 `plan.yaml`，会和当前架构阶段 task 混在一起，让阶段 gate 无法区分“架构任务未完成”和“下一阶段任务已预拆”。因此开发任务先作为 draft 暂存，进入 `SPRINTING` 后再逐个 promote 成正式 `TASK-*`。其它阶段默认根据上一阶段已经稳定的事实源即时创建当前阶段 task，只有当某个阶段也需要提前为后续阶段生成具体执行任务时，才应引入同类 draft queue。
+
 在尚未进入开发前，`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。
 
+### ADR 与 Memory 的边界
+
+`.docs/05_decisions/` 保存 ADR（Architecture Decision Record）。ADR 是软件工程中常见的架构决策记录实践，用来回答“为什么当时选择这个方案，而不是别的方案”。architecture / tech plan 可以写当前方案里的局部设计理由；如果一个决定有备选方案、影响多个模块或阶段、未来容易被质疑，或修改成本高，就应写成 ADR，记录背景、备选方案、理由、后果和替代关系。
+
+`<harnessRoot>/state/memory.md` 只做跨阶段快捷提示和导航，回答“下次进来要先记住什么、去哪里找”。memory 可以链接到 ADR、PRD、tech plan 或 implementation doc；完整背景、备选方案、取舍和长期后果放在 `.docs/05_decisions/` ADR 或其它正式 `.docs/**` 事实源里。
+
 ### Workflow skill 如何生效
 
 `<harnessRoot>/skills/<name>/SKILL.md` 是 Harness 的 workflow skill 事实源，也是稳定的 hard file index。它有两种使用方式：
@@ -156,7 +166,7 @@ Harness CLI v1 不承诺自动启动 Codex agent，也不要求 worker 之间通
 | `/prd` | 完善产品方案 | 在需求阶段创建或选择一个最小 `TASK-*` task；如果当前仍在架构阶段且未进入开发，可先回到 `REQUIREMENT_GATHERING` 修改 PRD |
 | `/design` | 设计技术方案 | 在架构阶段创建或选择一个最小 `TASK-*` task，生成或切分当前 architecture / tech plan / `plan.draft.yaml` 产物 |
 | `/dev` | 做下一个任务 | 创建或选择下一个最小 `TASK-*` development task，完成一个 task 闭环后停止 |
-| `/devloop` | 开始循环：写任务，执行任务 | 连续运行 `/dev`，直到没有明确任务或遇到 blocker |
+| `/devloop` | 开始循环：写任务，执行任务 | 连续运行 `/dev`，直到 `plan.yaml` 和 `plan.draft.yaml` 都没有明确任务或遇到 blocker |
 | `/test` | 跑一下当前验证 | 运行当前 task 或阶段对应 gate |
 | `/review` | 准备 review | 进入只读 Review workflow |
 
@@ -212,10 +222,12 @@ make docs-overview
 |---|---|
 | `<harnessRoot>/state/lifecycle.yaml` | 当前生命周期阶段和 active skill |
 | `<harnessRoot>/state/plan.yaml` | 当前和未来 task 的短期执行计划 |
+| `<harnessRoot>/state/memory.md` | 跨阶段稳定知识的摘要和正式事实源链接 |
 | `.docs/01_product/` | PRD、用户场景、验收标准 |
 | `.docs/02_architecture/` | 架构边界和高层设计 |
 | `.docs/03_tech_plan/` | 技术方案、接口契约、任务拆分 |
 | `.docs/04_implementation/` | 模块、子系统和核心数据流的真实实现事实 |
+| `.docs/05_decisions/` | ADR，长期关键决策及其背景、备选方案、理由和后果 |
 | `.docs/06_review/` | Review 报告 |
 | `.docs/07_test/` | 测试计划和回归记录 |
 | `.docs/08_release/` | 发布记录和回滚方案 |

package/assets/make/sdlc-harness.mk

@@ -12,7 +12,7 @@ help:
 	@echo "  make validate-plan       校验 plan.yaml task 合同，允许当前 open task"
 	@echo "  make validate-pm         校验产品需求产物"
 	@echo "  make validate-design     校验架构设计、技术方案和任务草案"
-	@echo "  make validate-dev        校验 sprint 任务状态、路径、代码 gate 和实现文档"
+	@echo "  make validate-dev        校验 sprint 任务状态、draft 消费、路径、代码 gate 和实现文档"
 	@echo "  make validate-review     校验 Review report"
 	@echo "  make validate-test       校验 regression/test plan"
 	@echo "  make validate-release    校验 release note、smoke result 和 rollback plan"
@@ -49,6 +49,7 @@ validate-design:
 
 validate-dev:
 	$(PYTHON) tools/validate_plan.py
+	$(PYTHON) tools/validate_dev_state.py
 	$(PYTHON) tools/validate_allowed_paths.py
 	$(MAKE) lint
 	$(MAKE) test-current-domain

package/assets/policies/allowed_paths.yaml

@@ -27,6 +27,7 @@ phases:
       - ".docs/04_implementation/**"
       - ".docs/INDEX.md"
       - "<harnessRoot>/state/plan.yaml"
+      - "<harnessRoot>/state/plan.draft.yaml"
 
   REVIEWING:
     read_only_source: true

package/assets/policies/gates.yaml

@@ -31,7 +31,7 @@ gates:
 
   validate-dev:
     command: "make validate-dev"
-    purpose: "验证任务状态、allowed_paths、代码检查、测试和实现文档"
+    purpose: "验证任务状态、已消费 draft、allowed_paths、代码检查、测试和实现文档"
     required_for:
       - "SPRINTING"
 

package/assets/policies/phase_contracts.yaml

@@ -45,11 +45,12 @@ phases:
       - "REQUIREMENT_GATHERING"
 
   SPRINTING:
-    goal: "按任务状态执行开发、测试和实现文档沉淀"
+    goal: "按任务状态执行开发、消费已采用草案、测试和实现文档沉淀"
     role: "developer"
     skill: "pjsdlc_dev_sprint"
     inputs:
       - "<harnessRoot>/state/plan.yaml"
+      - "<harnessRoot>/state/plan.draft.yaml"
       - "current open task plan contract"
       - ".docs/01_product/"
       - ".docs/03_tech_plan/"
@@ -57,6 +58,7 @@ phases:
       - "src/"
       - "tests/"
       - ".docs/04_implementation/"
+      - "<harnessRoot>/state/plan.draft.yaml"
     gates:
       - "make validate-dev"
     next: "REVIEWING"

package/assets/skills/pjsdlc_architect_design/SKILL.md

@@ -17,6 +17,8 @@ description: Use during ARCHITECTING to create architecture docs, technical plan
 
 架构产物应区分稳定边界和实现计划：architecture slice 记录领域边界、子系统、关键风险和长期约束；tech plan slice 记录接口契约、数据模型、模块方案、任务拆分和 gate。不要把重大架构变化藏在 task 描述里。
 
+ADR 用来解决“后来的人只看到结果，看不到当年取舍”的问题。architecture / tech plan 可以记录当前方案的局部设计理由；如果一个决定有明确备选方案、影响多个模块或阶段、未来容易被质疑、修改成本高，或需要保留 supersede 关系，就写入 `.docs/05_decisions/`。`<harnessRoot>/state/memory.md` 只保留这类决策的简短提示和链接，不承载完整背景、备选方案、取舍和后果。
+
 架构和技术方案产出本身也是 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。
@@ -45,6 +47,7 @@ description: Use during ARCHITECTING to create architecture docs, technical plan
 - `.docs/02_architecture/` 按领域边界、子系统、跨模块架构问题或关键技术风险切片。
 - `.docs/03_tech_plan/` 按可实现范围、接口契约、数据模型、模块方案或任务组切片。
 - `.docs/05_decisions/` 按单个架构决策切片，即一份 ADR 只记录一个 durable decision。
+- 写 ADR 的判断标准：存在备选方案、影响多个产物或阶段、未来容易被质疑、修改成本高、或需要说明 `Supersedes / Superseded by` 时，写 ADR；只影响当前模块内部实现细节、且理由已能在 architecture / tech plan 中局部说明时，不单独写 ADR。
 - 如果一个技术方案跨越多个独立模块，应拆成多个 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` 引用。

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` 创建或选择下一个最小 `TASK-*` development task，设置 `phase: "SPRINTING"`，并只完成一个 task 闭环后停止。`/devloop` 连续运行 `/dev`，直到技术方案中没有明确可创建/执行的任务，或遇到需求、架构、allowed_paths、gate、commit/push blocker。
+`/dev` 和 `/devloop` 是开发阶段的两个入口。`/dev` 创建或选择下一个最小 `TASK-*` development task，设置 `phase: "SPRINTING"`，并只完成一个 task 闭环后停止。通用规则是从任何 draft queue promote 正式 `TASK-*` 时都必须同次消费源 draft；当前开发阶段的内置 draft queue 是 `plan.draft.yaml.tasks[]`，因此如果这个 task 来自 `plan.draft.yaml.tasks[]`，promote 时必须同次删除源 draft，避免已采用草案继续显示为 `pending`。`/devloop` 连续运行 `/dev`，直到 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可创建/执行的任务，或遇到需求、架构、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。不要顺手重构、重排格式或处理无关问题；如果发现无关风险，只记录或报告。
 
@@ -25,6 +25,7 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 - `<harnessRoot>/state/lifecycle.yaml`
 - `<harnessRoot>/state/plan.yaml`
+- `<harnessRoot>/state/plan.draft.yaml`
 - 当前任务关联的 PRD 和技术方案
 - 当前源码和测试文件
 
@@ -35,6 +36,7 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 - `.docs/04_implementation/` 下相关模块、子系统或核心数据流的 implementation doc
 - 当前 task `working_notes` 或 implementation doc `Verification` 中的 gate evidence
 - 更新后的 `<harnessRoot>/state/plan.yaml`
+- 如果本轮 promote draft，更新后的 `<harnessRoot>/state/plan.draft.yaml`
 - 更新后的 `.docs/INDEX.md`
 - 当前 task 移除前创建的 task implementation commit
 - 从 `plan.yaml` 移除当前 task 后的 task completion ledger commit
@@ -51,8 +53,8 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 - 本 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` 创建一个最小 `TASK-*` open task；已有 open task 时，直接执行该 task；完成后停止。
-- `/devloop` 是连续执行入口：每完成一个 task 并 push 两段提交后，重新读取 lifecycle、plan、PRD、architecture 和 tech plan，再决定是否创建/执行下一个最小 task；没有明确任务或出现 blocker 时停止并报告。
+- `/dev` 是单任务执行入口：没有 open task 时，先根据 PRD、architecture、tech plan 和 `plan.draft.yaml` 创建一个最小 `TASK-*` open task；如果从 `plan.draft.yaml.tasks[]` 采用 draft，必须同次从 draft 列表删除源项；已有 open task 时，直接执行该 task；完成后停止。
+- `/devloop` 是连续执行入口：每完成一个 task 并 push 两段提交后，重新读取 lifecycle、`plan.yaml`、`plan.draft.yaml`、PRD、architecture 和 tech plan，再决定是否创建/执行下一个最小 task；没有 open task 且没有未采用 draft，或出现 blocker 时停止并报告。
 - Parallel Execution 是当前 task 的可选协作方式，不替代 task completion protocol；`SPRINTING` 并行从 lifecycle 的 `current_phase` 和 plan 的 `current_task_id` 推断上下文，不在 `parallel_execution` 内重复保存。
 
 ## Plan Protocol
@@ -61,10 +63,11 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 1. `current_task_id` 指向正在执行的 open task。
 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`。
-6. 将移除当前 task 后的 `plan.yaml` 提交为 task completion ledger commit，并 `git push` 两个 commit 到当前 upstream branch。
+3. 如果 open task 是由 `plan.draft.yaml.tasks[]` promote 而来，创建正式 `TASK-*` 和删除源 draft 必须发生在同一次状态更新中；正式 task 的恢复现场只保存在 `plan.yaml`。
+4. 任务执行中只保留恢复所需的简短 `working_notes`。
+5. gate、implementation doc、`.docs/INDEX.md` 和 `overview.md` 完成后，在当前 task 仍位于 `plan.yaml` 时创建 task implementation commit。
+6. implementation commit 完成后，再把该 task 从 `plan.yaml` 的 `tasks` 列表移除，并保留/递增 `next_task_sequence`。
+7. 将移除当前 task 后的 `plan.yaml` 提交为 task completion ledger commit，并 `git push` 两个 commit 到当前 upstream branch。
 
 done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认上下文。修 bug、补功能和继续开发时，优先读取当前代码、测试、PRD、技术方案和模块级 implementation doc；历史 task 查询主要看“做了什么、为什么做、影响哪个模块、验证了什么”，task id 和 commit 作为 implementation doc 的 provenance。`allowed_paths`、`required_gates`、临时 `working_notes` 是执行期约束，不作为历史查询 API。只有用户明确要求 forensic/audit/regression 追溯时，才临时使用 git、PR 或 CI 记录。
 
@@ -72,7 +75,7 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 
 1. 一次只执行一个任务。
 2. 开始修改前检查 `git status`；如果存在不属于当前 task 的未提交变更，先完成对应 task 的 commit/push，或报告 blocker，不要混入当前 task。
-3. 只编辑当前 task 的 `allowed_paths` 允许的文件，以及 `SPRINTING` 阶段允许的 Harness 记账文件。
+3. 只编辑当前 task 的 `allowed_paths` 允许的文件，以及 `SPRINTING` 阶段允许的 Harness 记账文件；如果本轮 promote draft，允许同步编辑 `<harnessRoot>/state/plan.draft.yaml` 来消费源 draft。
 4. 必须运行当前 task 的 `required_gates`。
 5. 如果 gate 因代码或测试逻辑失败，在任务范围内修复。
 6. 如果 gate 因基础设施、凭证缺失、产品行为不清或高风险架构变化失败，进入 `BLOCKED`。
@@ -83,7 +86,7 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 11. implementation commit 完成后，从当前 `plan.yaml` 移除该 task，并创建 task completion ledger commit。
 12. 默认不追溯已完成 task 的执行流水；只有显式 forensic/audit/regression 任务才临时查询 git、PR 或 CI 记录。
 13. 两个 commit 后必须 `git push` 到当前 upstream branch；如果没有 remote/upstream、权限或凭证导致无法 push，停止推进并报告 blocker。
-14. `/devloop` 每轮都必须重新读取当前状态，不得在一次上下文中假设 plan、代码或远端状态未变化。
+14. `/devloop` 每轮都必须重新读取当前状态，不得在一次上下文中假设 plan、draft、代码或远端状态未变化。
 15. 只有用户明确要求并行、多 agent 或多 worktree 时，才允许创建 `parallel_execution`；否则不得默认并行。
 16. `runtime_managed` 只在当前 runtime 支持 subagent 时使用；没有该能力时，输出 `user_orchestrated` worker prompt，由用户手动打开对话或 worktree 后粘贴。
 17. worker 不更新主事实源；主 Agent 才能更新 `plan.yaml`、`.docs/INDEX.md`、overview、implementation doc 和最终 gate 证据。
@@ -94,6 +97,7 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 - [ ] 当前 task `required_gates` 已通过，或 blocker 已记录。
 - [ ] open task 在 `plan.yaml` 中包含完整执行合同。
 - [ ] 当前任务仍然是单一清晰的执行单元。
+- [ ] 如果当前 task 来自 `plan.draft.yaml.tasks[]`，源 draft 已在 promote 时从 draft 列表删除。
 - [ ] implementation doc 已生成或更新，并反映相关模块的真实代码。
 - [ ] 如果启用了 `parallel_execution`，worker owned paths、forbidden paths、required gates 和主 Agent 集成结果已记录。
 - [ ] gate 结果已写入 implementation doc `Verification`，必要时当前 task `working_notes` 也记录了恢复现场所需的 gate evidence。

package/assets/skills/pjsdlc_manager/SKILL.md

@@ -47,8 +47,8 @@ Parallel Execution 是显式 opt-in：只有用户明确提出“并行”“多
 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；否则说明当前阶段冲突和推荐路径。
+17. 用户输入 `/dev`，或自然语言要求“开始开发”“做当前任务”“做下一个任务”“继续开发下一个任务”时，如果 `current_phase` 是 `SPRINTING`，创建或选择一个最小 `TASK-*` development task 并执行一个 task 闭环；如果 task 来自 `plan.draft.yaml.tasks[]`，promote 时必须同次删除源 draft；否则说明当前阶段冲突和推荐路径。
+18. 用户输入 `/devloop`，或自然语言要求“开始循环：写任务，执行任务”“把开发循环跑完”“连续开发”时，如果 `current_phase` 是 `SPRINTING`，连续运行 `/dev` 循环，直到 `plan.yaml.tasks[]` 和 `plan.draft.yaml.tasks[]` 都没有明确可做任务或遇到 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。
@@ -59,7 +59,7 @@ Parallel Execution 是显式 opt-in：只有用户明确提出“并行”“多
 
 ## Plan Protocol
 
-每个 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。
+每个 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` 指向模块级实现事实。任何阶段如果从 draft queue promote 正式 `TASK-*`，必须同次消费并删除源 draft；当前内置 draft queue 是 `plan.draft.yaml.tasks[]`，用于保存尚未采用的开发草案。done/cancelled task 不长期留在当前 `plan.yaml`。完成后的产物事实以对应 `.docs/**` slice 或模块级 implementation doc 为准，动作历史以 git/PR/CI/release 系统作为 cold archive，`next_task_sequence` 负责继续分配后续 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 残留。
 

package/assets/templates/ADR_TEMPLATE.md

@@ -2,18 +2,44 @@
 
 ## Status（状态）
 
-Proposed
+Proposed / Accepted / Superseded
 
 ## Context（背景）
 
-- 
+- 这个决策要解决什么问题？
+- 哪些需求、架构边界、技术方案或约束让这个决策必须长期保留？
+
+## Options（备选方案）
+
+- Option A:
+  - 优点:
+  - 代价/风险:
+- Option B:
+  - 优点:
+  - 代价/风险:
 
 ## Decision（决策）
 
 - 
 
+## Rationale（理由）
+
+- 为什么选择这个方案，而不是其它备选方案？
+- 这个选择依赖哪些前提？哪些变化会触发重新评估？
+
 ## Consequences（影响）
 
 - 正向影响（Positive）:
 - 负向影响（Negative）:
 - 后续动作（Follow-up）:
+
+## Supersedes / Superseded By（替代关系）
+
+- Supersedes:
+- Superseded by:
+
+## Links（链接）
+
+- Related PRD:
+- Related architecture / tech plan:
+- Related implementation:

package/dist/lib/init.js

@@ -55,7 +55,10 @@ async function createProjectState(projectRoot, root, report) {
         ],
         [harnessPath(root, "state", "plan.yaml"), `current_task_id: ""\nnext_task_sequence: 1\ntasks: []\n`],
         [harnessPath(root, "state", "plan.draft.yaml"), `next_task_sequence: 1\ntasks: []\n`],
-        [harnessPath(root, "state", "memory.md"), "# Project Memory\n\n短期执行计划写入 plan.yaml；长期稳定知识简短记录在这里，并链接到 `.docs/` 正式出处。\n"]
+        [
+            harnessPath(root, "state", "memory.md"),
+            "# Project Memory\n\n短期执行计划写入 plan.yaml；长期稳定知识只在这里记录简短摘要和链接。完整决策背景、备选方案、取舍和后果写入 `.docs/05_decisions/` ADR 或其它 `.docs/**` 正式事实源。\n"
+        ]
     ];
     for (const [relative, content] of files) {
         if (await writeTextIfChanged(path.join(projectRoot, relative), content)) {

package/dist/lib/migrations.js

@@ -356,7 +356,7 @@ async function ensureMemory(projectRoot, root, report) {
         report.skipped.push(relativeMemoryPath);
         return;
     }
-    const content = "# Project Memory\n\n记录跨阶段长期有效的稳定知识，并链接到 `.docs/` 正式出处。\n";
+    const content = "# Project Memory\n\n记录跨阶段长期有效知识的简短摘要和链接。完整决策背景、备选方案、取舍和后果写入 `.docs/05_decisions/` ADR 或其它 `.docs/**` 正式事实源。\n";
     if (await writeTextIfChanged(memoryPath, content)) {
         report.changed.push(relativeMemoryPath);
     }

package/dist/lib/validators.js

@@ -262,8 +262,26 @@ async function validateCrossCuttingArchitecture(projectRoot, productFiles, techP
     return errors;
 }
 async function validateDev(projectRoot) {
+    const root = await harnessRoot(projectRoot);
     const plan = await validatePlanState(projectRoot, false);
-    return { info: [`validate-dev checked ${plan.taskCount} task(s)`], errors: plan.errors };
+    const draftErrors = await validateDevDraftConsumed(projectRoot, root);
+    return { info: [`validate-dev checked ${plan.taskCount} task(s)`], errors: [...plan.errors, ...draftErrors] };
+}
+async function validateDevDraftConsumed(projectRoot, root) {
+    const errors = [];
+    const draft = await readYamlObject(path.join(projectRoot, root, "state", "plan.draft.yaml"));
+    if ("current_phase" in draft) {
+        errors.push("plan.draft.yaml must not define current_phase; lifecycle.yaml is the single source for current_phase");
+    }
+    if ("current_task_id" in draft) {
+        errors.push("plan.draft.yaml must not define current_task_id because drafts are not active task state");
+    }
+    const tasks = Array.isArray(draft.tasks) ? draft.tasks : [];
+    if (tasks.length > 0) {
+        const ids = tasks.map((task) => (isRecord(task) ? String(task.id ?? "<missing id>") : "<missing id>")).join(", ");
+        errors.push(`Unconsumed draft tasks remain in plan.draft.yaml: ${ids}. Promote the next draft into plan.yaml or remove already-consumed drafts before validate-dev.`);
+    }
+    return errors;
 }
 async function validateReview(projectRoot) {
     const plan = await validatePlanState(projectRoot, false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-project-sdlc",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "CLI and canonical assets for the AI SDLC Harness workflow.",
   "type": "module",
   "bin": {