prizmkit 1.1.130 → 1.1.134

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

@@ -1,131 +1,172 @@
 ---
 name: "prizmkit-plan"
-description: "Specify and plan development tasks: natural language → change artifact with spec.md and plan.md. Works for features, bug fixes, refactors, migrations, and other non-trivial changes. Use before /prizmkit-implement when the task needs written scope, design, or executable tasks; use simplified planning for Fast path changes and full planning for high-risk or multi-module work. Trigger on: 'specify', 'plan', 'new task', 'I want to add/build...', 'architect', 'design', 'break it down', 'create tasks'. (project)"
+description: "Start the formal PrizmKit requirement lifecycle by turning a natural-language change into spec.md and plan.md artifacts, running mandatory Main-Agent planning review plus optional capability-gated independent correctness review, initializing workflow state, and handing off to prizmkit-implement. Works for features, bug fixes, refactors, migrations, tests, and other formal requirements. (project)"
 ---
 
 # PrizmKit Plan
 
-A universal spec + plan generator. It turns a natural-language development task into a **change artifact**: `spec.md` (WHAT/WHY) and `plan.md` (HOW + Tasks).
+`/prizmkit-plan` is the entry point for one formal requirement. It converts a natural-language change into a reviewed change artifact: `spec.md` defines WHAT and WHY; `plan.md` defines HOW and executable tasks.
 
-A change artifact is not feature-only. It can describe a feature, bug fix, refactor, migration, test improvement, or other scoped change.
+A change artifact can describe a feature, bug fix, refactor, migration, test improvement, or another scoped requirement.
 
-### When to Use
-- Any non-trivial development task that benefits from written scope and task breakdown
-- Before `/prizmkit-implement` when no suitable `plan.md` exists
-- Fast path changes that still need a simplified plan and resumable Tasks section
-- Full path changes involving multiple files/modules, public interfaces, data models, architecture, security, or unclear requirements
-- User says "specify", "plan", "new task", "I want to add...", "architect", "design", or "break it down"
+## When to Use
 
-### When NOT to Use
-- Direct edit: typo, pure formatting, small docs edit, or tiny config tweak with no behavior impact
-- User explicitly asks for a one-off direct edit and the risk is low
-- A current artifact directory already has an adequate `spec.md` + `plan.md` for the requested work
+- Starting any formal software requirement.
+- A non-trivial change benefits from written scope, acceptance criteria, and task breakdown.
+- No adequate current `spec.md` and `plan.md` exist for the requested work.
+- User says "specify", "plan", "new task", "I want to add...", "architect", "design", or "break it down".
 
-## Path Selection
+## When NOT to Use
 
-Choose the lightest planning depth that protects correctness:
+- Direct edit: typo, pure formatting, small documentation edit, or another explicitly low-risk non-requirement change.
+- The active artifact directory already has an adequate reviewed `spec.md` and `plan.md`; resume from the workflow state instead.
 
-| Path | Planning behavior |
-|---|---|
-| Direct edit | Skip `/prizmkit-plan`; edit directly and verify the specific change. |
-| Fast path | Create a concise `spec.md` and simplified `plan.md` with a Tasks section. |
-| Full path | Create full `spec.md` and `plan.md` with architecture, risks, tests, and executable tasks. |
+## Formal Lifecycle
 
-Use Full path for high-risk, multi-module, public API, data model, security, permission, payment, deployment-impacting, or ambiguous work. Use Fast path for small scoped behavior changes. Explain the chosen path briefly.
+A successful plan starts this fixed lifecycle:
+
+```text
+plan → implement → code-review → test → retrospective → committer
+```
+
+Planning depth may be concise or comprehensive, but no later formal lifecycle stage may be silently skipped.
 
 ## Input
 
 | Parameter | Required | Description |
-|-----------|----------|-------------|
-| `description` | Yes | Natural-language description of the task |
-| `artifact_dir` | No | Directory to write the change artifact into. If omitted, auto-generates under `.prizmkit/specs/` using a numbered slug. |
-
-## Execution
-
-### Phase 0: Specify (`spec.md`)
-
-Skip this phase if `spec.md` already exists in the artifact directory and still matches the requested change.
-
-Steps:
-
-1. Gather the task description. If missing and interactive, ask the user; otherwise abort with a clear error.
-2. Determine artifact directory:
-   - If `artifact_dir` is provided, use it directly.
-   - If omitted, scan `.prizmkit/specs/` for existing numbered directories and create `.prizmkit/specs/###-task-slug/`.
-   - The `.prizmkit/specs/` path is a generic change-artifact location; it is not limited to features.
-3. Load project context: read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs. If L2 is missing for an affected module, use relevant source files as fallback context.
-4. Generate `spec.md` from `${SKILL_DIR}/assets/spec-template.md`:
-   - Focus on WHAT and WHY, not HOW.
-   - Include only relevant sections.
-   - Every goal needs acceptance criteria.
-   - Mark genuine ambiguity with `[NEEDS CLARIFICATION]`.
-5. If changes involve persistence, add a Data Model section. Read existing schema files to learn naming conventions, ID strategy, constraints, and migration patterns.
-6. Resolve `[NEEDS CLARIFICATION]` markers:
-   - Interactive: ask targeted questions using `${SKILL_DIR}/references/clarify-guide.md`.
-   - Non-interactive: choose conservative defaults and annotate the decision.
-
-Internal ID hygiene: PrizmKit IDs, task IDs, session/run IDs, branch names, absolute worktree paths, and `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths are internal metadata. They may appear in change artifacts, but do not write them into `.prizmkit/prizm-docs/`, product UI copy, API responses, emails, notifications, or expected user-visible test strings.
-
-### Phase 1: Design (`plan.md`)
-
-Precondition: `spec.md` exists.
-
-Steps:
-
-1. Read `spec.md`.
-2. Load project context if not already loaded: root Prizm doc, relevant L1/L2 docs, and source fallback for missing L2 docs.
-3. Resolve any remaining clarification markers.
-4. Generate `plan.md` from `${SKILL_DIR}/assets/plan-template.md`:
-   - Change approach
-   - Component/file changes
-   - Data model changes and migration approach when relevant
-   - Interface/API contract design when relevant
-   - Testing strategy, using risk-triggered `/prizmkit-test` criteria
-   - Risk assessment
-   - Behavior preservation strategy for refactors or behavior-adjacent changes
-5. Cross-check every spec goal maps to a plan component.
-6. Check alignment with `.prizmkit/prizm-docs/root.prizm` RULES.
-
-### Phase 2: Task Generation
-
-1. Choose task strategy: MVP-first, incremental, or parallel. Ask in interactive mode when the choice affects execution; otherwise infer from risk and dependencies.
-2. Append `## Tasks` to `plan.md` using `${SKILL_DIR}/assets/plan-template.md`:
-   - Setup tasks
-   - Foundation tasks
-   - Core tasks mapped to goals or logical units
-   - Polish tasks when needed
-   - Checkpoint tasks between phases when integration risk exists
-3. Mark parallel tasks with `[P]` only when they can safely run independently.
-4. Run the verification checklist from `${SKILL_DIR}/references/verification-checklist.md` and fix issues before the planning quality gate.
-
-### Phase 3: Plan/Spec Review Loop
-
-Run this phase every time `spec.md` and `plan.md` are created or updated, before reporting the plan or handing off to implementation.
-
-1. Explicitly read `${SKILL_DIR}/references/review-plan-spec-loop.md`.
-2. Execute that guide against the current `spec.md` and `plan.md`.
-3. Apply all resolvable `BLOCKER` fixes and accepted `SHOULD_FIX` fixes directly to `spec.md` and/or `plan.md`.
+|---|---|---|
+| `description` | Yes | Natural-language description of the requirement. |
+| `artifact_dir` | No | Directory for the change artifact. If omitted, create a numbered slug under `.prizmkit/specs/`. |
+
+## Atomic Stage Boundary
+
+`prizmkit-plan` owns only specification, plan, task generation, and planning-quality review. It writes its truthful terminal result and `next_stage`, then returns control. It must not invoke `prizmkit-implement` itself, including when an external orchestrator is active. The active orchestrator owns the next-stage invocation.
+
+## Phase 0: Initialization Check and Context
+
+1. Check whether project context such as `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json`, or a project brief exists.
+2. If initialization context is missing:
+   - recommend `/prizmkit-init` and explain that it improves project context and cross-session continuity;
+   - do not block planning;
+   - if the user continues, load the README, manifests, project instruction files, source structure, and relevant source files as fallback.
+3. If Prizm docs exist, read `root.prizm`, relevant L1 docs, relevant L2 docs when present, and source fallback when L2 is absent.
+4. Resolve `artifact_dir` once and reuse it for every later lifecycle handoff. Do not re-detect another artifact during the same requirement.
+
+## Phase 1: Specify (`spec.md`)
+
+Skip regeneration when `spec.md` already exists and still matches the requested requirement.
+
+1. Gather the requirement description. If it is missing in an interactive run, ask the user; otherwise return a clear blocked result.
+2. Determine the artifact directory:
+   - use the caller-provided `artifact_dir` when present;
+   - otherwise scan `.prizmkit/specs/` for existing numbered directories and create `.prizmkit/specs/###-task-slug/`.
+3. Generate `spec.md` from `${SKILL_DIR}/assets/spec-template.md`:
+   - focus on WHAT and WHY, not HOW;
+   - include only relevant sections;
+   - give every goal acceptance criteria;
+   - mark genuine ambiguity with `[NEEDS CLARIFICATION]`.
+4. For persistence changes, inspect existing schemas and add a Data Model section using project conventions.
+5. Resolve clarification markers:
+   - interactive: use `${SKILL_DIR}/references/clarify-guide.md` and ask targeted questions;
+   - non-interactive: choose conservative defaults, annotate them, and block when a safe default is impossible.
+
+Internal ID hygiene: PrizmKit IDs, task/session/run IDs, branch names, absolute worktree paths, and internal artifact paths may exist in change artifacts but must not leak into `.prizmkit/prizm-docs/`, product UI copy, API responses, emails, notifications, or expected user-visible test strings.
+
+## Phase 2: Design (`plan.md`)
+
+Precondition: `spec.md` exists with no unresolved blocker.
+
+1. Read `spec.md` and relevant project context.
+2. Resolve remaining clarification markers.
+3. Choose a planning depth appropriate to the requirement:
+   - concise for small, well-scoped formal requirements;
+   - comprehensive for multi-module, public API, data model, security, permission, payment, deployment-impacting, or ambiguous requirements.
+4. Generate `plan.md` from `${SKILL_DIR}/assets/plan-template.md` with:
+   - change approach;
+   - component and file changes;
+   - data migration approach when relevant;
+   - interface/API contract design when relevant;
+   - test strategy for the mandatory `/prizmkit-test` stage;
+   - risks and mitigations;
+   - behavior-preservation strategy for refactors.
+5. Cross-check every spec goal against the plan.
+6. Check alignment with project rules and available Prizm documentation.
+
+## Phase 3: Task Generation
+
+1. Choose an MVP-first, incremental, or safe parallel task strategy.
+2. Append `## Tasks` to `plan.md` using `${SKILL_DIR}/assets/plan-template.md`.
+3. Include setup, foundation, core, polish, and checkpoint tasks only when applicable.
+4. Mark `[P]` only for tasks that can safely execute independently.
+5. Include implementation-local verification where useful, while preserving the later full code-review and test stages.
+6. Run `${SKILL_DIR}/references/verification-checklist.md` and repair plan defects.
+
+## Phase 4: Plan/Spec Review Loop
+
+Run every time `spec.md` or `plan.md` is created or changed. This is the mandatory Main-Agent baseline on every host.
+
+1. Read `${SKILL_DIR}/references/review-plan-spec-loop.md`.
+2. Review the current artifacts against the requirement and project context.
+3. Apply all resolvable `BLOCKER` fixes and accepted `SHOULD_FIX` fixes.
 4. Treat `OPTIONAL` findings as non-blocking.
-5. Rerun the review once when fixes were applied, respecting the guide's maximum of 2 total rounds.
-6. If unresolved `BLOCKER` findings remain, stop and ask targeted clarification questions in interactive mode; in non-interactive mode, record the blocker and stop. Do not escalate to a Critic agent.
-7. Only proceed to `/prizmkit-implement` handoff after the loop has no unresolved blockers.
+5. Rerun once when fixes were applied, with a maximum of two planning-review rounds.
+6. If a `BLOCKER` remains, ask targeted questions in interactive mode; otherwise record `PLAN_BLOCKED` and stop.
+7. Continue only when no unresolved blocker remains.
+
+The planning review must not implement code, run the full test stage, or launch external orchestration.
+
+## Phase 5: Independent Plan Review
+
+Run only after the Main-Agent Plan/Spec review converges. This optional check never replaces or weakens the completed local review.
+
+1. Read `${SKILL_DIR}/references/independent-plan-review.md` and follow its complete contract.
+2. Apply its all-or-nothing semantic Host Capability Gate. If any required structural capability is unavailable or unproven, create no Reviewer and record strict downgrade in `plan.md`.
+3. When the gate passes, capture bounded immutable current-state input and create exactly one Plan Reviewer with the reference's Initial Reviewer Prompt.
+4. Use maximum two Reviewer responses. Adjudicate every correction as `accepted`, `rejected`, or `unresolved`; the Main Agent alone modifies artifacts.
+5. After an accepted correction, perform targeted Plan/Spec verification and, when one response remains, natively resume the exact same Reviewer. Never create a replacement Reviewer or simulate continuation with a fresh Reviewer plus summary.
+6. If native resume fails after modification, record downgrade and rerun the Main-Agent local Plan/Spec review over that modification as specified by the reference.
+7. If the final allowed response causes a modification, run targeted verification, record that the final state was not independently rechecked, and do not exceed the response budget.
+8. Append the terminal `## Independent Plan Review` record. Appending that audit record does not trigger another response.
+9. Any unresolved correction produces `PLAN_BLOCKED`; otherwise independent convergence or strict downgrade may continue to handoff from the valid completed Main-Agent review.
+
+## Phase 6: Workflow State and Handoff
+
+Read `${SKILL_DIR}/references/workflow-state-protocol.md` and create or update:
+
+```text
+.prizmkit/state/workflows/<requirement-slug>.json
+```
+
+Follow the bundled protocol. At minimum record:
+
+```json
+{
+  "schema_version": 1,
+  "artifact_dir": ".prizmkit/specs/001-example",
+  "stage": "plan",
+  "status": "PLAN_READY",
+  "completed_stages": ["plan"],
+  "repair_round": 0,
+  "repair_scope": null,
+  "next_stage": "implement",
+  "resume_from": "prizmkit-implement"
+}
+```
 
-The review loop is planning-only. It must not start implementation, run tests/builds, launch a pipeline, create a separate skill, or require a Critic agent.
+The state file is runtime metadata. Do not change the target project's Git or ignore policy.
 
 ## Output
 
-| Directory | Files |
-|---|---|
-| `artifact_dir` or auto-generated `.prizmkit/specs/###-slug/` | `spec.md` + `plan.md` |
+- `spec.md` and `plan.md` in the resolved artifact directory.
+- Workflow state with `PLAN_READY` or a truthful blocked result.
+- Planning depth, key decisions, task count, and checkpoint summary.
+- The same `artifact_dir` for every downstream stage.
 
-Report:
-- artifact directory
-- chosen path: Fast path or Full path
-- key decisions
-- task count and checkpoint summary
+## Handoff
 
-**HANDOFF:** `/prizmkit-implement`
+On `PLAN_READY`:
 
-## Examples
+1. If workflow state names an active `orchestrator`, return `PLAN_READY`, `stage_result=PLAN_READY`, `next_stage=implement`, the state path, and the same `artifact_dir` to that orchestrator; do not invoke the next stage independently.
+2. For direct stage use with no active orchestrator, report exactly one deterministic next action: `/prizmkit-implement`, with `stage_result=PLAN_READY`, the state-file path, and `artifact_dir`; a host may perform that semantic handoff on the user's behalf.
 
-Read `${SKILL_DIR}/references/examples.md` for worked examples of feature, refactoring, and bug fix planning.
+Read `${SKILL_DIR}/references/examples.md` only when a worked planning example is needed.

package/bundled/skills/prizmkit-plan/assets/plan-template.md

@@ -113,3 +113,21 @@
 - [ ] [CP-1] After Setup: project builds and tests pass
 - [ ] [CP-2] After Foundation: base changes verified
 - [ ] [CP-3] After each Core group: acceptance criteria pass
+
+## Independent Plan Review
+<!-- Append this terminal audit record after the Main-Agent review and the optional independent-review attempt. -->
+<!-- Appending this terminal record does not trigger another Reviewer response and does not add an implementation task. -->
+
+- Capability Gate: <ENABLED | DOWNGRADED>
+- Downgrade Reason: <reason or none>
+- Reviewer Responses: <0..2>
+- Convergence: <no correction | all rejected | final-budget verification | local-review fallback | strict downgrade>
+- Final State Independently Rechecked: <yes | no | not applicable>
+- Unresolved Corrections: <none for PLAN_READY>
+
+### Adjudication
+<!-- Repeat for every proposed correction. Use `None.` when there were no corrections. -->
+- Correction: <summary>
+- Decision: <accepted | rejected | unresolved>
+- Evidence: <evidence>
+- Modification: <actual change or none>

package/bundled/skills/prizmkit-plan/references/independent-plan-review.md

@@ -0,0 +1,242 @@
+# Independent Plan Review
+
+## Purpose
+
+Run one optional independent correctness review after the mandatory Main-Agent Plan/Spec review has converged. The Reviewer checks whether the current `spec.md` and `plan.md` correctly express the requirement and are ready for implementation. It is not required to disagree and must return `NO_CORRECTION_NEEDED` when no correction is justified.
+
+This reference is complete within `prizmkit-plan`. Do not depend on another skill's prompt or a platform-generated Reviewer role.
+
+## Required Ordering and Budget
+
+```text
+Draft spec.md and plan.md
+→ mandatory Main-Agent Plan/Spec review: maximum two rounds
+→ optional independent Plan Reviewer: maximum two responses
+→ PLAN_READY or PLAN_BLOCKED
+```
+
+The independent budget does not replace, reduce, or extend the local review budget. Create at most one Reviewer for the Plan stage. Never reuse it in another stage.
+
+## Host Capability Gate
+
+The gate is all-or-nothing. Before creating a Reviewer, the host must prove this semantic execution contract:
+
+```yaml
+execution_unit:
+  count: 1
+  access: read-only
+  mutation: unavailable
+  arbitrary_command_execution: unavailable
+  downstream_execution: structurally-unavailable
+  context_continuation: same-unit-native-resume
+  workspace_observation: bounded-active-checkout-input
+  model_configuration: inherit-current-session
+```
+
+Rules:
+
+- Prompt instructions cannot satisfy a missing structural capability.
+- The decision must not branch on platform identity, tool name, execution-unit type name, adapter output, or a platform allowlist.
+- If any capability is missing or cannot be proven, do not create a Reviewer. Use Strict Downgrade.
+- A general execution unit with a prompt saying "do not mutate or delegate" is not eligible when those capabilities remain available.
+- The Reviewer inherits the current session's model configuration. Do not add a separate model-selection contract.
+
+## Review Input
+
+Before each response, the Main Agent captures one bounded review input that is immutable for one response:
+
+```text
+review-input
+├── manifest: input identity, response number, project-relative paths, states, and consistency markers
+├── context: requirement, confirmed clarifications, relevant rules, and prior adjudication on resume
+└── payload: current spec.md, current plan.md, and only targeted supporting material
+```
+
+The Plan payload contains:
+
+- current `spec.md`;
+- current `plan.md`, including tasks;
+- original requirement and confirmed clarification decisions;
+- relevant project rules and Prizm documentation;
+- only the source or contract paths needed to verify concrete planning assumptions.
+
+Do not provide broad repository access as a substitute for capturing input. The representation may use host-native immutable content or a read-only temporary payload outside the project change set; the protocol does not require a particular temporary path or command.
+
+Before ordinary review, the Reviewer verifies that manifest, context, and payload agree. Missing content, unexplained entries, stale content, or mixed-round input produces `REVIEW_BLOCKED`, never partial success.
+
+## Initial Reviewer Prompt
+
+Instantiate the bracketed fields and retain every boundary below.
+
+```text
+You are the sole independent Plan Reviewer for this PrizmKit Plan stage.
+
+Purpose:
+Objectively determine whether the Main Agent's current specification and implementation plan correctly represent the confirmed requirement and are ready for implementation. You are not an adversary and are not required to disagree. Return NO_CORRECTION_NEEDED when the current artifacts are correct.
+
+Response:
+This is response [RESPONSE_NUMBER] of a maximum two responses.
+Review-input identity: [INPUT_ID]
+Manifest: [MANIFEST]
+Context: [CONTEXT]
+Payload: [PAYLOAD]
+Permitted targeted paths, if represented separately: [TARGETED_PATHS_OR_NONE]
+
+Execution boundaries:
+- Complete this review personally.
+- Do not create, schedule, resume, continue, request, or coordinate another execution unit.
+- Do not ask the Main Agent to create a helper.
+- Do not re-enter orchestration, delegation, another review workflow, or an equivalent process.
+- Do not modify, create, delete, rename, stage, commit, or otherwise mutate files.
+- Do not execute commands, tests, builds, network calls, or any operation that can change state.
+- Read only the bounded review input and explicitly permitted targeted paths.
+- Do not perform broad repository discovery or a full repository scan.
+- Report only corrections supported by a concrete target and evidence.
+- Do not invent an issue merely to return feedback.
+- Return REVIEW_BLOCKED rather than delegate or provide an incomplete success result.
+- Do not expose private reasoning traces. Return only the required output.
+
+First validate input consistency. Then review requirement and scope correctness, terminology and non-goals, acceptance criteria, goal-to-plan coverage, relevant data/interface/security/compatibility/performance/deployment/migration constraints, dependency evidence, task prerequisites and safe parallel markers, task actionability/testability/resumability, and unjustified scope expansion or overengineering.
+
+Do not review implementation code, execute tests, or redesign the requirement beyond a necessary correction.
+
+Return exactly one result using the Reviewer Output Protocol.
+```
+
+## Resume Prompt
+
+Resume the exact same Reviewer; do not create a new Reviewer with this text. Instantiate the bracketed fields.
+
+```text
+Continue as the same independent Plan Reviewer.
+
+Response:
+This is response [RESPONSE_NUMBER] of a maximum two responses.
+New review-input identity: [INPUT_ID]
+New manifest: [MANIFEST]
+Current context: [CONTEXT]
+Current payload: [PAYLOAD]
+Previously accepted corrections: [ACCEPTED_CORRECTIONS_OR_NONE]
+Modifications actually made: [MODIFICATIONS_OR_NONE]
+Previously rejected corrections and rejection evidence: [REJECTIONS_OR_NONE]
+Unresolved items: [UNRESOLVED_OR_NONE]
+
+All initial execution boundaries and the Reviewer Output Protocol remain mandatory. Review the current state, not the superseded payload. Do not repeat a rejected correction unless the new state invalidates the recorded rejection evidence. Validate the new input before ordinary review and return exactly one result.
+```
+
+## Reviewer Output Protocol
+
+Return exactly one of these forms. Do not add severity, confidence, dimension, workflow impact, or acceptance fields.
+
+### No Correction Needed
+
+```markdown
+### Result: NO_CORRECTION_NEEDED
+
+### Corrections
+None.
+
+### Summary
+<one or two sentences confirming what was reviewed>
+```
+
+### Correction Needed
+
+```markdown
+### Result: CORRECTION_NEEDED
+
+### Corrections
+
+#### Correction 1
+- Target: <spec.md or plan.md location, section, or task>
+- Problem: <what is currently incorrect>
+- Evidence: <concrete basis>
+- Correction: <recommended correction>
+
+### Summary
+<one or two sentences describing the current state>
+```
+
+Every correction contains only `Target`, `Problem`, `Evidence`, and `Correction`.
+
+### Review Blocked
+
+```markdown
+### Result: REVIEW_BLOCKED
+
+### Blocker
+- Target: <missing or inconsistent review input>
+- Problem: <why a complete review cannot be performed>
+- Evidence: <concrete mismatch or capability failure>
+- Correction: <what input or host condition would unblock review>
+
+### Summary
+No review verdict was produced.
+```
+
+`REVIEW_BLOCKED` is an internal independent-review result, not a lifecycle result.
+
+## Main-Agent Adjudication
+
+The Main Agent verifies each proposed correction and records exactly one decision:
+
+| Decision | Meaning | Action |
+|---|---|---|
+| `accepted` | Evidence proves an in-scope planning correction is needed. | Main Agent modifies `spec.md` and/or `plan.md` and performs targeted verification. |
+| `rejected` | Current artifacts, source, contracts, or rules disprove the proposed problem. | Record concrete rejection evidence and make no change for it. |
+| `unresolved` | Correctness or a safe correction cannot be established. | Record the item and return `PLAN_BLOCKED`. |
+
+The Reviewer never modifies artifacts and cannot overrule adjudication.
+
+Independent review converges normally when:
+
+1. the Reviewer returns `NO_CORRECTION_NEEDED`; or
+2. every correction in the current response is rejected with concrete evidence and no unresolved item remains.
+
+## Response Algorithm
+
+1. Run only after the Main-Agent Plan/Spec review converges with no unresolved `BLOCKER`.
+2. Apply the Host Capability Gate.
+3. If eligible, capture response 1 input and create exactly one Reviewer with the Initial Reviewer Prompt.
+4. Validate the result against the Reviewer Output Protocol.
+5. Adjudicate every correction. Any unresolved item returns `PLAN_BLOCKED`.
+6. For accepted corrections, the Main Agent modifies `spec.md` and/or `plan.md` and applies the relevant part of the existing verification checklist.
+7. If one response remains, capture fresh input and resume the exact same Reviewer with the Resume Prompt.
+8. If the second response causes a modification, no third response is allowed. Perform targeted Plan/Spec verification, record final-budget handling, and set `Final State Independently Rechecked` to `no`.
+9. Append the terminal `## Independent Plan Review` record. Appending the record itself never triggers another response.
+10. End the Reviewer when review converges, reaches the response limit, fails irrecoverably, or the stage becomes blocked. Explicitly terminate it when the host safely supports that operation; otherwise stop sending messages.
+
+## Strict Downgrade
+
+Use strict downgrade in any of these cases:
+
+- a required capability is unavailable or unproven before creation;
+- Reviewer creation fails;
+- the exact same Reviewer cannot be resumed or resume fails;
+- execution-unit integrity becomes uncertain.
+
+Behavior:
+
+1. Never create a weaker or replacement Reviewer.
+2. Never create a fresh Reviewer with a summary of the prior conversation; a summary is context, not native continuation.
+3. When no Reviewer is created, record the downgrade and continue from the completed Main-Agent review if it remains valid.
+4. When creation fails before any response, record the failure and preserve the completed Main-Agent review.
+5. When resume fails after an accepted modification, Never create a replacement Reviewer; rerun the local Plan/Spec review over the modification within its existing local semantics, record the downgrade and fallback, and return `PLAN_BLOCKED` if that verification cannot establish readiness.
+6. Reviewer input problems may be corrected and sent to the same Reviewer only while response budget and native continuation remain available. Otherwise downgrade.
+7. Report temporary input-cleanup failures honestly; cleanup failure does not change an otherwise verified planning result.
+
+Strict downgrade is visible reduced assurance, not an error verdict and not permission to weaken the gate.
+
+## Terminal Record
+
+Append the terminal record shape from `${SKILL_DIR}/assets/plan-template.md` after review or downgrade. Include:
+
+- `Capability Gate: ENABLED | DOWNGRADED`;
+- a concrete downgrade reason or `none`;
+- Reviewer responses used, from `0` through `2`;
+- convergence or fallback mode;
+- whether the final state received an independent recheck;
+- every proposed correction, Main-Agent decision, evidence, and actual modification;
+- unresolved items, which must be absent for `PLAN_READY`.
+
+This section is audit metadata, not an implementation task and not input that requires another Reviewer response.

package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md

@@ -4,7 +4,7 @@
 
 Run this local planning-quality gate after `spec.md` and `plan.md` are drafted or updated, before handing off to `/prizmkit-implement`.
 
-This is not a separate skill and it does not use a Critic agent. It is a bounded review loop executed inside `prizmkit-plan` to improve the planning artifacts only.
+This is not a separate skill and it does not use a Critic agent. It is the mandatory Main-Agent baseline executed inside `prizmkit-plan` to improve the planning artifacts only. Its maximum of two local rounds remains independent of the optional Reviewer described in `independent-plan-review.md`.
 
 ## Non-Goals
 
@@ -13,7 +13,7 @@ Do not do any of the following from this guide:
 - Start implementation or edit product/source code.
 - Run tests, builds, lint, or package commands.
 - Launch a feature, bugfix, or refactor pipeline.
-- Spawn or require a Critic agent.
+- Spawn or require a Critic agent inside this Main-Agent loop. The separate optional independent review is considered only after this loop converges and only through `independent-plan-review.md`.
 - Create a separate review-loop skill.
 - Expand scope beyond improving `spec.md` and `plan.md`.
 
@@ -87,8 +87,8 @@ Optional findings do not block handoff.
 4. Do not apply `OPTIONAL` findings unless they clearly improve readiness without expanding scope.
 5. If any fixes were applied, rerun this review once.
 6. Stop after at most 2 total review rounds.
-7. If unresolved `BLOCKER` findings remain after the final round, stop planning and ask targeted clarification questions. Do not escalate to a Critic agent.
-8. If no unresolved blockers remain, report that the planning quality gate passed and hand off to `/prizmkit-implement`.
+7. If unresolved `BLOCKER` findings remain after the final round, stop planning and ask targeted clarification questions. Do not escalate from this loop to a Critic agent or treat independent review as blocker recovery.
+8. If no unresolved blockers remain, report that the mandatory Main-Agent planning quality gate passed and hand off to the optional independent Plan review boundary in `independent-plan-review.md`.
 
 ## Output Summary