prizmkit 1.1.153 → 1.1.155

package/bundled/skills/prizmkit-test/references/test-coverage-model.md

@@ -40,16 +40,16 @@ Record dynamic or unprovable coupling as a remaining edge. An edge that can chan
 
 ## Truth Precedence
 
-Resolve expected behavior in this order:
+Resolve expected business behavior from confirmed specifications and acceptance criteria before lower-authority observations. For a producer-consumer boundary, apply the boundary-specific authority in `boundary-contract-and-test-double-guidance.md`:
 
 1. confirmed specification;
-2. machine-readable contract;
-3. acceptance criteria;
-4. trusted existing tests;
-5. callers and consumers;
-6. current implementation.
+2. machine-readable wire contract;
+3. traceably generated type, client, server stub, or fixture;
+4. provider raw-wire contract evidence or authorized isolated observation;
+5. provider implementation, locked SDK behavior, and matching official documentation;
+6. trusted existing tests, callers and consumers, consumer-local types/fixtures/mocks, and other current implementation evidence.
 
-Do not encode a possible implementation defect as expected behavior. Conflicting higher-precedence truth that cannot be resolved produces `TEST_BLOCKED`.
+Lower-authority material cannot override a higher-authority source or prove a property outside its boundary. Do not encode a possible implementation defect as expected behavior. Conflicting higher-precedence truth that cannot be resolved produces `TEST_BLOCKED`.
 
 ## Behavior Inventory
 
@@ -88,6 +88,21 @@ Cover validation, dependency, malformed-response, timeout, cancellation, cleanup
 
 Cover valid and invalid transitions, retries, repeated calls, writes, events, call counts, ordering, rollback, and cleanup.
 
+For every applicable state-changing user or system workflow, model and test the complete mutation lifecycle:
+
+1. precondition;
+2. input or selection;
+3. explicit commit point;
+4. cancel without side effects before commit;
+5. pending and duplicate-action protection;
+6. success visibility;
+7. failure recovery and absence of partial effects;
+8. reload or re-entry, including process restart when relevant;
+9. retry, conflict, and idempotency behavior;
+10. downstream read or consumption of the committed result.
+
+If the confirmed specification does not establish the commit point or interaction semantics, request clarification or return `TEST_BLOCKED` when the ambiguity affects the verdict. Do not infer the expected workflow from the current implementation.
+
 ### Permission
 
 Apply to identity, role, tenant, ownership, policy, entitlement, secret, or protected-resource behavior. Include missing/invalid identity, wrong owner or tenant, insufficient grants, and default-deny behavior.
@@ -112,20 +127,26 @@ Apply to databases, filesystems, queues, providers, clocks/randomness, cross-mod
 
 Apply when callers depend on return shape, errors, side effects, ordering, generated assets, shared types, contracts, state, or invocation conventions.
 
-## Layer Selection
+## Layer Selection and Proof Capability
 
-Use the lowest layer that proves a property without removing relevant composition.
+Use the lowest layer that proves a property without removing relevant composition. Classify tests by components actually executed:
 
 | Layer | Use For |
 |---|---|
-| Focused/unit | Critical pure logic, exact boundaries, deterministic errors, fast localization. |
-| Module/component | Public module behavior with internal collaborators composed as production uses them. |
-| Contract/integration | Shared protocol compatibility or isolated infrastructure that mocks cannot adequately prove. |
-| Code-level E2E | User-visible CLI, API, or UI composition when an applicable native harness exists. |
+| Focused / Unit Test | Critical pure logic, exact boundaries, deterministic errors, and fast localization; dependencies may be replaced. |
+| Module / Component Test | Public module behavior or UI component behavior under supplied dependencies. |
+| UI Component Test | Rendering and interaction with provider compatibility explicitly out of scope. |
+| Mock Browser Test | Browser workflow with an intercepted or fixture-backed critical boundary; not Full-stack evidence. |
+| Consumer Contract Test | Consumer handling against a contract-validated test double. |
+| Provider Contract Test | Provider raw wire payload at its serialization boundary. |
+| Integration Test | A named module/infrastructure combination with that combination kept real. |
+| Full-stack E2E | Complete user path with critical application boundaries not replaced. |
 | Affected-module regression | Every required test for the complete affected module. |
 | Regression Ring | Concrete callers, consumers, contracts, adapters, and shared state dependencies. |
 
-Not every behavior needs every layer. Record a concise reason for omitted higher layers, such as a pure library having no process or UI boundary.
+Browser execution alone does not determine the layer. Every test claim must state the property proved and any property not proven because a test double removes relevant composition.
+
+Not every behavior needs every layer. Record a concise reason for omitted higher layers, such as a pure library having no process or UI boundary. A missing layer blocks `TEST_PASS` only when it is needed to preserve a verdict-capable combination.
 
 ## Critical Low-Level Logic
 
@@ -182,12 +203,15 @@ Coverage is complete enough for `TEST_PASS` only when:
 1. every discoverable observable behavior is represented;
 2. every applicable risk has a credible project-native test;
 3. critical low-level logic has direct focused coverage when justified;
-4. selected layers preserve the property being proved;
-5. complete affected-module regression passes;
-6. Regression Ring verification passes;
-7. concrete unresolved coupling no longer affects the verdict;
-8. Main-Agent review converges;
-9. applicable independent review converges or is strictly downgraded;
-10. no mutation follows final review and execution.
+4. every verdict-relevant boundary and test double has contract authority, fidelity proof, removed-composition, proof-limit, and remaining-risk analysis;
+5. selected layers preserve the property being proved and composition-preserving evidence covers every verdict-capable removed combination;
+6. provider contracts inspect risk-relevant raw wire output;
+7. applicable state-changing workflows cover commit, cancellation, failure, re-entry, and repeated-operation semantics;
+8. complete affected-module regression passes;
+9. Regression Ring verification passes;
+10. concrete unresolved coupling no longer affects the verdict;
+11. Main-Agent review converges;
+12. applicable independent review converges or is strictly downgraded;
+13. no mutation follows final review and execution.
 
 Absolute completeness cannot be guaranteed. State remaining informational risks honestly without presenting them as proven behavior.

package/bundled/skills/prizmkit-test/references/test-report-template.md

@@ -49,7 +49,7 @@ Coverage metrics, when available: <diagnostic values or not collected>. Percenta
 
 | Path | Layer | Behaviors and Risks | Change |
 |---|---|---|---|
-| <path> | focused / module / contract / integration / E2E / regression | <coverage> | added / updated / existing |
+| <path> | focused/unit / module/component / UI component / Mock Browser / consumer contract / provider contract / integration / Full-stack E2E / regression | <coverage and proof boundary> | added / updated / existing |
 
 - Existing native framework reused: <yes/no and framework>
 - Infrastructure changes: <none or concise list>
@@ -104,12 +104,19 @@ Coverage metrics, when available: <diagnostic values or not collected>. Percenta
 - Review scope: delta / none
 - Rationale: <contract and risk analysis>
 
-## External Contracts and Mocks
+## Boundary Contracts and Test Doubles
 
-| Dependency | Contract Source | Test Double / Isolation | Variants | Remaining Risk |
+| Boundary | Contract Authority | Fidelity Proof | Test Double | Composition Removed |
 |---|---|---|---|---|
-| <dependency> | <project path or public official source/version> | <mock/fake/server/container/isolated service> | <success/boundary/failure variants> | <none or risk> |
+| <producer → consumer; protocol> | <boundary-appropriate source and provenance> | <generation/schema/raw-wire/shared fixture/isolated observation/contract framework> | <mock/fake/fixture/interception/server/container/service or none> | <serializer/adapter/network/provider/persistence/process or none> |
 
+| Property Not Proven | Composition-Preserving Test | Evidence Classification | Remaining Risk / Verdict Impact |
+|---|---|---|---|
+| <property outside the double-backed proof boundary> | <provider/consumer contract, integration, Full-stack E2E, or missing> | <local / consumer contract / provider contract / integration / Mock Browser / Full-stack> | <none, informational, TEST_NEEDS_FIXES correction, or TEST_BLOCKED prerequisite> |
+
+- Test-layer claims match actual composition: yes / no
+- Every verdict-capable removed combination has preserving evidence: yes / no
+- Provider raw wire asserted where serialization affects the verdict: yes / no / not-applicable
 - Production credentials or resources used: no
 - Real deployed environment validated: no
 
@@ -125,15 +132,18 @@ Render `TEST_PASS` only when:
 - mandatory Main-Agent review converged;
 - independent review converged or was visibly downgraded under its strict capability gate;
 - all required native tests pass on the exact final state;
+- every verdict-relevant test double has boundary-specific authority and fidelity proof;
+- every verdict-capable property removed by a double has composition-preserving evidence, and every layer claim matches actual composition;
+- applicable provider contract tests assert risk-relevant raw wire payload and state-changing workflows cover commit, cancellation, failure, re-entry, and repeated-operation semantics;
 - no accepted or unresolved finding remains;
-- no high-risk production repair awaits delta Code Review;
+- no high-risk production defect or correction remains;
 - no mutation occurred after final applicable review and execution.
 
-Render `TEST_NEEDS_FIXES` for a known remaining correction, exhausted review/repair budget with known work, or a completed high-risk repair requiring delta Code Review.
+Render `TEST_NEEDS_FIXES` for a known remaining correction, an exhausted testing-local review/repair budget with known work, or a proven high-risk production defect that this invocation must not repair.
 
-Render `TEST_BLOCKED` when truth, required input, safe environment, execution reliability, external-target safety, or required Reviewer input prevents a safe verdict.
+Render `TEST_BLOCKED` when truth, required input, safe environment, execution reliability, external-target safety, or required Reviewer input prevents a safe verdict. This includes unavailable required composition-preserving execution and unresolved contract authority or test-double fidelity that affects the verdict; lower-layer green tests cannot substitute.
 
-No conditional pass, commit authorization, release authorization, runtime classification, target hash, manifest, attestation, or package lifecycle belongs in the report.
+No conditional pass, commit authorization, release authorization, runtime classification, target hash, manifest, attestation, or package state belongs in the report.
 
 ## Terminal Machine Projection
 
@@ -153,8 +163,6 @@ Write `test-result.json` together with the report:
   },
   "repair_rounds": 0,
   "production_changed": false,
-  "review_required": false,
-  "review_scope": null,
   "unresolved_items": []
 }
 ```
@@ -170,7 +178,6 @@ Constraints:
 - `downgraded` requires `responses=0`, a non-empty `downgrade_reason`, and `final_state_rechecked=false`.
 - `not_applicable` requires `responses=0`, `downgrade_reason=null`, and `final_state_rechecked=false`.
 - `independent_review.responses` is otherwise bounded from `0` through `5`.
-- `review_scope` is `delta` exactly when `review_required=true`; otherwise it is null.
-- `unresolved_items` contains concise strings and agrees with the report.
-- Report and JSON agree on final result and production-review requirement.
+- `TEST_PASS` requires an empty `unresolved_items`; `TEST_NEEDS_FIXES` and `TEST_BLOCKED` each require at least one concise correction or blocker string, and the list agrees with the report.
+- Report and JSON agree on final result and production-change diagnostics.
 - The JSON is terminal output only and is never updated as an internal checkpoint.

package/bundled/skills/prizmkit-workflow/SKILL.md

@@ -46,7 +46,7 @@ Accept:
 
 - `description`: the natural-language formal requirement;
 - `artifact_dir`: optional explicit requirement artifact root;
-- `execution_mode`: `interactive` by default; headless only when a trusted host explicitly authorizes it;
+- `execution_mode`: `interactive`; external headless automation must invoke atomic stages directly and use its Python runtime for commit execution;
 - `resume`: optional workflow state path or requirement slug for recovery.
 
 If `description` is missing and no resumable workflow is supplied, ask for the requirement before invoking `prizmkit-plan`. External automation must invoke atomic stages directly with its own execution checkpoint rather than nesting this composite workflow.
@@ -57,11 +57,11 @@ If `description` is missing and no resumable workflow is supplied, ask for the r
 
 Invoke `/prizmkit-plan` with the requirement and any explicit `artifact_dir`. Do not write a second plan in this orchestrator.
 
-If initialization context is missing, allow `prizmkit-plan` to recommend initialization and continue with source fallback when the user chooses to proceed. Initialization is a soft prerequisite, not a hidden lifecycle stage.
+If initialization context is missing, let `prizmkit-plan` use its source fallback. Initialization is not a hidden lifecycle stage.
 
 ### 2. Preserve Requirement Identity
 
-Once `prizmkit-plan` resolves an `artifact_dir`, capture it and pass the exact same value to every later stage. The artifact root is generic and is not restricted to one directory family:
+Once `prizmkit-plan` resolves an `artifact_dir`, capture it and pass the exact same value to every later stage. Read `${SKILL_DIR}/references/artifact-identity.md` before deriving or opening workflow state. The artifact root is generic and is not restricted to one directory family:
 
 ```text
 .prizmkit/specs/<requirement-slug>/
@@ -69,35 +69,38 @@ Once `prizmkit-plan` resolves an `artifact_dir`, capture it and pass the exact s
 .prizmkit/refactor/<refactor-id>/
 ```
 
-Never select a different most-recent plan when resuming or handing off. The workflow state path is:
+Never select a different most-recent plan when resuming or handing off. Derive the workflow state path from the exact artifact-directory basename, validate its safe identity, and fail closed if an existing state path belongs to another artifact:
 
 ```text
-.prizmkit/state/workflows/<requirement-slug>.json
+.prizmkit/state/workflows/<requirement-identity>.json
 ```
 
-Read `${SKILL_DIR}/references/workflow-state-protocol.md` for the shared state contract. This workflow state remains distinct from any external host execution checkpoint. The target project controls whether generated `.prizmkit/` files are committed, ignored, or shared; do not modify its Git policy.
+Read `${SKILL_DIR}/references/artifact-identity.md` for path/collision rules and `${SKILL_DIR}/references/workflow-state-protocol.md` for the shared state content contract. This workflow state remains distinct from any external host execution checkpoint. The target project controls whether generated `.prizmkit/` files are committed, ignored, or shared; do not modify its Git policy.
 
 ### 3. Advance Only on Truthful Success
 
 After each atomic stage:
 
-1. Read the stage's actual output and terminal status.
-2. Validate the expected authoritative artifact or evidence and workflow-state transition.
-3. Preserve the same `artifact_dir`.
-4. Continue only on the permitted success status.
-5. Because this composite is the active orchestrator, atomic skills return terminal state and `next_stage` to it; they must not invoke the next stage recursively.
-6. If the host cannot invoke another skill automatically, stop with exactly one deterministic next skill, its `artifact_dir`, and the workflow-state path.
+1. Read the stage-local result and stage-owned artifacts.
+2. Validate those artifacts independently.
+3. Map the domain result to this composite's lifecycle status and update workflow state itself.
+4. Preserve the same `artifact_dir`.
+5. Continue only on the permitted success result.
+6. Supply explicit stage-local inputs to the next invocation; atomic Skills never read this composite's state or choose routing.
+7. If the host cannot invoke another Skill automatically, stop with one deterministic next invocation and caller-owned state path.
 
 Expected transitions:
 
 | Stage | Required success | Next stage |
 |---|---|---|
-| `prizmkit-plan` | `status=completed`, `stage_result=PLAN_READY` | `prizmkit-implement` |
-| `prizmkit-implement` | `status=completed`, `stage_result=IMPLEMENTED` | `prizmkit-code-review` |
-| `prizmkit-code-review` | `status=completed`, `stage_result=REVIEW_PASS` | `prizmkit-test` |
-| `prizmkit-test` | `status=completed`, `stage_result=TEST_PASS` | `prizmkit-retrospective` |
-| `prizmkit-retrospective` | `status=completed`, `stage_result=RETRO_COMPLETE`, with artifact result `DOCS_UPDATED` or `NO_DOC_CHANGE` | `prizmkit-committer` |
-| `prizmkit-committer` | explicit interactive confirmation, then `status=completed` with `stage_result=COMMITTED` | end |
+| `prizmkit-plan` | `PLAN_READY` plus valid `spec.md`/`plan.md` | `prizmkit-implement` |
+| `prizmkit-implement` | `IMPLEMENTED` plus completed task markers | `prizmkit-code-review` |
+| `prizmkit-code-review` | `PASS` plus valid `review-report.md` | `prizmkit-test` |
+| `prizmkit-test` | `TEST_PASS` plus consistent report/result pair | `prizmkit-retrospective` |
+| `prizmkit-retrospective` | `RETRO_COMPLETE` plus an artifact whose `outcome` and `result` agree | `prizmkit-committer` |
+| `prizmkit-committer` | `COMMITTED` after explicit interactive confirmation | end |
+
+Before invoking `prizmkit-retrospective`, derive the exact changed project paths outside `.prizmkit/` and pass them as `change_paths` with a concise `change_summary`. Do not ask that atomic Skill to infer scope from this composite's state or earlier artifacts.
 
 `TEST_NOT_APPLICABLE` is not a valid lifecycle success. Lightweight changes must execute deterministic verification and return `TEST_PASS`.
 
@@ -106,16 +109,16 @@ Expected transitions:
 The composite must not:
 
 - reinterpret a plan as implementation;
-- repair production code outside `prizmkit-implement` or the Main-Agent review loop;
+- repair production code itself instead of invoking the appropriate atomic stage with explicit repair input;
 - claim tests passed without a consistent `test-report.md` and terminal `test-result.json`;
 - reinterpret testing-domain results as runtime/session outcomes;
 - perform retrospective documentation changes itself;
-- stage or commit before `prizmkit-committer` applies the current execution's authorization boundary;
+- stage or commit before `prizmkit-committer` completes the interactive preview and confirmation boundary;
 - invoke `prizmkit-deploy` as a hidden seventh stage.
 
 ## Failure and Repair Routing
 
-Use the shared workflow state and authoritative stage evidence to determine routing. Do not blindly retry every failure.
+Use caller-owned workflow state and authoritative stage artifacts to determine routing. Atomic Skills never own this decision.
 
 ### Review Failure
 
@@ -136,15 +139,16 @@ The Main-Agent review skill owns its internal review repairs and its internal te
 ```text
 TEST_NEEDS_FIXES
   → preserve test-report.md and test-result.json
-  → stop with the known remaining correction or delta-review requirement
-  → caller owns any later review/retest decision
+  → when the outer repair budget remains, supply the exact correction to prizmkit-implement
+  → require fresh prizmkit-code-review and prizmkit-test results
+  → otherwise stop with WORKFLOW_BLOCKED
 
 TEST_BLOCKED
   → preserve test-report.md and test-result.json
   → stop with the unresolved truth, input, safety, environment, or reliability blocker
 ```
 
-The composite must not invoke implementation or Code Review automatically from inside the returned testing result unless its own explicitly authorized outer policy defines a new invocation. It must never treat either result as an AI CLI crash.
+The composite's bounded outer repair policy owns that fresh invocation route; it does not recreate the testing-local repair loop. It must never treat either non-pass result as an AI CLI crash.
 
 ### Environment Block
 
@@ -159,7 +163,7 @@ TEST_BLOCKED
   → stop with a deterministic prizmkit-test resume entry
 ```
 
-A trusted headless host performs its own bounded automatic environment recovery when invoking atomic stages. It does not invoke this composite workflow or silently turn a blocked result into success.
+An external headless runtime may perform its own bounded environment recovery when invoking atomic stages. It does not invoke this interactive composite workflow or silently turn a blocked result into success.
 
 ### Repair Limit
 
@@ -179,19 +183,13 @@ When the limit is reached:
 
 The internal `prizmkit-code-review` limit of ten completed review rounds remains separate and does not increment `repair_round`.
 
-## Commit Authorization Boundary
-
-The composite may automatically reach `/prizmkit-committer`, but it must not silently create a Git commit.
+## Interactive Commit Boundary
 
-Interactive execution requires the committer to:
+The composite reaches `/prizmkit-committer operation=interactive-commit` but must not silently create a Git commit.
 
-1. verify all five preceding stage results for the same `artifact_dir`;
-2. inspect the final workspace;
-3. present intended files, diff summary, sensitive-file warnings, and the proposed Conventional Commit message;
-4. wait for explicit user confirmation from the current user;
-5. create and verify the local commit only after confirmation.
+The composite must validate all prior stage artifacts, derive exact non-`.prizmkit/` change paths for the retrospective input, and validate its result. It then invokes the committer with the same `artifact_dir`, exact `evidence_paths`, caller-state paths in `excluded_paths`, and `operation=interactive-commit`. The committer inspects the supplied final change, presents the exact commit, waits for confirmation, and creates it only after approval.
 
-Trusted headless execution is a separate atomic-stage path. It requires a host-defined non-interactive `mode`, a trusted `owner` identifier, and `local_commit_authorized=true`; it does not ask or wait. Unknown headless contexts are blocked. Remote publication is a separate host-runtime operation and is never decided by this composite workflow.
+External headless orchestration supplies explicit evidence to `operation=prepare-runtime-commit`, maps `COMMIT_REQUEST_READY` to its own pending state, and lets Python Runtime validate and execute the request. Remote publication remains separate.
 
 ## Automatic Handoff and Manual Fallback
 
@@ -206,7 +204,7 @@ When it does not:
 ```text
 Next stage: /prizmkit-<skill>
 artifact_dir: <same resolved artifact_dir>
-workflow_state: .prizmkit/state/workflows/<requirement-slug>.json
+workflow_state: .prizmkit/state/workflows/<requirement-identity>.json
 ```
 
 The user can invoke that one atomic skill and this composite can resume with `resume` later.
@@ -242,7 +240,7 @@ push: not performed automatically
 next_action: invoke /prizmkit-deploy separately if deployment is needed
 ```
 
-If the user declines interactive commit confirmation, report `status=in_progress`, `stage_result=COMMIT_PENDING` rather than `WORKFLOW_COMPLETE` and provide the exact `/prizmkit-committer` resume entry.
+If the user declines interactive commit confirmation, preserve the committer stage as pending or in progress without a workflow `stage_result`, report the atomic operation result `COMMIT_DECLINED`, and provide the exact `/prizmkit-committer operation=interactive-commit` resume entry. `COMMIT_PENDING` is reserved for a validated Runtime commit request and must not represent an interactive decline.
 
 If blocked, report:
 

package/bundled/skills/prizmkit-workflow/references/artifact-identity.md

@@ -0,0 +1,34 @@
+# Interactive Workflow Artifact Identity
+
+The interactive workflow derives state identity from the exact caller/planning artifact directory; it never generates a second slug.
+
+## Derivation
+
+1. Resolve `artifact_dir` as a project-relative path inside the active checkout.
+2. Take its final path component unchanged as `<requirement-identity>`.
+3. Require 1-96 Unicode code points and at most 200 UTF-8 bytes, containing only letters, decimal digits, ASCII hyphens, or ASCII underscores, with a letter or digit at both ends. Reject control characters, separators, `.`/`..`, symlink escape, and empty identity. The byte limit leaves portable filename space for the `.json` suffix.
+4. Use exactly:
+
+```text
+.prizmkit/state/workflows/<requirement-identity>.json
+```
+
+Examples:
+
+```text
+.prizmkit/specs/070-skill-generated-artifact-contracts/
+→ .prizmkit/state/workflows/070-skill-generated-artifact-contracts.json
+
+.prizmkit/bugfix/B-001/
+→ .prizmkit/state/workflows/B-001.json
+```
+
+## Collision and Resume Safety
+
+- Store the exact normalized project-relative `artifact_dir` in state.
+- Before creating state, if the target file already exists, read it and require its `artifact_dir` to equal the active artifact directory exactly.
+- A state file naming collision with a different artifact directory is blocking. Do not overwrite, merge, suffix, or silently select a recent state; require the caller to resolve the conflicting record explicitly.
+- When `resume` supplies a state path, require it to equal the derived path, remain under `.prizmkit/state/workflows/`, and point to the exact artifact directory recorded inside it.
+- Continue using the same state path and artifact directory for every stage and repair round.
+
+External checkpoints use their own identity and are never derived from or merged into this path.

package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md

@@ -4,11 +4,13 @@
 
 ## Location and Identity
 
+Derive the path through `${SKILL_DIR}/references/artifact-identity.md`:
+
 ```text
-.prizmkit/state/workflows/<requirement-slug>.json
+.prizmkit/state/workflows/<requirement-identity>.json
 ```
 
-The active `artifact_dir` is preserved exactly across every stage:
+The identity is the validated artifact-directory basename. An existing state file for a different `artifact_dir` is a blocking collision and is never overwritten or suffixed automatically. The active `artifact_dir` is preserved exactly across every stage:
 
 ```text
 .prizmkit/specs/<requirement-slug>/
@@ -31,7 +33,7 @@ The state file is an index, not the authority for stage completion:
 | Terminal testing result | `{artifact_dir}/test-result.json` |
 | Retrospective completion | `{artifact_dir}/retrospective-result.json` |
 | Durable architecture knowledge | `.prizmkit/prizm-docs/` |
-| Local commit | Git history and confirmed or authorized commit identity |
+| Local commit | Git history and runtime- or user-verified commit identity |
 | Current stage, orchestrator, and resume entry | Workflow state |
 | External orchestration progress | External host checkpoint |
 
@@ -64,7 +66,7 @@ Every consumer compares workflow state with the skill-owned artifacts and curren
 | `orchestrator` | Semantic coordinator identifier, or null for direct stage use. |
 | `stage` | Stage that most recently wrote state. |
 | `status` | Lifecycle status: `pending`, `in_progress`, `completed`, `failed`, or `skipped`. |
-| `stage_result` | Domain result for the current stage, such as `PLAN_READY`, `IMPLEMENTED`, `REVIEW_PASS`, `REVIEW_NEEDS_FIXES`, `TEST_*`, `RETRO_COMPLETE`, or `COMMITTED`. |
+| `stage_result` | Coordinator-recorded lifecycle result mapped from a validated atomic result and its required artifacts, such as `PLAN_READY`, `IMPLEMENTED`, `REVIEW_PASS`, `REVIEW_NEEDS_FIXES`, `TEST_*`, `RETRO_COMPLETE`, or `COMMITTED`. |
 | `completed_stages` | Ordered stages completed for this requirement. |
 | `repair_scope` | Optional caller-owned routing scope. The test skill reports high-risk repairs through `test-result.json` instead of scheduling another stage. |
 | `repair_round` | Optional outer cross-stage repair round, from 0 through 3. It is not a test-internal repair counter. |
@@ -97,10 +99,10 @@ review-report NEEDS_FIXES        → status=failed,     stage_result=REVIEW_NEED
 test-result TEST_PASS            → status=completed,  stage_result=TEST_PASS
 test-result TEST_NEEDS_FIXES     → status=failed,     stage_result=TEST_NEEDS_FIXES
 test-result TEST_BLOCKED         → status=failed,     stage_result=TEST_BLOCKED
-retrospective DOCS_UPDATED       → status=completed,  stage_result=RETRO_COMPLETE
-retrospective NO_DOC_CHANGE      → status=completed,  stage_result=RETRO_COMPLETE
-retrospective blocked            → status=failed,     stage_result=RETRO_BLOCKED
-commit authorization pending     → status=in_progress, stage_result=COMMIT_PENDING
+retrospective outcome=RETRO_COMPLETE, result=DOCS_UPDATED   → status=completed, stage_result=RETRO_COMPLETE
+retrospective outcome=RETRO_COMPLETE, result=NO_DOC_CHANGE  → status=completed, stage_result=RETRO_COMPLETE
+retrospective outcome=RETRO_BLOCKED                         → status=failed,    stage_result=RETRO_BLOCKED
+runtime commit preparation       → status=in_progress, stage_result=COMMIT_PENDING
 local commit confirmed           → status=completed,  stage_result=COMMITTED
 commit blocked                   → status=failed,     stage_result=COMMIT_BLOCKED
 ```
@@ -115,8 +117,8 @@ commit blocked                   → status=failed,     stage_result=COMMIT_BLOC
 
 ```text
 TEST_NEEDS_FIXES
-→ known correction or required delta review remains
-→ caller decides whether and how to arrange another stage
+→ a known correction remains
+→ caller decides whether and how to arrange another invocation
 
 TEST_BLOCKED
 → truth, input, safe environment, or reliable execution prevents a verdict
@@ -132,30 +134,32 @@ Any outer repair or continuation policy is independently owned by the caller and
 
 1. An atomic stage performs only its own stage, writes its truthful result and artifact paths, and returns control.
 2. When `orchestrator` is non-null, only that orchestrator invokes the next skill.
-3. Direct stage use may report a possible next invocation but does not claim it ran.
+3. Direct atomic use returns only its local result and artifacts; it does not report or select another invocation.
 4. Every handoff preserves the same `artifact_dir`.
 5. External automation invokes atomic stages directly and does not nest the composite workflow.
 6. Workflow state never replaces or absorbs an external host checkpoint.
 
-## Commit Authorization
+## Commit Execution Ownership
 
 Interactive execution:
 
 ```text
 committer previews intended files and message
 → waits for explicit current-user confirmation
-→ creates the local commit
+→ stages, creates, and verifies the local commit
 ```
 
-Trusted headless execution:
+Pipeline execution:
 
 ```text
-trusted host explicitly authorizes the current local task commit
-→ committer verifies gates and commits automatically
+external coordinator validates its required gates and supplies exact readiness evidence
+→ committer validates only that evidence and writes an exact runtime-commit-request.json
+→ external coordinator maps COMMIT_REQUEST_READY to its checkpoint's in_progress/COMMIT_PENDING state
+→ Python runtime validates the request, commits, verifies Git, and writes checkpoint completed/COMMITTED
 → remote publication remains separate
 ```
 
-A self-declared or untrusted headless context does not authorize a commit.
+The preparation request is data for runtime validation, not prompt-level authorization. The committer must not stage, commit, or predeclare COMMITTED in pipeline preparation mode.
 
 ## Recovery
 
@@ -171,4 +175,4 @@ When state is missing, stale, or inconsistent:
 8. Reconstruct the latest safe predecessor and report the reconstruction.
 9. Continue only from the first incomplete or invalid stage.
 
-Stale state never bypasses review, testing, retrospective, commit authorization, or external checkpoint enforcement.
+Stale state never bypasses review, testing, retrospective, commit preparation/execution, or external checkpoint enforcement.

package/bundled/skills/recovery-workflow/SKILL.md

@@ -7,12 +7,14 @@ description: "Return the exact PrizmKit CLI command that continues an interrupte
 
 Find an interrupted pipeline task's durable checkout record and return the existing runtime command that continues that task on its recorded branch. The runtime already owns branch reuse, checkpoint interpretation, session continuation, and task execution; this skill must not reproduce those mechanisms.
 
+This skill invokes its own bundled detector. The canonical runtime exposes no separate Recovery command namespace, prompt generator, or Recovery AI-session launcher.
+
 ## Boundary
 
 This workflow:
 - Detects active feature, bugfix, and refactor task checkout records.
 - Confirms that each recorded task branch still exists.
-- Returns the exact item-specific `cli.py ... run <TASK_ID>` command.
+- Returns the exact item-specific `cli.py run <family> <TASK_ID>` command.
 - Shows the branch, task family, task ID, and checkout record that justify the command.
 
 This workflow does not:
@@ -40,7 +42,8 @@ The detector reads only active checkout records:
 
 A candidate is resumable only when:
 - `state` is `active`;
-- `task_id` matches its task family;
+- `task_type` equals the checkout directory family;
+- `task_id` is explicitly recorded, matches the exact `F-NNN`, `B-NNN`, or `R-NNN` family form, and equals its parent state-directory name;
 - `active_dev_branch` is present; and
 - the recorded local branch still exists.
 
@@ -71,9 +74,9 @@ Report that no active interrupted pipeline task branch was found. Do not fall ba
 Return the detector-provided command verbatim. The canonical forms are:
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py feature run F-001
-python3 ./.prizmkit/dev-pipeline/cli.py bugfix run B-001
-python3 ./.prizmkit/dev-pipeline/cli.py refactor run R-001
+python3 ./.prizmkit/dev-pipeline/cli.py run feature F-001
+python3 ./.prizmkit/dev-pipeline/cli.py run bugfix B-001
+python3 ./.prizmkit/dev-pipeline/cli.py run refactor R-001
 ```
 
 Do not prepend `git checkout`. The runtime resolves the durable checkout identity and continues the task on its recorded branch or linked worktree.
@@ -91,7 +94,7 @@ task_id: <F-NNN | B-NNN | R-NNN>
 branch: <recorded active_dev_branch>
 checkout: <project-relative checkout.json path>
 command:
-python3 ./.prizmkit/dev-pipeline/cli.py <family> run <TASK_ID>
+python3 ./.prizmkit/dev-pipeline/cli.py run <family> <TASK_ID>
 
 execution: not performed
 ```

package/bundled/skills/recovery-workflow/evals/evals.json

@@ -6,7 +6,7 @@
       "id": 1,
       "name": "single-feature-interruption",
       "prompt": "My feature pipeline process stopped. Give me the command to continue it.",
-      "expected_output": "Detect one active feature checkout record with an existing branch and return python3 ./.prizmkit/dev-pipeline/cli.py feature run F-001 without executing it.",
+      "expected_output": "Detect one active feature checkout record with an existing branch and return python3 ./.prizmkit/dev-pipeline/cli.py run feature F-001 without executing it.",
       "setup_description": "Create .prizmkit/state/features/F-001/checkout.json with state active and an existing dev/F-001-* local branch.",
       "files": []
     },
@@ -14,7 +14,7 @@
       "id": 2,
       "name": "single-bugfix-interruption",
       "prompt": "Resume the interrupted bugfix task.",
-      "expected_output": "Detect the active bugfix checkout and return python3 ./.prizmkit/dev-pipeline/cli.py bugfix run B-001 without reconstructing phases or executing the command.",
+      "expected_output": "Detect the active bugfix checkout and return python3 ./.prizmkit/dev-pipeline/cli.py run bugfix B-001 without reconstructing phases or executing the command.",
       "setup_description": "Create .prizmkit/state/bugfix/B-001/checkout.json with state active and an existing bugfix/B-001-* local branch.",
       "files": []
     },

package/bundled/skills/recovery-workflow/references/detection.md

@@ -13,9 +13,10 @@ Recovery uses the runtime's durable task checkout identity rather than reconstru
 A record is resumable only when:
 
 1. `state` equals `active`.
-2. `task_id` matches the directory family.
-3. `active_dev_branch` is non-empty.
-4. `refs/heads/<active_dev_branch>` exists locally.
+2. `task_type` equals the checkout directory family.
+3. `task_id` is explicitly present, matches the exact `F-NNN`, `B-NNN`, or `R-NNN` family form, and equals its parent state-directory name.
+4. `active_dev_branch` is non-empty.
+5. `refs/heads/<active_dev_branch>` exists locally.
 
 Ignore records whose state is `completed` or `reset`. Also ignore session logs, plan lists, artifact directories, and checkpoint files when no active checkout record exists. Those files may remain after completed or historical work and are not evidence of an interrupted task.
 
@@ -24,9 +25,9 @@ Ignore records whose state is `completed` or `reset`. Also ignore session logs,
 The item-specific foreground command reloads the active checkout record and reuses its branch or linked worktree:
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py feature run <F-NNN>
-python3 ./.prizmkit/dev-pipeline/cli.py bugfix run <B-NNN>
-python3 ./.prizmkit/dev-pipeline/cli.py refactor run <R-NNN>
+python3 ./.prizmkit/dev-pipeline/cli.py run feature <F-NNN>
+python3 ./.prizmkit/dev-pipeline/cli.py run bugfix <B-NNN>
+python3 ./.prizmkit/dev-pipeline/cli.py run refactor <R-NNN>
 ```
 
 The command does not need an explicit branch argument. Do not prepend `git checkout`, because the runtime owns checkout identity and branch/worktree reuse.