prizmkit 1.1.167 → 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.
@@ -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.167",
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,24 +48,32 @@ 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
 
55
- Validate a declaration with `${SKILL_DIR}/references/deployment-declaration-schema.json` and a Profile record with `${SKILL_DIR}/references/deploy-record-schema.json`, then run `python3 ${SKILL_DIR}/scripts/validate-deploy-artifact.py --kind <declaration|record> <path>`. Use managed fields only when both validations pass. Profile record writes are part of the standard deploy envelope; modifying the optional version-controlled declaration remains an explicit project-file request.
55
+ Validate either managed artifact through one read-only entry point: `python3 ${SKILL_DIR}/scripts/validate-deploy-artifact.py --kind <declaration|record> <path>`. It loads the matching shipped JSON Schema, applies structural and semantic checks, and for a Profile record requires `<path>` to end in `<profile.id>.json`. Use managed fields only when this command passes. On failure preserve the rejected candidate and actual target state; never replay or roll back deployment work merely to repair a record. Profile record writes are part of the standard deploy envelope; modifying the optional version-controlled declaration remains an explicit project-file request.
56
56
 
57
57
  When legacy `.prizmkit/deploy/` evidence exists, read `${SKILL_DIR}/references/legacy-migration.md`. Preserve uncertain evidence and stop legacy writers.
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
 
@@ -153,7 +161,7 @@ Load only the branch needed now:
153
161
  - action derivation or evidence conflict → `${SKILL_DIR}/references/capability-contract.md`
154
162
  - write, material work, migration, redeploy, dependency, promotion, or automation setup → `${SKILL_DIR}/references/policy-and-execution.md`
155
163
  - success cannot be established directly, or failure, unknown outcome, rollback, interruption, or resume applies → `${SKILL_DIR}/references/verification-and-recovery.md`
156
- - Profile record read/write → `${SKILL_DIR}/references/deploy-record-schema.json` and the semantic validator
157
- - declaration read/write → `${SKILL_DIR}/references/deployment-declaration-schema.json` and the semantic validator
164
+ - Profile record read/write → `${SKILL_DIR}/references/deploy-record-schema.json` through the single artifact validator
165
+ - declaration read/write → `${SKILL_DIR}/references/deployment-declaration-schema.json` through the single artifact validator
158
166
  - existing legacy evidence → `${SKILL_DIR}/references/legacy-migration.md`
159
167
  - an explicitly requested real external-resource test rather than an ordinary selected-Profile deployment → `${SKILL_DIR}/references/real-resource-test-policy.md`
@@ -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
 
@@ -37,7 +37,7 @@ Do not execute a legacy command or continue a legacy filename pattern. Local Sec
37
37
  - minimal still-relevant recovery.
38
38
  4. Do not create “already deployed” records for other legacy profile hints merely because they were listed in the old global record.
39
39
  5. When current Profile identity is absent, duplicated, unsafe for the lowercase Profile filename contract, or conflicts with target evidence, do not guess. Preserve the old record and ask for one Profile/target decision only when deployment continuation needs it.
40
- 6. Validate the complete v2 candidate with the Profile schema and semantic validator before writing it. A deploy invocation authorizes this selected-Profile local state conversion; it never authorizes deletion of old evidence.
40
+ 6. Name the complete v2 candidate `<profile.id>.json` and pass it through the single artifact validator, which loads the Profile schema and applies structural, semantic, and filename-identity checks before writing it. A deploy invocation authorizes this selected-Profile local state conversion; it never authorizes deletion of old evidence.
41
41
 
42
42
  A schema-v1 `latest_result` may use BLOCKED or CANCELLED. Map it only when current evidence proves the semantic outcome:
43
43