prizmkit 1.1.154 → 1.1.156

package/bundled/dev-pipeline/tests/test_checkpoint_state.py

@@ -6,6 +6,8 @@ import json
 import subprocess
 import sys
 
+import pytest
+
 from prizmkit_runtime.checkpoint_state import (
     VALID_CHECKPOINT_STATUSES,
     VALID_STAGE_RESULTS,
@@ -14,6 +16,7 @@ from prizmkit_runtime.checkpoint_state import (
     read_checkpoint_cursor,
     validate_checkpoint_data,
 )
+from prizmkit_runtime.test_result import load_test_result
 from update_checkpoint import update_checkpoint
 
 
@@ -58,8 +61,6 @@ def _write_test_artifacts(root, slug="feature", *, result="TEST_PASS"):
         },
         "repair_rounds": 0,
         "production_changed": False,
-        "review_required": False,
-        "review_scope": None,
         "unresolved_items": [],
     }
     (artifact_dir / "test-result.json").write_text(
@@ -73,14 +74,16 @@ def _family_checkpoint(root=None, *, semantic=None, terminal=True):
         "prizmkit-implement",
         "prizmkit-code-review",
         "prizmkit-test",
+        "completion-summary",
         "prizmkit-retrospective",
         "prizmkit-committer",
-        "completion-summary",
     ]
     steps = []
     previous = None
     for index, skill in enumerate(skills, start=1):
         step = _step(f"S{index:02d}", skill, skill, "completed", previous)
+        if skill == "prizmkit-implement":
+            step["stage_result"] = "IMPLEMENTED"
         if skill == "prizmkit-code-review":
             step["stage_result"] = "REVIEW_PASS"
         if skill == "prizmkit-test":
@@ -89,6 +92,10 @@ def _family_checkpoint(root=None, *, semantic=None, terminal=True):
                 ".prizmkit/specs/feature/test-report.md",
                 ".prizmkit/specs/feature/test-result.json",
             ]
+        if skill == "prizmkit-retrospective":
+            step["stage_result"] = "RETRO_COMPLETE"
+        if skill == "prizmkit-committer":
+            step["stage_result"] = "COMMITTED"
         steps.append(step)
         previous = step["id"]
     if root is not None:
@@ -97,7 +104,14 @@ def _family_checkpoint(root=None, *, semantic=None, terminal=True):
         "version": 1,
         "workflow_type": "feature-pipeline",
         "steps": steps,
-        "feature_state": semantic or ({"terminal_status": "WORKFLOW_COMPLETED"} if terminal else {}),
+        "feature_state": semantic or (
+            {
+                "terminal_status": "WORKFLOW_COMPLETED",
+                "runtime_base_head": "a" * 40,
+                "runtime_commit_hash": "b" * 40,
+            }
+            if terminal else {}
+        ),
     }
 
 
@@ -201,6 +215,16 @@ def test_structural_validation_rejects_status_result_mismatch(tmp_path):
     assert state.error_code == "stage_result_status_mismatch"
 
 
+def test_family_planning_wrappers_own_plan_results(tmp_path):
+    for skill in ("context-snapshot-and-plan", "bug-diagnosis-and-plan"):
+        step = _step("S01", skill, "Plan", "completed")
+        step["stage_result"] = "PLAN_READY"
+        state = validate_checkpoint_data(
+            _checkpoint([step]), path=tmp_path / f"{skill}.json",
+        )
+        assert state.valid is True
+
+
 def test_structural_validation_rejects_stage_result_owner_mismatch(tmp_path):
     for skill in ("prizmkit-test", "custom-stage"):
         step = _step("S01", skill, "Step", "completed")
@@ -391,7 +415,6 @@ def test_checkpoint_updater_supports_every_owned_stage_result(tmp_path):
         ("prizmkit-test", "TEST_BLOCKED", "failed"),
         ("prizmkit-retrospective", "RETRO_COMPLETE", "completed"),
         ("prizmkit-committer", "COMMIT_PENDING", "in_progress"),
-        ("prizmkit-committer", "COMMITTED", "completed"),
     ]
 
     assert {stage_result for _skill, stage_result, _status in cases} <= VALID_STAGE_RESULTS
@@ -404,6 +427,19 @@ def test_checkpoint_updater_supports_every_owned_stage_result(tmp_path):
             payload["steps"].insert(0, _step("S01", skill, skill, "pending"))
             target_index = 0
         else:
+            payload["steps"].insert(
+                0,
+                {
+                    "id": "S00",
+                    "skill": "context-snapshot-and-plan",
+                    "name": "Plan",
+                    "status": "completed",
+                    "stage_result": "PLAN_READY",
+                    "required_artifacts": [],
+                    "depends_on": None,
+                },
+            )
+            payload["steps"][1]["depends_on"] = "S00"
             target_index = next(
                 position
                 for position, step in enumerate(payload["steps"])
@@ -511,11 +547,26 @@ def test_family_sequence_mismatch_cannot_complete(tmp_path):
     assert state.semantic.error_code == "invalid_stage_sequence"
 
 
-def test_test_needs_fixes_is_valid_domain_result_and_blocks_l4(tmp_path):
+def test_test_needs_fixes_routes_to_implementation_and_rewinds_stale_gates(tmp_path):
     payload = _family_checkpoint(tmp_path, semantic={}, terminal=False)
-    payload["steps"][2]["status"] = "in_progress"
-    payload["steps"][2].pop("stage_result")
-    for step in payload["steps"][3:]:
+    payload["steps"].insert(
+        0,
+        {
+            "id": "S00",
+            "skill": "context-snapshot-and-plan",
+            "name": "Plan",
+            "status": "completed",
+            "stage_result": "PLAN_READY",
+            "required_artifacts": [],
+            "depends_on": None,
+        },
+    )
+    payload["steps"][1]["depends_on"] = "S00"
+    test_step = next(step for step in payload["steps"] if step["skill"] == "prizmkit-test")
+    test_index = payload["steps"].index(test_step)
+    test_step["status"] = "in_progress"
+    test_step.pop("stage_result")
+    for step in payload["steps"][test_index + 1:]:
         step["status"] = "pending"
         step.pop("stage_result", None)
     checkpoint = _write(tmp_path / "workflow-checkpoint.json", payload)
@@ -524,16 +575,80 @@ def test_test_needs_fixes_is_valid_domain_result_and_blocks_l4(tmp_path):
         str(checkpoint),
         "prizmkit-test",
         "failed",
-        semantic_update={"stage_result": "TEST_NEEDS_FIXES"},
+        semantic_update={
+            "stage_result": "TEST_NEEDS_FIXES",
+            "repair_scope": "production",
+        },
     )
-    persisted = json.loads(checkpoint.read_text(encoding="utf-8"))
+    routed = json.loads(checkpoint.read_text(encoding="utf-8"))
 
     assert result["ok"] is True
-    assert persisted["steps"][2]["stage_result"] == "TEST_NEEDS_FIXES"
-    assert persisted["feature_state"]["stage_result"] == "TEST_NEEDS_FIXES"
-    assert persisted["feature_state"]["blocked_reason"] == "test_needs_fixes"
-    assert persisted["feature_state"]["terminal_status"] == "WORKFLOW_BLOCKED"
-    assert "authoritative_evidence_paths" not in persisted["steps"][2]
+    assert test_step["skill"] == "prizmkit-test"
+    persisted_test = next(
+        step for step in routed["steps"] if step["skill"] == "prizmkit-test"
+    )
+    assert persisted_test["stage_result"] == "TEST_NEEDS_FIXES"
+    assert routed["feature_state"]["stage_result"] == "TEST_NEEDS_FIXES"
+    assert routed["feature_state"]["next_stage"] == "prizmkit-implement"
+    assert routed["feature_state"]["repair_round"] == 1
+
+    restarted = update_checkpoint(
+        str(checkpoint), "prizmkit-implement", "in_progress"
+    )
+    rewound = json.loads(checkpoint.read_text(encoding="utf-8"))
+
+    assert restarted["ok"] is True
+    implementation = next(
+        step for step in rewound["steps"] if step["skill"] == "prizmkit-implement"
+    )
+    assert implementation["status"] == "in_progress"
+    for step in rewound["steps"][rewound["steps"].index(implementation) + 1:]:
+        assert step["status"] == "pending"
+        assert "stage_result" not in step
+
+
+def test_terminal_atomic_blockers_become_workflow_blocked(tmp_path):
+    cases = [
+        ("context-snapshot-and-plan", "PLAN_BLOCKED"),
+        ("prizmkit-implement", "IMPLEMENT_BLOCKED"),
+        ("prizmkit-retrospective", "RETRO_BLOCKED"),
+        ("prizmkit-committer", "COMMIT_BLOCKED"),
+    ]
+    for index, (skill, stage_result) in enumerate(cases):
+        payload = _family_checkpoint(tmp_path, semantic={}, terminal=False)
+        if skill == "context-snapshot-and-plan":
+            payload["steps"].insert(
+                0,
+                {
+                    "id": "S00",
+                    "skill": skill,
+                    "name": "Plan",
+                    "status": "pending",
+                    "required_artifacts": [],
+                    "depends_on": None,
+                },
+            )
+            payload["steps"][1]["depends_on"] = "S00"
+            target_index = 0
+        else:
+            target_index = next(
+                position for position, step in enumerate(payload["steps"])
+                if step["skill"] == skill
+            )
+        for step in payload["steps"][target_index:]:
+            step["status"] = "pending"
+            step.pop("stage_result", None)
+        checkpoint = _write(tmp_path / f"terminal-blocker-{index}.json", payload)
+
+        result = update_checkpoint(
+            str(checkpoint), skill, "failed",
+            semantic_update={"stage_result": stage_result},
+        )
+        persisted = json.loads(checkpoint.read_text(encoding="utf-8"))
+
+        assert result["ok"] is True
+        assert persisted["feature_state"]["terminal_status"] == "WORKFLOW_BLOCKED"
+        assert persisted["feature_state"]["blocked_reason"]
 
 
 def test_test_blocked_preserves_l1_result_without_evidence_discovery(tmp_path):
@@ -602,6 +717,31 @@ def test_update_checkpoint_rejects_test_completion_for_non_pass(tmp_path):
     assert "requires TEST_PASS" in result["error"]
 
 
+def test_prompt_checkpoint_helper_rejects_runtime_owned_committed_result(tmp_path):
+    payload = _family_checkpoint(tmp_path, semantic={}, terminal=False)
+    committer = next(
+        step for step in payload["steps"] if step["skill"] == "prizmkit-committer"
+    )
+    committer["status"] = "in_progress"
+    committer["stage_result"] = "COMMIT_PENDING"
+    checkpoint = _write(tmp_path / "workflow-checkpoint.json", payload)
+
+    result = update_checkpoint(
+        str(checkpoint),
+        "prizmkit-committer",
+        "completed",
+        semantic_update={"stage_result": "COMMITTED"},
+    )
+
+    assert result["ok"] is False
+    assert "Runtime-owned" in result["error"]
+    without_result = update_checkpoint(
+        str(checkpoint), "prizmkit-committer", "completed"
+    )
+    assert without_result["ok"] is False
+    assert "Runtime-owned COMMITTED" in without_result["error"]
+
+
 def test_update_checkpoint_rejects_test_before_review_pass(tmp_path):
     payload = _family_checkpoint(tmp_path, semantic={}, terminal=False)
     payload["steps"][1]["status"] = "skipped"
@@ -623,7 +763,7 @@ def test_update_checkpoint_rejects_finalization_before_test_pass(tmp_path):
     payload = _family_checkpoint(tmp_path, semantic={}, terminal=False)
     payload["steps"][2]["status"] = "skipped"
     payload["steps"][2].pop("stage_result", None)
-    payload["steps"][3]["status"] = "pending"
+    payload["steps"][3]["status"] = "completed"
     for step in payload["steps"][4:]:
         step["status"] = "pending"
         step.pop("stage_result", None)
@@ -635,9 +775,53 @@ def test_update_checkpoint_rejects_finalization_before_test_pass(tmp_path):
     assert "TEST_PASS" in result["error"]
 
 
+def test_commit_pending_is_runtime_ready_but_not_workflow_complete(tmp_path):
+    payload = _family_checkpoint(tmp_path, semantic={}, terminal=False)
+    payload["steps"].insert(
+        0,
+        {
+            "id": "S00",
+            "skill": "context-snapshot-and-plan",
+            "name": "Plan",
+            "status": "completed",
+            "stage_result": "PLAN_READY",
+            "required_artifacts": [],
+            "depends_on": None,
+        },
+    )
+    payload["steps"][1]["depends_on"] = "S00"
+    committer = next(
+        step for step in payload["steps"] if step["skill"] == "prizmkit-committer"
+    )
+    committer["status"] = "in_progress"
+    committer["stage_result"] = "COMMIT_PENDING"
+    committer["required_artifacts"] = [
+        ".prizmkit/specs/feature/runtime-commit-request.json"
+    ]
+    artifact_dir = tmp_path / ".prizmkit/specs/feature"
+    (artifact_dir / "runtime-commit-request.json").write_text("{}", encoding="utf-8")
+    payload["feature_state"] = {
+        "stage": "committer",
+        "status": "in_progress",
+        "stage_result": "COMMIT_PENDING",
+        "repair_round": 0,
+    }
+    checkpoint = _write(artifact_dir / "workflow-checkpoint.json", payload)
+
+    state = load_checkpoint_state(checkpoint, project_root=tmp_path)
+
+    assert state.valid is True
+    assert state.semantic_commit_ready is True
+    assert state.semantic_complete is False
+    assert state.semantic_snapshot["commit_ready"] is True
+
+
 def test_declared_final_artifact_must_exist_for_completion(tmp_path):
     payload = _family_checkpoint(tmp_path)
-    payload["steps"][-1]["required_artifacts"] = [
+    summary_step = next(
+        step for step in payload["steps"] if step["skill"] == "completion-summary"
+    )
+    summary_step["required_artifacts"] = [
         ".prizmkit/specs/feature/completion-summary.json"
     ]
     checkpoint = _write(
@@ -655,6 +839,239 @@ def test_declared_final_artifact_must_exist_for_completion(tmp_path):
     assert present.semantic.artifacts_valid is True
 
 
+def test_completion_requires_declared_review_report_with_terminal_pass(tmp_path):
+    payload = _family_checkpoint(tmp_path)
+    review = next(
+        step for step in payload["steps"]
+        if step["skill"] == "prizmkit-code-review"
+    )
+    review["required_artifacts"] = [
+        ".prizmkit/specs/feature/review-report.md"
+    ]
+    checkpoint = _write(
+        tmp_path / ".prizmkit/specs/feature/workflow-checkpoint.json", payload,
+    )
+
+    assert load_checkpoint_state(checkpoint, project_root=tmp_path).semantic_complete is False
+    (checkpoint.parent / "review-report.md").write_text(
+        "# Review Report\n\n## Final Result\n\n- Verdict: NEEDS_FIXES\n",
+        encoding="utf-8",
+    )
+    assert load_checkpoint_state(checkpoint, project_root=tmp_path).semantic_complete is False
+    (checkpoint.parent / "review-report.md").write_text(
+        "# Review Report\n\n## Final Result\n\n- Verdict: PASS\n",
+        encoding="utf-8",
+    )
+    assert load_checkpoint_state(checkpoint, project_root=tmp_path).semantic_complete is True
+
+
+def test_completion_requires_valid_declared_retrospective_result(tmp_path):
+    payload = _family_checkpoint(tmp_path)
+    retrospective = next(
+        step for step in payload["steps"]
+        if step["skill"] == "prizmkit-retrospective"
+    )
+    retrospective["required_artifacts"] = [
+        ".prizmkit/specs/feature/retrospective-result.json"
+    ]
+    checkpoint = _write(
+        tmp_path / ".prizmkit/specs/feature/workflow-checkpoint.json", payload,
+    )
+
+    (checkpoint.parent / "retrospective-result.json").write_text(
+        "{}\n", encoding="utf-8",
+    )
+    assert load_checkpoint_state(checkpoint, project_root=tmp_path).semantic_complete is False
+    (checkpoint.parent / "retrospective-result.json").write_text(
+        json.dumps(
+            {
+                "schema_version": 1,
+                "outcome": "RETRO_COMPLETE",
+                "result": "NO_DOC_CHANGE",
+                "reason": "No durable change",
+                "change_paths": ["src/example.py"],
+                "documentation_paths": [],
+                "validation": [],
+            }
+        ),
+        encoding="utf-8",
+    )
+    assert load_checkpoint_state(checkpoint, project_root=tmp_path).semantic_complete is True
+
+
+@pytest.mark.parametrize(
+    "invalid_path",
+    [
+        ".prizmkit/prizm-docs/../escape.prizm",
+        ".prizmkit/prizm-docs/./module.prizm",
+        ".prizmkit/prizm-docs//module.prizm",
+        ".prizmkit\\prizm-docs\\module.prizm",
+        ".prizmkit/prizm-docs/module.md",
+    ],
+)
+def test_completion_rejects_unsafe_retrospective_documentation_path(
+    tmp_path, invalid_path,
+):
+    payload = _family_checkpoint(tmp_path)
+    retrospective = next(
+        step for step in payload["steps"]
+        if step["skill"] == "prizmkit-retrospective"
+    )
+    retrospective["required_artifacts"] = [
+        ".prizmkit/specs/feature/retrospective-result.json"
+    ]
+    checkpoint = _write(
+        tmp_path / ".prizmkit/specs/feature/workflow-checkpoint.json", payload,
+    )
+    (checkpoint.parent / "retrospective-result.json").write_text(
+        json.dumps(
+            {
+                "schema_version": 1,
+                "outcome": "RETRO_COMPLETE",
+                "result": "DOCS_UPDATED",
+                "reason": "Durable docs changed",
+                "change_paths": ["src/example.py"],
+                "documentation_paths": [invalid_path],
+                "validation": ["validate docs"],
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    assert load_checkpoint_state(checkpoint, project_root=tmp_path).semantic_complete is False
+
+
+@pytest.mark.parametrize(
+    "invalid_path",
+    ["../escape.py", "./src/example.py", "src//example.py", "src\\example.py"],
+)
+def test_completion_rejects_unsafe_retrospective_change_path(tmp_path, invalid_path):
+    payload = _family_checkpoint(tmp_path)
+    retrospective = next(
+        step for step in payload["steps"]
+        if step["skill"] == "prizmkit-retrospective"
+    )
+    retrospective["required_artifacts"] = [
+        ".prizmkit/specs/feature/retrospective-result.json"
+    ]
+    checkpoint = _write(
+        tmp_path / ".prizmkit/specs/feature/workflow-checkpoint.json", payload,
+    )
+    (checkpoint.parent / "retrospective-result.json").write_text(
+        json.dumps(
+            {
+                "schema_version": 1,
+                "outcome": "RETRO_COMPLETE",
+                "result": "NO_DOC_CHANGE",
+                "reason": "No durable change",
+                "change_paths": [invalid_path],
+                "documentation_paths": [],
+                "validation": [],
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    assert load_checkpoint_state(checkpoint, project_root=tmp_path).semantic_complete is False
+
+
+def test_completion_rejects_configured_verification_after_test(tmp_path):
+    payload = _family_checkpoint(tmp_path)
+    test_index = next(
+        index for index, step in enumerate(payload["steps"])
+        if step["skill"] == "prizmkit-test"
+    )
+    test_step = payload["steps"][test_index]
+    following = payload["steps"][test_index + 1]
+    payload["steps"].insert(
+        test_index + 1,
+        {
+            "id": "S99",
+            "skill": "browser-verification",
+            "name": "Browser Verification",
+            "status": "completed",
+            "required_artifacts": [],
+            "depends_on": test_step["id"],
+        },
+    )
+    following["depends_on"] = "S99"
+
+    state = validate_checkpoint_data(payload, project_root=tmp_path)
+
+    assert state.semantic.sequence_valid is False
+    assert "after review and before test" in state.semantic.error_message
+
+
+def test_configured_manual_verification_cannot_be_skipped_for_commit_readiness(tmp_path):
+    payload = _family_checkpoint(tmp_path, semantic={}, terminal=False)
+    payload["steps"].insert(
+        0,
+        {
+            "id": "S00",
+            "skill": "context-snapshot-and-plan",
+            "name": "Plan",
+            "status": "completed",
+            "stage_result": "PLAN_READY",
+            "required_artifacts": [],
+            "depends_on": None,
+        },
+    )
+    payload["steps"][1]["depends_on"] = "S00"
+    review = next(
+        step for step in payload["steps"]
+        if step["skill"] == "prizmkit-code-review"
+    )
+    test = next(
+        step for step in payload["steps"] if step["skill"] == "prizmkit-test"
+    )
+    test_index = payload["steps"].index(test)
+    payload["steps"].insert(
+        test_index,
+        {
+            "id": "S99",
+            "skill": "manual-verification",
+            "name": "Manual Verification",
+            "status": "skipped",
+            "required_artifacts": [],
+            "depends_on": review["id"],
+        },
+    )
+    test["depends_on"] = "S99"
+    committer = next(
+        step for step in payload["steps"]
+        if step["skill"] == "prizmkit-committer"
+    )
+    committer["status"] = "in_progress"
+    committer["stage_result"] = "COMMIT_PENDING"
+    committer["required_artifacts"] = [
+        ".prizmkit/specs/feature/runtime-commit-request.json"
+    ]
+    artifact_dir = tmp_path / ".prizmkit/specs/feature"
+    (artifact_dir / "runtime-commit-request.json").write_text("{}", encoding="utf-8")
+    checkpoint = _write(artifact_dir / "workflow-checkpoint.json", payload)
+
+    skipped = load_checkpoint_state(checkpoint, project_root=tmp_path)
+    payload["steps"][test_index]["status"] = "completed"
+    checkpoint.write_text(json.dumps(payload), encoding="utf-8")
+    completed = load_checkpoint_state(checkpoint, project_root=tmp_path)
+
+    assert skipped.semantic_commit_ready is False
+    assert completed.semantic_commit_ready is True
+
+
+def test_nonpass_test_projection_requires_exact_unresolved_item(tmp_path):
+    artifact_dir = _write_test_artifacts(
+        tmp_path, slug="nonpass", result="TEST_NEEDS_FIXES"
+    )
+    result_path = artifact_dir / "test-result.json"
+
+    assert load_test_result(result_path) is None
+    projection = json.loads(result_path.read_text(encoding="utf-8"))
+    projection["unresolved_items"] = ["Public API correction remains"]
+    result_path.write_text(json.dumps(projection), encoding="utf-8")
+    assert load_test_result(result_path) is not None
+
+
 def test_completion_rejects_invalid_test_result_projection(tmp_path):
     payload = _family_checkpoint(tmp_path)
     checkpoint = _write(
@@ -694,6 +1111,40 @@ def test_completion_rejects_inconsistent_independent_review_metadata(tmp_path):
     assert state.semantic.artifacts_valid is False
 
 
+def test_legacy_completed_checkpoint_accepts_historical_test_projection_read_only(tmp_path):
+    payload = _family_checkpoint(tmp_path)
+    by_skill = {step["skill"]: step for step in payload["steps"]}
+    legacy_order = [
+        "prizmkit-implement",
+        "prizmkit-code-review",
+        "prizmkit-test",
+        "prizmkit-retrospective",
+        "prizmkit-committer",
+        "completion-summary",
+    ]
+    payload["steps"] = [by_skill[skill] for skill in legacy_order]
+    previous = None
+    for index, step in enumerate(payload["steps"], start=1):
+        step["id"] = f"S{index:02d}"
+        step["depends_on"] = previous
+        previous = step["id"]
+    checkpoint = _write(
+        tmp_path / ".prizmkit/specs/feature/workflow-checkpoint.json", payload,
+    )
+    result_path = checkpoint.parent / "test-result.json"
+    projection = json.loads(result_path.read_text(encoding="utf-8"))
+    projection["review_required"] = False
+    projection["review_scope"] = None
+    result_path.write_text(json.dumps(projection), encoding="utf-8")
+    assert load_test_result(result_path) is None
+
+    state = load_checkpoint_state(checkpoint, project_root=tmp_path)
+
+    assert state.semantic_complete is True
+    assert state.semantic.artifacts_valid is True
+    assert state.semantic_commit_ready is False
+
+
 def test_completion_accepts_legacy_terminal_result_report(tmp_path):
     payload = _family_checkpoint(tmp_path)
     checkpoint = _write(