agent-project-sdlc 0.1.18 → 0.1.20

package/assets/templates/IMPLEMENTATION_DOC_TEMPLATE.md

@@ -50,10 +50,24 @@ Input
 - Config Contract:
 - Testing Handoff Readiness:
 - Known Missing Runtime Boundaries:
-- Basic Self-test Evidence:
+- Basic Self-test Evidence: See `Development Self-Test Report`.
 - Not applicable:
 
-## 7. Testing Handoff Contract（测试交接合同）
+## 7. Development Self-Test Report（开发自测报告，已执行）
+
+- Contract Source:
+- 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:
+- Testing Handoff Readiness:
+
+| Scenario ID | Result | Executed Entry | Actual Exit | Evidence |
+|---|---|---|---|---|
+| ST-001 | PASS / BLOCKED |  |  |  |
+
+## 8. Testing Handoff Contract（测试交接合同）
 
 - Entry:
 - Config:
@@ -63,7 +77,7 @@ Input
 - Cleanup / reset / idempotency:
 - Evidence Level:
 
-## 8. 关键实现逻辑
+## 9. 关键实现逻辑
 
 - 输入校验（Input validation）:
 - 核心分支（Core branches）:
@@ -71,22 +85,22 @@ Input
 - 边界兜底（Boundary fallback）:
 - 性能或并发注意事项（Performance or concurrency notes）:
 
-## 9. 与技术方案的偏移
+## 10. 与技术方案的偏移
 
 - 
 
-## 10. 测试覆盖（Test Coverage）
+## 11. 测试覆盖（Test Coverage）
 
 | 测试（Test） | 覆盖范围（Coverage） | 结果（Result） |
 |---|---|---|
 |  |  |  |
 
-## 11. 变更记录（Change Log）
+## 12. 变更记录（Change Log）
 
 | 日期（Date） | Task ID | Commit | 摘要（Summary） |
 |---|---|---|---|
 |  |  |  |  |
 
-## 12. 后续维护注意事项
+## 13. 后续维护注意事项
 
 - 

package/assets/templates/PLAN_TEMPLATE.yaml

@@ -1,17 +1,20 @@
 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.
+# 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
+# default; use trigger: "user_requested" when the user explicitly asks for
+# parallel / multi-agent / multi-worktree execution.
 # parallel_execution:
 #   enabled: true
-#   trigger: "user_requested"
-#   mode: "user_orchestrated" # or "runtime_managed" when the current agent runtime can spawn subagents
+#   trigger: "workflow_default"
+#   mode: "runtime_managed"
+#   runtime:
+#     provider: "codex_native_subagents" # fallbacks: user_orchestrated, codex_exec_worktree
 #   coordinator: "main_agent"
 #   workers:
 #     - id: "worker-feature"
 #       writes_repo: true
-#       branch: "agent/feature"
-#       worktree: "../project-feature"
 #       owned_paths:
 #         - "src/feature/**"
 #         - "tests/feature/**"
@@ -63,6 +66,24 @@ tasks:
       kind: "local | ci | staging | cloud_vm | managed_service | browser | worker | not_applicable"
       required_for_done: true
       handoff_entrypoint: "URL / CLI / worker command / server action"
+    # Required for SPRINTING tasks with a runnable boundary. Created during
+    # ARCHITECTING/RFC and executed during SPRINTING.
+    self_test_contract:
+      status: "required | not_applicable"
+      source: ".docs/03_tech_plan/example.md"
+      capability_refs:
+        - "PRD-EXAMPLE-001"
+      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"
+      required_gates:
+        - "npm run smoke"
+      scenarios:
+        - id: "ST-001"
+          entry: "command / URL / endpoint / worker command"
+          expected_exit: "observable response / side effect / page state"
+          evidence: "command/browser/API/log/screenshot/etc"
+      not_applicable_reason: ""
     working_notes:
       - "执行现场备注只在 open task 保留。"
     result_docs:

package/assets/templates/RFC_TEMPLATE.md

@@ -38,6 +38,17 @@
 - Retained test docs:
 - Reason:
 
-## 8. Status
+## 8. Development Self-Test Impact（开发自测影响）
+
+- Entry/exit impact:
+- Runtime / target environment impact:
+- Required gates impact:
+- Tech plan self-test contract impact:
+- `plan.yaml` / `plan.draft.yaml` task contract impact:
+- Implementation doc self-test report impact:
+- Module key test path impact:
+- Review / Testing handoff impact:
+
+## 9. Status
 
 - Status: DRAFT

package/assets/templates/TECH_DESIGN_TEMPLATE.md

@@ -45,12 +45,29 @@ Input
 
 `Implementation Doc` 应指向模块、子系统或核心数据流级文档；多个 task 可以更新同一份文档，task id 和 commit 记录在该文档的 provenance / Change Log 中。
 
-## 7. 风险与缓解
+## 7. Development Self-Test Contract（开发自测合同，待执行）
+
+> service / agent / runtime / worker / frontend app / provider-live / API / CLI 等可运行边界的开发 task 必填，并同步写入 `plan.draft.yaml.tasks[].self_test_contract`。
+
+- Contract source:
+- Capability refs:
+- Runnable entry:
+- Observable exit:
+- Module key test path（local start -> all self-test scenarios -> all promised runnable entries -> internal key paths -> observable completion evidence）:
+- Required gates:
+
+| Scenario ID | Entry | Expected Exit | Evidence |
+|---|---|---|---|
+| ST-001 |  |  | command/browser/API/log/screenshot/etc |
+
+- Not applicable reason:
+
+## 8. 风险与缓解
 
 | 风险（Risk） | 等级（Level） | 缓解措施（Mitigation） |
 |---|---|---|
 |  | P1 |  |
 
-## 8. 需要关注的方案偏移
+## 9. 需要关注的方案偏移
 
 - 

package/assets/tools/build_doc_overviews.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+
+from harness_utils import ROOT, HarnessError, require, run_main
+
+
+DOCS_ROOT = ROOT / ".docs"
+OUTPUT_NAME = "overview.md"
+LEGACY_OUTPUT_NAME = "overview.html"
+
+
+def stage_dirs() -> list[Path]:
+    require(DOCS_ROOT.exists(), "Missing .docs directory")
+    return sorted(path for path in DOCS_ROOT.iterdir() if path.is_dir() and not path.name.startswith("."))
+
+
+def resolve_stage(value: str) -> Path:
+    raw = Path(value)
+    path = raw if raw.is_absolute() else ROOT / raw
+    if not path.exists() and not value.startswith(".docs/"):
+        path = DOCS_ROOT / value
+    require(path.exists() and path.is_dir(), f"Stage directory not found: {value}")
+    require(DOCS_ROOT in path.parents or path == DOCS_ROOT, f"Stage must be under .docs/: {value}")
+    return path
+
+
+def markdown_files(stage: Path) -> list[Path]:
+    files = []
+    for path in sorted(stage.rglob("*.md")):
+        if any(part.startswith(".") for part in path.relative_to(stage).parts):
+            continue
+        if path.name in {OUTPUT_NAME, LEGACY_OUTPUT_NAME}:
+            continue
+        files.append(path)
+    return files
+
+
+def source_hash(files: list[Path], stage: Path) -> str:
+    digest = hashlib.sha256()
+    for path in files:
+        relative = path.relative_to(stage).as_posix()
+        digest.update(relative.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(path.read_bytes())
+        digest.update(b"\0")
+    return digest.hexdigest()[:16]
+
+
+def markdown_link(label: str, target: str) -> str:
+    escaped_label = label.replace("[", "\\[").replace("]", "\\]")
+    escaped_target = target.replace(" ", "%20")
+    return f"[{escaped_label}]({escaped_target})"
+
+
+def markdown_document(stage: Path, files: list[Path]) -> str:
+    stage_name = stage.relative_to(ROOT).as_posix()
+    digest = source_hash(files, stage)
+    parts = [
+        f"# {stage_name} overview",
+        "",
+        "<!-- generated-by: AI SDLC Harness build_doc_overviews.py -->",
+        f"<!-- source-hash: {digest} -->",
+        "",
+        "Generated artifact. Markdown slices remain the source of truth.",
+        "",
+        f"Source hash: `{digest}`",
+        "",
+        "## Source Slices",
+        "",
+    ]
+
+    if not files:
+        parts.extend(["当前阶段还没有 Markdown slice。", ""])
+    else:
+        for index, path in enumerate(files, start=1):
+            relative = path.relative_to(stage).as_posix()
+            parts.append(f"{index}. {markdown_link(relative, relative)}")
+        parts.append("")
+
+    for path in files:
+        relative = path.relative_to(stage).as_posix()
+        content = path.read_text(encoding="utf-8").strip()
+        parts.extend(
+            [
+                "---",
+                "",
+                f"## {relative}",
+                "",
+                f"Source: {markdown_link(relative, relative)}",
+                "",
+                content if content else "空文档。",
+                "",
+            ]
+        )
+
+    return "\n".join(parts).rstrip() + "\n"
+
+
+def write_overview(stage: Path, check: bool) -> bool:
+    files = markdown_files(stage)
+    output = stage / OUTPUT_NAME
+    legacy_output = stage / LEGACY_OUTPUT_NAME
+    rendered = markdown_document(stage, files)
+    if check:
+        if legacy_output.exists():
+            print(f"Legacy {legacy_output.relative_to(ROOT)} remains")
+            return False
+        if not output.exists():
+            print(f"Missing {output.relative_to(ROOT)}")
+            return False
+        existing = output.read_text(encoding="utf-8")
+        if existing != rendered:
+            print(f"Outdated {output.relative_to(ROOT)}")
+            return False
+        print(f"OK {output.relative_to(ROOT)}")
+        return True
+    if legacy_output.exists():
+        legacy_output.unlink()
+    output.write_text(rendered, encoding="utf-8")
+    print(f"Wrote {output.relative_to(ROOT)}")
+    return True
+
+
+def selected_stages(args: argparse.Namespace) -> list[Path]:
+    if args.stage:
+        return [resolve_stage(value) for value in args.stage]
+    return stage_dirs()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Build deterministic Markdown overviews for .docs stage slices")
+    parser.add_argument("--stage", action="append", help="Stage directory, e.g. .docs/01_product or 01_product")
+    parser.add_argument("--all", action="store_true", help="Build all .docs stage directories")
+    parser.add_argument("--check", action="store_true", help="Check whether overview.md files are up to date")
+    args = parser.parse_args()
+
+    stages = selected_stages(args)
+    require(stages, "No .docs stage directories found")
+    ok = True
+    for stage in stages:
+        ok = write_overview(stage, args.check) and ok
+    if not ok:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run_main(main)