agent-project-sdlc 0.1.18 → 0.1.20

package/assets/tools/validate_prompt_language.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+from pathlib import Path
+
+from harness_utils import ROOT, HarnessError, load_yaml, require, run_main
+
+
+SKILL_REQUIRED_SECTIONS = ["## 目的", "## 角色提示词", "## 输入", "## 规则", "## 完成检查"]
+ARTIFACT_SKILLS_REQUIRE_SEMANTIC_SLICING = {
+    "pjsdlc_pm_prd",
+    "pjsdlc_architect_design",
+    "pjsdlc_dev_sprint",
+    "pjsdlc_implementation_doc",
+    "pjsdlc_reviewer",
+    "pjsdlc_tester",
+    "pjsdlc_release_manager",
+    "pjsdlc_rfc_recalibrate",
+}
+SKILL_FORBIDDEN_HEADINGS = [
+    "## Purpose",
+    "## Required Inputs",
+    "## Outputs",
+    "## Rules",
+    "## Completion Checklist",
+]
+
+MACHINE_IDENTIFIERS = [
+    "current_phase",
+    "active_skill",
+    "allowed_paths",
+    "required_gates",
+    "implementation_doc",
+    "REQUIREMENT_GATHERING",
+    "ARCHITECTING",
+    "SPRINTING",
+    "REVIEWING",
+    "TESTING",
+    "RELEASING",
+    "RFC_RECALIBRATION",
+    "BLOCKED",
+    "pending",
+    "in_progress",
+    "done",
+    "pending_revision",
+]
+
+REQUIRED_AGENTS_TERMS = [
+    "Skill Language Contract",
+    "中文解释 + 英文精确标识符",
+    ".codex/state/lifecycle.yaml",
+    ".codex/state/plan.yaml",
+    "make validate-current",
+]
+
+YAML_KEYWORDS = {
+    "lifecycle": [
+        "project_name",
+        "version",
+        "current_phase",
+        "active_role",
+        "active_skill",
+        "current_milestone",
+        "allowed_next_phases",
+    ],
+    "plan": [
+        "current_task_id",
+        "next_task_sequence",
+        "tasks",
+    ],
+    "phase_contracts": ["phases"],
+}
+
+
+def text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def validate_agents() -> None:
+    content = text(ROOT / "AGENTS.md")
+    for term in REQUIRED_AGENTS_TERMS:
+        require(term in content, f"AGENTS.md missing skill language contract term: {term}")
+    for identifier in MACHINE_IDENTIFIERS:
+        require(identifier in content, f"AGENTS.md should preserve machine identifier: {identifier}")
+
+
+def validate_skills() -> None:
+    skill_files = sorted((ROOT / ".codex/skills").glob("*/SKILL.md"))
+    require(skill_files, "No workflow skill files found under .codex/skills/")
+
+    for path in skill_files:
+        content = text(path)
+        for section in SKILL_REQUIRED_SECTIONS:
+            require(section in content, f"{path.relative_to(ROOT)} missing Chinese section: {section}")
+        for heading in SKILL_FORBIDDEN_HEADINGS:
+            require(heading not in content, f"{path.relative_to(ROOT)} still uses English skill heading: {heading}")
+        require("name:" in content and "description:" in content, f"{path.relative_to(ROOT)} must keep frontmatter name/description")
+        skill_name = path.parent.name
+        if skill_name in ARTIFACT_SKILLS_REQUIRE_SEMANTIC_SLICING:
+            require("## 语义切片" in content, f"{path.relative_to(ROOT)} missing semantic slicing section: ## 语义切片")
+
+
+def validate_skill_template() -> None:
+    path = ROOT / ".codex/pjsdlc_managed/templates/SKILL_TEMPLATE.md"
+    require(path.exists(), "Missing .codex/pjsdlc_managed/templates/SKILL_TEMPLATE.md")
+    content = text(path)
+    for section in SKILL_REQUIRED_SECTIONS:
+        require(section in content, f"SKILL_TEMPLATE.md missing Chinese section: {section}")
+    require("## 语义切片" in content, "SKILL_TEMPLATE.md missing semantic slicing section: ## 语义切片")
+    require("current_phase" in content and "make validate-current" in content, "SKILL_TEMPLATE.md must demonstrate English machine identifiers")
+
+
+def validate_yaml_keys() -> None:
+    lifecycle = load_yaml(".codex/state/lifecycle.yaml")
+    tasks = load_yaml(".codex/state/plan.yaml")
+    phase_contracts = load_yaml(".codex/pjsdlc_managed/policies/phase_contracts.yaml")
+
+    for key in YAML_KEYWORDS["lifecycle"]:
+        require(key in lifecycle, f"lifecycle.yaml key was removed or translated: {key}")
+    for key in YAML_KEYWORDS["plan"]:
+        require(key in tasks, f"plan.yaml key was removed or translated: {key}")
+    for key in YAML_KEYWORDS["phase_contracts"]:
+        require(key in phase_contracts, f"phase_contracts.yaml key was removed or translated: {key}")
+
+
+def main() -> None:
+    try:
+        validate_agents()
+        validate_skills()
+        validate_skill_template()
+        validate_yaml_keys()
+    except HarnessError:
+        raise
+    print("Skill language contract OK")
+
+
+if __name__ == "__main__":
+    run_main(main)

package/assets/tools/validate_release_plan.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+from harness_utils import (
+    combined_text,
+    contains_any,
+    load_plan,
+    markdown_deliverables,
+    repo_path,
+    require,
+    run_main,
+    validate_plan_contract,
+)
+
+
+CURRENT_RELEASE_REPORT = ".docs/08_release/CURRENT_RELEASE.md"
+
+
+def release_deliverables():
+    current = repo_path(CURRENT_RELEASE_REPORT)
+    if current.exists():
+        return [current], CURRENT_RELEASE_REPORT
+    docs = markdown_deliverables(".docs/08_release")
+    return docs, "legacy .docs/08_release/*.md"
+
+
+def main() -> None:
+    validate_plan_contract(load_plan(), allow_open=False)
+    docs, source = release_deliverables()
+    require(docs, f"Missing current release report: expected {CURRENT_RELEASE_REPORT} or legacy .docs/08_release/*.md")
+    text = combined_text(docs)
+    require(contains_any(text, ["release", "发布"]), "Current release report must include release notes")
+    require(contains_any(text, ["smoke", "冒烟"]), "Current release report must include smoke test evidence")
+    require(contains_any(text, ["rollback", "回滚"]), "Current release report must include rollback plan")
+    print(f"Current release status OK: {source}")
+
+
+if __name__ == "__main__":
+    run_main(main)

package/assets/tools/validate_review.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+from harness_utils import contains_any, load_plan, read_text, require, run_main, validate_plan_contract
+
+READINESS_FIELDS = [
+    "Runnable Entry",
+    "Observable Exit",
+    "Initialization",
+    "Config Contract",
+    "Testing Handoff Readiness",
+]
+RUNTIME_MISMATCH_TERMS = [
+    "not deployed",
+    "not initialized",
+    "local only",
+    "localhost only",
+    "fake adapter",
+    "fake send",
+    "未部署",
+    "未初始化",
+    "只在本地",
+    "仅本地",
+    "本地跑通",
+]
+
+
+def main() -> None:
+    validate_plan_contract(load_plan(), allow_open=False)
+    text = read_text(".docs/06_review/REVIEW_REPORT.md")
+    require(contains_any(text, ["finding", "发现", "风险"]), "Review report must include findings or risks")
+    require(contains_any(text, ["test gap", "测试缺口", "coverage"]), "Review report must include test gaps or coverage notes")
+    require(
+        contains_any(text, ["entry/exit", "entrypoint", "入口", "出口", "runnable", "可运行"]),
+        "Review report must assess runnable entry/exit readiness before TESTING",
+    )
+    lowered = text.lower()
+    for field in READINESS_FIELDS:
+        field_lower = field.lower()
+        has_status = (
+            f"{field_lower}: pass" in lowered
+            or f"{field_lower}: `pass`" in lowered
+            or f"{field_lower}: blocked" in lowered
+            or f"{field_lower}: `blocked`" in lowered
+        )
+        require(has_status, f"Review report must include {field}: PASS/BLOCKED")
+        require(
+            f"{field_lower}: blocked" not in lowered and f"{field_lower}: `blocked`" not in lowered,
+            f"Review readiness is BLOCKED: {field}",
+        )
+    require(contains_any(text, ["pass", "blocked", "通过", "阻塞"]), "Review report must include PASS/BLOCKED decision")
+    if contains_any(lowered, ["decision: pass", "decision: `pass`", "final decision: pass"]):
+        require(
+            not contains_any(lowered, RUNTIME_MISMATCH_TERMS),
+            "Review report cannot PASS while target runtime or handoff evidence is missing or lower-level only",
+        )
+    print("Review report OK")
+
+
+if __name__ == "__main__":
+    run_main(main)

package/assets/tools/validate_rfc.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+import re
+
+from harness_utils import (
+    combined_text,
+    contains_any,
+    load_plan,
+    markdown_deliverables,
+    read_text,
+    repo_path,
+    require,
+    run_main,
+    validate_plan_contract,
+)
+
+
+TEST_FACT_SOURCE_REF = re.compile(r"\.docs/07_test/[^\s`,)]+")
+SELF_TEST_TRIGGER_TERMS = [
+    "entry/exit",
+    "runnable entry",
+    "runnable exit",
+    "runnable entry/exit",
+    "runtime",
+    "environment",
+    "target_runtime_environment",
+    "target runtime",
+    "required_gates",
+    "gate",
+    "handoff",
+    "blocker",
+    "module key test path",
+    "test route",
+    "test path",
+    "debug path",
+    "测试路径",
+    "测试链路",
+    "自测链路",
+    "模块关键测试路径",
+    "入口",
+    "出口",
+    "运行环境",
+    "阻塞",
+]
+SELF_TEST_IMPACT_TERMS = ["development self-test impact", "开发自测影响"]
+
+
+def superseded_test_docs(docs) -> list[str]:
+    paths: set[str] = set()
+    for doc in docs:
+        for line in doc.read_text(encoding="utf-8").splitlines():
+            lowered = line.lower()
+            if "superseded" not in lowered and "被替代" not in lowered and "失效" not in lowered:
+                continue
+            for match in TEST_FACT_SOURCE_REF.findall(line):
+                paths.add(match.rstrip(".,;:"))
+    return sorted(paths)
+
+
+def main() -> None:
+    validate_plan_contract(load_plan(), allow_open=False)
+    docs = markdown_deliverables(".docs/rfc")
+    require(docs, "No RFC documents found in .docs/rfc/")
+    text = combined_text(docs)
+    require(contains_any(text, ["background", "背景"]), "RFC must include background")
+    require(contains_any(text, ["product impact", "产品影响"]), "RFC must include product impact")
+    require(contains_any(text, ["technical impact", "技术影响"]), "RFC must include technical impact candidates")
+    require(contains_any(text, ["regression", "回归"]), "RFC must include regression requirements")
+    require(
+        contains_any(text, ["test fact source impact", "测试事实源影响"]),
+        "RFC must include Test Fact Source Impact",
+    )
+    index_text = read_text(".docs/INDEX.md")
+    for path in superseded_test_docs(docs):
+        require(not repo_path(path).exists(), f"Superseded test doc still exists in current facts: {path}")
+        require(path not in index_text, f"Superseded test doc still linked from .docs/INDEX.md: {path}")
+    statuses = re.findall(r"Status:\s*([A-Z_]+)", text)
+    require(statuses, "RFC must include a Status line")
+    allowed = {"DRAFT", "APPLIED", "VERIFIED", "ARCHIVED"}
+    invalid = [status for status in statuses if status not in allowed]
+    require(not invalid, "Invalid RFC status: " + ", ".join(invalid))
+    validate_development_self_test_impact(docs)
+    print(f"RFC artifacts OK: {len(docs)} file(s)")
+
+
+def validate_development_self_test_impact(docs) -> None:
+    for doc in docs:
+        number = rfc_number(doc.name)
+        if number is not None and number < 23:
+            continue
+        text = doc.read_text(encoding="utf-8")
+        if contains_any(text, SELF_TEST_TRIGGER_TERMS):
+            require(
+                contains_any(text, SELF_TEST_IMPACT_TERMS),
+                f"{doc.relative_to(repo_path('.')).as_posix()} must include Development Self-Test Impact when RFC changes entry/exit, runtime, gates, handoff, or blockers",
+            )
+
+
+def rfc_number(file_name: str) -> int | None:
+    match = re.match(r"^RFC[_-](\d+)", file_name, re.IGNORECASE)
+    return int(match.group(1)) if match else None
+
+
+if __name__ == "__main__":
+    run_main(main)

package/assets/tools/validate_task_docs.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+from harness_utils import contains_any, read_text, repo_path, require, run_main
+
+
+RUNNABLE_ENTRY_EXIT_TERMS = [
+    "runnable entry/exit",
+    "entry/exit",
+    "entry points",
+    "entry point",
+    "可运行入口/出口",
+    "入口/出口",
+    "not applicable",
+]
+
+
+def main() -> None:
+    index = read_text(".docs/INDEX.md")
+    docs_root = repo_path(".docs/04_implementation")
+    docs = sorted(
+        path for path in docs_root.rglob("*.md")
+        if path.name != "overview.md"
+    )
+    if not docs:
+        print("Implementation docs OK: no implementation docs yet")
+        return
+    for path in docs:
+        relative = path.relative_to(repo_path(".")).as_posix()
+        doc = relative if relative.startswith(".") else f".{relative}"
+        index_path = doc.removeprefix(".docs/")
+        require(doc in index or index_path in index, f".docs/INDEX.md does not link implementation doc: {doc}")
+        text = read_text(doc)
+        require(
+            contains_any(text, RUNNABLE_ENTRY_EXIT_TERMS),
+            f"Implementation doc must include Runnable Entry/Exit facts or explicit Not applicable: {doc}",
+        )
+    print(f"Implementation docs OK: {len(docs)} implementation doc(s)")
+
+
+if __name__ == "__main__":
+    run_main(main)

package/assets/tools/validate_test_plan.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+from harness_utils import (
+    changed_files,
+    contains_any,
+    load_lifecycle,
+    load_plan,
+    repo_path,
+    read_text,
+    require,
+    run_main,
+    testing_boundary_errors_for_changed_files,
+    validate_plan_contract,
+)
+
+TEST_REPORT_PATH = ".docs/07_test/TEST_REPORT.md"
+PLACEHOLDER_TERMS = ["pending", "tbd", "todo", "待填", "待补", "placeholder"]
+MISSING_READINESS_TERMS = [
+    "missing entry",
+    "missing exit",
+    "missing runnable",
+    "missing development evidence",
+    "no runnable",
+    "no entry",
+    "no exit",
+    "入口缺失",
+    "出口缺失",
+    "缺少入口",
+    "缺少出口",
+    "缺少 development evidence",
+    "尚未交付",
+    "未交付",
+    "不存在",
+    "not deployed",
+    "not initialized",
+    "local only",
+    "localhost only",
+    "fake adapter",
+    "fake send",
+    "未部署",
+    "未初始化",
+    "只在本地",
+    "仅本地",
+    "本地跑通",
+]
+
+
+def read_test_report() -> tuple[str, str]:
+    require(
+        repo_path(TEST_REPORT_PATH).exists(),
+        f"Missing test report: expected executed evidence at {TEST_REPORT_PATH}",
+    )
+    return read_text(TEST_REPORT_PATH), TEST_REPORT_PATH
+
+
+def main() -> None:
+    validate_plan_contract(load_plan(), allow_open=False)
+    text, source = read_test_report()
+    require(
+        not contains_any(text, PLACEHOLDER_TERMS),
+        "Test report must contain executed evidence, not pending/TBD/TODO/placeholder content",
+    )
+    require(contains_any(text, ["matrix", "矩阵"]), "Test report must include a test matrix")
+    require(contains_any(text, ["regression", "回归"]), "Test report must include regression evidence")
+    require(contains_any(text, ["coverage gap", "覆盖缺口", "gap"]), "Test report must include coverage gaps")
+    require(
+        contains_any(text, ["entry/exit", "entrypoint", "入口", "出口", "runnable", "可运行"]),
+        "Test report must state existing runnable entry/exit coverage or blocker status",
+    )
+    require(contains_any(text, ["pass", "blocked", "通过", "阻塞"]), "Test report must include PASS/BLOCKED decision")
+    if contains_any(text, ["decision\n\npass", "decision: pass", "decision: `pass`", "final decision: pass"]):
+        require(
+            not contains_any(text, MISSING_READINESS_TERMS),
+            "Test report cannot PASS while runnable entry/exit or Development Evidence is missing; use BLOCKED with recovery conditions",
+        )
+    if load_lifecycle().get("current_phase") == "TESTING":
+        for error in testing_boundary_errors_for_changed_files(changed_files()):
+            require(False, error)
+    print(f"Test report OK: {source}")
+
+
+if __name__ == "__main__":
+    run_main(main)

package/dist/lib/config.js

@@ -15,6 +15,7 @@ export function defaultConfig(root) {
             { path: harnessPath(root, "pjsdlc_managed", "templates"), strategy: "managed" },
             { path: harnessPath(root, "pjsdlc_managed", "policies"), strategy: "merge-with-local" },
             { path: harnessPath(root, "pjsdlc_managed", "make", "sdlc-harness.mk"), strategy: "managed" },
+            { path: "tools", strategy: "managed" },
             { path: ".github/workflows/harness.yml", strategy: "create-if-missing" }
         ],
         local_overrides: [

package/dist/lib/migrations.js

@@ -162,6 +162,9 @@ function migrateManagedFiles(managedFiles, root) {
             migrated.unshift(makefileEntry);
         }
     }
+    if (!seen.has("tools")) {
+        push({ path: "tools", strategy: "managed" });
+    }
     if (!seen.has(".github/workflows/harness.yml")) {
         push({ path: ".github/workflows/harness.yml", strategy: "create-if-missing" });
     }

package/dist/lib/sync-engine.js

@@ -49,6 +49,10 @@ async function syncManagedFile(projectRoot, root, managedFile, report) {
         await syncFile(packageAssetPath("make", "sdlc-harness.mk"), destination, report, "skip-if-missing");
         return;
     }
+    if (managedFile.path === "tools") {
+        await syncTree(packageAssetPath("tools"), destination, report);
+        return;
+    }
     if (managedFile.path === ".github/workflows/harness.yml") {
         await syncGithubWorkflow(packageAssetPath("github", "harness.yml"), destination, managedFile.path, report);
         return;