prizmkit 1.1.130 → 1.1.134

package/bundled/skills/prizmkit-committer/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
+→ committer verifies gates and commits automatically
+→ no question or wait is permitted
+```
+
+A self-declared or otherwise untrusted headless context does not authorize a commit. Remote publication remains a separate host-runtime decision.
+
+## 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-implement/SKILL.md

@@ -1,102 +1,128 @@
 ---
 name: "prizmkit-implement"
-description: "Execute plan.md tasks with a TDD-oriented approach. Respects task ordering, checkpoints, and dependencies for Fast path or Full path change artifacts. Reads Prizm docs before editing; optional inline implementation subagent delegation uses this skill's references and active-checkout/no-worktree constraints. Use after /prizmkit-plan. Trigger on: 'implement', 'build', 'code it', 'start coding', 'execute', 'write the code'. (project)"
+description: "Execute the reviewed plan for a formal PrizmKit requirement, update task checkpoints, preserve the shared workflow artifact directory, and hand off to prizmkit-code-review. Use after prizmkit-plan or when resuming implementation repair. (project)"
 ---
 
 # PrizmKit Implement
 
-### When to Use
-- After `/prizmkit-plan` when ready to write code
-- Fast path or Full path has a `plan.md` with unchecked tasks
-- User says "implement", "build", "code it", "start coding", "develop", or "execute"
+`/prizmkit-implement` executes the tasks in one formal requirement's `plan.md`. It is the implementation stage, including implementation repairs requested by code review or testing.
 
-### When NOT to Use
-- No `plan.md` exists and the task is not a Direct edit — run `/prizmkit-plan` first
-- All tasks in `plan.md` are checked off
-- Direct edit: typo, pure formatting, small docs edit, or tiny config tweak with no behavior impact
-- User is still asking for design/planning rather than implementation
+## When to Use
 
-## Preconditions
+- After `/prizmkit-plan` reports `PLAN_READY`.
+- When workflow state routes a review or test repair back to implementation.
+- When `plan.md` contains unchecked tasks for the active requirement.
+- User says "implement", "build", "code it", "start coding", "develop", or "execute".
 
-| Required Artifact | Check | If Missing |
+## When NOT to Use
+
+- No `spec.md` and `plan.md` exist for the formal requirement.
+- All planned tasks are complete and no repair scope is recorded.
+- The user is still deciding scope or asking for planning.
+- The request is a direct low-risk edit outside the formal requirement lifecycle.
+
+## Preconditions and Artifact Identity
+
+| Required artifact | Check | If missing |
 |---|---|---|
-| `plan.md` with Tasks section | File exists and has unchecked tasks | Run `/prizmkit-plan` |
-| `spec.md` | File exists in same artifact directory | Run `/prizmkit-plan` |
+| `plan.md` with Tasks | Exists and contains incomplete or explicitly repairable work | Return `IMPLEMENT_BLOCKED` and direct the user to `/prizmkit-plan`. |
+| `spec.md` | Exists in the same artifact directory | Return `IMPLEMENT_BLOCKED` and direct the user to `/prizmkit-plan`. |
+| Workflow state | Reusable or reconstructable | Reconstruct from artifacts and report the result when absent or stale. |
 
-Artifact directory: accept `artifact_dir` from caller. If not provided, scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks. When invoked as a handoff step, reuse the previous skill's `artifact_dir`; re-detection can select the wrong change artifact in a multi-task workspace.
+Accept `artifact_dir` from the preceding skill or workflow state. Do not scan for a different most-recent plan when invoked as a handoff. A single requirement must reuse the same `artifact_dir` throughout all stages.
 
 ## Context Loading
 
-Before implementation, load context once:
+Before editing:
 
-1. **Task context**: read `plan.md` and `spec.md`. If companion documents exist in the artifact directory, read only those relevant to the change.
-2. **Architecture context**:
-   - Read `.prizmkit/prizm-docs/root.prizm`.
-   - Read relevant L1 docs for affected modules.
-   - Read relevant L2 docs when they exist, especially INTERFACES, TRAPS, and DECISIONS.
-   - If a relevant L2 doc does not exist, read the target source files as fallback and note that no L2 was available. Do not stop implementation only because L2 is missing; `/prizmkit-retrospective` can create L2 after the change if durable detail exists.
-3. **Dev rules**: if root Prizm docs reference `.prizmkit/rules/<layer>-rules.md`, read the relevant rule files. If a referenced rule file is missing, skip it and continue.
+1. Read `plan.md`, `spec.md`, and only relevant companion artifacts.
+2. Read `.prizmkit/prizm-docs/root.prizm` when present.
+3. Read relevant L1 docs and relevant L2 docs when present.
+4. If an affected L2 doc is missing, read the target source files as fallback and record that no L2 context was available. Do not create L2 merely because it was read; retrospective decides whether durable knowledge warrants it.
+5. Read referenced layer rules when present. If a rule conflicts with the plan, stop and ask the user unless the plan clearly supersedes the rule.
 
-If a dev rule conflicts with `plan.md`, call out the conflict and ask the user unless the plan clearly supersedes the rule.
+## Optional Inline Delegation
 
-## Optional Inline Implementation Subagent Delegation
+The default is direct Main-Agent implementation. If a narrow slice is delegated, use `prompt_reference: ${SKILL_DIR}/references/implementation-subagent-procedure.md` and follow its active-checkout/no-worktree constraints. Delegation is optional implementation detail and does not alter lifecycle handoff or ownership.
 
-The default execution mode is direct Main Agent implementation. If delegation is useful for a narrow implementation slice, use only this skill's local reference:
+## Atomic Stage Boundary
 
-```yaml
-prompt_reference: ${SKILL_DIR}/references/implementation-subagent-procedure.md
-isolation: current-workspace / active-checkout / no-worktree
-subagent_kind: inline implementation prompt, not a platform-installed named agent
-```
+`prizmkit-implement` owns only execution of plan tasks and implementation repairs. It writes its truthful terminal result and `next_stage`, then returns control. When an external orchestrator is active, it must not invoke code review or test itself. The active orchestrator owns the next-stage invocation.
 
-Delegation rules:
-- Read `${SKILL_DIR}/references/implementation-subagent-procedure.md` before preparing the subagent prompt.
-- Pass the expected active checkout git top-level and the exact delegated task/file scope.
-- Do not use worktree isolation, copied checkouts, remote isolated checkouts, branch switching, or a platform-installed named implementation agent.
-- If active-checkout/no-worktree launch cannot be satisfied, stop with:
+## Execution
 
-```text
-Cannot delegate /prizmkit-implement because this platform cannot start an inline implementation subagent in the active checkout without worktree, copy, remote, or branch isolation.
-```
+For each unchecked or explicitly repair-scoped task, in plan order:
 
-## Execution
+1. Confirm the target scope and relevant context.
+2. Apply TDD when appropriate:
+   - add or update a failing test first for behavior changes;
+   - use the smallest meaningful verification for docs, configuration, UI-only, or mechanical changes.
+3. Cover relevant happy paths, domain edges, and errors without inventing meaningless tests.
+4. Avoid unrelated edits and preserve the requirement's artifact identity.
+5. Mark a task complete immediately after its implementation is complete.
+6. Stop dependent tasks on failure; run `[P]` tasks in parallel only when safe.
+7. Execute only local implementation verification here. The mandatory full lifecycle code review follows implementation and the mandatory auditable test stage follows code review.
+
+### Repair Scope
+
+When routed from a failed test or review, read `repair_scope` from workflow state and constrain edits accordingly:
 
-For each unchecked task in `plan.md`, in order:
-
-1. Confirm relevant context for the target files is loaded: L1, L2 when present, or source fallback when L2 is absent.
-2. Apply TDD where applicable:
-   - Write or update a failing test first for behavior changes.
-   - For UI-only, docs, configuration, or mechanical refactors where test-first does not apply, use the smallest meaningful verification instead.
-3. Follow internal ID hygiene: do not place PrizmKit feature/bug/refactor IDs, task IDs, session/run IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths in `.prizmkit/prizm-docs/`, user-visible UI text, API responses, emails, notifications, or tests that assert visible product copy.
-4. Cover relevant paths for changed logic:
-   - happy path
-   - domain-specific edge cases
-   - error conditions
-   Do not force meaningless edge/error tests when the function has none.
-5. Avoid redundant tests. Check existing coverage before adding a new test; each new test should exercise a distinct behavior or boundary.
-6. Test your own code and integration points, not framework internals, third-party library internals, or language built-ins.
-7. Mark the task as `[x]` immediately after completion. Immediate marking makes interrupted sessions resumable.
-8. Respect task semantics:
-   - Sequential tasks stop on failure when later tasks depend on them.
-   - `[P]` tasks may run in parallel within the same safe group.
-   - `CP:` checkpoint tasks require build/tests/verification specified by the plan before continuing.
-9. After all tasks complete, run the verification appropriate to the chosen path and risk. Full test orchestration via `/prizmkit-test` is risk-triggered, not mandatory for every change.
+- `production`, `runtime`, `schema`, `dependency`, or `public-interface`: production-affecting changes. Completion must hand off to `prizmkit-code-review`.
+- `test-infrastructure`: tests, fixtures, test runner configuration, or evidence setup only. Completion may hand off directly to `prizmkit-test`.
+- `unknown`: stop and ask the user; do not guess which downstream gates can be skipped.
 
 ## Recovery
 
-If a session is interrupted:
+If interrupted:
+
+- Reuse completed task markers and the same `artifact_dir`.
+- Inspect any partially edited files before continuing.
+- Reconcile workflow state with the plan and current diff.
+- Never report `IMPLEMENTED` when incomplete tasks or unresolved repair work remain.
+
+## Workflow State
+
+Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
 
-- Completed tasks should already be marked `[x]`.
-- Re-run `/prizmkit-implement`; it resumes from the first unchecked task.
-- If partially edited files exist without a completed task marker, inspect the diff and either finish the task or revert incomplete work before continuing.
+On successful implementation, update `.prizmkit/state/workflows/<requirement-slug>.json` with:
 
-## Output
+```json
+{
+  "stage": "implement",
+  "status": "IMPLEMENTED",
+  "completed_stages": ["plan", "implement"],
+  "repair_round": 0,
+  "repair_scope": null,
+  "next_stage": "code-review",
+  "resume_from": "prizmkit-code-review"
+}
+```
+
+For a repair, increment `repair_round`, set `status` to `IMPLEMENT_REPAIR`, preserve the triggering failure in the state, and select the next stage according to `repair_scope`. The outer workflow permits at most three repair rounds; the implementation stage must return a blocked result rather than start a fourth round.
+
+## Output and Handoff
+
+Report:
+
+- implementation summary;
+- completed and remaining tasks;
+- files changed;
+- local verification performed;
+- workflow state path and status;
+- exact next stage.
+
+On initial implementation or a production-affecting repair:
+
+```text
+IMPLEMENTED
+  → /prizmkit-code-review
+```
+
+On a test-infrastructure-only repair:
+
+```text
+IMPLEMENTED
+  → /prizmkit-test
+```
 
-- Code files created/modified as specified in `plan.md`
-- `plan.md` Tasks section updated with `[x]` markers
-- Implementation summary
-- Suggested next step:
-  - Full path or review-triggered risk: `/prizmkit-code-review`
-  - Risk-triggered testing: `/prizmkit-test`
-  - Docs/durable knowledge changed: `/prizmkit-retrospective`
-  - Otherwise: `/prizmkit-committer`
+If workflow state names an active `orchestrator`, return the terminal result, state path, and selected next stage to it; do not invoke another stage independently. For direct stage use, provide the deterministic next invocation with the same `artifact_dir`; a host may perform that semantic handoff on the user's behalf.

package/bundled/skills/prizmkit-implement/references/implementation-subagent-procedure.md

@@ -10,7 +10,7 @@ The Main Agent must provide:
 - The exact plan tasks or files delegated.
 - Any loaded Prizm docs traps/rules relevant to the delegated files.
 
-The implementation subagent must run in the same active checkout as the Main Agent.
+The implementation subagent must run in the same active checkout as the Main Agent. This is an inline subagent constraint, not a permission to create an isolated execution unit or worktree.
 
 ## Active Checkout Guard
 

package/bundled/skills/prizmkit-implement/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
+→ committer verifies gates and commits automatically
+→ no question or wait is permitted
+```
+
+A self-declared or otherwise untrusted headless context does not authorize a commit. Remote publication remains a separate host-runtime decision.
+
+## 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-init/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: "prizmkit-init"
-description: "Project takeover and bootstrap. Scans any project, generates Prizm docs and project brief. Use this skill whenever a user opens a new project for the first time, says 'initialize', 'set up PrizmKit', 'take over this project', 'bootstrap', 'scan this codebase', 'init', or when .prizmkit/prizm-docs/ doesn't exist yet. Also use when PrizmKit was just installed via npx but not yet initialized. (project)"
+description: "Recommended one-time project initialization for PrizmKit. Scans greenfield or brownfield projects, generates Prizm docs and a project brief, and prepares optional context for the formal requirement lifecycle. Use for initialize, bootstrap, take over this project, or first-time setup requests. (project)"
 ---
 
 # PrizmKit Init
 
-Project takeover and bootstrap skill. Scans any project (brownfield or greenfield), generates Prizm documentation and project brief. Supports Codex, Claude Code, CodeBuddy, and multi-platform installations.
+Recommended project initialization skill. Scans any brownfield or greenfield project, generates Prizm documentation and a project brief, and adapts to the current AI coding host when platform-specific instruction files are present.
 
 ### When to Use
 - Taking over a new project (brownfield or greenfield)
 - User says "initialize PrizmKit", "set up PrizmKit", "take over this project"
 - First time using PrizmKit on a project
-- After `npx prizmkit install` when project has no `.prizmkit/prizm-docs/`
+- After the PrizmKit skills are installed (for example with `npx skills add`) when the project has no `.prizmkit/prizm-docs/`
 
 ### When NOT to Use
 - All artifacts exist and are up to date → skip init; use `/prizmkit-prizm-docs` Status/Validate for health checks
@@ -26,7 +26,7 @@ Project takeover and bootstrap skill. Scans any project (brownfield or greenfiel
 ## Execution Steps
 
 **Phase 1: Platform Detection**
-1. Detect which platform is running (Codex, Claude Code, or CodeBuddy) via AI CLI environment.
+1. Detect the current AI coding host through available environment signals. Platform-specific files such as `AGENTS.md`, `CLAUDE.md`, or `CODEBUDDY.md` are non-exhaustive examples, not protocol identifiers.
 2. Hold detected platform value in memory — written to disk in Phase 6 along with other config fields.
 
 **Phase 2: Mode Detection**
@@ -140,7 +140,7 @@ Detect database and deployment signals, then ask 1-2 brief questions. This phase
    - If "SaaS platform": follow up with platform selection (Vercel / Railway / Fly.io / Cloudflare / AWS / Other)
 
 3. **Write results**:
-   - Append `### Infrastructure` section to the detected **main** platform instruction file (`AGENTS.md` for Codex, `CLAUDE.md` for Claude Code, `CODEBUDDY.md` for CodeBuddy). Do not write Infrastructure to `AGENTS.private.md`, `CLAUDE.private.md`, or `CODEBUDDY.private.md`; private files are reserved for PrizmKit framework protocol imports. Format:
+   - Append `### Infrastructure` to the detected host's main instruction file when that file exists. Use the host's conventional main instruction file; examples include `AGENTS.md`, `CLAUDE.md`, and `CODEBUDDY.md`. Do not write Infrastructure to private instruction files reserved for framework protocol imports. Format:
      ```markdown
      ### Infrastructure