agent-project-sdlc 0.1.1 → 0.1.3

package/assets/agents/AGENTS_CORE.md

@@ -31,12 +31,12 @@
 
 - `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 摘要。
+- task 完成并写入或更新相关 implementation doc 后，从 `plan.yaml` 的 `tasks` 列表移除该 task；不要长期保留 done/cancelled task 摘要。
 - `plan.draft.yaml` 是架构阶段生成的计划草案，不自动覆盖 `plan.yaml`。
 - 不维护 checkpoint 文件；任务现场只存在于 open task 的 plan 条目里。
-- 历史动作记录以 git commit 为准，产物结果以 implementation doc 为准。
+- 历史动作记录以 git commit 为准，产物结果以模块、子系统或核心数据流级 implementation doc 为准。
 - `SPRINTING` 阶段每完成一个 task，先在 task 仍位于 `plan.yaml` 时创建 task implementation commit；随后再从 `plan.yaml` 移除该 task 并创建 task completion ledger commit。两段提交 push 成功前不进入下一个 task。
-- 历史 task 查询默认面向产物结果和变更意图，读取 implementation doc、RFC、PRD、tech plan 和代码；`allowed_paths`、`required_gates`、临时 `working_notes` 是执行期约束，不作为历史查询 API。
+- 历史 task 查询默认面向产物结果和变更意图，读取模块级 implementation doc、RFC、PRD、tech plan 和代码；task id 和 commit 只作为 provenance，`allowed_paths`、`required_gates`、临时 `working_notes` 是执行期约束，不作为历史查询 API。
 - 过去 phase/task/gate 执行流水不是默认上下文；除非用户明确要求 forensic/audit/regression 追溯，否则不要读取或恢复历史执行信息。
 
 ## Prompt Language Contract
@@ -135,15 +135,15 @@ Strong success criteria 可以让你 independent loop。Weak criteria，例如
 4. 在 `SPRINTING` 阶段，一次只执行一个任务。
 5. 在 `SPRINTING` 阶段，只编辑当前 open task 的 `allowed_paths` 允许的文件。
 6. 不要在当前 open task 的 `required_gates` 通过前把任务标记为 `done`。
-7. 代码 gate 通过后，更新任务实现文档和 `.docs/INDEX.md`。
+7. 代码 gate 通过后，更新相关 implementation doc 和 `.docs/INDEX.md`。
 8. `reviewer` 角色只读，不直接修改源码。
 9. 需求变更必须进入 RFC 工作流。
 10. task/release 历史动作记录使用 git commit、tag 或外部 release 系统，不维护 `.agent/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` 中包含完整执行合同，再继续推进或交接。
-14. 默认不读取过去 task 或 phase 执行流水；修 bug、补功能和阶段交付以当前代码、测试、PRD、技术方案和 implementation doc 为准。
-15. gate 证据写入当前 task `working_notes` 或 implementation doc 的 `Verification`；不要维护独立 gate results state。
+14. 默认不读取过去 task 或 phase 执行流水；修 bug、补功能和阶段交付以当前代码、测试、PRD、技术方案和模块级 implementation doc 为准。
+15. gate 证据写入当前 task `working_notes` 或相关 implementation doc 的 `Verification`；不要维护独立 gate results state。
 16. 如果信息缺失，或 gate 因基础设施原因失败，停止推进并报告 blocker。
 
 ## 宏指令

package/assets/skills/pjsdlc_architect_design/SKILL.md

@@ -49,7 +49,7 @@ description: Use during ARCHITECTING to create architecture docs, technical plan
 2. 每个 open task 必须包含 `id`、`title`、`status`、`summary`、`docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和 `implementation_doc`。
 3. `plan.draft.yaml` 不得自动覆盖 `plan.yaml`。
 4. 风险或不清晰的问题按 `<harnessRoot>/pjsdlc_managed/policies/risk_matrix.yaml` 标记。
-5. 任务边界应足够小，能在一次开发执行和一份 implementation doc 内闭环。
+5. 任务边界应足够小，能在一次开发执行内闭环；`implementation_doc` 应指向将被更新或新增的模块、子系统或核心数据流文档。
 
 ## 完成检查
 

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、给出可能解释和推荐下一步，而不是扩大范围继续写。
 
-实现时遵循小步闭环：先检查 `git status`，确认工作区没有未归属到当前 task 的脏变更；再定位相关代码和测试，做必要修改，运行 gate，修复失败，写 implementation doc 并刷新文档派生视图。此时先不要从 `plan.yaml` 移除当前 task，要在当前 task 仍位于 `plan.yaml` 时创建 task implementation commit；随后再移除 task，创建 task completion ledger commit，并 push 两个 commit。不要顺手重构、重排格式或处理无关问题；如果发现无关风险，只记录或报告。
+实现时遵循小步闭环：先检查 `git status`，确认工作区没有未归属到当前 task 的脏变更；再定位相关代码和测试，做必要修改，运行 gate，修复失败，写入或更新相关 implementation doc 并刷新文档派生视图。此时先不要从 `plan.yaml` 移除当前 task，要在当前 task 仍位于 `plan.yaml` 时创建 task implementation commit；随后再移除 task，创建 task completion ledger commit，并 push 两个 commit。不要顺手重构、重排格式或处理无关问题；如果发现无关风险，只记录或报告。
 
 ## 输入
 
@@ -28,7 +28,7 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 
 - 当前 task `allowed_paths` 范围内的源码改动
 - 当前 task `allowed_paths` 范围内的测试改动
-- `.docs/04_implementation/` 下的 implementation doc
+- `.docs/04_implementation/` 下相关模块、子系统或核心数据流的 implementation doc
 - 当前 task `working_notes` 或 implementation doc `Verification` 中的 gate evidence
 - 更新后的 `<harnessRoot>/state/plan.yaml`
 - 更新后的 `.docs/INDEX.md`
@@ -39,13 +39,13 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 ## 语义切片
 
 - `SPRINTING` 阶段的执行单元是 `current_task_id`，不要在开发中重新生成整个 Sprint 计划。
-- 当前任务就是开发阶段的主要语义切片，代码、测试、gate 记录和 implementation doc 都围绕该任务闭环。
+- 当前 task 是开发阶段的执行单元、修改边界和提交边界；implementation doc 的长期语义切片是模块、子系统或核心数据流。
 - open task 在 `plan.yaml` 中直接保存 `docs`、`allowed_paths`、`required_gates`、`acceptance_criteria` 和必要的 `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。
 - 本 Skill 不直接重切 PRD 或 tech plan；如果发现上游语义边界错误，进入 `BLOCKED`、创建 RFC，或请求回到 `ARCHITECTING`。
-- gate 通过后调用 `implementation_doc`，由该 Skill 按真实实现生成 `.docs/04_implementation/` slice。
+- gate 通过后调用 `implementation_doc`，由该 Skill 按真实实现更新或新增 `.docs/04_implementation/` 模块级 slice。
 - 如果一个任务实际变成多个独立实现边界，应停止扩大范围，拆分后续任务或回到任务规划。
 
 ## Plan Protocol
@@ -59,7 +59,7 @@ description: Use during SPRINTING to execute one task from plan.yaml, respecting
 5. implementation commit 完成后，再把该 task 从 `plan.yaml` 的 `tasks` 列表移除，并保留/递增 `next_task_sequence`。
 6. 将移除当前 task 后的 `plan.yaml` 提交为 task completion ledger commit，并 `git push` 两个 commit 到当前 upstream branch。
 
-done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认上下文。修 bug、补功能和继续开发时，优先读取当前代码、测试、PRD、技术方案和 implementation doc；历史 task 查询主要看“做了什么、为什么做、产物在哪里、验证了什么”。`allowed_paths`、`required_gates`、临时 `working_notes` 是执行期约束，不作为历史查询 API。只有用户明确要求 forensic/audit/regression 追溯时，才临时使用 git、PR 或 CI 记录。
+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 记录。
 
 ## 规则
 
@@ -71,8 +71,8 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 6. 如果 gate 因基础设施、凭证缺失、产品行为不清或高风险架构变化失败，进入 `BLOCKED`。
 7. gate 通过后调用 `implementation_doc`。
 8. 只有 gate 通过且 implementation doc 校验通过后，才能把任务标记为 `done`。
-9. 任务完成并写入 implementation doc、刷新 `overview.md`、记录 gate 后，先创建 task implementation commit；此时不要移除该 task。
-10. task implementation commit 必须发生在 task 移除前；后续默认不要读取其中的执行期字段，历史查询以 implementation doc、RFC、PRD、tech plan 和代码为主。
+9. 任务完成并写入或更新相关 implementation doc、刷新 `overview.md`、记录 gate 后，先创建 task implementation commit；此时不要移除该 task。
+10. task implementation commit 必须发生在 task 移除前；后续默认不要读取其中的执行期字段，历史查询以模块级 implementation doc、RFC、PRD、tech plan 和代码为主。
 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。
@@ -82,8 +82,8 @@ done task 的执行流水不在当前 `plan.yaml` 长期保留，也不是默认
 - [ ] 代码和测试改动都在当前 task `allowed_paths` 范围内。
 - [ ] 当前 task `required_gates` 已通过，或 blocker 已记录。
 - [ ] open task 在 `plan.yaml` 中包含完整执行合同。
-- [ ] 当前任务仍然是单一清晰的开发语义切片。
-- [ ] implementation doc 已生成并反映真实代码。
+- [ ] 当前任务仍然是单一清晰的执行单元。
+- [ ] implementation doc 已生成或更新，并反映相关模块的真实代码。
 - [ ] gate 结果已写入 implementation doc `Verification`，必要时当前 task `working_notes` 也记录了恢复现场所需的 gate evidence。
 - [ ] task implementation commit 已在 task 移除前创建。
 - [ ] done task 已在 implementation commit 之后从当前 `plan.yaml` 移除。

package/assets/skills/pjsdlc_implementation_doc/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: pjsdlc_implementation_doc
-description: Use after a development task passes code gates to document the real implementation and plan deviations.
+description: Use after development gates pass to update module-level implementation facts and plan deviations.
 ---
 
 # Implementation Doc Skill
 
 ## 目的
 
-记录真实实现事实，包括代码结构、数据流、防御逻辑、测试覆盖，以及相对原技术方案的偏移。
+按模块、子系统或核心数据流记录真实实现事实，包括代码结构、数据流、防御逻辑、测试覆盖，以及相对原技术方案的偏移。
 
 ## 角色提示词
 
@@ -15,11 +15,11 @@ description: Use after a development task passes code gates to document the real
 
 开始记录前，先读取 task、PRD、技术方案、git diff、测试结果和相关源码。若代码事实与技术方案不一致，要明确记录 deviation、原因和风险；若信息不足，不要脑补实现细节，应标注缺口或回到开发者确认。
 
-文档应帮助后来者快速理解：改了哪些文件、关键对象/函数职责是什么、核心数据流如何运行、测试覆盖了什么、还有什么未覆盖。保持任务级粒度，不写成泛泛的模块百科。
+文档应帮助后来者快速理解：某个模块或核心数据流的当前实现是什么、关键对象/函数职责是什么、行为如何从输入流到输出、测试覆盖了什么、还有什么未覆盖。task id 只作为 provenance，不作为默认切片粒度。
 
 ## 输入
 
-- `<harnessRoot>/state/plan.yaml` 中的当前 task ID
+- `<harnessRoot>/state/plan.yaml` 中当前 task 的 `implementation_doc` 路径和 task ID
 - 当前 `git diff`
 - 关联 PRD
 - 关联技术方案
@@ -28,28 +28,30 @@ description: Use after a development task passes code gates to document the real
 
 ## 输出
 
-- `.docs/04_implementation/<domain>/<task>_impl.md`
+- `.docs/04_implementation/<domain>/<module_or_flow>.md`
 - 更新后的 `.docs/INDEX.md`
 
 ## 语义切片
 
-- `.docs/04_implementation/` 按已完成任务、真实实现模块或核心数据流切片。
-- 默认一项 `done` task 对应一份 implementation doc。
-- 如果一个任务实际产出多个独立模块或多个核心数据流，可以拆成多份 implementation docs，但每份都必须回链同一个 Task ID。
-- 如果实现只是在已有模块内补充逻辑，应更新原 implementation doc，而不是创建重复文档。
+- `.docs/04_implementation/` 默认按稳定的模块、子系统或核心数据流切片，并尽量与 architecture / tech plan 的边界对应。
+- task 是执行单元和提交边界，不是 implementation doc 的默认文档边界。task ID、commit 和 RFC 只记录在文档的 provenance 或变更记录中。
+- 如果一个 task 修改已有模块或数据流，应更新对应的原 implementation doc，而不是创建 `dev_*.md` task ledger。
+- 如果一个 task 真实产出多个独立模块或核心数据流，可以更新或新增多份 implementation docs；每份都记录相关 Task ID 和 commit。
+- 只有当某个 task 本身就是一个稳定模块/数据流边界时，implementation doc 才可以与单个 task 一一对应。
 - 如果真实代码边界与技术方案边界不同，必须在文档中记录偏移，并更新 `.docs/INDEX.md`。
 
 ## 规则
 
 1. implementation doc 描述当前代码事实，而不是期望中的未来设计。
-2. 每个被记录的文件都应说明作用和关键函数/对象。
+2. 每个被记录的文件都应说明它在该模块或数据流中的作用和关键函数/对象。
 3. 与技术方案的偏移必须明确记录，即便该偏移是合理的。
 4. 测试覆盖必须列出具体测试，或明确记录覆盖缺口。
-5. 文档粒度保持在任务级，不要写成巨型实现百科。
+5. 文档粒度保持在模块、子系统或核心数据流级别；不要默认按 task 建文档，也不要写成跨全项目的巨型百科。
 
 ## 完成检查
 
-- [ ] Task ID 和关联产物路径齐全。
+- [ ] 模块/子系统/核心数据流边界明确，并与相关 architecture / tech plan 对齐或记录偏移。
+- [ ] Task ID、commit 和关联产物路径已作为 provenance 记录。
 - [ ] 真实代码结构表已填写。
 - [ ] 核心数据流已说明。
 - [ ] 已判断 implementation doc 的语义切片边界。

package/assets/skills/pjsdlc_manager/SKILL.md

@@ -49,7 +49,7 @@ Skill、执行出口 gate，并记录 blocker。
 
 ## 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` 中包含 `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。
 
 `lifecycle.yaml` 和 `plan.yaml` 只用于当前可执行状态。默认不要读取过去 phase/task/gate 执行流水；只有用户明确要求 forensic/audit/regression 追溯时，才临时查询 git、PR、CI 或 release 记录。
 

package/assets/templates/IMPLEMENTATION_DOC_TEMPLATE.md

@@ -1,14 +1,16 @@
-# [Task/Module] Implementation Doc
+# [Module/Subsystem/Core Flow] Implementation Doc
 
 ## 1. 关联信息
 
-- Task ID:
+- Domain:
+- Module / subsystem / core flow:
+- Updated by task:
 - Linked PRD:
 - Linked technical design:
 - Linked RFC:
 - Linked commit:
 
-## 2. 本次实现范围
+## 2. 当前实现范围
 
 - 新增（Added）:
 - 修改（Changed）:
@@ -48,6 +50,12 @@ Input
 |---|---|---|
 |  |  |  |
 
-## 8. 后续维护注意事项
+## 8. 变更记录（Change Log）
+
+| 日期（Date） | Task ID | Commit | 摘要（Summary） |
+|---|---|---|---|
+|  |  |  |  |
+
+## 9. 后续维护注意事项
 
 - 

package/assets/templates/PLAN_TEMPLATE.yaml

@@ -22,4 +22,4 @@ tasks:
       - "验收标准写在 open task 内，完成后从当前 plan 删除。"
     working_notes:
       - "执行现场备注只在 open task 保留。"
-    implementation_doc: ".docs/04_implementation/example/dev_001.md"
+    implementation_doc: ".docs/04_implementation/example/module_or_flow.md"

package/assets/templates/TECH_DESIGN_TEMPLATE.md

@@ -43,6 +43,8 @@ Input
 |---|---|---|---|---|
 | DEV-001 |  | `src/**`, `tests/**` | `make lint`, `make test-current-domain` | `.docs/04_implementation/...` |
 
+`Implementation Doc` 应指向模块、子系统或核心数据流级文档；多个 task 可以更新同一份文档，task id 和 commit 记录在该文档的 provenance / Change Log 中。
+
 ## 7. 风险与缓解
 
 | 风险（Risk） | 等级（Level） | 缓解措施（Mitigation） |

package/dist/lib/config.js

@@ -1,12 +1,15 @@
 import path from "node:path";
+import { createRequire } from "node:module";
 import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
 import { pathExists, readText, writeTextIfChanged } from "./fs.js";
 import { parseYaml, stringifyYaml } from "./yaml.js";
+const require = createRequire(import.meta.url);
+const packageMetadata = require("../../package.json");
 export function defaultConfig(root) {
     return {
         core: {
             package: "agent-project-sdlc",
-            version: "0.1.0",
+            version: packageMetadata.version ?? "0.0.0",
             schema_version: "1"
         },
         managed_files: [

package/package.json

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