prizmkit 1.1.176 → 1.1.177

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.176",
3
- "bundledAt": "2026-08-11T07:08:48.540Z",
4
- "bundledFrom": "529c4ac"
2
+ "frameworkVersion": "1.1.177",
3
+ "bundledAt": "2026-08-14T15:01:11.231Z",
4
+ "bundledFrom": "99ed585"
5
5
  }
@@ -1072,7 +1072,7 @@ def _finalize_prepared_runtime_commit(
1072
1072
  execution_root: Path,
1073
1073
  prompt: PromptGenerationResult,
1074
1074
  ) -> RuntimeCommitResult:
1075
- """Execute a prepared commit only when the checkpoint proves readiness."""
1075
+ """Let Runtime adopt and execute an eligible prepared commit request."""
1076
1076
  checkpoint = prompt.checkpoint_path
1077
1077
  artifact = prompt.artifact_path
1078
1078
  if checkpoint is None or artifact is None or not checkpoint.is_file():
@@ -1082,7 +1082,7 @@ def _finalize_prepared_runtime_commit(
1082
1082
  state = load_checkpoint_state(checkpoint, project_root=execution_root)
1083
1083
  request_path = artifact / REQUEST_FILENAME
1084
1084
  cleanup_recovery = state.semantic_complete and request_path.is_file()
1085
- if not state.semantic_commit_ready and not cleanup_recovery:
1085
+ if not state.semantic_commit_ready and not cleanup_recovery and not request_path.is_file():
1086
1086
  return RuntimeCommitResult("not_ready", "checkpoint_not_commit_ready")
1087
1087
  result = finalize_runtime_commit(
1088
1088
  execution_root,
@@ -2,6 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ import copy
5
6
  import json
6
7
  import os
7
8
  import re
@@ -92,7 +93,16 @@ def finalize_runtime_commit(
92
93
  if not state.valid:
93
94
  return RuntimeCommitResult("failed", f"invalid_checkpoint:{state.error_code}")
94
95
  if not state.semantic_commit_ready and not state.semantic_complete:
95
- return RuntimeCommitResult("not_ready", "checkpoint_not_commit_ready")
96
+ prepared = prepare_runtime_commit_handoff(
97
+ root,
98
+ artifact_dir=artifact,
99
+ checkpoint_path=checkpoint,
100
+ )
101
+ if prepared.status != "ready":
102
+ return prepared
103
+ state = load_checkpoint_state(checkpoint, project_root=root)
104
+ if not state.semantic_commit_ready:
105
+ return RuntimeCommitResult("failed", "checkpoint_not_commit_ready_after_runtime_prepare")
96
106
 
97
107
  request_path = artifact / REQUEST_FILENAME
98
108
  request, error = _load_request(request_path, root, artifact)
@@ -214,6 +224,99 @@ def finalize_runtime_commit(
214
224
  return RuntimeCommitResult("committed", "runtime_commit_completed", head, recovered)
215
225
 
216
226
 
227
+ def prepare_runtime_commit_handoff(
228
+ project_root: Path,
229
+ *,
230
+ artifact_dir: Path,
231
+ checkpoint_path: Path,
232
+ ) -> RuntimeCommitResult:
233
+ """Atomically publish COMMIT_PENDING for one valid Runtime request.
234
+
235
+ The AI session owns request creation but not Runtime readiness. Existing
236
+ COMMIT_PENDING checkpoints remain idempotently ready; blocked or otherwise
237
+ ineligible checkpoints are never rewritten by this transition.
238
+ """
239
+ try:
240
+ root = project_root.resolve()
241
+ artifact = artifact_dir.resolve()
242
+ checkpoint = checkpoint_path.resolve()
243
+ except (OSError, RuntimeError):
244
+ return RuntimeCommitResult("failed", "unsafe_artifact_identity")
245
+ if not _within(artifact, root) or not _within(checkpoint, artifact):
246
+ return RuntimeCommitResult("failed", "unsafe_artifact_identity")
247
+
248
+ state = load_checkpoint_state(checkpoint, project_root=root)
249
+ if not state.valid:
250
+ return RuntimeCommitResult("failed", f"invalid_checkpoint:{state.error_code}")
251
+ if state.semantic_complete:
252
+ return RuntimeCommitResult("not_ready", "runtime_commit_already_finalized")
253
+ if state.semantic_commit_ready:
254
+ return RuntimeCommitResult("ready", "runtime_commit_handoff_already_prepared")
255
+ if state.semantic_blocked:
256
+ return RuntimeCommitResult("not_ready", "workflow_checkpoint_blocked")
257
+
258
+ request, error = _load_request(artifact / REQUEST_FILENAME, root, artifact)
259
+ if request is None:
260
+ return RuntimeCommitResult("failed", error or "invalid_commit_request")
261
+ if request.runtime_commit_hash:
262
+ return RuntimeCommitResult("failed", "premature_runtime_commit_hash")
263
+ current_head = _git(root, "rev-parse", "HEAD")
264
+ if current_head.return_code != 0:
265
+ return RuntimeCommitResult("failed", "git_head_unavailable")
266
+ if current_head.stdout.strip().lower() != request.base_head.lower():
267
+ return RuntimeCommitResult("failed", "base_head_mismatch")
268
+
269
+ data = copy.deepcopy(state.raw_data)
270
+ if not isinstance(data, dict):
271
+ return RuntimeCommitResult("failed", "checkpoint_runtime_prepare_rejected")
272
+ raw_steps = data.get("steps")
273
+ if not isinstance(raw_steps, list):
274
+ return RuntimeCommitResult("failed", "checkpoint_runtime_prepare_rejected")
275
+ committers = [
276
+ step for step in raw_steps
277
+ if isinstance(step, dict) and step.get("skill") == "prizmkit-committer"
278
+ ]
279
+ if len(committers) != 1:
280
+ return RuntimeCommitResult("failed", "checkpoint_runtime_prepare_rejected")
281
+ committer = committers[0]
282
+ if committer.get("status") != "in_progress" or committer.get("stage_result") not in {None, ""}:
283
+ return RuntimeCommitResult("not_ready", "checkpoint_not_runtime_handoff_candidate")
284
+ committer["stage_result"] = "COMMIT_PENDING"
285
+
286
+ state_key = semantic_state_key(str(data.get("workflow_type") or ""))
287
+ semantic = data.get(state_key)
288
+ if not isinstance(semantic, dict) or semantic.get("terminal_status") is not None:
289
+ return RuntimeCommitResult("not_ready", "checkpoint_not_runtime_handoff_candidate")
290
+ semantic.update(
291
+ {
292
+ "schema_version": 1,
293
+ "orchestrator": "pipeline-runtime",
294
+ "stage": "committer",
295
+ "status": "in_progress",
296
+ "stage_result": "COMMIT_PENDING",
297
+ "current_stage": "prizmkit-committer",
298
+ "next_stage": "prizmkit-committer",
299
+ "resume_from": None,
300
+ "blocked_reason": None,
301
+ "terminal_status": None,
302
+ }
303
+ )
304
+ candidate = validate_checkpoint_data(
305
+ data,
306
+ path=checkpoint,
307
+ exists=True,
308
+ project_root=root,
309
+ )
310
+ if not candidate.valid or not candidate.semantic_commit_ready:
311
+ return RuntimeCommitResult("failed", "checkpoint_runtime_prepare_rejected")
312
+ if _write_json_atomic(checkpoint, data):
313
+ return RuntimeCommitResult("failed", "checkpoint_runtime_prepare_failed")
314
+ prepared = load_checkpoint_state(checkpoint, project_root=root)
315
+ if not prepared.semantic_commit_ready:
316
+ return RuntimeCommitResult("failed", "checkpoint_not_commit_ready_after_runtime_prepare")
317
+ return RuntimeCommitResult("ready", "runtime_commit_handoff_prepared")
318
+
319
+
217
320
  def finalize_accepted_workspace_commit(
218
321
  project_root: Path,
219
322
  *,
@@ -841,8 +841,6 @@ def assemble_sections(sections_dir, init_done, browser_enabled,
841
841
  load_section(sections_dir, "context-budget-rules.md")))
842
842
  sections.append(("directory-convention",
843
843
  load_section(sections_dir, "directory-convention-full.md")))
844
- sections.append(("timeout-recovery",
845
- load_section(sections_dir, "subagent-timeout-recovery.md")))
846
844
  sections.append(("artifact-manifest",
847
845
  load_section(sections_dir, "artifact-manifest.md")))
848
846
 
@@ -269,6 +269,24 @@ def _checkpoint_project_root(checkpoint_path):
269
269
  return str(path.parent)
270
270
 
271
271
 
272
+ def _declared_runtime_request_exists(checkpoint_path, step):
273
+ """Return whether the committer's exact declared Runtime request exists."""
274
+ if step.get("skill") != "prizmkit-committer":
275
+ return False
276
+ project_root = Path(_checkpoint_project_root(checkpoint_path)).resolve()
277
+ for artifact in step.get("required_artifacts") or ():
278
+ if not isinstance(artifact, str) or not artifact.endswith("/runtime-commit-request.json"):
279
+ continue
280
+ candidate = (project_root / artifact).resolve()
281
+ try:
282
+ candidate.relative_to(project_root)
283
+ except ValueError:
284
+ continue
285
+ if candidate.is_file():
286
+ return True
287
+ return False
288
+
289
+
272
290
  def _finalize_semantics(checkpoint_path, data, state_key):
273
291
  """Derive a deterministic terminal status after an atomic mutation."""
274
292
  candidate = validate_checkpoint_data(
@@ -345,16 +363,24 @@ def update_checkpoint(
345
363
  return {"ok": False, "error": verdict_error}
346
364
 
347
365
  semantic_update = _normalize_semantic_update(semantic_update)
348
- if semantic_update.get("stage_result") == "COMMITTED":
366
+ if semantic_update.get("stage_result") in {"COMMIT_PENDING", "COMMITTED"}:
349
367
  return {
350
368
  "ok": False,
351
- "error": "COMMITTED is Runtime-owned and cannot be written by the Prompt checkpoint helper",
369
+ "error": "COMMIT_PENDING and COMMITTED are Runtime-owned and cannot be written by the Prompt checkpoint helper",
352
370
  }
353
371
  semantic_error = _validate_semantic_update(step, semantic_update)
354
372
  if semantic_error:
355
373
  return {"ok": False, "error": semantic_error}
356
374
 
357
375
  stage_result = semantic_update.get("stage_result")
376
+ if stage_result == "COMMIT_BLOCKED" and _declared_runtime_request_exists(checkpoint_path, step):
377
+ return {
378
+ "ok": False,
379
+ "error": (
380
+ "A Runtime commit request already exists; the Prompt checkpoint helper cannot "
381
+ "downgrade the committer to COMMIT_BLOCKED. Stop and let Python Runtime validate the handoff."
382
+ ),
383
+ }
358
384
  if new_status == "completed" and step.get("skill") == "prizmkit-code-review":
359
385
  stage_result = stage_result or step.get("stage_result")
360
386
  if stage_result != "REVIEW_PASS":
@@ -434,13 +460,15 @@ def update_checkpoint(
434
460
  if err:
435
461
  return {"ok": False, "error": err}
436
462
 
463
+ prompt_semantic = dict(final_state.semantic_snapshot)
464
+ prompt_semantic.pop("commit_ready", None)
437
465
  return {
438
466
  "ok": True,
439
467
  "step_id": step.get("id"),
440
468
  "skill": step.get("skill"),
441
469
  "old_status": old_status,
442
470
  "new_status": new_status,
443
- "semantic": final_state.semantic_snapshot,
471
+ "semantic": prompt_semantic,
444
472
  }
445
473
 
446
474
 
@@ -38,7 +38,7 @@ Complete the feature in headless non-interactive mode using the active atomic sk
38
38
  5. Invoke `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`. Validate its report/result pair. For `TEST_NEEDS_FIXES`, classify the concrete correction into an allowed `repair_scope`; unknown/unsafe scope blocks, while a safe in-budget route re-enters Implement and requires fresh Review, configured verification, and Test. Do not duplicate the Skill's internal repair loop.
39
39
  6. Write `completion-summary.json` before retrospective and commit preparation.
40
40
  7. Invoke `/prizmkit-retrospective` with the exact artifact root, non-`.prizmkit/` `change_paths`, and `change_summary`; validate `outcome=RETRO_COMPLETE`.
41
- 8. Before commit preparation, validate the complete Git-visible workspace regardless of when or where each correct change originated. Final Review/Test authority must cover every behavior-affecting visible change; ignored paths remain local, while merge conflicts, Secrets, sensitive content, stale evidence, and known incorrect or unverifiable content block. After validating every required artifact, invoke `/prizmkit-committer operation=prepare-runtime-commit artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/ evidence_paths=<exact paths> request_path=.prizmkit/specs/{{FEATURE_SLUG}}/runtime-commit-request.json`. Require a schema-v2 pathless request and `COMMIT_REQUEST_READY`; this session then records `COMMIT_PENDING` and stops. The Python runtime re-enumerates and commits the complete non-ignored workspace with only exact causal request/checkpoint bookkeeping omitted.
41
+ 8. Before commit preparation, validate the complete Git-visible workspace regardless of when or where each correct change originated. Final Review/Test authority must cover every behavior-affecting visible change; ignored paths remain local, while merge conflicts, Secrets, sensitive content, stale evidence, and known incorrect or unverifiable content block. After validating every required artifact, invoke `/prizmkit-committer operation=prepare-runtime-commit artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/ evidence_paths=<exact paths> request_path=.prizmkit/specs/{{FEATURE_SLUG}}/runtime-commit-request.json`. Require a schema-v2 pathless request and `COMMIT_REQUEST_READY`, then stop without another committer checkpoint update or request validator. The Python Runtime validates the request, publishes commit readiness, and commits the complete non-ignored workspace with only exact causal request/checkpoint bookkeeping omitted.
42
42
 
43
43
  ## Failure Capture
44
44
 
@@ -85,14 +85,6 @@ This is a finite, headless, non-interactive session. Preserve correctness first,
85
85
 
86
86
  ---
87
87
 
88
- ## Execution-Unit Timeout Recovery
89
-
90
- If an execution unit times out:
91
- 1. `{{RUNTIME_HELPER_CMD}} artifact list .prizmkit/specs/{{FEATURE_SLUG}}` — check what exists
92
- 2. If `context-snapshot.md` exists, use it for recovery navigation together with the current diff and the smallest relevant current-source reads. Continue only the remaining steps under the owning skill's execution budget.
93
- 3. Apply the owning skill or runtime contract for retry, native continuation, strict downgrade, or Main-Agent fallback. Do not create an unapproved replacement execution unit.
94
- 4. Do not poll indefinitely after the owning contract's retry budget is exhausted; write `failure-log.md` with the timeout and last observable state when recovery is blocked.
95
-
96
88
  ## Execution
97
89
 
98
90
  {{IF_INIT_NEEDED}}
@@ -450,7 +442,7 @@ Invoke `/prizmkit-retrospective` with the exact artifact root, exact non-`.prizm
450
442
 
451
443
  Before commit preparation, validate the complete Git-visible workspace regardless of when or where each correct change originated. Code Review and Test authority must cover every behavior-affecting visible change. Ignored paths remain naturally absent; merge conflicts, Secrets, sensitive content, stale evidence, and known incorrect or unverifiable content block. Never force-add or change/interpret project ignore policy.
452
444
 
453
- After this injected session validates every required artifact, invoke `/prizmkit-committer operation=prepare-runtime-commit artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/ evidence_paths=<exact paths> request_path=.prizmkit/specs/{{FEATURE_SLUG}}/runtime-commit-request.json`. Require a schema-v2 pathless request and `COMMIT_REQUEST_READY`; this session records `COMMIT_PENDING` and stops. The Python runtime re-enumerates and commits the complete non-ignored workspace, omitting only exact causal request/checkpoint bookkeeping, then verifies the local commit and finalizes checkpoint `COMMITTED`.
445
+ After this injected session validates every required artifact, invoke `/prizmkit-committer operation=prepare-runtime-commit artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/ evidence_paths=<exact paths> request_path=.prizmkit/specs/{{FEATURE_SLUG}}/runtime-commit-request.json`. Require a schema-v2 pathless request and `COMMIT_REQUEST_READY`, then stop without another committer checkpoint update or request validator. The Python Runtime validates the request, publishes commit readiness, commits the complete non-ignored workspace while omitting only exact causal request/checkpoint bookkeeping, verifies the local commit, and finalizes checkpoint `COMMITTED`.
454
446
 
455
447
  ## Critical Paths
456
448
 
@@ -245,7 +245,7 @@ Invoke `/prizmkit-retrospective` with the exact artifact root, exact non-`.prizm
245
245
 
246
246
  **c. Runtime commit preparation**
247
247
 
248
- After this injected session validates every required artifact and confirms final Review/Test authority covers the complete behavior-affecting Git-visible workspace, invoke `/prizmkit-committer operation=prepare-runtime-commit artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/ evidence_paths=<exact paths> request_path=.prizmkit/bugfix/{{BUG_ID}}/runtime-commit-request.json`. Require a schema-v2 pathless request and `COMMIT_REQUEST_READY`; this session records `COMMIT_PENDING` and stops. Ignored files remain local. The Python runtime re-enumerates and commits the complete non-ignored workspace with only exact causal request/checkpoint bookkeeping omitted, verifies the local commit, finalizes checkpoint `COMMITTED`, and controls any later publication.
248
+ After this injected session validates every required artifact and confirms final Review/Test authority covers the complete behavior-affecting Git-visible workspace, invoke `/prizmkit-committer operation=prepare-runtime-commit artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/ evidence_paths=<exact paths> request_path=.prizmkit/bugfix/{{BUG_ID}}/runtime-commit-request.json`. Require a schema-v2 pathless request and `COMMIT_REQUEST_READY`, then stop without another committer checkpoint update or request validator. Ignored files remain local. The Python Runtime validates the request, publishes commit readiness, commits the complete non-ignored workspace with only exact causal request/checkpoint bookkeeping omitted, verifies the local commit, finalizes checkpoint `COMMITTED`, and controls any later publication.
249
249
 
250
250
  ---
251
251
 
@@ -210,7 +210,7 @@ Write `.prizmkit/refactor/{{REFACTOR_ID}}/completion-summary.json` for downstrea
210
210
 
211
211
  Complete `refactor-report` and `completion-summary` before retrospective. Then invoke `/prizmkit-retrospective` with the exact artifact root, exact non-`.prizmkit/` `change_paths`, and a concise `change_summary`. Validate `outcome=RETRO_COMPLETE`; do not stage or commit.
212
212
 
213
- After this injected session validates every required artifact and confirms final Review/Test authority covers the complete behavior-affecting Git-visible workspace, invoke `/prizmkit-committer operation=prepare-runtime-commit artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/ evidence_paths=<exact paths> request_path=.prizmkit/refactor/{{REFACTOR_ID}}/runtime-commit-request.json`. Require a schema-v2 pathless request and `COMMIT_REQUEST_READY`; this session records `COMMIT_PENDING` and stops. Ignored files remain local. The Python runtime re-enumerates and commits the complete non-ignored workspace with only exact causal request/checkpoint bookkeeping omitted, verifies the local commit, finalizes checkpoint `COMMITTED`, and controls any later publication.
213
+ After this injected session validates every required artifact and confirms final Review/Test authority covers the complete behavior-affecting Git-visible workspace, invoke `/prizmkit-committer operation=prepare-runtime-commit artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/ evidence_paths=<exact paths> request_path=.prizmkit/refactor/{{REFACTOR_ID}}/runtime-commit-request.json`. Require a schema-v2 pathless request and `COMMIT_REQUEST_READY`, then stop without another committer checkpoint update or request validator. Ignored files remain local. The Python Runtime validates the request, publishes commit readiness, commits the complete non-ignored workspace with only exact causal request/checkpoint bookkeeping omitted, verifies the local commit, finalizes checkpoint `COMMITTED`, and controls any later publication.
214
214
 
215
215
  ---
216
216
 
@@ -24,9 +24,9 @@ Use this helper to update checkpoint status. Do not hand-edit `workflow-checkpoi
24
24
  - Complete `prizmkit-code-review` only with `--status completed --stage-result REVIEW_PASS`.
25
25
  - Complete `prizmkit-test` only after validating the sibling report/result pair, with `--status completed --stage-result TEST_PASS`.
26
26
  - Complete `prizmkit-retrospective` with `--status completed --stage-result RETRO_COMPLETE`.
27
- - After this injected session validates required gates and `/prizmkit-committer` returns `COMMIT_REQUEST_READY` with `runtime-commit-request.json`, record `--status in_progress --stage-result COMMIT_PENDING` and stop normal work. The Python runtime executes the local commit and alone advances this step to `completed/COMMITTED`.
27
+ - After this injected session validates required gates and `/prizmkit-committer` returns `COMMIT_REQUEST_READY` with `runtime-commit-request.json`, stop normal work without another checkpoint-helper call for the committer. The Python Runtime alone validates the request, publishes commit readiness, executes the local commit, and advances the step to `completed/COMMITTED`.
28
28
  - For `REVIEW_NEEDS_FIXES` or `TEST_NEEDS_FIXES`, classify the concrete correction into one allowed `--repair-scope`, record the failed step and result, and let the helper select the bounded implementation route. If the scope cannot be established safely, record `WORKFLOW_BLOCKED` rather than guessing.
29
- - Record `PLAN_BLOCKED`, `IMPLEMENT_BLOCKED`, `TEST_BLOCKED`, `RETRO_BLOCKED`, or `COMMIT_BLOCKED` with `--status failed --stage-result <result>` and a useful note. The helper records terminal `WORKFLOW_BLOCKED`; never mark the failed step completed.
29
+ - Record `PLAN_BLOCKED`, `IMPLEMENT_BLOCKED`, `TEST_BLOCKED`, or `RETRO_BLOCKED` with `--status failed --stage-result <result>` and a useful note. Record `COMMIT_BLOCKED` only when Committer returned it without producing `runtime-commit-request.json`; after a request exists, stop and leave all remaining committer transitions to Runtime. The helper records terminal `WORKFLOW_BLOCKED`; never mark a failed step completed.
30
30
  - When the routed implementation step is marked `in_progress`, the helper rewinds later checkpoint steps to pending while preserving their stage-owned reports for historical evidence. Fresh Review, configured verification, and Test results are still mandatory.
31
31
  - Complete `manual-verification` when configured; do not skip a required manual/hybrid evidence gate.
32
32
  - Omit `--note` when there is no useful failure or handoff note.
@@ -23,7 +23,7 @@ After Code Review, all configured verification, `TEST_PASS`, family reports/summ
23
23
  }
24
24
  ```
25
25
 
26
- 5. Require the stage-local result `COMMIT_REQUEST_READY`. Then this injected session—not the Skill—marks `prizmkit-committer` `in_progress` with `stage_result=COMMIT_PENDING` through the checkpoint helper. Do not mark it completed or write `COMMITTED`.
27
- 6. Stop normal work after the valid request and checkpoint handoff exist. Do not run `git add`, `git commit`, `git commit --amend`, merge, push, or create additional task files.
26
+ 5. Require the stage-local result `COMMIT_REQUEST_READY` and the exact request file. After that success, do not call the checkpoint helper again for the committer stage and do not run another request validator. Stop normal work immediately.
27
+ 6. Do not run `git add`, `git commit`, `git commit --amend`, merge, push, broad source searches, or create additional task files after the valid request exists.
28
28
 
29
- The Runtime validates the pathless schema, base, complete non-ignored workspace, sensitive path safeguards, merge state, and causal bookkeeping boundary. It stages the complete workspace, omitting only the exact active request/checkpoint whose final receipt cannot truthfully precede the commit; verifies a non-empty commit with the expected parent and message; records its Git receipt; and only then finalizes `COMMITTED` and performs configured integration. A malformed, stale, unsafe, incomplete, or contradictory handoff blocks without deleting user data.
29
+ The Runtime validates the pathless schema, base, complete pre-commit checkpoint, non-ignored workspace, sensitive path safeguards, merge state, and causal bookkeeping boundary. It atomically publishes its own commit-pending checkpoint state, stages the complete workspace while omitting only the exact active request/checkpoint whose final receipt cannot truthfully precede the commit, verifies a non-empty commit with the expected parent and message, records its Git receipt, and only then finalizes `COMMITTED` and performs configured integration. A malformed, stale, unsafe, incomplete, or contradictory handoff blocks without deleting user data.
@@ -407,14 +407,13 @@ def test_update_checkpoint_reenters_failed_stage_without_stale_result(tmp_path):
407
407
  assert "stage_result" not in persisted["feature_state"]
408
408
 
409
409
 
410
- def test_checkpoint_updater_supports_every_owned_stage_result(tmp_path):
410
+ def test_checkpoint_updater_supports_every_prompt_owned_stage_result(tmp_path):
411
411
  cases = [
412
412
  ("prizmkit-plan", "PLAN_READY", "completed"),
413
413
  ("prizmkit-implement", "IMPLEMENTED", "completed"),
414
414
  ("prizmkit-code-review", "REVIEW_PASS", "completed"),
415
415
  ("prizmkit-test", "TEST_BLOCKED", "failed"),
416
416
  ("prizmkit-retrospective", "RETRO_COMPLETE", "completed"),
417
- ("prizmkit-committer", "COMMIT_PENDING", "in_progress"),
418
417
  ]
419
418
 
420
419
  assert {stage_result for _skill, stage_result, _status in cases} <= VALID_STAGE_RESULTS
@@ -695,6 +694,7 @@ def test_update_checkpoint_completes_test_pass_without_validator(tmp_path):
695
694
  persisted = json.loads(checkpoint.read_text(encoding="utf-8"))
696
695
  assert persisted["steps"][2]["status"] == "completed"
697
696
  assert persisted["steps"][2]["stage_result"] == "TEST_PASS"
697
+ assert "commit_ready" not in result["semantic"]
698
698
 
699
699
 
700
700
  def test_update_checkpoint_rejects_test_completion_for_non_pass(tmp_path):
@@ -717,7 +717,7 @@ def test_update_checkpoint_rejects_test_completion_for_non_pass(tmp_path):
717
717
  assert "requires TEST_PASS" in result["error"]
718
718
 
719
719
 
720
- def test_prompt_checkpoint_helper_rejects_runtime_owned_committed_result(tmp_path):
720
+ def test_prompt_checkpoint_helper_rejects_runtime_owned_commit_results(tmp_path):
721
721
  payload = _family_checkpoint(tmp_path, semantic={}, terminal=False)
722
722
  committer = next(
723
723
  step for step in payload["steps"] if step["skill"] == "prizmkit-committer"
@@ -726,6 +726,12 @@ def test_prompt_checkpoint_helper_rejects_runtime_owned_committed_result(tmp_pat
726
726
  committer["stage_result"] = "COMMIT_PENDING"
727
727
  checkpoint = _write(tmp_path / "workflow-checkpoint.json", payload)
728
728
 
729
+ pending = update_checkpoint(
730
+ str(checkpoint),
731
+ "prizmkit-committer",
732
+ "in_progress",
733
+ semantic_update={"stage_result": "COMMIT_PENDING"},
734
+ )
729
735
  result = update_checkpoint(
730
736
  str(checkpoint),
731
737
  "prizmkit-committer",
@@ -733,6 +739,8 @@ def test_prompt_checkpoint_helper_rejects_runtime_owned_committed_result(tmp_pat
733
739
  semantic_update={"stage_result": "COMMITTED"},
734
740
  )
735
741
 
742
+ assert pending["ok"] is False
743
+ assert "Runtime-owned" in pending["error"]
736
744
  assert result["ok"] is False
737
745
  assert "Runtime-owned" in result["error"]
738
746
  without_result = update_checkpoint(
@@ -775,6 +783,39 @@ def test_update_checkpoint_rejects_finalization_before_test_pass(tmp_path):
775
783
  assert "TEST_PASS" in result["error"]
776
784
 
777
785
 
786
+ def test_prompt_checkpoint_helper_cannot_block_after_runtime_request_exists(tmp_path):
787
+ payload = _family_checkpoint(tmp_path, semantic={}, terminal=False)
788
+ committer = next(
789
+ step for step in payload["steps"] if step["skill"] == "prizmkit-committer"
790
+ )
791
+ committer["status"] = "in_progress"
792
+ committer.pop("stage_result", None)
793
+ committer["required_artifacts"] = [
794
+ ".prizmkit/specs/feature/runtime-commit-request.json"
795
+ ]
796
+ artifact_dir = tmp_path / ".prizmkit/specs/feature"
797
+ request = artifact_dir / "runtime-commit-request.json"
798
+ request.write_text("{}", encoding="utf-8")
799
+ checkpoint = _write(artifact_dir / "workflow-checkpoint.json", payload)
800
+
801
+ result = update_checkpoint(
802
+ str(checkpoint),
803
+ "prizmkit-committer",
804
+ "failed",
805
+ semantic_update={"stage_result": "COMMIT_BLOCKED"},
806
+ )
807
+
808
+ assert result["ok"] is False
809
+ assert "request already exists" in result["error"]
810
+ persisted = json.loads(checkpoint.read_text(encoding="utf-8"))
811
+ persisted_committer = next(
812
+ step for step in persisted["steps"]
813
+ if step["skill"] == "prizmkit-committer"
814
+ )
815
+ assert persisted_committer["status"] == "in_progress"
816
+ assert "stage_result" not in persisted_committer
817
+
818
+
778
819
  def test_commit_pending_is_runtime_ready_but_not_workflow_complete(tmp_path):
779
820
  payload = _family_checkpoint(tmp_path, semantic={}, terminal=False)
780
821
  payload["steps"].insert(
@@ -433,9 +433,10 @@ class TestScopedFeatureTestGate:
433
433
  assert "--status completed --stage-result REVIEW_PASS" in rendered
434
434
  assert "--status completed --stage-result TEST_PASS" in rendered
435
435
  assert "--status completed --stage-result RETRO_COMPLETE" in rendered
436
- assert "--status in_progress --stage-result COMMIT_PENDING" in rendered
437
- assert "Python runtime" in rendered
438
- assert "alone advances this step to `completed/COMMITTED`" in rendered
436
+ assert "--status in_progress --stage-result COMMIT_PENDING" not in rendered
437
+ assert "without another checkpoint-helper call for the committer" in rendered
438
+ assert "Python Runtime alone validates the request" in rendered
439
+ assert "advances the step to `completed/COMMITTED`" in rendered
439
440
  assert "Do not hand-edit `workflow-checkpoint.json` directly." in rendered
440
441
  assert "authoritative_evidence_paths" not in rendered
441
442
 
@@ -642,6 +643,28 @@ class TestHeadlessRecoveryReframing:
642
643
  for forbidden in (deleted_section, loader, placeholder, deleted_title):
643
644
  assert forbidden not in content
644
645
 
646
+ def test_feature_prompts_do_not_include_retired_execution_unit_timeout_recovery(self):
647
+ deleted_section = "subagent-timeout-recovery.md"
648
+ deleted_title = "Execution-Unit Timeout Recovery"
649
+ active_paths = [
650
+ Path("dev-pipeline/scripts/generate-bootstrap-prompt.py"),
651
+ Path("dev-pipeline/templates/bootstrap-tier3.md"),
652
+ ]
653
+
654
+ assert (Path("dev-pipeline/templates/sections") / deleted_section).exists() is False
655
+ for path in active_paths:
656
+ content = path.read_text(encoding="utf-8")
657
+ assert deleted_section not in content
658
+ assert deleted_title not in content
659
+
660
+ sections_dir = Path("dev-pipeline/templates/sections").resolve()
661
+ rendered = "\n".join(
662
+ section for _name, section in assemble_sections(
663
+ str(sections_dir), init_done=True, browser_enabled=False,
664
+ )
665
+ )
666
+ assert deleted_title not in rendered
667
+
645
668
  def test_assembled_prompts_do_not_spawn_log_monitor_or_require_compact(self):
646
669
  sections_dir = Path("dev-pipeline/templates/sections").resolve()
647
670
  deleted_title = "Session " + "Checkpoint Awareness"
@@ -1381,6 +1404,9 @@ class TestHeadlessPromptCleanupF033:
1381
1404
  assert artifact in prompt
1382
1405
  assert "Atomic Skills write only their stage-owned artifacts and domain results" in prompt
1383
1406
  assert "COMMIT_REQUEST_READY" in prompt
1407
+ assert "do not call the checkpoint helper again for the committer stage" in prompt
1408
+ assert "do not run another request validator" in prompt
1409
+ assert "atomically publishes its own commit-pending checkpoint state" in prompt
1384
1410
  assert '"schema_version": 2' in prompt
1385
1411
  assert '"intended_paths"' not in prompt
1386
1412
  assert "complete final Git-visible workspace" in prompt
@@ -1558,7 +1584,8 @@ class TestFeatureBootstrapShellExtraction:
1558
1584
  assert "text count .prizmkit/specs/123-prompt-cleanup/plan.md --pattern \"- [ ]\"" in tier3
1559
1585
  assert "/prizmkit-committer operation=prepare-runtime-commit" in tier3
1560
1586
  assert "Require a schema-v2 pathless request and `COMMIT_REQUEST_READY`" in tier3
1561
- assert "The Python runtime re-enumerates and commits the complete non-ignored workspace" in tier3
1587
+ assert "stop without another committer checkpoint update or request validator" in tier3
1588
+ assert "The Python Runtime validates the request, publishes commit readiness" in tier3
1562
1589
  assert "validate the complete Git-visible workspace" in tier3
1563
1590
  assert "Code Review and Test authority must cover every behavior-affecting visible change" in tier3
1564
1591
  assert "Ignored paths remain naturally absent" in tier3
@@ -12,6 +12,7 @@ from prizmkit_runtime.checkpoint_state import load_checkpoint_state
12
12
  from prizmkit_runtime.runtime_commit import (
13
13
  finalize_accepted_workspace_commit,
14
14
  finalize_runtime_commit,
15
+ prepare_runtime_commit_handoff,
15
16
  )
16
17
 
17
18
 
@@ -174,6 +175,30 @@ def _write_commit_ready_checkpoint(root: Path) -> tuple[Path, Path]:
174
175
  return artifact_dir, checkpoint_path
175
176
 
176
177
 
178
+ def _rewind_to_ai_request_ready(checkpoint_path: Path) -> None:
179
+ """Model the state after Committer wrote a request but before Runtime adoption."""
180
+ checkpoint = json.loads(checkpoint_path.read_text(encoding="utf-8"))
181
+ committer = next(
182
+ step for step in checkpoint["steps"]
183
+ if step["skill"] == "prizmkit-committer"
184
+ )
185
+ committer["status"] = "in_progress"
186
+ committer.pop("stage_result", None)
187
+ semantic = checkpoint["feature_state"]
188
+ semantic.update(
189
+ {
190
+ "stage": "committer",
191
+ "status": "in_progress",
192
+ "current_stage": "prizmkit-committer",
193
+ "next_stage": "prizmkit-committer",
194
+ "terminal_status": None,
195
+ }
196
+ )
197
+ semantic.pop("stage_result", None)
198
+ semantic.pop("blocked_reason", None)
199
+ checkpoint_path.write_text(json.dumps(checkpoint), encoding="utf-8")
200
+
201
+
177
202
  def _write_request(root: Path, artifact_dir: Path, base_head: str) -> Path:
178
203
  request_path = artifact_dir / "runtime-commit-request.json"
179
204
  request_path.write_text(
@@ -190,6 +215,136 @@ def _write_request(root: Path, artifact_dir: Path, base_head: str) -> Path:
190
215
  return request_path
191
216
 
192
217
 
218
+ def test_runtime_prepares_pending_from_ai_request_without_git_mutation(tmp_path):
219
+ base_head = _init_repo(tmp_path)
220
+ artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
221
+ _rewind_to_ai_request_ready(checkpoint_path)
222
+ (tmp_path / "tracked.txt").write_text("after\n", encoding="utf-8")
223
+ _write_request(tmp_path, artifact_dir, base_head)
224
+
225
+ result = prepare_runtime_commit_handoff(
226
+ tmp_path,
227
+ artifact_dir=artifact_dir,
228
+ checkpoint_path=checkpoint_path,
229
+ )
230
+
231
+ assert result.status == "ready"
232
+ assert result.reason == "runtime_commit_handoff_prepared"
233
+ assert _git(tmp_path, "rev-parse", "HEAD") == base_head
234
+ state = load_checkpoint_state(checkpoint_path, project_root=tmp_path)
235
+ assert state.semantic_commit_ready is True
236
+ committer = next(
237
+ step for step in state.steps if step.skill == "prizmkit-committer"
238
+ )
239
+ assert committer.status == "in_progress"
240
+ assert committer.stage_result == "COMMIT_PENDING"
241
+
242
+
243
+ def test_runtime_commit_auto_prepares_ai_request_and_finalizes(tmp_path):
244
+ base_head = _init_repo(tmp_path)
245
+ artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
246
+ _rewind_to_ai_request_ready(checkpoint_path)
247
+ (tmp_path / "tracked.txt").write_text("after\n", encoding="utf-8")
248
+ _write_request(tmp_path, artifact_dir, base_head)
249
+
250
+ result = finalize_runtime_commit(
251
+ tmp_path,
252
+ artifact_dir=artifact_dir,
253
+ checkpoint_path=checkpoint_path,
254
+ )
255
+
256
+ assert result.status == "committed"
257
+ assert result.commit_hash == _git(tmp_path, "rev-parse", "HEAD")
258
+ assert load_checkpoint_state(
259
+ checkpoint_path,
260
+ project_root=tmp_path,
261
+ ).semantic_complete is True
262
+
263
+
264
+ def test_runner_adopts_request_without_ai_publishing_pending(tmp_path):
265
+ from types import SimpleNamespace
266
+
267
+ from prizmkit_runtime.runners import _finalize_prepared_runtime_commit
268
+
269
+ base_head = _init_repo(tmp_path)
270
+ artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
271
+ _rewind_to_ai_request_ready(checkpoint_path)
272
+ (tmp_path / "tracked.txt").write_text("after\n", encoding="utf-8")
273
+ _write_request(tmp_path, artifact_dir, base_head)
274
+
275
+ result = _finalize_prepared_runtime_commit(
276
+ tmp_path,
277
+ SimpleNamespace(
278
+ checkpoint_path=checkpoint_path,
279
+ artifact_path=artifact_dir,
280
+ ),
281
+ )
282
+
283
+ assert result.status == "committed"
284
+ assert load_checkpoint_state(
285
+ checkpoint_path,
286
+ project_root=tmp_path,
287
+ ).semantic_complete is True
288
+
289
+
290
+ def test_runtime_prepare_does_not_override_terminal_commit_block(tmp_path):
291
+ base_head = _init_repo(tmp_path)
292
+ artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
293
+ _rewind_to_ai_request_ready(checkpoint_path)
294
+ checkpoint = json.loads(checkpoint_path.read_text(encoding="utf-8"))
295
+ committer = next(
296
+ step for step in checkpoint["steps"]
297
+ if step["skill"] == "prizmkit-committer"
298
+ )
299
+ committer["status"] = "failed"
300
+ committer["stage_result"] = "COMMIT_BLOCKED"
301
+ checkpoint["feature_state"].update(
302
+ {
303
+ "status": "failed",
304
+ "stage_result": "COMMIT_BLOCKED",
305
+ "current_stage": None,
306
+ "next_stage": None,
307
+ "blocked_reason": "commit_blocked",
308
+ "terminal_status": "WORKFLOW_BLOCKED",
309
+ }
310
+ )
311
+ checkpoint_path.write_text(json.dumps(checkpoint), encoding="utf-8")
312
+ _write_request(tmp_path, artifact_dir, base_head)
313
+
314
+ result = prepare_runtime_commit_handoff(
315
+ tmp_path,
316
+ artifact_dir=artifact_dir,
317
+ checkpoint_path=checkpoint_path,
318
+ )
319
+
320
+ assert result.status == "not_ready"
321
+ assert result.reason == "workflow_checkpoint_blocked"
322
+ persisted = load_checkpoint_state(checkpoint_path, project_root=tmp_path)
323
+ assert persisted.semantic_blocked is True
324
+ assert _git(tmp_path, "rev-parse", "HEAD") == base_head
325
+
326
+
327
+ def test_runtime_prepare_rejects_stale_request_without_publishing_pending(tmp_path):
328
+ base_head = _init_repo(tmp_path)
329
+ artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
330
+ _rewind_to_ai_request_ready(checkpoint_path)
331
+ _write_request(tmp_path, artifact_dir, "a" * 40)
332
+
333
+ result = prepare_runtime_commit_handoff(
334
+ tmp_path,
335
+ artifact_dir=artifact_dir,
336
+ checkpoint_path=checkpoint_path,
337
+ )
338
+
339
+ assert result.status == "failed"
340
+ assert result.reason == "base_head_mismatch"
341
+ state = load_checkpoint_state(checkpoint_path, project_root=tmp_path)
342
+ assert state.semantic_commit_ready is False
343
+ assert state.current_step is not None
344
+ assert state.current_step.stage_result is None
345
+ assert _git(tmp_path, "rev-parse", "HEAD") == base_head
346
+
347
+
193
348
  def test_runtime_commit_executes_complete_workspace_and_finalizes_only_checkpoint(tmp_path):
194
349
  base_head = _init_repo(tmp_path)
195
350
  artifact_dir, checkpoint_path = _write_commit_ready_checkpoint(tmp_path)
@@ -11,7 +11,7 @@ For a formal requirement:
11
11
  2. Use `/prizmkit-committer` for one local commit operation and one truthful Conventional Commit message.
12
12
  3. The commit candidate is the complete current Git-visible workspace: staged, unstaged, added, deleted, renamed, copied, and non-ignored untracked content, regardless of when or where each valid change originated.
13
13
  4. Final Code Review and Test authority must cover every behavior-affecting candidate. Committer inspects the complete final workspace, blocks stale or unsafe evidence, reports every visible change and message, and continues without an additional confirmation pause.
14
- 5. Direct Committer revalidates and stages the complete workspace automatically. Explicit Runtime preparation still writes a schema-v2 pathless request, and Python Runtime re-enumerates and stages the complete validated workspace after `COMMIT_PENDING`.
14
+ 5. Direct Committer revalidates and stages the complete workspace automatically. Explicit Runtime preparation writes a schema-v2 pathless request and stops; Python Runtime validates that request, atomically publishes `COMMIT_PENDING`, and re-enumerates and stages the complete validated workspace.
15
15
  6. Ignored paths remain local, never block, and are never force-added. Path provenance or namespace alone never admits or excludes content.
16
16
  7. Merge conflicts, Secrets, sensitive local content, known incorrect or incoherent changes, and unverifiable content still block. Only the exact active direct-workflow state or Runtime request/checkpoint and post-commit receipt writes may remain outside the snapshot because their causal finalization follows the commit.
17
17
  8. Runtime verifies the base, parent, message, non-empty commit, recovery receipt, and checkpoint finalization before integration.
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.1.176",
2
+ "version": "1.1.177",
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.",
@@ -217,7 +217,7 @@ Invoke Committer with the same `artifact_dir`, exact `evidence_paths`, `operatio
217
217
 
218
218
  Ignored paths remain naturally absent, stay local, and never block or require force-add. Global Secret, sensitive-content, merge-state, evidence-freshness, and content-correctness checks apply to every Git-visible candidate without provenance exceptions. The exact `.prizmkit/state/workflows/<requirement-identity>.json` remains local during the direct commit because this coordinator must finalize it after Committer returns. Exact active Runtime request/checkpoint and post-commit receipt writes follow the same causal rule in automation; no broader or caller-selected exclusion is allowed.
219
219
 
220
- External headless orchestration supplies explicit readiness evidence to `operation=prepare-runtime-commit`, maps `COMMIT_REQUEST_READY` to its own pending state, and lets Python Runtime validate and execute the schema-v2 pathless request. Runtime commits the complete validated Git-visible workspace with only exact causal bookkeeping omitted, then verifies Git and finalizes `COMMITTED`. Remote publication remains separate.
220
+ External headless orchestration supplies explicit readiness evidence to `operation=prepare-runtime-commit` and stops after `COMMIT_REQUEST_READY` and the exact request exist. Python Runtime validates the schema-v2 pathless request, atomically publishes its pending checkpoint state, commits the complete validated Git-visible workspace with only exact causal bookkeeping omitted, verifies Git, and finalizes `COMMITTED`. Remote publication remains separate.
221
221
 
222
222
  ## Automatic Handoff and Manual Fallback
223
223
 
@@ -173,8 +173,9 @@ Pipeline execution:
173
173
  ```text
174
174
  external coordinator validates its required gates and supplies exact readiness evidence
175
175
  → committer validates the complete Git-visible workspace and writes a schema-v2 pathless runtime-commit-request.json without Git mutation
176
- → external coordinator maps COMMIT_REQUEST_READY to its checkpoint's in_progress/COMMIT_PENDING state
177
- → Python runtime re-enumerates and stages the complete non-ignored workspace
176
+ → external coordinator stops after COMMIT_REQUEST_READY and the exact request exist
177
+ → Python Runtime validates the request and atomically publishes the checkpoint's in_progress/COMMIT_PENDING state
178
+ → Python Runtime re-enumerates and stages the complete non-ignored workspace
178
179
  → Python runtime verifies the commit, writes its receipt, and finalizes checkpoint completed/COMMITTED
179
180
  → remote publication remains separate
180
181
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "prizmkit",
3
- "version": "1.1.176",
3
+ "version": "1.1.177",
4
4
  "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,9 +0,0 @@
1
- ## Execution-Unit Timeout Recovery
2
-
3
- This recovery path applies to any delegated execution unit created by the active skill or runtime. The unit's own skill contract determines whether it may be resumed, replaced, or handled by the Main Agent; do not infer those rules from this prompt.
4
-
5
- If an execution unit times out:
6
- 1. `{{RUNTIME_HELPER_CMD}} artifact list .prizmkit/specs/{{FEATURE_SLUG}}` — check what exists
7
- 2. If `context-snapshot.md` exists: open a recovery prompt with `"Read .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md for project context and the Implementation Log. Run git diff HEAD to see actual code changes already made. Do NOT re-read individual source files unless the File Manifest directs you to."` + only remaining steps + `model: "lite"`
8
- 3. Apply the active skill's retry and continuation contract. Do not create a replacement execution unit when that contract requires native continuation or strict downgrade.
9
- 4. After the allowed recovery attempts are exhausted, the Main Agent continues directly when safe or records `failure-log.md` with the timeout and last observable state.