prizmkit 1.1.154 → 1.1.156

package/bundled/dev-pipeline/templates/sections/bugfix-phase-review.md

@@ -2,7 +2,7 @@
 
 Code review is mandatory for every committable Bugfix, including small or obvious fixes. Do not create a FAST_PATH that skips this gate.
 
-Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/` and follow the skill's complete review contract for review execution, repairs, verification, evidence, and handoff. Do not invoke another review skill or add a second review path outside that contract.
+Invoke `/prizmkit-code-review` with the exact `artifact_dir`, spec, plan, and current change. The Skill returns only `PASS` or `NEEDS_FIXES`; this injected session validates `review-report.md`, maps the result, updates the checkpoint, and chooses routing.
 
 Missing required evidence, an unsafe repair, a failed verification, or failure to converge under the review contract produces `NEEDS_FIXES`.
 
@@ -12,8 +12,8 @@ Missing required evidence, an unsafe repair, a failed verification, or failure t
 {{RUNTIME_HELPER_CMD}} text final-verdict .prizmkit/bugfix/{{BUG_ID}}/review-report.md
 ```
 
-- `REVIEW_PASS` → proceed to the mandatory post-review test gate.
-- `REVIEW_NEEDS_FIXES` → route through bounded implementation/review/test repair; do not commit.
+- Skill `PASS` with a valid report → map to `REVIEW_PASS` and proceed to configured verification.
+- Skill `NEEDS_FIXES` with a valid report → map to `REVIEW_NEEDS_FIXES`, classify the concrete findings into an allowed `repair_scope`, record both values, and route through the bounded repair path. If no safe scope exists, block instead of guessing; do not commit.
 - `REVIEW_INCOMPLETE` or `REVIEW_INVALID` → inspect progress once, write `failure-log.md`, and stop. Do not accept old or incidental verdict text and do not synthesize a passing result outside the skill.
 
 **Checkpoint update**: Set step `prizmkit-code-review` to `completed` with `stage_result=REVIEW_PASS` only for an accepted valid Final Result. Set it to `failed` with `stage_result=REVIEW_NEEDS_FIXES` when the review returns known unresolved findings.

package/bundled/dev-pipeline/templates/sections/bugfix-phase-test.md

@@ -16,9 +16,9 @@ They must agree on the testing result and unresolved items. Do not require an ev
 Gate outcomes:
 
 - `TEST_PASS`: mark the test checkpoint step completed and continue to retrospective.
-- `TEST_NEEDS_FIXES`: preserve the report/result and stop truthfully. A high-risk production repair reports `review_required=true` and `review_scope=delta`; the caller owns any review-and-retest route.
+- `TEST_NEEDS_FIXES`: this injected session classifies the exact unresolved correction into an allowed `repair_scope` and records both on the failed test step. If scope and outer budget permit, start `prizmkit-implement` with that explicit repair input; the helper rewinds stale downstream steps, then fresh review, configured verification, and test results are mandatory. If scope is unsafe/unknown or budget is exhausted, record terminal `WORKFLOW_BLOCKED`. Never recreate the testing-local repair loop.
 - `TEST_BLOCKED`: preserve the report/result and blocker, then record terminal `WORKFLOW_BLOCKED`. Do not reinterpret the result as a runtime crash or make speculative production edits.
 
 The skill itself diagnoses and repairs valid execution failures for at most three rounds before returning. The caller must not recreate that repair loop or maintain test-internal state.
 
-**Checkpoint update**: Only `TEST_PASS` plus `test-report.md` and `test-result.json` completes `prizmkit-test` and allows retrospective.
+**Checkpoint update**: This injected session completes `prizmkit-test` only for `TEST_PASS` plus valid `test-report.md` and `test-result.json`; non-pass results follow the routing above.

package/bundled/dev-pipeline/templates/sections/bugfix-reminders.md

@@ -1,12 +1,12 @@
 ## Reminders
 
-- Use the atomic skills: `/prizmkit-plan`, `/prizmkit-implement`, `/prizmkit-code-review`, `/prizmkit-retrospective`, `/prizmkit-committer`.
+- Use every formal atomic stage: `/prizmkit-plan`, `/prizmkit-implement`, `/prizmkit-code-review`, `/prizmkit-test`, `/prizmkit-retrospective`, `/prizmkit-committer` preparation.
 - All bugfix skills use `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/`.
 - The first plan task must prove the bug with a reproduction test when feasible.
-- Commit with `fix(<scope>):`, not `feat:`.
+- Use a `fix(<scope>):` Conventional Commit message in the runtime commit request.
 - Do not write TRAP dates into `.prizmkit/prizm-docs/`.
 - Follow the active skills and runtime contracts; they determine execution topology, review ownership, and delegation boundaries.
 - On execution-unit timeout, preserve the active checkout and artifacts and follow the owning contract's recovery or downgrade path.
-- Checkpoint state is the recovery truth; skipped steps must be marked `skipped`.
-- Browser verification is a mandatory attempt by default; it blocks only when explicitly required.
+- Checkpoint state is recovery guidance; mandatory stage results and their authoritative artifacts remain required.
+- Browser verification is present only when configured; follow its configured blocking policy.
 - If `DEV_PORT` is unknown, discover it from project config; do not guess port 3000.

package/bundled/dev-pipeline/templates/sections/bugfix-session-context.md

@@ -3,5 +3,4 @@
 - **Bug ID**: {{BUG_ID}} | **Session**: {{SESSION_ID}} | **Run**: {{RUN_ID}}
 - **Bug Title**: {{BUG_TITLE}}
 - **Severity**: {{SEVERITY}}
-- **Mode**: {{PIPELINE_MODE}}
 - **Verification Type**: {{VERIFICATION_TYPE}}

package/bundled/dev-pipeline/templates/sections/checkpoint-system.md

@@ -19,20 +19,23 @@ Use this helper to update checkpoint status. Do not hand-edit `workflow-checkpoi
 
 - Use the step `skill` value such as `prizmkit-implement`, or the step id such as `S04`.
 - Omit `--stage-result` for stages without a domain result.
-- Complete `prizmkit-plan` with `--status completed --stage-result PLAN_READY`.
+- Complete the checkpoint's planning step (`context-snapshot-and-plan`, `bug-diagnosis-and-plan`, or `prizmkit-plan`) with `--status completed --stage-result PLAN_READY`.
 - Complete `prizmkit-implement` with `--status completed --stage-result IMPLEMENTED`.
 - Complete `prizmkit-code-review` only with `--status completed --stage-result REVIEW_PASS`.
 - Complete `prizmkit-test` only after validating the sibling report/result pair, with `--status completed --stage-result TEST_PASS`.
 - Complete `prizmkit-retrospective` with `--status completed --stage-result RETRO_COMPLETE`.
-- Record commit authorization wait with `--status in_progress --stage-result COMMIT_PENDING`; after the local commit, use `--status completed --stage-result COMMITTED`.
-- For `TEST_NEEDS_FIXES` or `TEST_BLOCKED`, use `--status failed --stage-result <result>` and preserve its report/result and blocker; never mark the test step completed.
+- After this injected session validates required gates and `/prizmkit-committer` returns `COMMIT_REQUEST_READY` with `runtime-commit-request.json`, record `--status in_progress --stage-result COMMIT_PENDING` and stop normal work. The Python runtime executes the local commit and alone advances this step to `completed/COMMITTED`.
+- For `REVIEW_NEEDS_FIXES` or `TEST_NEEDS_FIXES`, classify the concrete correction into one allowed `--repair-scope`, record the failed step and result, and let the helper select the bounded implementation route. If the scope cannot be established safely, record `WORKFLOW_BLOCKED` rather than guessing.
+- Record `PLAN_BLOCKED`, `IMPLEMENT_BLOCKED`, `TEST_BLOCKED`, `RETRO_BLOCKED`, or `COMMIT_BLOCKED` with `--status failed --stage-result <result>` and a useful note. The helper records terminal `WORKFLOW_BLOCKED`; never mark the failed step completed.
+- When the routed implementation step is marked `in_progress`, the helper rewinds later checkpoint steps to pending while preserving their stage-owned reports for historical evidence. Fresh Review, configured verification, and Test results are still mandatory.
+- Complete `manual-verification` when configured; do not skip a required manual/hybrid evidence gate.
 - Omit `--note` when there is no useful failure or handoff note.
 
 ### Rules
 
 1. Before each skill, verify its predecessor is `completed` or `skipped`.
 2. Starting a skill marks its step `in_progress`; a valid success marks it `completed`; a non-pass records its truthful `stage_result` and leaves later stages incomplete.
-3. Pipeline metadata owns only `current_stage`, `next_stage`, `stage_result`, `repair_scope`, `repair_round`, `blocked_reason`, and `terminal_status`; lifecycle `status` belongs to each checkpoint step.
+3. Pipeline metadata owns only `current_stage`, `next_stage`, `stage_result`, `repair_scope`, `repair_round`, `blocked_reason`, `terminal_status`, and runtime commit readiness; lifecycle `status` belongs to each checkpoint step.
 4. Skills own their reports and terminal results. The pipeline must not duplicate a skill's internal state machine or require evidence manifests, hashes, or attestations.
 5. Preserve all reports and session artifacts on recovery. Never replace skill artifacts with the pipeline checkpoint or merge their schemas.
 6. `TEST_NEEDS_FIXES` is a known testing-domain non-pass. `TEST_BLOCKED` records terminal `WORKFLOW_BLOCKED` with a deterministic reason. Neither is an AI CLI crash.

package/bundled/dev-pipeline/templates/sections/context-budget-rules.md

@@ -1,29 +1,16 @@
-## Context Budget Rules (CRITICAL — read before any phase)
+## Context and Execution Rules
 
-You are running in **headless non-interactive mode** with a FINITE context window. Exceeding it will crash the session and lose all work. Follow these rules strictly:
+This is a finite, headless, non-interactive session. Preserve correctness first, then minimize unnecessary context use.
 
-0. **NON-INTERACTIVE MODE** — There is NO human on the other end. NEVER ask for user confirmation, NEVER wait for user input, NEVER use interactive prompts (e.g. "Would you like me to…"). If a skill has an interactive step (e.g. offer remediation, ask for approval), skip it and proceed autonomously. Make decisions based on the data available and move forward.
-
-1. **context-snapshot.md is your single source of truth** — After it is available, use it instead of re-reading individual source files. If you just created or updated it in this session, continue from the in-context content; read it only when resuming/continuing, after context compaction/loss, or when handing work to an execution unit.
-2. **Never re-read your own writes** — After you create/modify a file, do NOT read it back to verify. Trust your write was correct.
-3. **Never re-read unmodified files** — Once you have read a file into context, do NOT read it again unless it was modified by an Edit/Write operation after your last read. Use platform file/search tools for targeted lookup; when shell-free helper lookup is needed, run `{{RUNTIME_HELPER_CMD}} text search <file> --pattern "<pattern>" --json`, then read only the smallest bounded range with the platform file-reading tool instead of full-file Read. Before issuing a Read, ask yourself: "Have I read this file before, and has it changed since?" If the answer is "no, it hasn't changed" — do NOT read it. This applies to all files summarized in context-snapshot.md Section 4. Follow the active skill and runtime contracts when an execution unit is created; do not infer its permissions, continuation, or retry behavior from this prompt.
-4. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
-5. **One task at a time** — Complete and test one task before starting the next.
-6. **Minimize tool output** — Never load full command output into context. First capture command output to a temp file using the command/tool output option or the host-appropriate redirection, then inspect only the final relevant lines and use targeted search helpers to extract the information needed for the current task. Only read the filtered result — never the raw full output.
-7. **No intermediate commits** — Do NOT run `git add`/`git commit` during implementation phases. All changes are committed once at the end via `/prizmkit-committer`.
-8. **Capture test output once** — When running test suites during the post-review gate, capture output once to `/tmp/test-out.txt` using the command/tool output option or the host-appropriate redirection, surface only the final relevant lines, then search `/tmp/test-out.txt` for details. Never re-run the suite just to apply a different filter.
-9. **Package version verification (HARD CONSTRAINT — BLOCKING)** — Before writing ANY dependency version in `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`, `Gemfile`, `pyproject.toml`, or any other dependency manifest:
-   - You MUST verify the real version exists by querying the package registry first:
-     - npm/Node.js: `npm view <package> dist-tags.latest`
-     - Python/pip: `pip index versions <package>` and use the first result line
-     - Go: `go list -m -versions <module>@latest`
-     - Rust: `cargo search <crate> --limit 1`
-   - **NEVER guess or hallucinate version numbers**. If you cannot verify a version, use `"latest"` or `"*"` as a placeholder, or omit the version constraint entirely and let the package manager resolve it
-   - If the registry query fails (network issue, package not found), you MUST either:
-     (a) Use a known-safe version you have high confidence in, OR
-     (b) Skip that dependency and document it as a manual step, OR
-     (c) Use no version constraint (e.g., `"express": "*"`)
-   - **This is a BLOCKING gate**: do NOT run `npm install` / `pip install` / `cargo build` / `go mod tidy` until ALL versions in the manifest have been verified or use open constraints
-   - Batch version lookups: query multiple packages in parallel to save time (e.g., run multiple `npm view` commands concurrently)
-10. **Build artifact hygiene** — After any build/compile command (`go build`, `npm run build`, `tsc`, etc.), ensure the output binary, build directory, generated bundle, or cache directory is ignored by git before the commit phase. Never commit compiled binaries, build output, or generated artifacts.
-11. **Read offset safety (BLOCKING)** — If Read returns "shorter than offset"/"File is empty"/"Wasted call" — do NOT retry same offset. Use the platform file-reading tool to refresh bounded line information, or locate an anchor with `{{RUNTIME_HELPER_CMD}} text search <file> --pattern "<anchor>" --json` before reading a small bounded range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets or prescribe POSIX-only lookup commands.
+1. **Non-interactive behavior** — Do not ask a question or wait for user input. Resolve safe uncertainty from the task contract, current code, project documentation, and conservative existing patterns. When no safe deterministic choice exists, write the blocker and return the owning stage's truthful blocked result.
+2. **Progressive context loading** — Read `root.prizm`, then only relevant module/detail docs and source files. Use `context-snapshot.md` as a navigation and handoff summary, not as a substitute for current source, diffs, or authoritative stage artifacts.
+3. **Targeted rereads are allowed** — Avoid repeating unchanged full-file reads, but reread the smallest relevant range when a file changed, context was compacted, an artifact may be stale, or verification requires the actual final content. Never rely on “trusting” an unverified write.
+4. **Verify modifications** — After edits, use the smallest appropriate diff, parser, formatter, type check, focused test, or bounded file read to verify the result. Code Review, Test, Retrospective, and Commit preparation must inspect the actual final state required by their own contracts.
+5. **Scope discipline** — Read and change only files justified by the Task Contract, concrete dependency/caller evidence, or a mandatory lifecycle gate. Do not perform curiosity-driven repository sweeps.
+6. **Implementation versus test gate** — During implementation, use focused local verification and TDD where appropriate. The complete affected-module and Regression Ring test gate remains owned by `/prizmkit-test` after Code Review; do not create a second caller-owned test-repair loop.
+7. **Bound command output** — Prefer commands and tool options that limit output. When a command is verbose, capture it using a host-appropriate temporary location and inspect only relevant summaries or matched ranges. Do not require a POSIX-only fixed path.
+8. **Dependency integrity** — Follow the target project's package manager, lockfile, registry, and version-pinning conventions. Verify new versions from an authoritative registry when network access is safe; do not introduce wildcard or guessed versions merely to bypass verification.
+9. **Build artifact hygiene** — Keep generated binaries, caches, bundles, and temporary output out of the intended commit unless the project explicitly treats them as source artifacts.
+10. **Commit boundary** — Do not create implementation, review, test, or retrospective commits. In a pipeline session, `/prizmkit-committer` prepares the exact commit request and the Python runtime executes the local commit.
+11. **State ownership boundary** — Atomic Skills never read or mutate orchestration state. This injected session updates `workflow-checkpoint.json` only through the declared helper; runtime helpers may manage their declared PID files. Never hand-edit runner-owned family/session/lock/heartbeat/progress/retry/checkout/daemon/log state.
+12. **Read failure handling** — After a failed bounded read, locate a stable anchor or refresh file length before another attempt. Do not repeat the same invalid offset or guess a new one.

package/bundled/dev-pipeline/templates/sections/feature-completion-summary.md

@@ -0,0 +1,20 @@
+### Feature Completion Summary
+
+After `TEST_PASS` and any configured browser verification, write `.prizmkit/specs/{{FEATURE_SLUG}}/completion-summary.json` before retrospective and commit preparation:
+
+```json
+{
+  "completion_notes": [
+    "<key API, model, exported function, or integration point needed by downstream features>"
+  ]
+}
+```
+
+Requirements:
+
+- Include 3–8 concise, self-contained notes when meaningful.
+- Prefer public interfaces, models, integration points, and important file paths.
+- Exclude routine test/config details unless downstream work depends on them.
+- When no downstream dependency exists, still summarize the durable delivered capability.
+
+**Checkpoint update**: Mark `completion-summary` completed only after the JSON is valid and non-empty.

package/bundled/dev-pipeline/templates/sections/phase-commit-full.md

@@ -1,75 +1,12 @@
-### Architecture Sync & Commit (SINGLE COMMIT) — DO NOT SKIP
+### Retrospective — Durable Documentation Sync
 
-**a.** Check if feature already committed by inspecting recent git history for `{{FEATURE_ID}}`:
-```bash
-git log --oneline
-```
-- If a commit for `{{FEATURE_ID}}` already exists → **skip d** (do NOT run /prizmkit-committer, do NOT run git reset, do NOT stage or unstage anything). Proceed directly to e Final verification.
-- If no existing commit → proceed normally with b–d.
+After validating Code Review, configured verification, `TEST_PASS`, and the Feature completion summary, invoke `/prizmkit-retrospective` with the exact artifact root, exact non-`.prizmkit/` `change_paths`, and a concise `change_summary`. It returns only `RETRO_COMPLETE` or `RETRO_BLOCKED`.
 
-**Feature Documentation Policy**:
-- Run `/prizmkit-retrospective` before commit to update `.prizmkit/prizm-docs/` with durable structural knowledge from this feature.
-- Capture architecture knowledge when the feature adds interfaces, dependencies, observable behavior, modules, or durable TRAPS/RULES/DECISIONS.
-- Commit prefix: `feat({{FEATURE_ID}}):`.
+Use `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`. The retrospective must:
 
-**b.** Run `/prizmkit-retrospective` (**before commit**, maintains `.prizmkit/prizm-docs/` architecture index):
-1. **Structural sync**: update KEY_FILES/INTERFACES/DEPENDENCIES/file counts for changed modules
-2. **Architecture knowledge**: extract TRAPS, RULES, DECISIONS from completed work into `.prizmkit/prizm-docs/`
-3. **Detail-doc coverage check**: For any module/sub-module with source files created or significantly modified in this session but no detail `.prizm` doc — evaluate whether one is warranted and create it when needed. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
-4. Stage doc changes: `git add .prizmkit/prizm-docs/`
-⚠️ Do NOT commit here. Only stage.
+1. Treat only the exact supplied non-`.prizmkit/` `change_paths` as authoritative input; do not expand scope.
+2. Synchronize `.prizmkit/prizm-docs/` only when durable structure, interfaces, dependencies, behavior, TRAPS, RULES, or DECISIONS changed.
+3. Write `.prizmkit/specs/{{FEATURE_SLUG}}/retrospective-result.json` with `outcome=RETRO_COMPLETE` and `result=DOCS_UPDATED|NO_DOC_CHANGE`.
+4. Validate any changed Prizm docs.
 
-**c.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):
-```bash
-git add <specific-files-created-or-modified>
-git add .prizmkit/prizm-docs/
-```
-
-**d.** Run `/prizmkit-committer` → THE ONLY commit for this feature:
-`feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`
-This single commit includes: feature code + tests + .prizmkit/prizm-docs/ updates.
-- MANDATORY: commit must be done via `/prizmkit-committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
-- Do NOT run `update-feature-status.py` here — the pipeline runner handles feature-list.json updates automatically after session exit.
-
-**e.** Final verification:
-```bash
-git status --short
-```
-Working tree MUST be clean after this step. If any feature-related files remain, stage them explicitly and amend the SAME commit with `git commit --amend --no-edit`; do NOT create a separate commit.
-
-**Exception**: `session-summary.md` in the artifact directory is a local cross-session artifact generated by `/prizmkit-committer` — it is NOT committed to git. Ignore it in the clean-tree check.
-
-**f.** Write completion summary for downstream dependency context:
-
-Write `.prizmkit/specs/{{FEATURE_SLUG}}/completion-summary.json` with the key changes from this session. This file is NOT committed to git — the pipeline runner reads it to propagate context to dependent features.
-
-```json
-{
-  "completion_notes": [
-    "<each item: one key change, API, model, or integration point that downstream features may need>",
-    "Example: Added User model (id, email, password_hash, display_name) in prisma/schema.prisma",
-    "Example: POST /api/auth/register and POST /api/auth/login endpoints in src/api/auth.ts",
-    "Example: Auth middleware in src/middleware/auth.ts — validates JWT on protected routes"
-  ]
-}
-```
-
-Rules for writing completion notes:
-- Focus on **what downstream features need to know**: new APIs, models, exported functions, key file paths
-- Each note should be self-contained and concise (one line, under 120 characters preferred)
-- Include 3-8 notes covering the most important changes
-- Do NOT include test files, config changes, or internal implementation details unless they affect other features
-- If this feature has no downstream dependents, still write the summary (it serves as documentation)
-
-
-
-### TERMINAL STOP — Commit Completed
-
-After all of the following are true, the session is **TERMINAL**:
-
-- `/prizmkit-committer` has completed
-- `git status --short` is clean (except ignored/local-only pipeline artifacts)
-- `.prizmkit/specs/{{FEATURE_SLUG}}/completion-summary.json` is written
-- the `prizmkit-committer` checkpoint is marked `completed`
-
-At that point, stop immediately. Do **not** process delayed normal-work results, edit files, amend the commit, or start any new tool calls. Code Review must end its optional Reviewer lifecycle before Final Result, so no independent-review response remains pending. Any normal-work result that arrives after S09 is completed is follow-up work for a later session, not part of this feature commit.
+Do not stage or commit. This injected session validates `retrospective-result.json`, maps `RETRO_COMPLETE` to the completed checkpoint step, and stops on `RETRO_BLOCKED`.

package/bundled/dev-pipeline/templates/sections/phase-implement-full.md

@@ -1,27 +1,27 @@
 ### Implement — Plan Execution
 
-Execute the reviewed plan through the active implementation skill. The skill and runtime determine the execution topology; preserve the shared artifact directory, active checkout, and task checkpoints.
+Invoke the implementation Skill with the reviewed `spec.md`, `plan.md`, and any explicit repair scope. The Skill returns only `IMPLEMENTED` or `IMPLEMENT_BLOCKED`; this injected session preserves the artifact directory/checkout and updates the checkpoint after validating the result.
 
 Before starting, check plan.md Tasks:
 ```bash
 {{RUNTIME_HELPER_CMD}} text count .prizmkit/specs/{{FEATURE_SLUG}}/plan.md --pattern "- [ ]"
 ```
-- If result is `0` (all tasks already `[x]`) → **SKIP to Review**.
-- If non-zero → execute the remaining tasks below.
+- If result is `0`, proceed only when the current checkpoint already has a valid `IMPLEMENTED` result and the implementation evidence still matches; otherwise invoke the implementation Skill to reconcile and validate the supplied work.
+- If non-zero, invoke the implementation Skill for the remaining tasks.
 
 **Build artifacts rule**: After any build/compile command, ensure output is in `.gitignore`. Never commit binaries/build output.
 
 **3a.** Run `/prizmkit-implement` directly:
 - Continue from the `spec.md` / `plan.md` / `context-snapshot.md` content you created in Phase 1-2; do not re-read self-authored artifacts just because implementation starts
 - Re-read `plan.md` or `context-snapshot.md` only when resuming/continuing, when current context was compacted or lost, or when task checkbox state may have changed outside this session
-- Follow the implementation skill's current execution and delegation contract
+- Follow the implementation skill's stage-local execution contract
 - Use context-snapshot.md Section 4 File Manifest for targeted source reads; avoid re-reading source files already summarized there unless they changed after the snapshot
-- Implements task-by-task, marking each `[x]` immediately
-- Remember to update checkpoints after finishing a series of tasks
+- Implement task-by-task, marking each `[x]` immediately
+- Return the stage result; only this injected session updates the checkpoint
 
 **3b. Focused checks only (no test gate here)**:
 - During implementation, do not run mandatory periodic or full-suite tests.
-- If a tiny targeted check is needed to understand a local failure, run only the smallest relevant command and capture output to `/tmp/test-out.txt`.
+- If a tiny targeted check is needed to understand a local failure, run only the smallest relevant command and bound its output using a host-appropriate temporary location.
 - The scoped feature test gate runs after code review; do not declare implementation success based on an early full-suite run.
 
 **3c. Verification Gate Self-Check (BLOCKING — before declaring implement done)**:

package/bundled/dev-pipeline/templates/sections/phase-prizmkit-test.md

@@ -1,6 +1,6 @@
 ### Scoped Feature Test Gate — PrizmKit Test
 
-**Goal**: After Code Review completes, use `/prizmkit-test` to analyze the complete affected business module and Regression Ring, add project-native tests, repair valid failures within the skill's bounded loop, and produce the terminal report/result pair.
+**Goal**: After Code Review and all configured Browser/Manual verification complete, use `/prizmkit-test` to analyze the complete affected business module and Regression Ring, add project-native tests, repair valid failures within the skill's bounded loop, and produce the terminal report/result pair.
 
 Run the skill with the current Feature artifact directory:
 
@@ -15,14 +15,14 @@ Consume these sibling terminal artifacts:
 - `.prizmkit/specs/{{FEATURE_SLUG}}/test-report.md`
 - `.prizmkit/specs/{{FEATURE_SLUG}}/test-result.json`
 
-The JSON is the minimal terminal result projection and the report contains semantic coverage, native execution, Main-Agent review, optional independent Test Reviewer, and repair details. They must agree. Do not require an evidence package, manifest, hashes, attestation, package lifecycle, or test-internal checkpoint.
+The JSON is the minimal terminal result projection and the report contains semantic coverage, native execution, Main-Agent review, optional independent Test Reviewer, and repair details. They must agree. Do not require an evidence package, manifest, hashes, attestation, package state, or test-internal checkpoint.
 
 ## Caller Routing
 
 The caller checkpoint records only the returned testing result and caller-owned routing state. It must not ask the skill to manage sessions or checkpoints.
 
 - `TEST_PASS` → mark `prizmkit-test` completed and continue to retrospective.
-- `TEST_NEEDS_FIXES` → stop the current caller path truthfully. If `review_required=true` and `review_scope=delta`, a caller may route the repaired delta through Code Review before invoking test again. Any continuation policy is caller-owned, not part of the test skill.
+- `TEST_NEEDS_FIXES` → this injected session classifies the exact unresolved correction into an allowed `repair_scope` and records both on the failed test step. If scope and outer budget permit, start `prizmkit-implement` with that explicit repair input; the checkpoint helper rewinds stale downstream steps, after which fresh `prizmkit-code-review`, configured verification, and `prizmkit-test` results are mandatory. If scope is unsafe/unknown or budget is exhausted, record terminal `WORKFLOW_BLOCKED`. Never recreate the testing-local repair loop.
 - `TEST_BLOCKED` → preserve the report, result, and blocker; record terminal `WORKFLOW_BLOCKED`. Do not reinterpret it as an AI CLI crash or perform speculative production edits.
 
 A test execution failure inside the skill is not automatically terminal: `/prizmkit-test` owns up to three direct diagnosis-and-repair rounds. The caller handles only the terminal result returned after that loop.

package/bundled/dev-pipeline/templates/sections/phase-review-full.md

@@ -2,10 +2,10 @@
 
 Review the completed implementation before the full Feature test gate runs. A review result is a required predecessor; never accept or route around testing as if a review had passed.
 
-Use `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` so `/prizmkit-code-review` can read the spec, plan, context snapshot, implementation log, and current diff. Follow the skill's current review contract for review execution, repairs, verification, evidence, and handoff. Do not invoke another review skill or add a second review path outside that contract.
+Invoke `/prizmkit-code-review` with the exact `artifact_dir`, spec, plan, and current change. The Skill owns review/repair and returns only `PASS` or `NEEDS_FIXES`; this injected session validates `review-report.md`, maps the result, updates checkpoint state, and chooses routing.
 
-- `REVIEW_PASS` → update checkpoint metadata with `stage=code-review`, `status=completed`, `stage_result=REVIEW_PASS`, `next_stage=prizmkit-test`, and `resume_from=prizmkit-test`; then run the full test gate.
-- `REVIEW_NEEDS_FIXES` → update the review step with `status=failed` and `stage_result=REVIEW_NEEDS_FIXES`, preserve findings, increment the shared outer `repair_round`, route `prizmkit-implement` → `prizmkit-code-review` → `prizmkit-test`, and do not accept any test result from before the repaired review.
+- Skill `PASS` with a valid report → map to `REVIEW_PASS`, mark the review checkpoint step completed, and continue to the next configured Browser/Manual verification step; invoke `prizmkit-test` only after those configured checks finish.
+- Skill `NEEDS_FIXES` with a valid report → map to `REVIEW_NEEDS_FIXES`, classify the concrete findings into an allowed `repair_scope`, and update the failed review step with both values. The checkpoint helper increments the shared outer `repair_round`; then route `prizmkit-implement` → `prizmkit-code-review` → configured verification → `prizmkit-test`, and do not accept any result from before the repaired review. If no safe scope can be established, block instead of guessing.
 - If the outer repair round is already three, record `WORKFLOW_BLOCKED`; do not start another repair route.
 
 Missing required evidence, unsafe repair, failed verification, or failure to converge under the review contract produces `REVIEW_NEEDS_FIXES`.
@@ -18,7 +18,7 @@ Missing required evidence, unsafe repair, failed verification, or failure to con
 
 Handle the marker:
 
-- `REVIEW_PASS` → proceed to the structured test gate.
+- `REVIEW_PASS` → proceed through configured Browser/Manual verification, then the structured test gate.
 - `REVIEW_NEEDS_FIXES` → follow the repair route above; do not externally restart the review loop.
 - `REVIEW_INCOMPLETE` or `REVIEW_INVALID` → inspect append-only progress once, write `failure-log.md`, and stop. Do not accept old/incidental verdict text or synthesize a pass.
 

package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md

@@ -5,9 +5,9 @@ Check existing artifacts first:
 {{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}
 ```
 
-- Both (spec.md, plan.md) exist → **SKIP to CP-1**
-- `context-snapshot.md` exists → use it directly, skip context snapshot building
-- Some missing → generate only missing files
+- Both `spec.md` and `plan.md` exist → preserve them; the planning Skill still validates them and returns the local result
+- `context-snapshot.md` exists → use it directly and skip snapshot rebuilding
+- Some planning artifacts are missing → let the planning Skill generate only the missing files
 
 Before planning, check whether feature code already exists in the project (use the helper to search source directories identified from `root.prizm` or the project tree scan):
 ```bash
@@ -55,8 +55,7 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
 {{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/plan.md
 ```
 
-- spec.md missing: Run `/prizmkit-plan` → generate spec.md. Resolve uncertain requirements from the task description, existing code, and conservative existing-project patterns.
-- plan.md missing: Run `/prizmkit-plan` → generate plan.md (change approach, components, interface design, data model, testing strategy, risk assessment, and Tasks section with `[ ]` checkboxes)
+Invoke `/prizmkit-plan` once with the exact `artifact_dir`, requirement description, and loaded project context. The Skill creates or validates both artifacts and returns only `PLAN_READY` or `PLAN_BLOCKED`. This injected session records `PLAN_READY` on checkpoint step `context-snapshot-and-plan`; `PLAN_BLOCKED` records the failed planning result and stops.
 
 > All files go under `.prizmkit/specs/{{FEATURE_SLUG}}/`. Confirm each with `ls` after writing.
 
@@ -67,17 +66,6 @@ Before proceeding past CP-1, verify:
 3. No unresolved data model uncertainty remains in the Data Model section — resolve by reading existing code and making a conservative choice that matches existing patterns. Document the resolution in plan.md.
 4. If a DB design decision genuinely cannot be resolved from existing code alone, document the assumption made and flag it in the Implementation Log for user review.
 
-**CP-1**: Both spec.md and plan.md exist.
-
-### Plan Self-Check — Orchestrator Direct
-
-The active planning skill and runtime determine whether any additional planning execution is appropriate. Do not treat this bounded self-check as a substitute for the planning skill's own review contract.
-
-1. Re-read only `context-snapshot.md`, `spec.md`, and `plan.md`.
-2. Cross-check spec.md and plan.md Tasks against the feature description and Verification Gates in the Task Contract.
-3. Verify the plan references the File Manifest and avoids unrelated work.
-4. If you find CRITICAL issues, fix ONLY those issues in spec.md/plan.md before continuing.
-
-**CP-1.5**: Plan self-check complete; no CRITICAL plan issues remain.
+**CP-1**: The Skill returned `PLAN_READY`; spec.md and plan.md exist and passed its planning review. The injected session validates artifact presence but does not perform a second planning review.
 
 

package/bundled/dev-pipeline/templates/sections/refactor-critical-paths.md

@@ -8,6 +8,8 @@
 | Review Report | `.prizmkit/refactor/{{REFACTOR_ID}}/review-report.md` |
 | Refactor Report | `.prizmkit/refactor/{{REFACTOR_ID}}/refactor-report.md` |
 | Completion Summary | `.prizmkit/refactor/{{REFACTOR_ID}}/completion-summary.json` |
+| Test Result | `.prizmkit/refactor/{{REFACTOR_ID}}/test-result.json` |
+| Retrospective Result | `.prizmkit/refactor/{{REFACTOR_ID}}/retrospective-result.json` |
+| Runtime Commit Request | `.prizmkit/refactor/{{REFACTOR_ID}}/runtime-commit-request.json` |
 | Workflow Checkpoint | `{{CHECKPOINT_PATH}}` |
-| Session Status Output | `{{SESSION_STATUS_PATH}}` |
 | Project Root | `{{PROJECT_ROOT}}` |

package/bundled/dev-pipeline/templates/sections/refactor-phase-commit-report.md

@@ -1,30 +1,17 @@
-### Phase 4: Commit, Report & Completion Summary
+### Refactor Report and Completion Summary
 
-**Refactor Documentation Policy**:
-- Default: run `/prizmkit-retrospective` with full sync because refactoring changes structure and interfaces.
-- Skip architecture knowledge injection only for a pure rename with no interface or dependency changes.
-
-Run `/prizmkit-retrospective` using the current working tree and staged changes as input context. Do not rely only on `git diff --cached`.
-
-Stage changed files explicitly; never use `git add -A` or `git add .`.
-
-Run `/prizmkit-committer` with commit prefix:
-
-```text
-refactor({{REFACTOR_ID}}): {{REFACTOR_TITLE}}
-```
-
-The runtime controls any optional remote publication after this local commit; do not make a publication decision in this session.
+After `TEST_PASS`, create both family artifacts before retrospective and runtime commit preparation.
 
 Write `.prizmkit/refactor/{{REFACTOR_ID}}/refactor-report.md` with:
-- refactor summary;
+
+- refactor summary and changed module boundaries;
 - files/modules changed;
-- behavior-preservation evidence before/after;
-- review findings;
-- browser evidence when applicable;
-- acceptance criteria checklist.
+- behavior-preservation evidence before and after;
+- Code Review and Test results;
+- configured browser verification evidence and limitations;
+- final acceptance-criteria checklist.
 
-Write `.prizmkit/refactor/{{REFACTOR_ID}}/completion-summary.json` for downstream refactor context:
+Write `.prizmkit/refactor/{{REFACTOR_ID}}/completion-summary.json`:
 
 ```json
 {
@@ -34,4 +21,4 @@ Write `.prizmkit/refactor/{{REFACTOR_ID}}/completion-summary.json` for downstrea
 }
 ```
 
-**Checkpoint update**: Set `prizmkit-retrospective`, `prizmkit-committer`, `refactor-report`, and `completion-summary` to `completed` as each finishes.
+Do not stage or commit. Mark `refactor-report` and `completion-summary` completed only after both artifacts are current and valid.

package/bundled/dev-pipeline/templates/sections/refactor-phase-implement.md

@@ -2,7 +2,7 @@
 
 **Goal**: execute the refactor plan while preserving behavior.
 
-Run `/prizmkit-implement` directly with `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/`.
+Invoke `/prizmkit-implement` with the exact `artifact_dir`, reviewed spec/plan, and any explicit repair findings. It returns only `IMPLEMENTED` or `IMPLEMENT_BLOCKED`.
 
 Rules:
 - Follow the implementation skill's current execution and delegation contract.
@@ -13,4 +13,4 @@ Rules:
 - If tests fail unexpectedly, treat it as a behavior-preservation failure and fix before proceeding.
 - Document changed module boundaries and any deviations from the plan in `context-snapshot.md`.
 
-**Checkpoint update**: Set step `prizmkit-implement` to `completed` when all tasks are `[x]` and behavior-preservation evidence is recorded.
+**Checkpoint update**: This injected session maps `IMPLEMENTED` to a completed step when all tasks are `[x]` and behavior-preservation evidence is valid. `IMPLEMENT_BLOCKED` records the blocker and stops.

package/bundled/dev-pipeline/templates/sections/refactor-phase-plan.md

@@ -2,7 +2,7 @@
 
 **Goal**: produce a behavior-preserving refactor plan before editing code.
 
-Run `/prizmkit-plan` with `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/`.
+Invoke `/prizmkit-plan` once with the exact `artifact_dir`, refactor requirement, behavior-preservation input, and project context. It returns only `PLAN_READY` or `PLAN_BLOCKED`.
 
 The spec.md must include:
 - refactor goals and acceptance criteria;
@@ -19,4 +19,4 @@ The plan.md must include:
 
 Resolve uncertain refactor details from existing code and conservative project patterns. Do not expand scope beyond the task contract.
 
-**Checkpoint update**: Set step `prizmkit-plan` to `completed` after `spec.md` and `plan.md` exist.
+**Checkpoint update**: This injected session sets `prizmkit-plan` to `completed` only after `PLAN_READY` and validation of `spec.md`/`plan.md`; `PLAN_BLOCKED` records the blocker and stops.

package/bundled/dev-pipeline/templates/sections/refactor-phase-review.md

@@ -1,6 +1,6 @@
 ### Phase 3: Review — Code Review & Behavior Verification
 
-Run `/prizmkit-code-review` directly with `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/` and follow the skill's complete review contract for review execution, repairs, verification, evidence, and handoff. Do not invoke another review skill or add a second review path outside that contract.
+Invoke `/prizmkit-code-review` with the exact `artifact_dir`, spec, plan, and current change. The Skill returns only `PASS` or `NEEDS_FIXES`; this injected session validates `review-report.md`, maps the result, updates the checkpoint, and chooses routing.
 
 Missing required evidence, an unsafe repair, a failed verification, or failure to converge under the review contract produces `NEEDS_FIXES`.
 
@@ -10,8 +10,8 @@ Missing required evidence, an unsafe repair, a failed verification, or failure t
 {{RUNTIME_HELPER_CMD}} text final-verdict .prizmkit/refactor/{{REFACTOR_ID}}/review-report.md
 ```
 
-- `REVIEW_PASS` → proceed.
-- `REVIEW_NEEDS_FIXES` → log unresolved findings and proceed only when they do not block behavior preservation under explicit task policy.
+- Skill `PASS` with a valid report → map to `REVIEW_PASS` and proceed to configured verification and the authoritative Test gate.
+- Skill `NEEDS_FIXES` with a valid report → map to `REVIEW_NEEDS_FIXES`, classify the concrete findings into an allowed `repair_scope`, mark the review step failed with both values, preserve findings, and route through the bounded repair path. If scope is unsafe/unknown or the outer repair budget is exhausted, record `WORKFLOW_BLOCKED`. Never continue as though review passed.
 - `REVIEW_INCOMPLETE` or `REVIEW_INVALID` → inspect progress once, write `failure-log.md`, and stop. Do not accept stale verdict text or synthesize a passing result outside the skill.
 
 Verify directly that the review checks behavior preservation, public API compatibility, imports, tests, and rollback assumptions.

package/bundled/dev-pipeline/templates/sections/refactor-phase-test.md

@@ -16,9 +16,9 @@ They must agree on the testing result and unresolved items. Do not require an ev
 Gate outcomes:
 
 - `TEST_PASS`: verify required behavior-preservation coverage is included, mark the test step completed, and continue to retrospective.
-- `TEST_NEEDS_FIXES`: preserve the report/result and stop truthfully. A high-risk production repair reports `review_required=true` and `review_scope=delta`; the caller owns any review-and-retest route.
+- `TEST_NEEDS_FIXES`: this injected session classifies the exact unresolved correction into an allowed `repair_scope` and records both on the failed test step. If scope and outer budget permit, start `prizmkit-implement` with that explicit repair input; the helper rewinds stale downstream steps, then fresh review, configured verification, and test results are mandatory. If scope is unsafe/unknown or budget is exhausted, record terminal `WORKFLOW_BLOCKED`. Never recreate the testing-local repair loop.
 - `TEST_BLOCKED`: preserve the report/result and blocker, then record terminal `WORKFLOW_BLOCKED`. Do not reinterpret the result as a runtime crash or make speculative production edits.
 
 The skill itself diagnoses and repairs valid execution failures for at most three rounds before returning. The caller must not recreate that repair loop or maintain test-internal state.
 
-**Checkpoint update**: Only `TEST_PASS` plus `test-report.md` and `test-result.json` completes `prizmkit-test` and allows retrospective.
+**Checkpoint update**: This injected session completes `prizmkit-test` only for `TEST_PASS` plus valid `test-report.md` and `test-result.json`; non-pass results follow the routing above.

package/bundled/dev-pipeline/templates/sections/refactor-reminders.md

@@ -1,12 +1,12 @@
 ## Reminders
 
-- Use the atomic skills: `/prizmkit-plan`, `/prizmkit-implement`, `/prizmkit-code-review`, `/prizmkit-retrospective`, `/prizmkit-committer`.
+- Use every formal atomic stage: `/prizmkit-plan`, `/prizmkit-implement`, `/prizmkit-code-review`, `/prizmkit-test`, `/prizmkit-retrospective`, `/prizmkit-committer` preparation.
 - All refactor skills use `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/`.
 - Behavior preservation is the first priority.
-- Follow the active skills and runtime contracts; they determine execution topology, review ownership, and delegation boundaries
-- On execution-unit timeout, preserve the active checkout and artifacts and follow the owning contract's recovery or downgrade path
-- Main orchestrator runs `/prizmkit-code-review` directly.
-- Commit with `refactor(<scope>):`, not `feat:` or `fix:`.
-- Checkpoint state is the recovery truth; skipped steps must be marked `skipped`.
-- Browser verification is a mandatory attempt by default; it blocks only when explicitly required.
+- Follow the active skills and runtime contracts; they determine execution topology, review ownership, and delegation boundaries.
+- On execution-unit timeout, preserve the active checkout and artifacts and follow the owning contract's recovery or downgrade path.
+- Main orchestrator runs `/prizmkit-code-review` directly and never routes around `REVIEW_NEEDS_FIXES`.
+- Use a `refactor(<scope>):` Conventional Commit message in the runtime commit request.
+- Checkpoint state is recovery guidance; mandatory stage results and their authoritative artifacts remain required.
+- Browser verification is present only when configured; follow its configured blocking policy.
 - If `DEV_PORT` is unknown, discover it from project config; do not guess port 3000.

package/bundled/dev-pipeline/templates/sections/refactor-session-context.md

@@ -4,4 +4,3 @@
 - **Title**: {{REFACTOR_TITLE}}
 - **Type**: {{REFACTOR_TYPE}}
 - **Priority**: {{PRIORITY}} | **Complexity**: {{COMPLEXITY}}
-- **Mode**: {{PIPELINE_MODE}}

package/bundled/dev-pipeline/templates/sections/retrospective.md

@@ -0,0 +1,12 @@
+### Retrospective — Durable Documentation Sync
+
+After validating Code Review, configured verification, `TEST_PASS`, and family reports/summaries, invoke `/prizmkit-retrospective` with the exact `artifact_dir`, exact non-`.prizmkit/` `change_paths`, and a concise `change_summary`. The Skill returns only `RETRO_COMPLETE` or `RETRO_BLOCKED`.
+
+The retrospective must:
+
+1. Treat only the exact supplied non-`.prizmkit/` `change_paths` as authoritative input; do not expand scope.
+2. Synchronize `.prizmkit/prizm-docs/` only for durable structure, interfaces, dependencies, behavior, TRAPS, RULES, or DECISIONS.
+3. Write `{{ARTIFACT_DIR}}/retrospective-result.json` with `outcome=RETRO_COMPLETE` and `result=DOCS_UPDATED|NO_DOC_CHANGE`.
+4. Validate any changed Prizm docs.
+
+Do not stage or commit. This injected session validates `retrospective-result.json` and maps `RETRO_COMPLETE` to the completed checkpoint step. `RETRO_BLOCKED` records the blocker and stops.