prizmkit 1.1.149 → 1.1.150

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.149",
-  "bundledAt": "2026-07-25T02:52:20.120Z",
-  "bundledFrom": "4b222c1"
+  "frameworkVersion": "1.1.150",
+  "bundledAt": "2026-07-25T15:41:05.690Z",
+  "bundledFrom": "a759b38"
 }

package/bundled/dev-pipeline/README.md

@@ -96,34 +96,36 @@ If `.prizmkit/plans/feature-list.json` path is omitted, defaults to `.prizmkit/p
 
 ---
 
-### `cli.py reset feature` — Reset & Retry Failed/Stuck Feature
+### `cli.py reset feature` — Reset Feature Recovery State
 
-Resets a feature's state so it can be re-executed from scratch.
+Reset is state-only and never starts execution. `--run` is unsupported; invoke `feature run` separately after a successful reset.
 
 ```bash
-python3 ./cli.py reset feature <feature-id> [--clean] [--run] [.prizmkit/plans/feature-list.json]
+python3 ./cli.py reset feature <feature-id> [--clean] [.prizmkit/plans/feature-list.json]
+python3 ./cli.py reset feature --failed --preserve-runtime [.prizmkit/plans/feature-list.json]
 ```
 
 | Flag | Description |
 |------|-------------|
-| `--clean` | Delete session history + `.prizmkit/specs/{slug}/` artifacts |
-| `--run` | Immediately run after reset |
+| `--clean` | Delete the task branch, session history, and `.prizmkit/specs/{slug}/` artifacts |
+| `--failed --preserve-runtime` | Restore every failed chain in the list while retaining checkout identity, branches/worktrees, sessions, checkpoints, artifacts, and WIP |
 
-**What gets cleaned with `--clean`:**
-- `state/features/F-XXX/sessions/` — all session logs and prompts
-- `.prizmkit/specs/{feature-slug}/` — spec.md, plan.md, context-snapshot.md
-
-**What is always reset (with or without `--clean`):**
-- `status.json` — status → pending, retry_count → 0
-- `.prizmkit/plans/feature-list.json` — feature status → pending
+`--preserve-runtime` requires `--failed` and cannot be combined with `--clean`, an item ID/range, or another reset filter. It restores every `failed` root plus causal `auto_skipped` descendants, clears code/infrastructure retry counters, and marks continuation pending without clearing existing history or failure metadata. Valid checkout/branch/worktree/checkpoint identity is reused unchanged; when the recorded branch is missing, reset creates a replacement from the recorded base, retains old artifacts for reference, and rewinds implementation-and-later checkpoint stages to `pending`.
 
 **Examples:**
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-007                    # Reset status only
-python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-007 --clean            # Reset + delete artifacts
-python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-007 --clean --run      # Reset + clean + retry
+# Preserve all failed runtime chains, then execute separately
+python3 ./.prizmkit/dev-pipeline/cli.py reset feature --failed --preserve-runtime
+python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
+
+# Fresh single-feature reset, then execute separately
+python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-007
+python3 ./.prizmkit/dev-pipeline/cli.py feature run F-007
+
+# Destructive clean reset, then execute separately
 python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-007 --clean my-features.json
+python3 ./.prizmkit/dev-pipeline/cli.py feature run F-007 my-features.json
 ```
 
 ---
@@ -598,8 +600,9 @@ Specify a model for individual features in `.prizmkit/plans/feature-list.json`:
 # All features without a per-feature model use Sonnet
 MODEL=claude-sonnet-4.6 python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
 
-# Retry with Opus
-MODEL=claude-opus-4.6 python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-007 --clean --run
+# Destructively reset, then retry with Opus as a separate run
+python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-007 --clean
+MODEL=claude-opus-4.6 python3 ./.prizmkit/dev-pipeline/cli.py feature run F-007
 
 # Test which model the CLI is using
 MODEL=claude-sonnet-4.6 python3 ./.prizmkit/dev-pipeline/cli.py feature test-cli

package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import copy
 import json
 import re
 from dataclasses import dataclass, field
@@ -443,6 +444,82 @@ def invalid_existing_checkpoint(path: str | Path | None) -> CheckpointState | No
     return None
 
 
+def rewind_checkpoint_for_implementation(
+    data: Mapping[str, Any],
+    *,
+    path: str | Path | None = None,
+    project_root: str | Path | None = None,
+) -> dict[str, Any]:
+    """Return a validated copy rewound from implementation through completion."""
+    state = validate_checkpoint_data(
+        data,
+        path=path,
+        exists=True,
+        project_root=project_root,
+    )
+    if not state.valid:
+        raise ValueError(f"Invalid checkpoint: {state.error_code}: {state.error_message}")
+    if not state.semantic.sequence_valid:
+        detail = state.semantic.error_message or "mandatory stage sequence is invalid"
+        raise ValueError(f"Invalid checkpoint: {detail}")
+
+    implementation_indexes = [
+        step.index for step in state.steps if step.skill == "prizmkit-implement"
+    ]
+    if len(implementation_indexes) != 1:
+        raise ValueError("Invalid checkpoint: expected exactly one prizmkit-implement step")
+
+    rewound = copy.deepcopy(dict(data))
+    raw_steps = rewound.get("steps")
+    if not isinstance(raw_steps, list):
+        raise ValueError("Invalid checkpoint: steps must be an array")
+    implementation_index = implementation_indexes[0]
+    for raw_step in raw_steps[implementation_index:]:
+        if not isinstance(raw_step, dict):
+            raise ValueError("Invalid checkpoint: every step must be an object")
+        raw_step["status"] = "pending"
+        raw_step.pop("stage_result", None)
+
+    state_key = semantic_state_key(state.semantic.workflow_type)
+    raw_semantic = rewound.get(state_key)
+    if not isinstance(raw_semantic, dict):
+        raise ValueError(f"Invalid checkpoint: {state_key} must be an object")
+    raw_semantic.update(
+        {
+            "stage": "implement",
+            "current_stage": "prizmkit-implement",
+            "status": "pending",
+            "repair_scope": None,
+            "repair_round": 0,
+            "next_stage": "prizmkit-implement",
+            "resume_from": "prizmkit-implement",
+            "blocked_reason": None,
+            "terminal_status": None,
+        }
+    )
+    raw_semantic.pop("stage_result", None)
+    if isinstance(raw_semantic.get("completed_stages"), list):
+        raw_semantic["completed_stages"] = [
+            value
+            for value in raw_semantic["completed_stages"]
+            if value in {"plan", "prizmkit-plan"}
+        ]
+    for key in ("complete", "completion_ready", "test_result_valid"):
+        if key in raw_semantic:
+            raw_semantic[key] = False
+
+    validated = validate_checkpoint_data(
+        rewound,
+        path=path,
+        exists=True,
+        project_root=project_root,
+    )
+    if not validated.valid or not validated.semantic.sequence_valid:
+        detail = validated.error_message or validated.semantic.error_message or "rewind validation failed"
+        raise ValueError(f"Invalid rewound checkpoint: {detail}")
+    return rewound
+
+
 def semantic_state_key(workflow_type: str) -> str:
     """Return the family-owned L4 semantic metadata key."""
     return SEMANTIC_STATE_KEYS.get(workflow_type, "l4_state")

package/bundled/dev-pipeline/prizmkit_runtime/gitops.py

@@ -23,8 +23,8 @@ PIPELINE_METADATA_EXCLUDES = (
 
 HIDDEN_TOOL_WORKTREE_EXCLUDES = (
     *PIPELINE_METADATA_EXCLUDES,
-    ":(top,exclude).skills-lock.json",
-    ":(top,exclude).AGENTS.md",
+    ":(top,exclude)skills-lock.json",
+    ":(top,exclude)AGENTS.md",
     ":(top,exclude).claude",
     ":(top,exclude,glob).claude/**",
     ":(top,exclude).codebuddy",
@@ -126,6 +126,14 @@ class WorktreeSupportAssetsResult:
     reason: str = ""
 
 
+@dataclass(frozen=True)
+class RegisteredWorktree:
+    """One path/branch pair reported by ``git worktree list --porcelain``."""
+
+    path: Path
+    branch: str = ""
+
+
 def _safe_worktree_name(branch_name: str) -> str:
     safe = re.sub(r"[^A-Za-z0-9._-]+", "-", branch_name.strip())
     safe = safe.strip(".-")
@@ -194,20 +202,59 @@ def worktree_remove_plan(runtime: WorktreeRuntimeContext, *, delete_branch: bool
     )
 
 
-def worktree_registered(runtime: WorktreeRuntimeContext) -> bool:
-    """Return whether git worktree metadata contains the resolved path."""
-    result = run_git_command(runtime.context.project_root, ("worktree", "list", "--porcelain"))
+def registered_worktrees(project_root: Path) -> tuple[RegisteredWorktree, ...]:
+    """Return registered worktree identities without changing repository state."""
+    result = run_git_command(project_root, ("worktree", "list", "--porcelain"))
     if result.return_code != 0:
-        return False
-    target = str(runtime.worktree_path.resolve())
-    candidates: list[str] = []
-    for line in result.stdout.splitlines():
+        return ()
+    registrations: list[RegisteredWorktree] = []
+    current_path: Path | None = None
+    current_branch = ""
+    for line in (*result.stdout.splitlines(), ""):
         stripped = line.strip()
         if stripped.startswith("worktree "):
-            candidates.append(stripped.removeprefix("worktree ").strip())
-        elif stripped:
-            candidates.append(stripped.split()[0])
-    return any(Path(candidate).resolve() == Path(target) for candidate in candidates if candidate)
+            if current_path is not None:
+                registrations.append(RegisteredWorktree(current_path.resolve(), current_branch))
+            current_path = Path(stripped.removeprefix("worktree ").strip())
+            current_branch = ""
+        elif stripped.startswith("branch "):
+            current_branch = stripped.removeprefix("branch ").strip().removeprefix("refs/heads/")
+        elif not stripped and current_path is not None:
+            registrations.append(RegisteredWorktree(current_path.resolve(), current_branch))
+            current_path = None
+            current_branch = ""
+        elif current_path is None and stripped:
+            legacy = re.match(r"^(.*?)\s+[0-9a-fA-F]+\s+\[([^]]+)]$", stripped)
+            if legacy:
+                registrations.append(
+                    RegisteredWorktree(Path(legacy.group(1)).resolve(), legacy.group(2))
+                )
+    return tuple(registrations)
+
+
+def worktree_registered(runtime: WorktreeRuntimeContext) -> bool:
+    """Return whether Git metadata contains the resolved path and task branch."""
+    target = runtime.worktree_path.resolve()
+    branch = runtime.context.working_branch
+    return any(
+        registration.path == target and registration.branch == branch
+        for registration in registered_worktrees(runtime.context.project_root)
+    )
+
+
+def local_branch_exists(project_root: Path, branch: str) -> bool:
+    """Return whether an exact local branch ref exists."""
+    if not branch.strip():
+        return False
+    return run_git_command(
+        project_root,
+        ("show-ref", "--verify", "--quiet", f"refs/heads/{branch}"),
+    ).return_code == 0
+
+
+def create_branch_from_base(project_root: Path, branch: str, base_branch: str) -> GitCommandResult:
+    """Create a local branch from a validated base without checking it out."""
+    return run_git_command(project_root, ("branch", branch, base_branch))
 
 
 def mark_worktree_sentinel(runtime: WorktreeRuntimeContext) -> None:
@@ -555,13 +602,31 @@ def branch_merge_plan(context: BranchContext, *, auto_push: bool = False) -> Git
     )
 
 
-def branch_save_wip_plan(context: BranchContext) -> GitCommandPlan:
+def _literal_pathspecs(paths: Sequence[str]) -> tuple[str, ...]:
+    return tuple(f":(top,literal){path}" for path in paths)
+
+
+def _wip_pathspecs(paths: Sequence[str] | None) -> tuple[str, ...]:
+    return _literal_pathspecs(paths) if paths is not None else (".",)
+
+
+def branch_save_wip_plan(
+    context: BranchContext,
+    *,
+    commit_paths: Sequence[str] | None = None,
+    add_paths: Sequence[str] | None = None,
+) -> GitCommandPlan:
     """Plan WIP preservation that fails when task state cannot be committed."""
-    return GitCommandPlan(
-        name="branch_save_wip",
-        commands=(
-            _git("rev-parse", "--abbrev-ref", "HEAD", description="verify current branch"),
-            _git("add", "-A", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES, description="stage non-ignored work excluding hidden tool worktrees"),
+    commit_pathspecs = _wip_pathspecs(commit_paths)
+    add_pathspecs = _wip_pathspecs(add_paths if add_paths is not None else commit_paths)
+    commands = [
+        _git("rev-parse", "--abbrev-ref", "HEAD", description="verify current branch"),
+        _git("ls-files", "-u", description="require no unmerged paths before WIP commit"),
+    ]
+    if add_pathspecs:
+        commands.append(_git("add", "-A", "--", *add_pathspecs, description="stage Git-visible work"))
+    commands.extend(
+        (
             _git(
                 "commit",
                 "--no-verify",
@@ -571,26 +636,42 @@ def branch_save_wip_plan(context: BranchContext) -> GitCommandPlan:
                 "Pipeline was interrupted by signal. This commit preserves work-in-progress.",
                 "-m",
                 f"To resume: git checkout {context.working_branch}",
+                "--",
+                *commit_pathspecs,
                 description="create WIP commit",
             ),
             _git(
                 "status", "--porcelain", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES,
                 description="require clean task checkout after WIP commit",
             ),
-        ),
-        notes=("Task state stays on its branch; failed preservation is reported.",),
+        )
+    )
+    return GitCommandPlan(
+        name="branch_save_wip",
+        commands=tuple(commands),
+        notes=("Task state stays on its branch; ignored and runner-owned support paths are not explicit add operands.",),
     )
 
 
-def branch_ensure_return_plan(context: BranchContext) -> GitCommandPlan:
+def branch_ensure_return_plan(
+    context: BranchContext,
+    *,
+    commit_paths: Sequence[str] | None = None,
+    add_paths: Sequence[str] | None = None,
+) -> GitCommandPlan:
     """Plan a fail-closed WIP commit followed by a clean base return."""
-    return GitCommandPlan(
-        name="branch_ensure_return",
-        commands=(
-            _git("rebase", "--abort", allow_failure=True, description="abort in-progress rebase"),
-            _git("rev-parse", "--abbrev-ref", "HEAD", description="detect current branch"),
-            _git("status", "--porcelain", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES, description="detect WIP before checkout"),
-            _git("add", "-A", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES, description="stage WIP before checkout"),
+    commit_pathspecs = _wip_pathspecs(commit_paths)
+    add_pathspecs = _wip_pathspecs(add_paths if add_paths is not None else commit_paths)
+    commands = [
+        _git("rebase", "--abort", allow_failure=True, description="abort in-progress rebase"),
+        _git("rev-parse", "--abbrev-ref", "HEAD", description="detect current branch"),
+        _git("ls-files", "-u", description="require no unmerged paths before WIP commit"),
+        _git("status", "--porcelain", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES, description="detect WIP before checkout"),
+    ]
+    if add_pathspecs:
+        commands.append(_git("add", "-A", "--", *add_pathspecs, description="stage Git-visible WIP before checkout"))
+    commands.extend(
+        (
             _git(
                 "commit",
                 "--no-verify",
@@ -600,7 +681,8 @@ def branch_ensure_return_plan(context: BranchContext) -> GitCommandPlan:
                 "Pipeline was interrupted by signal. This commit preserves work-in-progress.",
                 "-m",
                 f"To resume: git checkout {context.working_branch}",
-                allow_failure=True,
+                "--",
+                *commit_pathspecs,
                 description="save WIP before return when on dev branch",
             ),
             _git(
@@ -608,8 +690,30 @@ def branch_ensure_return_plan(context: BranchContext) -> GitCommandPlan:
                 description="require clean task checkout before return",
             ),
             _git("checkout", context.base_branch, description="return to original branch"),
+        )
+    )
+    return GitCommandPlan(
+        name="branch_ensure_return",
+        commands=tuple(commands),
+        notes=("Return only after task state is committed and the checkout is clean; never merge or push.",),
+    )
+
+
+def _clean_branch_return_plan(context: BranchContext) -> GitCommandPlan:
+    """Plan a base return when the task checkout has no Git-visible WIP."""
+    return GitCommandPlan(
+        name="branch_ensure_return",
+        commands=(
+            _git("rebase", "--abort", allow_failure=True, description="abort in-progress rebase"),
+            _git("rev-parse", "--abbrev-ref", "HEAD", description="detect current branch"),
+            _git("ls-files", "-u", description="require no unmerged paths before base return"),
+            _git(
+                "status", "--porcelain", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES,
+                description="require clean task checkout before return",
+            ),
+            _git("checkout", context.base_branch, description="return to original branch"),
         ),
-        notes=("Return only after task state is committed and the checkout is clean.",),
+        notes=("A clean task checkout needs no WIP commit before returning to base.",),
     )
 
 
@@ -632,18 +736,86 @@ def current_branch(project_root: Path) -> str:
 
 
 def git_status_safe(project_root: Path) -> str:
-    """Return status while excluding hidden AI tool worktree directories."""
+    """Return task-visible status while excluding runner-owned support paths."""
     result = run_git_command(project_root, ("status", "--porcelain", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES))
     return result.stdout if result.return_code == 0 else ""
 
 
+def _status_record_paths(stdout: str) -> tuple[str, ...]:
+    records = stdout.split("\0")
+    changed: list[str] = []
+    index = 0
+    while index < len(records):
+        record = records[index]
+        index += 1
+        if not record or len(record) < 4 or record[2] != " ":
+            continue
+        status = record[:2]
+        changed.append(record[3:])
+        if "R" in status or "C" in status:
+            if index < len(records) and records[index]:
+                changed.append(records[index])
+                index += 1
+    return tuple(dict.fromkeys(path for path in changed if path))
+
+
+def visible_task_paths(project_root: Path) -> tuple[tuple[str, ...], GitCommandResult]:
+    result = run_git_command(
+        project_root,
+        ("status", "--porcelain=v1", "-z", "--untracked-files=all", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES),
+    )
+    return (_status_record_paths(result.stdout) if result.return_code == 0 else ()), result
+
+
+def addable_task_paths(project_root: Path, paths: Sequence[str]) -> tuple[tuple[str, ...], GitCommandResult]:
+    indexed = run_git_command(project_root, ("ls-files", "-z", "--", *_literal_pathspecs(paths)))
+    if indexed.return_code != 0:
+        return (), indexed
+    indexed_paths = set(indexed.stdout.split("\0"))
+    addable = tuple(
+        path
+        for path in paths
+        if path in indexed_paths or (project_root / path).exists() or (project_root / path).is_symlink()
+    )
+    return addable, indexed
+
+
+def _status_failure_plan(name: str, result: GitCommandResult, description: str) -> GitPlanResult:
+    plan = GitCommandPlan(name=name, commands=(_git(*result.args, description=description),))
+    return GitPlanResult(plan=plan, results=(result,))
+
+
 def branch_save_wip(project_root: Path, working_branch: str) -> GitPlanResult:
-    """Execute shell-compatible WIP save only when currently on working_branch."""
+    """Save task-visible WIP only when currently on the recorded working branch."""
     context = BranchContext(base_branch="", working_branch=working_branch, project_root=project_root)
-    plan = branch_save_wip_plan(context)
-    if not working_branch or current_branch(project_root) != working_branch or not git_status_safe(project_root).strip():
-        return GitPlanResult(plan=plan, results=())
-    return run_git_plan(project_root, plan)
+    default_plan = branch_save_wip_plan(context)
+    active = current_branch(project_root)
+    if not working_branch or not active:
+        return GitPlanResult(plan=default_plan, results=())
+    if active != working_branch:
+        mismatch_plan = GitCommandPlan(
+            name=default_plan.name,
+            commands=(_git("rev-parse", "--abbrev-ref", "HEAD", description="verify current task branch"),),
+        )
+        failure = GitCommandResult(
+            args=mismatch_plan.commands[0].args,
+            return_code=1,
+            stdout=active,
+            stderr=f"Active branch {active} does not match task branch {working_branch}",
+        )
+        return GitPlanResult(plan=mismatch_plan, results=(failure,))
+    paths, status = visible_task_paths(project_root)
+    if status.return_code != 0:
+        return _status_failure_plan(default_plan.name, status, "inspect task-visible WIP")
+    if not paths:
+        return GitPlanResult(plan=default_plan, results=())
+    add_paths, indexed = addable_task_paths(project_root, paths)
+    if indexed.return_code != 0:
+        return _status_failure_plan(default_plan.name, indexed, "resolve task-visible WIP paths")
+    return run_git_plan(
+        project_root,
+        branch_save_wip_plan(context, commit_paths=paths, add_paths=add_paths),
+    )
 
 
 def worktree_save_wip(runtime: WorktreeRuntimeContext) -> GitPlanResult:
@@ -652,7 +824,7 @@ def worktree_save_wip(runtime: WorktreeRuntimeContext) -> GitPlanResult:
 
 
 def branch_ensure_return(project_root: Path, base_branch: str, working_branch: str = "") -> GitPlanResult:
-    """Commit task WIP and return to base only from a clean checkout."""
+    """Commit Git-visible task WIP when needed, then return the caller checkout to base."""
     active = current_branch(project_root)
     context = BranchContext(base_branch=base_branch, working_branch=working_branch or active, project_root=project_root)
     if not active or active == base_branch:
@@ -670,7 +842,18 @@ def branch_ensure_return(project_root: Path, base_branch: str, working_branch: s
             stderr=f"Active branch {active} does not match task branch {working_branch}",
         )
         return GitPlanResult(plan=mismatch_plan, results=(failure,))
-    return run_git_plan(project_root, branch_ensure_return_plan(context))
+    paths, status = visible_task_paths(project_root)
+    if status.return_code != 0:
+        return _status_failure_plan("branch_ensure_return", status, "inspect task-visible WIP before base return")
+    if not paths:
+        return run_git_plan(project_root, _clean_branch_return_plan(context))
+    add_paths, indexed = addable_task_paths(project_root, paths)
+    if indexed.return_code != 0:
+        return _status_failure_plan("branch_ensure_return", indexed, "resolve task-visible WIP paths before base return")
+    return run_git_plan(
+        project_root,
+        branch_ensure_return_plan(context, commit_paths=paths, add_paths=add_paths),
+    )
 
 
 def _git_config_has_value(project_root: Path, key: str) -> bool:
@@ -737,6 +920,18 @@ def run_git_plan(project_root: Path, plan: GitCommandPlan) -> GitPlanResult:
     results: list[GitCommandResult] = []
     for command in plan.commands:
         result = run_git_command(project_root, command.args)
+        if (
+            command.args[:2] == ("ls-files", "-u")
+            and command.description.startswith("require no unmerged")
+            and result.return_code == 0
+            and result.stdout.strip()
+        ):
+            result = GitCommandResult(
+                args=result.args,
+                return_code=1,
+                stdout=result.stdout,
+                stderr="Task checkout contains unresolved Git paths",
+            )
         if (
             command.args[:2] == ("status", "--porcelain")
             and command.description.startswith("require clean")