prizmkit 1.1.153 → 1.1.155

package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py

@@ -6,15 +6,19 @@ import copy
 import json
 import re
 from dataclasses import dataclass, field
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import Any, Mapping
 
-from .test_result import valid_test_artifact_pair
+from .test_result import (
+    valid_legacy_test_artifact_pair,
+    valid_test_artifact_pair,
+)
 
 VALID_CHECKPOINT_STATUSES = {"pending", "in_progress", "completed", "skipped", "failed"}
 TERMINAL_STEP_STATUSES = {"completed", "skipped"}
 STEP_ID_PATTERN = re.compile(r"^S[0-9]+$")
 MAX_OUTER_REPAIR_ROUNDS = 3
+_COMMIT_HASH_PATTERN = re.compile(r"^[0-9a-fA-F]{40,64}$")
 
 REVIEW_RESULTS = {"REVIEW_PASS", "REVIEW_NEEDS_FIXES"}
 TEST_RESULTS = {"TEST_PASS", "TEST_NEEDS_FIXES", "TEST_BLOCKED"}
@@ -32,6 +36,8 @@ VALID_STAGE_RESULTS = (
 )
 STAGE_RESULT_OWNERS = {
     "prizmkit-plan": PLAN_RESULTS,
+    "context-snapshot-and-plan": PLAN_RESULTS,
+    "bug-diagnosis-and-plan": PLAN_RESULTS,
     "prizmkit-implement": IMPLEMENT_RESULTS,
     "prizmkit-code-review": REVIEW_RESULTS,
     "prizmkit-test": TEST_RESULTS,
@@ -49,6 +55,15 @@ WORKFLOW_STAGE_SKILLS = {
 SKILL_WORKFLOW_STAGES = {
     skill: stage for stage, skill in WORKFLOW_STAGE_SKILLS.items()
 }
+SKILL_WORKFLOW_STAGES.update({
+    "context-snapshot-and-plan": "plan",
+    "bug-diagnosis-and-plan": "plan",
+})
+FAMILY_PLAN_SKILLS = {
+    "feature-pipeline": "context-snapshot-and-plan",
+    "bugfix-pipeline": "bug-diagnosis-and-plan",
+    "refactor-pipeline": "prizmkit-plan",
+}
 VALID_TERMINAL_STATUSES = {"WORKFLOW_COMPLETED", "WORKFLOW_BLOCKED"}
 VALID_REPAIR_SCOPES = {
     "production",
@@ -63,7 +78,7 @@ SEMANTIC_STATE_KEYS = {
     "bugfix-pipeline": "bugfix_state",
     "refactor-pipeline": "refactor_state",
 }
-FAMILY_REQUIRED_STAGES = {
+LEGACY_FAMILY_REQUIRED_STAGES = {
     "feature-pipeline": (
         "prizmkit-implement",
         "prizmkit-code-review",
@@ -91,6 +106,34 @@ FAMILY_REQUIRED_STAGES = {
     ),
 }
 
+FAMILY_REQUIRED_STAGES = {
+    "feature-pipeline": (
+        "prizmkit-implement",
+        "prizmkit-code-review",
+        "prizmkit-test",
+        "completion-summary",
+        "prizmkit-retrospective",
+        "prizmkit-committer",
+    ),
+    "bugfix-pipeline": (
+        "prizmkit-implement",
+        "prizmkit-code-review",
+        "prizmkit-test",
+        "bug-report",
+        "prizmkit-retrospective",
+        "prizmkit-committer",
+    ),
+    "refactor-pipeline": (
+        "prizmkit-implement",
+        "prizmkit-code-review",
+        "prizmkit-test",
+        "refactor-report",
+        "completion-summary",
+        "prizmkit-retrospective",
+        "prizmkit-committer",
+    ),
+}
+
 
 @dataclass(frozen=True)
 class CheckpointStep:
@@ -128,10 +171,13 @@ class SemanticCheckpoint:
     repair_round: int = 0
     blocked_reason: str | None = None
     terminal_status: str | None = None
+    runtime_base_head: str = ""
+    runtime_commit_hash: str = ""
     sequence_valid: bool = False
     test_result_valid: bool = False
     artifacts_valid: bool = False
     completion_ready: bool = False
+    commit_ready: bool = False
     complete: bool = False
     blocked: bool = False
     error_code: str = ""
@@ -147,6 +193,9 @@ class SemanticCheckpoint:
             "repair_round": self.repair_round,
             "blocked_reason": self.blocked_reason,
             "terminal_status": self.terminal_status,
+            "runtime_base_head": self.runtime_base_head,
+            "runtime_commit_hash": self.runtime_commit_hash,
+            "commit_ready": self.commit_ready,
         }
 
 
@@ -200,6 +249,11 @@ class CheckpointState:
         """Return whether this checkpoint authoritatively proves task completion."""
         return self.valid and self.semantic.complete
 
+    @property
+    def semantic_commit_ready(self) -> bool:
+        """Return whether the runtime may execute the prepared local commit."""
+        return self.valid and self.semantic.commit_ready
+
     @property
     def semantic_blocked(self) -> bool:
         """Return whether this checkpoint has a deterministic blocked terminal state."""
@@ -591,8 +645,21 @@ def _derive_semantic_state(
         return _semantic_error(workflow_type, current_step, "invalid_semantic_state", f"{state_key} must be an object")
 
     required = FAMILY_REQUIRED_STAGES.get(workflow_type)
-    sequence_error = _required_sequence_error(steps, required) if required else "unsupported workflow family"
+    canonical_sequence_error = (
+        _required_sequence_error(steps, required)
+        if required else "unsupported workflow family"
+    )
+    if not canonical_sequence_error:
+        canonical_sequence_error = _configured_verification_sequence_error(steps)
+    legacy_required = LEGACY_FAMILY_REQUIRED_STAGES.get(workflow_type)
+    legacy_sequence_valid = bool(
+        canonical_sequence_error
+        and legacy_required
+        and not _required_sequence_error(steps, legacy_required)
+    )
+    sequence_error = "" if legacy_sequence_valid else canonical_sequence_error
     sequence_valid = not sequence_error
+    canonical_sequence_valid = not canonical_sequence_error
 
     repair_round = raw_state.get("repair_round", 0)
     if isinstance(repair_round, bool) or not isinstance(repair_round, int) or not 0 <= repair_round <= MAX_OUTER_REPAIR_ROUNDS:
@@ -629,14 +696,61 @@ def _derive_semantic_state(
     terminal_status = raw_state.get("terminal_status")
     if terminal_status is not None and terminal_status not in VALID_TERMINAL_STATUSES:
         return _semantic_error(workflow_type, current_step, "invalid_terminal_status", "terminal_status is not recognized")
+    runtime_base_head = str(raw_state.get("runtime_base_head") or "").strip()
+    runtime_commit_hash = str(raw_state.get("runtime_commit_hash") or "").strip()
+    runtime_receipt_valid = bool(
+        _COMMIT_HASH_PATTERN.fullmatch(runtime_base_head)
+        and _COMMIT_HASH_PATTERN.fullmatch(runtime_commit_hash)
+        and runtime_base_head.lower() != runtime_commit_hash.lower()
+    )
+    if (runtime_base_head or runtime_commit_hash) and not runtime_receipt_valid:
+        return _semantic_error(
+            workflow_type,
+            current_step,
+            "invalid_runtime_commit_receipt",
+            "Runtime commit receipt requires distinct valid base and commit hashes",
+        )
     blocked_reason = raw_state.get("blocked_reason")
     if blocked_reason is not None and (not isinstance(blocked_reason, str) or not blocked_reason.strip()):
         return _semantic_error(workflow_type, current_step, "invalid_blocked_reason", "blocked_reason must be a non-empty string")
     if terminal_status == "WORKFLOW_BLOCKED" and not blocked_reason:
         return _semantic_error(workflow_type, current_step, "missing_blocked_reason", "WORKFLOW_BLOCKED requires blocked_reason")
+    if blocked_reason and terminal_status == "WORKFLOW_COMPLETED":
+        return _semantic_error(
+            workflow_type,
+            current_step,
+            "completed_workflow_has_blocked_reason",
+            "WORKFLOW_COMPLETED cannot retain blocked_reason",
+        )
+    if blocked_reason and terminal_status != "WORKFLOW_BLOCKED":
+        return _semantic_error(
+            workflow_type,
+            current_step,
+            "blocked_reason_without_blocked_terminal",
+            "blocked_reason requires terminal_status=WORKFLOW_BLOCKED",
+        )
 
     review_step = _single_step(steps, "prizmkit-code-review")
     test_step = _single_step(steps, "prizmkit-test")
+    plan_step = _single_step(steps, FAMILY_PLAN_SKILLS.get(workflow_type, ""))
+    implement_step = _single_step(steps, "prizmkit-implement")
+    plan_valid = bool(
+        plan_step
+        and implement_step
+        and plan_step.index < implement_step.index
+        and plan_step.status == "completed"
+        and plan_step.stage_result == "PLAN_READY"
+    )
+    configured_manual_valid = all(
+        step.status == "completed"
+        for step in steps
+        if step.skill == "manual-verification"
+    )
+    implementation_valid = bool(
+        implement_step
+        and implement_step.status == "completed"
+        and implement_step.stage_result == "IMPLEMENTED"
+    )
     review_valid = bool(
         review_step
         and review_step.status == "completed"
@@ -647,18 +761,65 @@ def _derive_semantic_state(
         and test_step.status == "completed"
         and test_step.stage_result == "TEST_PASS"
     )
-    all_required_completed = bool(required) and all(
+    effective_required = legacy_required if legacy_sequence_valid else required
+    all_required_completed = bool(effective_required) and all(
         (step := _single_step(steps, skill)) is not None and step.status == "completed"
-        for skill in required
+        for skill in effective_required
     )
     artifacts_valid = all(
         _required_step_artifacts_valid(step, checkpoint_path, project_root)
         for step in steps
         if step.status == "completed"
     )
+    completion_artifacts_valid = artifacts_valid or (
+        legacy_sequence_valid
+        and all(
+            _required_step_artifacts_valid(
+                step,
+                checkpoint_path,
+                project_root,
+                allow_legacy_test=True,
+            )
+            for step in steps
+            if step.status == "completed"
+        )
+    )
+    retrospective_step = _single_step(steps, "prizmkit-retrospective")
+    retrospective_valid = bool(
+        retrospective_step
+        and retrospective_step.status == "completed"
+        and retrospective_step.stage_result == "RETRO_COMPLETE"
+    )
+    committer_step = _single_step(steps, "prizmkit-committer")
+    committed_valid = bool(
+        committer_step
+        and committer_step.status == "completed"
+        and committer_step.stage_result == "COMMITTED"
+    )
+    precommit_required = tuple(
+        skill for skill in (required or ()) if skill != "prizmkit-committer"
+    )
+    all_precommit_completed = bool(precommit_required) and all(
+        (step := _single_step(steps, skill)) is not None and step.status == "completed"
+        for skill in precommit_required
+    )
+    commit_request_valid = bool(
+        committer_step
+        and committer_step.status == "in_progress"
+        and committer_step.stage_result == "COMMIT_PENDING"
+        and _required_step_artifacts_valid(committer_step, checkpoint_path, project_root)
+    )
+    commit_ready = (
+        canonical_sequence_valid and plan_valid and configured_manual_valid
+        and all_precommit_completed and implementation_valid and review_valid
+        and test_result_valid and retrospective_valid and artifacts_valid
+        and commit_request_valid and terminal_status is None
+    )
     completion_ready = (
-        sequence_valid and all_required_completed and review_valid
-        and test_result_valid and artifacts_valid
+        sequence_valid and all_required_completed and implementation_valid
+        and review_valid and test_result_valid and retrospective_valid
+        and committed_valid and completion_artifacts_valid
+        and (legacy_sequence_valid or runtime_receipt_valid)
     )
     blocked = terminal_status == "WORKFLOW_BLOCKED" and bool(blocked_reason)
     complete = completion_ready and terminal_status == "WORKFLOW_COMPLETED" and not blocked
@@ -705,10 +866,13 @@ def _derive_semantic_state(
         repair_round=repair_round,
         blocked_reason=blocked_reason,
         terminal_status=terminal_status,
+        runtime_base_head=runtime_base_head,
+        runtime_commit_hash=runtime_commit_hash,
         sequence_valid=sequence_valid,
         test_result_valid=test_result_valid,
-        artifacts_valid=artifacts_valid,
+        artifacts_valid=completion_artifacts_valid,
         completion_ready=completion_ready,
+        commit_ready=commit_ready,
         complete=complete,
         blocked=blocked,
         error_code=error_code,
@@ -733,16 +897,34 @@ def _required_sequence_error(
     return ""
 
 
+def _configured_verification_sequence_error(
+    steps: tuple[CheckpointStep, ...],
+) -> str:
+    """Require configured Browser/Manual checks between Review and Test."""
+    review = _single_step(steps, "prizmkit-code-review")
+    test = _single_step(steps, "prizmkit-test")
+    if review is None or test is None:
+        return ""
+    for skill in ("browser-verification", "manual-verification"):
+        matches = [step for step in steps if step.skill == skill]
+        if len(matches) > 1:
+            return f"Expected at most one configured stage {skill}"
+        if matches and not (review.index < matches[0].index < test.index):
+            return f"Configured stage {skill} must run after review and before test"
+    return ""
+
+
 def _single_step(steps: tuple[CheckpointStep, ...], skill: str) -> CheckpointStep | None:
     matches = [step for step in steps if step.skill == skill]
     return matches[0] if len(matches) == 1 else None
 
 
-
 def _required_step_artifacts_valid(
     step: CheckpointStep,
     checkpoint_path: Path | None,
     project_root: Path | None,
+    *,
+    allow_legacy_test: bool = False,
 ) -> bool:
     """Validate declared artifacts, including semantic test terminal output."""
     if step.skill == "prizmkit-test":
@@ -755,11 +937,38 @@ def _required_step_artifacts_valid(
         result_path = (root / results[0]).resolve()
         if not _is_within_root(report_path, root) or not _is_within_root(result_path, root):
             return False
-        return valid_test_artifact_pair(
+        validator = (
+            valid_legacy_test_artifact_pair
+            if allow_legacy_test
+            else valid_test_artifact_pair
+        )
+        return validator(
             report_path,
             result_path,
             required_result="TEST_PASS",
         )
+    if step.skill == "prizmkit-code-review":
+        return _valid_review_artifact(step, checkpoint_path, project_root)
+    if step.skill == "prizmkit-retrospective":
+        return _valid_retrospective_artifact(step, checkpoint_path, project_root)
+    if (
+        step.skill == "prizmkit-committer"
+        and step.status == "completed"
+        and step.stage_result == "COMMITTED"
+    ):
+        requests = tuple(
+            artifact
+            for artifact in step.required_artifacts
+            if artifact.endswith("/runtime-commit-request.json")
+        )
+        if not step.required_artifacts:
+            return True
+        if len(requests) != 1:
+            return False
+        durable = tuple(
+            artifact for artifact in step.required_artifacts if artifact not in requests
+        )
+        return _required_artifact_paths_exist(durable, checkpoint_path, project_root)
     return _required_artifacts_exist(step, checkpoint_path, project_root)
 
 
@@ -768,23 +977,154 @@ def _required_artifacts_exist(
     checkpoint_path: Path | None,
     project_root: Path | None,
 ) -> bool:
-    if not step.required_artifacts:
+    return _required_artifact_paths_exist(
+        step.required_artifacts,
+        checkpoint_path,
+        project_root,
+    )
+
+
+def _required_artifact_paths_exist(
+    artifacts: tuple[str, ...],
+    checkpoint_path: Path | None,
+    project_root: Path | None,
+) -> bool:
+    if not artifacts:
         return True
     import glob
 
     root = (project_root or _infer_project_root(checkpoint_path)).resolve()
-    for artifact in step.required_artifacts:
+    for artifact in artifacts:
         candidate = (root / artifact).resolve()
         if not _is_within_root(candidate, root):
             return False
         if glob.has_magic(str(candidate)):
             if not glob.glob(str(candidate)):
                 return False
-        elif not candidate.exists():
-            return False
+        else:
+            try:
+                if not candidate.exists():
+                    return False
+                if candidate.is_file() and candidate.stat().st_size == 0:
+                    return False
+            except OSError:
+                return False
     return True
 
 
+def _valid_review_artifact(
+    step: CheckpointStep,
+    checkpoint_path: Path | None,
+    project_root: Path | None,
+) -> bool:
+    reports = [item for item in step.required_artifacts if item.endswith("/review-report.md")]
+    if not reports:
+        return _required_artifacts_exist(step, checkpoint_path, project_root)
+    if len(reports) != 1 or not _required_artifacts_exist(step, checkpoint_path, project_root):
+        return False
+    root = (project_root or _infer_project_root(checkpoint_path)).resolve()
+    report = (root / reports[0]).resolve()
+    if not _is_within_root(report, root):
+        return False
+    try:
+        text = report.read_text(encoding="utf-8")
+    except (OSError, UnicodeError):
+        return False
+    final_sections = re.findall(
+        r"(?ms)^## Final Result\s*$\n(?P<body>.*?)(?=^## |\Z)",
+        text,
+    )
+    if len(final_sections) != 1:
+        return False
+    verdicts = re.findall(r"(?m)^- Verdict:\s*(PASS|NEEDS_FIXES)\s*$", final_sections[0])
+    return verdicts == ["PASS"]
+
+
+def _valid_retrospective_artifact(
+    step: CheckpointStep,
+    checkpoint_path: Path | None,
+    project_root: Path | None,
+) -> bool:
+    results = [
+        item for item in step.required_artifacts
+        if item.endswith("/retrospective-result.json")
+    ]
+    if not results:
+        return _required_artifacts_exist(step, checkpoint_path, project_root)
+    if len(results) != 1 or not _required_artifacts_exist(step, checkpoint_path, project_root):
+        return False
+    root = (project_root or _infer_project_root(checkpoint_path)).resolve()
+    result_path = (root / results[0]).resolve()
+    if not _is_within_root(result_path, root):
+        return False
+    try:
+        value = json.loads(result_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return False
+    expected_keys = {
+        "schema_version",
+        "outcome",
+        "result",
+        "reason",
+        "change_paths",
+        "documentation_paths",
+        "validation",
+    }
+    return bool(
+        isinstance(value, dict)
+        and set(value) == expected_keys
+        and value.get("schema_version") == 1
+        and value.get("outcome") == "RETRO_COMPLETE"
+        and value.get("result") in {"DOCS_UPDATED", "NO_DOC_CHANGE"}
+        and isinstance(value.get("reason"), str)
+        and value["reason"].strip()
+        and isinstance(value.get("change_paths"), list)
+        and all(_valid_retrospective_change_path(path) for path in value["change_paths"])
+        and isinstance(value.get("documentation_paths"), list)
+        and all(
+            _valid_retrospective_documentation_path(path)
+            for path in value["documentation_paths"]
+        )
+        and isinstance(value.get("validation"), list)
+        and all(isinstance(item, str) and item.strip() for item in value["validation"])
+        and (
+            value.get("result") != "DOCS_UPDATED"
+            or (
+                bool(value["documentation_paths"])
+                and bool(value["validation"])
+            )
+        )
+    )
+
+
+def _valid_retrospective_documentation_path(value: object) -> bool:
+    if not isinstance(value, str) or not value.strip() or "\\" in value:
+        return False
+    raw_parts = value.split("/")
+    if any(part in {"", ".", ".."} for part in raw_parts):
+        return False
+    path = PurePosixPath(value)
+    return bool(
+        not path.is_absolute()
+        and len(raw_parts) >= 3
+        and raw_parts[:2] == [".prizmkit", "prizm-docs"]
+        and path.suffix == ".prizm"
+    )
+
+
+def _valid_retrospective_change_path(value: object) -> bool:
+    if not isinstance(value, str) or not value.strip() or "\\" in value:
+        return False
+    raw_parts = value.split("/")
+    if any(part in {"", ".", ".."} for part in raw_parts):
+        return False
+    path = PurePosixPath(value)
+    return bool(
+        not path.is_absolute()
+        and raw_parts[0] != ".prizmkit"
+    )
+
+
 def _is_within_root(path: Path, root: Path) -> bool:
     try:
         path.relative_to(root)