prizmkit 1.1.130 → 1.1.131

package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py

@@ -24,17 +24,23 @@ Usage:
 
 import argparse
 import glob
+import hashlib
 import json
 import os
 import re
+import subprocess
 import sys
 
 from utils import enrich_global_context, helper_replacements, load_json_file, resolve_prompt_platform, setup_logging
 from continuation import add_continuation_args, append_continuation_handoff, is_continuation
-from prompt_framework import browser_enabled_from_item, checkpoint_group, checkpoint_skip, checkpoint_step, detect_dev_server_port, generate_checkpoint_from_sections, merge_checkpoint_state as merge_shared_checkpoint_state
+from prompt_framework import browser_enabled_from_item, checkpoint_group, checkpoint_skip, checkpoint_step, detect_dev_server_port, generate_checkpoint_from_sections, merge_checkpoint_state as merge_shared_checkpoint_state, pipeline_checkpoint_metadata, route_pipeline_repair
 
 
 DEFAULT_MAX_RETRIES = 3
+MAX_OUTER_REPAIR_ROUNDS = 3
+EVIDENCE_FINAL_RECORDS = {"validation.json", "verdict.json", "test-report.md"}
+EVIDENCE_SHA256_RE = re.compile(r"^[a-f0-9]{64}$")
+EVIDENCE_TARGET_HASH_KEYS = ("source", "tests", "contracts", "lockfiles", "environment", "plan")
 
 LOGGER = setup_logging("generate-bootstrap-prompt")
 
@@ -679,7 +685,9 @@ SECTION_TO_SKILL = {
     "phase-prizmkit-test": checkpoint_step(
         "prizmkit-test", "Scoped Feature Test Gate",
         [".prizmkit/specs/{slug}/test-report-path.txt",
-         ".prizmkit/test/*/test-report.md"],
+         ".prizmkit/test/evidence/*/manifest.json",
+         ".prizmkit/test/evidence/*/verdict.json",
+         ".prizmkit/test/evidence/*/validation.json"],
     ),
     "phase-review": checkpoint_step("prizmkit-code-review", "Code Review", []),
     "phase-browser": checkpoint_step("browser-verification", "Browser Verification", []),
@@ -716,6 +724,366 @@ def _read_text(path):
         return ""
 
 
+def _canonical_sha256(value):
+    """Return the protocol's compact, key-sorted JSON SHA-256."""
+    payload = json.dumps(
+        value, ensure_ascii=False, sort_keys=True, separators=(",", ":"),
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def _file_sha256(path):
+    """Hash a file without loading large evidence records into memory."""
+    digest = hashlib.sha256()
+    try:
+        with open(path, "rb") as f:
+            for chunk in iter(lambda: f.read(1024 * 1024), b""):
+                digest.update(chunk)
+    except OSError:
+        return ""
+    return digest.hexdigest()
+
+
+def _load_strict_json(path):
+    """Load JSON while rejecting duplicate keys and non-JSON constants."""
+    def reject_duplicates(pairs):
+        result = {}
+        for key, value in pairs:
+            if key in result:
+                raise ValueError("duplicate object key: {}".format(key))
+            result[key] = value
+        return result
+
+    def reject_constant(value):
+        raise ValueError("non-JSON numeric constant: {}".format(value))
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(
+                f, object_pairs_hook=reject_duplicates,
+                parse_constant=reject_constant,
+            )
+    except (OSError, ValueError, TypeError):
+        return None
+
+
+def _is_sha256(value):
+    return isinstance(value, str) and bool(EVIDENCE_SHA256_RE.fullmatch(value))
+
+
+def _path_is_within(root, candidate):
+    """Return whether candidate resolves below root without escaping it."""
+    try:
+        return os.path.commonpath([
+            os.path.realpath(root), os.path.realpath(candidate),
+        ]) == os.path.realpath(root)
+    except ValueError:
+        return False
+
+
+def _resolve_test_evidence_validator(project_root):
+    """Return the installed validator path used by the current project."""
+    candidates = [
+        os.path.join(
+            project_root, ".claude", "command-assets", "prizmkit-test",
+            "scripts", "validate_test_evidence.py",
+        ),
+        os.path.join(
+            project_root, ".agents", "skills", "prizmkit-test", "scripts",
+            "validate_test_evidence.py",
+        ),
+        os.path.join(
+            project_root, ".codebuddy", "skills", "prizmkit-test", "scripts",
+            "validate_test_evidence.py",
+        ),
+    ]
+    return next((path for path in candidates if os.path.isfile(path)), "")
+
+
+def _evidence_validator_passes(project_root, evidence_root, validation):
+    """Re-run the authoritative L1 validator before accepting any verdict."""
+    validator_path = _resolve_test_evidence_validator(project_root)
+    if (not validator_path or
+            validation.get("validator_sha256") != _file_sha256(validator_path)):
+        return False
+    try:
+        result = subprocess.run(
+            [sys.executable, validator_path,
+             "--evidence-dir", evidence_root,
+             "--project-root", project_root],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=120,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return result.returncode == 0
+
+
+def _evidence_package_from_pointer(project_root, pointer_artifact):
+    """Resolve a Feature report pointer to the structured evidence package."""
+    pointer_path = os.path.join(project_root, pointer_artifact)
+    pointed = _read_text(pointer_path).strip().splitlines()
+    if not pointed:
+        return None, None
+
+    report_path = pointed[0].strip()
+    if not os.path.isabs(report_path):
+        report_path = os.path.join(project_root, report_path)
+    evidence_root = os.path.dirname(report_path)
+    expected_root = os.path.join(project_root, ".prizmkit", "test", "evidence")
+    if not _path_is_within(expected_root, evidence_root):
+        return None, None
+    relative_root = os.path.relpath(evidence_root, expected_root)
+    if (not relative_root or relative_root.startswith("..") or
+            os.sep in relative_root):
+        return None, None
+    if os.path.basename(report_path) != "test-report.md":
+        return None, None
+    if not os.path.isfile(report_path):
+        return None, None
+    return os.path.realpath(evidence_root), os.path.realpath(report_path)
+
+
+def _manifest_entries(evidence_root, manifest):
+    """Validate the manifest file list and return path -> entry."""
+    entries = manifest.get("files")
+    if not isinstance(entries, list):
+        return None
+    result = {}
+    for entry in entries:
+        if not isinstance(entry, dict):
+            return None
+        relative = entry.get("path")
+        if (not isinstance(relative, str) or not relative or
+                os.path.isabs(relative) or relative in result or
+                ".." in relative.split("/") or "\\" in relative):
+            return None
+        path = os.path.join(evidence_root, relative)
+        if not _path_is_within(evidence_root, path) or not os.path.isfile(path):
+            return None
+        if not _is_sha256(entry.get("sha256")):
+            return None
+        if not isinstance(entry.get("produced_by"), str) or not entry["produced_by"].strip():
+            return None
+        if _file_sha256(path) != entry["sha256"]:
+            return None
+        result[relative] = entry
+
+    actual = set()
+    for root, _dirs, files in os.walk(evidence_root):
+        for filename in files:
+            relative = os.path.relpath(os.path.join(root, filename), evidence_root)
+            if relative != "manifest.json":
+                actual.add(relative)
+    return result if set(result) == actual else None
+
+
+def _extract_report_scope(report_text):
+    """Read only the derived report's artifact identity, never its verdict."""
+    in_scope = False
+    for raw_line in report_text.splitlines():
+        line = raw_line.strip()
+        if line == "## Scope":
+            in_scope = True
+            continue
+        if in_scope and line.startswith("## "):
+            break
+        if in_scope and line.startswith("- Artifact Dir:"):
+            return line.split(":", 1)[1].strip()
+    return ""
+
+
+def _validate_target_hashes(evidence_root, project_root, manifest, entry_map):
+    """Validate live inventoried files against the manifest target hashes."""
+    inventory_path = os.path.join(evidence_root, "target-inventory.json")
+    environment_path = os.path.join(evidence_root, "environment.json")
+    inventory = _load_strict_json(inventory_path)
+    environment = _load_strict_json(environment_path)
+    if not isinstance(inventory, dict) or not isinstance(environment, dict):
+        return False
+    if "target-inventory.json" not in entry_map or "environment.json" not in entry_map:
+        return False
+
+    categories = inventory.get("categories")
+    expected = set(EVIDENCE_TARGET_HASH_KEYS[:4])
+    if not isinstance(categories, dict) or set(categories) != expected:
+        return False
+    aggregates = {}
+    for category in sorted(expected):
+        records = categories.get(category)
+        if not isinstance(records, list):
+            return False
+        normalized = []
+        for record in records:
+            if not isinstance(record, dict):
+                return False
+            relative = record.get("path")
+            expected_hash = record.get("sha256")
+            if (not isinstance(relative, str) or os.path.isabs(relative) or
+                    not _is_sha256(expected_hash)):
+                return False
+            live_path = os.path.join(project_root, relative)
+            if (not _path_is_within(project_root, live_path) or
+                    not os.path.isfile(live_path) or
+                    _file_sha256(live_path) != expected_hash):
+                return False
+            normalized.append({"path": relative, "sha256": expected_hash})
+        aggregates[category] = _canonical_sha256(
+            sorted(normalized, key=lambda item: item["path"]),
+        )
+
+    aggregates["environment"] = _canonical_sha256(environment)
+    plan_inputs = inventory.get("plan_inputs")
+    if not isinstance(plan_inputs, dict) or not plan_inputs:
+        return False
+    aggregates["plan"] = _canonical_sha256(plan_inputs)
+    target_hashes = manifest.get("target_hashes")
+    return target_hashes == aggregates
+
+
+def validate_feature_test_evidence(project_root, artifact_dir):
+    """Return structured Feature test evidence, or None when it is unsafe."""
+    pointer_artifact = os.path.join(artifact_dir, "test-report-path.txt")
+    evidence_root, report_path = _evidence_package_from_pointer(
+        project_root, pointer_artifact,
+    )
+    if not evidence_root or not report_path:
+        return None
+
+    marker_path = os.path.join(project_root, artifact_dir, ".prizmkit-test-started")
+    if not os.path.isfile(marker_path):
+        return None
+    try:
+        if os.path.getmtime(report_path) < os.path.getmtime(marker_path):
+            return None
+    except OSError:
+        return None
+
+    manifest = _load_strict_json(os.path.join(evidence_root, "manifest.json"))
+    verdict = _load_strict_json(os.path.join(evidence_root, "verdict.json"))
+    validation = _load_strict_json(os.path.join(evidence_root, "validation.json"))
+    if not all(isinstance(record, dict) for record in (manifest, verdict, validation)):
+        return None
+    entry_map = _manifest_entries(evidence_root, manifest)
+    if entry_map is None or not {"verdict.json", "validation.json"}.issubset(entry_map):
+        return None
+
+    identity = manifest.get("evidence_id_inputs")
+    evidence_id = manifest.get("evidence_id")
+    if (not isinstance(identity, dict) or not _is_sha256(identity.get("working_diff_sha256")) or
+            not _is_sha256(identity.get("scope_sha256")) or
+            not isinstance(identity.get("baseline_commit"), str) or
+            evidence_id != _canonical_sha256(identity) or
+            os.path.basename(evidence_root) != evidence_id):
+        return None
+    if (manifest.get("protocol_version") != "1.0" or
+            manifest.get("sensitivity") != "project-controlled" or
+            manifest.get("environment_claim") != "mocked-code-level-only" or
+            manifest.get("compatibility") != "legacy-test-report-interface-not-supported" or
+            manifest.get("final_verdict") not in {"TEST_PASS", "TEST_FAIL", "TEST_BLOCKED"}):
+        return None
+    stages = manifest.get("stages")
+    stage_names = [stage.get("name") for stage in stages] if isinstance(stages, list) else []
+    if stage_names != [
+            "CHANGE_CLASSIFY", "SCOPE_DISCOVER", "CONTRACT_MODEL", "TEST_PLAN",
+            "INFRA_READY", "TEST_BUILD", "EXECUTE_PROVE", "EVIDENCE_PACKAGE",
+            "EVIDENCE_VALIDATE"]:
+        return None
+    for stage in stages:
+        if (not isinstance(stage, dict) or stage.get("status") not in {"complete", "not_applicable"} or
+                not _is_sha256(stage.get("input_sha256")) or
+                not isinstance(stage.get("outputs"), list)):
+            return None
+    if (not _is_sha256(manifest.get("working_diff_sha256")) or
+            manifest.get("working_diff_sha256") != identity.get("working_diff_sha256")):
+        return None
+
+    final_verdict = manifest["final_verdict"]
+    if (verdict.get("verdict") != final_verdict or
+            verdict.get("testing_domain_only") is not True or
+            verdict.get("authorizes_commit_or_release") is not False or
+            verdict.get("real_environment_validated") is not False or
+            verdict.get("repairs_business_defects") is not False or
+            not isinstance(verdict.get("blockers"), list) or
+            not isinstance(verdict.get("reproduced_failures"), list)):
+        return None
+    if final_verdict == "TEST_PASS" and (
+            verdict.get("code_evidence_replayable") is not True or
+            verdict.get("blockers") or verdict.get("reproduced_failures")):
+        return None
+    if final_verdict == "TEST_FAIL" and not verdict.get("reproduced_failures"):
+        return None
+    if final_verdict == "TEST_BLOCKED" and not verdict.get("blockers"):
+        return None
+
+    payload = sorted(
+        ({"path": path, "sha256": entry["sha256"]}
+         for path, entry in entry_map.items()
+         if path not in EVIDENCE_FINAL_RECORDS),
+        key=lambda item: item["path"],
+    )
+    if (validation.get("validator") != "validate_test_evidence.py" or
+            not _is_sha256(validation.get("validator_sha256")) or
+            validation.get("payload_sha256") != _canonical_sha256(payload) or
+            validation.get("result") != "passed" or
+            validation.get("verdict") != final_verdict or
+            validation.get("semantics") != "integrity-and-protocol-validation-not-hostile-producer-proof" or
+            not isinstance(validation.get("replay_receipt_ids"), list)):
+        return None
+    if not _evidence_validator_passes(project_root, evidence_root, validation):
+        return None
+
+    report_scope = _normalize_artifact_dir(_extract_report_scope(_read_text(report_path)))
+    expected_scope = _normalize_artifact_dir(artifact_dir)
+    if report_scope != expected_scope:
+        return None
+    if not _validate_target_hashes(evidence_root, project_root, manifest, entry_map):
+        return None
+    scope = _load_strict_json(os.path.join(evidence_root, "scope.json"))
+    if not isinstance(scope, dict) or identity.get("scope_sha256") != _canonical_sha256(scope):
+        return None
+
+    state_path = os.path.join(
+        project_root, ".prizmkit", "state", "workflows",
+        os.path.basename(artifact_dir) + ".json",
+    )
+    state = _load_strict_json(state_path) if os.path.isfile(state_path) else {}
+    if state and (not isinstance(state, dict) or state.get("stage_result") not in {None, final_verdict, "TEST_PASS", "TEST_FAIL", "TEST_BLOCKED"}):
+        return None
+    return {
+        "evidence_id": evidence_id,
+        "evidence_dir": os.path.relpath(evidence_root, project_root),
+        "manifest_path": os.path.relpath(os.path.join(evidence_root, "manifest.json"), project_root),
+        "verdict_path": os.path.relpath(os.path.join(evidence_root, "verdict.json"), project_root),
+        "validation_path": os.path.relpath(os.path.join(evidence_root, "validation.json"), project_root),
+        "verdict": final_verdict,
+        "repair_scope": state.get("repair_scope") if isinstance(state, dict) else None,
+        "repair_round": state.get("repair_round", 0) if isinstance(state, dict) else 0,
+        "target_hashes": manifest.get("target_hashes"),
+    }
+
+
+def route_feature_repair(stage_result, repair_scope=None, repair_round=0):
+    """Map Feature review/test outcomes to the shared safe route contract."""
+    return route_pipeline_repair(stage_result, repair_scope, repair_round)
+
+
+def feature_checkpoint_metadata(artifact_dir, evidence=None, stage="plan",
+                                status="PLAN_READY", stage_result=None,
+                                repair_scope=None, repair_round=0,
+                                next_stage="prizmkit-implement",
+                                resume_from="prizmkit-implement"):
+    """Build Feature L4 handoff metadata through the shared semantic contract."""
+    return pipeline_checkpoint_metadata(
+        artifact_dir, evidence=evidence, stage=stage, status=status,
+        stage_result=stage_result, repair_scope=repair_scope,
+        repair_round=repair_round, next_stage=next_stage,
+        resume_from=resume_from,
+    )
+
+
 def _normalize_artifact_dir(path):
     """Normalize report artifact_dir values for comparison."""
     return path.strip().replace("\\", "/").rstrip("/")
@@ -1091,8 +1459,12 @@ def _scoped_report_fresh(project_root, pointer_artifact, report_path, report_tex
     return True
 
 
-def _validate_scoped_test_report(project_root, artifacts):
-    """Validate the feature prizmkit-test pointer and scoped PASS report."""
+def _validate_legacy_scoped_test_report(project_root, artifacts):
+    """Validate the legacy Markdown report for old callers only.
+
+    Feature checkpoints must use ``_validate_scoped_test_report`` below; this
+    retained helper is intentionally not used by Feature prompt generation.
+    """
     pointer_artifacts = [a for a in artifacts
                          if a.endswith("/test-report-path.txt")]
     if not pointer_artifacts:
@@ -1130,6 +1502,16 @@ def _validate_scoped_test_report(project_root, artifacts):
                                  report_path, report_text))
 
 
+def _validate_scoped_test_report(project_root, artifacts):
+    """Validate current Feature structured evidence, never Markdown authority."""
+    pointer_artifacts = [a for a in artifacts if a.endswith("/test-report-path.txt")]
+    if not pointer_artifacts:
+        return False
+    return validate_feature_test_evidence(
+        project_root, os.path.dirname(pointer_artifacts[0]),
+    ) is not None
+
+
 def _completed_step_artifacts_valid(project_root, skill_key, artifacts):
     """Return whether a completed checkpoint step can be preserved."""
     if not all(_artifact_exists(project_root, a) for a in artifacts):
@@ -1886,6 +2268,16 @@ def main():
             checkpoint_dir, "workflow-checkpoint.json",
         )
 
+        # L4 metadata remains separate from the L1 workflow-state contract.
+        checkpoint["feature_state"] = feature_checkpoint_metadata(
+            os.path.join(".prizmkit", "specs", feature_slug),
+            stage="plan",
+            status="PLAN_READY",
+            stage_result=None,
+            next_stage="prizmkit-implement",
+            resume_from="prizmkit-implement",
+        )
+
         # On resume, merge existing completed state (with artifact validation)
         if (is_resume or is_continuation(args)) and os.path.exists(checkpoint_path):
             try:

package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py

@@ -22,9 +22,11 @@ from prompt_framework import (
     merge_checkpoint_state,
     mode_agent_count,
     normalize_mode,
+    pipeline_checkpoint_metadata,
     read_text_file,
     render_from_sections,
     replace_placeholders,
+    route_pipeline_repair,
     validate_rendered,
     write_output,
 )
@@ -34,6 +36,30 @@ from utils import enrich_global_context, helper_replacements, load_json_file, re
 LOGGER = setup_logging("generate-bugfix-prompt")
 
 
+def route_bugfix_repair(stage_result, repair_scope=None, repair_round=0):
+    """Map Bugfix review/test outcomes to the shared safe route contract."""
+    return route_pipeline_repair(stage_result, repair_scope, repair_round)
+
+
+def bugfix_checkpoint_metadata(artifact_dir, evidence=None, stage="plan",
+                               status="PLAN_READY", stage_result=None,
+                               repair_scope=None, repair_round=0,
+                               next_stage="prizmkit-implement",
+                               resume_from="prizmkit-implement"):
+    """Build Bugfix L4 handoff metadata while preserving Bugfix L1 state."""
+    return pipeline_checkpoint_metadata(
+        artifact_dir,
+        evidence=evidence,
+        stage=stage,
+        status=status,
+        stage_result=stage_result,
+        repair_scope=repair_scope,
+        repair_round=repair_round,
+        next_stage=next_stage,
+        resume_from=resume_from,
+    )
+
+
 # Section name -> checkpoint contract.
 BUGFIX_SECTION_TO_SKILL = {
     "bugfix-phase-init": checkpoint_step("prizmkit-init", "Initialize", [".prizmkit/bugfix/{slug}"]),
@@ -43,6 +69,14 @@ BUGFIX_SECTION_TO_SKILL = {
     ),
     "bugfix-phase-implement": checkpoint_step("prizmkit-implement", "Implement Fix", []),
     "bugfix-phase-review": checkpoint_step("prizmkit-code-review", "Code Review", []),
+    "bugfix-phase-test": checkpoint_step(
+        "prizmkit-test", "Post-Review Test Gate",
+        [
+            ".prizmkit/test/evidence/*/manifest.json",
+            ".prizmkit/test/evidence/*/verdict.json",
+            ".prizmkit/test/evidence/*/validation.json",
+        ],
+    ),
     "phase-browser": checkpoint_step("browser-verification", "Browser Verification", []),
     "bugfix-phase-commit-report": checkpoint_group([
         ("prizmkit-retrospective", "Retrospective", []),
@@ -378,6 +412,7 @@ def assemble_bugfix_sections(pipeline_mode, sections_dir, browser_enabled, manua
     sections.extend([
         ("bugfix-phase-implement", load_section(sections_dir, "bugfix-phase-implement.md")),
         ("bugfix-phase-review", load_section(sections_dir, "bugfix-phase-review.md")),
+        ("bugfix-phase-test", load_section(sections_dir, "bugfix-phase-test.md")),
     ])
     if browser_enabled:
         browser_section_file = {
@@ -395,6 +430,7 @@ def assemble_bugfix_sections(pipeline_mode, sections_dir, browser_enabled, manua
         ])
         return sections
     sections.extend([
+        ("headless-commit-authorization", load_section(sections_dir, "headless-commit-authorization.md")),
         ("bugfix-phase-commit-report", load_section(sections_dir, "bugfix-phase-commit-report.md")),
         ("bugfix-session-status", load_section(sections_dir, "bugfix-session-status.md")),
         ("bugfix-critical-paths", load_section(sections_dir, "bugfix-critical-paths.md")),
@@ -412,6 +448,7 @@ def generate_bugfix_checkpoint(bug_id, session_id, pipeline_mode="standard", sec
             ("bugfix-phase-diagnose-plan", ""),
             ("bugfix-phase-implement", ""),
             ("bugfix-phase-review", ""),
+            ("bugfix-phase-test", ""),
             ("bugfix-phase-commit-report", ""),
         ]
     return generate_checkpoint_from_sections(
@@ -428,7 +465,11 @@ def generate_bugfix_checkpoint(bug_id, session_id, pipeline_mode="standard", sec
 
 def merge_bugfix_checkpoint_state(existing, fresh, project_root):
     """Merge existing bugfix checkpoint state into fresh definition."""
-    return merge_checkpoint_state(existing, fresh, project_root, logger=LOGGER)
+    merged = merge_checkpoint_state(existing, fresh, project_root, logger=LOGGER)
+    existing_state = existing.get("bugfix_state")
+    if isinstance(existing_state, dict):
+        merged["bugfix_state"] = existing_state
+    return merged
 
 
 def emit_failure(message):
@@ -503,6 +544,18 @@ def main():
     checkpoint = generate_bugfix_checkpoint(
         args.bug_id, args.session_id, pipeline_mode, sections if use_sections else None,
     )
+    if not any(step.get("skill") == "prizmkit-test" for step in checkpoint["steps"]):
+        emit_failure("Bugfix checkpoint is missing the mandatory prizmkit-test stage")
+    checkpoint["bugfix_state"] = bugfix_checkpoint_metadata(
+        replacements["{{ARTIFACT_DIR}}"],
+        stage="plan",
+        status="PLAN_READY",
+        stage_result=None,
+        repair_scope=None,
+        repair_round=0,
+        next_stage="prizmkit-implement",
+        resume_from="prizmkit-implement",
+    )
 
     if (args.resume_phase != "null" or is_continuation(args)) and os.path.exists(checkpoint_path):
         try:

package/bundled/dev-pipeline/scripts/generate-refactor-prompt.py

@@ -22,9 +22,11 @@ from prompt_framework import (
     merge_checkpoint_state,
     mode_agent_count,
     normalize_mode,
+    pipeline_checkpoint_metadata,
     read_text_file,
     render_from_sections,
     replace_placeholders,
+    route_pipeline_repair,
     validate_rendered,
     write_output,
 )
@@ -34,6 +36,30 @@ from utils import enrich_global_context, helper_replacements, load_json_file, re
 LOGGER = setup_logging("generate-refactor-prompt")
 
 
+def route_refactor_repair(stage_result, repair_scope=None, repair_round=0):
+    """Map Refactor review/test outcomes to the shared safe route contract."""
+    return route_pipeline_repair(stage_result, repair_scope, repair_round)
+
+
+def refactor_checkpoint_metadata(artifact_dir, evidence=None, stage="plan",
+                                 status="PLAN_READY", stage_result=None,
+                                 repair_scope=None, repair_round=0,
+                                 next_stage="prizmkit-implement",
+                                 resume_from="prizmkit-implement"):
+    """Build Refactor L4 handoff metadata while preserving Refactor L1 state."""
+    return pipeline_checkpoint_metadata(
+        artifact_dir,
+        evidence=evidence,
+        stage=stage,
+        status=status,
+        stage_result=stage_result,
+        repair_scope=repair_scope,
+        repair_round=repair_round,
+        next_stage=next_stage,
+        resume_from=resume_from,
+    )
+
+
 REFACTOR_SECTION_TO_SKILL = {
     "refactor-phase-init": checkpoint_step("prizmkit-init", "Initialize", [".prizmkit/refactor/{slug}"]),
     "refactor-phase-plan": checkpoint_step(
@@ -48,6 +74,14 @@ REFACTOR_SECTION_TO_SKILL = {
         "prizmkit-code-review", "Review — Code Review & Behavior Verification",
         [".prizmkit/refactor/{slug}/review-report.md"],
     ),
+    "refactor-phase-test": checkpoint_step(
+        "prizmkit-test", "Post-Review Test Gate",
+        [
+            ".prizmkit/test/evidence/*/manifest.json",
+            ".prizmkit/test/evidence/*/verdict.json",
+            ".prizmkit/test/evidence/*/validation.json",
+        ],
+    ),
     "phase-browser": checkpoint_step("browser-verification", "Browser Verification", []),
     "refactor-phase-commit-report": checkpoint_group([
         ("prizmkit-retrospective", "Retrospective", []),
@@ -399,6 +433,7 @@ def assemble_refactor_sections(pipeline_mode, sections_dir, browser_enabled, bro
     sections.extend([
         ("refactor-phase-implement", load_section(sections_dir, "refactor-phase-implement.md")),
         ("refactor-phase-review", load_section(sections_dir, "refactor-phase-review.md")),
+        ("refactor-phase-test", load_section(sections_dir, "refactor-phase-test.md")),
     ])
     if browser_enabled:
         browser_section_file = {
@@ -407,6 +442,7 @@ def assemble_refactor_sections(pipeline_mode, sections_dir, browser_enabled, bro
         }.get(browser_tool, "phase-browser-verification-auto.md")
         sections.append(("phase-browser", load_section(sections_dir, browser_section_file)))
     sections.extend([
+        ("headless-commit-authorization", load_section(sections_dir, "headless-commit-authorization.md")),
         ("refactor-phase-commit-report", load_section(sections_dir, "refactor-phase-commit-report.md")),
         ("refactor-session-status", load_section(sections_dir, "refactor-session-status.md")),
         ("refactor-critical-paths", load_section(sections_dir, "refactor-critical-paths.md")),
@@ -423,6 +459,7 @@ def generate_refactor_checkpoint(refactor_id, session_id, pipeline_mode="standar
             ("refactor-phase-plan", ""),
             ("refactor-phase-implement", ""),
             ("refactor-phase-review", ""),
+            ("refactor-phase-test", ""),
             ("refactor-phase-commit-report", ""),
         ]
     return generate_checkpoint_from_sections(
@@ -438,7 +475,11 @@ def generate_refactor_checkpoint(refactor_id, session_id, pipeline_mode="standar
 
 
 def merge_refactor_checkpoint_state(existing, fresh, project_root):
-    return merge_checkpoint_state(existing, fresh, project_root, logger=LOGGER)
+    merged = merge_checkpoint_state(existing, fresh, project_root, logger=LOGGER)
+    existing_state = existing.get("refactor_state")
+    if isinstance(existing_state, dict):
+        merged["refactor_state"] = existing_state
+    return merged
 
 
 def emit_failure(message):
@@ -511,6 +552,18 @@ def main():
     checkpoint = generate_refactor_checkpoint(
         args.refactor_id, args.session_id, pipeline_mode, sections if use_sections else None,
     )
+    if not any(step.get("skill") == "prizmkit-test" for step in checkpoint["steps"]):
+        emit_failure("Refactor checkpoint is missing the mandatory prizmkit-test stage")
+    checkpoint["refactor_state"] = refactor_checkpoint_metadata(
+        replacements["{{ARTIFACT_DIR}}"],
+        stage="plan",
+        status="PLAN_READY",
+        stage_result=None,
+        repair_scope=None,
+        repair_round=0,
+        next_stage="prizmkit-implement",
+        resume_from="prizmkit-implement",
+    )
 
     if (args.resume_phase != "null" or is_continuation(args)) and os.path.exists(checkpoint_path):
         try: