prizmkit 1.1.153 → 1.1.155

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

@@ -0,0 +1,935 @@
+"""Focused tests for explicit reset modes and causal state recovery."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from utils import causal_reset_selection
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+PIPELINE_ROOT = REPO_ROOT / "dev-pipeline"
+
+
+def _item(item_id, status="pending", dependencies=None, **extra):
+    return {
+        "id": item_id,
+        "title": item_id,
+        "status": status,
+        "dependencies": list(dependencies or []),
+        **extra,
+    }
+
+
+@pytest.mark.parametrize(
+    ("prefix", "root_statuses"),
+    (
+        ("F-", {"failed", "skipped"}),
+        ("B-", {"failed", "skipped", "needs_info"}),
+        ("R-", {"failed", "skipped"}),
+    ),
+)
+def test_causal_selection_single_root_recovers_only_complete_chain(prefix, root_statuses):
+    items = [
+        _item(f"{prefix}001", "failed"),
+        _item(f"{prefix}002", "auto_skipped", [f"{prefix}001"]),
+        _item(f"{prefix}003", "auto_skipped", [f"{prefix}002"]),
+        _item(f"{prefix}004", "completed", [f"{prefix}001"], marker="preserve"),
+        _item(f"{prefix}005", "failed"),
+        _item(f"{prefix}006", "auto_skipped", [f"{prefix}005"]),
+    ]
+
+    selected = causal_reset_selection(
+        items,
+        selected_id=f"{prefix}001",
+        blocking_root_statuses=root_statuses,
+        item_label="Task",
+    )
+
+    assert selected == (f"{prefix}001", f"{prefix}002", f"{prefix}003")
+    assert items[3]["status"] == "completed"
+    assert items[3]["marker"] == "preserve"
+
+
+@pytest.mark.parametrize("prefix", ("F-", "B-", "R-"))
+def test_causal_selection_keeps_multi_root_descendant_blocked(prefix):
+    root_statuses = {"failed", "skipped", "needs_info"} if prefix == "B-" else {"failed", "skipped"}
+    items = [
+        _item(f"{prefix}001", "failed"),
+        _item(f"{prefix}002", "skipped"),
+        _item(f"{prefix}003", "auto_skipped", [f"{prefix}001"]),
+        _item(f"{prefix}004", "auto_skipped", [f"{prefix}003", f"{prefix}002"]),
+        _item(f"{prefix}005", "auto_skipped", [f"{prefix}002"]),
+    ]
+
+    selected = causal_reset_selection(
+        items,
+        selected_id=f"{prefix}001",
+        blocking_root_statuses=root_statuses,
+    )
+
+    assert selected == (f"{prefix}001", f"{prefix}003")
+
+
+def test_causal_selection_does_not_cross_an_orphan_auto_skipped_blocker():
+    items = [
+        _item("F-001", "failed"),
+        _item("F-002", "auto_skipped"),
+        _item("F-003", "auto_skipped", ["F-001", "F-002"]),
+    ]
+
+    selected = causal_reset_selection(
+        items,
+        selected_id="F-001",
+        blocking_root_statuses={"failed", "skipped"},
+    )
+
+    assert selected == ("F-001",)
+
+
+@pytest.mark.parametrize("prefix", ("F-", "B-", "R-"))
+def test_selecting_auto_skipped_leaf_includes_every_required_root(prefix):
+    root_statuses = {"failed", "skipped", "needs_info"} if prefix == "B-" else {"failed", "skipped"}
+    second_root_status = "needs_info" if prefix == "B-" else "skipped"
+    items = [
+        _item(f"{prefix}001", "failed"),
+        _item(f"{prefix}002", second_root_status),
+        _item(f"{prefix}003", "auto_skipped", [f"{prefix}001"]),
+        _item(f"{prefix}004", "auto_skipped", [f"{prefix}002"]),
+        _item(f"{prefix}005", "auto_skipped", [f"{prefix}003", f"{prefix}004"]),
+        _item(f"{prefix}006", "completed"),
+    ]
+
+    selected = causal_reset_selection(
+        items,
+        selected_id=f"{prefix}005",
+        blocking_root_statuses=root_statuses,
+    )
+
+    assert selected == (
+        f"{prefix}001",
+        f"{prefix}002",
+        f"{prefix}003",
+        f"{prefix}004",
+        f"{prefix}005",
+    )
+
+
+@pytest.mark.parametrize(
+    ("prefix", "root_statuses", "root_status"),
+    (
+        ("F-", {"failed", "skipped"}, "skipped"),
+        ("B-", {"failed", "skipped", "needs_info"}, "needs_info"),
+        ("R-", {"failed", "skipped"}, "skipped"),
+    ),
+)
+def test_causal_selection_all_recovers_every_supported_chain(prefix, root_statuses, root_status):
+    items = [
+        _item(f"{prefix}001", "failed"),
+        _item(f"{prefix}002", root_status),
+        _item(f"{prefix}003", "auto_skipped", [f"{prefix}001", f"{prefix}002"]),
+        _item(f"{prefix}004", "completed"),
+        _item(f"{prefix}005", "pending"),
+    ]
+
+    selected = causal_reset_selection(
+        items,
+        selected_id=None,
+        blocking_root_statuses=root_statuses,
+    )
+
+    assert selected == (f"{prefix}001", f"{prefix}002", f"{prefix}003")
+
+
+def test_causal_selection_rejects_missing_invalid_and_orphan_targets():
+    items = [
+        _item("F-001", "failed"),
+        _item("F-002", "pending"),
+        _item("F-003", "auto_skipped"),
+    ]
+
+    with pytest.raises(ValueError, match="not found"):
+        causal_reset_selection(items, selected_id="F-999", blocking_root_statuses={"failed", "skipped"})
+    with pytest.raises(ValueError, match="not recoverable"):
+        causal_reset_selection(items, selected_id="F-002", blocking_root_statuses={"failed", "skipped"})
+    with pytest.raises(ValueError, match="unresolved auto_skipped blocker"):
+        causal_reset_selection(items, selected_id="F-003", blocking_root_statuses={"failed", "skipped"})
+
+
+def test_causal_selection_rejects_invalid_dependency_graph_before_selection():
+    items = [
+        _item("F-001", "failed", ["F-002"]),
+        _item("F-002", "auto_skipped", ["F-001"]),
+    ]
+
+    with pytest.raises(ValueError, match="Dependency cycle"):
+        causal_reset_selection(items, selected_id="F-001", blocking_root_statuses={"failed", "skipped"})
+
+
+FAMILY_CONTRACTS = {
+    "feature": {
+        "prefix": "F-",
+        "list_key": "features",
+        "list_arg": "--feature-list",
+        "id_arg": "--feature-id",
+        "schema": "dev-pipeline-feature-list-v1",
+        "script": "update-feature-status.py",
+        "branch_prefix": "dev",
+        "artifact_root": "specs",
+    },
+    "bugfix": {
+        "prefix": "B-",
+        "list_key": "bugs",
+        "list_arg": "--bug-list",
+        "id_arg": "--bug-id",
+        "schema": "dev-pipeline-bug-fix-list-v1",
+        "script": "update-bug-status.py",
+        "branch_prefix": "bugfix",
+        "artifact_root": "bugfix",
+    },
+    "refactor": {
+        "prefix": "R-",
+        "list_key": "refactors",
+        "list_arg": "--refactor-list",
+        "id_arg": "--refactor-id",
+        "schema": "dev-pipeline-refactor-list-v1",
+        "script": "update-refactor-status.py",
+        "branch_prefix": "refactor",
+        "artifact_root": "refactor",
+    },
+}
+
+
+def _make_paths(tmp_path):
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    project_root = tmp_path / "project"
+    (project_root / ".prizmkit" / "plans").mkdir(parents=True)
+    return resolve_runtime_paths(pipeline_root=PIPELINE_ROOT, project_root=project_root)
+
+
+def _family_and_plan(paths, kind, items):
+    from prizmkit_runtime.runner_models import family_for
+
+    family = family_for(kind, paths)
+    contract = FAMILY_CONTRACTS[kind]
+    family.plan_path.write_text(
+        json.dumps(
+            {
+                "$schema": contract["schema"],
+                "project_name": "Reset Test",
+                contract["list_key"]: items,
+            },
+            indent=2,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    return family, family.plan_path
+
+
+def _write_runtime_status(family, item_id, **overrides):
+    status_dir = family.state_dir / item_id
+    status_dir.mkdir(parents=True, exist_ok=True)
+    status = {
+        f"{family.kind if family.kind != 'bugfix' else 'bug'}_id": item_id,
+        "retry_count": 4,
+        "infra_error_count": 3,
+        "last_infra_error_session_id": "old-session",
+        "sessions": ["old-session"],
+        "last_session_id": "old-session",
+        "last_failed_session_id": "old-session",
+        "resume_from_phase": 4,
+        "continuation_pending": True,
+        "continuation_reason": "context_overflow",
+        "continuation_count": 2,
+        "context_overflow_count": 2,
+        "previous_session_id": "old-session",
+        "custom_diagnostic": {"keep": True},
+        **overrides,
+    }
+    status_path = status_dir / "status.json"
+    status_path.write_text(json.dumps(status, indent=2) + "\n", encoding="utf-8")
+    return status_path, status
+
+
+def _tree_snapshot(root):
+    if not root.exists():
+        return {}
+    return {
+        str(path.relative_to(root)): path.read_bytes()
+        for path in sorted(root.rglob("*"))
+        if path.is_file()
+    }
+
+
+def _git(project_root, *args):
+    return subprocess.run(
+        ["git", *args],
+        cwd=project_root,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=True,
+    ).stdout.strip()
+
+
+def _init_git_repository(project_root):
+    subprocess.run(
+        ["git", "init", "-b", "main"],
+        cwd=project_root,
+        stdout=subprocess.DEVNULL,
+        check=True,
+    )
+    _git(project_root, "config", "user.email", "reset@example.com")
+    _git(project_root, "config", "user.name", "Reset Test")
+    source = project_root / "source.txt"
+    source.write_text("committed\n", encoding="utf-8")
+    _git(project_root, "add", "source.txt")
+    _git(project_root, "commit", "-m", "base")
+    source.write_text("committed\nlocal work\n", encoding="utf-8")
+    return source
+
+
+@pytest.mark.parametrize("kind", ("feature", "bugfix", "refactor"))
+def test_state_only_resets_exact_causal_records_and_preserves_checkout_git_and_artifacts(tmp_path, kind):
+    from prizmkit_runtime.reset import run_reset_command
+    from prizmkit_runtime.task_checkout import (
+        CHECKOUT_MODE_WORKTREE,
+        TaskCheckout,
+        persist_task_checkout,
+    )
+
+    paths = _make_paths(tmp_path / kind)
+    contract = FAMILY_CONTRACTS[kind]
+    prefix = contract["prefix"]
+    root_id = f"{prefix}001"
+    child_id = f"{prefix}002"
+    other_root_id = f"{prefix}003"
+    shared_id = f"{prefix}004"
+    completed_id = f"{prefix}005"
+    unrelated_child_id = f"{prefix}006"
+    items = [
+        _item(root_id, "failed", marker="root-field"),
+        _item(child_id, "auto_skipped", [root_id], marker="child-field"),
+        _item(other_root_id, "failed", marker="other-root-field"),
+        _item(shared_id, "auto_skipped", [child_id, other_root_id], marker="shared-field"),
+        _item(completed_id, "completed", marker="completed-field"),
+        _item(unrelated_child_id, "auto_skipped", [other_root_id], marker="unrelated-field"),
+    ]
+    family, plan_path = _family_and_plan(paths, kind, items)
+    source_path = _init_git_repository(paths.project_root)
+    branch_name = f"{contract['branch_prefix']}/{root_id}-preserved"
+    _git(paths.project_root, "branch", branch_name, "main")
+
+    worktree_path = paths.project_root / ".task-worktrees" / root_id
+    worktree_path.mkdir(parents=True)
+    worktree_marker = worktree_path / "keep.txt"
+    worktree_marker.write_text("worktree remains\n", encoding="utf-8")
+    checkout = TaskCheckout.active(
+        kind,
+        root_id,
+        branch_name,
+        "main",
+        checkout_mode=CHECKOUT_MODE_WORKTREE,
+        worktree_path=str(worktree_path),
+    )
+    persist_task_checkout(family.state_dir, checkout)
+    checkout_path = family.state_dir / root_id / "checkout.json"
+
+    root_status_path, _root_before = _write_runtime_status(
+        family,
+        root_id,
+        active_dev_branch=branch_name,
+        base_branch="main",
+    )
+    child_status_path, _child_before = _write_runtime_status(family, child_id)
+    other_status_path, _other_before = _write_runtime_status(family, other_root_id)
+    completed_status_path, _completed_before = _write_runtime_status(family, completed_id)
+
+    session_log = family.state_dir / root_id / "sessions" / "old-session" / "logs" / "session.log"
+    session_log.parent.mkdir(parents=True)
+    session_log.write_text("session history\n", encoding="utf-8")
+    artifact_name = "001-root" if kind == "feature" else root_id
+    artifact_dir = paths.project_root / ".prizmkit" / contract["artifact_root"] / artifact_name
+    artifact_dir.mkdir(parents=True)
+    checkpoint = artifact_dir / "workflow-checkpoint.json"
+    checkpoint.write_text('{"sentinel":"checkpoint"}\n', encoding="utf-8")
+    artifact = artifact_dir / "spec.md"
+    artifact.write_text("artifact remains\n", encoding="utf-8")
+
+    protected_bytes = {
+        "checkout": checkout_path.read_bytes(),
+        "session": session_log.read_bytes(),
+        "checkpoint": checkpoint.read_bytes(),
+        "artifact": artifact.read_bytes(),
+        "worktree": worktree_marker.read_bytes(),
+        "other_status": other_status_path.read_bytes(),
+        "completed_status": completed_status_path.read_bytes(),
+        "source": source_path.read_bytes(),
+    }
+    branch_refs_before = _git(paths.project_root, "show-ref", "--heads")
+    branch_before = _git(paths.project_root, "branch", "--show-current")
+    source_diff_before = _git(paths.project_root, "diff", "--", "source.txt")
+
+    result = run_reset_command(
+        kind,
+        (root_id, "--state-only", str(plan_path)),
+        paths,
+    )
+
+    assert result.exit_code == 0, result.render()
+    payload = json.loads(result.render())
+    assert payload["action"] == "reset_state"
+    assert payload["reset_count"] == 2
+    updated = json.loads(plan_path.read_text(encoding="utf-8"))[contract["list_key"]]
+    statuses = {item["id"]: item["status"] for item in updated}
+    assert statuses == {
+        root_id: "pending",
+        child_id: "pending",
+        other_root_id: "failed",
+        shared_id: "auto_skipped",
+        completed_id: "completed",
+        unrelated_child_id: "auto_skipped",
+    }
+    assert {item["id"]: item["marker"] for item in updated} == {
+        root_id: "root-field",
+        child_id: "child-field",
+        other_root_id: "other-root-field",
+        shared_id: "shared-field",
+        completed_id: "completed-field",
+        unrelated_child_id: "unrelated-field",
+    }
+
+    for selected_status_path in (root_status_path, child_status_path):
+        selected_status = json.loads(selected_status_path.read_text(encoding="utf-8"))
+        assert selected_status["retry_count"] == 0
+        assert selected_status["infra_error_count"] == 0
+        assert selected_status["last_infra_error_session_id"] is None
+        assert selected_status["sessions"] == []
+        assert selected_status["last_session_id"] is None
+        assert selected_status["last_failed_session_id"] is None
+        assert selected_status["resume_from_phase"] is None
+        assert selected_status["custom_diagnostic"] == {"keep": True}
+        for continuation_key in (
+            "continuation_pending",
+            "continuation_reason",
+            "continuation_count",
+            "context_overflow_count",
+            "previous_session_id",
+        ):
+            assert continuation_key not in selected_status
+
+    root_status = json.loads(root_status_path.read_text(encoding="utf-8"))
+    assert root_status["active_dev_branch"] == branch_name
+    assert root_status["base_branch"] == "main"
+    assert checkout_path.read_bytes() == protected_bytes["checkout"]
+    assert session_log.read_bytes() == protected_bytes["session"]
+    assert checkpoint.read_bytes() == protected_bytes["checkpoint"]
+    assert artifact.read_bytes() == protected_bytes["artifact"]
+    assert worktree_marker.read_bytes() == protected_bytes["worktree"]
+    assert other_status_path.read_bytes() == protected_bytes["other_status"]
+    assert completed_status_path.read_bytes() == protected_bytes["completed_status"]
+    assert source_path.read_bytes() == protected_bytes["source"]
+    assert _git(paths.project_root, "show-ref", "--heads") == branch_refs_before
+    assert _git(paths.project_root, "branch", "--show-current") == branch_before
+    assert _git(paths.project_root, "diff", "--", "source.txt") == source_diff_before
+    assert not (family.state_dir / "pipeline.json").exists()
+
+
+@pytest.mark.parametrize(
+    ("kind", "second_root_status"),
+    (("feature", "skipped"), ("bugfix", "needs_info"), ("refactor", "skipped")),
+)
+def test_state_only_all_recovers_all_supported_chains_without_pipeline_state(tmp_path, kind, second_root_status):
+    from prizmkit_runtime.reset import run_reset_command
+
+    paths = _make_paths(tmp_path / kind)
+    contract = FAMILY_CONTRACTS[kind]
+    prefix = contract["prefix"]
+    items = [
+        _item(f"{prefix}001", "failed"),
+        _item(f"{prefix}002", second_root_status),
+        _item(f"{prefix}003", "auto_skipped", [f"{prefix}001", f"{prefix}002"]),
+        _item(f"{prefix}004", "completed", marker="done"),
+        _item(f"{prefix}005", "pending", marker="unrelated"),
+    ]
+    family, plan_path = _family_and_plan(paths, kind, items)
+    completed_status_path, _ = _write_runtime_status(family, f"{prefix}004")
+    completed_before = completed_status_path.read_bytes()
+
+    result = run_reset_command(
+        kind,
+        ("--state-only", "--all", str(plan_path)),
+        paths,
+    )
+
+    assert result.exit_code == 0, result.render()
+    payload = json.loads(result.render())
+    assert payload["action"] == "reset_state"
+    assert payload["reset_count"] == 3
+    updated = json.loads(plan_path.read_text(encoding="utf-8"))[contract["list_key"]]
+    assert [item["status"] for item in updated] == [
+        "pending",
+        "pending",
+        "pending",
+        "completed",
+        "pending",
+    ]
+    assert completed_status_path.read_bytes() == completed_before
+    assert not (family.state_dir / "pipeline.json").exists()
+
+
+@pytest.mark.parametrize("kind", ("feature", "bugfix", "refactor"))
+def test_reset_without_mode_fails_before_any_mutation(tmp_path, kind):
+    from prizmkit_runtime.reset import run_reset_command
+
+    paths = _make_paths(tmp_path / kind)
+    prefix = FAMILY_CONTRACTS[kind]["prefix"]
+    family, plan_path = _family_and_plan(paths, kind, [_item(f"{prefix}001", "failed")])
+    marker = family.state_dir / "sentinel.bin"
+    marker.parent.mkdir(parents=True)
+    marker.write_bytes(b"runtime-sentinel")
+    before_plan = plan_path.read_bytes()
+    before_state = _tree_snapshot(family.state_dir)
+
+    result = run_reset_command(kind, (f"{prefix}001", str(plan_path)), paths)
+
+    assert result.exit_code != 0
+    assert "Exactly one reset mode is required" in result.render()
+    assert "--state-only" in result.render()
+    assert plan_path.read_bytes() == before_plan
+    assert _tree_snapshot(family.state_dir) == before_state
+
+
+@pytest.mark.parametrize(
+    "mode_pair",
+    (
+        ("--state-only", "--fresh-checkout"),
+        ("--state-only", "--clean"),
+        ("--state-only", "--preserve-runtime"),
+        ("--fresh-checkout", "--clean"),
+        ("--fresh-checkout", "--preserve-runtime"),
+        ("--clean", "--preserve-runtime"),
+    ),
+)
+def test_conflicting_reset_modes_fail_before_mutation(tmp_path, mode_pair):
+    from prizmkit_runtime.reset import run_reset_command
+
+    paths = _make_paths(tmp_path)
+    family, plan_path = _family_and_plan(paths, "feature", [_item("F-001", "failed")])
+    marker = family.state_dir / "sentinel.bin"
+    marker.parent.mkdir(parents=True)
+    marker.write_bytes(b"runtime-sentinel")
+    before_plan = plan_path.read_bytes()
+    before_state = _tree_snapshot(family.state_dir)
+
+    result = run_reset_command(
+        "feature",
+        ("F-001", *mode_pair, "--failed", str(plan_path)),
+        paths,
+    )
+
+    assert result.exit_code != 0
+    assert "Exactly one reset mode is required" in result.render()
+    assert plan_path.read_bytes() == before_plan
+    assert _tree_snapshot(family.state_dir) == before_state
+
+
+@pytest.mark.parametrize(
+    ("args", "message"),
+    (
+        (("F-001", "--standard"), "Unsupported reset arguments"),
+        (("--state-only",), "requires exactly one item ID or explicit --all"),
+        (("F-001", "--state-only", "--all"), "requires exactly one item ID or explicit --all"),
+        (("F-001:F-002", "--state-only"), "ranges and status filters are unsupported"),
+        (("--failed", "--state-only"), "ranges and status filters are unsupported"),
+        (("--fresh-checkout",), "requires exactly one item ID, range, or supported status filter"),
+        (("--fresh-checkout", "--all"), "--all is supported only with --state-only"),
+        (("--clean",), "requires exactly one item ID, range, or supported status filter"),
+        (("--clean", "--all"), "--all is supported only with --state-only"),
+        (("--preserve-runtime",), "requires --failed"),
+        (("F-001", "--failed", "--preserve-runtime"), "cannot target an ID, range, or --all"),
+        (("--failed", "--preserve-runtime", "--all"), "cannot target an ID, range, or --all"),
+    ),
+)
+def test_reset_selector_matrix_rejects_unsupported_forms_before_mutation(tmp_path, args, message):
+    from prizmkit_runtime.reset import run_reset_command
+
+    paths = _make_paths(tmp_path)
+    family, plan_path = _family_and_plan(
+        paths,
+        "feature",
+        [_item("F-001", "failed"), _item("F-002", "auto_skipped", ["F-001"])],
+    )
+    marker = family.state_dir / "sentinel.bin"
+    marker.parent.mkdir(parents=True)
+    marker.write_bytes(b"runtime-sentinel")
+    before_plan = plan_path.read_bytes()
+    before_state = _tree_snapshot(family.state_dir)
+
+    result = run_reset_command("feature", (*args, str(plan_path)), paths)
+
+    assert result.exit_code != 0
+    assert message in result.render()
+    assert plan_path.read_bytes() == before_plan
+    assert _tree_snapshot(family.state_dir) == before_state
+
+
+@pytest.mark.parametrize(
+    ("items", "args", "message"),
+    (
+        ([_item("F-001", "failed")], ("F-999", "--state-only"), "not found"),
+        ([_item("F-001", "pending")], ("F-001", "--state-only"), "not recoverable"),
+        ([_item("F-001", "auto_skipped")], ("F-001", "--state-only"), "unresolved auto_skipped blocker"),
+        ([_item("F-001", "completed")], ("--state-only", "--all"), "No recoverable blocking roots"),
+        (
+            [_item("F-001", "failed", ["F-002"]), _item("F-002", "auto_skipped", ["F-001"])],
+            ("F-001", "--state-only"),
+            "Dependency cycle",
+        ),
+    ),
+)
+def test_state_only_invalid_target_or_graph_is_fail_closed(tmp_path, items, args, message):
+    from prizmkit_runtime.reset import run_reset_command
+
+    paths = _make_paths(tmp_path)
+    family, plan_path = _family_and_plan(paths, "feature", items)
+    marker = family.state_dir / "sentinel.bin"
+    marker.parent.mkdir(parents=True)
+    marker.write_bytes(b"runtime-sentinel")
+    before_plan = plan_path.read_bytes()
+    before_state = _tree_snapshot(family.state_dir)
+
+    result = run_reset_command("feature", (*args, str(plan_path)), paths)
+
+    assert result.exit_code != 0
+    assert message in result.render()
+    assert plan_path.read_bytes() == before_plan
+    assert _tree_snapshot(family.state_dir) == before_state
+
+
+@pytest.mark.parametrize("kind", ("feature", "bugfix", "refactor"))
+@pytest.mark.parametrize("mode", ("--fresh-checkout", "--clean"))
+@pytest.mark.parametrize(
+    ("selector", "expected_numbers"),
+    (
+        (("X-003",), (3,)),
+        (("X-001:X-002",), (1, 2)),
+        (("--failed",), (1,)),
+    ),
+)
+def test_fresh_checkout_and_clean_keep_id_range_and_filter_selection(
+    monkeypatch,
+    tmp_path,
+    kind,
+    mode,
+    selector,
+    expected_numbers,
+):
+    from prizmkit_runtime import reset as reset_runtime
+    from prizmkit_runtime.reset import run_reset_command
+
+    paths = _make_paths(tmp_path)
+    prefix = FAMILY_CONTRACTS[kind]["prefix"]
+    normalized_selector = tuple(value.replace("X-", prefix) for value in selector)
+    family, plan_path = _family_and_plan(
+        paths,
+        kind,
+        [
+            _item(f"{prefix}001", "failed"),
+            _item(f"{prefix}002", "auto_skipped", [f"{prefix}001"]),
+            _item(f"{prefix}003", "pending"),
+        ],
+    )
+    family.state_dir.mkdir(parents=True, exist_ok=True)
+    (family.state_dir / "pipeline.json").write_text("{}\n", encoding="utf-8")
+    captured = []
+
+    def fake_reset_one(received_family, item, options, project_root, return_branch, lines):
+        captured.append((received_family.kind, item.item_id, options.fresh_checkout, options.clean))
+        return True
+
+    monkeypatch.setattr(reset_runtime, "_reset_one", fake_reset_one)
+    monkeypatch.setattr(reset_runtime, "default_branch", lambda _root: "main")
+
+    result = run_reset_command(
+        kind,
+        (*normalized_selector, mode, str(plan_path)),
+        paths,
+    )
+
+    assert result.exit_code == 0, result.render()
+    expected_ids = [f"{prefix}{number:03d}" for number in expected_numbers]
+    assert [entry[1] for entry in captured] == expected_ids
+    assert all(entry[2] is (mode == "--fresh-checkout") for entry in captured)
+    assert all(entry[3] is (mode == "--clean") for entry in captured)
+
+
+def _valid_bug(bug_id, status="pending", dependencies=None):
+    return {
+        "id": bug_id,
+        "title": bug_id,
+        "description": "Bug description",
+        "severity": "high",
+        "error_source": {"type": "failed_test", "content": "failure"},
+        "verification_type": "automated",
+        "acceptance_criteria": ["Regression is fixed"],
+        "status": status,
+        "dependencies": list(dependencies or []),
+    }
+
+
+def _run_bug_updater(plan_path, state_dir, *args):
+    return subprocess.run(
+        [
+            sys.executable,
+            str(PIPELINE_ROOT / "scripts" / "update-bug-status.py"),
+            "--bug-list",
+            str(plan_path),
+            "--state-dir",
+            str(state_dir),
+            "--project-root",
+            str(plan_path.parent),
+            *args,
+        ],
+        cwd=REPO_ROOT,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )
+
+
+@pytest.mark.parametrize(
+    ("session_status", "extra_args", "expected_root_status"),
+    (
+        ("failed", ("--max-retries", "1"), "failed"),
+        ("workflow_skipped", (), "skipped"),
+        ("workflow_blocked", (), "needs_info"),
+    ),
+)
+def test_bugfix_terminal_roots_auto_skip_pending_descendants(
+    tmp_path,
+    session_status,
+    extra_args,
+    expected_root_status,
+):
+    plan_path = tmp_path / "bug-fix-list.json"
+    state_dir = tmp_path / "state"
+    completed_status = state_dir / "B-004" / "status.json"
+    completed_status.parent.mkdir(parents=True)
+    completed_status.write_text('{"custom":"unchanged"}\n', encoding="utf-8")
+    completed_before = completed_status.read_bytes()
+    plan_path.write_text(
+        json.dumps(
+            {
+                "$schema": "dev-pipeline-bug-fix-list-v1",
+                "project_name": "Bug Cascade",
+                "bugs": [
+                    _valid_bug("B-001", "in_progress"),
+                    _valid_bug("B-002", "pending", ["B-001"]),
+                    _valid_bug("B-003", "pending", ["B-002"]),
+                    _valid_bug("B-004", "completed"),
+                ],
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    result = _run_bug_updater(
+        plan_path,
+        state_dir,
+        "--action",
+        "update",
+        "--bug-id",
+        "B-001",
+        "--session-status",
+        session_status,
+        *extra_args,
+    )
+
+    assert result.returncode == 0, (result.stdout, result.stderr)
+    summary = json.loads(result.stdout)
+    assert summary["auto_skipped"] == ["B-002", "B-003"]
+    statuses = {
+        bug["id"]: bug["status"]
+        for bug in json.loads(plan_path.read_text(encoding="utf-8"))["bugs"]
+    }
+    assert statuses == {
+        "B-001": expected_root_status,
+        "B-002": "auto_skipped",
+        "B-003": "auto_skipped",
+        "B-004": "completed",
+    }
+    assert completed_status.read_bytes() == completed_before
+
+
+def test_existing_bugfix_list_lazily_normalizes_blocked_pending_descendants(tmp_path):
+    plan_path = tmp_path / "bug-fix-list.json"
+    state_dir = tmp_path / "state"
+    data = {
+        "$schema": "dev-pipeline-bug-fix-list-v1",
+        "project_name": "Legacy Bug List",
+        "bugs": [
+            _valid_bug("B-001", "failed"),
+            _valid_bug("B-002", "pending", ["B-001"]),
+            _valid_bug("B-003", "pending", ["B-002"]),
+            _valid_bug("B-004", "completed"),
+        ],
+    }
+    plan_path.write_text(json.dumps(data), encoding="utf-8")
+
+    result = _run_bug_updater(plan_path, state_dir, "--action", "get_next")
+
+    assert result.returncode == 0, (result.stdout, result.stderr)
+    assert result.stdout.strip() == "PIPELINE_COMPLETE"
+    updated = json.loads(plan_path.read_text(encoding="utf-8"))
+    statuses = {bug["id"]: bug["status"] for bug in updated["bugs"]}
+    assert statuses == {
+        "B-001": "failed",
+        "B-002": "auto_skipped",
+        "B-003": "auto_skipped",
+        "B-004": "completed",
+    }
+
+    status_result = _run_bug_updater(plan_path, state_dir, "--action", "status")
+    assert status_result.returncode == 0
+    assert "Auto-skipped: 2" in status_result.stdout
+    assert "[⊘]" in status_result.stdout
+
+
+def test_bugfix_auto_skip_write_failure_is_nonzero_without_partial_state(monkeypatch, tmp_path, capsys):
+    plan_path = tmp_path / "bug-fix-list.json"
+    state_dir = tmp_path / "state"
+    data = {
+        "$schema": "dev-pipeline-bug-fix-list-v1",
+        "project_name": "Write Failure",
+        "bugs": [
+            _valid_bug("B-001", "failed"),
+            _valid_bug("B-002", "pending", ["B-001"]),
+        ],
+    }
+    plan_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    before = plan_path.read_bytes()
+    module = _load_source_module(
+        "f060_update_bug_status_write_failure",
+        PIPELINE_ROOT / "scripts" / "update-bug-status.py",
+    )
+    monkeypatch.setattr(module, "write_json_file", lambda *_args, **_kwargs: "permission denied")
+
+    with pytest.raises(SystemExit):
+        module.auto_skip_blocked_bugs(str(plan_path), str(state_dir), "B-001")
+
+    output = capsys.readouterr().out
+    assert "Failed to write auto-skipped bugs" in output
+    assert plan_path.read_bytes() == before
+    assert _tree_snapshot(state_dir) == {}
+
+
+def _load_source_module(name, path):
+    import importlib.util
+
+    spec = importlib.util.spec_from_file_location(name, path)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_bugfix_auto_skipped_schema_validators_and_aggregation_are_consistent():
+    from prizmkit_runtime.daemon import PROGRESS_COUNTS_BY_KIND
+    from prizmkit_runtime.runner_models import family_for
+    from prizmkit_runtime.runners import _completion_compatible_statuses
+    from prizmkit_runtime.paths import resolve_runtime_paths
+
+    schema = json.loads(
+        (PIPELINE_ROOT / "templates" / "bug-fix-list-schema.json").read_text(encoding="utf-8")
+    )
+    status_enum = schema["properties"]["bugs"]["items"]["properties"]["status"]["enum"]
+    assert "auto_skipped" in status_enum
+
+    init_module = _load_source_module(
+        "f060_init_bugfix",
+        PIPELINE_ROOT / "scripts" / "init-bugfix-pipeline.py",
+    )
+    planner_module = _load_source_module(
+        "f060_validate_bug_list",
+        REPO_ROOT
+        / "core"
+        / "skills"
+        / "orchestration-skill"
+        / "pipelines"
+        / "bug-planner"
+        / "scripts"
+        / "validate-bug-list.py",
+    )
+    assert "auto_skipped" in init_module.VALID_STATUSES
+    assert "auto_skipped" in init_module.TERMINAL_STATUSES
+    assert "auto_skipped" in planner_module.VALID_STATUSES
+
+    bugs = [
+        _valid_bug("B-001", "failed"),
+        _valid_bug("B-002", "pending", ["B-001"]),
+        _valid_bug("B-003", "auto_skipped", ["B-001"]),
+    ]
+    init_errors, _seen = init_module.validate_bugs(bugs)
+    assert init_errors == []
+    planner_result = planner_module.validate(
+        {
+            "$schema": "dev-pipeline-bug-fix-list-v1",
+            "project_name": "Validator Test",
+            "bugs": bugs,
+        }
+    )
+    assert planner_result["valid"] is True, planner_result["errors"]
+
+    assert "auto_skipped" in PROGRESS_COUNTS_BY_KIND["bugfix"]
+    paths = resolve_runtime_paths(pipeline_root=PIPELINE_ROOT, project_root=REPO_ROOT)
+    bug_family = family_for("bugfix", paths)
+    assert "auto_skipped" in _completion_compatible_statuses(bug_family)
+
+
+def test_all_updaters_expose_only_reset_state_internal_recovery_action():
+    retired_action = "un" + "skip"
+    for contract in FAMILY_CONTRACTS.values():
+        source = (PIPELINE_ROOT / "scripts" / contract["script"]).read_text(encoding="utf-8")
+        assert retired_action not in source
+        assert '"reset_state"' in source
+        assert '"action": "reset_state"' in source
+
+
+def test_canonical_reset_guidance_documents_every_explicit_mode_without_generated_outputs():
+    launcher_root = (
+        REPO_ROOT
+        / "core"
+        / "skills"
+        / "orchestration-skill"
+        / "pipelines"
+    )
+    launchers = {
+        "feature-pipeline-launcher": ("feature", "F-001"),
+        "bugfix-pipeline-launcher": ("bugfix", "B-001"),
+        "refactor-pipeline-launcher": ("refactor", "R-001"),
+    }
+    for launcher, (family, item_id) in launchers.items():
+        source = (launcher_root / launcher / "SKILL.md").read_text(encoding="utf-8")
+        assert f"reset {family} {item_id} --state-only" in source
+        assert f"reset {family} {item_id} --fresh-checkout" in source
+        assert f"reset {family} {item_id} --clean" in source
+        assert f"reset {family} --failed --preserve-runtime" in source
+        assert "exactly one mode" in source.lower()
+
+    memory_source = (REPO_ROOT / "core" / "templates" / "project-memory-template.md").read_text(
+        encoding="utf-8"
+    )
+    assert "reset <family> <task-id> --state-only" in memory_source
+    assert "reset <family> --state-only --all" in memory_source
+    assert "reset <family> <task-id-or-range> --fresh-checkout" in memory_source
+    assert "reset <family> <task-id-or-range> --clean" in memory_source
+    assert "reset <family> --failed --preserve-runtime" in memory_source
+    assert "<family> " + "un" + "skip" not in memory_source