prizmkit 1.1.148 → 1.1.150

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

@@ -0,0 +1,959 @@
+"""Regression tests for non-destructive failed-chain reset behavior."""
+
+import json
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+PIPELINE_ROOT = REPO_ROOT / "dev-pipeline"
+CLI_PATH = PIPELINE_ROOT / "cli.py"
+if str(PIPELINE_ROOT) not in sys.path:
+    sys.path.insert(0, str(PIPELINE_ROOT))
+
+
+def _make_paths(tmp_path):
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    project = tmp_path / "project"
+    (project / ".prizmkit" / "plans").mkdir(parents=True)
+    return resolve_runtime_paths(pipeline_root=PIPELINE_ROOT, project_root=project)
+
+
+def _write_family_plan(paths, kind, items):
+    plan_config = {
+        "feature": (paths.feature_plan, "features", "dev-pipeline-feature-list-v1"),
+        "bugfix": (paths.bugfix_plan, "bugs", "dev-pipeline-bug-fix-list-v1"),
+        "refactor": (paths.refactor_plan, "refactors", "dev-pipeline-refactor-list-v1"),
+    }
+    plan_path, list_key, schema = plan_config[kind]
+    plan_path.write_text(
+        json.dumps({"$schema": schema, "project_name": "Fake", list_key: items}),
+        encoding="utf-8",
+    )
+    return plan_path
+
+
+def _write_semantic_completion_checkpoint(project_root, artifact_dir, workflow_type="feature-pipeline"):
+    contracts = {
+        "feature-pipeline": (
+            "feature_state",
+            [
+                "prizmkit-implement", "prizmkit-code-review", "prizmkit-test",
+                "prizmkit-retrospective", "prizmkit-committer", "completion-summary",
+            ],
+        ),
+        "bugfix-pipeline": (
+            "bugfix_state",
+            [
+                "prizmkit-implement", "prizmkit-code-review", "prizmkit-test",
+                "prizmkit-retrospective", "prizmkit-committer", "bug-report",
+            ],
+        ),
+        "refactor-pipeline": (
+            "refactor_state",
+            [
+                "prizmkit-implement", "prizmkit-code-review", "prizmkit-test",
+                "prizmkit-retrospective", "prizmkit-committer", "refactor-report",
+                "completion-summary",
+            ],
+        ),
+    }
+    state_key, skills = contracts[workflow_type]
+    steps = []
+    previous = None
+    for index, skill in enumerate(skills, start=1):
+        step = {
+            "id": f"S{index:02d}",
+            "skill": skill,
+            "name": skill,
+            "status": "completed",
+            "required_artifacts": [],
+            "depends_on": previous,
+        }
+        if skill == "prizmkit-implement":
+            step["stage_result"] = "IMPLEMENTED"
+        if skill == "prizmkit-code-review":
+            step["stage_result"] = "REVIEW_PASS"
+        if skill == "prizmkit-test":
+            step["stage_result"] = "TEST_PASS"
+            relative_artifact = artifact_dir.relative_to(project_root)
+            step["required_artifacts"] = [
+                str(relative_artifact / "test-report.md"),
+                str(relative_artifact / "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"]
+    artifact_dir.mkdir(parents=True, exist_ok=True)
+    (artifact_dir / "test-report.md").write_text(
+        "# Test Report\n\n## Final Result\n\n- Result: TEST_PASS\n",
+        encoding="utf-8",
+    )
+    (artifact_dir / "test-result.json").write_text(
+        json.dumps({
+            "schema_version": 1,
+            "result": "TEST_PASS",
+            "report": "test-report.md",
+            "main_review_rounds": 1,
+            "independent_review": {
+                "status": "downgraded",
+                "responses": 0,
+                "downgrade_reason": "read-only capability unavailable",
+                "final_state_rechecked": False,
+            },
+            "repair_rounds": 0,
+            "production_changed": False,
+            "review_required": False,
+            "review_scope": None,
+            "unresolved_items": [],
+        }),
+        encoding="utf-8",
+    )
+    checkpoint = artifact_dir / "workflow-checkpoint.json"
+    checkpoint.write_text(
+        json.dumps({
+            "version": 1,
+            "workflow_type": workflow_type,
+            "steps": steps,
+            state_key: {
+                "repair_round": 0,
+                "terminal_status": "WORKFLOW_COMPLETED",
+            },
+        }),
+        encoding="utf-8",
+    )
+    return checkpoint
+
+
+def _init_preserve_runtime_repo(paths):
+    subprocess.run(["git", "init", "-b", "main"], cwd=paths.project_root, check=True, stdout=subprocess.DEVNULL)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=paths.project_root, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=paths.project_root, check=True)
+    (paths.project_root / "base.txt").write_text("base\n", encoding="utf-8")
+    subprocess.run(["git", "add", "base.txt"], cwd=paths.project_root, check=True)
+    subprocess.run(["git", "commit", "-m", "base"], cwd=paths.project_root, check=True, stdout=subprocess.DEVNULL)
+
+
+def _preserve_family_contract(kind):
+    return {
+        "feature": ("F-", "dev", "feature-pipeline", "specs"),
+        "bugfix": ("B-", "bugfix", "bugfix-pipeline", "bugfix"),
+        "refactor": ("R-", "refactor", "refactor-pipeline", "refactor"),
+    }[kind]
+
+
+def _preserve_item_id(prefix, number):
+    return f"{prefix}{number:03d}"
+
+
+def _preserve_items(kind):
+    prefix, _branch_prefix, _workflow_type, _artifact_root = _preserve_family_contract(kind)
+    statuses = [
+        (1, "failed", []),
+        (2, "auto_skipped", [_preserve_item_id(prefix, 1)]),
+        (3, "auto_skipped", [_preserve_item_id(prefix, 2)]),
+        (4, "completed", []),
+        (5, "skipped", []),
+        (6, "auto_skipped", [_preserve_item_id(prefix, 5)]),
+        (7, "needs_info", []),
+        (8, "pending", []),
+        (9, "split", []),
+    ]
+    return [
+        {
+            "id": _preserve_item_id(prefix, number),
+            "title": "Root" if number == 1 else f"Item {number}",
+            "description": "preserve runtime",
+            "status": status,
+            "priority": "medium",
+            "dependencies": dependencies,
+        }
+        for number, status, dependencies in statuses
+    ]
+
+
+def _write_preserve_runtime_state(paths, kind, item_id, branch, *, base_branch="main"):
+    from prizmkit_runtime.runner_models import family_for
+    from prizmkit_runtime.task_checkout import TaskCheckout, persist_task_checkout
+
+    family = family_for(kind, paths)
+    family.state_dir.mkdir(parents=True, exist_ok=True)
+    (family.state_dir / "pipeline.json").write_text(json.dumps({"status": "failed"}), encoding="utf-8")
+    item_state = family.state_dir / item_id
+    sessions = item_state / "sessions" / "old-session" / "logs"
+    sessions.mkdir(parents=True, exist_ok=True)
+    (sessions / "session.log").write_text("historical log\n", encoding="utf-8")
+    status = {
+        "status": "failed",
+        "retry_count": 7,
+        "infra_error_count": 4,
+        "sessions": ["old-session"],
+        "last_session_id": "old-session",
+        "previous_session_id": "old-session",
+        "last_infra_error_session_id": "old-session",
+        "continuation_pending": False,
+        "continuation_reason": "code_error",
+        "continuation_summary_path": "keep-this-path",
+        "last_progress_fingerprint": {"head": "abc", "checkpoint": "S03"},
+        "no_progress_count": 2,
+        "fatal_error_code": "provider_error",
+        "active_dev_branch": branch,
+        "base_branch": base_branch,
+        "custom_diagnostic": {"reason": "preserve me"},
+    }
+    status_path = item_state / "status.json"
+    status_path.write_text(json.dumps(status, indent=2) + "\n", encoding="utf-8")
+    checkout = TaskCheckout.active(kind, item_id, branch, base_branch)
+    persist_task_checkout(family.state_dir, checkout)
+    return family, status_path, status, checkout
+
+
+@pytest.mark.parametrize("kind", ["feature", "bugfix", "refactor"])
+def test_preserve_runtime_restores_failed_chain_and_preserves_existing_checkout_history(tmp_path, kind):
+    from prizmkit_runtime.reset import run_reset_command
+    from prizmkit_runtime.task_checkout import load_task_checkout
+
+    paths = _make_paths(tmp_path / kind)
+    _init_preserve_runtime_repo(paths)
+    prefix, branch_prefix, workflow_type, artifact_root = _preserve_family_contract(kind)
+    root_id = _preserve_item_id(prefix, 1)
+    plan = _write_family_plan(paths, kind, _preserve_items(kind))
+    branch = f"{branch_prefix}/{root_id}-preserved"
+    subprocess.run(["git", "branch", branch, "main"], cwd=paths.project_root, check=True)
+    family, status_path, before_status, checkout = _write_preserve_runtime_state(paths, kind, root_id, branch)
+    descendant_status = family.state_dir / _preserve_item_id(prefix, 2) / "status.json"
+    descendant_status.parent.mkdir(parents=True, exist_ok=True)
+    descendant_status.write_text(
+        json.dumps({"status": "auto_skipped", "caused_by": root_id, "sessions": ["child-history"]}, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    descendant_status_before = descendant_status.read_bytes()
+    artifact_name = "001-root" if kind == "feature" else root_id
+    artifact = paths.project_root / ".prizmkit" / artifact_root / artifact_name
+    checkpoint = _write_semantic_completion_checkpoint(paths.project_root, artifact, workflow_type)
+    checkpoint_before = checkpoint.read_bytes()
+    session_log = family.state_dir / root_id / "sessions" / "old-session" / "logs" / "session.log"
+    session_before = session_log.read_bytes()
+    branch_head_before = subprocess.run(
+        ["git", "rev-parse", branch], cwd=paths.project_root, check=True, stdout=subprocess.PIPE, text=True
+    ).stdout.strip()
+
+    result = run_reset_command(kind, ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 0, result.render()
+    updated_plan = json.loads(plan.read_text(encoding="utf-8"))
+    statuses = {item["id"]: item["status"] for item in updated_plan[family.list_key]}
+    assert statuses[root_id] == "pending"
+    assert statuses[_preserve_item_id(prefix, 2)] == "pending"
+    assert statuses[_preserve_item_id(prefix, 3)] == "pending"
+    assert statuses[_preserve_item_id(prefix, 4)] == "completed"
+    assert statuses[_preserve_item_id(prefix, 5)] == "skipped"
+    assert statuses[_preserve_item_id(prefix, 6)] == "auto_skipped"
+    assert statuses[_preserve_item_id(prefix, 7)] == "needs_info"
+    assert statuses[_preserve_item_id(prefix, 8)] == "pending"
+    assert statuses[_preserve_item_id(prefix, 9)] == "split"
+    expected_status = dict(before_status)
+    expected_status.update(retry_count=0, infra_error_count=0, continuation_pending=True)
+    assert json.loads(status_path.read_text(encoding="utf-8")) == expected_status
+    assert load_task_checkout(family.state_dir, kind, root_id) == checkout
+    assert descendant_status.read_bytes() == descendant_status_before
+    assert checkpoint.read_bytes() == checkpoint_before
+    assert session_log.read_bytes() == session_before
+    assert subprocess.run(
+        ["git", "rev-parse", branch], cwd=paths.project_root, check=True, stdout=subprocess.PIPE, text=True
+    ).stdout.strip() == branch_head_before
+    assert "Active checkouts reused" in result.render()
+    assert "Reset did not start a runner" in result.render()
+
+
+@pytest.mark.parametrize("kind", ["feature", "bugfix", "refactor"])
+def test_preserve_runtime_no_failed_root_is_a_noop_without_checkout_state(tmp_path, kind):
+    from prizmkit_runtime.reset import run_reset_command
+    from prizmkit_runtime.runner_models import family_for
+
+    paths = _make_paths(tmp_path / kind)
+    items = _preserve_items(kind)
+    items[0]["status"] = "completed"
+    plan = _write_family_plan(paths, kind, items)
+    family = family_for(kind, paths)
+    before = plan.read_bytes()
+
+    result = run_reset_command(kind, ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 0
+    assert "No failed" in result.render()
+    assert plan.read_bytes() == before
+    assert not any((family.state_dir / item["id"] / "checkout.json").exists() for item in items)
+
+
+def test_preserve_runtime_option_boundaries_and_removed_reset_run_do_not_mutate_state(tmp_path):
+    from prizmkit_runtime.reset import ResetOptions, run_reset_command
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+
+    paths = _make_paths(tmp_path)
+    plan = _write_family_plan(paths, "feature", _preserve_items("feature"))
+    family = family_for("feature", paths)
+    family.state_dir.mkdir(parents=True, exist_ok=True)
+    (family.state_dir / "pipeline.json").write_text("{}\n", encoding="utf-8")
+    before = plan.read_bytes()
+    invalid_cases = [
+        (("F-001", "--run"), "no longer accepts --run"),
+        (("--preserve-runtime",), "requires --failed"),
+        (("--failed", "--preserve-runtime", "--clean"), "mutually exclusive"),
+        (("F-001", "--failed", "--preserve-runtime"), "cannot target an ID or range"),
+        (("F-001:F-003", "--failed", "--preserve-runtime"), "cannot target an ID or range"),
+        (("--failed", "--preserve-runtime", "--stalled"), "Unsupported reset arguments"),
+        (("--failed", "--preserve-runtime", "--unknown"), "Unsupported reset arguments"),
+    ]
+
+    for args, message in invalid_cases:
+        result = run_reset_command("feature", args, paths)
+        assert result.exit_code != 0
+        assert message in result.render()
+        assert plan.read_bytes() == before
+    assert "run_after" not in ResetOptions.__dataclass_fields__
+    invocation = parse_invocation(
+        family,
+        "run",
+        ("F-001", "--max-retries", "6", "--max-infra-retries", "7"),
+    )
+    assert invocation.action == "run"
+    assert invocation.item_id == "F-001"
+    assert invocation.max_retries == 6
+    assert invocation.max_infra_retries == 7
+
+
+def test_preserve_runtime_restores_every_failed_root_in_one_successful_pass(tmp_path):
+    from prizmkit_runtime.reset import run_reset_command
+
+    paths = _make_paths(tmp_path)
+    _init_preserve_runtime_repo(paths)
+    items = [
+        {"id": "F-001", "title": "Root One", "status": "failed", "dependencies": []},
+        {"id": "F-002", "title": "Child One", "status": "auto_skipped", "dependencies": ["F-001"]},
+        {"id": "F-003", "title": "Root Two", "status": "failed", "dependencies": []},
+        {"id": "F-004", "title": "Child Two", "status": "auto_skipped", "dependencies": ["F-003"]},
+        {"id": "F-005", "title": "Done", "status": "completed", "dependencies": []},
+    ]
+    plan = _write_family_plan(paths, "feature", items)
+    before_statuses = {}
+    for item_id in ("F-001", "F-003"):
+        branch = f"dev/{item_id}-existing"
+        subprocess.run(["git", "branch", branch, "main"], cwd=paths.project_root, check=True)
+        _family, status_path, status_data, _checkout = _write_preserve_runtime_state(
+            paths, "feature", item_id, branch
+        )
+        before_statuses[item_id] = (status_path, status_data)
+
+    result = run_reset_command("feature", ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 0, result.render()
+    statuses = {
+        item["id"]: item["status"]
+        for item in json.loads(plan.read_text(encoding="utf-8"))["features"]
+    }
+    assert statuses == {
+        "F-001": "pending",
+        "F-002": "pending",
+        "F-003": "pending",
+        "F-004": "pending",
+        "F-005": "completed",
+    }
+    for status_path, before in before_statuses.values():
+        expected = dict(before)
+        expected.update(retry_count=0, infra_error_count=0, continuation_pending=True)
+        assert json.loads(status_path.read_text(encoding="utf-8")) == expected
+    assert "Failed roots restored: F-001, F-003" in result.render()
+
+    plan_after = plan.read_bytes()
+    runtime_after = {
+        item_id: status_path.read_bytes()
+        for item_id, (status_path, _before) in before_statuses.items()
+    }
+    second = run_reset_command("feature", ("--failed", "--preserve-runtime"), paths)
+    assert second.exit_code == 0
+    assert "No failed" in second.render()
+    assert plan.read_bytes() == plan_after
+    assert {
+        item_id: status_path.read_bytes()
+        for item_id, (status_path, _before) in before_statuses.items()
+    } == runtime_after
+
+
+def test_preserve_runtime_respects_existing_task_guard_without_mutation(tmp_path):
+    from prizmkit_runtime.reset import run_reset_command
+    from prizmkit_runtime.task_checkout import task_checkout_guard
+
+    paths = _make_paths(tmp_path)
+    _init_preserve_runtime_repo(paths)
+    plan = _write_family_plan(
+        paths,
+        "feature",
+        [{"id": "F-001", "title": "Root", "status": "failed", "dependencies": []}],
+    )
+    subprocess.run(["git", "branch", "dev/F-001-existing", "main"], cwd=paths.project_root, check=True)
+    family, status_path, _status, _checkout = _write_preserve_runtime_state(
+        paths, "feature", "F-001", "dev/F-001-existing"
+    )
+    plan_before = plan.read_bytes()
+    status_before = status_path.read_bytes()
+
+    with task_checkout_guard(family.state_dir, "F-001"):
+        result = run_reset_command("feature", ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 1
+    assert "checkout lifecycle is busy" in result.render()
+    assert plan.read_bytes() == plan_before
+    assert status_path.read_bytes() == status_before
+
+
+@pytest.mark.parametrize(
+    ("kind", "item_id"),
+    [("feature", "F-001"), ("bugfix", "B-001"), ("refactor", "R-001")],
+)
+def test_public_reset_cli_hard_rejects_run_for_every_family_without_state_change(tmp_path, kind, item_id):
+    project = tmp_path / kind
+    project.mkdir()
+
+    completed = subprocess.run(
+        [
+            sys.executable,
+            str(CLI_PATH),
+            "--project-root",
+            str(project),
+            "reset",
+            kind,
+            item_id,
+            "--run",
+        ],
+        cwd=REPO_ROOT,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        check=False,
+    )
+
+    assert completed.returncode == 2
+    assert "Reset no longer accepts --run" in completed.stdout + completed.stderr
+    assert not (project / ".prizmkit").exists()
+
+
+@pytest.mark.parametrize(
+    ("items", "expected_error"),
+    [
+        (
+            [{"id": "F-001", "title": "Root", "status": "failed", "dependencies": ["F-999"]}],
+            "unknown dependency F-999",
+        ),
+        (
+            [
+                {"id": "F-001", "title": "One", "status": "failed", "dependencies": ["F-002"]},
+                {"id": "F-002", "title": "Two", "status": "auto_skipped", "dependencies": ["F-001"]},
+            ],
+            "dependency cycle",
+        ),
+        (
+            [
+                {"id": "F-001", "title": "One", "status": "failed", "dependencies": []},
+                {"id": "F-001", "title": "Duplicate", "status": "failed", "dependencies": []},
+            ],
+            "duplicate item id: F-001",
+        ),
+    ],
+)
+def test_preserve_runtime_rejects_invalid_dependency_graph_without_state_mutation(
+    tmp_path,
+    items,
+    expected_error,
+):
+    from prizmkit_runtime.reset import run_reset_command
+
+    paths = _make_paths(tmp_path)
+    plan = _write_family_plan(paths, "feature", items)
+    before = plan.read_bytes()
+
+    result = run_reset_command("feature", ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 1
+    assert expected_error in result.render()
+    assert plan.read_bytes() == before
+    assert not paths.feature_state_dir.exists()
+
+
+def test_preserve_runtime_success_quotes_list_path_in_separate_run_instruction(tmp_path):
+    from prizmkit_runtime.reset import run_reset_command
+
+    paths = _make_paths(tmp_path / "parent with spaces")
+    _init_preserve_runtime_repo(paths)
+    plan = _write_family_plan(
+        paths,
+        "feature",
+        [{"id": "F-001", "title": "Root", "status": "failed", "dependencies": []}],
+    )
+    subprocess.run(["git", "branch", "dev/F-001-existing", "main"], cwd=paths.project_root, check=True)
+    _write_preserve_runtime_state(paths, "feature", "F-001", "dev/F-001-existing")
+
+    result = run_reset_command("feature", ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 0
+    assert f"feature run {shlex.quote(str(plan.resolve()))}" in result.render()
+
+
+def test_preserve_runtime_requires_recorded_base_to_be_a_local_branch(tmp_path):
+    from prizmkit_runtime.reset import run_reset_command
+
+    paths = _make_paths(tmp_path)
+    _init_preserve_runtime_repo(paths)
+    subprocess.run(["git", "tag", "base-tag", "main"], cwd=paths.project_root, check=True)
+    plan = _write_family_plan(
+        paths,
+        "feature",
+        [{"id": "F-001", "title": "Root", "status": "failed", "dependencies": []}],
+    )
+    _family, status_path, _before_status, _checkout = _write_preserve_runtime_state(
+        paths,
+        "feature",
+        "F-001",
+        "dev/F-001-missing",
+        base_branch="base-tag",
+    )
+    plan_before = plan.read_bytes()
+    status_before = status_path.read_bytes()
+
+    result = run_reset_command("feature", ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 1
+    assert "recorded base branch is missing: base-tag" in result.render()
+    assert plan.read_bytes() == plan_before
+    assert status_path.read_bytes() == status_before
+
+
+def test_preserve_runtime_preflights_all_failed_roots_before_any_state_change(tmp_path):
+    from prizmkit_runtime.reset import run_reset_command
+
+    paths = _make_paths(tmp_path)
+    _init_preserve_runtime_repo(paths)
+    items = [
+        {"id": "F-001", "title": "One", "status": "failed", "dependencies": []},
+        {"id": "F-002", "title": "Two", "status": "failed", "dependencies": []},
+        {"id": "F-003", "title": "Three", "status": "failed", "dependencies": []},
+    ]
+    plan = _write_family_plan(paths, "feature", items)
+    subprocess.run(["git", "branch", "dev/F-001-existing", "main"], cwd=paths.project_root, check=True)
+    family, status_one, _data_one, _checkout_one = _write_preserve_runtime_state(
+        paths, "feature", "F-001", "dev/F-001-existing"
+    )
+    _family, status_two, _data_two, _checkout_two = _write_preserve_runtime_state(
+        paths, "feature", "F-002", "dev/F-002-missing", base_branch="missing-base-two"
+    )
+    _family, status_three, _data_three, _checkout_three = _write_preserve_runtime_state(
+        paths, "feature", "F-003", "dev/F-003-missing", base_branch="missing-base-three"
+    )
+    plan_before = plan.read_bytes()
+    status_one_before = status_one.read_bytes()
+    status_two_before = status_two.read_bytes()
+    status_three_before = status_three.read_bytes()
+    checkout_one_before = (family.state_dir / "F-001" / "checkout.json").read_bytes()
+    branches_before = subprocess.run(
+        ["git", "branch", "--format=%(refname:short)"],
+        cwd=paths.project_root,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout
+
+    result = run_reset_command("feature", ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 1
+    assert "recorded base branch is missing: missing-base-two" in result.render()
+    assert "recorded base branch is missing: missing-base-three" in result.render()
+    assert plan.read_bytes() == plan_before
+    assert status_one.read_bytes() == status_one_before
+    assert status_two.read_bytes() == status_two_before
+    assert status_three.read_bytes() == status_three_before
+    assert (family.state_dir / "F-001" / "checkout.json").read_bytes() == checkout_one_before
+    assert subprocess.run(
+        ["git", "branch", "--format=%(refname:short)"],
+        cwd=paths.project_root,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout == branches_before
+
+
+def test_preserve_runtime_invalid_existing_checkpoint_blocks_before_mutation(tmp_path):
+    from prizmkit_runtime.reset import run_reset_command
+
+    paths = _make_paths(tmp_path)
+    _init_preserve_runtime_repo(paths)
+    plan = _write_family_plan(
+        paths,
+        "feature",
+        [{"id": "F-001", "title": "Root", "status": "failed", "dependencies": []}],
+    )
+    subprocess.run(["git", "branch", "dev/F-001-existing", "main"], cwd=paths.project_root, check=True)
+    _family, status_path, _before_status, _checkout = _write_preserve_runtime_state(
+        paths, "feature", "F-001", "dev/F-001-existing"
+    )
+    artifact = paths.project_root / ".prizmkit" / "specs" / "001-root"
+    artifact.mkdir(parents=True)
+    checkpoint = artifact / "workflow-checkpoint.json"
+    checkpoint.write_text("{\"steps\": \"invalid\"}\n", encoding="utf-8")
+    plan_before = plan.read_bytes()
+    status_before = status_path.read_bytes()
+    checkout_before = (
+        paths.feature_state_dir / "F-001" / "checkout.json"
+    ).read_bytes()
+
+    result = run_reset_command("feature", ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 1
+    assert "invalid checkpoint" in result.render()
+    assert plan.read_bytes() == plan_before
+    assert status_path.read_bytes() == status_before
+    assert (paths.feature_state_dir / "F-001" / "checkout.json").read_bytes() == checkout_before
+    assert checkpoint.read_text(encoding="utf-8") == "{\"steps\": \"invalid\"}\n"
+
+
+def _add_completed_plan_step(checkpoint):
+    payload = json.loads(checkpoint.read_text(encoding="utf-8"))
+    payload["steps"].insert(
+        0,
+        {
+            "id": "S00",
+            "skill": "prizmkit-plan",
+            "name": "plan",
+            "status": "completed",
+            "stage_result": "PLAN_READY",
+            "depends_on": None,
+            "required_artifacts": [],
+        },
+    )
+    payload["steps"][1]["depends_on"] = "S00"
+    state_key = {
+        "feature-pipeline": "feature_state",
+        "bugfix-pipeline": "bugfix_state",
+        "refactor-pipeline": "refactor_state",
+    }[payload["workflow_type"]]
+    payload[state_key]["completed_stages"] = ["plan", "implement", "code-review", "test"]
+    checkpoint.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def test_preserve_runtime_missing_branch_creates_replacement_and_rewinds_checkpoint(tmp_path):
+    from prizmkit_runtime.gitops import local_branch_exists
+    from prizmkit_runtime.reset import run_reset_command
+    from prizmkit_runtime.runner_models import family_for
+    from prizmkit_runtime.task_checkout import load_task_checkout
+
+    paths = _make_paths(tmp_path)
+    _init_preserve_runtime_repo(paths)
+    plan = _write_family_plan(
+        paths,
+        "feature",
+        [{"id": "F-001", "title": "Root", "status": "failed", "dependencies": []}],
+    )
+    family, status_path, before_status, old_checkout = _write_preserve_runtime_state(
+        paths, "feature", "F-001", "dev/F-001-deleted"
+    )
+    artifact = paths.project_root / ".prizmkit" / "specs" / "001-root"
+    checkpoint = _write_semantic_completion_checkpoint(paths.project_root, artifact)
+    _add_completed_plan_step(checkpoint)
+    (artifact / "implementation-notes.md").write_text("keep context\n", encoding="utf-8")
+    session_log = family.state_dir / "F-001" / "sessions" / "old-session" / "logs" / "session.log"
+    session_before = session_log.read_bytes()
+    base_head = subprocess.run(
+        ["git", "rev-parse", "main"], cwd=paths.project_root, check=True, stdout=subprocess.PIPE, text=True
+    ).stdout.strip()
+
+    result = run_reset_command("feature", ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 0, result.render()
+    checkout = load_task_checkout(family.state_dir, "feature", "F-001")
+    assert checkout is not None and checkout.is_active and not checkout.is_reset
+    assert checkout.active_dev_branch != old_checkout.active_dev_branch
+    assert checkout.active_dev_branch.startswith("dev/F-001-resume-")
+    assert checkout.base_branch == "main"
+    assert local_branch_exists(paths.project_root, checkout.active_dev_branch)
+    assert subprocess.run(
+        ["git", "rev-parse", checkout.active_dev_branch],
+        cwd=paths.project_root,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout.strip() == base_head
+    persisted = json.loads(checkpoint.read_text(encoding="utf-8"))
+    assert persisted["steps"][0]["status"] == "completed"
+    assert persisted["steps"][0]["stage_result"] == "PLAN_READY"
+    assert all(step["status"] == "pending" for step in persisted["steps"][1:])
+    assert all("stage_result" not in step for step in persisted["steps"][1:])
+    assert persisted["feature_state"]["stage"] == "implement"
+    assert persisted["feature_state"]["current_stage"] == "prizmkit-implement"
+    assert persisted["feature_state"]["completed_stages"] == ["plan"]
+    assert (artifact / "implementation-notes.md").read_text(encoding="utf-8") == "keep context\n"
+    expected_status = dict(before_status)
+    expected_status.update(
+        retry_count=0,
+        infra_error_count=0,
+        continuation_pending=True,
+        active_dev_branch=checkout.active_dev_branch,
+        base_branch="main",
+    )
+    assert json.loads(status_path.read_text(encoding="utf-8")) == expected_status
+    assert session_log.read_bytes() == session_before
+    assert json.loads(plan.read_text(encoding="utf-8"))["features"][0]["status"] == "pending"
+
+
+@pytest.mark.parametrize(
+    ("kind", "item_id", "branch_prefix", "workflow_type", "artifact_root", "state_key"),
+    [
+        ("bugfix", "B-001", "bugfix", "bugfix-pipeline", "bugfix", "bugfix_state"),
+        ("refactor", "R-001", "refactor", "refactor-pipeline", "refactor", "refactor_state"),
+    ],
+)
+def test_missing_branch_checkpoint_rewind_has_cross_family_parity(
+    tmp_path,
+    kind,
+    item_id,
+    branch_prefix,
+    workflow_type,
+    artifact_root,
+    state_key,
+):
+    from prizmkit_runtime.gitops import local_branch_exists
+    from prizmkit_runtime.reset import run_reset_command
+    from prizmkit_runtime.runner_models import family_for
+    from prizmkit_runtime.task_checkout import load_task_checkout
+
+    paths = _make_paths(tmp_path / kind)
+    _init_preserve_runtime_repo(paths)
+    plan = _write_family_plan(
+        paths,
+        kind,
+        [{"id": item_id, "title": "Root", "status": "failed", "dependencies": []}],
+    )
+    family, _status_path, _before_status, old_checkout = _write_preserve_runtime_state(
+        paths, kind, item_id, f"{branch_prefix}/{item_id}-deleted"
+    )
+    artifact = paths.project_root / ".prizmkit" / artifact_root / item_id
+    checkpoint = _write_semantic_completion_checkpoint(
+        paths.project_root,
+        artifact,
+        workflow_type,
+    )
+    _add_completed_plan_step(checkpoint)
+
+    result = run_reset_command(kind, ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 0, result.render()
+    checkout = load_task_checkout(family.state_dir, kind, item_id)
+    assert checkout is not None and checkout.is_active
+    assert checkout.active_dev_branch != old_checkout.active_dev_branch
+    assert checkout.active_dev_branch.startswith(f"{branch_prefix}/{item_id}-resume-")
+    assert local_branch_exists(paths.project_root, checkout.active_dev_branch)
+    persisted = json.loads(checkpoint.read_text(encoding="utf-8"))
+    assert persisted["steps"][0]["status"] == "completed"
+    assert all(step["status"] == "pending" for step in persisted["steps"][1:])
+    assert persisted[state_key]["stage"] == "implement"
+    assert persisted[state_key]["current_stage"] == "prizmkit-implement"
+    collection = {"bugfix": "bugs", "refactor": "refactors"}[kind]
+    assert json.loads(plan.read_text(encoding="utf-8"))[collection][0]["status"] == "pending"
+
+
+def test_preserve_runtime_reuses_registered_worktree_without_cleanup(tmp_path):
+    from prizmkit_runtime.gitops import (
+        BranchContext,
+        WorktreePolicy,
+        ensure_linked_worktree,
+        registered_worktrees,
+        worktree_runtime_context,
+    )
+    from prizmkit_runtime.reset import run_reset_command
+    from prizmkit_runtime.runner_models import family_for
+    from prizmkit_runtime.task_checkout import (
+        CHECKOUT_MODE_WORKTREE,
+        TaskCheckout,
+        load_task_checkout,
+        persist_task_checkout,
+    )
+
+    paths = _make_paths(tmp_path)
+    _init_preserve_runtime_repo(paths)
+    plan = _write_family_plan(
+        paths,
+        "feature",
+        [{"id": "F-001", "title": "Root", "status": "failed", "dependencies": []}],
+    )
+    family, status_path, _before_status, _old_checkout = _write_preserve_runtime_state(
+        paths, "feature", "F-001", "dev/F-001-worktree"
+    )
+    runtime = worktree_runtime_context(
+        BranchContext("main", "dev/F-001-worktree", paths.project_root),
+        WorktreePolicy(True, True, True, tmp_path / "worktrees"),
+    )
+    assert ensure_linked_worktree(runtime).ok
+    worktree_checkout = TaskCheckout.active(
+        "feature",
+        "F-001",
+        "dev/F-001-worktree",
+        "main",
+        checkout_mode=CHECKOUT_MODE_WORKTREE,
+        worktree_path=str(runtime.worktree_path),
+    )
+    persist_task_checkout(family.state_dir, worktree_checkout)
+    artifact = runtime.worktree_path / ".prizmkit" / "specs" / "001-root"
+    artifact.mkdir(parents=True)
+    marker = artifact / "partial.md"
+    marker.write_text("worktree WIP\n", encoding="utf-8")
+    registrations_before = registered_worktrees(paths.project_root)
+
+    result = run_reset_command("feature", ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 0, result.render()
+    assert load_task_checkout(family.state_dir, "feature", "F-001") == worktree_checkout
+    assert runtime.worktree_path.is_dir()
+    assert marker.read_text(encoding="utf-8") == "worktree WIP\n"
+    assert registered_worktrees(paths.project_root) == registrations_before
+    assert json.loads(status_path.read_text(encoding="utf-8"))["continuation_pending"] is True
+    assert json.loads(plan.read_text(encoding="utf-8"))["features"][0]["status"] == "pending"
+
+
+def test_replacement_worktree_skips_registered_path_collision_even_when_path_is_absent(monkeypatch, tmp_path):
+    from prizmkit_runtime import reset_preserve
+    from prizmkit_runtime.gitops import (
+        BranchContext,
+        RegisteredWorktree,
+        WorktreePolicy,
+        worktree_runtime_context,
+    )
+    from prizmkit_runtime.runner_models import family_for
+    from prizmkit_runtime.task_checkout import CHECKOUT_MODE_WORKTREE, TaskCheckout
+
+    paths = _make_paths(tmp_path)
+    _init_preserve_runtime_repo(paths)
+    family = family_for("feature", paths)
+    worktree_root = tmp_path / "worktrees"
+    old_runtime = worktree_runtime_context(
+        BranchContext("main", "dev/F-001-old", paths.project_root),
+        WorktreePolicy(True, True, True, worktree_root),
+    )
+    checkout = TaskCheckout.active(
+        "feature",
+        "F-001",
+        "dev/F-001-old",
+        "main",
+        checkout_mode=CHECKOUT_MODE_WORKTREE,
+        worktree_path=str(old_runtime.worktree_path),
+    )
+    item = reset_preserve.PreservePlanItem(
+        "F-001", "Root", "001-root", "failed", (), 0
+    )
+    monkeypatch.setattr(reset_preserve.time, "strftime", lambda *_args: "20260725120000")
+    colliding_runtime = worktree_runtime_context(
+        BranchContext(
+            "main",
+            "dev/F-001-resume-20260725120000",
+            paths.project_root,
+        ),
+        WorktreePolicy(True, True, True, worktree_root),
+    )
+    registration = RegisteredWorktree(
+        colliding_runtime.worktree_path,
+        "different/branch-with-same-normalized-path",
+    )
+
+    branch, runtime = reset_preserve._replacement_identity(
+        family,
+        item,
+        checkout,
+        paths.project_root,
+        (registration,),
+        old_runtime,
+    )
+
+    assert branch == "dev/F-001-resume-20260725120000-1"
+    assert runtime is not None
+    assert runtime.worktree_path != colliding_runtime.worktree_path
+
+
+def test_preserve_runtime_missing_worktree_copies_reference_artifacts_without_deleting_old_site(tmp_path):
+    from prizmkit_runtime.gitops import BranchContext, WorktreePolicy, worktree_runtime_context
+    from prizmkit_runtime.reset import run_reset_command
+    from prizmkit_runtime.runner_models import family_for
+    from prizmkit_runtime.task_checkout import (
+        CHECKOUT_MODE_WORKTREE,
+        TaskCheckout,
+        load_task_checkout,
+        persist_task_checkout,
+    )
+
+    paths = _make_paths(tmp_path)
+    _init_preserve_runtime_repo(paths)
+    plan = _write_family_plan(
+        paths,
+        "feature",
+        [{"id": "F-001", "title": "Root", "status": "failed", "dependencies": []}],
+    )
+    family, status_path, before_status, _branch_checkout = _write_preserve_runtime_state(
+        paths, "feature", "F-001", "dev/F-001-deleted-worktree"
+    )
+    old_runtime = worktree_runtime_context(
+        BranchContext("main", "dev/F-001-deleted-worktree", paths.project_root),
+        WorktreePolicy(True, True, True, tmp_path / "worktrees"),
+    )
+    old_runtime.worktree_path.mkdir(parents=True)
+    old_checkout = TaskCheckout.active(
+        "feature",
+        "F-001",
+        "dev/F-001-deleted-worktree",
+        "main",
+        checkout_mode=CHECKOUT_MODE_WORKTREE,
+        worktree_path=str(old_runtime.worktree_path),
+    )
+    persist_task_checkout(family.state_dir, old_checkout)
+    old_artifact = old_runtime.worktree_path / ".prizmkit" / "specs" / "001-root"
+    old_checkpoint = _write_semantic_completion_checkpoint(old_runtime.worktree_path, old_artifact)
+    _add_completed_plan_step(old_checkpoint)
+    old_marker = old_artifact / "partial.md"
+    old_marker.write_text("old reference\n", encoding="utf-8")
+    external_reference = tmp_path / "external-reference.txt"
+    external_reference.write_text("do not copy through symlink\n", encoding="utf-8")
+    old_link = old_artifact / "external-reference"
+    old_link.symlink_to(external_reference)
+    old_checkpoint_before = old_checkpoint.read_bytes()
+
+    result = run_reset_command("feature", ("--failed", "--preserve-runtime"), paths)
+
+    assert result.exit_code == 0, result.render()
+    checkout = load_task_checkout(family.state_dir, "feature", "F-001")
+    assert checkout is not None and checkout.is_active and checkout.uses_worktree
+    assert checkout.active_dev_branch.startswith("dev/F-001-resume-")
+    assert Path(checkout.worktree_path) != old_runtime.worktree_path
+    assert Path(checkout.worktree_path).is_dir()
+    assert old_runtime.worktree_path.is_dir()
+    assert old_checkpoint.read_bytes() == old_checkpoint_before
+    assert old_marker.read_text(encoding="utf-8") == "old reference\n"
+    copied_artifact = Path(checkout.worktree_path) / ".prizmkit" / "specs" / "001-root"
+    assert (copied_artifact / "partial.md").read_text(encoding="utf-8") == "old reference\n"
+    copied_link = copied_artifact / "external-reference"
+    assert copied_link.is_symlink()
+    assert copied_link.resolve() == external_reference.resolve()
+    copied_checkpoint = json.loads((copied_artifact / "workflow-checkpoint.json").read_text(encoding="utf-8"))
+    assert copied_checkpoint["steps"][0]["status"] == "completed"
+    assert all(step["status"] == "pending" for step in copied_checkpoint["steps"][1:])
+    expected_status = dict(before_status)
+    expected_status.update(
+        retry_count=0,
+        infra_error_count=0,
+        continuation_pending=True,
+        active_dev_branch=checkout.active_dev_branch,
+        base_branch="main",
+    )
+    assert json.loads(status_path.read_text(encoding="utf-8")) == expected_status
+    assert json.loads(plan.read_text(encoding="utf-8"))["features"][0]["status"] == "pending"