prizmkit 1.1.149 → 1.1.150

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

@@ -2412,8 +2412,16 @@ def test_git_branch_worktree_plans_preserve_shell_invariants(tmp_path):
     assert any(command.args[:2] == ("rebase", "--abort") for command in ensure.commands)
     assert any(command.args[:2] == ("add", "-A") for command in ensure.commands)
     assert not any(command.args and command.args[0] == "stash" for command in ensure.commands)
+    assert not any(command.args and command.args[0] in {"merge", "push"} for command in save_wip.commands + ensure.commands)
+    assert not any(command.args[:2] == ("branch", "-d") for command in save_wip.commands + ensure.commands)
     assert ensure.never_fails is False
-    assert any(".*/worktrees/**" in " ".join(command.args) for command in save_wip.commands)
+    assert any(command.args == ("add", "-A", "--", ".") for command in save_wip.commands)
+    assert not any(
+        "exclude" in arg
+        for command in save_wip.commands
+        if command.args[:2] == ("add", "-A")
+        for arg in command.args
+    )
     assert worktree.commands[0].args[:2] == ("worktree", "add")
 
     allowed_failure_result = GitPlanResult(
@@ -2587,16 +2595,27 @@ def test_branch_return_ignores_installed_runtime_paths_without_blocking_wip_comm
     from prizmkit_runtime.gitops import branch_ensure_return
 
     _init_merge_repo(tmp_path)
-    (tmp_path / ".gitignore").write_text(".prizmkit/*\n.claude/\n", encoding="utf-8")
+    (tmp_path / ".gitignore").write_text(
+        ".prizmkit/*\n.claude/\n.codebuddy/\n.agents/\n.pi\n",
+        encoding="utf-8",
+    )
     subprocess.run(["git", "add", ".gitignore"], cwd=tmp_path, check=True)
     subprocess.run(["git", "commit", "-m", "ignore installed runtime"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
-    runtime_file = tmp_path / ".prizmkit" / "dev-pipeline" / "cli.py"
-    runtime_file.parent.mkdir(parents=True)
-    runtime_file.write_text("# installed runtime\n", encoding="utf-8")
+    ignored_files = (
+        tmp_path / ".prizmkit" / "dev-pipeline" / "cli.py",
+        tmp_path / ".claude" / "runtime.json",
+        tmp_path / ".codebuddy" / "runtime.json",
+        tmp_path / ".agents" / "runtime.json",
+        tmp_path / ".pi" / "runtime.json",
+    )
+    for ignored_file in ignored_files:
+        ignored_file.parent.mkdir(parents=True, exist_ok=True)
+        ignored_file.write_text("ignored support\n", encoding="utf-8")
     manifest = tmp_path / ".prizmkit" / "manifest.json"
     manifest.write_text('{}\n', encoding="utf-8")
     subprocess.run(["git", "checkout", "-b", "dev/interrupted"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
     (tmp_path / "interrupted.txt").write_text("preserved\n", encoding="utf-8")
+    (tmp_path / "interrupted [literal]*.txt").write_text("special path\n", encoding="utf-8")
 
     result = branch_ensure_return(tmp_path, "main", "dev/interrupted")
 
@@ -2607,6 +2626,168 @@ def test_branch_return_ignores_installed_runtime_paths_without_blocking_wip_comm
     assert subprocess.run(
         ["git", "show", "dev/interrupted:interrupted.txt"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
     ).stdout == "preserved\n"
+    assert subprocess.run(
+        ["git", "show", "dev/interrupted:interrupted [literal]*.txt"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout == "special path\n"
+    committed_paths = subprocess.run(
+        ["git", "ls-tree", "-r", "--name-only", "dev/interrupted"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout.splitlines()
+    assert not any(path.startswith((".claude/", ".codebuddy/", ".agents/", ".pi/")) for path in committed_paths)
+
+
+def test_clean_branch_return_skips_wip_commit_and_checks_out_base(tmp_path):
+    from prizmkit_runtime.gitops import branch_ensure_return
+
+    _init_merge_repo(tmp_path)
+    base_head = subprocess.run(
+        ["git", "rev-parse", "HEAD"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout.strip()
+    subprocess.run(["git", "checkout", "-b", "dev/clean-interrupt"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+
+    result = branch_ensure_return(tmp_path, "main", "dev/clean-interrupt")
+
+    assert result.ok is True
+    assert not any(command_result.args[:1] == ("commit",) for command_result in result.results)
+    assert subprocess.run(
+        ["git", "branch", "--show-current"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout.strip() == "main"
+    assert subprocess.run(
+        ["git", "rev-parse", "dev/clean-interrupt"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout.strip() == base_head
+
+
+def test_branch_return_commits_staged_unstaged_deleted_renamed_and_special_paths(tmp_path):
+    from prizmkit_runtime.gitops import branch_ensure_return
+
+    _init_merge_repo(tmp_path)
+    tracked_paths = {
+        "mixed.txt": "base mixed\n",
+        "delete me.txt": "delete me\n",
+        "rename source.txt": "rename me\n",
+    }
+    for relative, content in tracked_paths.items():
+        (tmp_path / relative).write_text(content, encoding="utf-8")
+    subprocess.run(["git", "add", "--", *tracked_paths], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-m", "wip matrix base"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    subprocess.run(["git", "checkout", "-b", "dev/wip-matrix"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+
+    (tmp_path / "mixed.txt").write_text("staged version\n", encoding="utf-8")
+    subprocess.run(["git", "add", "mixed.txt"], cwd=tmp_path, check=True)
+    (tmp_path / "mixed.txt").write_text("final unstaged version\n", encoding="utf-8")
+    (tmp_path / "delete me.txt").unlink()
+    subprocess.run(["git", "mv", "rename source.txt", "renamed [literal]*.txt"], cwd=tmp_path, check=True)
+    (tmp_path / "new [literal]*.txt").write_text("new special\n", encoding="utf-8")
+
+    result = branch_ensure_return(tmp_path, "main", "dev/wip-matrix")
+
+    assert result.ok is True
+    assert subprocess.run(
+        ["git", "branch", "--show-current"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
+    ).stdout.strip() == "main"
+    assert subprocess.run(
+        ["git", "show", "dev/wip-matrix:mixed.txt"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
+    ).stdout == "final unstaged version\n"
+    assert subprocess.run(
+        ["git", "show", "dev/wip-matrix:renamed [literal]*.txt"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout == "rename me\n"
+    assert subprocess.run(
+        ["git", "show", "dev/wip-matrix:new [literal]*.txt"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout == "new special\n"
+    task_tree = subprocess.run(
+        ["git", "ls-tree", "-r", "--name-only", "dev/wip-matrix"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout.splitlines()
+    assert "delete me.txt" not in task_tree
+    assert "rename source.txt" not in task_tree
+
+
+def test_branch_return_rejects_unmerged_paths_without_commit_or_checkout(tmp_path):
+    from prizmkit_runtime.gitops import branch_ensure_return
+
+    _init_merge_repo(tmp_path)
+    subprocess.run(["git", "checkout", "-b", "dev/conflicted"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    (tmp_path / "app.txt").write_text("task side\n", encoding="utf-8")
+    subprocess.run(["git", "commit", "-am", "task side"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    subprocess.run(["git", "checkout", "main"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    (tmp_path / "app.txt").write_text("base side\n", encoding="utf-8")
+    subprocess.run(["git", "commit", "-am", "base side"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    subprocess.run(["git", "checkout", "dev/conflicted"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    merge = subprocess.run(
+        ["git", "merge", "main"],
+        cwd=tmp_path,
+        check=False,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    assert merge.returncode != 0
+    head_before = subprocess.run(
+        ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
+    ).stdout.strip()
+
+    result = branch_ensure_return(tmp_path, "main", "dev/conflicted")
+
+    assert result.ok is False
+    assert "unresolved Git paths" in result.results[-1].stderr
+    assert subprocess.run(
+        ["git", "branch", "--show-current"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
+    ).stdout.strip() == "dev/conflicted"
+    assert subprocess.run(
+        ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
+    ).stdout.strip() == head_before
+    assert subprocess.run(
+        ["git", "ls-files", "-u"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
+    ).stdout.strip()
+
+
+def test_branch_save_wip_rejects_clean_recorded_branch_mismatch(tmp_path):
+    from prizmkit_runtime.gitops import branch_save_wip
+
+    _init_merge_repo(tmp_path)
+    subprocess.run(["git", "checkout", "-b", "dev/unrelated"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+
+    result = branch_save_wip(tmp_path, "dev/recorded-task")
+
+    assert result.ok is False
+    assert result.results[-1].stderr == "Active branch dev/unrelated does not match task branch dev/recorded-task"
+    assert subprocess.run(
+        ["git", "branch", "--show-current"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout.strip() == "dev/unrelated"
 
 
 def test_branch_return_commit_failure_does_not_checkout_base(monkeypatch, tmp_path):
@@ -3104,3 +3285,142 @@ def test_daemon_status_cli_preserves_pure_json_stdout(tmp_path):
     assert "Python feature daemon" not in result.stdout
     assert "Transition command contract" not in result.stdout
 
+
+def test_active_checkout_replacement_is_guarded_and_never_writes_reset_tombstone(tmp_path):
+    from prizmkit_runtime.task_checkout import (
+        TaskCheckout,
+        TaskCheckoutError,
+        load_task_checkout,
+        persist_task_checkout,
+        replace_active_task_checkout_locked,
+    )
+
+    state_dir = tmp_path / "state"
+    expected = TaskCheckout.active("feature", "F-001", "dev/F-001-old", "main")
+    replacement = TaskCheckout.active("feature", "F-001", "dev/F-001-resume", "main")
+    persist_task_checkout(state_dir, expected)
+
+    path = replace_active_task_checkout_locked(state_dir, expected, replacement)
+
+    assert path == state_dir / "F-001" / "checkout.json"
+    loaded = load_task_checkout(state_dir, "feature", "F-001")
+    assert loaded == replacement
+    assert loaded is not None and loaded.is_reset is False
+    with pytest.raises(TaskCheckoutError, match="changed before recovery replacement"):
+        replace_active_task_checkout_locked(state_dir, expected, replacement)
+
+
+def test_checkpoint_rewind_preserves_planning_and_resets_implementation_downstream():
+    from prizmkit_runtime.checkpoint_state import (
+        rewind_checkpoint_for_implementation,
+        validate_checkpoint_data,
+    )
+
+    skills = [
+        "prizmkit-plan",
+        "prizmkit-implement",
+        "prizmkit-code-review",
+        "prizmkit-test",
+        "prizmkit-retrospective",
+        "prizmkit-committer",
+        "completion-summary",
+    ]
+    steps = []
+    previous = None
+    for index, skill in enumerate(skills, start=1):
+        status = "pending"
+        stage_result = None
+        if skill == "prizmkit-plan":
+            status, stage_result = "completed", "PLAN_READY"
+        elif skill == "prizmkit-implement":
+            status, stage_result = "completed", "IMPLEMENTED"
+        elif skill == "prizmkit-code-review":
+            status, stage_result = "failed", "REVIEW_NEEDS_FIXES"
+        step = {
+            "id": f"S{index:02d}",
+            "skill": skill,
+            "name": skill,
+            "status": status,
+            "depends_on": previous,
+            "required_artifacts": [],
+        }
+        if stage_result:
+            step["stage_result"] = stage_result
+        steps.append(step)
+        previous = step["id"]
+    payload = {
+        "version": 1,
+        "workflow_type": "feature-pipeline",
+        "steps": steps,
+        "feature_state": {
+            "schema_version": 1,
+            "artifact_dir": ".prizmkit/specs/example",
+            "orchestrator": "prizmkit-l4",
+            "stage": "code-review",
+            "current_stage": "prizmkit-code-review",
+            "status": "failed",
+            "stage_result": "REVIEW_NEEDS_FIXES",
+            "repair_scope": "production",
+            "repair_round": 2,
+            "next_stage": "prizmkit-implement",
+            "resume_from": "prizmkit-implement",
+            "blocked_reason": "review_needs_fixes",
+            "terminal_status": "WORKFLOW_BLOCKED",
+            "completed_stages": ["plan", "implement"],
+        },
+    }
+
+    rewound = rewind_checkpoint_for_implementation(payload)
+
+    assert rewound is not payload
+    assert rewound["steps"][0] == payload["steps"][0]
+    assert all(step["status"] == "pending" for step in rewound["steps"][1:])
+    assert all("stage_result" not in step for step in rewound["steps"][1:])
+    semantic = rewound["feature_state"]
+    assert semantic["stage"] == "implement"
+    assert semantic["current_stage"] == "prizmkit-implement"
+    assert semantic["status"] == "pending"
+    assert semantic["repair_round"] == 0
+    assert semantic["completed_stages"] == ["plan"]
+    assert semantic["blocked_reason"] is None
+    assert semantic["terminal_status"] is None
+    assert "stage_result" not in semantic
+    validated = validate_checkpoint_data(rewound)
+    assert validated.valid is True
+    assert validated.current_step is not None
+    assert validated.current_step.skill == "prizmkit-implement"
+
+
+def test_git_recovery_helpers_create_branch_without_checkout_and_report_registration(tmp_path):
+    from prizmkit_runtime.gitops import (
+        create_branch_from_base,
+        local_branch_exists,
+        registered_worktrees,
+    )
+
+    subprocess.run(["git", "init", "-b", "main"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=tmp_path, check=True)
+    (tmp_path / "base.txt").write_text("base\n", encoding="utf-8")
+    subprocess.run(["git", "add", "base.txt"], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-m", "base"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
+
+    assert local_branch_exists(tmp_path, "main") is True
+    assert local_branch_exists(tmp_path, "missing") is False
+    result = create_branch_from_base(tmp_path, "dev/F-001-resume", "main")
+
+    assert result.return_code == 0
+    assert local_branch_exists(tmp_path, "dev/F-001-resume") is True
+    assert subprocess.run(
+        ["git", "branch", "--show-current"],
+        cwd=tmp_path,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    ).stdout.strip() == "main"
+    registrations = registered_worktrees(tmp_path)
+    assert any(
+        registration.path == tmp_path.resolve() and registration.branch == "main"
+        for registration in registrations
+    )
+

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.149",
+  "version": "1.1.150",
   "skills": {
     "prizmkit": {
       "description": "Framework introduction and navigation for the formal single-requirement lifecycle, project initialization, Prizm docs, and independent deployment.",

package/bundled/skills/bugfix-pipeline-launcher/SKILL.md

@@ -51,7 +51,7 @@ Read `${SKILL_DIR}/references/configuration.md` before constructing prerequisite
 | Check status | Daemon status and item-level status commands |
 | Show logs | Recent or follow-log command |
 | Stop | Daemon stop command plus optional status command |
-| Retry one bug | Standard or clean reset-and-run command with safety disclosure |
+| Retry failed bug work | Preserve-runtime, standard, or clean reset plus a separate run command with safety disclosure |
 
 Only the start intent uses the execution-mode and configuration rounds.
 
@@ -151,27 +151,39 @@ Optionally include the daemon status command for the user to run afterward. Do n
 
 ## Retry Command
 
-A reset can discard uncommitted changes when the target task branch is currently checked out. Clean reset additionally deletes the task branch and clears its task history/artifacts. Never hide these effects behind the word “retry.”
+Reset changes state only; it never starts execution and rejects `--run`. Always return reset and run as separate commands.
 
-Use `AskUserQuestion` before constructing a retry command:
+A standard reset can discard uncommitted changes when the target task branch is currently checked out and records a fresh-checkout boundary. Clean reset additionally deletes the task branch and clears task history/artifacts. Preserve-runtime failed recovery instead scans the whole selected list, restores every failed root and its causal `auto_skipped` descendants, and retains valid checkout identity, sessions, checkpoints, artifacts, branches, worktrees, and WIP. If a recorded branch is missing, it creates a replacement from the recorded base, retains old artifacts for reference, and rewinds implementation-and-later checkpoint stages. Never hide these effects behind the word “retry.”
 
-- **Standard retry (Recommended)** — reset task status and rerun while preserving a non-current task branch; warn that an active task branch may still have uncommitted changes discarded by reset.
-- **Clean retry** — perform the standard reset and also delete the task branch and clear task history/artifacts.
-- **Cancel** — return no reset command.
+Use `AskUserQuestion` before constructing retry commands:
+
+- **Preserve failed runtime (Recommended for continuing failed work)** — recover all failed chains in the selected list without cleanup, then run the list; disclose that this is whole-list recovery rather than a single-ID reset.
+- **Standard fresh retry** — reset one bug, then run that bug separately; warn that the active task branch can lose uncommitted changes.
+- **Clean retry** — reset one bug, delete its task branch/history/artifacts, then run it separately.
+- **Cancel** — return no reset or run command.
+
+Preserve-runtime template:
+
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix --failed --preserve-runtime .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py bugfix run .prizmkit/plans/bug-fix-list.json
+```
 
 Standard template:
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix B-001 --run .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix B-001 .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py bugfix run B-001 .prizmkit/plans/bug-fix-list.json
 ```
 
 Clean template:
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix B-001 --clean --run .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix B-001 --clean .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py bugfix run B-001 .prizmkit/plans/bug-fix-list.json
 ```
 
-For clean retry, require explicit acknowledgement of branch deletion and possible uncommitted-change loss before displaying the command.
+`--preserve-runtime` requires `--failed` and cannot be combined with `--clean`, an ID, a range, or another reset filter. Retry-budget flags such as `--max-retries` and `--max-infra-retries` belong on the run command, never reset. For clean retry, require explicit acknowledgement of branch deletion and possible uncommitted-change loss before displaying either command.
 
 ## Output Contract
 

package/bundled/skills/feature-pipeline-launcher/SKILL.md

@@ -54,7 +54,7 @@ Classify the request before asking configuration questions:
 | Check status | Daemon status and item-level status commands |
 | Show logs | Recent or follow-log command |
 | Stop | Daemon stop command plus optional status command |
-| Retry one feature | Standard or clean reset-and-run command with safety disclosure |
+| Retry failed feature work | Preserve-runtime, standard, or clean reset plus a separate run command with safety disclosure |
 
 Only the start intent uses the execution-mode and configuration rounds.
 
@@ -169,27 +169,39 @@ Optionally include the daemon status command for the user to run afterward. Do n
 
 ## Retry Command
 
-A reset can discard uncommitted changes when the target task branch is currently checked out. Clean reset additionally deletes the task branch and clears its task history/artifacts. Never hide these effects behind the word “retry.”
+Reset changes state only; it never starts execution and rejects `--run`. Always return reset and run as separate commands.
 
-Use `AskUserQuestion` before constructing a retry command:
+A standard reset can discard uncommitted changes when the target task branch is currently checked out and records a fresh-checkout boundary. Clean reset additionally deletes the task branch and clears task history/artifacts. Preserve-runtime failed recovery instead scans the whole selected list, restores every failed root and its causal `auto_skipped` descendants, and retains valid checkout identity, sessions, checkpoints, artifacts, branches, worktrees, and WIP. If a recorded branch is missing, it creates a replacement from the recorded base, retains old artifacts for reference, and rewinds implementation-and-later checkpoint stages. Never hide these effects behind the word “retry.”
 
-- **Standard retry (Recommended)** — reset task status and rerun while preserving a non-current task branch; warn that an active task branch may still have uncommitted changes discarded by reset.
-- **Clean retry** — perform the standard reset and also delete the task branch and clear task history/artifacts.
-- **Cancel** — return no reset command.
+Use `AskUserQuestion` before constructing retry commands:
+
+- **Preserve failed runtime (Recommended for continuing failed work)** — recover all failed chains in the selected list without cleanup, then run the list; disclose that this is whole-list recovery rather than a single-ID reset.
+- **Standard fresh retry** — reset one feature, then run that feature separately; warn that the active task branch can lose uncommitted changes.
+- **Clean retry** — reset one feature, delete its task branch/history/artifacts, then run it separately.
+- **Cancel** — return no reset or run command.
+
+Preserve-runtime template:
+
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py reset feature --failed --preserve-runtime .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
+```
 
 Standard template:
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-001 --run .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-001 .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py feature run F-001 .prizmkit/plans/feature-list.json
 ```
 
 Clean template:
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-001 --clean --run .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-001 --clean .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py feature run F-001 .prizmkit/plans/feature-list.json
 ```
 
-For clean retry, require explicit acknowledgement of branch deletion and possible uncommitted-change loss before displaying the command.
+`--preserve-runtime` requires `--failed` and cannot be combined with `--clean`, an ID, a range, or another reset filter. Retry-budget flags such as `--max-retries` and `--max-infra-retries` belong on the run command, never reset. For clean retry, require explicit acknowledgement of branch deletion and possible uncommitted-change loss before displaying either command.
 
 ## Output Contract
 

package/bundled/skills/refactor-pipeline-launcher/SKILL.md

@@ -52,7 +52,7 @@ Read `${SKILL_DIR}/references/configuration.md` before constructing prerequisite
 | Check status | Daemon status and item-level status commands |
 | Show logs | Recent or follow-log command |
 | Stop | Daemon stop command plus optional status command |
-| Retry one refactor | Standard or clean reset-and-run command with safety disclosure |
+| Retry failed refactor work | Preserve-runtime, standard, or clean reset plus a separate run command with safety disclosure |
 
 Only the start intent uses the execution-mode and configuration rounds.
 
@@ -164,27 +164,39 @@ Optionally include the daemon status command for the user to run afterward. Do n
 
 ## Retry Command
 
-A reset can discard uncommitted changes when the target task branch is currently checked out. Clean reset additionally deletes the task branch and clears its task history/artifacts. Never hide these effects behind the word “retry.”
+Reset changes state only; it never starts execution and rejects `--run`. Always return reset and run as separate commands.
 
-Use `AskUserQuestion` before constructing a retry command:
+A standard reset can discard uncommitted changes when the target task branch is currently checked out and records a fresh-checkout boundary. Clean reset additionally deletes the task branch and clears task history/artifacts. Preserve-runtime failed recovery instead scans the whole selected list, restores every failed root and its causal `auto_skipped` descendants, and retains valid checkout identity, sessions, checkpoints, artifacts, branches, worktrees, and WIP. If a recorded branch is missing, it creates a replacement from the recorded base, retains old artifacts for reference, and rewinds implementation-and-later checkpoint stages. Never hide these effects behind the word “retry.”
 
-- **Standard retry (Recommended)** — reset task status and rerun while preserving a non-current task branch; warn that an active task branch may still have uncommitted changes discarded by reset.
-- **Clean retry** — perform the standard reset and also delete the task branch and clear task history/artifacts.
-- **Cancel** — return no reset command.
+Use `AskUserQuestion` before constructing retry commands:
+
+- **Preserve failed runtime (Recommended for continuing failed work)** — recover all failed chains in the selected list without cleanup, then run the list; disclose that this is whole-list recovery rather than a single-ID reset.
+- **Standard fresh retry** — reset one refactor, then run that refactor separately; warn that the active task branch can lose uncommitted changes.
+- **Clean retry** — reset one refactor, delete its task branch/history/artifacts, then run it separately.
+- **Cancel** — return no reset or run command.
+
+Preserve-runtime template:
+
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py reset refactor --failed --preserve-runtime .prizmkit/plans/refactor-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py refactor run .prizmkit/plans/refactor-list.json
+```
 
 Standard template:
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py reset refactor R-001 --run .prizmkit/plans/refactor-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset refactor R-001 .prizmkit/plans/refactor-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py refactor run R-001 .prizmkit/plans/refactor-list.json
 ```
 
 Clean template:
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py reset refactor R-001 --clean --run .prizmkit/plans/refactor-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset refactor R-001 --clean .prizmkit/plans/refactor-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py refactor run R-001 .prizmkit/plans/refactor-list.json
 ```
 
-For clean retry, require explicit acknowledgement of branch deletion and possible uncommitted-change loss before displaying the command.
+`--preserve-runtime` requires `--failed` and cannot be combined with `--clean`, an ID, a range, or another reset filter. Retry-budget flags such as `--max-retries` and `--max-infra-retries` belong on the run command, never reset. For clean retry, require explicit acknowledgement of branch deletion and possible uncommitted-change loss before displaying either command.
 
 ## Output Contract
 

package/bundled/templates/project-memory-template.md

@@ -32,6 +32,44 @@ This project uses PrizmKit with the Prizm documentation system for AI-optimized
 ### Available Commands
 Run `/prizmkit` to see all available PrizmKit commands.
 
+### Python Runtime CLI Quick Reference
+
+Placeholders: `<family> = feature | bugfix | refactor`; `<task-id> = F-NNN | B-NNN | R-NNN`; `<list>` is optional and defaults by family:
+
+| `<family>` | Default `<list>` |
+|---|---|
+| `feature` | `.prizmkit/plans/feature-list.json` |
+| `bugfix` | `.prizmkit/plans/bug-fix-list.json` |
+| `refactor` | `.prizmkit/plans/refactor-list.json` |
+
+```bash
+# Run/resume the whole list or one task
+python3 ./.prizmkit/dev-pipeline/cli.py <family> run [<list>] [--max-retries N] [--max-infra-retries N]
+python3 ./.prizmkit/dev-pipeline/cli.py <family> run <task-id> [<list>] [--max-retries N] [--max-infra-retries N]
+
+# Inspect or recover task state
+python3 ./.prizmkit/dev-pipeline/cli.py <family> status [<list>]
+python3 ./.prizmkit/dev-pipeline/cli.py <family> unskip [<task-id>] [<list>]
+python3 ./.prizmkit/dev-pipeline/cli.py recovery detect
+
+# Reset state (never starts execution)
+python3 ./.prizmkit/dev-pipeline/cli.py reset <family> <task-id> [<list>]
+python3 ./.prizmkit/dev-pipeline/cli.py reset <family> --failed --preserve-runtime [<list>]
+python3 ./.prizmkit/dev-pipeline/cli.py reset <family> <task-id> --clean [<list>]
+
+# Background operation
+python3 ./.prizmkit/dev-pipeline/cli.py daemon <family> start [<list>]
+python3 ./.prizmkit/dev-pipeline/cli.py daemon <family> status
+python3 ./.prizmkit/dev-pipeline/cli.py daemon <family> logs [--lines N|--follow]
+python3 ./.prizmkit/dev-pipeline/cli.py daemon <family> stop
+```
+
+Runtime boundaries:
+- Reset and run are separate operations; reset rejects `--run`. Retry ceilings belong to `run`, not reset.
+- `--preserve-runtime` requires `--failed`, scans the whole selected list, and cannot be combined with `--clean`, an ID/range, or another reset filter.
+- Preserve-runtime recovery keeps valid checkout identity, sessions, checkpoints, artifacts, branches, worktrees, and WIP. If the recorded branch is missing, it creates a replacement from the recorded base and rewinds implementation-and-later checkpoint stages while retaining old artifacts for reference. Clean reset is destructive.
+- In zsh/Bash multiline commands, `\` must be the final character on the line with no trailing space.
+
 ### Lightweight Planning Path
 Not every change needs the full formal-requirement lifecycle. Use the lightweight path for:
 - Bug fixes with clear root cause, config tweaks, typo fixes, simple refactors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.149",
+  "version": "1.1.150",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {