prizmkit 1.1.191 → 1.1.193

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/bundled/VERSION.json +3 -3
  2. package/bundled/adapters/antigravity/skill-adapter.js +13 -4
  3. package/bundled/adapters/codex/skill-adapter.js +28 -8
  4. package/bundled/adapters/cursor/skill-adapter.js +13 -4
  5. package/bundled/adapters/pi/skill-adapter.js +28 -7
  6. package/bundled/dev-pipeline/.env.example +4 -12
  7. package/bundled/dev-pipeline/README.md +28 -44
  8. package/bundled/dev-pipeline/assets/feature-list-example.json +0 -1
  9. package/bundled/dev-pipeline/assets/skill-subagent-integration.md +6 -6
  10. package/bundled/dev-pipeline/prizmkit_runtime/atomic_io.py +48 -0
  11. package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +66 -23
  12. package/bundled/dev-pipeline/prizmkit_runtime/cli.py +10 -7
  13. package/bundled/dev-pipeline/prizmkit_runtime/commands.py +2 -21
  14. package/bundled/dev-pipeline/prizmkit_runtime/config.py +48 -78
  15. package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +127 -67
  16. package/bundled/dev-pipeline/prizmkit_runtime/gitops.py +158 -462
  17. package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py +102 -50
  18. package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -25
  19. package/bundled/dev-pipeline/prizmkit_runtime/paths.py +0 -6
  20. package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py +47 -21
  21. package/bundled/dev-pipeline/prizmkit_runtime/processes.py +217 -156
  22. package/bundled/dev-pipeline/prizmkit_runtime/reset.py +39 -27
  23. package/bundled/dev-pipeline/prizmkit_runtime/reset_preserve.py +34 -174
  24. package/bundled/dev-pipeline/prizmkit_runtime/results.py +25 -0
  25. package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +133 -110
  26. package/bundled/dev-pipeline/prizmkit_runtime/runner_classification.py +15 -5
  27. package/bundled/dev-pipeline/prizmkit_runtime/runner_models.py +1 -95
  28. package/bundled/dev-pipeline/prizmkit_runtime/runner_prompts.py +0 -2
  29. package/bundled/dev-pipeline/prizmkit_runtime/runner_status.py +7 -2
  30. package/bundled/dev-pipeline/prizmkit_runtime/runners.py +540 -262
  31. package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +175 -135
  32. package/bundled/dev-pipeline/prizmkit_runtime/runtime_helper.py +90 -9
  33. package/bundled/dev-pipeline/prizmkit_runtime/sessions.py +214 -133
  34. package/bundled/dev-pipeline/prizmkit_runtime/status.py +1 -3
  35. package/bundled/dev-pipeline/prizmkit_runtime/stream_progress.py +2783 -0
  36. package/bundled/dev-pipeline/prizmkit_runtime/task_checkout.py +27 -102
  37. package/bundled/dev-pipeline/prizmkit_runtime/test_result.py +58 -4
  38. package/bundled/dev-pipeline/scripts/check-session-status.py +56 -20
  39. package/bundled/dev-pipeline/scripts/continuation.py +8 -7
  40. package/bundled/dev-pipeline/scripts/detect-stuck.py +47 -33
  41. package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +13 -16
  42. package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +20 -10
  43. package/bundled/dev-pipeline/scripts/init-bugfix-pipeline.py +10 -7
  44. package/bundled/dev-pipeline/scripts/init-change-artifact.py +25 -4
  45. package/bundled/dev-pipeline/scripts/init-pipeline.py +14 -69
  46. package/bundled/dev-pipeline/scripts/parse-stream-progress.py +31 -2616
  47. package/bundled/dev-pipeline/scripts/patch-completion-notes.py +4 -24
  48. package/bundled/dev-pipeline/scripts/prompt_framework.py +85 -20
  49. package/bundled/dev-pipeline/scripts/status_common.py +591 -0
  50. package/bundled/dev-pipeline/scripts/update-bug-status.py +85 -463
  51. package/bundled/dev-pipeline/scripts/update-checkpoint.py +254 -65
  52. package/bundled/dev-pipeline/scripts/update-feature-status.py +76 -509
  53. package/bundled/dev-pipeline/scripts/utils.py +5 -12
  54. package/bundled/dev-pipeline/templates/bootstrap-tier3.md +5 -5
  55. package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +7 -0
  56. package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +7 -7
  57. package/bundled/dev-pipeline/templates/sections/artifact-manifest.md +1 -1
  58. package/bundled/dev-pipeline/templates/sections/bugfix-phase-manual-verification.md +1 -1
  59. package/bundled/dev-pipeline/templates/sections/bugfix-phase-review.md +1 -1
  60. package/bundled/dev-pipeline/templates/sections/bugfix-phase-test.md +2 -1
  61. package/bundled/dev-pipeline/templates/sections/checkpoint-system.md +1 -1
  62. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +1 -1
  63. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +2 -2
  64. package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md +2 -2
  65. package/bundled/dev-pipeline/templates/sections/phase-prizmkit-test.md +2 -1
  66. package/bundled/dev-pipeline/templates/sections/phase-review-full.md +1 -1
  67. package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md +3 -6
  68. package/bundled/dev-pipeline/templates/session-status-schema.json +2 -5
  69. package/bundled/skills/_metadata.json +9 -63
  70. package/bundled/skills/app-planner/SKILL.md +32 -303
  71. package/bundled/skills/app-planner/references/app-design-guide.md +0 -4
  72. package/bundled/skills/app-planner/references/generated-plan-review.md +2 -1
  73. package/bundled/skills/app-planner/references/project-brief-guide.md +14 -0
  74. package/bundled/skills/app-planner/references/project-conventions-discovery.md +4 -6
  75. package/bundled/skills/app-planner/references/project-state-detection.md +2 -3
  76. package/bundled/skills/bug-fix-workflow/SKILL.md +1 -2
  77. package/bundled/skills/bug-fix-workflow/references/bug-diagnosis.md +4 -7
  78. package/bundled/skills/bug-planner/SKILL.md +54 -435
  79. package/bundled/skills/bug-planner/references/generated-plan-review.md +3 -2
  80. package/bundled/skills/bug-planner/references/input-formats.md +32 -0
  81. package/bundled/skills/bugfix-pipeline-launcher/SKILL.md +4 -6
  82. package/bundled/skills/bugfix-pipeline-launcher/references/configuration.md +4 -28
  83. package/bundled/skills/feature-pipeline-launcher/SKILL.md +4 -6
  84. package/bundled/skills/feature-pipeline-launcher/references/configuration.md +4 -28
  85. package/bundled/skills/feature-planner/SKILL.md +60 -439
  86. package/bundled/skills/feature-planner/assets/planning-guide.md +1 -1
  87. package/bundled/skills/feature-planner/references/completeness-review.md +34 -0
  88. package/bundled/skills/feature-planner/references/decomposition-patterns.md +2 -2
  89. package/bundled/skills/feature-planner/references/error-recovery.md +1 -1
  90. package/bundled/skills/feature-planner/references/generated-plan-review.md +3 -2
  91. package/bundled/skills/feature-planner/references/incremental-feature-planning.md +3 -1
  92. package/bundled/skills/feature-workflow/SKILL.md +1 -2
  93. package/bundled/skills/prizmkit/SKILL.md +7 -1
  94. package/bundled/skills/prizmkit-code-review/SKILL.md +14 -6
  95. package/bundled/skills/prizmkit-code-review/references/independent-code-review.md +7 -4
  96. package/bundled/skills/prizmkit-code-review/references/review-report-template.md +16 -0
  97. package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py +58 -20
  98. package/bundled/skills/prizmkit-implement/SKILL.md +1 -1
  99. package/bundled/skills/prizmkit-init/SKILL.md +24 -127
  100. package/bundled/skills/prizmkit-init/assets/project-brief-template.md +3 -3
  101. package/bundled/skills/prizmkit-plan/SKILL.md +6 -8
  102. package/bundled/skills/prizmkit-plan/references/clarify-guide.md +1 -1
  103. package/bundled/skills/prizmkit-plan/references/independent-plan-review.md +5 -2
  104. package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md +6 -5
  105. package/bundled/skills/prizmkit-prizm-docs/SKILL.md +1 -13
  106. package/bundled/skills/prizmkit-prizm-docs/references/op-update.md +1 -1
  107. package/bundled/skills/prizmkit-retrospective/SKILL.md +6 -4
  108. package/bundled/skills/prizmkit-test/SKILL.md +25 -133
  109. package/bundled/skills/prizmkit-test/references/independent-test-review.md +5 -2
  110. package/bundled/skills/prizmkit-test/references/test-coverage-model.md +6 -0
  111. package/bundled/skills/prizmkit-workflow/SKILL.md +2 -3
  112. package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md +4 -3
  113. package/bundled/skills/recovery-workflow/SKILL.md +7 -7
  114. package/bundled/skills/recovery-workflow/evals/evals.json +1 -1
  115. package/bundled/skills/recovery-workflow/references/detection.md +1 -3
  116. package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py +0 -6
  117. package/bundled/templates/project-memory-template.md +1 -2
  118. package/package.json +1 -1
  119. package/src/scaffold.js +28 -7
  120. package/bundled/dev-pipeline/SCHEMA_ANALYSIS.md +0 -53
  121. package/bundled/dev-pipeline/scripts/generate-refactor-prompt.py +0 -649
  122. package/bundled/dev-pipeline/scripts/init-refactor-pipeline.py +0 -463
  123. package/bundled/dev-pipeline/scripts/update-refactor-status.py +0 -1512
  124. package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md +0 -240
  125. package/bundled/dev-pipeline/templates/refactor-list-schema.json +0 -266
  126. package/bundled/dev-pipeline/templates/sections/refactor-critical-paths.md +0 -15
  127. package/bundled/dev-pipeline/templates/sections/refactor-mission.md +0 -9
  128. package/bundled/dev-pipeline/templates/sections/refactor-phase-commit-report.md +0 -24
  129. package/bundled/dev-pipeline/templates/sections/refactor-phase-implement.md +0 -16
  130. package/bundled/dev-pipeline/templates/sections/refactor-phase-init.md +0 -9
  131. package/bundled/dev-pipeline/templates/sections/refactor-phase-plan.md +0 -22
  132. package/bundled/dev-pipeline/templates/sections/refactor-phase-review.md +0 -19
  133. package/bundled/dev-pipeline/templates/sections/refactor-phase-test.md +0 -24
  134. package/bundled/dev-pipeline/templates/sections/refactor-reminders.md +0 -12
  135. package/bundled/dev-pipeline/templates/sections/refactor-session-context.md +0 -6
  136. package/bundled/dev-pipeline/templates/sections/refactor-task-contract.md +0 -52
  137. package/bundled/dev-pipeline/tests/conftest.py +0 -29
  138. package/bundled/dev-pipeline/tests/live_ai_cli_log_smoke.py +0 -208
  139. package/bundled/dev-pipeline/tests/test_auto_skip.py +0 -1871
  140. package/bundled/dev-pipeline/tests/test_checkpoint_state.py +0 -1314
  141. package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +0 -1712
  142. package/bundled/dev-pipeline/tests/test_generate_bugfix_prompt.py +0 -627
  143. package/bundled/dev-pipeline/tests/test_generate_refactor_prompt.py +0 -478
  144. package/bundled/dev-pipeline/tests/test_python_runner_parity.py +0 -5641
  145. package/bundled/dev-pipeline/tests/test_recovery_workflow.py +0 -322
  146. package/bundled/dev-pipeline/tests/test_repository_bootstrap.py +0 -252
  147. package/bundled/dev-pipeline/tests/test_reset_modes.py +0 -1208
  148. package/bundled/dev-pipeline/tests/test_reset_preserve.py +0 -957
  149. package/bundled/dev-pipeline/tests/test_runtime_commit.py +0 -1113
  150. package/bundled/dev-pipeline/tests/test_runtime_helper.py +0 -303
  151. package/bundled/dev-pipeline/tests/test_unified_cli.py +0 -5504
  152. package/bundled/dev-pipeline/tests/test_utils.py +0 -170
  153. package/bundled/skills/feature-planner/assets/evaluation-guide.md +0 -44
  154. package/bundled/skills/refactor-pipeline-launcher/SKILL.md +0 -219
  155. package/bundled/skills/refactor-pipeline-launcher/references/configuration.md +0 -78
  156. package/bundled/skills/refactor-planner/SKILL.md +0 -467
  157. package/bundled/skills/refactor-planner/assets/planning-guide.md +0 -291
  158. package/bundled/skills/refactor-planner/references/behavior-preservation.md +0 -187
  159. package/bundled/skills/refactor-planner/references/error-recovery.md +0 -45
  160. package/bundled/skills/refactor-planner/references/fast-path.md +0 -59
  161. package/bundled/skills/refactor-planner/references/generated-plan-review.md +0 -107
  162. package/bundled/skills/refactor-planner/references/planning-phases.md +0 -172
  163. package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +0 -230
  164. package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +0 -1120
  165. package/bundled/skills/refactor-workflow/SKILL.md +0 -205
@@ -1,10 +1,9 @@
1
- """Branch and worktree helper primitives."""
1
+ """Branch helper primitives."""
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
5
  import os
6
6
  import re
7
- import shutil
8
7
  import subprocess
9
8
  from collections.abc import Sequence
10
9
  from dataclasses import dataclass
@@ -26,6 +25,8 @@ PIPELINE_METADATA_EXCLUDES = (
26
25
  ":(top,exclude).prizmkit/manifest.json",
27
26
  ":(top,exclude,glob).prizmkit/specs/**/workflow-checkpoint.json",
28
27
  ":(top,exclude,glob).prizmkit/specs/**/runtime-commit-request.json",
28
+ ":(top,exclude,glob).prizmkit/bugfix/**/workflow-checkpoint.json",
29
+ ":(top,exclude,glob).prizmkit/bugfix/**/runtime-commit-request.json",
29
30
  )
30
31
 
31
32
  HIDDEN_TOOL_WORKTREE_EXCLUDES = (
@@ -57,14 +58,11 @@ PIPELINE_FALLBACK_GIT_NAME = "PrizmKit Pipeline"
57
58
  PIPELINE_FALLBACK_GIT_EMAIL = "prizmkit-pipeline@example.invalid"
58
59
 
59
60
  WORKTREE_PLATFORM_SUPPORT_DIRS = (".claude", ".codebuddy", ".codex", ".agents", ".pi", ".cursor")
60
- WORKTREE_ROOT_SUPPORT_FILES = ("skills-lock.json", "AGENTS.md")
61
- WORKTREE_PRIZMKIT_SUPPORT_ENTRIES = ("prizm-docs", "config.json", "manifest.json")
62
- WORKTREE_SUPPORT_IGNORE_NAMES = {"__pycache__", ".DS_Store", "settings.local.json"}
63
61
 
64
62
 
65
63
  @dataclass(frozen=True)
66
64
  class BranchContext:
67
- """Branch state required by git/worktree helpers."""
65
+ """Branch state required by git branch helpers."""
68
66
 
69
67
  base_branch: str
70
68
  working_branch: str
@@ -72,69 +70,6 @@ class BranchContext:
72
70
  remote_name: str = "origin"
73
71
 
74
72
 
75
- @dataclass(frozen=True)
76
- class WorktreePolicy:
77
- """Worktree creation and cleanup policy for later porting."""
78
-
79
- use_worktree: bool
80
- cleanup_on_success: bool
81
- preserve_on_failure: bool
82
- worktree_root: Path | None = None
83
-
84
-
85
-
86
-
87
- @dataclass(frozen=True)
88
- class WorktreeRuntimeContext:
89
- """Resolved linked-worktree paths and safety metadata."""
90
-
91
- context: BranchContext
92
- policy: WorktreePolicy
93
- worktree_root: Path
94
- worktree_path: Path
95
- sentinel_path: Path
96
-
97
- def is_cleanup_path_safe(self) -> bool:
98
- root = self.worktree_root.resolve()
99
- target = self.worktree_path.resolve()
100
- try:
101
- return os.path.commonpath([str(root), str(target)]) == str(root) and target != root
102
- except ValueError:
103
- return False
104
-
105
-
106
-
107
-
108
- @dataclass(frozen=True)
109
- class WorktreeOperationResult:
110
- """Executable linked-worktree operation result."""
111
-
112
- ok: bool
113
- reason: str = ""
114
- runtime: WorktreeRuntimeContext | None = None
115
- results: tuple[GitCommandResult, ...] = ()
116
-
117
-
118
- @dataclass(frozen=True)
119
- class WorktreeRemovalResult:
120
- """Guarded worktree removal result."""
121
-
122
- ok: bool
123
- reason: str = ""
124
- results: tuple[GitCommandResult, ...] = ()
125
-
126
-
127
- @dataclass(frozen=True)
128
- class WorktreeSupportAssetsResult:
129
- """Support assets materialized into an AI-visible linked worktree."""
130
-
131
- ok: bool
132
- copied: tuple[Path, ...] = ()
133
- existing: tuple[Path, ...] = ()
134
- missing: tuple[str, ...] = ()
135
- reason: str = ""
136
-
137
-
138
73
  @dataclass(frozen=True)
139
74
  class RegisteredWorktree:
140
75
  """One path/branch pair reported by ``git worktree list --porcelain``."""
@@ -143,74 +78,6 @@ class RegisteredWorktree:
143
78
  branch: str = ""
144
79
 
145
80
 
146
- def _safe_worktree_name(branch_name: str) -> str:
147
- safe = re.sub(r"[^A-Za-z0-9._-]+", "-", branch_name.strip())
148
- safe = safe.strip(".-")
149
- return safe or "worktree"
150
-
151
-
152
- def worktree_runtime_context(context: BranchContext, policy: WorktreePolicy) -> WorktreeRuntimeContext:
153
- """Resolve deterministic per-branch worktree paths under a runner-owned root."""
154
- root = (policy.worktree_root or context.project_root / ".prizmkit" / "state" / "worktrees").resolve()
155
- worktree_path = root / _safe_worktree_name(context.working_branch)
156
- return WorktreeRuntimeContext(
157
- context=context,
158
- policy=policy,
159
- worktree_root=root,
160
- worktree_path=worktree_path,
161
- sentinel_path=worktree_path / ".prizmkit-worktree",
162
- )
163
-
164
-
165
- def linked_worktree_setup_plan(runtime: WorktreeRuntimeContext) -> GitCommandPlan:
166
- """Plan linked-worktree branch creation without main-worktree checkout."""
167
- context = runtime.context
168
- return GitCommandPlan(
169
- name="linked_worktree_setup",
170
- commands=(
171
- _git("rev-parse", "--verify", context.working_branch, allow_failure=True, description="check existing branch"),
172
- _git("branch", context.working_branch, context.base_branch, allow_failure=True, description="create branch without checkout"),
173
- _git("worktree", "list", "--porcelain", allow_failure=True, description="inspect registered worktrees"),
174
- _git("worktree", "add", "--checkout", str(runtime.worktree_path), context.working_branch, allow_failure=True, description="create or reuse linked worktree"),
175
- ),
176
- notes=(
177
- "Creates the task branch without checking it out in the main working tree.",
178
- "A deterministic path lets context-overflow continuations reuse the same worktree.",
179
- ),
180
- require_one_success=((0, 1),),
181
- )
182
-
183
-
184
- def worktree_merge_plan(runtime: WorktreeRuntimeContext, *, auto_push: bool = False) -> GitCommandPlan:
185
- """Plan rebase-in-worktree then fast-forward merge in the main repository."""
186
- context = runtime.context
187
- commands = [
188
- _git("rebase", context.base_branch, description="rebase worktree branch onto base"),
189
- _git("merge", "--ff-only", context.working_branch, description="fast-forward base from worktree branch"),
190
- ]
191
- if auto_push:
192
- commands.append(_git("push", allow_failure=True, description="optional auto-push after merge"))
193
- return GitCommandPlan(
194
- name="worktree_merge",
195
- commands=tuple(commands),
196
- notes=("Run rebase in the linked worktree and merge from the main checkout after checkout-free setup.",),
197
- )
198
-
199
-
200
- def worktree_remove_plan(runtime: WorktreeRuntimeContext, *, delete_branch: bool = True) -> GitCommandPlan:
201
- """Plan guarded linked-worktree removal and optional branch deletion."""
202
- commands = [
203
- _git("worktree", "remove", "--force", str(runtime.worktree_path), description="remove linked worktree"),
204
- ]
205
- if delete_branch:
206
- commands.append(_git("branch", "-d", runtime.context.working_branch, allow_failure=True, description="delete merged task branch"))
207
- return GitCommandPlan(
208
- name="worktree_remove",
209
- commands=tuple(commands),
210
- notes=("Caller must verify cleanup safety and registration before executing.",),
211
- )
212
-
213
-
214
81
  def registered_worktrees(project_root: Path) -> tuple[RegisteredWorktree, ...]:
215
82
  """Return registered worktree identities without changing repository state."""
216
83
  result = run_git_command(project_root, ("worktree", "list", "--porcelain"))
@@ -241,16 +108,6 @@ def registered_worktrees(project_root: Path) -> tuple[RegisteredWorktree, ...]:
241
108
  return tuple(registrations)
242
109
 
243
110
 
244
- def worktree_registered(runtime: WorktreeRuntimeContext) -> bool:
245
- """Return whether Git metadata contains the resolved path and task branch."""
246
- target = runtime.worktree_path.resolve()
247
- branch = runtime.context.working_branch
248
- return any(
249
- registration.path == target and registration.branch == branch
250
- for registration in registered_worktrees(runtime.context.project_root)
251
- )
252
-
253
-
254
111
  def local_branch_exists(project_root: Path, branch: str) -> bool:
255
112
  """Return whether an exact local branch ref exists."""
256
113
  if not branch.strip():
@@ -266,248 +123,6 @@ def create_branch_from_base(project_root: Path, branch: str, base_branch: str) -
266
123
  return run_git_command(project_root, ("branch", branch, base_branch))
267
124
 
268
125
 
269
- def mark_worktree_sentinel(runtime: WorktreeRuntimeContext) -> None:
270
- """Write a small runner-owned sentinel inside a linked worktree."""
271
- runtime.sentinel_path.parent.mkdir(parents=True, exist_ok=True)
272
- runtime.sentinel_path.write_text(runtime.context.working_branch + "\n", encoding="utf-8")
273
-
274
-
275
-
276
- def materialize_worktree_support_assets(runtime: WorktreeRuntimeContext) -> WorktreeSupportAssetsResult:
277
- """Copy ignored/untracked PrizmKit support assets into the linked worktree.
278
-
279
- Git worktree checkout materializes only tracked files. Platform agent
280
- definitions, Prizm docs/config, and installed runtime utility scripts are
281
- commonly ignored support assets, yet generated prompts reference them from
282
- the AI-visible project root. Copy only missing support files so continuation
283
- worktrees keep any task-local artifact changes.
284
- """
285
- source_root = runtime.context.project_root
286
- target_root = runtime.worktree_path
287
- copied: list[Path] = []
288
- existing: list[Path] = []
289
- missing: list[str] = []
290
-
291
- try:
292
- for relative in WORKTREE_PLATFORM_SUPPORT_DIRS:
293
- _materialize_optional_support_entry(source_root, target_root, relative, copied, existing, missing)
294
- for relative in WORKTREE_ROOT_SUPPORT_FILES:
295
- _materialize_optional_support_entry(source_root, target_root, relative, copied, existing, missing)
296
- for relative in WORKTREE_PRIZMKIT_SUPPORT_ENTRIES:
297
- _materialize_optional_support_entry(
298
- source_root / ".prizmkit",
299
- target_root / ".prizmkit",
300
- relative,
301
- copied,
302
- existing,
303
- missing,
304
- )
305
-
306
- runtime_scripts = _runtime_support_scripts_source(source_root)
307
- if runtime_scripts is None:
308
- missing.append(".prizmkit/dev-pipeline/scripts")
309
- else:
310
- target = target_root / ".prizmkit" / "dev-pipeline" / "scripts"
311
- changed = _copy_support_entry(runtime_scripts, target)
312
- (copied if changed else existing).append(target)
313
-
314
- runtime_package = _runtime_support_package_source(source_root)
315
- if runtime_package is None:
316
- missing.append(".prizmkit/dev-pipeline/prizmkit_runtime")
317
- else:
318
- target = target_root / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime"
319
- changed = _copy_support_entry(runtime_package, target)
320
- (copied if changed else existing).append(target)
321
- except OSError as exc:
322
- return WorktreeSupportAssetsResult(False, tuple(copied), tuple(existing), tuple(missing), str(exc))
323
-
324
- return WorktreeSupportAssetsResult(True, tuple(copied), tuple(existing), tuple(missing))
325
-
326
-
327
- def _materialize_optional_support_entry(
328
- source_root: Path,
329
- target_root: Path,
330
- relative: str,
331
- copied: list[Path],
332
- existing: list[Path],
333
- missing: list[str],
334
- ) -> None:
335
- source = source_root / relative
336
- target = target_root / relative
337
- if not source.exists() and not source.is_symlink():
338
- missing.append(relative)
339
- return
340
- changed = _copy_support_entry(source, target)
341
- (copied if changed else existing).append(target)
342
-
343
-
344
- def _runtime_support_scripts_source(project_root: Path) -> Path | None:
345
- candidates = (
346
- project_root / ".prizmkit" / "dev-pipeline" / "scripts",
347
- project_root / "dev-pipeline" / "scripts",
348
- )
349
- for candidate in candidates:
350
- if candidate.is_dir():
351
- return candidate
352
- return None
353
-
354
-
355
- def _runtime_support_package_source(project_root: Path) -> Path | None:
356
- candidates = (
357
- project_root / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime",
358
- project_root / "dev-pipeline" / "prizmkit_runtime",
359
- )
360
- for candidate in candidates:
361
- if candidate.is_dir():
362
- return candidate
363
- return None
364
-
365
-
366
- def _copy_support_entry(source: Path, target: Path) -> bool:
367
- if source.is_symlink():
368
- if target.exists() or target.is_symlink():
369
- return False
370
- target.parent.mkdir(parents=True, exist_ok=True)
371
- os.symlink(os.readlink(source), target)
372
- return True
373
- if source.is_file():
374
- if target.exists():
375
- return False
376
- target.parent.mkdir(parents=True, exist_ok=True)
377
- shutil.copy2(source, target)
378
- return True
379
-
380
- changed = False
381
- if not target.exists():
382
- target.mkdir(parents=True, exist_ok=True)
383
- changed = True
384
- for current_root, dir_names, file_names in os.walk(source):
385
- dir_names[:] = [name for name in dir_names if not _skip_support_asset_name(name)]
386
- relative_root = Path(current_root).relative_to(source)
387
- target_root = target / relative_root
388
- if not target_root.exists():
389
- target_root.mkdir(parents=True, exist_ok=True)
390
- changed = True
391
- for file_name in file_names:
392
- if _skip_support_asset_name(file_name):
393
- continue
394
- source_file = Path(current_root) / file_name
395
- target_file = target_root / file_name
396
- if target_file.exists() or target_file.is_symlink():
397
- continue
398
- if source_file.is_symlink():
399
- os.symlink(os.readlink(source_file), target_file)
400
- else:
401
- shutil.copy2(source_file, target_file)
402
- changed = True
403
- return changed
404
-
405
-
406
- def _skip_support_asset_name(name: str) -> bool:
407
- return name in WORKTREE_SUPPORT_IGNORE_NAMES or name.endswith(".pyc")
408
-
409
-
410
- def ensure_linked_worktree(runtime: WorktreeRuntimeContext) -> WorktreeOperationResult:
411
- """Create or reuse a linked worktree for the runtime context."""
412
- if not runtime.policy.use_worktree:
413
- return WorktreeOperationResult(False, "worktree_disabled", runtime)
414
- if not runtime.is_cleanup_path_safe():
415
- return WorktreeOperationResult(False, "unsafe_worktree_path", runtime)
416
-
417
- runtime.worktree_root.mkdir(parents=True, exist_ok=True)
418
- results: list[GitCommandResult] = []
419
-
420
- branch_check = run_git_command(runtime.context.project_root, ("rev-parse", "--verify", runtime.context.working_branch))
421
- results.append(branch_check)
422
- if branch_check.return_code != 0:
423
- branch_create = run_git_command(
424
- runtime.context.project_root,
425
- ("branch", runtime.context.working_branch, runtime.context.base_branch),
426
- )
427
- results.append(branch_create)
428
- if branch_create.return_code != 0:
429
- return WorktreeOperationResult(False, "branch_create_failed", runtime, tuple(results))
430
-
431
- if worktree_registered(runtime):
432
- mark_worktree_sentinel(runtime)
433
- return WorktreeOperationResult(True, runtime=runtime, results=tuple(results))
434
-
435
- if runtime.worktree_path.exists() and any(runtime.worktree_path.iterdir()):
436
- return WorktreeOperationResult(False, "worktree_path_exists_unregistered", runtime, tuple(results))
437
-
438
- add = run_git_command(
439
- runtime.context.project_root,
440
- ("worktree", "add", "--checkout", str(runtime.worktree_path), runtime.context.working_branch),
441
- )
442
- results.append(add)
443
- if add.return_code != 0:
444
- if worktree_registered(runtime):
445
- mark_worktree_sentinel(runtime)
446
- return WorktreeOperationResult(True, runtime=runtime, results=tuple(results))
447
- return WorktreeOperationResult(False, "worktree_add_failed", runtime, tuple(results))
448
-
449
- mark_worktree_sentinel(runtime)
450
- return WorktreeOperationResult(True, runtime=runtime, results=tuple(results))
451
-
452
-
453
- def merge_linked_worktree(runtime: WorktreeRuntimeContext, *, auto_push: bool = False) -> WorktreeOperationResult:
454
- """Fast-forward a committed linked-worktree branch, rebasing only when needed."""
455
- results: list[GitCommandResult] = []
456
- clean = run_git_command(
457
- runtime.worktree_path,
458
- ("status", "--porcelain", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES),
459
- )
460
- if clean.return_code == 0 and clean.stdout.strip():
461
- clean = GitCommandResult(
462
- args=clean.args,
463
- return_code=1,
464
- stdout=clean.stdout,
465
- stderr="Task worktree is not clean; committed branch state is required",
466
- )
467
- results.append(clean)
468
- if clean.return_code != 0:
469
- return WorktreeOperationResult(False, "dirty_task_checkout", runtime, tuple(results))
470
-
471
- if not branch_fast_forward_possible(runtime.context.project_root, runtime.context):
472
- rebase = run_git_command(runtime.worktree_path, ("rebase", runtime.context.base_branch))
473
- results.append(rebase)
474
- if rebase.return_code != 0:
475
- results.append(run_git_command(runtime.worktree_path, ("rebase", "--abort")))
476
- return WorktreeOperationResult(False, "merge_conflict", runtime, tuple(results))
477
-
478
- checkout = run_git_command(runtime.context.project_root, ("checkout", runtime.context.base_branch))
479
- results.append(checkout)
480
- if checkout.return_code != 0:
481
- return WorktreeOperationResult(False, "base_checkout_failed", runtime, tuple(results))
482
-
483
- merge = run_git_command(runtime.context.project_root, ("merge", "--ff-only", runtime.context.working_branch))
484
- results.append(merge)
485
- if merge.return_code != 0:
486
- results.append(run_git_command(runtime.context.project_root, ("merge", "--abort")))
487
- return WorktreeOperationResult(False, "merge_conflict", runtime, tuple(results))
488
-
489
- if auto_push:
490
- results.append(run_git_command(runtime.context.project_root, ("push",)))
491
-
492
- return WorktreeOperationResult(True, runtime=runtime, results=tuple(results))
493
-
494
- def guarded_worktree_remove(runtime: WorktreeRuntimeContext, *, delete_branch: bool = True) -> WorktreeRemovalResult:
495
- """Remove a worktree only when path, sentinel, and git metadata are safe."""
496
- if not runtime.is_cleanup_path_safe():
497
- return WorktreeRemovalResult(False, "unsafe_worktree_path")
498
- if not runtime.sentinel_path.is_file():
499
- return WorktreeRemovalResult(False, "missing_worktree_sentinel")
500
- if not worktree_registered(runtime):
501
- return WorktreeRemovalResult(False, "worktree_not_registered")
502
- results: list[GitCommandResult] = []
503
- for command in worktree_remove_plan(runtime, delete_branch=delete_branch).commands:
504
- result = run_git_command(runtime.context.project_root, command.args)
505
- results.append(result)
506
- if result.return_code != 0 and not command.allow_failure:
507
- return WorktreeRemovalResult(False, command.description or "worktree_remove_failed", tuple(results))
508
- return WorktreeRemovalResult(True, results=tuple(results))
509
-
510
-
511
126
  @dataclass(frozen=True)
512
127
  class GitCommand:
513
128
  """One planned git command."""
@@ -515,11 +130,13 @@ class GitCommand:
515
130
  args: tuple[str, ...]
516
131
  allow_failure: bool = False
517
132
  description: str = ""
133
+ fail_on_stdout: bool = False
134
+ fail_message: str = ""
518
135
 
519
136
 
520
137
  @dataclass(frozen=True)
521
138
  class GitCommandPlan:
522
- """A deterministic branch/worktree command plan."""
139
+ """A deterministic branch command plan."""
523
140
 
524
141
  name: str
525
142
  commands: tuple[GitCommand, ...]
@@ -580,8 +197,20 @@ class WipRestoreResult:
580
197
  return self.status == "restored"
581
198
 
582
199
 
583
- def _git(*args: str, allow_failure: bool = False, description: str = "") -> GitCommand:
584
- return GitCommand(args=args, allow_failure=allow_failure, description=description)
200
+ def _git(
201
+ *args: str,
202
+ allow_failure: bool = False,
203
+ description: str = "",
204
+ fail_on_stdout: bool = False,
205
+ fail_message: str = "",
206
+ ) -> GitCommand:
207
+ return GitCommand(
208
+ args=args,
209
+ allow_failure=allow_failure,
210
+ description=description,
211
+ fail_on_stdout=fail_on_stdout,
212
+ fail_message=fail_message,
213
+ )
585
214
 
586
215
 
587
216
  def branch_create_plan(context: BranchContext) -> GitCommandPlan:
@@ -598,18 +227,6 @@ def branch_create_plan(context: BranchContext) -> GitCommandPlan:
598
227
  )
599
228
 
600
229
 
601
- def branch_return_plan(context: BranchContext) -> GitCommandPlan:
602
- """Plan shell-equivalent branch_return intent."""
603
- return GitCommandPlan(
604
- name="branch_return",
605
- commands=(
606
- _git("rev-parse", "--abbrev-ref", "HEAD", description="detect current branch"),
607
- _git("checkout", context.base_branch, allow_failure=True, description="checkout original branch if needed"),
608
- ),
609
- notes=("Safe when already on the original branch.",),
610
- )
611
-
612
-
613
230
  def branch_fast_forward_possible(project_root: Path, context: BranchContext) -> bool:
614
231
  """Return whether the base branch is an ancestor of the committed task branch."""
615
232
  return run_git_command(
@@ -634,6 +251,8 @@ def branch_merge_plan(
634
251
  ".",
635
252
  *HIDDEN_TOOL_WORKTREE_EXCLUDES,
636
253
  description="require a clean task checkout",
254
+ fail_on_stdout=True,
255
+ fail_message="Task checkout is not clean; committed branch state is required",
637
256
  ),
638
257
  ]
639
258
  if rebase:
@@ -664,10 +283,14 @@ def branch_merge_plan(
664
283
  )
665
284
 
666
285
 
667
- def _literal_pathspecs(paths: Sequence[str]) -> tuple[str, ...]:
286
+ def literal_pathspecs(paths: Sequence[str]) -> tuple[str, ...]:
287
+ """Wrap repository-relative paths in literal top-anchored Git pathspecs."""
668
288
  return tuple(f":(top,literal){path}" for path in paths)
669
289
 
670
290
 
291
+ _literal_pathspecs = literal_pathspecs
292
+
293
+
671
294
  def _wip_pathspecs(paths: Sequence[str] | None) -> tuple[str, ...]:
672
295
  return _literal_pathspecs(paths) if paths is not None else (".",)
673
296
 
@@ -779,18 +402,6 @@ def _clean_branch_return_plan(context: BranchContext) -> GitCommandPlan:
779
402
  )
780
403
 
781
404
 
782
- def worktree_add_plan(context: BranchContext, policy: WorktreePolicy) -> GitCommandPlan:
783
- """Plan worktree creation without recreating retired Windows runtime sources."""
784
- root = policy.worktree_root or context.project_root.parent / f"{context.working_branch.replace('/', '-')}-worktree"
785
- return GitCommandPlan(
786
- name="worktree_add",
787
- commands=(
788
- _git("worktree", "add", str(root), context.working_branch, description="create git worktree"),
789
- ),
790
- notes=("Generic git worktree helper; no retired platform source trees are created.",),
791
- )
792
-
793
-
794
405
  def current_branch(project_root: Path) -> str:
795
406
  """Return current git branch name, or an empty string outside git.
796
407
 
@@ -843,7 +454,8 @@ def git_status_safe(project_root: Path) -> str:
843
454
  return result.stdout + tracked_support.stdout
844
455
 
845
456
 
846
- def _status_record_paths(stdout: str) -> tuple[str, ...]:
457
+ def parse_status_record_paths(stdout: str) -> tuple[str, ...]:
458
+ """Decode exact paths from NUL-delimited ``git status --porcelain=v1 -z`` output."""
847
459
  records = stdout.split("\0")
848
460
  changed: list[str] = []
849
461
  index = 0
@@ -861,6 +473,9 @@ def _status_record_paths(stdout: str) -> tuple[str, ...]:
861
473
  return tuple(dict.fromkeys(path for path in changed if path))
862
474
 
863
475
 
476
+ _status_record_paths = parse_status_record_paths
477
+
478
+
864
479
  def visible_task_paths(project_root: Path) -> tuple[tuple[str, ...], GitCommandResult]:
865
480
  result = run_git_command(
866
481
  project_root,
@@ -869,7 +484,7 @@ def visible_task_paths(project_root: Path) -> tuple[tuple[str, ...], GitCommandR
869
484
  if result.return_code != 0:
870
485
  return (), result
871
486
 
872
- # Platform payloads copied into a task worktree stay hidden, but existing
487
+ # Platform payloads copied into a task checkout stay hidden, but existing
873
488
  # tracked Cursor/Antigravity/Codex project configuration remains part of
874
489
  # complete-workspace commit semantics. `--untracked-files=no` admits only
875
490
  # Git-owned changes and cannot sweep materialized support files into a task commit.
@@ -934,11 +549,6 @@ def branch_save_wip(project_root: Path, working_branch: str) -> GitPlanResult:
934
549
  )
935
550
 
936
551
 
937
- def worktree_save_wip(runtime: WorktreeRuntimeContext) -> GitPlanResult:
938
- """Preserve dirty linked-worktree changes on the task branch before removal."""
939
- return branch_save_wip(runtime.worktree_path, runtime.context.working_branch)
940
-
941
-
942
552
  def _matches_runtime_wip_identity(
943
553
  subject: str,
944
554
  body: str,
@@ -1111,6 +721,25 @@ def restore_runtime_wip(
1111
721
  )
1112
722
 
1113
723
 
724
+ def _git_state_path_exists(project_root: Path, git_entry: str) -> bool:
725
+ result = run_git_command(project_root, ("rev-parse", "--git-path", git_entry))
726
+ if result.return_code != 0 or not result.stdout.strip():
727
+ return False
728
+ candidate = Path(result.stdout.strip())
729
+ resolved = candidate if candidate.is_absolute() else (project_root / candidate)
730
+ return resolved.exists()
731
+
732
+
733
+ def abort_in_progress_git_operation(project_root: Path) -> None:
734
+ """Best-effort abort of interrupted rebase, merge, or cherry-pick state."""
735
+ if _git_state_path_exists(project_root, "rebase-merge") or _git_state_path_exists(project_root, "rebase-apply"):
736
+ run_git_command(project_root, ("rebase", "--abort"))
737
+ if _git_state_path_exists(project_root, "MERGE_HEAD"):
738
+ run_git_command(project_root, ("merge", "--abort"))
739
+ if _git_state_path_exists(project_root, "CHERRY_PICK_HEAD"):
740
+ run_git_command(project_root, ("cherry-pick", "--abort"))
741
+
742
+
1114
743
  def branch_ensure_return(project_root: Path, base_branch: str, working_branch: str = "") -> GitPlanResult:
1115
744
  """Commit Git-visible task WIP when needed, then return the caller checkout to base."""
1116
745
  active = current_branch(project_root)
@@ -1150,6 +779,8 @@ def _git_config_has_value(project_root: Path, key: str) -> bool:
1150
779
  stdout=subprocess.PIPE,
1151
780
  stderr=subprocess.PIPE,
1152
781
  text=True,
782
+ encoding="utf-8",
783
+ errors="replace",
1153
784
  check=False,
1154
785
  )
1155
786
  return completed.returncode == 0 and bool(completed.stdout.strip())
@@ -1161,7 +792,8 @@ def _identity_value_available(project_root: Path, config_key: str, author_env: s
1161
792
  )
1162
793
 
1163
794
 
1164
- def _commit_identity_global_args(project_root: Path) -> tuple[str, ...]:
795
+ def commit_identity_global_args(project_root: Path) -> tuple[str, ...]:
796
+ """Return fallback ``git -c`` identity flags only when repository identity is unset."""
1165
797
  global_args: list[str] = []
1166
798
  if not _identity_value_available(project_root, "user.name", "GIT_AUTHOR_NAME", "GIT_COMMITTER_NAME"):
1167
799
  global_args.extend(("-c", f"user.name={PIPELINE_FALLBACK_GIT_NAME}"))
@@ -1170,7 +802,8 @@ def _commit_identity_global_args(project_root: Path) -> tuple[str, ...]:
1170
802
  return tuple(global_args)
1171
803
 
1172
804
 
1173
- def _commit_args_without_signing(args: tuple[str, ...]) -> tuple[str, ...]:
805
+ def commit_args_without_signing(args: tuple[str, ...]) -> tuple[str, ...]:
806
+ """Add ``--no-gpg-sign`` to pipeline ``git commit`` invocations unless explicitly signed."""
1174
807
  explicit_signing = any(
1175
808
  arg == "-S" or arg.startswith("-S") or arg == "--gpg-sign" or arg.startswith("--gpg-sign=")
1176
809
  for arg in args[1:]
@@ -1185,14 +818,17 @@ def run_git_command(project_root: Path, args: Sequence[str]) -> GitCommandResult
1185
818
  command_args = tuple(map(str, args))
1186
819
  global_args: tuple[str, ...] = ()
1187
820
  executable_args = command_args
821
+ if command_args and command_args[0] in {"commit", "rebase", "merge"}:
822
+ global_args = commit_identity_global_args(project_root)
1188
823
  if command_args and command_args[0] == "commit":
1189
- global_args = _commit_identity_global_args(project_root)
1190
- executable_args = _commit_args_without_signing(command_args)
824
+ executable_args = commit_args_without_signing(command_args)
1191
825
  completed = subprocess.run(
1192
826
  ["git", *global_args, "-C", str(project_root), *executable_args],
1193
827
  stdout=subprocess.PIPE,
1194
828
  stderr=subprocess.PIPE,
1195
829
  text=True,
830
+ encoding="utf-8",
831
+ errors="replace",
1196
832
  check=False,
1197
833
  )
1198
834
  return GitCommandResult(
@@ -1209,28 +845,24 @@ def run_git_plan(project_root: Path, plan: GitCommandPlan) -> GitPlanResult:
1209
845
  for command in plan.commands:
1210
846
  result = run_git_command(project_root, command.args)
1211
847
  if (
1212
- command.args[:2] == ("ls-files", "-u")
1213
- and command.description.startswith("require no unmerged")
1214
- and result.return_code == 0
848
+ result.return_code == 0
1215
849
  and result.stdout.strip()
1216
- ):
1217
- result = GitCommandResult(
1218
- args=result.args,
1219
- return_code=1,
1220
- stdout=result.stdout,
1221
- stderr="Task checkout contains unresolved Git paths",
850
+ and (
851
+ command.fail_on_stdout
852
+ or (command.args[:2] == ("ls-files", "-u") and command.description.startswith("require no unmerged"))
853
+ or (command.args[:2] == ("status", "--porcelain") and command.description.startswith("require clean"))
1222
854
  )
1223
- if (
1224
- command.args[:2] == ("status", "--porcelain")
1225
- and command.description.startswith("require clean")
1226
- and result.return_code == 0
1227
- and result.stdout.strip()
1228
855
  ):
856
+ stderr_message = command.fail_message or (
857
+ "Task checkout contains unresolved Git paths"
858
+ if command.args[:2] == ("ls-files", "-u")
859
+ else "Task checkout is not clean; committed branch state is required"
860
+ )
1229
861
  result = GitCommandResult(
1230
862
  args=result.args,
1231
863
  return_code=1,
1232
864
  stdout=result.stdout,
1233
- stderr="Task checkout is not clean; committed branch state is required",
865
+ stderr=stderr_message,
1234
866
  )
1235
867
  results.append(result)
1236
868
  if result.return_code != 0 and not (command.allow_failure or plan.never_fails):
@@ -1251,12 +883,26 @@ class ResetBranchCleanupResult:
1251
883
  warnings: tuple[str, ...] = ()
1252
884
 
1253
885
 
1254
- _TASK_BRANCH_PREFIXES = ("dev/", "bugfix/", "refactor/")
886
+ _TASK_BRANCH_PATTERN = re.compile(
887
+ r"^(?:prizmkit/|prizmkit-)?(?:dev/(?:feature/)?F-[0-9]+(?:-.*)?|bugfix/(?:bugfix/)?B-[0-9]+(?:-.*)?)$"
888
+ )
1255
889
 
1256
890
 
1257
891
  def _is_generated_task_branch(branch: str) -> bool:
1258
892
  """Return whether a branch name is a generated task branch."""
1259
- return any(branch.startswith(prefix) for prefix in _TASK_BRANCH_PREFIXES)
893
+ return bool(_TASK_BRANCH_PATTERN.fullmatch(branch))
894
+
895
+
896
+ def safe_task_branch_prefix(project_root: Path, base_prefix: str) -> str:
897
+ """Return a task branch prefix that avoids Git ref collisions with existing branches."""
898
+ prefix = base_prefix.strip().strip("/") or "dev"
899
+ if not local_branch_exists(project_root, prefix):
900
+ return prefix
901
+ if not local_branch_exists(project_root, "prizmkit") and not local_branch_exists(
902
+ project_root, f"prizmkit/{prefix}"
903
+ ):
904
+ return f"prizmkit/{prefix}"
905
+ return f"prizmkit-{prefix}"
1260
906
 
1261
907
 
1262
908
  def _origin_default_name(project_root: Path) -> str:
@@ -1357,16 +1003,22 @@ def reset_branch_pattern(prefix: str, item_id: str) -> str:
1357
1003
 
1358
1004
 
1359
1005
  def list_reset_branches(project_root: Path, prefix: str, item_id: str) -> tuple[str, ...]:
1360
- """List dev branches that shell reset helpers would clean for an item."""
1361
- result = run_git_command(project_root, ("branch", "--list", reset_branch_pattern(prefix, item_id)))
1362
- if result.return_code != 0:
1363
- return ()
1364
- branches = []
1365
- for line in result.stdout.splitlines():
1366
- branch = line.strip().lstrip("* ").strip()
1367
- if branch:
1368
- branches.append(branch)
1369
- return tuple(branches)
1006
+ """List dev branches that reset helpers would clean for an item."""
1007
+ patterns = (
1008
+ reset_branch_pattern(prefix, item_id),
1009
+ reset_branch_pattern(f"prizmkit/{prefix}", item_id),
1010
+ reset_branch_pattern(f"prizmkit-{prefix}", item_id),
1011
+ )
1012
+ branches: list[str] = []
1013
+ for pattern in patterns:
1014
+ result = run_git_command(project_root, ("branch", "--list", pattern))
1015
+ if result.return_code != 0:
1016
+ continue
1017
+ for line in result.stdout.splitlines():
1018
+ branch = line.strip().lstrip("* ").strip()
1019
+ if branch:
1020
+ branches.append(branch)
1021
+ return tuple(dict.fromkeys(branches))
1370
1022
 
1371
1023
 
1372
1024
  def reset_cleanup_branch(project_root: Path, branch: str, *, return_branch: str, delete: bool) -> ResetBranchCleanupResult:
@@ -1377,22 +1029,66 @@ def reset_cleanup_branch(project_root: Path, branch: str, *, return_branch: str,
1377
1029
  cleaned = False
1378
1030
 
1379
1031
  if active == branch:
1032
+ if not return_branch or not local_branch_exists(project_root, return_branch):
1033
+ warnings.append(
1034
+ f"cannot safely reset active branch {branch}: return branch {return_branch or '(empty)'} does not exist"
1035
+ )
1036
+ return ResetBranchCleanupResult(
1037
+ branch=branch,
1038
+ cleaned=False,
1039
+ deleted=False,
1040
+ returned_to=restored,
1041
+ checkout_discarded=False,
1042
+ branch_preserved=True,
1043
+ warnings=tuple(warnings),
1044
+ )
1380
1045
  run_git_command(project_root, ("reset", "HEAD"))
1381
1046
  run_git_command(project_root, ("checkout", "--", "."))
1382
- run_git_command(project_root, ("clean", "-fd"))
1047
+ run_git_command(
1048
+ project_root,
1049
+ (
1050
+ "clean",
1051
+ "-fd",
1052
+ "-e",
1053
+ ".prizmkit/",
1054
+ "-e",
1055
+ ".claude/",
1056
+ "-e",
1057
+ ".codebuddy/",
1058
+ "-e",
1059
+ ".codex/",
1060
+ "-e",
1061
+ ".agents/",
1062
+ "-e",
1063
+ ".cursor/",
1064
+ "-e",
1065
+ ".pi/",
1066
+ ),
1067
+ )
1383
1068
  checkout = run_git_command(project_root, ("checkout", return_branch))
1384
1069
  if checkout.return_code != 0:
1385
1070
  warnings.append(f"failed to checkout {return_branch}")
1386
1071
  restored = branch
1387
- else:
1388
- restored = return_branch
1389
- cleaned = True
1072
+ return ResetBranchCleanupResult(
1073
+ branch=branch,
1074
+ cleaned=False,
1075
+ deleted=False,
1076
+ returned_to=restored,
1077
+ checkout_discarded=False,
1078
+ branch_preserved=True,
1079
+ warnings=tuple(warnings),
1080
+ )
1081
+ restored = return_branch
1082
+ cleaned = True
1390
1083
 
1391
1084
  deleted = False
1392
1085
  if delete:
1393
- deleted = run_git_command(project_root, ("branch", "-D", branch)).return_code == 0
1394
- if not deleted:
1395
- warnings.append(f"failed to delete branch {branch}")
1086
+ if not local_branch_exists(project_root, branch):
1087
+ cleaned = True
1088
+ else:
1089
+ deleted = run_git_command(project_root, ("branch", "-D", branch)).return_code == 0
1090
+ if not deleted:
1091
+ warnings.append(f"failed to delete branch {branch}")
1396
1092
  elif active != branch:
1397
1093
  cleaned = True
1398
1094