prizmkit 1.1.129 → 1.1.131

package/bundled/skills/prizmkit-code-review/SKILL.md

@@ -1,55 +1,64 @@
 ---
 name: "prizmkit-code-review"
-description: "Review the complete current change in a bounded Main-Agent loop. Adjudicate findings with evidence, directly repair accepted findings, verify repairs, and append progress until the review converges to PASS or stops with unresolved findings as NEEDS_FIXES. (project)"
+description: "Review the complete current change for a formal PrizmKit requirement in a bounded Main-Agent loop. Directly repair accepted findings, verify repairs, converge to PASS or stop with NEEDS_FIXES, and hand off to prizmkit-test. (project)"
 ---
 
 # PrizmKit Code Review
 
-Use one Main-Agent review loop. The current Main Agent is the only Code Review executor: it performs the complete review, filters candidate findings, repairs accepted findings, verifies the repairs, and decides the final result.
+`/prizmkit-code-review` is the mandatory review stage after implementation and before the full test stage. The current Main Agent is the only Code Review executor. It owns the complete review loop: it discovers findings, adjudicates them, directly repairs accepted findings, verifies repairs, and continues until the review converges or stops safely.
 
 ## Execution Boundary
 
 - Do not delegate any part of Code Review directly or indirectly.
 - Do not invoke another review skill or review workflow from inside this skill.
 - Do not launch review work through a general-purpose execution unit or relabel it as a finder, verifier, audit, compatibility review, verification, or gap sweep.
-- These restrictions apply for the entire review phase, including candidate discovery, evidence checks, repair verification, and final gap analysis.
-- The Main Agent may directly use non-delegating read, search, edit, and test capabilities in the active workspace.
-- `{artifact_dir}/review-report.md` is the only persisted review artifact. Do not append separate Review Notes to `context-snapshot.md`.
+- The Main Agent may directly read, search, edit, and run targeted verification in the active workspace.
+- Review repairs occur before the full `/prizmkit-test` stage so final test evidence represents the final reviewed workspace.
+- `{artifact_dir}/review-report.md` is the only persisted review artifact for this execution.
+
+## Atomic Stage Boundary
+
+`prizmkit-code-review` owns only the complete Main-Agent review, accepted-finding repairs, and review verification. It writes its truthful terminal result and `next_stage`, then returns control. It must not invoke `prizmkit-test` or `prizmkit-implement` itself; the active orchestrator owns outer repair routing and the next-stage invocation.
 
 ## When to Use
 
-- After `/prizmkit-implement` as the Full path quality gate
-- For Fast path when behavior, impact, or the user warrants review
-- When the user asks to validate implementation, find defects, assess regressions, or decide commit readiness
+- After `/prizmkit-implement` reports `IMPLEMENTED`.
+- After implementation repairs that changed production code, runtime configuration, schema, dependencies, or public interfaces.
+- When workflow state routes a formal requirement back to review after `TEST_FAIL`.
+- When the user asks for a complete review or commit readiness decision.
+
+## When NOT to Use
 
-## Input
+- No valid `spec.md` and `plan.md` exist for the active requirement.
+- Implementation tasks or required repair work remain incomplete.
+- A test-stage environment stop is caused by availability rather than a review concern; resume from test when the environment is available.
+- The request is a direct low-risk edit outside the formal requirement lifecycle.
+
+## Input and State
 
 | Parameter | Required | Description |
 |---|---|---|
-| `artifact_dir` | No | Directory containing `spec.md` and `plan.md`. Reuse a caller-provided directory; otherwise locate the current completed change artifact. |
-
-## Required Asset
+| `artifact_dir` | No | Directory containing `spec.md` and `plan.md`. Reuse the caller's directory or workflow-state value. |
+| `review_scope` | No | `full` for the initial review; `delta` for a production-affecting repair after a prior review pass. |
 
-- `${SKILL_DIR}/references/review-report-template.md`: report lifecycle and append contract
+Every invocation must reuse the same `artifact_dir`. If workflow state is missing, reconstruct it from `spec.md`, `plan.md`, `review-report.md`, the current diff, and any test evidence, and report the reconstruction.
 
-## Phase 0: Initialize Report and Collect Context
+## Phase 0: Initialize Report and Reuse Current Context
 
-1. Resolve `{artifact_dir}` and `{artifact_dir}/review-report.md`.
-2. At the start of every execution, replace any prior report with a new execution header using the report template. The new report begins with `## Status: IN_PROGRESS` and contains no prior Final Result.
-3. Read `spec.md`, `plan.md`, relevant `/prizmkit-test` evidence, `.prizmkit/prizm-docs/root.prizm`, applicable progressive docs, and project rules.
-4. Inspect the complete current Git change:
-   - staged and unstaged tracked changes;
-   - untracked files;
-   - deleted and renamed files;
-   - relevant unchanged callers, dependents, contracts, and tests.
-5. Review in the active workspace so dirty and untracked content is authoritative.
-6. If no changes exist, append final verification and exactly one final result with `PASS`, then finish.
+1. Resolve `{artifact_dir}` and `{artifact_dir}/review-report.md` from the active requirement context.
+2. At the start of each execution, replace any prior report with a new execution header using `${SKILL_DIR}/references/review-report-template.md`.
+3. Within that execution, append progress after every review round, repair batch, final verification, and exactly one `## Final Result`.
+4. Start from the Main Agent's current requirement context and inspect the complete workspace change first: `git status --short`, the staged diff, and the unstaged diff. Include untracked, deleted, and renamed files in the review scope.
+5. Do not reread `spec.md`, `plan.md`, project rules, progressive docs, or unchanged source merely to recreate context the Main Agent already holds. Load only the missing or potentially stale material required to resolve a concrete ambiguity, verify an acceptance criterion, understand a changed contract, or reconstruct missing workflow state.
+6. Inspect unchanged callers, dependents, contracts, or tests only when the diff changes or may violate an interface, shared behavior, or regression boundary. Do not perform an unconditional repository-wide dependency sweep.
+7. For `review_scope=delta`, focus on files and behavior affected since the prior review pass and expand only across contracts implicated by that delta.
+8. If no changes exist, record final verification and `PASS` only when the current requirement context and prior implementation state prove there is nothing left to review.
 
 ## Phase 1: Main-Agent Review Loop
 
-The Main Agent reviews and repairs in the current context. The fixed limit is ten completed review rounds.
+The Main Agent reviews the complete current change, using the active requirement context and expanding beyond the diff only when a concrete acceptance criterion, contract, dependency, or regression risk requires it.
 
-Track cumulative counts:
+Use at most ten completed review rounds per execution. Track:
 
 ```yaml
 main_review_rounds: 0
@@ -59,85 +68,106 @@ rejected_findings: 0
 unresolved_findings: 0
 ```
 
-### Review One Round
+For every candidate finding:
 
-Each round examines the complete current change against goals, contracts, rules, callers, dependents, regression risks, and test evidence.
+1. Describe a reproducible failure scenario, affected behavior, and evidence.
+2. Classify exactly one of:
+   - `accepted`: evidence proves an in-scope repair is needed;
+   - `rejected`: evidence disproves the failure scenario;
+   - `unresolved`: correctness or safe repair cannot be established.
+3. Treat Missing tools, permissions, environment, or required evidence as an unresolved finding when they prevent review verification.
+4. If a repair cannot be completed safely, record an unresolved finding and return `NEEDS_FIXES`.
+5. Append the review round to `review-report.md`.
 
-1. Identify concrete candidate findings. A finding must describe a reproducible failure scenario, affected behavior, and supporting evidence.
-2. Classify each candidate as exactly one of:
-   - `accepted`: concrete evidence supports the failure scenario and an in-scope repair is required;
-   - `rejected`: code, tests, contracts, or governing evidence disproves the failure scenario;
-   - `unresolved`: correctness cannot be established or repaired safely with the available evidence or environment.
-3. Treat Missing tools, permissions, environment, or required evidence as an unresolved finding when they prevent required verification. Do not treat missing evidence as success.
-4. Append `## Main Review Round N` with findings, accepted, rejected, unresolved, and the next action.
-5. Apply these rules:
+Round behavior:
 
 ```text
-accepted = 0 and unresolved = 0                     -> review converged
-accepted > 0 and round < 10                         -> Main Agent directly repairs, verifies, and continues
-accepted > 0 at ten completed review rounds         -> NEEDS_FIXES
-unresolved > 0                                      -> NEEDS_FIXES
-repair cannot be completed safely                   -> unresolved finding -> NEEDS_FIXES
-required verification fails or cannot be performed -> unresolved finding -> NEEDS_FIXES
-```
+accepted = 0 and unresolved = 0
+  → review converged
+  → when all candidate findings are rejected, accepted remains 0 and the review converges
 
-When all candidate findings are rejected, `accepted = 0` and `unresolved = 0`, so the review converges. Rejected findings do not cause another round.
+accepted > 0 and rounds remain
+  → Main Agent directly repairs accepted findings
+  → targeted verification
+  → next complete review round
+
+unresolved > 0 or safe repair impossible
+  → NEEDS_FIXES
+
+maximum ten completed rounds reached with accepted findings
+  → NEEDS_FIXES
+```
 
 ## Phase 2: Repair and Verification
 
-When a round has accepted findings and fewer than ten rounds have completed:
+For accepted findings while the round limit remains:
 
-1. Main Agent directly repairs every accepted in-scope finding in the active workspace.
-2. Run targeted tests, static checks, or other verification appropriate to each repaired behavior.
-3. Inspect resulting changes and ensure the repair did not introduce a new regression.
-4. Append `## Repair Verification` with fixed findings, verification evidence, and the next round.
-5. Start the next complete review round.
+1. Repair directly in the active workspace.
+2. Run targeted tests, static checks, or other verification appropriate to each repair.
+3. Inspect the complete resulting diff for unrelated changes and regressions.
+4. Append repair verification and continue the review loop.
 
-If a repair is unsafe, incomplete, or cannot receive required verification, record the affected finding as unresolved and finish with `NEEDS_FIXES`.
+Do not run the full auditable testing protocol as a substitute for this review stage. The full testing stage follows only after review `PASS`.
 
-## Phase 3: Append-Only Reporting
+If a repair is unsafe, incomplete, or unverifiable, record an unresolved finding and finish with `NEEDS_FIXES`.
 
-`{artifact_dir}/review-report.md` is the only required persisted review artifact.
+## Phase 3: Final Result
 
-Within one execution, append new sections only. Do not rewrite an earlier progress section. Append after:
+Before completing:
 
-- every Main-Agent review round;
-- every repair and verification batch;
-- final verification;
-- the final result.
+1. Confirm the final workspace is the complete reviewed change.
+2. Confirm all accepted findings are fixed and no unresolved finding remains for `PASS`.
+3. Append final verification and exactly one final result.
 
-An interrupted execution remains `IN_PROGRESS` and shows its latest completed phase. It has no terminal verdict.
+Valid results:
 
-## Phase 4: Final Verification and Result
+```text
+PASS | NEEDS_FIXES
+```
 
-Before completing:
+`PASS` requires review convergence, no unresolved findings, and credible targeted verification. `NEEDS_FIXES` means an outer implementation repair is required or completion must stop safely.
+
+## Workflow State and Outer Repair Routing
+
+Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
+
+On `PASS`, update workflow state:
 
-1. Confirm the final workspace still represents the complete reviewed change.
-2. Confirm required tests and checks have credible evidence.
-3. Confirm no accepted or unresolved finding remains for `PASS`.
-4. Append `## Final Verification`.
-5. Append exactly one final result:
-
-```markdown
-## Final Result
-
-- Verdict: PASS | NEEDS_FIXES
-- Main Review Rounds: <count>
-- Accepted Findings: <count>
-- Fixed Findings: <count>
-- Rejected Findings: <count>
-- Unresolved Findings: <count>
-- Summary: <concise conclusion>
+```json
+{
+  "stage": "code-review",
+  "status": "REVIEW_PASS",
+  "stage_result": "PASS",
+  "completed_stages": ["plan", "implement", "code-review"],
+  "next_stage": "test",
+  "resume_from": "prizmkit-test"
+}
 ```
 
-Final outcomes:
+On `NEEDS_FIXES` caused by code findings, update workflow state:
+
+```json
+{
+  "stage": "code-review",
+  "status": "REVIEW_NEEDS_FIXES",
+  "stage_result": "NEEDS_FIXES",
+  "repair_scope": "production",
+  "next_stage": "implement",
+  "resume_from": "prizmkit-implement"
+}
+```
+
+Increment the outer `repair_round` only when returning to implementation; the review-internal ten-round loop never increments it. The outer workflow permits at most three repair rounds and must return a truthful unresolved `NEEDS_FIXES` result instead of beginning a fourth.
+
+## Handoff
 
-- `PASS`: review converged with `accepted = 0`, `unresolved = 0`, and required verification evidence is complete.
-- `NEEDS_FIXES`: round ten still has accepted findings, any finding remains unresolved, a repair cannot be completed safely, or required verification is unavailable or failed.
+After `PASS`:
 
-Exactly one final result is allowed. Do not append progress after Final Result.
+```text
+REVIEW_PASS
+  → /prizmkit-test
+```
 
-Completion handoff:
+If workflow state names an active `orchestrator`, return `REVIEW_PASS`, the report/state paths, and `next_stage=test` to it; do not invoke test independently. For direct stage use, report the exact `/prizmkit-test` invocation and same `artifact_dir`; a host may perform that semantic handoff on the user's behalf.
 
-- `PASS`: run `/prizmkit-retrospective` when structural docs or durable knowledge changed; otherwise proceed to `/prizmkit-committer`.
-- `NEEDS_FIXES`: report unresolved findings and stop.
+After `NEEDS_FIXES`, stop and hand off to `/prizmkit-implement`; do not test or commit the unrepaired production change.

package/bundled/skills/prizmkit-code-review/references/review-report-template.md

@@ -74,4 +74,4 @@ Exactly one Final Result terminates a completed execution:
 - An IN_PROGRESS report without Final Result is incomplete.
 - Generic or incidental verdict text outside the last Final Result does not prove completion.
 - Do not append any section after Final Result.
-- Do not persist a separate review-state JSON file.
+- A separate review-state JSON file is not required; the shared workflow state under `.prizmkit/state/workflows/` may record lifecycle handoff and recovery metadata.

package/bundled/skills/prizmkit-code-review/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.