prizmkit 1.1.184 → 1.1.187

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.
@@ -1,5 +1,5 @@
1
1
  {
2
- "frameworkVersion": "1.1.184",
3
- "bundledAt": "2026-09-18T15:58:59.797Z",
4
- "bundledFrom": "72909d7"
2
+ "frameworkVersion": "1.1.187",
3
+ "bundledAt": "2026-10-20T15:24:46.460Z",
4
+ "bundledFrom": "f09590f"
5
5
  }
@@ -792,9 +792,41 @@ def worktree_add_plan(context: BranchContext, policy: WorktreePolicy) -> GitComm
792
792
 
793
793
 
794
794
  def current_branch(project_root: Path) -> str:
795
- """Return current git branch name, or an empty string outside git."""
795
+ """Return current git branch name, or an empty string outside git.
796
+
797
+ An unborn branch has no HEAD commit, so ``rev-parse --abbrev-ref HEAD``
798
+ fails. ``symbolic-ref`` still reports the branch Git will use for the
799
+ first commit.
800
+ """
796
801
  result = run_git_command(project_root, ("rev-parse", "--abbrev-ref", "HEAD"))
797
- return result.stdout.strip() if result.return_code == 0 else ""
802
+ if result.return_code == 0:
803
+ return result.stdout.strip()
804
+ symbolic = run_git_command(project_root, ("symbolic-ref", "--short", "HEAD"))
805
+ if symbolic.return_code == 0:
806
+ return symbolic.stdout.strip()
807
+ return ""
808
+
809
+
810
+ def ensure_git_repository(project_root: Path) -> GitCommandResult:
811
+ """Create a repository when the project root is not already inside one."""
812
+ probe = run_git_command(project_root, ("rev-parse", "--is-inside-work-tree"))
813
+ if probe.return_code == 0 and probe.stdout.strip() == "true":
814
+ return probe
815
+ return run_git_command(project_root, ("init",))
816
+
817
+
818
+ def ensure_branch_has_commit(project_root: Path) -> GitCommandResult:
819
+ """Give the current branch a commit when it is still unborn.
820
+
821
+ Task branches cannot be created from a branch name that has no commit.
822
+ """
823
+ head = run_git_command(project_root, ("rev-parse", "--verify", "HEAD"))
824
+ if head.return_code == 0:
825
+ return head
826
+ return run_git_command(
827
+ project_root,
828
+ ("commit", "--allow-empty", "--no-verify", "-m", "chore: initialize repository"),
829
+ )
798
830
 
799
831
 
800
832
  def git_status_safe(project_root: Path) -> str:
@@ -1219,16 +1251,104 @@ class ResetBranchCleanupResult:
1219
1251
  warnings: tuple[str, ...] = ()
1220
1252
 
1221
1253
 
1222
- def default_branch(project_root: Path) -> str:
1223
- """Resolve the same main/master/default-branch fallback used by reset scripts."""
1254
+ _TASK_BRANCH_PREFIXES = ("dev/", "bugfix/", "refactor/")
1255
+
1256
+
1257
+ def _is_generated_task_branch(branch: str) -> bool:
1258
+ """Return whether a branch name is a generated task branch."""
1259
+ return any(branch.startswith(prefix) for prefix in _TASK_BRANCH_PREFIXES)
1260
+
1261
+
1262
+ def _origin_default_name(project_root: Path) -> str:
1224
1263
  origin = run_git_command(project_root, ("symbolic-ref", "refs/remotes/origin/HEAD"))
1225
- if origin.return_code == 0 and origin.stdout.strip():
1226
- return origin.stdout.strip().removeprefix("refs/remotes/origin/")
1227
- if run_git_command(project_root, ("rev-parse", "--verify", "main")).return_code == 0:
1228
- return "main"
1229
- if run_git_command(project_root, ("rev-parse", "--verify", "master")).return_code == 0:
1230
- return "master"
1231
- return current_branch(project_root) or "main"
1264
+ if origin.return_code != 0:
1265
+ return ""
1266
+ return origin.stdout.strip().removeprefix("refs/remotes/origin/")
1267
+
1268
+
1269
+ def _local_branch_names(project_root: Path) -> tuple[str, ...]:
1270
+ result = run_git_command(project_root, ("for-each-ref", "--format=%(refname:short)", "refs/heads"))
1271
+ if result.return_code != 0:
1272
+ return ()
1273
+ return tuple(line.strip() for line in result.stdout.splitlines() if line.strip())
1274
+
1275
+
1276
+ def _previous_branch(project_root: Path) -> str:
1277
+ """Return the latest checked-out branch that is not a generated task branch."""
1278
+ for offset in range(1, 9):
1279
+ revision = f"@{{-{offset}}}"
1280
+ result = run_git_command(project_root, ("rev-parse", "--abbrev-ref", revision))
1281
+ if result.return_code != 0:
1282
+ return ""
1283
+ name = result.stdout.strip()
1284
+ if not name or name in {"HEAD", revision} or _is_generated_task_branch(name):
1285
+ continue
1286
+ if local_branch_exists(project_root, name):
1287
+ return name
1288
+ return ""
1289
+
1290
+
1291
+ def _closest_primary_branch(project_root: Path, branches: tuple[str, ...]) -> str:
1292
+ """Return the non-task branch a task checkout most recently came from."""
1293
+ ancestors: list[str] = []
1294
+ for branch in branches:
1295
+ if run_git_command(project_root, ("merge-base", "--is-ancestor", branch, "HEAD")).return_code == 0:
1296
+ ancestors.append(branch)
1297
+ if len(ancestors) == 1:
1298
+ return ancestors[0]
1299
+ closest: list[str] = []
1300
+ for candidate in ancestors:
1301
+ behind_another = False
1302
+ for other in ancestors:
1303
+ if other == candidate:
1304
+ continue
1305
+ candidate_contains_other = run_git_command(
1306
+ project_root,
1307
+ ("merge-base", "--is-ancestor", other, candidate),
1308
+ ).return_code == 0
1309
+ other_contains_candidate = run_git_command(
1310
+ project_root,
1311
+ ("merge-base", "--is-ancestor", candidate, other),
1312
+ ).return_code == 0
1313
+ if other_contains_candidate and not candidate_contains_other:
1314
+ behind_another = True
1315
+ break
1316
+ if not behind_another:
1317
+ closest.append(candidate)
1318
+ if len(closest) == 1:
1319
+ return closest[0]
1320
+ return ""
1321
+
1322
+
1323
+ def default_branch(project_root: Path) -> str:
1324
+ """Return the branch a task should leave and later restore.
1325
+
1326
+ The name is whatever this repository uses. A generated task branch is not
1327
+ a primary branch, and a missing name is never replaced with ``main``.
1328
+ """
1329
+ current = current_branch(project_root)
1330
+ if current and current != "HEAD" and not _is_generated_task_branch(current):
1331
+ return current
1332
+
1333
+ previous = _previous_branch(project_root)
1334
+ if (
1335
+ previous
1336
+ and not _is_generated_task_branch(previous)
1337
+ and local_branch_exists(project_root, previous)
1338
+ ):
1339
+ return previous
1340
+
1341
+ primaries = tuple(branch for branch in _local_branch_names(project_root) if not _is_generated_task_branch(branch))
1342
+ if len(primaries) == 1:
1343
+ return primaries[0]
1344
+ closest = _closest_primary_branch(project_root, primaries)
1345
+ if closest:
1346
+ return closest
1347
+
1348
+ origin = _origin_default_name(project_root)
1349
+ if origin and not _is_generated_task_branch(origin):
1350
+ return origin
1351
+ return ""
1232
1352
 
1233
1353
 
1234
1354
  def reset_branch_pattern(prefix: str, item_id: str) -> str:
@@ -25,7 +25,10 @@ from .gitops import (
25
25
  branch_save_wip,
26
26
  current_branch,
27
27
  default_branch,
28
+ ensure_branch_has_commit,
29
+ ensure_git_repository,
28
30
  ensure_linked_worktree,
31
+ local_branch_exists,
29
32
  guarded_worktree_remove,
30
33
  materialize_worktree_support_assets,
31
34
  merge_linked_worktree,
@@ -68,6 +71,7 @@ from .task_checkout import (
68
71
  TaskCheckout,
69
72
  complete_task_checkout_locked,
70
73
  load_task_checkout,
74
+ replace_missing_recorded_base_locked,
71
75
  reserve_task_checkout_locked,
72
76
  task_checkout_guard,
73
77
  )
@@ -348,7 +352,7 @@ def _latest_session_status(state_dir: Path, item_id: str) -> dict[str, object]:
348
352
 
349
353
  def _resolve_base_branch(project_root: Path, metadata: dict[str, object], active_branch: str, family: RunnerFamily, item_id: str) -> str:
350
354
  recorded = str(metadata.get("base_branch") or "").strip()
351
- if recorded:
355
+ if recorded and local_branch_exists(project_root, recorded):
352
356
  return recorded
353
357
  detected_default = default_branch(project_root)
354
358
  if _is_current_task_branch(active_branch, family, item_id) or _is_recovery_side_effect_branch(active_branch, family, item_id):
@@ -557,6 +561,14 @@ def _process_item_locked(
557
561
  if config.ai_client.platform == "cursor" and not config.effort_validation.valid:
558
562
  raise RuntimeError(config.effort_validation.message)
559
563
 
564
+ repository = ensure_git_repository(paths.project_root)
565
+ if repository.return_code != 0:
566
+ detail = (repository.stderr or repository.stdout).strip()
567
+ first = detail.splitlines()[0] if detail else "git init failed"
568
+ raise RuntimeError(f"Cannot initialize Git repository before {family.kind} task {item_id}: {first}")
569
+ if repository.args and repository.args[0] == "init":
570
+ _emit_info(f"Git: initialized repository before {family.kind} task {item_id}")
571
+
560
572
  active_branch = current_branch(paths.project_root)
561
573
  checkout = load_task_checkout(family.state_dir, family.task_type, item_id)
562
574
  if checkout is not None and checkout.is_completed:
@@ -594,6 +606,29 @@ def _process_item_locked(
594
606
  else:
595
607
  _emit_info(f"Preflight: no user-visible changes to preserve before {family.kind} task {item_id}")
596
608
 
609
+ born = ensure_branch_has_commit(paths.project_root)
610
+ if born.return_code != 0:
611
+ detail = (born.stderr or born.stdout).strip()
612
+ first = detail.splitlines()[0] if detail else "initial commit failed"
613
+ raise RuntimeError(f"Cannot create the initial commit before {family.kind} task {item_id}: {first}")
614
+ if born.args and born.args[0] == "commit":
615
+ _emit_info(f"Git: created initial commit before {family.kind} task {item_id}")
616
+ active_branch = current_branch(paths.project_root)
617
+ if not local_branch_exists(paths.project_root, base_branch):
618
+ base_branch = _resolve_base_branch(paths.project_root, metadata, active_branch, family, item_id)
619
+ branch_context = BranchContext(base_branch, branch_name, paths.project_root)
620
+
621
+ if (
622
+ checkout is not None
623
+ and checkout.is_active
624
+ and checkout.base_branch != base_branch
625
+ and not local_branch_exists(paths.project_root, checkout.base_branch)
626
+ and local_branch_exists(paths.project_root, base_branch)
627
+ ):
628
+ previous_base = checkout.base_branch
629
+ checkout = replace_missing_recorded_base_locked(family.state_dir, checkout, base_branch)
630
+ _emit_info(f"Checkout: recorded base {previous_base} is missing; using {base_branch}")
631
+
597
632
  if use_worktree:
598
633
  worktree_runtime = worktree_runtime_context(
599
634
  branch_context,
@@ -248,6 +248,29 @@ def reserve_task_checkout_locked(state_dir: Path | str, candidate: TaskCheckout)
248
248
  return candidate
249
249
 
250
250
 
251
+ def replace_missing_recorded_base_locked(
252
+ state_dir: Path | str,
253
+ existing: TaskCheckout,
254
+ base_branch: str,
255
+ ) -> TaskCheckout:
256
+ """Record a resolved base when the stored base ref was never created."""
257
+ if not existing.is_active:
258
+ raise TaskCheckoutError("Only an active checkout can replace a missing base branch")
259
+ replacement = TaskCheckout.active(
260
+ existing.task_type,
261
+ existing.task_id,
262
+ existing.active_dev_branch,
263
+ base_branch,
264
+ checkout_mode=existing.checkout_mode,
265
+ worktree_path=existing.worktree_path,
266
+ )
267
+ current = load_task_checkout(state_dir, existing.task_type, existing.task_id)
268
+ if current != existing:
269
+ raise TaskCheckoutError(f"Task {existing.task_id} checkout changed before base correction")
270
+ persist_task_checkout(state_dir, replacement)
271
+ return replacement
272
+
273
+
251
274
  def reserve_task_checkout(state_dir: Path | str, candidate: TaskCheckout) -> TaskCheckout:
252
275
  """Reserve a checkout with first-writer-wins synchronization."""
253
276
  with task_checkout_guard(state_dir, candidate.task_id):
@@ -2663,6 +2663,7 @@ def test_no_worktree_exhausted_failure_stays_on_task_branch_without_merge_for_al
2663
2663
  events.append(plan.name)
2664
2664
  return SimpleNamespace(ok=True, plan=plan, results=())
2665
2665
 
2666
+ monkeypatch.setattr(runners, "current_branch", lambda _root: "release")
2666
2667
  monkeypatch.setattr(runners, "run_git_plan", fake_run_git_plan)
2667
2668
  monkeypatch.setattr(runners, "branch_ensure_return", lambda project_root, base, task_branch: events.append(("return", base, task_branch)))
2668
2669
  monkeypatch.setattr(runners, "commit_final_bookkeeping", lambda project_root, family, item_id, status: final_commits.append((project_root, item_id, status)))
@@ -2673,7 +2674,7 @@ def test_no_worktree_exhausted_failure_stays_on_task_branch_without_merge_for_al
2673
2674
  assert status == "failed"
2674
2675
  assert events[0] == "branch_create"
2675
2676
  assert "branch_merge" not in events
2676
- assert events[-1] == ("return", "main", branch)
2677
+ assert events[-1] == ("return", "release", branch)
2677
2678
  assert final_commits == [(paths.project_root, item_id, "failed")]
2678
2679
  assert wip_commits == [(paths.project_root, item_id, "failed")]
2679
2680
 
@@ -2684,11 +2685,22 @@ def test_no_worktree_runner_ignores_recovery_side_effect_branch(monkeypatch, tmp
2684
2685
 
2685
2686
  monkeypatch.delenv("DEV_BRANCH", raising=False)
2686
2687
  paths = _make_paths(tmp_path)
2688
+ subprocess.run(["git", "init", "-b", "trunk"], cwd=paths.project_root, check=True, stdout=subprocess.DEVNULL)
2689
+ subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=paths.project_root, check=True)
2690
+ subprocess.run(["git", "config", "user.name", "Test"], cwd=paths.project_root, check=True)
2691
+ subprocess.run(
2692
+ ["git", "commit", "--allow-empty", "-m", "base"],
2693
+ cwd=paths.project_root,
2694
+ check=True,
2695
+ stdout=subprocess.DEVNULL,
2696
+ )
2697
+ subprocess.run(["git", "branch", "main"], cwd=paths.project_root, check=True)
2687
2698
  family = family_for("feature", paths)
2688
2699
  invocation = parse_invocation(family, "run", ())
2689
2700
  invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
2690
2701
  observed = _install_runner_session_fakes(monkeypatch, runners)
2691
2702
  branch_names = []
2703
+ bases = []
2692
2704
 
2693
2705
  monkeypatch.setenv("DEV_BRANCH", "dev/F-001-recovery-20260707")
2694
2706
  monkeypatch.setattr(runners, "current_branch", lambda _root: "dev/F-001-recovery-20260707")
@@ -2696,6 +2708,7 @@ def test_no_worktree_runner_ignores_recovery_side_effect_branch(monkeypatch, tmp
2696
2708
  def fake_run_git_plan(project_root, plan):
2697
2709
  if plan.name == "branch_create":
2698
2710
  branch_names.append(plan.commands[1].args[2])
2711
+ bases.append(plan.commands[1].args[3])
2699
2712
  return SimpleNamespace(ok=True, plan=plan, results=())
2700
2713
 
2701
2714
  monkeypatch.setattr(runners, "run_git_plan", fake_run_git_plan)
@@ -2705,8 +2718,9 @@ def test_no_worktree_runner_ignores_recovery_side_effect_branch(monkeypatch, tmp
2705
2718
  assert status == "completed"
2706
2719
  assert branch_names and branch_names[0].startswith("dev/F-001-")
2707
2720
  assert "recovery" not in branch_names[0]
2721
+ assert bases == ["trunk"]
2708
2722
  assert observed.updates[-1][2]["active_dev_branch"] == branch_names[0]
2709
- assert observed.updates[-1][2]["base_branch"] == "main"
2723
+ assert observed.updates[-1][2]["base_branch"] == "trunk"
2710
2724
 
2711
2725
 
2712
2726
  @pytest.mark.parametrize(
@@ -0,0 +1,252 @@
1
+ """Git bootstrap for projects that have no repository or no commits yet."""
2
+
3
+ import json
4
+ import subprocess
5
+ from pathlib import Path
6
+
7
+ import pytest
8
+
9
+ PIPELINE_ROOT = Path(__file__).resolve().parents[1]
10
+
11
+
12
+ def _git(project, *args, check=True):
13
+ return subprocess.run(
14
+ ["git", "-C", str(project), *args],
15
+ check=check,
16
+ stdout=subprocess.PIPE,
17
+ stderr=subprocess.PIPE,
18
+ text=True,
19
+ )
20
+
21
+
22
+ def _init_unborn(project, branch):
23
+ project.mkdir(parents=True, exist_ok=True)
24
+ _git(project, "init", "-b", branch)
25
+
26
+
27
+ def _identity(project):
28
+ _git(project, "config", "user.email", "test@example.com")
29
+ _git(project, "config", "user.name", "Test")
30
+
31
+
32
+ def test_current_branch_reads_unborn_branch_name(tmp_path):
33
+ from prizmkit_runtime.gitops import current_branch, default_branch
34
+
35
+ project = tmp_path / "unborn"
36
+ _init_unborn(project, "master")
37
+
38
+ assert current_branch(project) == "master"
39
+ assert default_branch(project) == "master"
40
+
41
+
42
+ def test_current_branch_is_empty_outside_a_repository(tmp_path):
43
+ from prizmkit_runtime.gitops import current_branch
44
+
45
+ assert current_branch(tmp_path) == ""
46
+
47
+
48
+ def test_default_branch_uses_the_checked_out_branch_when_main_also_exists(tmp_path):
49
+ from prizmkit_runtime.gitops import default_branch
50
+
51
+ project = tmp_path / "develop-repo"
52
+ _init_unborn(project, "develop")
53
+ _identity(project)
54
+ _git(project, "commit", "--allow-empty", "-m", "init")
55
+ _git(project, "branch", "main")
56
+
57
+ assert default_branch(project) == "develop"
58
+
59
+
60
+ def test_task_branch_resolves_back_to_the_primary_it_left(tmp_path):
61
+ from prizmkit_runtime.gitops import (
62
+ BranchContext,
63
+ branch_create_plan,
64
+ branch_ensure_return,
65
+ current_branch,
66
+ default_branch,
67
+ run_git_plan,
68
+ )
69
+
70
+ project = tmp_path / "trunk-repo"
71
+ _init_unborn(project, "trunk")
72
+ _identity(project)
73
+ _git(project, "commit", "--allow-empty", "-m", "init")
74
+ _git(project, "branch", "main")
75
+ created = run_git_plan(project, branch_create_plan(BranchContext("trunk", "dev/F-001-custom", project)))
76
+ assert created.ok
77
+ assert current_branch(project) == "dev/F-001-custom"
78
+ assert default_branch(project) == "trunk"
79
+
80
+ returned = branch_ensure_return(project, "trunk", "dev/F-001-custom")
81
+ assert returned.ok
82
+ assert current_branch(project) == "trunk"
83
+
84
+
85
+ def test_default_branch_prefers_an_existing_main_or_master_commit(tmp_path):
86
+ from prizmkit_runtime.gitops import default_branch
87
+
88
+ main_repo = tmp_path / "main-repo"
89
+ _init_unborn(main_repo, "main")
90
+ _identity(main_repo)
91
+ (main_repo / "README").write_text("main\n", encoding="utf-8")
92
+ _git(main_repo, "add", "README")
93
+ _git(main_repo, "commit", "-m", "init")
94
+ assert default_branch(main_repo) == "main"
95
+
96
+ master_repo = tmp_path / "master-repo"
97
+ _init_unborn(master_repo, "master")
98
+ _identity(master_repo)
99
+ (master_repo / "README").write_text("master\n", encoding="utf-8")
100
+ _git(master_repo, "add", "README")
101
+ _git(master_repo, "commit", "-m", "init")
102
+ assert default_branch(master_repo) == "master"
103
+
104
+
105
+ def test_missing_repository_can_create_a_task_branch_after_preflight(tmp_path):
106
+ from prizmkit_runtime.gitops import (
107
+ BranchContext,
108
+ branch_create_plan,
109
+ current_branch,
110
+ default_branch,
111
+ ensure_branch_has_commit,
112
+ ensure_git_repository,
113
+ local_branch_exists,
114
+ run_git_plan,
115
+ )
116
+ from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
117
+
118
+ project = tmp_path / "fresh"
119
+ project.mkdir()
120
+ (project / "README").write_text("framework\n", encoding="utf-8")
121
+
122
+ created = ensure_git_repository(project)
123
+ assert created.return_code == 0
124
+ assert created.args[0] == "init"
125
+ again = ensure_git_repository(project)
126
+ assert again.args[0] == "rev-parse"
127
+
128
+ base = current_branch(project)
129
+ assert base
130
+ assert base != "HEAD"
131
+ assert default_branch(project) == base
132
+
133
+ preflight = commit_preflight_ready_changes(project, "F-001")
134
+ assert preflight.committed
135
+ assert ensure_branch_has_commit(project).args[0] == "rev-parse"
136
+ assert local_branch_exists(project, base)
137
+ assert not local_branch_exists(project, "this-branch-does-not-exist")
138
+
139
+ plan = run_git_plan(project, branch_create_plan(BranchContext(base, "dev/F-001-fresh", project)))
140
+ assert plan.ok
141
+ assert local_branch_exists(project, "dev/F-001-fresh")
142
+ assert _git(project, "merge-base", "--is-ancestor", base, "dev/F-001-fresh").returncode == 0
143
+
144
+
145
+ def test_unborn_master_preflight_branches_from_master_not_main(tmp_path):
146
+ from prizmkit_runtime.gitops import (
147
+ BranchContext,
148
+ branch_create_plan,
149
+ current_branch,
150
+ default_branch,
151
+ local_branch_exists,
152
+ run_git_plan,
153
+ )
154
+ from prizmkit_runtime.runner_bookkeeping import commit_preflight_ready_changes
155
+
156
+ project = tmp_path / "master-only"
157
+ _init_unborn(project, "master")
158
+ _identity(project)
159
+ (project / ".gitignore").write_text(".prizmkit/*\n", encoding="utf-8")
160
+
161
+ assert current_branch(project) == "master"
162
+ assert default_branch(project) == "master"
163
+ preflight = commit_preflight_ready_changes(project, "F-001")
164
+ assert preflight.committed
165
+ assert _git(project, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip() == "master"
166
+ assert not local_branch_exists(project, "main")
167
+
168
+ plan = run_git_plan(project, branch_create_plan(BranchContext("master", "dev/F-001-master", project)))
169
+ assert plan.ok
170
+ assert local_branch_exists(project, "dev/F-001-master")
171
+
172
+
173
+ def test_empty_repository_gets_an_initial_commit_before_branching(tmp_path):
174
+ from prizmkit_runtime.gitops import (
175
+ BranchContext,
176
+ branch_create_plan,
177
+ current_branch,
178
+ ensure_branch_has_commit,
179
+ ensure_git_repository,
180
+ local_branch_exists,
181
+ run_git_plan,
182
+ )
183
+
184
+ project = tmp_path / "empty"
185
+ project.mkdir()
186
+ assert ensure_git_repository(project).return_code == 0
187
+ base = current_branch(project)
188
+ born = ensure_branch_has_commit(project)
189
+ assert born.return_code == 0
190
+ assert born.args[0] == "commit"
191
+ assert local_branch_exists(project, base)
192
+ plan = run_git_plan(project, branch_create_plan(BranchContext(base, "dev/F-001-empty", project)))
193
+ assert plan.ok
194
+
195
+
196
+ def test_runner_uses_real_master_when_recorded_base_main_does_not_exist(monkeypatch, tmp_path):
197
+ from prizmkit_runtime import runners
198
+ from prizmkit_runtime.gitops import local_branch_exists
199
+ from prizmkit_runtime.runner_models import family_for, parse_invocation
200
+ from prizmkit_runtime.task_checkout import TaskCheckout, load_task_checkout, persist_task_checkout
201
+
202
+ monkeypatch.delenv("USE_WORKTREE", raising=False)
203
+ monkeypatch.delenv("DEV_BRANCH", raising=False)
204
+ monkeypatch.setattr(
205
+ runners,
206
+ "load_runtime_config",
207
+ lambda paths: type("Config", (), {
208
+ "ai_client": type("Client", (), {"command": "fake-ai", "platform": "codebuddy", "launch_profile": None})(),
209
+ "model": "",
210
+ "effort": None,
211
+ "effort_validation": type("Effort", (), {"valid": True, "message": ""})(),
212
+ })(),
213
+ )
214
+
215
+ paths = tmp_path / "project"
216
+ _init_unborn(paths, "master")
217
+ _identity(paths)
218
+ (paths / ".prizmkit" / "plans").mkdir(parents=True)
219
+ (paths / "README").write_text("ready\n", encoding="utf-8")
220
+ _git(paths, "add", "README")
221
+ _git(paths, "commit", "-m", "chore: ready for F-001")
222
+
223
+ from prizmkit_runtime.paths import resolve_runtime_paths
224
+
225
+ runtime_paths = resolve_runtime_paths(
226
+ pipeline_root=PIPELINE_ROOT,
227
+ project_root=paths,
228
+ )
229
+ family = family_for("feature", runtime_paths)
230
+ invocation = parse_invocation(family, "run", ())
231
+ invocation = invocation.__class__(**{**invocation.__dict__, "list_path": runtime_paths.feature_plan})
232
+ persist_task_checkout(
233
+ family.state_dir,
234
+ TaskCheckout.active("feature", "F-001", "dev/F-001-poison", "main"),
235
+ )
236
+
237
+ def stop_after_branch(*_args, **_kwargs):
238
+ raise RuntimeError("stop-after-branch")
239
+
240
+ monkeypatch.setattr(runners, "start_item", stop_after_branch)
241
+
242
+ with pytest.raises(RuntimeError, match="stop-after-branch"):
243
+ runners._process_item(family, invocation, "F-001", runtime_paths, initial_metadata={})
244
+
245
+ checkout = load_task_checkout(family.state_dir, family.task_type, "F-001")
246
+ assert checkout is not None
247
+ assert checkout.base_branch == "master"
248
+ assert checkout.active_dev_branch == "dev/F-001-poison"
249
+ assert local_branch_exists(paths, "dev/F-001-poison")
250
+ assert _git(paths, "merge-base", "--is-ancestor", "master", "dev/F-001-poison").returncode == 0
251
+ stored = json.loads((family.state_dir / "F-001" / "checkout.json").read_text(encoding="utf-8"))
252
+ assert stored["base_branch"] == "master"
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.1.184",
2
+ "version": "1.1.187",
3
3
  "skills": {
4
4
  "prizmkit": {
5
5
  "description": "Framework introduction and navigation for the formal single-requirement lifecycle, project initialization, Prizm docs, and independent deployment.",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "prizmkit",
3
- "version": "1.1.184",
3
+ "version": "1.1.187",
4
4
  "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,19 +1,50 @@
1
1
  /**
2
- * Generate only explicit private host-memory ignores.
2
+ * Generate install-time gitignore text.
3
3
  *
4
- * `.prizmkit/**` tracking policy is project-controlled: this module never adds
5
- * framework-directory ignore entries. Only install appends private host-memory
6
- * ignores; upgrade and config must not write `.gitignore`.
4
+ * Install appends the exact `.prizmkit/*` line and any explicit private
5
+ * host-memory filenames. Upgrade and config must not write `.gitignore`.
6
+ * Cleanup removes only private host-memory entries.
7
7
  */
8
8
 
9
+ const FRAMEWORK_HEADER = '# PrizmKit';
10
+ const FRAMEWORK_ENTRY = '.prizmkit/*';
11
+ const PRIVATE_MEMORY_HEADER = '# PrizmKit private host memory';
12
+
13
+ /**
14
+ * @param {string[] | undefined} values
15
+ * @returns {string[]}
16
+ */
17
+ function uniqueGitignoreEntries(values) {
18
+ return Array.isArray(values) ? [...new Set(values.filter(Boolean))] : [];
19
+ }
20
+
9
21
  /**
10
22
  * @param {Object} options - { privateMemoryFiles?: string[] }
11
23
  * @returns {string}
12
24
  */
13
25
  export function generateGitignore(options = {}) {
14
- const privateMemoryFiles = Array.isArray(options.privateMemoryFiles)
15
- ? [...new Set(options.privateMemoryFiles.filter(Boolean))]
16
- : [];
17
- if (privateMemoryFiles.length === 0) return '';
18
- return ['# PrizmKit private host memory', ...privateMemoryFiles].join('\n');
26
+ const privateMemoryFiles = uniqueGitignoreEntries(options.privateMemoryFiles);
27
+ const lines = [FRAMEWORK_HEADER, FRAMEWORK_ENTRY];
28
+ if (privateMemoryFiles.length > 0) {
29
+ lines.push(PRIVATE_MEMORY_HEADER, ...privateMemoryFiles);
30
+ }
31
+ return lines.join('\n');
32
+ }
33
+
34
+ /**
35
+ * Sections appended independently so an existing private-memory header
36
+ * is not treated as the framework header.
37
+ *
38
+ * @param {Object} options - { privateMemoryFiles?: string[] }
39
+ * @returns {{ header: string, entries: string[] }[]}
40
+ */
41
+ export function gitignoreSections(options = {}) {
42
+ const privateMemoryFiles = uniqueGitignoreEntries(options.privateMemoryFiles);
43
+ const sections = [
44
+ { header: FRAMEWORK_HEADER, entries: [FRAMEWORK_ENTRY] },
45
+ ];
46
+ if (privateMemoryFiles.length > 0) {
47
+ sections.push({ header: PRIVATE_MEMORY_HEADER, entries: privateMemoryFiles });
48
+ }
49
+ return sections;
19
50
  }
package/src/scaffold.js CHANGED
@@ -4,7 +4,8 @@
4
4
  * 全部使用 Copy 模式(不使用 symlink),项目完全独立于框架仓库。
5
5
  * 通过 adapters 转换 core/ 资源为平台特定格式。
6
6
  * 不安装框架开发文件(docs、tests、scripts 等)。
7
- * 仅按显式平台需要合并私有记忆文件 ignore;`.prizmkit/**` Git 策略由项目控制。
7
+ * 安装时追加精确的 `.prizmkit/*` 行和所选平台的私有记忆文件 ignore。
8
+ * upgrade 与 config 不写 `.gitignore`。
8
9
  */
9
10
 
10
11
  import chalk from 'chalk';
@@ -24,7 +25,7 @@ import {
24
25
  loadRulesMetadata,
25
26
  getSkillCandidatePaths,
26
27
  } from './metadata.js';
27
- import { generateGitignore } from './gitignore-template.js';
28
+ import { generateGitignore, gitignoreSections } from './gitignore-template.js';
28
29
  import { buildManifest, readManifestForLifecycle, writeManifest } from './manifest.js';
29
30
  import { canonicalizePlatformSelection, defaultCliForPlatform, expandPlatforms, isKnownPlatform, nativeSkillRoot, payloadSkillRoots, platformLabel, privateProjectMemoryFile, privateProjectMemoryFiles, projectMemoryFile, resolvePayloadPlatforms, unknownPlatformMessage } from './platforms.js';
30
31
  import { normalizeRuntime, runtimeLabel } from './runtimes.js';
@@ -1374,46 +1375,42 @@ export async function installPipeline(projectRoot, dryRun, options = {}) {
1374
1375
  */
1375
1376
  export async function installGitignore(projectRoot, options = {}, dryRun) {
1376
1377
  const targetPath = path.join(projectRoot, '.gitignore');
1377
- const templateContent = generateGitignore({
1378
- pipeline: options.pipeline,
1379
- privateMemoryFiles: options.privateMemoryFiles || [],
1380
- });
1378
+ const sectionOptions = { privateMemoryFiles: options.privateMemoryFiles || [] };
1379
+ const templateContent = generateGitignore(sectionOptions);
1380
+ const sections = gitignoreSections(sectionOptions);
1381
1381
  const existed = await fs.pathExists(targetPath);
1382
1382
 
1383
1383
  if (dryRun) {
1384
- if (!templateContent) {
1385
- if (!existed) console.log(chalk.gray(' [dry-run] .gitignore (no managed private-memory entries)'));
1386
- return;
1387
- }
1388
- console.log(chalk.gray(' [dry-run] .gitignore (private host memory only)'));
1384
+ console.log(chalk.gray(' [dry-run] .gitignore (.prizmkit/* and private host memory)'));
1389
1385
  return;
1390
1386
  }
1391
1387
 
1392
- if (!templateContent) {
1393
- if (!existed) console.log(chalk.gray(' • .gitignore (no managed private-memory entries)'));
1388
+ if (!existed) {
1389
+ await fs.writeFile(targetPath, `${templateContent}\n`);
1390
+ console.log(chalk.green(' ✓ .gitignore'));
1394
1391
  return;
1395
1392
  }
1396
1393
 
1397
- if (existed) {
1398
- const current = await fs.readFile(targetPath, 'utf-8');
1399
- const existingLines = new Set(current.split('\n').map(l => l.trim()));
1400
- const templateLines = templateContent.split('\n').map(l => l.trim()).filter(Boolean);
1401
- const missing = templateLines.filter(line => !existingLines.has(line) && !line.startsWith('#'));
1394
+ const current = await fs.readFile(targetPath, 'utf-8');
1395
+ const existingLines = new Set(current.split('\n').map(line => line.trim()));
1396
+ const chunks = [];
1397
+ let missingCount = 0;
1398
+ for (const section of sections) {
1399
+ const missing = section.entries.filter(line => !existingLines.has(line));
1400
+ if (missing.length === 0) continue;
1401
+ missingCount += missing.length;
1402
+ const header = existingLines.has(section.header) ? '' : `${section.header}\n`;
1403
+ chunks.push(header + missing.join('\n'));
1404
+ }
1402
1405
 
1403
- if (missing.length > 0) {
1404
- const separator = current.endsWith('\n') ? '' : '\n';
1405
- const managedHeader = '# PrizmKit private host memory';
1406
- const header = existingLines.has(managedHeader) ? '' : `${managedHeader}\n`;
1407
- await fs.appendFile(targetPath, separator + '\n' + header + missing.join('\n') + '\n');
1408
- console.log(chalk.green(` ✓ .gitignore (added ${missing.length} entries)`));
1409
- } else {
1410
- console.log(chalk.green(' ✓ .gitignore (up-to-date)'));
1411
- }
1406
+ if (missingCount === 0) {
1407
+ console.log(chalk.green(' ✓ .gitignore (up-to-date)'));
1412
1408
  return;
1413
1409
  }
1414
1410
 
1415
- await fs.writeFile(targetPath, `${templateContent}\n`);
1416
- console.log(chalk.green(' ✓ .gitignore'));
1411
+ const separator = current.endsWith('\n') ? '' : '\n';
1412
+ await fs.appendFile(targetPath, `${separator}\n${chunks.join('\n')}\n`);
1413
+ console.log(chalk.green(` ✓ .gitignore (added ${missingCount} entries)`));
1417
1414
  }
1418
1415
 
1419
1416
  // ============================================================