agent-project-sdlc 0.1.9 → 0.1.11

package/assets/skills/pjsdlc_release_manager/SKILL.md

@@ -17,8 +17,11 @@ description: Use during RELEASING to prepare release notes, smoke evidence, depl
 
 Release note 面向人类读者，必须说明变更价值、影响范围和注意事项；rollback plan 面向执行者，必须具体到触发条件、操作入口、验证方式和负责人。
 
+发布准备本身也是 workflow task。开始 release 工作前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "RELEASING"`；当前轮只产出一个 release slice、一次 smoke evidence 补充、一个部署检查或一个 rollback plan 单元。发布动作本身仍需用户明确授权。
+
 ## 输入
 
+- `<harnessRoot>/state/plan.yaml`
 - `.docs/07_test/`
 - build artifacts
 - changelog 或 task list
@@ -27,6 +30,7 @@ Release note 面向人类读者，必须说明变更价值、影响范围和注
 ## 输出
 
 - `.docs/08_release/` 下的 release note
+- 更新后的 `<harnessRoot>/state/plan.yaml`
 - smoke test result
 - deployment checklist
 - rollback plan
@@ -40,6 +44,17 @@ Release note 面向人类读者，必须说明变更价值、影响范围和注
 - 如果只是补充同一版本的 smoke evidence 或 rollback step，应更新原 release slice。
 - 发布 slice 完成后更新 `.docs/INDEX.md`；不再维护 Harness archive。
 
+## Plan Protocol
+
+发布阶段受 `plan.yaml` 管控：
+
+1. 没有 open task 时，先创建一个最小 `TASK-*` task，设置 `phase: "RELEASING"` 和 `current_task_id`。
+2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 `.docs/08_release/**` 文件。
+3. 单个 task 的目标应足够小：一个版本 release note、一个 smoke evidence 补充、一个 deployment checklist 或一个 rollback plan。
+4. 执行当前 task 时只编辑 `allowed_paths` 中的 release 产物、`.docs/INDEX.md`、overview 和 `plan.yaml`。
+5. 完成后运行 `make validate-plan` 和 task required gates；阶段出口前运行 `make validate-release`。
+6. task 完成后从 `plan.yaml.tasks` 移除；如果还有 pending release task，下一轮 `/release` 或 `/next` 再继续。
+
 ## 规则
 
 1. 除非用户明确要求，不自动部署。
@@ -47,10 +62,13 @@ Release note 面向人类读者，必须说明变更价值、影响范围和注
 3. Rollback plan 必须可执行。
 4. Smoke test evidence 必须链接或摘要记录。
 5. Human confirmation items 必须明确。
+6. 发布阶段一次只执行一个 `TASK-*` task。
 
 ## 完成检查
 
 - [ ] Release note 已生成。
+- [ ] 当前发布工作已绑定 `plan.yaml` 中一个最小 `TASK-*` task，并设置 `phase: "RELEASING"`。
+- [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] Build artifacts 已记录。
 - [ ] Smoke test result 已记录。
 - [ ] 已判断 release slice 的版本或发布批次边界。

package/assets/skills/pjsdlc_reviewer/SKILL.md

@@ -17,8 +17,11 @@ Review 时先建立证据链：PRD 说什么、技术方案承诺什么、implem
 
 不要把个人偏好包装成 blocker。区分 blocking issue、follow-up improvement 和 open question。如果没有发现问题，要明确说明，同时列出剩余测试缺口或残余风险。
 
+Review 产出本身也是 workflow task。开始 review 前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "REVIEWING"`；当前轮只产出一个 review batch、一个风险主题 slice 或一次 PR review 结论。不要在一个任务里覆盖多个互不相关的 review 主题。
+
 ## 输入
 
+- `<harnessRoot>/state/plan.yaml`
 - `.docs/01_product/`
 - `.docs/03_tech_plan/`
 - `.docs/04_implementation/`
@@ -29,6 +32,7 @@ Review 时先建立证据链：PRD 说什么、技术方案承诺什么、implem
 ## 输出
 
 - `.docs/06_review/REVIEW_REPORT.md`
+- 更新后的 `<harnessRoot>/state/plan.yaml`
 - 风险清单
 - 重构建议
 - 是否允许进入 `TESTING` 的结论
@@ -41,6 +45,17 @@ Review 时先建立证据链：PRD 说什么、技术方案承诺什么、implem
 - Review 不重切上游 PRD / tech plan；如果发现上游边界错误，记录 blocker 或建议 RFC。
 - 每次新增或拆分 review slice 后，都要更新 `.docs/INDEX.md`。
 
+## Plan Protocol
+
+Review 阶段受 `plan.yaml` 管控：
+
+1. 没有 open task 时，先创建一个最小 `TASK-*` task，设置 `phase: "REVIEWING"` 和 `current_task_id`。
+2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 `.docs/06_review/**` 文件。
+3. 单个 task 的目标应足够小：一次 review batch、一个 PR、一个模块或一个风险主题。
+4. 执行当前 task 时只写 review 产物、`.docs/INDEX.md`、`overview.md` 和 `plan.yaml`，不修改源码。
+5. 完成后运行 `make validate-plan` 和 `make docs-overview`；阶段出口前运行 `make validate-review`。
+6. task 完成后从 `plan.yaml.tasks` 移除；如果还有 pending review task，下一轮 `/review` 或 `/next` 再继续。
+
 ## 规则
 
 1. 本 Skill 不修改源码。
@@ -48,10 +63,13 @@ Review 时先建立证据链：PRD 说什么、技术方案承诺什么、implem
 3. 每条 finding 尽量引用文件、需求、任务或文档路径。
 4. 区分 blocking issues 和 follow-up improvements。
 5. 如果未发现问题，明确说明，并列出剩余测试缺口或残余风险。
+6. Review 阶段一次只执行一个 `TASK-*` task。
 
 ## 完成检查
 
 - [ ] Review report 已生成。
+- [ ] 当前 review 工作已绑定 `plan.yaml` 中一个最小 `TASK-*` task，并设置 `phase: "REVIEWING"`。
+- [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] 已评估需求一致性。
 - [ ] 已评估架构和可维护性风险。
 - [ ] 已判断 review slice 的范围和风险主题边界。

package/assets/skills/pjsdlc_rfc_recalibrate/SKILL.md

@@ -19,6 +19,8 @@ description: Use during RFC_RECALIBRATION to process requirement changes with im
 
 影响面分析必须先于补丁。至少检查 docs/state/skills/policies/templates/tools/package assets/tests/migrations/generated artifacts 是否受影响；如果某一类不受影响，也要显式说明不受影响或不需要修改。对于 Harness package 相关变更，还要检查 `sync`、`upgrade`、source mappings、package assets 和用户项目迁移行为。
 
+RFC recalibration 本身也是 workflow task。开始处理变更前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "RFC_RECALIBRATION"`；当前轮只处理一个 RFC 文件、一个 impact analysis 单元或一个局部补丁单元。
+
 ## 输入
 
 - `.docs/rfc/RFC_*.md`
@@ -33,6 +35,7 @@ description: Use during RFC_RECALIBRATION to process requirement changes with im
 - 局部更新后的 PRD 和技术方案
 - 被标记为 `pending_revision` 的受影响任务，或新增增量任务
 - Regression requirements
+- 更新后的 `<harnessRoot>/state/plan.yaml`
 - 更新后的 `.docs/INDEX.md`
 
 ## 语义切片
@@ -43,6 +46,17 @@ description: Use during RFC_RECALIBRATION to process requirement changes with im
 - 对受影响产物做局部补丁，不重写无关稳定 slice。
 - 每次 RFC 影响了文档边界，都要更新 `.docs/INDEX.md` 并记录受影响任务状态。
 
+## Plan Protocol
+
+RFC 阶段受 `plan.yaml` 管控：
+
+1. 没有 open task 时，先创建一个最小 `TASK-*` task，设置 `phase: "RFC_RECALIBRATION"` 和 `current_task_id`。
+2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 RFC、受影响 PRD/tech plan/test docs 或 plan update。
+3. 单个 task 的目标应足够小：一份 RFC 的 impact analysis、一个受影响 slice 的局部补丁、一组任务状态调整，或一个回归要求更新。
+4. 执行当前 task 时只编辑 `allowed_paths` 中的 RFC、受影响 facts、`.docs/INDEX.md`、overview 和 `plan.yaml`。
+5. 完成后运行 `make validate-plan` 和 task required gates；阶段出口前运行 `make validate-rfc`。
+6. task 完成后从 `plan.yaml.tasks` 移除；如果还有 pending RFC task，下一轮 `/rfc` 或 `/next` 再继续。
+
 ## 规则
 
 1. 影响已接受产物的需求变化，必须先进入本 Skill。
@@ -51,10 +65,13 @@ description: Use during RFC_RECALIBRATION to process requirement changes with im
 4. 受影响的 `pending` 或 `in_progress` 任务追加 revision notes。
 5. 不重写无关的稳定文档。
 6. 只有 `make validate-rfc` 通过后，才能恢复原阶段或进入 `SPRINTING`。
+7. RFC 阶段一次只执行一个 `TASK-*` task。
 
 ## 完成检查
 
 - [ ] RFC 包含有效 status 和 acceptance criteria。
+- [ ] 当前 RFC 工作已绑定 `plan.yaml` 中一个最小 `TASK-*` task，并设置 `phase: "RFC_RECALIBRATION"`。
+- [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] Product impact 和 technical impact 已记录。
 - [ ] 已判断 RFC 是否需要拆分，以及是否影响其它阶段 slice。
 - [ ] 已列出 docs/state/skills/policies/templates/tools/package assets/tests/migrations/generated artifacts 的影响面。

package/assets/skills/pjsdlc_tester/SKILL.md

@@ -17,10 +17,13 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 
 执行回归时，优先选择能证明阶段出口的 gate。测试无法运行、环境缺失或数据不可得时，不要宣布通过，应记录 blocker、已完成检查和恢复条件。
 
+测试计划和回归证据产出本身也是 workflow task。开始测试前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "TESTING"`；当前轮只产出一个测试矩阵 slice、一个回归批次、一个风险验证片区或一组 scoped test changes。
+
 如果用户明确要求并行、多 agent 或多 worktree，测试阶段可以启用 `parallel_execution`，让 worker 分别执行互不依赖的回归片区、smoke、兼容性或风险验证。worker 只提交证据和必要的 scoped test changes；最终 `.docs/07_test/**`、coverage gaps、PASS/BLOCKED 决策和阶段 gate 由主 Agent 汇总。没有用户显式要求时，测试 workflow 保持串行。
 
 ## 输入
 
+- `<harnessRoot>/state/plan.yaml`
 - `.docs/01_product/`
 - `.docs/03_tech_plan/`
 - `.docs/04_implementation/`
@@ -32,6 +35,7 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 
 - `.docs/07_test/TEST_PLAN.md`
 - 必要时在 `tests/` 下补充测试
+- 更新后的 `<harnessRoot>/state/plan.yaml`
 - 回归测试记录
 - 覆盖缺口清单
 
@@ -43,6 +47,17 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 - 如果新增测试只是覆盖同一验收标准，应更新原 test slice，不要创建重复测试计划。
 - 每次新增、拆分或合并 test slice 后，都要更新 `.docs/INDEX.md`。
 
+## Plan Protocol
+
+测试阶段受 `plan.yaml` 管控：
+
+1. 没有 open task 时，先创建一个最小 `TASK-*` task，设置 `phase: "TESTING"` 和 `current_task_id`。
+2. open task 必须包含 `phase`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `result_docs`；`result_docs` 指向本 task 计划产出的 `.docs/07_test/**` 文件，必要时也列出 scoped test files。
+3. 单个 task 的目标应足够小：一个测试矩阵 slice、一个回归批次、一个风险验证片区，或一组紧密相关的测试变更。
+4. 执行当前 task 时只编辑 `allowed_paths` 中的测试、测试文档、`.docs/INDEX.md`、overview 和 `plan.yaml`。
+5. 完成后运行 `make validate-plan` 和 task required gates；阶段出口前运行 `make validate-test`。
+6. task 完成后从 `plan.yaml.tasks` 移除；如果还有 pending testing task，下一轮 `/test` 或 `/next` 再继续。
+
 ## 规则
 
 1. 测试用例必须追溯到 PRD acceptance criteria 或 Review findings。
@@ -50,10 +65,13 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 3. 如果有意延后覆盖，必须记录风险和 follow-up。
 4. 并行测试必须使用 `parallel_execution.trigger: "user_requested"`；`runtime_managed` 只在当前 runtime 支持 subagent 时使用，否则输出 `user_orchestrated` worker prompt。
 5. 宣布阶段完成前运行 `make test-all`。
+6. 测试阶段一次只执行一个 `TASK-*` task。
 
 ## 完成检查
 
 - [ ] Test matrix 已把需求映射到测试。
+- [ ] 当前测试工作已绑定 `plan.yaml` 中一个最小 `TASK-*` task，并设置 `phase: "TESTING"`。
+- [ ] 当前 task 已从 `plan.yaml` 移除，或因中断/blocker 保留为可恢复 open task。
 - [ ] Regression checklist 已完成。
 - [ ] 已判断 test plan / test matrix 的语义切片边界。
 - [ ] Coverage gaps 已明确。

package/assets/templates/PLAN_TEMPLATE.yaml

@@ -1,5 +1,4 @@
-current_phase: "SPRINTING"
-current_task_id: "DEV-001"
+current_task_id: "TASK-001"
 next_task_sequence: 2
 # Optional. Omit this block for normal serial workflow. Only add it when the
 # user explicitly asks for parallel / multi-agent / multi-worktree execution.
@@ -7,9 +6,7 @@ next_task_sequence: 2
 #   enabled: true
 #   trigger: "user_requested"
 #   mode: "user_orchestrated" # or "runtime_managed" when the current agent runtime can spawn subagents
-#   phase: "SPRINTING"
 #   coordinator: "main_agent"
-#   linked_task_id: "DEV-001"
 #   workers:
 #     - id: "worker-feature"
 #       writes_repo: true
@@ -33,24 +30,30 @@ next_task_sequence: 2
 #     fact_source_updates:
 #       - ".docs/04_implementation/"
 tasks:
-  - id: "DEV-001"
-    title: "实现示例任务"
+  - id: "TASK-001"
+    phase: "REQUIREMENT_GATHERING"
+    title: "生成示例 PRD slice"
     status: "pending"
     summary: "一句话描述任务目标和交付边界。"
     docs:
+      raw:
+        - ".docs/00_raw/example.md"
       product:
         - ".docs/01_product/example.md"
-      tech_plan:
-        - ".docs/03_tech_plan/example.md"
+      architecture: []
+      tech_plan: []
       rfc: []
     allowed_paths:
-      - "src/**"
-      - "tests/**"
+      - ".docs/00_raw/**"
+      - ".docs/01_product/**"
+      - ".docs/INDEX.md"
+      - "<harnessRoot>/state/plan.yaml"
     required_gates:
-      - "make lint"
-      - "make test-current-domain"
+      - "make validate-plan"
+      - "make docs-overview"
     acceptance_criteria:
       - "验收标准写在 open task 内，完成后从当前 plan 删除。"
     working_notes:
       - "执行现场备注只在 open task 保留。"
-    implementation_doc: ".docs/04_implementation/example/module_or_flow.md"
+    result_docs:
+      - ".docs/01_product/example.md"

package/assets/templates/TECH_DESIGN_TEMPLATE.md

@@ -41,7 +41,7 @@ Input
 
 | Task ID | 标题（Title） | Allowed Paths | Required Gates | Implementation Doc |
 |---|---|---|---|---|
-| DEV-001 |  | `src/**`, `tests/**` | `make lint`, `make test-current-domain` | `.docs/04_implementation/...` |
+| TASK-001 |  | `src/**`, `tests/**` | `make lint`, `make test-current-domain` | `.docs/04_implementation/...` |
 
 `Implementation Doc` 应指向模块、子系统或核心数据流级文档；多个 task 可以更新同一份文档，task id 和 commit 记录在该文档的 provenance / Change Log 中。
 

package/dist/commands/index.js

@@ -13,9 +13,14 @@ export const commands = {
     validate,
     "validate-harness": (args) => validate(["validate-harness", ...args]),
     "validate-current": (args) => validate(["validate-current", ...args]),
+    "validate-plan": (args) => validate(["validate-plan", ...args]),
     "validate-pm": (args) => validate(["validate-pm", ...args]),
     "validate-design": (args) => validate(["validate-design", ...args]),
     "validate-dev": (args) => validate(["validate-dev", ...args]),
+    "validate-review": (args) => validate(["validate-review", ...args]),
+    "validate-test": (args) => validate(["validate-test", ...args]),
+    "validate-release": (args) => validate(["validate-release", ...args]),
+    "validate-rfc": (args) => validate(["validate-rfc", ...args]),
     package: packageSource
 };
 export function help() {
@@ -26,5 +31,6 @@ export function help() {
   upgrade              Run migrations and then sync
   doctor               Diagnose project configuration and drift
   validate <gate>      Run a Harness validation gate
+  validate-*           Run a named gate directly, including validate-plan/review/test/release/rfc
   package <subcommand> Maintain package canonical source`);
 }

package/dist/lib/init.js

@@ -53,8 +53,8 @@ async function createProjectState(projectRoot, root, report) {
             harnessPath(root, "state", "lifecycle.yaml"),
             `project_name: "Project"\nversion: "v0.1"\ncurrent_phase: "SPRINTING"\nactive_role: "developer"\nactive_skill: "pjsdlc_dev_sprint"\ncurrent_milestone: "MVP"\nblocked_reason: ""\nsuspended_phase: ""\nallowed_next_phases:\n  - "REVIEWING"\n`
         ],
-        [harnessPath(root, "state", "plan.yaml"), `current_phase: "SPRINTING"\ncurrent_task_id: ""\nnext_task_sequence: 1\ntasks: []\n`],
-        [harnessPath(root, "state", "plan.draft.yaml"), `current_phase: "SPRINTING"\ncurrent_task_id: ""\nnext_task_sequence: 1\ntasks: []\n`],
+        [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"]
     ];
     for (const [relative, content] of files) {

package/dist/lib/migrations.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { readdir, rename, rm } from "node:fs/promises";
-import { readConfig } from "./config.js";
+import { defaultConfig, readConfig } from "./config.js";
 import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
 import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
 import { parseYaml, stringifyYaml } from "./yaml.js";
@@ -23,8 +23,8 @@ export async function runMigrations(projectRoot) {
     await migrateConfig(projectRoot, root, report);
     await migrateLegacyManagedPaths(projectRoot, root, report);
     await migrateLifecycle(projectRoot, root, report);
-    await migratePlan(projectRoot, root, report, "plan.yaml", "tasks.yaml");
-    await migratePlan(projectRoot, root, report, "plan.draft.yaml", "tasks.draft.yaml");
+    await migratePlan(projectRoot, root, report, "plan.yaml", "tasks.yaml", { activePlan: true });
+    await migratePlan(projectRoot, root, report, "plan.draft.yaml", "tasks.draft.yaml", { activePlan: false });
     await removeLegacyGateResults(projectRoot, root, report);
     await removeLegacyCheckpoints(projectRoot, root, report);
     await ensureMemory(projectRoot, root, report);
@@ -38,6 +38,9 @@ async function migrateConfig(projectRoot, root, report) {
         return;
     }
     const config = await readConfig(projectRoot);
+    const currentCore = defaultConfig(root).core;
+    config.core.package = currentCore.package;
+    config.core.version = currentCore.version;
     config.core.schema_version = CURRENT_SCHEMA_VERSION;
     config.managed_files = migrateManagedFiles(config.managed_files, root);
     config.local_overrides = config.local_overrides.map((item) => migrateLocalOverride(item, root));
@@ -197,7 +200,7 @@ async function migrateLifecycle(projectRoot, root, report) {
         report.skipped.push(relativeLifecyclePath);
     }
 }
-async function migratePlan(projectRoot, root, report, planFileName, legacyFileName) {
+async function migratePlan(projectRoot, root, report, planFileName, legacyFileName, options) {
     const relativePlanPath = harnessPath(root, "state", planFileName);
     const planPath = path.join(projectRoot, relativePlanPath);
     const legacyTasksPath = path.join(projectRoot, harnessPath(root, "state", legacyFileName));
@@ -208,18 +211,32 @@ async function migratePlan(projectRoot, root, report, planFileName, legacyFileNa
     }
     const data = (parseYaml(await readText(sourcePath)) ?? {});
     let changed = false;
-    if (!("current_phase" in data)) {
-        data.current_phase = "SPRINTING";
+    if ("current_phase" in data) {
+        delete data.current_phase;
         changed = true;
     }
-    if (!("current_task_id" in data)) {
+    if (options.activePlan && !("current_task_id" in data)) {
         data.current_task_id = "";
         changed = true;
     }
+    if (!options.activePlan && "current_task_id" in data) {
+        delete data.current_task_id;
+        changed = true;
+    }
     if (!Array.isArray(data.tasks)) {
         data.tasks = [];
         changed = true;
     }
+    if (isRecord(data.parallel_execution)) {
+        if ("phase" in data.parallel_execution) {
+            delete data.parallel_execution.phase;
+            changed = true;
+        }
+        if ("linked_task_id" in data.parallel_execution) {
+            delete data.parallel_execution.linked_task_id;
+            changed = true;
+        }
+    }
     if (Array.isArray(data.tasks)) {
         const retainedTasks = [];
         let maxTaskSequence = 0;
@@ -266,10 +283,12 @@ async function migratePlan(projectRoot, root, report, planFileName, legacyFileNa
             changed = true;
         }
     }
-    const currentTaskId = String(data.current_task_id ?? "");
-    if (currentTaskId && !taskById(data, currentTaskId)) {
-        data.current_task_id = "";
-        changed = true;
+    if (options.activePlan) {
+        const currentTaskId = String(data.current_task_id ?? "");
+        if (currentTaskId && !taskById(data, currentTaskId)) {
+            data.current_task_id = "";
+            changed = true;
+        }
     }
     if (changed || sourcePath !== planPath) {
         if (await writeTextIfChanged(planPath, stringifyYaml(data))) {