agent-project-sdlc 0.1.21 → 0.1.23

package/assets/skills/pjsdlc_tester/SKILL.md

@@ -17,7 +17,7 @@ description: Use during TESTING to produce a test matrix, run regression, and do
 
 执行回归时，优先选择能证明阶段出口的 gate。测试无法运行、环境缺失或数据不可得时，不要宣布通过；如果已经进入 TESTING，应在 `TEST_REPORT.md` 中记录 `BLOCKED`、已完成检查和恢复条件。
 
-TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输出验证。可以补充测试、fixture、mock、assertion helper 和测试文档，但不能在 TESTING 中新增或长期维护 product runtime、server/API/CLI/adapter、direct poller、cloud bootstrap、systemd unit、真实 provider adapter、package runtime script 或部署脚本。如果发现真实入口/出口不存在、implementation doc 缺少 `Development Evidence` 或 `Development Self-Test Report`、自测报告缺少从本地启动或调用入口到完成全部自测用例的 `Module Key Test Path`、或该路径没有覆盖本 task / 本模块承诺的入口、内部关键路径、关键边界、观察点和完成证据，live 模式不可调用、配置契约缺失、Review readiness checklist 不是全 `PASS`，或 `Evidence Level` / `Target Runtime Environment` / `self_test_contract` 与 task 或技术方案承诺不一致，应记录 `BLOCKED`、生成 RFC 或后续 dev task 建议，并停止把测试阶段扩大成开发/集成搭建。开发尚未交付可测试 entry/exit、目标运行环境、Development Self-Test Report 或 Testing Handoff Contract 时，不要在 `.docs/07_test/**` 提前生成正式测试用例或正式报告；验收思路应留在 PRD acceptance criteria、tech plan verification strategy 或非 `.docs/07_test/**` 的草稿说明里。`TEST_REPORT.md` 不能在描述缺少 entry/exit、缺少 Development Evidence、缺少 Development Self-Test Report、证据等级不匹配或未交付应用入口时给出 `PASS`。
+TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输出验证。可以补充测试、fixture、mock、assertion helper 和测试文档，但不能在 TESTING 中新增或长期维护 product runtime、server/API/CLI/adapter、direct poller、cloud bootstrap、systemd unit、真实 provider adapter、package runtime script 或部署脚本。如果发现真实入口/出口不存在、implementation doc 缺少 `Development Evidence` 或 `Development Self-Test Report`、自测报告缺少 `Report Status: PASS`、缺少从本地启动或调用入口到完成全部自测用例的 `Module Key Test Path`、缺少 `Evidence Index Refs`、或该路径没有覆盖本 task / 本模块承诺的入口、内部关键路径、关键边界、观察点和完成证据，live 模式不可调用、配置契约缺失、Review readiness checklist 不是全 `PASS`，或 `Evidence Level` / `Target Runtime Environment` / `self_test_contract` 与 task 或技术方案承诺不一致，应记录 `BLOCKED`、生成 RFC 或后续 dev task 建议，并停止把测试阶段扩大成开发/集成搭建。若 `self_test_contract` 设置 `graph_required: true` 或包含 `module_key_test_graph`，TESTING 必须按 `Module Key Test Graph` 选择入口、checkpoint、scenario 和 observable exit，不能重新发明 runtime 或把图扩成测试执行引擎。`Development Self-Test Report` 不是 debug log、operator log、runbook、evidence dump 或探索流水；测试只消费其模块入口、核心路径、出口和最小证据指针。high-risk runtime/live/remote-operator 验证要先读 `plan.yaml#resume_capsule`，再读 `.docs/09_runbooks/**` runbook 和 evidence index，最后才读 exploration appendix；测试只沿 canonical path 和 hard constraints 验证，不重新尝试 `do_not_retry` 中的失败路径。开发尚未交付可测试 entry/exit、目标运行环境、Development Self-Test Report 或 Testing Handoff Contract 时，不要在 `.docs/07_test/**` 提前生成正式测试用例或正式报告；验收思路应留在 PRD acceptance criteria、tech plan verification strategy 或非 `.docs/07_test/**` 的草稿说明里。`TEST_REPORT.md` 不能在描述缺少 entry/exit、缺少 Development Evidence、缺少 Development Self-Test Report、证据等级不匹配或未交付应用入口时给出 `PASS`。
 
 测试设计和回归证据产出本身也是 workflow task。开始测试前，先在 `<harnessRoot>/state/plan.yaml` 创建或选择一个足够小的 `TASK-*` open task，并设置 `phase: "TESTING"`；当前轮只产出一个测试策略 slice、测试用例 slice、回归批次、风险验证片区或一组 scoped test changes。`plan.yaml` 仍是唯一执行计划事实源，`.docs/07_test/**` 只记录当前方案的 test strategy、test cases、executed regression evidence、coverage gaps 和 final decision，不表达“下一步如何开发”，也不保留已被 RFC supersede 的旧测试结果。
 
@@ -67,7 +67,7 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 
 ## 规则
 
-1. 测试用例必须追溯到 PRD acceptance criteria 或 Review findings，并绑定 SPRINTING/REVIEWING 已确认的 runnable entry/exit、Development Evidence、Development Self-Test Report、Evidence Level、Target Runtime Environment 和 Testing Handoff Contract。
+1. 测试用例必须追溯到 PRD acceptance criteria 或 Review findings，并绑定 SPRINTING/REVIEWING 已确认的 runnable entry/exit、Development Evidence、Development Self-Test Report、Evidence Level、Target Runtime Environment 和 Testing Handoff Contract；复杂路径还要消费 Module Key Test Graph，而不是在 TESTING 中重新设计 runtime path。
 2. 根据风险补充边界、负向、回归和集成测试。
 3. 如果有意延后覆盖，必须记录风险和 follow-up。
 4. 不得新增 product runtime、server/API/CLI/adapter、poller、cloud bootstrap、systemd unit、真实 provider adapter、package runtime script 或部署脚本；这些属于 SPRINTING/RFC。
@@ -87,7 +87,8 @@ TESTING 只能调用 SPRINTING/REVIEWING 已确认 `PASS` 的入口做输入/输
 - [ ] Regression checklist 已完成。
 - [ ] 测试只调用既有 runnable entry/exit；未在 TESTING 中新增 product runtime、bootstrap、provider adapter、deploy 或 package runtime script。
 - [ ] 已核对 implementation doc 中的 Development Evidence、Evidence Level、Target Runtime Environment 和 Testing Handoff Contract，并只基于已交付入口设计测试。
-- [ ] 已核对 Development Self-Test Report 中 scenario results、executed gates、Module Key Test Path 和 actual evidence。
+- [ ] 已核对 Development Self-Test Report 中 Report Status、Module Application Entry、scenario results、executed gates、Module Key Test Path、Observable Exit、Current Blocker、Testing Handoff Readiness 和 Evidence Index Refs；若存在 Module Key Test Graph，测试路径按图消费。
+- [ ] high-risk runtime/live 验证已优先使用 `resume_capsule` 与 runbook/evidence index，未重复执行 exploration appendix 中的失败路径。
 - [ ] 已判断 test report / test matrix 的语义切片边界。
 - [ ] 未把测试计划、测试用例或待填内容写成 `TEST_REPORT.md`。
 - [ ] 已确认 `.docs/07_test/**` 只包含当前方案仍有效的测试事实。

package/assets/templates/EVIDENCE_INDEX_TEMPLATE.md

@@ -0,0 +1,18 @@
+# [Runtime / Live Smoke] Evidence Index
+
+本文件只保存证据指针和缺口，不把证据正文塞回 implementation doc 主线或 `Development Self-Test Report`。
+
+| Scenario | Status | Evidence File / System | Gap / Next Action |
+|---|---|---|---|
+|  | PASS / BLOCKED / GAP |  |  |
+
+## Evidence Retention
+
+- Temporary evidence:
+- Stable artifact / CI / release record:
+- Evidence that must not be copied into main docs:
+- Development Self-Test Report reference format:
+
+## Missing Evidence
+
+- 

package/assets/templates/EXPLORATION_APPENDIX_TEMPLATE.md

@@ -0,0 +1,24 @@
+# [Runtime / Operator Path] Exploration Appendix
+
+## Purpose
+
+记录失败尝试、诊断路径和不要重复踩坑的结论。本文件是记忆附录，不是恢复主线。
+不要把本文件的长日志复制进 `Development Self-Test Report`；主报告最多保留一句 fallback / diagnostic 总结。
+
+## Failed / Diagnostic Attempts
+
+| Attempt | Result | Why It Failed Or Stayed Diagnostic | Do Not Retry Rule |
+|---|---|---|---|
+|  |  |  |  |
+
+## Useful Observations
+
+- 
+
+## Promoted Decisions
+
+| Decision | Promoted To |
+|---|---|
+|  | `plan.yaml#resume_capsule` / runbook / implementation doc |
+
+凡会改变下一步动作的判断，必须 promoted 到 `plan.yaml#resume_capsule.do_not_retry` 或 runbook 顶部 `Hard Constraints`；本 appendix 只能保留推导和历史背景。

package/assets/templates/IMPLEMENTATION_DOC_TEMPLATE.md

@@ -51,23 +51,76 @@ Input
 - Testing Handoff Readiness:
 - Known Missing Runtime Boundaries:
 - Basic Self-test Evidence: See `Development Self-Test Report`.
+- Resume Capsule / Runbook:
 - Not applicable:
 
-## 7. Development Self-Test Report（开发自测报告，已执行）
+## 7. Current Operator Path（当前操作路径，仅 runtime/live/remote-operator 需要）
 
+- Canonical path:
+- Operator runbook: `.docs/09_runbooks/...`
+- Credential reference: Keychain item name 或 secret reference name only；不要记录明文密钥。
+- Command/UI channel:
+- Hard Constraints: 会改变下一步动作的判断必须提升到这里和 `plan.yaml#resume_capsule.do_not_retry`；不要只埋在 evidence、notes 或 appendix。
+- Do-not-retry summary: fallback / diagnostic 只写一句结论，详细内容进 exploration appendix 或 git history。
+
+## 8. Development Self-Test Report（开发自测报告）
+
+本节是开发阶段可执行交接卡，只证明模块应用入口、核心路径、出口和最小证据指针。目标控制在几十行；high-risk runtime/live 场景包含 `Gate Breakdown` 时也不要超过 120 行。本节不是 debug log、operator log、runbook、evidence dump 或探索流水。
+
+- Report Status: PASS | BLOCKED | IN_PROGRESS | STALE
 - Contract Source:
+- Module Application Entry:
+- Module Key Test Path: local start / invocation -> all self-test scenarios -> all task/module promised runnable entries -> actual internal key paths / boundaries / checkpoints -> observable completion evidence
+- Module Key Test Graph: required only when `self_test_contract.graph_required: true` or `module_key_test_graph` exists; keep it as a compact DAG pointer list/table covering entry, checkpoints, scenario nodes, observable exit, and evidence refs.
 - Scenario Results:
 - Executed Gates:
-- Module Key Test Path: local start / invocation -> all self-test scenarios -> all task/module promised runnable entries -> actual internal key paths / boundaries / checkpoints -> observable completion evidence
-- Actual Evidence:
-- Missing / Blockers:
+- Observable Exit:
+- Current Blocker:
 - Testing Handoff Readiness:
+- Evidence Index Refs: `.docs/09_runbooks/..._evidence.md` 或外部 artifact / CI / command output path；不要复制证据正文。
+
+保留：
+- Runnable Entry / Module Key Test Path / Observable Exit
+- Scenario Results / Executed Gates / Evidence Index Refs
+- Current Blocker / Testing Handoff Readiness
+
+不保留：
+- 每次工具探索的完整流水
+- debug log、operator log、历史操作日记或 runbook 正文
+- fallback / diagnostic 的长篇命令、截图过程或 UI 细节
+- 与当前恢复路径无关的旧失败通道；只在 appendix 或 git history 保留
+- `Actual Evidence` 正文字段；证据正文进入 Evidence Index 或外部 artifact，本节只留 refs
+- high-risk implementation doc 主线不得新增 `Evidence Dump`、`Operator Log`、`Failed Attempts`、`Screenshot Index` 等章节；这些只能进入 runbook / evidence index / exploration appendix
+
+### Gate Breakdown（Gate 分层）
+
+| Gate Layer | Status | Evidence | Gap / Next Action |
+|---|---|---|---|
+| Local gate |  |  |  |
+| Cloud/service gate |  |  |  |
+| Executor/operator readiness |  |  |  |
+| Live smoke / handoff |  |  |  |
 
 | Scenario ID | Result | Executed Entry | Actual Exit | Evidence |
 |---|---|---|---|---|
 |  |  |  |  |  |
 
-## 8. Testing Handoff Contract（测试交接合同）
+### Module Key Test Graph（复杂 / high-risk 路径需要）
+
+只记录实际 handoff path 的 DAG 骨架和 evidence pointer；不要放 command output、截图过程、operator log、debug log、runbook 正文、失败探索或历史流水。
+
+| Node ID | Kind | Label | Scenario Ref | Expected Exit | Evidence Ref |
+|---|---|---|---|---|---|
+| entry-local-start | entry |  |  |  |  |
+| scenario-st-001 | scenario |  | ST-001 |  | `.docs/09_runbooks/...#ST-001` |
+| exit-observable | observable_exit |  |  |  |  |
+
+| From | To |
+|---|---|
+| entry-local-start | scenario-st-001 |
+| scenario-st-001 | exit-observable |
+
+## 9. Testing Handoff Contract（测试交接合同）
 
 - Entry:
 - Config:
@@ -77,7 +130,7 @@ Input
 - Cleanup / reset / idempotency:
 - Evidence Level:
 
-## 9. 关键实现逻辑
+## 10. 关键实现逻辑
 
 - 输入校验（Input validation）:
 - 核心分支（Core branches）:
@@ -85,22 +138,22 @@ Input
 - 边界兜底（Boundary fallback）:
 - 性能或并发注意事项（Performance or concurrency notes）:
 
-## 10. 与技术方案的偏移
+## 11. 与技术方案的偏移
 
 - 
 
-## 11. 测试覆盖（Test Coverage）
+## 12. 测试覆盖（Test Coverage）
 
 | 测试（Test） | 覆盖范围（Coverage） | 结果（Result） |
 |---|---|---|
 |  |  |  |
 
-## 12. 变更记录（Change Log）
+## 13. 变更记录（Change Log）
 
 | 日期（Date） | Task ID | Commit | 摘要（Summary） |
 |---|---|---|---|
 |  |  |  |  |
 
-## 13. 后续维护注意事项
+## 14. 后续维护注意事项
 
 - 

package/assets/templates/PLAN_TEMPLATE.yaml

@@ -1,5 +1,21 @@
 current_task_id: "TASK-001"
 next_task_sequence: 2
+# Required while the current SPRINTING task is high-risk runtime/live work
+# (`external_provider_live`, `deployed_runtime`, `business_handoff_ready`, or
+# target runtime `cloud_vm` / `managed_service` / `browser` / `worker`). Keep this
+# short: 5-8 recovery facts, not a full attempt log.
+# resume_capsule:
+#   task_id: "TASK-001"
+#   state: "in_progress | blocked | ready_for_gate"
+#   canonical_path: "operator/runtime path to continue from"
+#   next_step: "one concrete next action"
+#   blocker: "current blocker, or none with context"
+#   last_passed_gate: "last concrete PASS gate or checkpoint"
+#   do_not_retry:
+#     - "known failed path, repeated trap, or strategy-changing hard constraint; e.g. if PC WeChat shows QR after confirmed login, first classify rule_assumption_gap vs operator_induced_logout_or_session_reset before rescanning"
+#   recovery_refs:
+#     - ".docs/04_implementation/example.md"
+#     - ".docs/09_runbooks/example_live_smoke_runbook.md"
 # Optional top-level execution contract. Omit this block when the current task
 # stays serial after the default parallel eligibility check. Use
 # trigger: "workflow_default" when the workflow safely splits the task by
@@ -46,6 +62,7 @@ tasks:
       architecture: []
       tech_plan: []
       rfc: []
+      runbook: []
     allowed_paths:
       - ".docs/00_raw/**"
       - ".docs/01_product/**"
@@ -76,6 +93,36 @@ tasks:
       runnable_entry: "command / URL / endpoint / worker command"
       observable_exit: "response / page state / side effect / log / artifact"
       module_key_test_path: "local start command / URL -> all self-test scenarios -> all task/module promised runnable entries -> internal key paths / boundaries / checkpoints -> observable completion evidence"
+      # Set graph_required: true for complex/high-risk handoff paths:
+      # scenario >= 3, multiple branches/entries, runtime/live/provider/browser/worker,
+      # or paths that Review/Testing must consume explicitly. The graph is a
+      # lightweight DAG handoff skeleton, not an execution trace, runbook, log,
+      # evidence dump, or graph engine input.
+      graph_required: false
+      module_key_test_graph:
+        nodes:
+          - id: "entry-local-start"
+            kind: "entry"
+            label: "local start command / URL"
+          - id: "checkpoint-core-path"
+            kind: "checkpoint"
+            label: "core module boundary or checkpoint"
+          - id: "scenario-st-001"
+            kind: "scenario"
+            label: "ST-001 expected behavior"
+            scenario_ref: "ST-001"
+            expected_exit: "observable response / side effect / page state"
+            evidence_ref: ".docs/09_runbooks/example_evidence.md#ST-001"
+          - id: "exit-observable"
+            kind: "observable_exit"
+            label: "observable response / side effect / page state"
+        edges:
+          - from: "entry-local-start"
+            to: "checkpoint-core-path"
+          - from: "checkpoint-core-path"
+            to: "scenario-st-001"
+          - from: "scenario-st-001"
+            to: "exit-observable"
       required_gates:
         - "npm run smoke"
       scenarios:
@@ -85,6 +132,6 @@ tasks:
           evidence: "command/browser/API/log/screenshot/etc"
       not_applicable_reason: ""
     working_notes:
-      - "执行现场备注只在 open task 保留。"
+      - "执行现场备注只保留恢复所需的短备注；目标 5-8 条，validator 上限 8 条；路径选择结论提升到 resume_capsule。"
     result_docs:
       - ".docs/01_product/example.md"

package/assets/templates/RUNBOOK_TEMPLATE.md

@@ -0,0 +1,52 @@
+# [Runtime / Operator Path] Runbook
+
+本文件记录 operator/provisioning 恢复路径，不是 `Development Self-Test Report` 或 scenario evidence。
+
+## 1. Recovery Summary
+
+- Canonical path:
+- Current state:
+- Next command channel:
+- Last known good checkpoint:
+- Primary blocker:
+
+## 2. Hard Constraints
+
+- 会改变下一步动作的判断必须写在这里，并同步到 `plan.yaml#resume_capsule.do_not_retry` 或 implementation doc `Current Operator Path`。
+- Example: PC 微信已登录后再次出现 QR 时，先判定 `rule_assumption_gap` vs `operator_induced_logout_or_session_reset`，不得直接进入重新扫码流程。
+
+## 3. Operator Path
+
+```txt
+canonical:
+credentials: Keychain item name or secret reference only
+remote host:
+command channel:
+UI channel:
+do not prefer:
+```
+
+## 4. Preconditions
+
+- Required access:
+- Required local tools:
+- Required remote services:
+- Safety / cleanup notes:
+
+## 5. Resume Steps
+
+1. 
+2. 
+3. 
+
+## 6. Fallbacks And Diagnostics
+
+- Preferred fallback:
+- Diagnostic-only paths:
+- Do not retry:
+
+## 7. Linked Evidence
+
+- Evidence index:
+- Exploration appendix:
+- Implementation doc: