prizmkit 1.1.130 → 1.1.131

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.130",
-  "bundledAt": "2026-07-15T08:17:59.816Z",
-  "bundledFrom": "81d54a2"
+  "frameworkVersion": "1.1.131",
+  "bundledAt": "2026-07-18T08:21:47.386Z",
+  "bundledFrom": "c1378b1"
 }

package/bundled/dev-pipeline/.env.example

@@ -30,7 +30,7 @@
                               # Unset = auto-detect from estimated_complexity
 
 # ─── Refactor Pipeline Only ──────────────────────────────────────────
-# STRICT_BEHAVIOR_CHECK=1    # Run full test suite after each refactor (1=on, 0=off)
+# STRICT_BEHAVIOR_CHECK=1    # Enable strict behavior-preservation gates for refactor tasks (1=on, 0=off)
 
 # ─── Branch Management ────────────────────────────────────────────────
 # AUTO_PUSH=0                # Auto-push to remote after successful task (0=off, 1=on)

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

@@ -1,9 +1,11 @@
-"""Shared workflow-checkpoint.json reader and validator."""
+"""Shared workflow-checkpoint.json reader and semantic validator."""
 
 from __future__ import annotations
 
 import json
 import re
+import subprocess
+import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Mapping
@@ -11,6 +13,57 @@ from typing import Any, Mapping
 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
+
+REVIEW_RESULTS = {"REVIEW_PASS", "REVIEW_NEEDS_FIXES"}
+TEST_RESULTS = {"TEST_PASS", "TEST_FAIL", "TEST_BLOCKED"}
+VALID_STAGE_RESULTS = REVIEW_RESULTS | TEST_RESULTS
+VALID_TERMINAL_STATUSES = {"WORKFLOW_COMPLETED", "WORKFLOW_BLOCKED"}
+VALID_REPAIR_SCOPES = {
+    "production",
+    "runtime",
+    "schema",
+    "dependency",
+    "public-interface",
+    "test-infrastructure",
+}
+SEMANTIC_STATE_KEYS = {
+    "feature-pipeline": "feature_state",
+    "bugfix-pipeline": "bugfix_state",
+    "refactor-pipeline": "refactor_state",
+}
+FAMILY_REQUIRED_STAGES = {
+    "feature-pipeline": (
+        "prizmkit-implement",
+        "prizmkit-code-review",
+        "prizmkit-test",
+        "prizmkit-retrospective",
+        "prizmkit-committer",
+        "completion-summary",
+    ),
+    "bugfix-pipeline": (
+        "prizmkit-implement",
+        "prizmkit-code-review",
+        "prizmkit-test",
+        "prizmkit-retrospective",
+        "prizmkit-committer",
+        "bug-report",
+    ),
+    "refactor-pipeline": (
+        "prizmkit-implement",
+        "prizmkit-code-review",
+        "prizmkit-test",
+        "prizmkit-retrospective",
+        "prizmkit-committer",
+        "refactor-report",
+        "completion-summary",
+    ),
+}
+EVIDENCE_FILENAMES = {
+    "manifest": "manifest.json",
+    "verdict": "verdict.json",
+    "validation": "validation.json",
+}
 
 
 @dataclass(frozen=True)
@@ -23,6 +76,8 @@ class CheckpointStep:
     status: str
     depends_on: str | None = None
     required_artifacts: tuple[str, ...] = ()
+    stage_result: str | None = None
+    authoritative_evidence_paths: Mapping[str, str | None] = field(default_factory=dict)
     index: int = 0
 
     @property
@@ -36,6 +91,42 @@ class CheckpointStep:
         return f"{self.id} ({self.skill})"
 
 
+@dataclass(frozen=True)
+class SemanticCheckpoint:
+    """Provider-neutral L4 state shared by runners, status, and recovery."""
+
+    workflow_type: str = ""
+    current_stage: str | None = None
+    next_stage: str | None = None
+    stage_result: str | None = None
+    repair_scope: str | None = None
+    repair_round: int = 0
+    authoritative_evidence_paths: Mapping[str, str | None] = field(default_factory=dict)
+    blocked_reason: str | None = None
+    terminal_status: str | None = None
+    sequence_valid: bool = False
+    evidence_valid: bool = False
+    artifacts_valid: bool = False
+    completion_ready: bool = False
+    complete: bool = False
+    blocked: bool = False
+    error_code: str = ""
+    error_message: str = ""
+
+    def as_dict(self) -> dict[str, object]:
+        """Return the additive runtime-state representation."""
+        return {
+            "current_stage": self.current_stage,
+            "next_stage": self.next_stage,
+            "stage_result": self.stage_result,
+            "repair_scope": self.repair_scope,
+            "repair_round": self.repair_round,
+            "authoritative_evidence_paths": dict(self.authoritative_evidence_paths),
+            "blocked_reason": self.blocked_reason,
+            "terminal_status": self.terminal_status,
+        }
+
+
 @dataclass(frozen=True)
 class CheckpointState:
     """Result of loading and validating one workflow checkpoint."""
@@ -50,6 +141,7 @@ class CheckpointState:
     all_completed: bool = False
     duplicate_skills: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
     raw_data: Mapping[str, Any] | None = None
+    semantic: SemanticCheckpoint = field(default_factory=SemanticCheckpoint)
 
     @property
     def current_step_name(self) -> str:
@@ -69,17 +161,38 @@ class CheckpointState:
 
     @property
     def cursor_signature(self) -> str:
-        """Return a stable progress fingerprint cursor string."""
+        """Return a stable semantic progress fingerprint cursor string."""
         if not self.valid:
             return f"invalid:{self.error_code}" if self.exists else ""
-        if self.all_completed:
-            return "complete"
+        if self.semantic.complete:
+            return "complete:WORKFLOW_COMPLETED"
+        if self.semantic.blocked:
+            return f"blocked:{self.semantic.blocked_reason or 'unspecified'}"
         if self.current_step is None:
-            return ""
+            return "complete"
         return f"{self.current_step.id}:{self.current_step.skill}:{self.current_step.status}"
 
+    @property
+    def semantic_complete(self) -> bool:
+        """Return whether this checkpoint authoritatively proves task completion."""
+        return self.valid and self.semantic.complete
 
-def load_checkpoint_state(path: str | Path | None) -> CheckpointState:
+    @property
+    def semantic_blocked(self) -> bool:
+        """Return whether this checkpoint has a deterministic blocked terminal state."""
+        return self.valid and self.semantic.blocked
+
+    @property
+    def semantic_snapshot(self) -> dict[str, object]:
+        """Return the normalized state persisted by runtime consumers."""
+        return self.semantic.as_dict()
+
+
+def load_checkpoint_state(
+    path: str | Path | None,
+    *,
+    project_root: str | Path | None = None,
+) -> CheckpointState:
     """Load and validate one workflow-checkpoint.json file."""
     checkpoint_path = Path(path) if path is not None else None
     if checkpoint_path is None or not checkpoint_path.is_file():
@@ -90,7 +203,12 @@ def load_checkpoint_state(path: str | Path | None) -> CheckpointState:
         return _invalid(checkpoint_path, True, "malformed_json", f"Malformed checkpoint JSON: {exc}")
     except OSError as exc:
         return _invalid(checkpoint_path, True, "read_error", f"Cannot read checkpoint: {exc}")
-    return validate_checkpoint_data(data, path=checkpoint_path, exists=True)
+    return validate_checkpoint_data(
+        data,
+        path=checkpoint_path,
+        exists=True,
+        project_root=project_root,
+    )
 
 
 def validate_checkpoint_data(
@@ -98,8 +216,9 @@ def validate_checkpoint_data(
     *,
     path: str | Path | None = None,
     exists: bool = True,
+    project_root: str | Path | None = None,
 ) -> CheckpointState:
-    """Validate already-loaded checkpoint data."""
+    """Validate already-loaded checkpoint data and derive semantic L4 state."""
     checkpoint_path = Path(path) if path is not None else None
     if not isinstance(data, dict):
         return _invalid(checkpoint_path, exists, "invalid_root", "Checkpoint root must be an object")
@@ -156,6 +275,15 @@ def validate_checkpoint_data(
         if not isinstance(artifacts, list) or any(not isinstance(item, str) for item in artifacts):
             return _invalid(checkpoint_path, exists, "invalid_required_artifacts", f"Step {step_id} has invalid required_artifacts", data)
 
+        stage_result = raw_step.get("stage_result")
+        if stage_result is not None and stage_result not in VALID_STAGE_RESULTS:
+            return _invalid(checkpoint_path, exists, "invalid_stage_result", f"Step {step_id} has invalid stage_result", data)
+        evidence = raw_step.get("authoritative_evidence_paths", {})
+        if evidence is None:
+            evidence = {}
+        if not _valid_evidence_mapping(evidence):
+            return _invalid(checkpoint_path, exists, "invalid_evidence_paths", f"Step {step_id} has invalid evidence paths", data)
+
         step = CheckpointStep(
             id=step_id,
             skill=skill,
@@ -163,6 +291,8 @@ def validate_checkpoint_data(
             status=str(status),
             depends_on=depends_on,
             required_artifacts=tuple(artifacts),
+            stage_result=stage_result,
+            authoritative_evidence_paths=dict(evidence),
             index=index,
         )
         steps.append(step)
@@ -186,12 +316,23 @@ def validate_checkpoint_data(
                 data,
             )
 
+    progress_error = _progress_error(steps)
+    if progress_error:
+        return _invalid(checkpoint_path, exists, "invalid_step_progress", progress_error, data)
+
     duplicate_skills = {
         skill: tuple(ids)
         for skill, ids in skill_to_ids.items()
         if len(ids) > 1
     }
     current_step = next((step for step in steps if step.status not in TERMINAL_STEP_STATUSES), None)
+    semantic = _derive_semantic_state(
+        data,
+        tuple(steps),
+        current_step,
+        checkpoint_path,
+        Path(project_root) if project_root is not None else None,
+    )
     return CheckpointState(
         path=checkpoint_path,
         exists=exists,
@@ -201,6 +342,7 @@ def validate_checkpoint_data(
         all_completed=current_step is None,
         duplicate_skills=duplicate_skills,
         raw_data=data,
+        semantic=semantic,
     )
 
 
@@ -224,6 +366,7 @@ def checkpoint_cursor(checkpoint: Mapping[str, Any] | None) -> dict[str, object]
             "failed": [],
             "first_cursor": f"(invalid checkpoint: {state.error_code})",
             "current_step_name": "",
+            "semantic": state.semantic_snapshot,
         }
 
     grouped: dict[str, list[str]] = {
@@ -250,6 +393,7 @@ def checkpoint_cursor(checkpoint: Mapping[str, Any] | None) -> dict[str, object]
         "failed": grouped["failed"],
         "first_cursor": first_cursor,
         "current_step_name": state.current_step_name,
+        "semantic": state.semantic_snapshot,
     }
 
 
@@ -266,6 +410,298 @@ def invalid_existing_checkpoint(path: str | Path | None) -> CheckpointState | No
     return None
 
 
+def semantic_state_key(workflow_type: str) -> str:
+    """Return the family-owned L4 semantic metadata key."""
+    return SEMANTIC_STATE_KEYS.get(workflow_type, "l4_state")
+
+
+def _progress_error(steps: list[CheckpointStep]) -> str:
+    active_seen = False
+    for step in steps:
+        if step.status in TERMINAL_STEP_STATUSES:
+            if active_seen:
+                return f"Step {step.id} is terminal after an unfinished predecessor"
+        else:
+            active_seen = True
+    return ""
+
+
+def _derive_semantic_state(
+    data: Mapping[str, Any],
+    steps: tuple[CheckpointStep, ...],
+    current_step: CheckpointStep | None,
+    checkpoint_path: Path | None,
+    project_root: Path | None,
+) -> SemanticCheckpoint:
+    workflow_type = str(data.get("workflow_type") or "")
+    state_key = semantic_state_key(workflow_type)
+    raw_state = data.get(state_key, {})
+    if not isinstance(raw_state, dict):
+        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"
+    sequence_valid = not 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:
+        return _semantic_error(workflow_type, current_step, "invalid_repair_round", "repair_round must be an integer from 0 through 3")
+    repair_scope = raw_state.get("repair_scope")
+    if repair_scope is not None and repair_scope not in VALID_REPAIR_SCOPES:
+        return _semantic_error(workflow_type, current_step, "invalid_repair_scope", "repair_scope is not a safe shared scope")
+    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")
+    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")
+
+    review_step = _single_step(steps, "prizmkit-code-review")
+    test_step = _single_step(steps, "prizmkit-test")
+    review_valid = bool(
+        review_step
+        and review_step.status == "completed"
+        and review_step.stage_result == "REVIEW_PASS"
+    )
+    evidence_paths = (
+        dict(test_step.authoritative_evidence_paths)
+        if test_step and test_step.authoritative_evidence_paths
+        else dict(raw_state.get("authoritative_evidence_paths") or {})
+    )
+    evidence_valid = bool(
+        test_step
+        and test_step.status == "completed"
+        and test_step.stage_result == "TEST_PASS"
+        and _validate_test_evidence(evidence_paths, checkpoint_path, project_root)
+    )
+    all_required_completed = bool(required) and all(
+        (step := _single_step(steps, skill)) is not None and step.status == "completed"
+        for skill in required
+    )
+    artifacts_valid = all(
+        _required_artifacts_exist(step, checkpoint_path, project_root)
+        for step in steps
+        if step.status == "completed"
+    )
+    completion_ready = (
+        sequence_valid and all_required_completed and review_valid
+        and evidence_valid and artifacts_valid
+    )
+    blocked = terminal_status == "WORKFLOW_BLOCKED" and bool(blocked_reason)
+    complete = completion_ready and terminal_status == "WORKFLOW_COMPLETED" and not blocked
+
+    current_stage = current_step.skill if current_step is not None else None
+    next_stage = current_stage
+    if current_step is not None and current_step.status == "in_progress":
+        later = steps[current_step.index + 1:]
+        next_step = next((step for step in later if step.status not in TERMINAL_STEP_STATUSES), None)
+        next_stage = next_step.skill if next_step is not None else None
+    if terminal_status is not None:
+        current_stage = None
+        next_stage = None
+
+    error_code = ""
+    error_message = ""
+    if sequence_error:
+        error_code = "invalid_stage_sequence"
+        error_message = sequence_error
+    elif all(step.status in TERMINAL_STEP_STATUSES for step in steps) and not completion_ready and not blocked:
+        error_code = "incomplete_semantic_evidence"
+        if not review_valid:
+            error_message = "completed checkpoint lacks REVIEW_PASS on the review stage"
+        elif not evidence_valid:
+            error_message = "completed checkpoint lacks valid TEST_PASS structured evidence"
+        else:
+            error_message = "completed checkpoint lacks mandatory completed stages"
+    elif terminal_status == "WORKFLOW_COMPLETED" and not completion_ready:
+        error_code = "invalid_completed_terminal"
+        error_message = "WORKFLOW_COMPLETED does not have semantic completion evidence"
+
+    return SemanticCheckpoint(
+        workflow_type=workflow_type,
+        current_stage=current_stage,
+        next_stage=next_stage,
+        stage_result=raw_state.get("stage_result"),
+        repair_scope=repair_scope,
+        repair_round=repair_round,
+        authoritative_evidence_paths=evidence_paths,
+        blocked_reason=blocked_reason,
+        terminal_status=terminal_status,
+        sequence_valid=sequence_valid,
+        evidence_valid=evidence_valid,
+        artifacts_valid=artifacts_valid,
+        completion_ready=completion_ready,
+        complete=complete,
+        blocked=blocked,
+        error_code=error_code,
+        error_message=error_message,
+    )
+
+
+def _required_sequence_error(
+    steps: tuple[CheckpointStep, ...],
+    required: tuple[str, ...] | None,
+) -> str:
+    if not required:
+        return ""
+    positions: list[int] = []
+    for skill in required:
+        matches = [step.index for step in steps if step.skill == skill]
+        if len(matches) != 1:
+            return f"Expected exactly one mandatory stage {skill}"
+        positions.append(matches[0])
+    if positions != sorted(positions):
+        return "Mandatory stages are not in the expected family order"
+    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_artifacts_exist(
+    step: CheckpointStep,
+    checkpoint_path: Path | None,
+    project_root: Path | None,
+) -> bool:
+    if not step.required_artifacts:
+        return True
+    import glob
+
+    root = (project_root or _infer_project_root(checkpoint_path)).resolve()
+    for artifact in step.required_artifacts:
+        candidate = root / artifact
+        if glob.has_magic(str(candidate)):
+            if not glob.glob(str(candidate)):
+                return False
+        elif not candidate.exists():
+            return False
+    return True
+
+def _valid_evidence_mapping(value: object) -> bool:
+    if not isinstance(value, dict):
+        return False
+    return all(
+        key in EVIDENCE_FILENAMES
+        and (path is None or isinstance(path, str))
+        for key, path in value.items()
+    )
+
+
+def _validate_test_evidence(
+    paths: Mapping[str, str | None],
+    checkpoint_path: Path | None,
+    project_root: Path | None,
+) -> bool:
+    if set(paths) != set(EVIDENCE_FILENAMES):
+        return False
+    root = (project_root or _infer_project_root(checkpoint_path)).resolve()
+    resolved: dict[str, Path] = {}
+    for key, filename in EVIDENCE_FILENAMES.items():
+        raw_path = paths.get(key)
+        if not isinstance(raw_path, str) or not raw_path.strip():
+            return False
+        candidate = Path(raw_path)
+        if not candidate.is_absolute():
+            candidate = root / candidate
+        try:
+            candidate = candidate.resolve()
+            candidate.relative_to(root)
+        except (OSError, ValueError):
+            return False
+        if candidate.name != filename or not candidate.is_file():
+            return False
+        resolved[key] = candidate
+    parents = {path.parent for path in resolved.values()}
+    if len(parents) != 1:
+        return False
+    try:
+        manifest = json.loads(resolved["manifest"].read_text(encoding="utf-8"))
+        verdict = json.loads(resolved["verdict"].read_text(encoding="utf-8"))
+        validation = json.loads(resolved["validation"].read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return False
+    if not all(isinstance(record, dict) for record in (manifest, verdict, validation)):
+        return False
+    evidence_id = manifest.get("evidence_id")
+    if isinstance(evidence_id, str) and evidence_id and resolved["manifest"].parent.name != evidence_id:
+        return False
+    records_agree = (
+        manifest.get("final_verdict") == "TEST_PASS"
+        and verdict.get("verdict") == "TEST_PASS"
+        and validation.get("verdict") == "TEST_PASS"
+        and validation.get("result") == "passed"
+    )
+    if not records_agree:
+        return False
+    validator = _resolve_evidence_validator(root)
+    if validator is None:
+        return False
+    return _evidence_validator_passes(root, resolved["manifest"].parent, validator)
+
+
+def _evidence_validator_passes(
+    project_root: Path,
+    evidence_dir: Path,
+    validator: Path,
+) -> bool:
+    try:
+        result = subprocess.run(
+            [
+                sys.executable, str(validator),
+                "--evidence-dir", str(evidence_dir),
+                "--project-root", str(project_root),
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=120,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return result.returncode == 0
+
+
+def _resolve_evidence_validator(project_root: Path) -> Path | None:
+    candidates = (
+        project_root / ".claude" / "command-assets" / "prizmkit-test" / "scripts" / "validate_test_evidence.py",
+        project_root / ".agents" / "skills" / "prizmkit-test" / "scripts" / "validate_test_evidence.py",
+        project_root / ".codebuddy" / "skills" / "prizmkit-test" / "scripts" / "validate_test_evidence.py",
+        project_root / "core" / "skills" / "prizmkit-skill" / "prizmkit-test" / "scripts" / "validate_test_evidence.py",
+    )
+    return next((path for path in candidates if path.is_file()), None)
+
+
+def _infer_project_root(checkpoint_path: Path | None) -> Path:
+    if checkpoint_path is None:
+        return Path.cwd()
+    resolved = checkpoint_path.resolve()
+    for parent in (resolved.parent, *resolved.parents):
+        if (parent / ".prizmkit").is_dir():
+            return parent
+    return resolved.parent
+
+
+def _semantic_error(
+    workflow_type: str,
+    current_step: CheckpointStep | None,
+    code: str,
+    message: str,
+) -> SemanticCheckpoint:
+    stage = current_step.skill if current_step is not None else None
+    return SemanticCheckpoint(
+        workflow_type=workflow_type,
+        current_stage=stage,
+        next_stage=stage,
+        error_code=code,
+        error_message=message,
+    )
+
+
 def _invalid(
     path: Path | None,
     exists: bool,
@@ -280,4 +716,5 @@ def _invalid(
         error_code=code,
         error_message=message,
         raw_data=raw_data,
+        semantic=SemanticCheckpoint(error_code=code, error_message=message),
     )