prizmkit 1.1.169 → 1.1.170

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.169",
3
- "bundledAt": "2026-08-04T06:56:26.228Z",
4
- "bundledFrom": "37e94df"
2
+ "frameworkVersion": "1.1.170",
3
+ "bundledAt": "2026-08-05T18:03:01.414Z",
4
+ "bundledFrom": "e849c27"
5
5
  }
@@ -561,6 +561,25 @@ class GitPlanResult:
561
561
  return True
562
562
 
563
563
 
564
+ @dataclass(frozen=True)
565
+ class WipRestoreResult:
566
+ """Observable result of restoring one exact Runtime-owned WIP tip."""
567
+
568
+ status: str
569
+ reason: str
570
+ wip_head: str = ""
571
+ restored_head: str = ""
572
+ results: tuple[GitCommandResult, ...] = ()
573
+
574
+ @property
575
+ def ok(self) -> bool:
576
+ return self.status in {"restored", "not_needed"}
577
+
578
+ @property
579
+ def restored(self) -> bool:
580
+ return self.status == "restored"
581
+
582
+
564
583
  def _git(*args: str, allow_failure: bool = False, description: str = "") -> GitCommand:
565
584
  return GitCommand(args=args, allow_failure=allow_failure, description=description)
566
585
 
@@ -888,6 +907,178 @@ def worktree_save_wip(runtime: WorktreeRuntimeContext) -> GitPlanResult:
888
907
  return branch_save_wip(runtime.worktree_path, runtime.context.working_branch)
889
908
 
890
909
 
910
+ def _matches_runtime_wip_identity(
911
+ subject: str,
912
+ body: str,
913
+ *,
914
+ family_kind: str,
915
+ item_id: str,
916
+ working_branch: str,
917
+ ) -> bool:
918
+ failure_subject = re.fullmatch(
919
+ rf"wip\({re.escape(item_id)}\): preserve {re.escape(family_kind)} [a-z][a-z0-9_]* state",
920
+ subject,
921
+ )
922
+ failure_body = "Pipeline preserved task branch work without merging it to the base branch."
923
+ if failure_subject is not None and body == failure_body:
924
+ return True
925
+
926
+ interruption_subject = f"wip({working_branch}): interrupted — uncommitted work saved"
927
+ interruption_body = (
928
+ "Pipeline was interrupted by signal. This commit preserves work-in-progress.\n\n"
929
+ f"To resume: git checkout {working_branch}"
930
+ )
931
+ return subject == interruption_subject and body == interruption_body
932
+
933
+
934
+ def restore_runtime_wip(
935
+ project_root: Path,
936
+ *,
937
+ family_kind: str,
938
+ item_id: str,
939
+ working_branch: str,
940
+ ) -> WipRestoreResult:
941
+ """Rehydrate one exact Runtime-owned WIP tip into the reused task workspace."""
942
+ results: list[GitCommandResult] = []
943
+ active = run_git_command(project_root, ("rev-parse", "--abbrev-ref", "HEAD"))
944
+ results.append(active)
945
+ if active.return_code != 0:
946
+ return WipRestoreResult("failed", "runtime_wip_branch_unavailable", results=tuple(results))
947
+ if active.stdout.strip() != working_branch:
948
+ return WipRestoreResult("failed", "runtime_wip_branch_mismatch", results=tuple(results))
949
+
950
+ unmerged = run_git_command(project_root, ("ls-files", "-u"))
951
+ results.append(unmerged)
952
+ if unmerged.return_code != 0:
953
+ return WipRestoreResult("failed", "runtime_wip_merge_state_unavailable", results=tuple(results))
954
+ if unmerged.stdout.strip():
955
+ return WipRestoreResult("failed", "runtime_wip_unresolved_merge", results=tuple(results))
956
+
957
+ identity = run_git_command(project_root, ("show", "-s", "--format=%H%x00%P%x00%s%x00%b", "HEAD"))
958
+ results.append(identity)
959
+ if identity.return_code != 0:
960
+ return WipRestoreResult("failed", "runtime_wip_identity_unavailable", results=tuple(results))
961
+ parts = identity.stdout.rstrip("\n").split("\0", 3)
962
+ if len(parts) != 4:
963
+ return WipRestoreResult("failed", "runtime_wip_identity_invalid", results=tuple(results))
964
+ head, parents_text, subject, body = parts
965
+ body = body.rstrip("\n")
966
+ if not _matches_runtime_wip_identity(
967
+ subject,
968
+ body,
969
+ family_kind=family_kind,
970
+ item_id=item_id,
971
+ working_branch=working_branch,
972
+ ):
973
+ return WipRestoreResult(
974
+ "not_needed",
975
+ "runtime_wip_not_found",
976
+ wip_head=head,
977
+ restored_head=head,
978
+ results=tuple(results),
979
+ )
980
+
981
+ staged = run_git_command(project_root, ("diff", "--cached", "--name-only", "-z"))
982
+ results.append(staged)
983
+ if staged.return_code != 0:
984
+ return WipRestoreResult(
985
+ "failed",
986
+ "runtime_wip_staged_state_unavailable",
987
+ wip_head=head,
988
+ restored_head=head,
989
+ results=tuple(results),
990
+ )
991
+ if staged.stdout.strip("\0"):
992
+ return WipRestoreResult(
993
+ "failed",
994
+ "runtime_wip_staged_changes",
995
+ wip_head=head,
996
+ restored_head=head,
997
+ results=tuple(results),
998
+ )
999
+
1000
+ parents = parents_text.split()
1001
+ if len(parents) != 1:
1002
+ return WipRestoreResult(
1003
+ "failed",
1004
+ "runtime_wip_parent_invalid",
1005
+ wip_head=head,
1006
+ restored_head=head,
1007
+ results=tuple(results),
1008
+ )
1009
+ parent = parents[0]
1010
+ changed = run_git_command(
1011
+ project_root,
1012
+ ("diff-tree", "--no-commit-id", "--name-only", "--no-renames", "-r", "-z", head),
1013
+ )
1014
+ results.append(changed)
1015
+ if changed.return_code != 0:
1016
+ return WipRestoreResult(
1017
+ "failed",
1018
+ "runtime_wip_paths_unavailable",
1019
+ wip_head=head,
1020
+ restored_head=head,
1021
+ results=tuple(results),
1022
+ )
1023
+ wip_paths = {path for path in changed.stdout.split("\0") if path}
1024
+ if not wip_paths:
1025
+ return WipRestoreResult(
1026
+ "failed",
1027
+ "runtime_wip_empty_commit",
1028
+ wip_head=head,
1029
+ restored_head=head,
1030
+ results=tuple(results),
1031
+ )
1032
+
1033
+ reset = run_git_command(project_root, ("reset", "--mixed", parent))
1034
+ results.append(reset)
1035
+ if reset.return_code != 0:
1036
+ return WipRestoreResult(
1037
+ "failed",
1038
+ "runtime_wip_restore_failed",
1039
+ wip_head=head,
1040
+ restored_head=head,
1041
+ results=tuple(results),
1042
+ )
1043
+
1044
+ restored_head_result = run_git_command(project_root, ("rev-parse", "HEAD"))
1045
+ results.append(restored_head_result)
1046
+ visible_paths, visible_result = visible_task_paths(project_root)
1047
+ results.append(visible_result)
1048
+ visible_set = set(visible_paths)
1049
+ verified = (
1050
+ restored_head_result.return_code == 0
1051
+ and restored_head_result.stdout.strip() == parent
1052
+ and visible_result.return_code == 0
1053
+ and wip_paths.issubset(visible_set)
1054
+ )
1055
+ if not verified:
1056
+ rollback = run_git_command(project_root, ("reset", "--mixed", head))
1057
+ results.append(rollback)
1058
+ reason = (
1059
+ "runtime_wip_restore_rollback_failed"
1060
+ if rollback.return_code != 0
1061
+ else "runtime_wip_restore_verification_failed"
1062
+ )
1063
+ current = run_git_command(project_root, ("rev-parse", "HEAD"))
1064
+ results.append(current)
1065
+ return WipRestoreResult(
1066
+ "failed",
1067
+ reason,
1068
+ wip_head=head,
1069
+ restored_head=current.stdout.strip() if current.return_code == 0 else "",
1070
+ results=tuple(results),
1071
+ )
1072
+
1073
+ return WipRestoreResult(
1074
+ "restored",
1075
+ "runtime_wip_restored",
1076
+ wip_head=head,
1077
+ restored_head=parent,
1078
+ results=tuple(results),
1079
+ )
1080
+
1081
+
891
1082
  def branch_ensure_return(project_root: Path, base_branch: str, working_branch: str = "") -> GitPlanResult:
892
1083
  """Commit Git-visible task WIP when needed, then return the caller checkout to base."""
893
1084
  active = current_branch(project_root)
@@ -29,6 +29,7 @@ from .gitops import (
29
29
  guarded_worktree_remove,
30
30
  materialize_worktree_support_assets,
31
31
  merge_linked_worktree,
32
+ restore_runtime_wip,
32
33
  run_git_command,
33
34
  run_git_plan,
34
35
  worktree_runtime_context,
@@ -565,7 +566,8 @@ def _process_item_locked(
565
566
  branch_name = _resolve_working_branch(family, item_id, metadata, env, active_branch)
566
567
  branch_context = BranchContext(base_branch, branch_name, paths.project_root)
567
568
  worktree_runtime = None
568
- if checkout is not None and checkout.is_active:
569
+ reusing_checkout = checkout is not None and checkout.is_active
570
+ if reusing_checkout:
569
571
  use_worktree = checkout.uses_worktree
570
572
  worktree_path = Path(checkout.worktree_path) if checkout.worktree_path else None
571
573
  else:
@@ -641,6 +643,36 @@ def _process_item_locked(
641
643
  if not branch_result.ok:
642
644
  return "infra_error"
643
645
 
646
+ if reusing_checkout:
647
+ restored_wip = restore_runtime_wip(
648
+ execution_root,
649
+ family_kind=family.kind,
650
+ item_id=item_id,
651
+ working_branch=branch_name,
652
+ )
653
+ if not restored_wip.ok:
654
+ _emit_warning(
655
+ f"Runtime WIP recovery failed for {item_id}: {restored_wip.reason}; "
656
+ "AI launch was blocked and the preserved checkout remains active"
657
+ )
658
+ return _record_setup_failure(
659
+ family,
660
+ invocation,
661
+ item_id,
662
+ paths.project_root,
663
+ execution_root,
664
+ base_branch,
665
+ branch_name,
666
+ worktree_runtime=worktree_runtime,
667
+ )
668
+ if restored_wip.restored:
669
+ _emit_info(
670
+ f"Recovery: restored Runtime-owned WIP {restored_wip.wip_head[:12]} "
671
+ f"into the workspace for {item_id}"
672
+ )
673
+ else:
674
+ _emit_info(f"Recovery: no Runtime-owned WIP tip to restore for {item_id}")
675
+
644
676
  _emit_item_header(family, invocation, item_id, metadata)
645
677
  status_root = execution_root if use_worktree else paths.project_root
646
678
  status_family = _family_for_execution_root(family, paths.project_root, status_root)
@@ -1465,6 +1465,8 @@ def _install_runner_session_fakes(monkeypatch, runners, *, statuses=("success",)
1465
1465
  cleanup_calls = []
1466
1466
  merge_calls = []
1467
1467
  wip_calls = []
1468
+ restore_calls = []
1469
+ events = []
1468
1470
  status_queue = list(statuses)
1469
1471
 
1470
1472
  monkeypatch.setattr(
@@ -1501,6 +1503,7 @@ def _install_runner_session_fakes(monkeypatch, runners, *, statuses=("success",)
1501
1503
  )
1502
1504
 
1503
1505
  def fake_generate_prompt(family, invocation, **kwargs):
1506
+ events.append("prompt")
1504
1507
  prompt_calls.append(kwargs)
1505
1508
  session_paths = kwargs["session_paths"]
1506
1509
  execution_root = kwargs.get("execution_root") or kwargs["project_root"]
@@ -1570,6 +1573,17 @@ def _install_runner_session_fakes(monkeypatch, runners, *, statuses=("success",)
1570
1573
  wip_calls.append(runtime)
1571
1574
  return SimpleNamespace(ok=True, plan=None, results=())
1572
1575
 
1576
+ def fake_restore_wip(project_root, **kwargs):
1577
+ events.append("restore")
1578
+ restore_calls.append((project_root, kwargs))
1579
+ return SimpleNamespace(
1580
+ ok=True,
1581
+ restored=False,
1582
+ reason="runtime_wip_not_found",
1583
+ wip_head="",
1584
+ restored_head="",
1585
+ )
1586
+
1573
1587
  monkeypatch.setattr(runners, "generate_prompt", fake_generate_prompt)
1574
1588
  monkeypatch.setattr(runners, "AISessionLauncher", FakeLauncher)
1575
1589
  monkeypatch.setattr(runners, "classify_session", fake_classify)
@@ -1577,6 +1591,7 @@ def _install_runner_session_fakes(monkeypatch, runners, *, statuses=("success",)
1577
1591
  monkeypatch.setattr(runners, "guarded_worktree_remove", fake_cleanup, raising=False)
1578
1592
  monkeypatch.setattr(runners, "merge_linked_worktree", fake_merge, raising=False)
1579
1593
  monkeypatch.setattr(runners, "worktree_save_wip", fake_save_wip, raising=False)
1594
+ monkeypatch.setattr(runners, "restore_runtime_wip", fake_restore_wip, raising=False)
1580
1595
  return SimpleNamespace(
1581
1596
  prompt_calls=prompt_calls,
1582
1597
  launch_cwds=launch_cwds,
@@ -1585,8 +1600,184 @@ def _install_runner_session_fakes(monkeypatch, runners, *, statuses=("success",)
1585
1600
  cleanup_calls=cleanup_calls,
1586
1601
  merge_calls=merge_calls,
1587
1602
  wip_calls=wip_calls,
1603
+ restore_calls=restore_calls,
1604
+ events=events,
1605
+ )
1606
+
1607
+
1608
+ def test_runner_does_not_restore_wip_for_first_checkout(monkeypatch, tmp_path):
1609
+ from prizmkit_runtime import runners
1610
+ from prizmkit_runtime.runner_models import family_for, parse_invocation
1611
+
1612
+ paths = _make_paths(tmp_path / "first-checkout-no-wip-restore")
1613
+ family = family_for("feature", paths)
1614
+ invocation = parse_invocation(family, "run", ())
1615
+ invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
1616
+ observed = _install_runner_session_fakes(monkeypatch, runners)
1617
+ monkeypatch.setattr(
1618
+ runners,
1619
+ "run_git_plan",
1620
+ lambda *args, **kwargs: SimpleNamespace(ok=True, reason="", results=()),
1588
1621
  )
1589
1622
 
1623
+ status = runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
1624
+
1625
+ assert status == "completed"
1626
+ assert observed.restore_calls == []
1627
+ assert observed.events == ["prompt"]
1628
+
1629
+
1630
+ def test_runner_restores_wip_before_prompt_for_reused_branch_checkout(monkeypatch, tmp_path):
1631
+ from prizmkit_runtime import runners
1632
+ from prizmkit_runtime.runner_models import family_for, parse_invocation
1633
+ from prizmkit_runtime.task_checkout import TaskCheckout, persist_task_checkout
1634
+
1635
+ paths = _make_paths(tmp_path / "reused-branch-wip-restore")
1636
+ family = family_for("feature", paths)
1637
+ branch = "dev/feature/F-001-preserved"
1638
+ persist_task_checkout(
1639
+ family.state_dir,
1640
+ TaskCheckout.active(family.task_type, "F-001", branch, "main"),
1641
+ )
1642
+ invocation = parse_invocation(family, "run", ())
1643
+ invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
1644
+ observed = _install_runner_session_fakes(monkeypatch, runners)
1645
+ monkeypatch.setattr(
1646
+ runners,
1647
+ "run_git_plan",
1648
+ lambda *args, **kwargs: SimpleNamespace(ok=True, reason="", results=()),
1649
+ )
1650
+
1651
+ status = runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
1652
+
1653
+ assert status == "completed"
1654
+ assert observed.events == ["restore", "prompt"]
1655
+ assert observed.restore_calls == [
1656
+ (
1657
+ paths.project_root,
1658
+ {
1659
+ "family_kind": "feature",
1660
+ "item_id": "F-001",
1661
+ "working_branch": branch,
1662
+ },
1663
+ )
1664
+ ]
1665
+
1666
+
1667
+ def test_runner_restores_wip_before_prompt_for_reused_worktree_checkout(monkeypatch, tmp_path):
1668
+ from prizmkit_runtime import runners
1669
+ from prizmkit_runtime.gitops import (
1670
+ BranchContext,
1671
+ WorktreePolicy,
1672
+ worktree_runtime_context,
1673
+ )
1674
+ from prizmkit_runtime.runner_models import family_for, parse_invocation
1675
+ from prizmkit_runtime.task_checkout import (
1676
+ CHECKOUT_MODE_WORKTREE,
1677
+ TaskCheckout,
1678
+ persist_task_checkout,
1679
+ )
1680
+
1681
+ monkeypatch.setenv("USE_WORKTREE", "1")
1682
+ paths = _make_paths(tmp_path / "reused-worktree-wip-restore")
1683
+ family = family_for("feature", paths)
1684
+ branch = "dev/feature/F-001-preserved"
1685
+ expected_runtime = worktree_runtime_context(
1686
+ BranchContext("main", branch, paths.project_root),
1687
+ WorktreePolicy(
1688
+ use_worktree=True,
1689
+ cleanup_on_success=True,
1690
+ preserve_on_failure=True,
1691
+ worktree_root=paths.state_dir / "worktrees",
1692
+ ),
1693
+ )
1694
+ worktree_path = expected_runtime.worktree_path
1695
+ persist_task_checkout(
1696
+ family.state_dir,
1697
+ TaskCheckout.active(
1698
+ family.task_type,
1699
+ "F-001",
1700
+ branch,
1701
+ "main",
1702
+ checkout_mode=CHECKOUT_MODE_WORKTREE,
1703
+ worktree_path=str(worktree_path),
1704
+ ),
1705
+ )
1706
+ invocation = parse_invocation(family, "run", ())
1707
+ invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
1708
+ observed = _install_runner_session_fakes(monkeypatch, runners)
1709
+
1710
+ def fake_setup(runtime):
1711
+ runtime.worktree_path.mkdir(parents=True, exist_ok=True)
1712
+ return SimpleNamespace(ok=True, runtime=runtime, reason="")
1713
+
1714
+ monkeypatch.setattr(runners, "ensure_linked_worktree", fake_setup)
1715
+ monkeypatch.setattr(
1716
+ runners,
1717
+ "materialize_worktree_support_assets",
1718
+ lambda *args, **kwargs: SimpleNamespace(ok=True, reason=""),
1719
+ )
1720
+
1721
+ status = runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
1722
+
1723
+ assert status == "completed"
1724
+ assert observed.events == ["restore", "prompt"]
1725
+ assert observed.restore_calls[0][0] == worktree_path.resolve()
1726
+ assert observed.restore_calls[0][1] == {
1727
+ "family_kind": "feature",
1728
+ "item_id": "F-001",
1729
+ "working_branch": branch,
1730
+ }
1731
+
1732
+
1733
+ def test_runner_blocks_ai_launch_when_reused_wip_restore_fails(monkeypatch, tmp_path):
1734
+ from prizmkit_runtime import runners
1735
+ from prizmkit_runtime.runner_models import family_for, parse_invocation
1736
+ from prizmkit_runtime.task_checkout import TaskCheckout, persist_task_checkout
1737
+
1738
+ paths = _make_paths(tmp_path / "failed-branch-wip-restore")
1739
+ family = family_for("feature", paths)
1740
+ branch = "dev/feature/F-001-preserved"
1741
+ persist_task_checkout(
1742
+ family.state_dir,
1743
+ TaskCheckout.active(family.task_type, "F-001", branch, "main"),
1744
+ )
1745
+ invocation = parse_invocation(family, "run", ())
1746
+ invocation = invocation.__class__(**{**invocation.__dict__, "list_path": paths.feature_plan})
1747
+ observed = _install_runner_session_fakes(monkeypatch, runners)
1748
+ monkeypatch.setattr(
1749
+ runners,
1750
+ "run_git_plan",
1751
+ lambda *args, **kwargs: SimpleNamespace(ok=True, reason="", results=()),
1752
+ )
1753
+ monkeypatch.setattr(
1754
+ runners,
1755
+ "restore_runtime_wip",
1756
+ lambda *args, **kwargs: SimpleNamespace(
1757
+ ok=False,
1758
+ restored=False,
1759
+ reason="runtime_wip_unresolved_merge",
1760
+ wip_head="preserved-head",
1761
+ restored_head="preserved-head",
1762
+ ),
1763
+ raising=False,
1764
+ )
1765
+ monkeypatch.setattr(
1766
+ runners,
1767
+ "commit_wip_changes",
1768
+ lambda *args, **kwargs: SimpleNamespace(ok=True),
1769
+ )
1770
+ monkeypatch.setattr(
1771
+ runners,
1772
+ "branch_ensure_return",
1773
+ lambda *args, **kwargs: SimpleNamespace(ok=True),
1774
+ )
1775
+
1776
+ status = runners._process_item(family, invocation, "F-001", paths, initial_metadata={})
1777
+
1778
+ assert status == "infra_error"
1779
+ assert observed.prompt_calls == []
1780
+ assert observed.launch_cwds == []
1590
1781
 
1591
1782
 
1592
1783
  def test_outer_runner_routes_cursor_through_native_preflight_and_session_config(monkeypatch, tmp_path):
@@ -224,6 +224,60 @@ def test_runtime_commit_executes_complete_workspace_and_finalizes_only_checkpoin
224
224
  ).semantic_complete is True
225
225
 
226
226
 
227
+ def test_runtime_commit_finalizes_rehydrated_failure_wip(tmp_path):
228
+ from types import SimpleNamespace
229
+
230
+ from prizmkit_runtime.gitops import restore_runtime_wip
231
+ from prizmkit_runtime.runner_bookkeeping import commit_wip_changes
232
+
233
+ base_head = _init_repo(tmp_path)
234
+ branch = "dev/F-005-runtime-wip"
235
+ _git(tmp_path, "checkout", "-b", branch)
236
+ (tmp_path / "tracked.txt").write_text("preserved feature change\n", encoding="utf-8")
237
+ preserved = commit_wip_changes(
238
+ tmp_path,
239
+ SimpleNamespace(kind="feature"),
240
+ "F-005",
241
+ "failed",
242
+ )
243
+ assert preserved.committed is True
244
+ wip_head = _git(tmp_path, "rev-parse", "HEAD")
245
+ assert wip_head != base_head
246
+ assert _git(tmp_path, "status", "--porcelain", "--", "tracked.txt") == ""
247
+
248
+ restored = restore_runtime_wip(
249
+ tmp_path,
250
+ family_kind="feature",
251
+ item_id="F-005",
252
+ working_branch=branch,
253
+ )
254
+ assert restored.ok is True
255
+ assert restored.restored is True
256
+ assert restored.wip_head == wip_head
257
+ assert restored.restored_head == base_head
258
+ assert _git(tmp_path, "rev-parse", "HEAD") == base_head
259
+ assert "tracked.txt" in _git(tmp_path, "status", "--porcelain", "--", "tracked.txt")
260
+
261
+ artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
262
+ _write_request(tmp_path, artifact_dir, base_head)
263
+ result = finalize_runtime_commit(
264
+ tmp_path,
265
+ artifact_dir=artifact_dir,
266
+ checkpoint_path=checkpoint_path,
267
+ )
268
+
269
+ assert result.status == "committed"
270
+ assert result.reason == "runtime_commit_completed"
271
+ assert result.commit_hash == _git(tmp_path, "rev-parse", "HEAD")
272
+ assert _git(tmp_path, "show", "-s", "--format=%s", "HEAD") == "fix(runtime): finalize prepared task"
273
+ assert _git(tmp_path, "show", "HEAD:tracked.txt") == "preserved feature change"
274
+ assert _git(tmp_path, "rev-list", "--count", f"{base_head}..HEAD") == "1"
275
+ checkpoint = json.loads(checkpoint_path.read_text(encoding="utf-8"))
276
+ assert checkpoint["feature_state"]["runtime_base_head"] == base_head
277
+ assert checkpoint["feature_state"]["runtime_commit_hash"] == result.commit_hash
278
+ assert checkpoint["feature_state"]["terminal_status"] == "WORKFLOW_COMPLETED"
279
+
280
+
227
281
  @pytest.mark.parametrize(
228
282
  "durable_path",
229
283
  [
@@ -3373,6 +3373,428 @@ def _stash_oids(project_root):
3373
3373
  return tuple(line for line in output.splitlines() if line)
3374
3374
 
3375
3375
 
3376
+ def _commit_runtime_wip(project_root, subject, *body_paragraphs):
3377
+ subprocess.run(["git", "add", "-A", "--", "."], cwd=project_root, check=True)
3378
+ command = ["git", "commit", "--no-verify", "-m", subject]
3379
+ for paragraph in body_paragraphs:
3380
+ command.extend(["-m", paragraph])
3381
+ subprocess.run(command, cwd=project_root, check=True, stdout=subprocess.DEVNULL)
3382
+ return subprocess.run(
3383
+ ["git", "rev-parse", "HEAD"],
3384
+ cwd=project_root,
3385
+ check=True,
3386
+ stdout=subprocess.PIPE,
3387
+ text=True,
3388
+ ).stdout.strip()
3389
+
3390
+
3391
+ def test_restore_runtime_wip_rehydrates_complete_failure_commit(tmp_path):
3392
+ from prizmkit_runtime.gitops import restore_runtime_wip
3393
+
3394
+ _init_merge_repo(tmp_path)
3395
+ (tmp_path / "delete me.txt").write_text("delete\n", encoding="utf-8")
3396
+ (tmp_path / "rename source.txt").write_text("rename\n", encoding="utf-8")
3397
+ subprocess.run(
3398
+ ["git", "add", "delete me.txt", "rename source.txt"],
3399
+ cwd=tmp_path,
3400
+ check=True,
3401
+ )
3402
+ subprocess.run(
3403
+ ["git", "commit", "-m", "add restoration matrix"],
3404
+ cwd=tmp_path,
3405
+ check=True,
3406
+ stdout=subprocess.DEVNULL,
3407
+ )
3408
+ subprocess.run(
3409
+ ["git", "checkout", "-b", "dev/F-005-runtime-wip"],
3410
+ cwd=tmp_path,
3411
+ check=True,
3412
+ stdout=subprocess.DEVNULL,
3413
+ )
3414
+ parent = subprocess.run(
3415
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3416
+ ).stdout.strip()
3417
+ (tmp_path / "app.txt").write_text("recovered feature\n", encoding="utf-8")
3418
+ (tmp_path / "delete me.txt").unlink()
3419
+ subprocess.run(
3420
+ ["git", "mv", "rename source.txt", "renamed [literal]*.txt"],
3421
+ cwd=tmp_path,
3422
+ check=True,
3423
+ )
3424
+ (tmp_path / "new [literal]*.txt").write_text("new\n", encoding="utf-8")
3425
+ wip_head = _commit_runtime_wip(
3426
+ tmp_path,
3427
+ "wip(F-005): preserve feature failed state",
3428
+ "Pipeline preserved task branch work without merging it to the base branch.",
3429
+ )
3430
+
3431
+ result = restore_runtime_wip(
3432
+ tmp_path,
3433
+ family_kind="feature",
3434
+ item_id="F-005",
3435
+ working_branch="dev/F-005-runtime-wip",
3436
+ )
3437
+
3438
+ assert result.ok is True
3439
+ assert result.restored is True
3440
+ assert result.reason == "runtime_wip_restored"
3441
+ assert result.wip_head == wip_head
3442
+ assert result.restored_head == parent
3443
+ assert subprocess.run(
3444
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3445
+ ).stdout.strip() == parent
3446
+ status = subprocess.run(
3447
+ ["git", "status", "--porcelain=v1"],
3448
+ cwd=tmp_path,
3449
+ check=True,
3450
+ stdout=subprocess.PIPE,
3451
+ text=True,
3452
+ ).stdout
3453
+ assert "app.txt" in status
3454
+ assert "delete me.txt" in status
3455
+ assert "rename source.txt" in status
3456
+ assert "renamed [literal]*.txt" in status
3457
+ assert "new [literal]*.txt" in status
3458
+ assert (tmp_path / "app.txt").read_text(encoding="utf-8") == "recovered feature\n"
3459
+ assert not (tmp_path / "delete me.txt").exists()
3460
+ assert (tmp_path / "renamed [literal]*.txt").read_text(encoding="utf-8") == "rename\n"
3461
+ assert (tmp_path / "new [literal]*.txt").read_text(encoding="utf-8") == "new\n"
3462
+
3463
+ status_before_repeat = status
3464
+ repeated = restore_runtime_wip(
3465
+ tmp_path,
3466
+ family_kind="feature",
3467
+ item_id="F-005",
3468
+ working_branch="dev/F-005-runtime-wip",
3469
+ )
3470
+ assert repeated.ok is True
3471
+ assert repeated.restored is False
3472
+ assert repeated.reason == "runtime_wip_not_found"
3473
+ assert repeated.restored_head == parent
3474
+ assert subprocess.run(
3475
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3476
+ ).stdout.strip() == parent
3477
+ assert subprocess.run(
3478
+ ["git", "status", "--porcelain=v1"],
3479
+ cwd=tmp_path,
3480
+ check=True,
3481
+ stdout=subprocess.PIPE,
3482
+ text=True,
3483
+ ).stdout == status_before_repeat
3484
+
3485
+
3486
+ def test_restore_runtime_wip_accepts_exact_interruption_identity(tmp_path):
3487
+ from prizmkit_runtime.gitops import branch_save_wip, restore_runtime_wip
3488
+
3489
+ _init_merge_repo(tmp_path)
3490
+ branch = "dev/F-005-interrupted"
3491
+ subprocess.run(["git", "checkout", "-b", branch], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3492
+ parent = subprocess.run(
3493
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3494
+ ).stdout.strip()
3495
+ (tmp_path / "app.txt").write_text("interrupted\n", encoding="utf-8")
3496
+ preserved = branch_save_wip(tmp_path, branch)
3497
+ assert preserved.ok is True
3498
+ assert any(command.args[:1] == ("commit",) for command in preserved.plan.commands)
3499
+
3500
+ result = restore_runtime_wip(
3501
+ tmp_path,
3502
+ family_kind="feature",
3503
+ item_id="F-005",
3504
+ working_branch=branch,
3505
+ )
3506
+
3507
+ assert result.ok is True
3508
+ assert result.restored is True
3509
+ assert result.restored_head == parent
3510
+ assert (tmp_path / "app.txt").read_text(encoding="utf-8") == "interrupted\n"
3511
+
3512
+
3513
+ @pytest.mark.parametrize(
3514
+ ("subject", "body"),
3515
+ (
3516
+ ("feat(F-005): completed work", ""),
3517
+ (
3518
+ "wip(F-005): preserve feature failed state",
3519
+ "User-authored lookalike without the canonical Runtime body.",
3520
+ ),
3521
+ (
3522
+ "wip(F-999): preserve feature failed state",
3523
+ "Pipeline preserved task branch work without merging it to the base branch.",
3524
+ ),
3525
+ ),
3526
+ )
3527
+ def test_restore_runtime_wip_leaves_non_owned_tip_unchanged(tmp_path, subject, body):
3528
+ from prizmkit_runtime.gitops import restore_runtime_wip
3529
+
3530
+ _init_merge_repo(tmp_path)
3531
+ branch = "dev/F-005-owned-only"
3532
+ subprocess.run(["git", "checkout", "-b", branch], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3533
+ (tmp_path / "app.txt").write_text("committed\n", encoding="utf-8")
3534
+ head = _commit_runtime_wip(tmp_path, subject, *([body] if body else []))
3535
+
3536
+ result = restore_runtime_wip(
3537
+ tmp_path,
3538
+ family_kind="feature",
3539
+ item_id="F-005",
3540
+ working_branch=branch,
3541
+ )
3542
+
3543
+ assert result.ok is True
3544
+ assert result.restored is False
3545
+ assert result.reason == "runtime_wip_not_found"
3546
+ assert subprocess.run(
3547
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3548
+ ).stdout.strip() == head
3549
+ assert subprocess.run(
3550
+ ["git", "status", "--porcelain"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3551
+ ).stdout == ""
3552
+
3553
+
3554
+ def test_restore_runtime_wip_leaves_staged_work_on_non_wip_tip_unchanged(tmp_path):
3555
+ from prizmkit_runtime.gitops import restore_runtime_wip
3556
+
3557
+ _init_merge_repo(tmp_path)
3558
+ branch = "dev/F-005-ordinary-staged"
3559
+ subprocess.run(["git", "checkout", "-b", branch], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3560
+ head = subprocess.run(
3561
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3562
+ ).stdout.strip()
3563
+ (tmp_path / "app.txt").write_text("staged recovery work\n", encoding="utf-8")
3564
+ subprocess.run(["git", "add", "app.txt"], cwd=tmp_path, check=True)
3565
+ staged_before = subprocess.run(
3566
+ ["git", "diff", "--cached", "--", "app.txt"],
3567
+ cwd=tmp_path,
3568
+ check=True,
3569
+ stdout=subprocess.PIPE,
3570
+ text=True,
3571
+ ).stdout
3572
+
3573
+ result = restore_runtime_wip(
3574
+ tmp_path,
3575
+ family_kind="feature",
3576
+ item_id="F-005",
3577
+ working_branch=branch,
3578
+ )
3579
+
3580
+ assert result.ok is True
3581
+ assert result.restored is False
3582
+ assert result.reason == "runtime_wip_not_found"
3583
+ assert subprocess.run(
3584
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3585
+ ).stdout.strip() == head
3586
+ assert subprocess.run(
3587
+ ["git", "diff", "--cached", "--", "app.txt"],
3588
+ cwd=tmp_path,
3589
+ check=True,
3590
+ stdout=subprocess.PIPE,
3591
+ text=True,
3592
+ ).stdout == staged_before
3593
+
3594
+
3595
+ def test_restore_runtime_wip_rejects_staged_overlay_without_moving_wip_tip(tmp_path):
3596
+ from prizmkit_runtime.gitops import restore_runtime_wip
3597
+
3598
+ _init_merge_repo(tmp_path)
3599
+ branch = "dev/F-005-staged-overlay"
3600
+ subprocess.run(["git", "checkout", "-b", branch], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3601
+ (tmp_path / "app.txt").write_text("preserved\n", encoding="utf-8")
3602
+ wip_head = _commit_runtime_wip(
3603
+ tmp_path,
3604
+ "wip(F-005): preserve feature failed state",
3605
+ "Pipeline preserved task branch work without merging it to the base branch.",
3606
+ )
3607
+ (tmp_path / "post-wip.txt").write_text("staged after preservation\n", encoding="utf-8")
3608
+ subprocess.run(["git", "add", "post-wip.txt"], cwd=tmp_path, check=True)
3609
+ staged_before = subprocess.run(
3610
+ ["git", "diff", "--cached", "--binary"],
3611
+ cwd=tmp_path,
3612
+ check=True,
3613
+ stdout=subprocess.PIPE,
3614
+ text=True,
3615
+ ).stdout
3616
+
3617
+ result = restore_runtime_wip(
3618
+ tmp_path,
3619
+ family_kind="feature",
3620
+ item_id="F-005",
3621
+ working_branch=branch,
3622
+ )
3623
+
3624
+ assert result.ok is False
3625
+ assert result.reason == "runtime_wip_staged_changes"
3626
+ assert result.wip_head == wip_head
3627
+ assert result.restored_head == wip_head
3628
+ assert subprocess.run(
3629
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3630
+ ).stdout.strip() == wip_head
3631
+ assert subprocess.run(
3632
+ ["git", "diff", "--cached", "--binary"],
3633
+ cwd=tmp_path,
3634
+ check=True,
3635
+ stdout=subprocess.PIPE,
3636
+ text=True,
3637
+ ).stdout == staged_before
3638
+ assert (tmp_path / "app.txt").read_text(encoding="utf-8") == "preserved\n"
3639
+ assert (tmp_path / "post-wip.txt").read_text(encoding="utf-8") == "staged after preservation\n"
3640
+
3641
+
3642
+ def test_restore_runtime_wip_rejects_recorded_branch_mismatch_without_moving_head(tmp_path):
3643
+ from prizmkit_runtime.gitops import restore_runtime_wip
3644
+
3645
+ _init_merge_repo(tmp_path)
3646
+ branch = "dev/F-005-actual"
3647
+ subprocess.run(["git", "checkout", "-b", branch], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3648
+ (tmp_path / "app.txt").write_text("preserved\n", encoding="utf-8")
3649
+ head = _commit_runtime_wip(
3650
+ tmp_path,
3651
+ "wip(F-005): preserve feature failed state",
3652
+ "Pipeline preserved task branch work without merging it to the base branch.",
3653
+ )
3654
+
3655
+ result = restore_runtime_wip(
3656
+ tmp_path,
3657
+ family_kind="feature",
3658
+ item_id="F-005",
3659
+ working_branch="dev/F-005-recorded",
3660
+ )
3661
+
3662
+ assert result.ok is False
3663
+ assert result.reason == "runtime_wip_branch_mismatch"
3664
+ assert subprocess.run(
3665
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3666
+ ).stdout.strip() == head
3667
+
3668
+
3669
+ def test_restore_runtime_wip_rejects_merge_state_without_moving_head(tmp_path):
3670
+ from prizmkit_runtime.gitops import restore_runtime_wip
3671
+
3672
+ _init_merge_repo(tmp_path)
3673
+ branch = "dev/F-005-conflicted"
3674
+ subprocess.run(["git", "checkout", "-b", branch], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3675
+ (tmp_path / "app.txt").write_text("preserved side\n", encoding="utf-8")
3676
+ wip_head = _commit_runtime_wip(
3677
+ tmp_path,
3678
+ "wip(F-005): preserve feature failed state",
3679
+ "Pipeline preserved task branch work without merging it to the base branch.",
3680
+ )
3681
+ subprocess.run(["git", "checkout", "main"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3682
+ (tmp_path / "app.txt").write_text("base side\n", encoding="utf-8")
3683
+ subprocess.run(["git", "commit", "-am", "advance conflicting base"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3684
+ subprocess.run(["git", "checkout", branch], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3685
+ merge = subprocess.run(
3686
+ ["git", "merge", "main"],
3687
+ cwd=tmp_path,
3688
+ check=False,
3689
+ stdout=subprocess.PIPE,
3690
+ stderr=subprocess.PIPE,
3691
+ text=True,
3692
+ )
3693
+ assert merge.returncode != 0
3694
+
3695
+ result = restore_runtime_wip(
3696
+ tmp_path,
3697
+ family_kind="feature",
3698
+ item_id="F-005",
3699
+ working_branch=branch,
3700
+ )
3701
+
3702
+ assert result.ok is False
3703
+ assert result.reason == "runtime_wip_unresolved_merge"
3704
+ assert subprocess.run(
3705
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3706
+ ).stdout.strip() == wip_head
3707
+ assert subprocess.run(
3708
+ ["git", "ls-files", "-u"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3709
+ ).stdout.strip()
3710
+
3711
+
3712
+ def test_restore_runtime_wip_rejects_exact_merge_commit_identity(tmp_path):
3713
+ from prizmkit_runtime.gitops import restore_runtime_wip
3714
+
3715
+ _init_merge_repo(tmp_path)
3716
+ subprocess.run(["git", "checkout", "-b", "wip-side"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3717
+ (tmp_path / "side.txt").write_text("side\n", encoding="utf-8")
3718
+ subprocess.run(["git", "add", "side.txt"], cwd=tmp_path, check=True)
3719
+ subprocess.run(["git", "commit", "-m", "side commit"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3720
+ subprocess.run(["git", "checkout", "main"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3721
+ branch = "dev/F-005-merge-wip"
3722
+ subprocess.run(["git", "checkout", "-b", branch], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3723
+ (tmp_path / "app.txt").write_text("task side\n", encoding="utf-8")
3724
+ subprocess.run(["git", "commit", "-am", "task commit"], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3725
+ subprocess.run(
3726
+ [
3727
+ "git",
3728
+ "merge",
3729
+ "--no-ff",
3730
+ "wip-side",
3731
+ "-m",
3732
+ "wip(F-005): preserve feature failed state",
3733
+ "-m",
3734
+ "Pipeline preserved task branch work without merging it to the base branch.",
3735
+ ],
3736
+ cwd=tmp_path,
3737
+ check=True,
3738
+ stdout=subprocess.DEVNULL,
3739
+ )
3740
+ head = subprocess.run(
3741
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3742
+ ).stdout.strip()
3743
+
3744
+ result = restore_runtime_wip(
3745
+ tmp_path,
3746
+ family_kind="feature",
3747
+ item_id="F-005",
3748
+ working_branch=branch,
3749
+ )
3750
+
3751
+ assert result.ok is False
3752
+ assert result.reason == "runtime_wip_parent_invalid"
3753
+ assert subprocess.run(
3754
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3755
+ ).stdout.strip() == head
3756
+
3757
+
3758
+ def test_restore_runtime_wip_rolls_back_tip_when_postcondition_fails(monkeypatch, tmp_path):
3759
+ from prizmkit_runtime import gitops
3760
+
3761
+ _init_merge_repo(tmp_path)
3762
+ branch = "dev/F-005-rollback"
3763
+ subprocess.run(["git", "checkout", "-b", branch], cwd=tmp_path, check=True, stdout=subprocess.DEVNULL)
3764
+ (tmp_path / "app.txt").write_text("preserved\n", encoding="utf-8")
3765
+ wip_head = _commit_runtime_wip(
3766
+ tmp_path,
3767
+ "wip(F-005): preserve feature failed state",
3768
+ "Pipeline preserved task branch work without merging it to the base branch.",
3769
+ )
3770
+ monkeypatch.setattr(
3771
+ gitops,
3772
+ "visible_task_paths",
3773
+ lambda _root: (
3774
+ (),
3775
+ gitops.GitCommandResult(("status",), 0, "", ""),
3776
+ ),
3777
+ )
3778
+
3779
+ result = gitops.restore_runtime_wip(
3780
+ tmp_path,
3781
+ family_kind="feature",
3782
+ item_id="F-005",
3783
+ working_branch=branch,
3784
+ )
3785
+
3786
+ assert result.ok is False
3787
+ assert result.reason == "runtime_wip_restore_verification_failed"
3788
+ assert result.restored_head == wip_head
3789
+ assert subprocess.run(
3790
+ ["git", "rev-parse", "HEAD"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3791
+ ).stdout.strip() == wip_head
3792
+ assert subprocess.run(
3793
+ ["git", "status", "--porcelain"], cwd=tmp_path, check=True, stdout=subprocess.PIPE, text=True,
3794
+ ).stdout == ""
3795
+ assert (tmp_path / "app.txt").read_text(encoding="utf-8") == "preserved\n"
3796
+
3797
+
3376
3798
  def test_branch_merge_preserves_preexisting_stash_when_workspace_is_clean(tmp_path):
3377
3799
  from prizmkit_runtime.gitops import BranchContext, branch_merge_plan, run_git_plan
3378
3800
 
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.1.169",
2
+ "version": "1.1.170",
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.",
@@ -30,14 +30,14 @@ Do not use it for unrelated application implementation, general server administr
30
30
 
31
31
  Explicit deploy invocation authorizes the standard deployment envelope: project reads, build/package, project-declared dependency resolution, non-destructive native migration, candidate creation, start/restart, live handoff, minimum verification, bounded retry, exact old-release retirement, failed-candidate/temporary-resource cleanup, and the selected Profile record update.
32
32
 
33
- Do not ask for a second complete-plan confirmation for those standard actions. Pause only when the next action requires:
33
+ Do not ask for a second complete-plan confirmation for those standard actions. Before returning `WAITING_USER`, exhaust bounded read-only discovery, unambiguous target resolution, and already configured non-interactive authentication. Pause only when no safe automatic continuation remains and the next action requires:
34
34
 
35
- 1. an identity or authentication action such as login, MFA, or browser approval;
36
- 2. a target choice that current evidence cannot resolve;
35
+ 1. an identity or authentication action only the user can complete after established credentials have been tried;
36
+ 2. a target choice that remains absent, conflicting, or ambiguous after current evidence is inspected;
37
37
  3. an irreversible or insufficiently bounded data effect;
38
38
  4. a shared or unknown-ownership resource decision.
39
39
 
40
- A missing rollback mechanism is disclosed but is not a separate confirmation. Privileged or global work outside the Profile's already established target boundary is an authorization/ownership decision and pauses before execution.
40
+ A missing Profile record, ordinary first deployment, selected-target SSH connection, known bounded downtime, material work inside the standard envelope, or missing rollback mechanism does not create a confirmation. Disclose relevant effects while continuing. Privileged or global work outside the Profile's already established target boundary is an authorization/ownership decision and pauses before execution.
41
41
 
42
42
  ## Managed Artifacts
43
43
 
@@ -48,7 +48,7 @@ Prefer project-native deployment configuration. PrizmKit owns only:
48
48
  | `prizmkit.deploy.json` | Optional version-controlled non-sensitive declaration index for Profile hints and policy |
49
49
  | `.prizmkit/deploy/profiles/<profile-id>.json` | One local non-sensitive current/result/recovery record per stable Profile |
50
50
 
51
- A Profile record is absent means this is the first PrizmKit-managed deployment for that location. Ask once where to deploy, derive a stable lowercase Profile ID, and then inspect the chosen target. Absence does not prove the target is empty; adopt observed current state instead of creating a duplicate deployment.
51
+ A missing Profile record means only that PrizmKit has not recorded this location. Resolve a provisional target from the explicit request, valid declaration and referenced native configuration, or one unambiguous project-native/SSH target, then inspect it directly and derive the stable lowercase Profile ID. Do not pause merely because the record is absent or the target came from a valid declared default. Ask one target question only when no location resolves, multiple candidates remain, or target evidence conflicts. Absence never proves the target is empty; adopt observed current state instead of creating a duplicate deployment.
52
52
 
53
53
  Keep actual IP addresses, URLs, credentials, and dynamic endpoints out of Profile IDs and filenames. Use non-sensitive target references and fingerprints inside the managed objects. File count grows only with declared Profiles, never with deployments, releases, phases, capabilities, history entries, or recovery events.
54
54
 
@@ -58,14 +58,22 @@ When legacy `.prizmkit/deploy/` evidence exists, read `${SKILL_DIR}/references/l
58
58
 
59
59
  Secret values stay in user- or target-owned Secret systems. Managed artifacts contain only names, external source references, and presence states. Never persist raw command output or full logs.
60
60
 
61
+ ## Remote Connection Default
62
+
63
+ For a Profile whose selected target is a directly managed remote machine, use the installed `ssh` command as the default transport for discovery, deployment, operations, and verification. SSH implements the semantic `connect` capability; it is not a Profile type or a provider/tool route. Prefer an observed or user-supplied SSH config alias and reuse its user, port, proxy, agent/key, and host-verification settings. Run bounded non-interactive remote commands instead of opening an unmanaged interactive shell when the action permits it.
64
+
65
+ For a resolved remote destination, attempt one bounded non-interactive SSH probe with the established config, agent/key, proxy, and host-key evidence before asking about authentication. A successful probe continues directly into observation and deployment. Do not ask the user to confirm credentials that already work. If the destination is still incomplete, ask one target question for the config alias or destination and any non-default port; do not guess the host, user, port, private-key path, or bastion. Connecting to the selected target is part of explicit deploy authority. Pause only when the probe proves a user-only authentication action is required or target identity cannot be established. Preserve host-key verification, and treat an unknown or changed key without trusted fingerprint evidence as an identity decision rather than bypassing the check.
66
+
67
+ This default does not override stronger current evidence. Use the project-native target/control-plane path when the target is local, exposes no host shell, or declares a different authoritative deployment transport. A transfer action may use an available SSH-backed transfer executable while preserving the same verified destination and authentication boundary.
68
+
61
69
  ## AutoDeploy Workflow
62
70
 
63
71
  ### 1. Select Profile
64
72
 
65
- 1. Resolve a candidate from the explicitly requested Profile, a valid declared default, or the sole known Profile.
66
- 2. If that candidate has no Profile record, treat the operation as its first PrizmKit deployment and ask once to confirm where to deploy; a declaration hint may propose the location but cannot skip this confirmation.
67
- 3. If no candidate exists, ask once where to deploy and derive the stable Profile identity from that decision.
68
- 4. If multiple Profiles remain possible, ask one target question rather than guessing from environment names.
73
+ 1. Resolve a candidate from the explicitly requested Profile, a valid declared default, the sole known Profile, or one unambiguous project-native deployment target.
74
+ 2. If that candidate has no Profile record but its location resolves from the request, valid declaration/native configuration, or one matching SSH target, inspect it directly and derive the stable Profile identity without confirmation.
75
+ 3. If no named candidate exists but current evidence identifies exactly one target, adopt it provisionally and inspect it before writing a Profile record.
76
+ 4. Ask one target question only when no target resolves, multiple candidates remain, or evidence conflicts; never ask merely because this is the first deployment.
69
77
 
70
78
  Different Profiles may operate independently. When the same Profile already has recoverable work, attach to or resume it instead of creating a second candidate.
71
79
 
@@ -80,7 +88,7 @@ Read only the project-native files and target observations needed to establish:
80
88
  - project-native reports or immutable artifacts that can be reused;
81
89
  - selected commands and material child effects through an executable, target-native, or human boundary.
82
90
 
83
- Current target and project-native control-plane evidence outrank the local Profile summary. Reconcile drift from observed state. Do not expose Secret values or substitute conventional ports/endpoints for observed configuration.
91
+ Resolve the connection path through the Remote Connection Default before deriving remote actions. Current target and project-native control-plane evidence outrank the local Profile summary. Reconcile drift from observed state. Do not expose Secret values or substitute conventional ports/endpoints for observed configuration.
84
92
 
85
93
  Read `${SKILL_DIR}/references/capability-contract.md` when selecting or deriving an action.
86
94
 
@@ -27,6 +27,14 @@ Lower evidence may identify what to inspect but cannot override current direct o
27
27
 
28
28
  A maintained recipe is reusable only while its project, tool, target, artifact, command, health, ownership, resource, and cleanup fingerprint matches. Otherwise derive the action from current project evidence, real capability evidence, and applicable official documentation. A product name or remembered command is never enough for a write.
29
29
 
30
+ ## Direct Remote-Machine Transport
31
+
32
+ When the selected target is a directly managed remote machine with shell access, choose the installed `ssh` executable as the default implementation of `connect`. Derive its destination and options from current project-native evidence, an observed or user-supplied SSH config alias, or the confirmed target decision. Do not derive connection details from a Profile/environment name, and do not guess a host, user, port, key path, or jump host.
33
+
34
+ Build the connection action as an executable plus separate arguments and prefer an exact bounded remote command, for example the semantic shape `ssh <destination> <remote-command>`, over an unmanaged interactive session. Reuse the established SSH config, authentication agent/key reference, proxy path, and host-key verification. Once the destination resolves, run one bounded non-interactive probe before concluding that authentication requires the user; successful established credentials authorize immediate observation and continuation. An SSH-backed transfer executable is eligible only when installed capability proves it and it preserves the same destination, identity, and effect boundary.
35
+
36
+ SSH is a transport default, not a protocol route. Do not force it onto a local target, an API/control-plane-only target, or a project whose authoritative native deployment path provides no host shell. Do not disable or silently bypass host-key verification. A first-seen or changed key without trusted fingerprint evidence is a target-identity conflict. Create a Human Checkpoint for login, MFA, key enrollment, or another authentication action only after current non-interactive methods cannot complete it.
37
+
30
38
  ## Base Action Contract
31
39
 
32
40
  Every selected automatic or human action contains only these base facts:
@@ -41,7 +49,7 @@ Every selected automatic or human action contains only these base facts:
41
49
 
42
50
  Keep executable and arguments separate where possible. Use project-relative working directories and inject Secret material through user- or target-owned systems. Never interpolate an untrusted value into an opaque shell command.
43
51
 
44
- An action is automatic when current evidence proves its executable shape, target, effects, ownership, bounded resource behavior, and verification inside the standard deployment envelope. When a person must authenticate, choose a target, decide an irreversible data effect, or resolve shared ownership, represent one exact human action and expected postcondition. When no safe action can be established, report the missing evidence or unsupported capability instead of fabricating a command.
52
+ An action is automatic when current evidence proves its executable shape, target, effects, ownership, bounded resource behavior, and verification inside the standard deployment envelope. Before creating a Human Checkpoint, perform bounded read-only discovery, resolve any single evidence-backed target, and try established non-interactive authentication. Only when a person must still authenticate, choose among unresolved targets, decide an irreversible data effect, or resolve shared ownership, represent one exact human action and expected postcondition. When no safe action can be established, report the missing evidence or unsupported capability instead of fabricating a command.
45
53
 
46
54
  Evidence derivation basis such as maintained recipe or current dynamic derivation is internal provenance, not a user-visible deployment status and not a risk classification.
47
55
 
@@ -53,7 +61,7 @@ Attach a Gate only when its condition applies:
53
61
  - **Supersession Gate:** an existing live/candidate/rollback deployment may be replaced, retained, or retired.
54
62
  - **Data Gate:** migration or another persistent-data effect occurs.
55
63
  - **Shared Resource Gate:** another workload may consume the resource or ownership is uncertain.
56
- - **Human Checkpoint:** identity, authentication, target choice, irreversible data, or shared ownership requires the user.
64
+ - **Human Checkpoint:** unresolved identity/authentication/target choice after bounded automatic attempts, irreversible data, or shared ownership requires the user.
57
65
  - **Unknown Outcome Gate:** a write may have happened but its result is not proven.
58
66
 
59
67
  The applicable Gate owns its additional facts and policy. Do not add supersession to status/log actions, data analysis to a build without data effects, or a human checkpoint to an ordinary authorized write.
@@ -68,7 +76,7 @@ Read-only status, health, history, or bounded logs do not require expansion of u
68
76
 
69
77
  ## Release and Profile Evidence
70
78
 
71
- Bind every action to one selected Profile, target fingerprint, and desired release when deployment is involved. Actual target state outranks a stale Profile summary. A missing Profile record means no PrizmKit-managed state exists; after the user identifies the target, inspect it before assuming a first physical deployment.
79
+ Bind every action to one selected Profile, target fingerprint, and desired release when deployment is involved. Actual target state outranks a stale Profile summary. A missing Profile record means no PrizmKit-managed state exists, not that target confirmation is required. Use an explicit request, valid declared default/native configuration, or one unambiguous project-native/SSH target as a provisional locator, inspect it directly, and ask only when no unique non-conflicting target can be resolved. Never assume a first physical deployment.
72
80
 
73
81
  Prefer an immutable project-native artifact. When test, staging, and production policies allow the same artifact, preserve its identity across Profiles rather than rebuilding. If no artifact mechanism exists, use the current committed revision unless the user separately asks to create a reproducible release from other source state.
74
82
 
@@ -10,14 +10,16 @@ An explicit deploy invocation authorizes the selected Profile's standard deploym
10
10
 
11
11
  The standard envelope covers project-owned, bounded actions needed to build/package, resolve project-declared dependencies, apply non-destructive native migrations, create a candidate, start/restart, hand off live traffic, verify, retain bounded rollback, retire exact old runtime resources, clean failed/temporary resources, and update the selected Profile record.
12
12
 
13
- Pause with one exact `WAITING_USER` action only for:
13
+ For a selected directly managed remote machine, connecting and running bounded project-scoped actions through the established SSH destination are part of that standard envelope. Do not ask for another confirmation merely because the next executable is `ssh`; use established non-interactive credentials first. A missing Profile record or ordinary first deployment also does not create a checkpoint when one non-conflicting target resolves from current evidence.
14
14
 
15
- 1. an identity or authentication action that only the user can complete;
16
- 2. a target choice current evidence cannot resolve;
15
+ Exhaust bounded automatic discovery, target resolution, and configured non-interactive authentication before pausing with one exact `WAITING_USER` action. Pause only for:
16
+
17
+ 1. an identity or authentication action that only the user can complete after established methods have been attempted;
18
+ 2. a target choice still absent, ambiguous, or conflicting after current evidence is inspected;
17
19
  3. an irreversible data effect or data impact that cannot be bounded safely;
18
20
  4. a shared or unknown-ownership resource decision.
19
21
 
20
- A missing reliable rollback is disclosed but does not create another approval. Privileged/global work not already established by the selected target boundary is treated as an authorization or shared-ownership decision rather than silently executed.
22
+ Known bounded downtime, material work inside the standard envelope, and missing reliable rollback are disclosed while execution continues; they do not create another approval. Privileged/global work not already established by the selected target boundary is treated as an authorization or shared-ownership decision rather than silently executed.
21
23
 
22
24
  ## Effect and Resource Policy
23
25
 
@@ -35,6 +37,12 @@ A material budget covers aggregate attempts rather than resetting per retry. Est
35
37
 
36
38
  Do not run a material producer when current project-native evidence already covers the same source/release, toolchain, target assumptions, and required scope. Run the least expensive missing producer at most once for that binding. A changed binding starts a newly observed current→desired decision; it does not justify automatic repeated full rings.
37
39
 
40
+ ## SSH Execution Boundary
41
+
42
+ For each selected SSH action, preserve the verified destination, authentication identity, proxy path, host-key evidence, and project-owned working boundary used during discovery. Execute the smallest exact remote command needed for the current difference, with bounded connection/action time and output. Reuse one proven connection binding across observation, transfer, write, and verification instead of silently changing users or endpoints between steps.
43
+
44
+ Do not pass Secret values in command arguments, print private-key material, start a broad remote inventory, or bypass host-key verification. Attempt one bounded non-interactive connection with the established SSH configuration before deciding authentication cannot complete; continue immediately when it succeeds. Only then return one exact `WAITING_USER` authentication action when user input is unavoidable. If the target key or destination differs from established evidence, treat it as an identity conflict rather than a transient retry. After a disconnect during a possible write, use the same verified SSH destination to inspect actual state before considering replay.
45
+
38
46
  ## Current → Desired Loop
39
47
 
40
48
  For one selected Profile:
@@ -90,9 +90,11 @@ After timeout, disconnect, or interruption during a possible write:
90
90
 
91
91
  Never infer “not applied” from a missing response. Never rerun a material producer merely to reconstruct history.
92
92
 
93
+ For a directly managed remote machine, reconnect through the same verified SSH destination and authentication identity used for the action. A successful SSH connection proves access only; it does not prove that the desired release, runtime, selector, health, or cleanup postconditions succeeded. An unexpected host key or destination is an identity conflict, not evidence that the write was unapplied.
94
+
93
95
  ## Interruption and Resume
94
96
 
95
- Load only the selected Profile record's current, latest result, minimal recovery, and bounded observations. Then rediscover project revision, target fingerprint, authentication identity, desired release eligibility, actual live/candidate inventory, selector, owned residuals, configured health, and relevant tool capability.
97
+ Load only the selected Profile record's current, latest result, minimal recovery, and bounded observations. Then rediscover project revision, target fingerprint, connection transport and destination, authentication identity, desired release eligibility, actual live/candidate inventory, selector, owned residuals, configured health, and relevant tool capability. For a directly managed remote machine, re-establish the same verified SSH binding before inspecting or resuming target actions.
96
98
 
97
99
  Resume from the first unproven current→desired action. Do not reconstruct commands from history summaries. When observed identity/effects differ, discard the stale proposed action and derive the next action from current evidence. If another operation already targets the same Profile/desired release, attach to it rather than creating a candidate.
98
100
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "prizmkit",
3
- "version": "1.1.169",
3
+ "version": "1.1.170",
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": {