prizmkit 1.1.119 → 1.1.121

package/bundled/skills/prizmkit-code-review/references/reviewer-agent-prompt.md

@@ -1,9 +1,9 @@
-# Reviewer Agent Prompt Template
+# Reviewer Subagent Prompt Template
 
-Used in Phase 1 Step 1 of `/prizmkit-code-review`. The orchestrator fills `{goals}`, `{plan decisions}`, `{scoped test report}`, `{workspace context}`, `{dev rules}`, `{round N}`, and `{round_context}` before spawning the dedicated `prizm-dev-team-reviewer` agent.
+Used in Phase 1 Step 1 of `/prizmkit-code-review`. The orchestrator fills the placeholders before spawning an independent read-only Reviewer under `${SKILL_DIR}/references/reviewer-workspace-protocol.md`.
 
 ```
-You are the dedicated PrizmKit Reviewer agent (`prizm-dev-team-reviewer`). Review workspace changes against the spec goals, plan decisions, scoped test evidence, and per-layer dev rules. Do not modify files and do not apply fixes; the Main Agent will filter findings and apply accepted fixes directly.
+You are the independent read-only Reviewer for `/prizmkit-code-review`. Review the verified workspace snapshot against the spec goals, plan decisions, scoped test evidence, and dev rules. Do not modify files or apply fixes; the Main Agent will filter findings and apply accepted fixes.
 
 ## Spec Goals
 {goals and acceptance criteria from spec.md}
@@ -12,53 +12,67 @@ You are the dedicated PrizmKit Reviewer agent (`prizm-dev-team-reviewer`). Revie
 {architecture decisions and task list from plan.md}
 
 ## Scoped Test Report
-{summary from artifact_dir/test-report-path.txt and test-report.md, including Scope, Generated / Updated Tests, In-Scope Failures, Baseline Failures, Out of Scope Gaps, Boundary Matrix / Boundary Completion Gate if present, and Verdict. If no scoped report exists for a change artifact, write "No scoped /prizmkit-test report found (expected for pre-test review)." Treat that absence as informational unless the calling workflow explicitly requires a prior test report.}
+{summary from artifact_dir/test-report-path.txt and test-report.md, including Scope, Generated / Updated Tests, In-Scope Failures, Baseline Failures, Out of Scope Gaps, Boundary Matrix / Boundary Completion Gate if present, and Verdict. If no scoped report exists, write "No scoped /prizmkit-test report found (expected for pre-test review)." Treat that absence as informational unless the calling workflow requires a prior report.}
 
-## Workspace Context
-{git status, unstaged diff summary, staged diff summary, current working directory, expected active checkout git top-level, and new-file paths captured by the Main Agent in Phase 0 from the active checkout. This is your primary review scope — use this context to understand what changed. Request targeted file reads only when you need specific line-level detail for a finding, not to re-discover or re-index the repository. Do not read files that are not in the workspace context unless you need them to verify impact (callers, dependents, shared patterns). Do not switch to a separate worktree or repository copy — the Main Agent has provided everything needed to understand the change set.}
+## Workspace Manifest
+{repository and baseline identity, review-round identity, changed path inventory and statuses, staged/unstaged composition, untracked content entries, delete markers, rename pairs, and stable content identities captured by the Main Agent}
 
-## Active Checkout Guard
-The orchestrator must provide the expected active checkout git top-level in Workspace Context. Before reviewing, verify that your current git top-level matches that expected active checkout.
+## Review Payload
+{the reviewable representation of every manifest entry, plus clearly identified unchanged context needed to evaluate callers, dependents, or shared patterns}
 
-If your current checkout is different, or appears to be under `.claude/worktrees/`, `.prizmkit/state/worktrees/`, a remote checkout, or any copied/temporary checkout:
-- Stop immediately.
-- Do not review files.
-- Do not produce normal findings.
-- Report `WRONG_CHECKOUT` and state that `/prizmkit-code-review` cannot continue because the reviewer subagent was not started in the active checkout/no-worktree mode required by this skill.
+## Reviewer Strategy
+{concise description of how the current platform made the snapshot available. This is diagnostic context, not a required parameter contract.}
 
-Worktree review is not supported by `/prizmkit-code-review`; do not continue from a worktree even if the files appear similar.
+## Workspace Equivalence Guard
+Validate the supplied manifest and payload according to the Reviewer Workspace Protocol before normal review:
+- Every manifest path and state must be represented.
+- Staged, unstaged, untracked, deleted, and renamed changes must not be silently lost.
+- Changed content identities and review-round identity must match.
+- Unexplained changed paths, stale content, or unverifiable entries are mismatches.
 
-## Dev Rules (per-layer conventions)
+Do not reject a snapshot merely because its physical path, checkout layout, branch label, host, or transport differs from the Main Agent's environment. Content equivalence is the invariant.
+
+If equivalence cannot be proven:
+- Stop before normal review.
+- Do not produce ordinary findings.
+- Return `WORKSPACE_MISMATCH` with concrete mismatch evidence and required corrective action.
+
+## Dev Rules
 {rules from .prizmkit/rules/<layer>-rules.md, or "No custom dev rules configured — use general best practices."}
 
 ## Review Round
 Round {N}. {round_context}
 
 ## What to Review
-Use the orchestrator-provided workspace context as the source of truth for changed files:
-- For new files listed in workspace status, read their full content.
-- For modified files, read enough surrounding context to understand the change.
-- Do not edit files, stage changes, run test suites, or spawn other agents.
-- Do not request or create worktrees — you are reviewing the active checkout's changes. The orchestrator has already captured the full diff and status context; re-discovering the whole repository is wasteful and unnecessary.
+Use the verified workspace snapshot as the primary review scope:
+- Read the full content of new files.
+- For modified files, read enough surrounding context to understand behavior and impact.
+- Read unchanged callers, dependents, or shared patterns only when needed to verify a potential finding.
+- Do not edit files, stage changes, run tools that modify the review view, spawn other agents, or apply fixes.
+- Do not broadly re-index the repository when the supplied snapshot and targeted reads are sufficient.
 
 ## Review Dimensions
-Evaluate the changes across these dimensions (focus on what's relevant):
+Evaluate the relevant dimensions:
 
-1. **Goal alignment**: Do the changes accomplish all goals from spec.md? Anything missing or off-target?
-2. **Defects**: Logic bugs, missing error handling, boundary condition issues, incorrect behavior.
-3. **Completeness**: Files that should have been changed but weren't? Missing tests, types, imports, exports?
-4. **Consistency**: Do changes follow the project's existing patterns, naming conventions, and code style?
-5. **Security**: Hardcoded secrets, injection vulnerabilities, unsafe operations.
-6. **Test quality**: If a scoped `/prizmkit-test` report is present, verify the report scope is `this-change`, the artifact dir matches the reviewed change, generated/updated tests assert real behavior rather than mock success or empty assertions, in-scope failures are not mislabeled as baseline failures, baseline failures are genuinely unrelated or pre-existing, out-of-scope gaps were not turned into unrelated test changes, and the report verdict is compatible with proceeding.
-7. **Rules compliance**: (Skip this dimension if no dev rules were provided.) Do changes follow the per-layer dev rules? Flag violations of framework conventions, naming patterns, state management, or other rules defined for that layer.
+1. **Goal alignment**: Do the changes accomplish the spec goals and acceptance criteria?
+2. **Defects**: Are there logic bugs, boundary failures, or missing error handling?
+3. **Completeness**: Are required files, tests, types, imports, or exports missing?
+4. **Consistency**: Do the changes follow existing project patterns, naming, and style?
+5. **Security**: Do the changes introduce secrets, injection paths, or unsafe operations?
+6. **Test quality**: When a scoped report exists, verify its scope and artifact identity, meaningful assertions, failure classification, boundary evidence, and verdict compatibility.
+7. **Rules compliance**: When dev rules exist, verify the relevant layer conventions.
 
 ## Output Format
-Respond with EXACTLY this format:
+Respond with exactly this structure:
+
+### Result: PASS | NEEDS_FIXES | WORKSPACE_MISMATCH
 
-### Result: PASS | NEEDS_FIXES
+### Snapshot Verification
+- Status: VERIFIED | FAILED
+- Identity: <manifest identity or mismatch summary>
 
 ### Findings
-(If PASS, write "No issues found.")
+(If PASS, write "No issues found." If WORKSPACE_MISMATCH, include only mismatch evidence and required action.)
 
 #### Finding N
 - **Severity**: high | medium | low
@@ -69,10 +83,10 @@ Respond with EXACTLY this format:
 - **Verification**: How to confirm the fix is correct
 
 ### Summary
-One to two sentences about the overall state of the changes.
+One to two sentences about the snapshot and overall state of the changes.
 ```
 
 ## Round Context
 
 - Round 1: "This is the first review. Examine all changes comprehensively."
-- Round 2+: "Previous round found issues that were fixed. Focus on: (1) whether previous fixes are correct, (2) whether fixes introduced new problems, (3) any remaining issues. Do not re-report issues that have already been fixed."
+- Round 2+: "Previous findings were filtered and accepted fixes were applied. Verify those fixes, check for regressions, and identify remaining issues without re-reporting resolved findings."

package/bundled/skills/prizmkit-code-review/references/reviewer-workspace-protocol.md

@@ -0,0 +1,90 @@
+# Reviewer Workspace Protocol
+
+Use this protocol whenever `/prizmkit-code-review` delegates review to an independent Reviewer. The protocol defines observable guarantees, not Agent API parameters, so the Main Agent can adapt to the capabilities of the current platform.
+
+## Protocol Invariants
+
+1. **Independence**: A subagent separate from the Main Agent performs review judgment. The Main Agent may prepare the snapshot, filter findings, and apply fixes, but does not substitute its own review when delegation fails.
+2. **Completeness**: The review snapshot represents every in-scope staged, unstaged, untracked, deleted, and renamed change captured for the round.
+3. **Currency**: Each review round uses a snapshot captured after the previous round's fixes. Never reuse a prior-round snapshot as evidence of current state.
+4. **Equivalence**: The Reviewer's view must be content-equivalent to the captured Main-Agent workspace. Physical path, checkout layout, branch label, host, and transport may differ without violating equivalence.
+5. **Verifiability**: The Reviewer validates the supplied manifest before normal review. Missing, extra, stale, or mixed content produces `WORKSPACE_MISMATCH`, not code findings.
+6. **Read-only review**: The Reviewer does not modify files or apply fixes. This keeps review evidence stable and preserves clear fix ownership.
+
+## Strategy Selection
+
+Choose a platform-supported strategy that can satisfy all protocol invariants. The strategy may use a shared workspace, an isolated workspace populated with the captured change, a remote environment supplied with equivalent content, a materialized snapshot, or another mechanism the platform supports.
+
+Do not encode a particular Agent type, model, isolation value, branch convention, directory prefix, or transport command into the skill contract. Those details are implementation choices and may change across platforms or sessions.
+
+Prefer the least elaborate strategy that can prove equivalence. If a candidate strategy cannot carry or expose all workspace states, choose another strategy rather than weakening the protocol.
+
+## Workspace Manifest
+
+Create a manifest for each round containing enough information to detect an incomplete or stale review view:
+
+- repository identity and baseline revision
+- round number or equivalent monotonic round identity
+- changed path inventory and each path's status
+- staged and unstaged composition when both exist for a path
+- untracked file content required for review
+- deleted-path markers
+- rename source and destination pairs
+- stable content identities for changed content and any review-critical context
+- relevant spec, plan, dev-rule, and scoped-test evidence identities or embedded content
+
+The exact encoding is implementation-defined. Use hashes when available, but another deterministic content identity is acceptable when the environment lacks a hashing utility. A prose summary alone is insufficient when it cannot detect omitted or stale content.
+
+## Review Payload
+
+Provide the Reviewer with both:
+
+1. The manifest used for verification.
+2. A reviewable representation of every manifest entry.
+
+A reviewable representation may be workspace files, complete file content, patches plus required base content, or an equivalent materialization. Diff summaries alone are insufficient for new files or when surrounding code is necessary to evaluate behavior.
+
+Supply targeted dependency or caller context when required to verify impact. Keep that context distinguishable from changed content so the Reviewer does not mistake unchanged files for part of the patch.
+
+## Reviewer Verification
+
+Before normal review, the Reviewer checks:
+
+1. Repository and baseline identity are consistent with the supplied snapshot.
+2. Every changed path in the manifest is available in the review payload.
+3. No unexplained changed path appears outside the manifest.
+4. Staged, unstaged, untracked, deleted, and renamed states are represented without silent loss.
+5. Content identities match the manifest.
+6. The snapshot belongs to the current review round.
+
+When all checks pass, report snapshot verification as `VERIFIED` and proceed with review.
+
+When a check cannot be completed or fails, stop normal review and return:
+
+```text
+### Result: WORKSPACE_MISMATCH
+
+### Snapshot Verification
+- Status: FAILED
+- Mismatch: <missing, extra, stale, or unverifiable manifest entries>
+- Required action: <what the Main Agent must re-capture, transport, or verify>
+```
+
+Do not emit ordinary code findings after `WORKSPACE_MISMATCH`, because findings from an unverified snapshot could misrepresent the current change.
+
+## Round Refresh
+
+After accepted fixes are applied:
+
+1. Discard the previous manifest as current evidence.
+2. Capture a new manifest and review payload from the Main Agent's updated workspace.
+3. Establish a fresh independent Reviewer view using any valid strategy.
+4. Repeat Reviewer verification before the next review.
+
+A platform may reuse an existing Reviewer session only when the refreshed payload replaces stale state and equivalence is verified again.
+
+## Failure Boundary
+
+Retry or change strategy when the mismatch is repairable. Stop when the platform cannot provide an independent Reviewer with a verifiable equivalent snapshot.
+
+Record the failure as an unresolved review blocker with verdict `NEEDS_FIXES`, snapshot verification `FAILED`, and the mismatch evidence. Do not downgrade to Main-Agent self-review, because doing so would satisfy neither the independence invariant nor the user's expectation of an independent quality gate.

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

@@ -1,6 +1,6 @@
 ---
 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; when relevant L2 docs are missing, falls back to target source files and lets /prizmkit-retrospective create L2 later if needed. Use after /prizmkit-plan. Trigger on: 'implement', 'build', 'code it', 'start coding', 'execute', 'write the code'. (project)"
+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)"
 ---
 
 # PrizmKit Implement
@@ -39,6 +39,26 @@ Before implementation, load context once:
 
 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 Implementation Subagent Delegation
+
+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:
+
+```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
+```
+
+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:
+
+```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.
+```
+
 ## Execution
 
 For each unchecked task in `plan.md`, in order:

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

@@ -0,0 +1,67 @@
+# Implementation Subagent Procedure
+
+Use this reference only when `/prizmkit-implement` deliberately delegates implementation work to an inline implementation subagent. The default path remains direct Main Agent implementation. Delegation is allowed only when the active-checkout/no-worktree contract below can be satisfied.
+
+## Launch Contract
+
+The Main Agent must provide:
+- Artifact directory containing `spec.md`, `plan.md`, and `context-snapshot.md` when available.
+- Expected active checkout git top-level from the Main Agent's workspace.
+- 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.
+
+## Active Checkout Guard
+
+Before reading or editing files, verify your current git top-level matches the expected active checkout git top-level provided by the Main Agent.
+
+Stop immediately and report `WRONG_CHECKOUT` if any of these are true:
+- You are running from a git worktree, tool-created worktree, `.claude/worktrees/`, `.prizmkit/state/worktrees/`, copied repository checkout, remote isolated checkout, or temporary clone.
+- Your current git top-level differs from the expected active checkout git top-level.
+- You are on a different branch because the launch path switched branches.
+- You would need to create or enter another checkout to complete the work.
+
+Do not create worktrees, copied repositories, remote checkouts, or branch switches. Do not continue from the wrong checkout even if files appear identical.
+
+## Context Loading
+
+1. Read `context-snapshot.md` first when it exists.
+2. Use Section 3 for relevant Prizm rules/traps and Section 4 File Manifest for file summaries.
+3. Do not re-read files already summarized in the File Manifest unless a specific implementation detail is missing.
+4. If no context snapshot exists, read `.prizmkit/prizm-docs/root.prizm`, relevant L1/L2 docs, then targeted source files.
+5. If a relevant L2 doc is missing, use source fallback and note that retrospective may create or update docs later.
+
+## Implementation Rules
+
+- Implement only the tasks delegated by the Main Agent and follow `plan.md` task order.
+- Use TDD where meaningful: update/write the smallest relevant test first for behavior changes, then implement, then run the smallest useful check.
+- For docs/config/mechanical refactors where test-first is not meaningful, use the smallest verification that proves the change.
+- Mark delegated `plan.md` tasks `[x]` immediately after completion when the Main Agent explicitly authorizes task marking; otherwise report completed task IDs to the Main Agent for marking.
+- Do not execute git `add`, `commit`, `reset`, `push`, branch checkout, rebase, merge, or stash operations.
+- Do not spawn further agents.
+- Do not perform broad repository rediscovery. Read only delegated files and targeted dependencies needed for correctness.
+- Do not write PrizmKit feature/bug/refactor/task/session/run IDs, pipeline IDs, workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths into `.prizmkit/prizm-docs/`, user-visible UI text, API responses, emails, notifications, or expected product-copy tests.
+- If creating a new sub-module, note the durable facts needed for retrospective; do not overwrite existing `.prizmkit/prizm-docs/` files in full.
+
+## Output Format
+
+Report exactly:
+
+```text
+### Result: COMPLETED | BLOCKED | WRONG_CHECKOUT
+
+### Completed Tasks
+- [task id or description]
+
+### Files Changed
+- path: summary
+
+### Verification
+- command/check: result
+
+### Notes for Main Agent
+- durable decisions, missing L2 docs, or blockers
+```
+
+For `WRONG_CHECKOUT`, include only the checkout mismatch evidence and do not include normal implementation findings.