prizmkit 1.1.154 → 1.1.156

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

@@ -20,7 +20,6 @@ from prompt_framework import (
     generate_checkpoint_from_sections,
     load_section,
     merge_checkpoint_state,
-    normalize_mode,
     pipeline_checkpoint_metadata,
     read_text_file,
     render_from_sections,
@@ -81,11 +80,17 @@ REFACTOR_SECTION_TO_SKILL = {
     ),
     "phase-browser": checkpoint_step("browser-verification", "Browser Verification", []),
     "refactor-phase-commit-report": checkpoint_group([
-        ("prizmkit-retrospective", "Retrospective", []),
-        ("prizmkit-committer", "Commit", []),
         ("refactor-report", "Generate Refactor Report", [".prizmkit/refactor/{slug}/refactor-report.md"]),
         ("completion-summary", "Completion Summary", [".prizmkit/refactor/{slug}/completion-summary.json"]),
     ]),
+    "retrospective": checkpoint_step(
+        "prizmkit-retrospective", "Retrospective",
+        [".prizmkit/refactor/{slug}/retrospective-result.json"],
+    ),
+    "runtime-commit-handoff": checkpoint_step(
+        "prizmkit-committer", "Runtime Commit Handoff",
+        [".prizmkit/refactor/{slug}/runtime-commit-request.json"],
+    ),
 }
 
 REFACTOR_SPLIT_STEPS = {}
@@ -107,8 +112,12 @@ def parse_args():
     parser.add_argument("--state-dir", default=None, help="State directory (default: .prizmkit/state/refactor)")
     parser.add_argument("--output", required=True, help="Output path for the rendered prompt")
     parser.add_argument("--project-root", default=None, help="AI-visible project root used for rendered prompt paths")
+    parser.add_argument(
+        "--no-checkpoint-write",
+        action="store_true",
+        help="Render and validate a preview without creating or updating checkpoint state",
+    )
     parser.add_argument("--template", default=None, help="Custom legacy template path. Defaults to section assembly.")
-    parser.add_argument("--mode", choices=["lite", "standard", "full"], default=None, help="Pipeline execution mode override")
     add_continuation_args(parser, "refactor")
     return parser.parse_args()
 
@@ -189,15 +198,39 @@ def format_scope_modules(scope):
     return _format_scope_list(scope, "modules")
 
 
+def _test_path_list(value):
+    if not isinstance(value, list):
+        return []
+    return [str(item) for item in value if str(item).strip()]
+
+
+def format_existing_tests(value):
+    if isinstance(value, bool):
+        coverage = "yes" if value else "no"
+        return "- Coverage declared: {} (specific test paths not supplied)".format(coverage)
+    tests = _test_path_list(value)
+    if tests:
+        return "\n".join("- `{}`".format(test) for test in tests)
+    return "- (none specified)"
+
+
 def format_behavior_preservation(bp):
     if not bp or not isinstance(bp, dict):
         return "- (no behavior preservation details)"
     lines = ["- **Strategy**: {}".format(bp.get("strategy", "unknown"))]
-    existing_tests = bp.get("existing_tests", [])
-    if existing_tests:
-        lines.append("- **Existing Tests**:")
-        lines.extend("  - `{}`".format(test) for test in existing_tests)
-    new_tests_needed = bp.get("new_tests_needed", [])
+    existing_tests = bp.get("existing_tests")
+    if isinstance(existing_tests, bool):
+        lines.append(
+            "- **Existing Tests Cover Scope**: {}".format(
+                "yes" if existing_tests else "no"
+            )
+        )
+    else:
+        tests = _test_path_list(existing_tests)
+        if tests:
+            lines.append("- **Existing Tests**:")
+            lines.extend("  - `{}`".format(test) for test in tests)
+    new_tests_needed = _test_path_list(bp.get("new_tests_needed"))
     if new_tests_needed:
         lines.append("- **New Tests Needed**:")
         lines.extend("  - {}".format(test) for test in new_tests_needed)
@@ -289,46 +322,24 @@ def _args_project_root(args, script_dir):
     return resolve_project_root(script_dir)
 
 
-def determine_refactor_mode(args, refactor):
-    if args.mode:
-        return args.mode
-    priority = str(refactor.get("priority", "medium")).lower()
-    complexity = str(refactor.get("complexity", "medium")).lower()
-    if priority == "critical" and complexity in ("high", "critical"):
-        return "full"
-    if complexity in ("high", "critical"):
-        return "standard"
-    return normalize_mode({"low": "lite", "medium": "lite"}.get(complexity, "lite"))
-
-
 def build_replacements(args, refactor, refactors, global_context, script_dir):
     project_root = _args_project_root(args, script_dir)
     resolve_prompt_platform(project_root)
 
-    state_dir = (
-        os.path.abspath(args.state_dir)
-        if args.state_dir
-        else os.path.join(project_root, ".prizmkit", "state", "refactor")
-    )
-    session_status_path = os.path.join(state_dir, args.refactor_id, "sessions", args.session_id, "session-status.json")
-
     scope = refactor.get("scope", {})
     bp = refactor.get("behavior_preservation", {})
     behavior_strategy = bp.get("strategy", "test-gate") if isinstance(bp, dict) else "test-gate"
-    existing_tests = bp.get("existing_tests", []) if isinstance(bp, dict) else []
-    if not isinstance(existing_tests, list):
-        existing_tests = []
-    new_tests_needed = bp.get("new_tests_needed", []) if isinstance(bp, dict) else []
-    if not isinstance(new_tests_needed, list):
-        new_tests_needed = []
-    existing_tests_str = "\n".join("- `{}`".format(test) for test in existing_tests) if existing_tests else "- (none specified)"
+    existing_tests = bp.get("existing_tests") if isinstance(bp, dict) else None
+    new_tests_needed = _test_path_list(
+        bp.get("new_tests_needed") if isinstance(bp, dict) else None
+    )
+    existing_tests_str = format_existing_tests(existing_tests)
     new_tests_str = "\n".join("- {}".format(test) for test in new_tests_needed) if new_tests_needed else "- (none specified)"
 
     browser_enabled, browser_tool, browser_verify_steps, browser_blocking = browser_enabled_from_item(refactor)
     dev_port = detect_dev_server_port(project_root)
     dev_url = "http://localhost:{}".format(dev_port) if dev_port.isdigit() else "<UNKNOWN_DETECT_FROM_PROJECT_CONFIG>"
 
-    pipeline_mode = determine_refactor_mode(args, refactor)
     replacements = {
         "{{SESSION_LOG_PATH}}": os.path.join(".prizmkit", "state", "refactor", args.refactor_id, "sessions", args.session_id, "logs", "session.log"),
         "{{RUN_ID}}": args.run_id,
@@ -346,16 +357,15 @@ def build_replacements(args, refactor, refactors, global_context, script_dir):
         "{{NEW_TESTS_NEEDED}}": new_tests_str,
         "{{PRIORITY}}": refactor.get("priority", "medium"),
         "{{COMPLEXITY}}": refactor.get("complexity", "medium"),
-        "{{PIPELINE_MODE}}": pipeline_mode,
         "{{REFACTOR_DESCRIPTION}}": refactor.get("description", ""),
         "{{USER_CONTEXT}}": format_user_context(refactor.get("user_context", [])),
         "{{ACCEPTANCE_CRITERIA}}": format_acceptance_criteria(refactor.get("acceptance_criteria", [])),
         "{{AC_CHECKLIST}}": format_ac_checklist(refactor.get("acceptance_criteria", [])),
         "{{DEPENDENCIES}}": format_dependencies(refactor.get("dependencies", []), refactors),
         "{{GLOBAL_CONTEXT}}": format_global_context(global_context, project_root),
-        "{{SESSION_STATUS_PATH}}": session_status_path,
         "{{PROJECT_ROOT}}": project_root,
         "{{ARTIFACT_DIR}}": ".prizmkit/refactor/{}".format(args.refactor_id),
+        "{{FAMILY_ARTIFACTS}}": "├── refactor-report.md\n├── completion-summary.json",
         "{{CHECKPOINT_PATH}}": os.path.join(".prizmkit", "refactor", args.refactor_id, "workflow-checkpoint.json"),
         "{{CHECKPOINT_SYSTEM}}": read_checkpoint_system_section(script_dir),
         "{{TIMESTAMP}}": "",
@@ -404,24 +414,22 @@ def render_template(template_content, replacements, resume_phase, refactor):
     return replace_placeholders(process_conditional_blocks(template_content, resume_phase, refactor), replacements)
 
 
-def _refactor_header(pipeline_mode):
-    title = "# Dev-Pipeline Refactor Session Bootstrap — {}\n".format(pipeline_mode.title())
-    desc = {
-        "lite": "**Tier 1 — Scoped Refactor Guidance**: use the active skills and runtime contracts for planning, implementation, review, and behavior verification.",
-        "standard": "**Tier 2 — Refactor Review Gates**: use the active skills and runtime contracts for planning, implementation, review, and behavior verification.",
-        "full": "**Tier 3 — Full Refactor Guardrails**: use the active skills and runtime contracts for planning, implementation, review, recovery, and behavior verification.",
-    }.get(pipeline_mode, "**Refactor pipeline**")
-    return title + "\n" + desc + "\n"
+def _refactor_header():
+    return (
+        "# Dev-Pipeline Refactor Session Bootstrap — Canonical Guidance\n\n"
+        "Use the active skills and runtime contracts for planning, implementation, "
+        "review, behavior verification, retrospective, and runtime-owned commit execution.\n"
+    )
 
 
-def assemble_refactor_sections(pipeline_mode, sections_dir, browser_enabled, browser_tool="auto"):
+def assemble_refactor_sections(sections_dir, browser_enabled, browser_tool="auto"):
     sections = [
-        ("header", _refactor_header(pipeline_mode)),
+        ("header", _refactor_header()),
         ("refactor-session-context", load_section(sections_dir, "refactor-session-context.md")),
         ("mission", load_section(sections_dir, "refactor-mission.md")),
         ("refactor-task-contract", load_section(sections_dir, "refactor-task-contract.md")),
         ("context-budget-rules", load_section(sections_dir, "context-budget-rules.md")),
-        ("refactor-artifacts", load_section(sections_dir, "refactor-artifacts.md")),
+        ("artifact-manifest", load_section(sections_dir, "artifact-manifest.md")),
         ("checkpoint-system", load_section(sections_dir, "checkpoint-system.md")),
         ("execution-header", "---\n\n## Execution\n"),
         ("refactor-phase-init", load_section(sections_dir, "refactor-phase-init.md")),
@@ -430,7 +438,6 @@ 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 = {
@@ -439,9 +446,10 @@ 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-test", load_section(sections_dir, "refactor-phase-test.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")),
+        ("retrospective", load_section(sections_dir, "retrospective.md")),
+        ("runtime-commit-handoff", load_section(sections_dir, "runtime-commit-handoff.md")),
         ("refactor-critical-paths", load_section(sections_dir, "refactor-critical-paths.md")),
         ("failure-capture", load_section(sections_dir, "failure-capture.md")),
         ("refactor-reminders", load_section(sections_dir, "refactor-reminders.md")),
@@ -449,20 +457,27 @@ def assemble_refactor_sections(pipeline_mode, sections_dir, browser_enabled, bro
     return sections
 
 
-def generate_refactor_checkpoint(refactor_id, session_id, pipeline_mode="standard", sections=None):
+def generate_refactor_checkpoint(
+    refactor_id, session_id, sections=None, *, browser_enabled=False,
+):
     if sections is None:
         sections = [
             ("refactor-phase-init", ""),
             ("refactor-phase-plan", ""),
             ("refactor-phase-implement", ""),
             ("refactor-phase-review", ""),
+        ]
+        if browser_enabled:
+            sections.append(("phase-browser", ""))
+        sections.extend([
             ("refactor-phase-test", ""),
             ("refactor-phase-commit-report", ""),
-        ]
+            ("retrospective", ""),
+            ("runtime-commit-handoff", ""),
+        ])
     return generate_checkpoint_from_sections(
         sections,
         REFACTOR_SECTION_TO_SKILL,
-        pipeline_mode,
         "refactor-pipeline",
         refactor_id,
         refactor_id,
@@ -504,7 +519,6 @@ def main():
         global_context = {}
 
     replacements = build_replacements(args, refactor, refactors, global_context, script_dir)
-    pipeline_mode = replacements["{{PIPELINE_MODE}}"]
     browser_enabled = replacements["{{BROWSER_ENABLED}}"] == "true"
 
     use_sections = os.path.isdir(sections_dir) and not args.template
@@ -512,16 +526,17 @@ def main():
     if use_sections:
         try:
             sections = assemble_refactor_sections(
-                pipeline_mode, sections_dir, browser_enabled,
+                sections_dir, browser_enabled,
                 browser_tool=replacements["{{BROWSER_TOOL}}"],
             )
             rendered = render_from_sections(sections, replacements)
         except FileNotFoundError as exc:
-            LOGGER.warning("Refactor section assembly failed (%s), falling back to legacy template", exc)
-            use_sections = False
+            emit_failure("Refactor section assembly failed: {}".format(exc))
 
     if not use_sections:
-        template_path = args.template or os.path.join(templates_dir, "refactor-bootstrap-prompt.md")
+        if not args.template:
+            emit_failure("Canonical Refactor prompt sections are unavailable")
+        template_path = args.template
         template_content, err = read_text_file(template_path)
         if err:
             emit_failure("Template error: {}".format(err))
@@ -537,7 +552,7 @@ def main():
         logger=LOGGER,
     )
     if not is_valid:
-        LOGGER.error("Rendered refactor prompt failed validation: %s", "; ".join(errors))
+        emit_failure("Rendered refactor prompt failed validation: {}".format("; ".join(errors)))
 
     err = write_output(args.output, rendered)
     if err:
@@ -545,9 +560,13 @@ def main():
 
     project_root = _args_project_root(args, script_dir)
     checkpoint_path = os.path.join(project_root, replacements["{{CHECKPOINT_PATH}}"])
-    os.makedirs(os.path.dirname(checkpoint_path), exist_ok=True)
+    if not args.no_checkpoint_write:
+        os.makedirs(os.path.dirname(checkpoint_path), exist_ok=True)
     checkpoint = generate_refactor_checkpoint(
-        args.refactor_id, args.session_id, pipeline_mode, sections if use_sections else None,
+        args.refactor_id,
+        args.session_id,
+        sections if use_sections else None,
+        browser_enabled=browser_enabled,
     )
     if not any(step.get("skill") == "prizmkit-test" for step in checkpoint["steps"]):
         emit_failure("Refactor checkpoint is missing the mandatory prizmkit-test stage")
@@ -562,7 +581,7 @@ def main():
         resume_from="prizmkit-implement",
     )
 
-    if (args.resume_phase != "null" or is_continuation(args)) and os.path.exists(checkpoint_path):
+    if not args.no_checkpoint_write and (args.resume_phase != "null" or is_continuation(args)) and os.path.exists(checkpoint_path):
         try:
             with open(checkpoint_path, "r", encoding="utf-8") as f:
                 existing = json.load(f)
@@ -571,14 +590,32 @@ def main():
         except (json.JSONDecodeError, KeyError) as exc:
             LOGGER.warning("Existing refactor checkpoint corrupted (%s) — generating fresh", exc)
 
-    with open(checkpoint_path, "w", encoding="utf-8") as f:
-        json.dump(checkpoint, f, indent=2, ensure_ascii=False)
-    LOGGER.info("Wrote refactor checkpoint to %s", checkpoint_path)
+    if not args.no_checkpoint_write:
+        with open(checkpoint_path, "w", encoding="utf-8") as f:
+            json.dump(checkpoint, f, indent=2, ensure_ascii=False)
+        LOGGER.info("Wrote refactor checkpoint to %s", checkpoint_path)
 
     if is_continuation(args):
         rendered = append_continuation_handoff(
             rendered, args, project_root, args.task_type, args.refactor_id, args.refactor_id, checkpoint,
         )
+        final_valid, final_warnings, final_errors = validate_rendered(
+            rendered,
+            required_markers=[
+                ("## Your Mission", "Mission section"),
+                ("## Execution", "Execution section"),
+                ("## Failure Capture", "Failure Capture Protocol"),
+            ],
+            logger=LOGGER,
+        )
+        if not final_valid:
+            emit_failure(
+                "Rendered refactor continuation prompt failed validation: {}".format(
+                    "; ".join(final_errors)
+                )
+            )
+        warnings.extend(final_warnings)
+        errors.extend(final_errors)
         err = write_output(args.output, rendered)
         if err:
             emit_failure(err)
@@ -586,9 +623,8 @@ def main():
     output = {
         "success": True,
         "output_path": os.path.abspath(args.output),
-        "checkpoint_path": checkpoint_path,
+        "checkpoint_path": "" if args.no_checkpoint_write else checkpoint_path,
         "model": refactor.get("model", ""),
-        "pipeline_mode": pipeline_mode,
         "render_mode": "sections" if use_sections else "legacy",
         "validation_warnings": len(warnings),
         "validation_errors": len(errors),

package/bundled/dev-pipeline/scripts/prompt_framework.py

@@ -16,6 +16,7 @@ if _PIPELINE_ROOT not in sys.path:
 
 from prizmkit_runtime.checkpoint_state import (  # noqa: E402
     VALID_CHECKPOINT_STATUSES,
+    VALID_REPAIR_SCOPES,
     expected_status_for_stage_result,
 )
 from prizmkit_runtime.test_result import valid_test_artifact_pair  # noqa: E402
@@ -48,9 +49,11 @@ def route_pipeline_repair(stage_result, repair_scope=None, repair_round=0):
     }
     if stage_result == "TEST_PASS":
         result.update(
-            next_stage="prizmkit-retrospective",
-            resume_from="prizmkit-retrospective",
-            reason="project-native tests passed",
+            resumable=True,
+            next_stage="family-report",
+            resume_from="family-report",
+            route=["family-report", "prizmkit-retrospective"],
+            reason="project-native tests passed; family reports precede retrospective",
         )
         return result
     if stage_result == "TEST_BLOCKED":
@@ -62,16 +65,7 @@ def route_pipeline_repair(stage_result, repair_scope=None, repair_round=0):
             terminal_status="WORKFLOW_BLOCKED",
         )
         return result
-    if stage_result == "TEST_NEEDS_FIXES":
-        result.update(
-            blocked=True,
-            resumable=False,
-            reason="prizmkit-test stopped with a known remaining correction",
-            blocked_reason="test_needs_fixes",
-            terminal_status="WORKFLOW_BLOCKED",
-        )
-        return result
-    if stage_result != "REVIEW_NEEDS_FIXES":
+    if stage_result not in {"REVIEW_NEEDS_FIXES", "TEST_NEEDS_FIXES"}:
         result.update(
             blocked=True,
             reason="unknown stage result is unsafe",
@@ -87,13 +81,27 @@ def route_pipeline_repair(stage_result, repair_scope=None, repair_round=0):
             terminal_status="WORKFLOW_BLOCKED",
         )
         return result
+    if repair_scope not in VALID_REPAIR_SCOPES:
+        result.update(
+            blocked=True,
+            reason="repair scope is missing or unsafe",
+            blocked_reason="unsafe_repair_scope",
+            terminal_status="WORKFLOW_BLOCKED",
+        )
+        return result
 
     result["repair_round"] = current_round + 1
+    reason = (
+        "test findings require implementation, fresh review, and fresh testing"
+        if stage_result == "TEST_NEEDS_FIXES"
+        else "review findings require implementation and fresh review"
+    )
     result.update(
+        resumable=True,
         next_stage="prizmkit-implement",
         resume_from="prizmkit-implement",
         route=["prizmkit-implement", "prizmkit-code-review", "prizmkit-test"],
-        reason="review findings require implementation and fresh review",
+        reason=reason,
     )
     return result
 
@@ -117,7 +125,7 @@ def pipeline_checkpoint_metadata(artifact_dir, stage="plan",
     return {
         "schema_version": 1,
         "artifact_dir": artifact_dir,
-        "orchestrator": "prizmkit-l4",
+        "orchestrator": "pipeline-runtime",
         "stage": stage,
         "current_stage": current_stage,
         "status": status,
@@ -176,7 +184,7 @@ def validate_rendered(content, required_markers=None, logger=None):
 
     unreplaced = re.findall(r"\{\{[A-Z][A-Z_0-9]+\}\}", content)
     if unreplaced:
-        warnings.append(
+        errors.append(
             "Unreplaced placeholders: {}".format(", ".join(sorted(set(unreplaced))))
         )
 
@@ -309,7 +317,6 @@ def _contract_steps(contract):
 def generate_checkpoint_from_sections(
     sections,
     step_mapping,
-    pipeline_mode,
     workflow_type,
     item_id,
     item_slug,
@@ -359,7 +366,6 @@ def generate_checkpoint_from_sections(
     return {
         "version": 1,
         "workflow_type": workflow_type,
-        "pipeline_mode": pipeline_mode,
         "item_id": item_id,
         "item_slug": item_slug,
         "session_id": session_id,
@@ -409,10 +415,18 @@ def merge_checkpoint_state(existing, fresh, project_root, validator=None, logger
             artifacts = step.get("required_artifacts", [])
             skill = step.get("skill", "")
             stage_result = previous.get("stage_result") if isinstance(previous, dict) else None
-            verdict_valid = (
-                (skill != "prizmkit-code-review" or stage_result == "REVIEW_PASS")
-                and (skill != "prizmkit-test" or stage_result == "TEST_PASS")
-            )
+            expected_results = {
+                "context-snapshot-and-plan": "PLAN_READY",
+                "bug-diagnosis-and-plan": "PLAN_READY",
+                "prizmkit-plan": "PLAN_READY",
+                "prizmkit-implement": "IMPLEMENTED",
+                "prizmkit-code-review": "REVIEW_PASS",
+                "prizmkit-test": "TEST_PASS",
+                "prizmkit-retrospective": "RETRO_COMPLETE",
+                "prizmkit-committer": "COMMITTED",
+            }
+            expected_result = expected_results.get(skill)
+            verdict_valid = expected_result is None or stage_result == expected_result
             if verdict_valid and validator(skill, artifacts):
                 step["status"] = "completed"
                 if stage_result:
@@ -441,25 +455,6 @@ def merge_checkpoint_state(existing, fresh, project_root, validator=None, logger
     return fresh
 
 
-def determine_mode_from_complexity(value):
-    """Map a coarse complexity/severity value to lite/standard/full."""
-    mapping = {
-        "low": "lite",
-        "medium": "lite",
-        "minor": "lite",
-        "high": "standard",
-        "major": "standard",
-        "critical": "full",
-    }
-    return mapping.get(str(value or "").lower(), "lite")
-
-
-def normalize_mode(value, default="lite"):
-    """Normalize a mode string to lite/standard/full."""
-    value = str(value or "").lower()
-    return value if value in {"lite", "standard", "full"} else default
-
-
 def detect_dev_server_port(project_root):
     """Return a detected dev-server port string, or an unknown placeholder."""
     unknown = "<UNKNOWN_DETECT_FROM_PROJECT_CONFIG>"

package/bundled/dev-pipeline/scripts/update-bug-status.py

@@ -1003,11 +1003,8 @@ def action_status(bug_list_data, state_dir, project_root=None):
         bs = load_bug_status(state_dir, bid)
         retry_count = bs.get("retry_count", 0)
         max_retries_val = bs.get("max_retries", 3)
-        # Read phase cursor from checkpoint (authoritative when valid).
+        # Read the authoritative checkpoint cursor without mutating cached runtime state.
         resume_phase = _checkpoint_phase_or_cached(project_root, bid, bs)
-        if resume_phase != bs.get("resume_from_phase"):
-            bs["resume_from_phase"] = resume_phase
-            save_bug_status(state_dir, bid, bs)
 
         if bstatus in counts:
             counts[bstatus] += 1

package/bundled/dev-pipeline/scripts/update-checkpoint.py

@@ -14,6 +14,7 @@ if _PIPELINE_ROOT not in sys.path:
 
 from prizmkit_runtime.checkpoint_state import (  # noqa: E402
     MAX_OUTER_REPAIR_ROUNDS,
+    PLAN_RESULTS,
     REVIEW_RESULTS,
     SKILL_WORKFLOW_STAGES,
     STEP_ID_PATTERN,
@@ -110,9 +111,16 @@ def _mandatory_predecessor_verdict_error(steps, index, workflow_type):
     preceding = steps[:index]
     review = next((item for item in preceding if item.get("skill") == "prizmkit-code-review"), None)
     test = next((item for item in preceding if item.get("skill") == "prizmkit-test"), None)
+    skill = steps[index].get("skill")
+    if skill == "prizmkit-implement":
+        planning = [
+            item for item in preceding
+            if item.get("stage_result") in PLAN_RESULTS
+        ]
+        if len(planning) != 1 or planning[0].get("status") != "completed" or planning[0].get("stage_result") != "PLAN_READY":
+            return "Implementation requires a completed PLAN_READY predecessor"
     if review is None and test is None:
         return None
-    skill = steps[index].get("skill")
     if skill == "prizmkit-test":
         if not review or review.get("status") != "completed" or review.get("stage_result") != "REVIEW_PASS":
             return "Test stage requires a completed REVIEW_PASS predecessor"
@@ -170,23 +178,27 @@ def _validate_semantic_update(step, semantic_update):
 
 
 def _apply_repair_policy(l4_state, stage_result, repair_scope):
-    if stage_result not in {"REVIEW_NEEDS_FIXES", "TEST_NEEDS_FIXES", "TEST_BLOCKED"}:
-        return False
-    current_round = l4_state.get("repair_round", 0)
-    if not isinstance(current_round, int) or isinstance(current_round, bool):
-        current_round = MAX_OUTER_REPAIR_ROUNDS
-    if stage_result in {"TEST_NEEDS_FIXES", "TEST_BLOCKED"}:
+    terminal_blockers = {
+        "PLAN_BLOCKED": "plan_blocked",
+        "IMPLEMENT_REPAIR": "implementation_repair",
+        "IMPLEMENT_BLOCKED": "implementation_blocked",
+        "TEST_BLOCKED": "test_blocked",
+        "RETRO_BLOCKED": "retrospective_blocked",
+        "COMMIT_BLOCKED": "commit_blocked",
+    }
+    if stage_result in terminal_blockers:
         l4_state.update(
             terminal_status="WORKFLOW_BLOCKED",
-            blocked_reason=(
-                "test_needs_fixes"
-                if stage_result == "TEST_NEEDS_FIXES"
-                else "test_blocked"
-            ),
+            blocked_reason=terminal_blockers[stage_result],
             current_stage=None,
             next_stage=None,
         )
         return False
+    if stage_result not in {"REVIEW_NEEDS_FIXES", "TEST_NEEDS_FIXES"}:
+        return False
+    current_round = l4_state.get("repair_round", 0)
+    if not isinstance(current_round, int) or isinstance(current_round, bool):
+        current_round = MAX_OUTER_REPAIR_ROUNDS
     if current_round >= MAX_OUTER_REPAIR_ROUNDS:
         l4_state.update(
             repair_round=MAX_OUTER_REPAIR_ROUNDS,
@@ -205,12 +217,36 @@ def _apply_repair_policy(l4_state, stage_result, repair_scope):
         )
         return False
     l4_state["repair_round"] = current_round + 1
+    l4_state["repair_scope"] = repair_scope
     l4_state["terminal_status"] = None
     l4_state["blocked_reason"] = None
     l4_state["next_stage"] = "prizmkit-implement"
     return True
 
 
+def _prepare_repair_reentry(data, index):
+    """Rewind downstream gates when a routed repair re-enters implementation."""
+    step = data["steps"][index]
+    if step.get("skill") != "prizmkit-implement":
+        return
+    state_key = semantic_state_key(str(data.get("workflow_type") or ""))
+    l4_state = data.get(state_key)
+    if not isinstance(l4_state, dict):
+        return
+    if (
+        l4_state.get("next_stage") != "prizmkit-implement"
+        or l4_state.get("stage_result")
+        not in {"REVIEW_NEEDS_FIXES", "TEST_NEEDS_FIXES"}
+    ):
+        return
+    for later in data["steps"][index + 1:]:
+        later["status"] = "pending"
+        later.pop("stage_result", None)
+        later.pop("note", None)
+    l4_state["terminal_status"] = None
+    l4_state["blocked_reason"] = None
+
+
 def _sync_cursor(data, l4_state, preserve_next_stage=False):
     active = next(
         (step for step in data["steps"] if step.get("status") not in TERMINAL_STEP_STATUSES),
@@ -291,6 +327,9 @@ def update_checkpoint(
         suffix = " Available: {}".format(", ".join(available)) if available else ""
         return {"ok": False, "error": "{}{}".format(find_error or "Step not found.", suffix)}
 
+    if new_status == "in_progress":
+        _prepare_repair_reentry(data, index)
+
     if new_status in {"in_progress", "completed", "skipped"} and not _predecessors_terminal(data["steps"], index):
         return {
             "ok": False,
@@ -306,6 +345,11 @@ def update_checkpoint(
             return {"ok": False, "error": verdict_error}
 
     semantic_update = _normalize_semantic_update(semantic_update)
+    if semantic_update.get("stage_result") == "COMMITTED":
+        return {
+            "ok": False,
+            "error": "COMMITTED is Runtime-owned and cannot be written by the Prompt checkpoint helper",
+        }
     semantic_error = _validate_semantic_update(step, semantic_update)
     if semantic_error:
         return {"ok": False, "error": semantic_error}
@@ -319,6 +363,10 @@ def update_checkpoint(
         stage_result = stage_result or step.get("stage_result")
         if stage_result != "TEST_PASS":
             return {"ok": False, "error": "Test completion requires TEST_PASS"}
+    if new_status == "completed" and step.get("skill") == "prizmkit-committer":
+        stage_result = stage_result or step.get("stage_result")
+        if stage_result != "COMMITTED":
+            return {"ok": False, "error": "Committer completion requires Runtime-owned COMMITTED"}
     expected_status = expected_status_for_stage_result(stage_result)
     if expected_status is not None and new_status != expected_status:
         return {
@@ -350,7 +398,7 @@ def update_checkpoint(
         if key in semantic_update:
             l4_state[key] = semantic_update[key]
     l4_state["schema_version"] = 1
-    l4_state["orchestrator"] = "prizmkit-l4"
+    l4_state["orchestrator"] = "pipeline-runtime"
     skill = step.get("skill")
     l4_state["stage"] = SKILL_WORKFLOW_STAGES.get(skill, skill)
     l4_state["status"] = new_status