prizmkit 1.1.130 → 1.1.131

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

@@ -15,9 +15,20 @@ Choose project-semantic parameters from the target project: framework, commands,
 
 Fix only the protocol mechanisms needed for safe, replayable evidence: project/evidence/request locators, schema-shaped requests, path confinement, real process execution, complete raw capture, runner-generated chained receipts, hash binding, append-only history, differential isolation/cleanup, and resume invalidation. Read `${SKILL_DIR}/references/trusted-evidence-execution.md` before inventory, execution, differential proof, resume, or replay; it defines the trust boundary and builder commands. Read `${SKILL_DIR}/references/evidence-request-protocol.md` when authoring any request or authoritative JSON record; it defines request ownership, structured N/A, and the schema map.
 
-## When to Use
+## Formal Lifecycle Position
+
+For a formal requirement, `/prizmkit-test` runs after the Main-Agent code-review stage reaches `PASS` and before retrospective:
+
+```text
+plan → implement → code-review → test → retrospective → committer
+```
+
+Read `${SKILL_DIR}/references/workflow-state-protocol.md` before reading or updating lifecycle state. Reuse the caller's `artifact_dir`; do not select another recent plan. When an active `orchestrator` is recorded, return the testing result and next-stage metadata to it instead of invoking another skill independently.
+
+## Atomic Stage Boundary
+
+`prizmkit-test` owns only auditable test evidence generation, validation, and the testing-domain verdict. It writes the authoritative `TEST_*` result and `next_stage`, then returns control. When an external orchestrator is active, it must not invoke retrospective or implementation itself. The active orchestrator owns the next-stage invocation and repair routing.
 
-Use for:
 
 - behavior-changing source code;
 - runtime configuration, schema, migration, generated-runtime, lockfile, or dependency changes;
@@ -35,6 +46,7 @@ Documentation, comment, and formatting-only scopes use deterministic lightweight
 3. Preserve complete command/environment/output values as requested. Mark the package `sensitivity=project-controlled`; the project owns access control, retention, and upload policy.
 4. Treat code-level dependencies as mock-first. Real deployed test-environment validation is a separate authorized activity.
 5. Never delete existing tests.
+6. For `TEST_FAIL`, classify and persist an evidence-backed `repair_scope` of `test-infrastructure`, `production`, `runtime`, `schema`, `dependency`, `public-interface`, or `unknown`. Test-infrastructure scope routes to implement then test; production-family scope routes to implement, code-review, then test. If evidence cannot support a safe classification, return `TEST_BLOCKED`.
 
 If test infrastructure is missing, the infrastructure preparation state establishes only the necessary project-native infrastructure autonomously. Do not ask the user to install routine test dependencies in a headless run; verify dependency versions before editing manifests.
 
@@ -171,7 +183,7 @@ Create `.prizmkit/test/evidence/<evidence-id>/` from the package template with:
 - `contracts/` snapshots
 - derived `test-report.md`
 
-Hash baseline, diff, the stable source snapshot, inventoried source/tests/contracts/lockfiles, environment, plan, and every evidence file. Runtime state, evidence output, linked Agent worktrees, Git metadata, and bytecode caches are outside source identity; evidence files remain independently content-addressed through `manifest.json`. Set `environment_claim=mocked-code-level-only` and `compatibility=legacy-test-report-interface-not-supported`.
+Hash baseline, diff, the stable source snapshot, inventoried source/tests/contracts/lockfiles, environment, plan, and every evidence file. Runtime state, evidence output, linked Agent worktrees, Git metadata, and bytecode caches are outside source identity; evidence files remain independently content-addressed through `manifest.json`. Set `environment_claim=mocked-code-level-only`.
 
 ### 9. EVIDENCE_VALIDATE
 
@@ -203,11 +215,17 @@ For a large module or bounded budget, persist matrix/checkpoint progress and ret
 Only these testing-domain outcomes are valid:
 
 - `TEST_PASS`: every required module behavior/risk and Regression Ring check is proven, required executions pass reliably, cleanup succeeds, no verdict-capable unresolved edge remains, and deterministic validation passes.
-- `TEST_FAIL`: a valid reliable test reproduces an implementation or resolved-contract failure.
+- `TEST_FAIL`: a valid reliable test reproduces an implementation or resolved-contract failure. The authoritative verdict record must include `repair_scope` and enough evidence for the next stage to route safely.
 - `TEST_BLOCKED`: unknown scope, conflicting truth, unavailable/unreliable/flaky necessary execution, incomplete evidence, unproven tests, failed cleanup, budget truncation, or deterministic validation failure.
 
 No conditional pass exists.
 
+## Workflow State and Handoff
+
+Before writing state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
+
+On `TEST_PASS`, update the active workflow state with `status=TEST_PASS`, `stage_result=TEST_PASS`, and `next_stage=retrospective`. On `TEST_FAIL`, persist the evidence-backed `repair_scope`, set `status=TEST_FAIL` and `stage_result=TEST_FAIL`, and return to implementation; test-infrastructure scope selects `next_stage=implement` with a direct test resume, while production-family scope selects `next_stage=implement` and requires code review before testing again. On `TEST_BLOCKED`, preserve the blocker, do not modify production code speculatively, and return a blocked result. The authoritative verdict is the validated evidence record; the derived Markdown report is only a compatibility view. If an active orchestrator exists, return the terminal result and `next_stage` to it; do not invoke the next skill independently.
+
 ## Derived Report and Handoff
 
 Generate `test-report.md` from structured evidence using `${SKILL_DIR}/references/test-report-template.md`. It is a replaceable view, not the source of truth. Report only:
@@ -216,9 +234,13 @@ Generate `test-report.md` from structured evidence using `${SKILL_DIR}/reference
 - evidence directory and ID;
 - validator result and key execution pointers;
 - sensitivity and mocked-versus-real warning;
-- explicit notice that the legacy test-report interface is not supported.
+- authoritative evidence pointers for external automation and interactive consumers.
+
+Do not embed an independent AI reviewer, decide overall code quality, claim broad Spec compliance, repair a validly detected business defect, authorize commit/release, or perform deployed test/production validation. The derived report is a view; `verdict.json`, validation records, and the evidence manifest remain authoritative.
+
+## Compatibility
 
-Do not embed an independent AI reviewer, decide overall code quality, claim broad Spec compliance, repair a validly detected business defect, authorize commit/release, or perform deployed test/production validation.
+Consumers must read authoritative `TEST_*` evidence. During migration, a legacy Markdown report may be used only as a compatibility view after the authoritative verdict has passed validation.
 
 Existing Pipeline and Skill consumers are not migrated by this protocol. Temporary post-install incompatibility with callers expecting the legacy report is accepted and must be stated, not hidden.
 

package/bundled/skills/prizmkit-test/references/examples.md

@@ -99,4 +99,4 @@ A comments-only diff is deterministically classified and parser/format/generated
 
 ## Compatibility Notice
 
-The legacy `PASS | NEEDS_FIXES | BLOCKED` Markdown report interface is intentionally not preserved. Existing Pipeline and Skill consumers are not migrated here and may be temporarily incompatible after installation.
+The testing-domain verdict remains `TEST_PASS | TEST_FAIL | TEST_BLOCKED`. Consumers must use validated authoritative evidence and may use `test-report.md` only as a derived compatibility view. The formal lifecycle does not reinterpret a testing result as a review or commit verdict.

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

@@ -78,7 +78,7 @@ Verdict: TEST_PASS | TEST_FAIL | TEST_BLOCKED
 - Real deployed environment validated: no
 
 ## Compatibility
-The legacy test-report interface is not supported. Existing Pipeline or other Skill consumers were not migrated and may be temporarily incompatible after installation.
+The formal lifecycle consumes validated authoritative `TEST_*` evidence through workflow state and structured evidence pointers. `test-report.md` is a derived compatibility view and must not be interpreted as a review, retrospective, commit, or release verdict.
 ```
 
 ## Verdict Rendering Rules

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

@@ -0,0 +1,181 @@
+# PrizmKit Workflow State Protocol
+
+`workflow-state.json` is lifecycle runtime metadata for one formal requirement. It preserves stage handoff, repair routing, orchestrator ownership, and resume information without replacing authoritative artifacts or any host-owned execution checkpoint.
+
+## Location and Identity
+
+```text
+.prizmkit/state/workflows/<requirement-slug>.json
+```
+
+The state file is created only when a lifecycle runs. The active `artifact_dir` is the generic requirement artifact root and must be preserved exactly across every stage:
+
+```text
+.prizmkit/specs/<requirement-slug>/
+.prizmkit/bugfix/<bug-id>/
+.prizmkit/refactor/<refactor-id>/
+```
+
+Never select a different most-recent plan when resuming or handing off. Any execution checkpoint maintained by an external host remains separate from this lifecycle state. Never merge, substitute, or infer one schema from the other. The target project controls whether generated `.prizmkit/` files are committed, ignored, or shared.
+
+## Authority
+
+The state file is an index, not the authority for stage completion:
+
+| Information | Authority |
+|---|---|
+| Requirement goals and acceptance criteria | `{artifact_dir}/spec.md` |
+| Implementation tasks and completion | `{artifact_dir}/plan.md` plus current workspace |
+| Review findings and verdict | `{artifact_dir}/review-report.md` final result |
+| Test execution, verdict, and repair scope | Validated evidence package and authoritative `verdict.json` |
+| Test report presentation | `{artifact_dir}/test-report.md` as a derived view only |
+| Retrospective completion and result | `{artifact_dir}/retrospective-result.json` |
+| Durable architecture knowledge | `.prizmkit/prizm-docs/` |
+| Local commit | Git history and confirmed or authorized commit identity |
+| Current stage, orchestrator, and resume entry | Workflow state |
+| External orchestration progress | The external host's own checkpoint, never this state |
+
+Every consumer compares workflow state with authoritative artifacts and the current workspace. Missing or stale state is reconstructed from those sources and is never accepted as success by itself.
+
+## Schema
+
+```json
+{
+  "schema_version": 1,
+  "artifact_dir": ".prizmkit/specs/example",
+  "orchestrator": "prizmkit-workflow",
+  "stage": "test",
+  "status": "TEST_PASS",
+  "stage_result": "TEST_PASS",
+  "completed_stages": ["plan", "implement", "code-review", "test"],
+  "repair_scope": null,
+  "repair_round": 0,
+  "next_stage": "retrospective",
+  "resume_from": "prizmkit-retrospective"
+}
+```
+
+### Fields
+
+| Field | Meaning |
+|---|---|
+| `schema_version` | State schema version. Current value is `1`. |
+| `artifact_dir` | The single generic requirement artifact root reused by every stage. |
+| `orchestrator` | `prizmkit-workflow`, another semantic coordinator identifier, or `null` for direct stage use. |
+| `stage` | The stage that most recently wrote state. |
+| `status` | Lifecycle progression status, distinct from the domain `stage_result`. |
+| `stage_result` | Domain result such as `PASS`, `NEEDS_FIXES`, `TEST_*`, `DOCS_UPDATED`, or `NO_DOC_CHANGE`. |
+| `completed_stages` | Ordered stages completed for this requirement. |
+| `repair_scope` | `null`, `test-infrastructure`, `production`, `runtime`, `schema`, `dependency`, `public-interface`, or `unknown`. |
+| `repair_round` | Outer cross-stage repair round, from `0` through `3`. |
+| `next_stage` | Next semantic stage, or `null` after commit. |
+| `resume_from` | Exact atomic skill that can resume, or `null` after commit. |
+
+## Lifecycle and Verdict Mappings
+
+The mandatory formal lifecycle is:
+
+```text
+PLAN_READY
+  → IMPLEMENTED
+  → REVIEW_PASS
+  → TEST_PASS
+  → RETRO_COMPLETE
+  → COMMIT_PENDING
+  → COMMITTED
+```
+
+No formal stage is silently optional. Domain evidence maps as follows:
+
+```text
+review-report final PASS        → status=REVIEW_PASS, stage_result=PASS
+review-report final NEEDS_FIXES → status=REVIEW_NEEDS_FIXES, stage_result=NEEDS_FIXES
+validated verdict TEST_PASS     → status=TEST_PASS, stage_result=TEST_PASS
+validated verdict TEST_FAIL     → status=TEST_FAIL, stage_result=TEST_FAIL
+validated verdict TEST_BLOCKED  → status=TEST_BLOCKED, stage_result=TEST_BLOCKED
+retrospective result DOCS_UPDATED  → status=RETRO_COMPLETE, stage_result=DOCS_UPDATED
+retrospective result NO_DOC_CHANGE → status=RETRO_COMPLETE, stage_result=NO_DOC_CHANGE
+```
+
+`RETRO_COMPLETE` is the stable completion status. `DOCS_UPDATED` and `NO_DOC_CHANGE` are mutually exclusive retrospective results, not substitute statuses. A derived Markdown test report never establishes a `TEST_*` status without validated authoritative evidence.
+
+## Repair Routing
+
+```text
+REVIEW_NEEDS_FIXES
+  → implement
+  → code-review
+  → test
+
+TEST_FAIL with repair_scope=test-infrastructure
+  → implement
+  → test
+
+TEST_FAIL with repair_scope=production|runtime|schema|dependency|public-interface
+  → implement
+  → code-review
+  → test
+
+TEST_FAIL with repair_scope=unknown
+  → conservative production route only when safe
+  → otherwise WORKFLOW_BLOCKED
+
+TEST_BLOCKED
+  → never make speculative production edits
+  → interactive execution stops with a prizmkit-test resume entry
+  → a trusted headless host may perform bounded environment recovery, then records WORKFLOW_BLOCKED if unresolved
+
+RETRO_BLOCKED
+  → WORKFLOW_BLOCKED
+WORKFLOW_BLOCKED
+  → resume only after the recorded blocker is resolved
+```
+
+The outer workflow permits at most three automatic repair rounds. These are cross-stage rounds (`repair_round` `0` through `3`). The code-review internal loop permits at most ten completed review rounds and is separate; review-internal repairs do not increment the outer counter.
+
+## Orchestrator Ownership and Handoff
+
+1. An atomic stage performs only its own stage, writes the truthful terminal result and `next_stage`, and returns control.
+2. When `orchestrator` is non-null, only that orchestrator invokes the next skill. The atomic stage must not auto-invoke it again.
+3. Direct stage use may report one deterministic next invocation but does not claim the next stage ran.
+4. Every handoff preserves the same `artifact_dir`.
+5. External automation invokes atomic stages directly and does not invoke `prizmkit-workflow` as a nested coordinator.
+6. Workflow state never replaces or absorbs an external host's checkpoint.
+
+## Commit Authorization
+
+Interactive execution:
+
+```text
+committer previews intended files and message
+→ waits for explicit confirmation from the current user
+→ creates the local commit
+```
+
+Trusted headless execution:
+
+```text
+a trusted host explicitly authorizes the current local task commit
+→ host injects mode=<host-defined-headless-mode>, owner=<trusted-host-identifier>,
+  local_commit_authorized=true, push_authorized=false
+→ committer verifies gates and commits automatically
+→ no question, wait, or push is permitted
+```
+
+A self-declared or otherwise untrusted headless context does not authorize a commit. Push is never implied by either mode.
+
+## Recovery
+
+When state is missing, stale, or inconsistent:
+
+1. Read `spec.md` and `plan.md` from `artifact_dir` only when they are not already available in current context.
+2. Inspect task markers and the current workspace.
+3. Read the latest review report and final result when needed to establish review authority.
+4. Validate authoritative test evidence and `repair_scope`.
+5. Validate `retrospective-result.json` when retrospective is claimed complete.
+6. Verify the commit when commit is claimed complete.
+7. When an external host is active, let that host validate its own checkpoint independently; never merge the schemas.
+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 host checkpoint enforcement.

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

@@ -0,0 +1,266 @@
+---
+name: "prizmkit-workflow"
+description: "Coordinate one explicitly requested formal software requirement through the complete PrizmKit lifecycle from plan to confirmed commit. Use when the user invokes prizmkit-workflow or explicitly asks for the full six-stage lifecycle, a plan-to-commit workflow, or one formal requirement completed end to end. Do not trigger on generic build, implement, feature, bug, or refactor requests; those belong to the applicable individual skill or an external integration. (project)"
+---
+
+# PrizmKit Workflow
+
+`/prizmkit-workflow` is the optional composite entry point for one interactive formal software requirement. The user describes the requirement once; this skill coordinates the six atomic lifecycle skills in order and preserves the same requirement context throughout. It does not replace or reimplement any atomic stage.
+
+```text
+prizmkit-plan
+  → prizmkit-implement
+  → prizmkit-code-review
+  → prizmkit-test
+  → prizmkit-retrospective
+  → prizmkit-committer
+```
+
+The six stages are mandatory for a formal requirement. The order is not a suggestion and no stage is silently optional.
+
+## When to Use
+
+Use this composite entry point when the user:
+
+- explicitly invokes `/prizmkit-workflow`;
+- explicitly asks for the full six-stage PrizmKit lifecycle;
+- asks for one formal requirement to be coordinated from plan through commit;
+- asks for a plan-to-commit or single-requirement full lifecycle;
+- wants the workflow to continue automatically after each successful stage.
+
+Generic "implement", "build", "add feature", "fix bug", or "refactor" requests do not select this workflow by themselves. Use the applicable individual skill unless the user explicitly asks for this complete lifecycle; external integrations may also invoke individual skills through their published contracts.
+
+Use an individual atomic stage skill when the user explicitly wants only planning, implementation, review, testing, documentation maintenance, or committing.
+
+Do not use this skill for:
+
+- a typo, pure formatting change, or explicitly low-risk direct edit;
+- first-time project initialization only; recommend `/prizmkit-init`;
+- standalone Prizm documentation repair; use `/prizmkit-prizm-docs`;
+- deployment or operations; use `/prizmkit-deploy` separately;
+- multiple requirements in one invocation; this composite handles one requirement only.
+
+## Inputs
+
+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;
+- `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.
+
+## Core Orchestration Rules
+
+### 1. Start with Plan
+
+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.
+
+### 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:
+
+```text
+.prizmkit/specs/<requirement-slug>/
+.prizmkit/bugfix/<bug-id>/
+.prizmkit/refactor/<refactor-id>/
+```
+
+Never select a different most-recent plan when resuming or handing off. The workflow state path is:
+
+```text
+.prizmkit/state/workflows/<requirement-slug>.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.
+
+### 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.
+
+Expected transitions:
+
+| Stage | Required success | Next stage |
+|---|---|---|
+| `prizmkit-plan` | `PLAN_READY` | `prizmkit-implement` |
+| `prizmkit-implement` | `IMPLEMENTED` | `prizmkit-code-review` |
+| `prizmkit-code-review` | `REVIEW_PASS` | `prizmkit-test` |
+| `prizmkit-test` | `TEST_PASS` | `prizmkit-retrospective` |
+| `prizmkit-retrospective` | `status=RETRO_COMPLETE` with result `DOCS_UPDATED` or `NO_DOC_CHANGE` | `prizmkit-committer` |
+| `prizmkit-committer` | explicit interactive confirmation, then `COMMITTED` | end |
+
+`TEST_NOT_APPLICABLE` is not a valid lifecycle success. Lightweight changes must execute deterministic verification and return `TEST_PASS`.
+
+### 4. Do Not Duplicate Stage Responsibilities
+
+The composite must not:
+
+- reinterpret a plan as implementation;
+- repair production code outside `prizmkit-implement` or the Main-Agent review loop;
+- claim tests passed without validated authoritative test evidence;
+- treat a derived Markdown report as the test source of truth;
+- perform retrospective documentation changes itself;
+- stage or commit before `prizmkit-committer` applies the current execution's authorization 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.
+
+### Review Failure
+
+`REVIEW_NEEDS_FIXES` maps from the final review report result `NEEDS_FIXES`. Route to:
+
+```text
+prizmkit-implement
+  → prizmkit-code-review
+  → prizmkit-test
+```
+
+The Main-Agent review skill owns its internal review repairs and its internal ten-round limit before returning its terminal result. The outer workflow repair counter is separate.
+
+### Test Failure
+
+`TEST_FAIL` must come from the validated authoritative evidence verdict and include `repair_scope`:
+
+TEST_FAIL affecting only tests, fixtures, test-runner configuration, or evidence infrastructure uses `repair_scope=test-infrastructure`:
+
+```text
+TEST_FAIL with repair_scope=test-infrastructure
+  → prizmkit-implement
+  → prizmkit-test
+```
+
+Test infrastructure includes tests, fixtures, test-runner configuration, and evidence infrastructure only.
+
+TEST_FAIL affecting production code, runtime configuration, schema, dependencies, or public interfaces uses the matching production-family scope:
+
+```text
+TEST_FAIL with repair_scope=production | runtime | schema | dependency | public-interface
+  → prizmkit-implement
+  → prizmkit-code-review
+  → prizmkit-test
+```
+
+Production-affecting repair after `REVIEW_PASS` must receive another review. A test-infrastructure-only repair may return directly to testing. Unknown scope uses the conservative production route only when safe; otherwise the workflow is blocked.
+
+### Environment Block
+
+`TEST_BLOCKED` means trustworthy evidence is unavailable because of environment, permission, dependency, external-service, scope, evidence, reliability, cleanup, or budget problems.
+
+Interactive behavior:
+
+```text
+TEST_BLOCKED
+  → persist the blocker
+  → do not make speculative production edits
+  → 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.
+
+### Repair Limit
+
+The outer orchestrator allows at most three automatic repair rounds. These are cross-stage rounds: one repair route from `implement` through all gates required by the repair scope.
+
+```text
+repair_round: 0 → 1 → 2 → 3
+```
+
+When the limit is reached:
+
+- set workflow status to `WORKFLOW_BLOCKED`;
+- preserve the latest authoritative failure evidence;
+- report completed rounds and unresolved cause;
+- report the exact skill, `artifact_dir`, and state path from which a user may resume after resolving the cause or explicitly authorizing another attempt;
+- do not claim the requirement is complete.
+
+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 execution requires the committer to:
+
+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.
+
+Trusted headless execution is a separate atomic-stage path. It requires a host-defined non-interactive `mode`, a trusted `owner` identifier, `local_commit_authorized=true`, and `push_authorized=false`; it does not ask or wait and never pushes. Unknown headless contexts are blocked. Remote push is never part of this composite workflow's automatic path.
+
+## Automatic Handoff and Manual Fallback
+
+When the host supports semantic skill-to-skill invocation, the active composite invokes the next atomic stage after each permitted success transition.
+
+When it does not:
+
+1. update or verify workflow state;
+2. stop without claiming the next stage ran;
+3. print one exact recovery instruction:
+
+```text
+Next stage: /prizmkit-<skill>
+artifact_dir: <same resolved artifact_dir>
+workflow_state: .prizmkit/state/workflows/<requirement-slug>.json
+```
+
+The user can invoke that one atomic skill and this composite can resume with `resume` later.
+
+## Resume Protocol
+
+On resume:
+
+1. Read the workflow state specified by `resume` or discover the target project's active workflow state.
+2. Read `${SKILL_DIR}/references/workflow-state-protocol.md`.
+3. Verify `spec.md`, `plan.md`, review report, authoritative test evidence, retrospective result, and current workspace against state.
+4. If state is missing or stale, reconstruct the safest recoverable predecessor and report the reconstruction.
+5. Continue from the first incomplete stage; never bypass a required gate based only on stale state.
+6. Preserve the same `artifact_dir` and repair-round count.
+7. When an external host is involved, let it validate its own checkpoint independently; never merge that checkpoint into workflow state.
+
+## Completion Report
+
+At successful completion, report:
+
+```text
+WORKFLOW_COMPLETE
+artifact_dir: <path>
+stages:
+  - PLAN_READY
+  - IMPLEMENTED
+  - REVIEW_PASS
+  - TEST_PASS
+  - RETRO_COMPLETE (DOCS_UPDATED | NO_DOC_CHANGE)
+  - COMMITTED
+commit: <hash>
+push: not performed automatically
+next_action: invoke /prizmkit-deploy separately if deployment is needed
+```
+
+If the user declines interactive commit confirmation, report `COMMIT_PENDING` rather than `WORKFLOW_COMPLETE` and provide the exact `/prizmkit-committer` resume entry.
+
+If blocked, report:
+
+```text
+WORKFLOW_BLOCKED
+stage: <stage>
+reason: <evidence-backed reason>
+repair_round: <0..3>
+resume_from: <skill>
+artifact_dir: <same path>
+```
+
+Never report success for a stage that did not produce its required terminal result.