prizmkit 1.1.154 → 1.1.156

package/bundled/dev-pipeline/scripts/update-feature-status.py

@@ -1398,11 +1398,8 @@ def action_status(feature_list_data, state_dir, feature_filter=None, project_roo
         fstatus = feature.get("status", "pending")
         fs = load_feature_status(state_dir, fid)
         feature_slug = _build_feature_slug(fid, title)
-        # Read phase cursor from checkpoint (authoritative when valid).
+        # Read the authoritative checkpoint cursor without mutating cached runtime state.
         resume_phase = _checkpoint_phase_or_cached(project_root, feature_slug, fs)
-        if resume_phase != fs.get("resume_from_phase"):
-            fs["resume_from_phase"] = resume_phase
-            save_feature_status(state_dir, fid, fs)
         degraded_reason = degraded_reason_map.get(fid)
 
         # Count statuses

package/bundled/dev-pipeline/scripts/update-refactor-status.py

@@ -1010,11 +1010,8 @@ def action_status(refactor_list_data, state_dir, project_root=None):
         rs = load_refactor_status(state_dir, rid)
         retry_count = rs.get("retry_count", 0)
         max_retries_val = rs.get("max_retries", 3)
-        # Read phase cursor from checkpoint (authoritative when valid).
+        # Read the authoritative checkpoint cursor without mutating cached runtime state.
         resume_phase = _checkpoint_phase_or_cached(project_root, rid, rs)
-        if resume_phase != rs.get("resume_from_phase"):
-            rs["resume_from_phase"] = resume_phase
-            save_refactor_status(state_dir, rid, rs)
 
         if rstatus in counts:
             counts[rstatus] += 1

package/bundled/dev-pipeline/templates/bootstrap-prompt.md

@@ -1,8 +1,6 @@
-# Dev-Pipeline Fallback Bootstrap Prompt
+# Dev-Pipeline Custom Feature Prompt Compatibility Template
 
-> **Note**: This is an emergency fallback template. Normally, `generate-bootstrap-prompt.py`
-> renders modular full guidance from `templates/sections/`. If sections are unavailable,
-> it tries `bootstrap-tier3.md` before this last-resort fallback.
+> Canonical pipeline generation uses `templates/sections/`. This monolithic file is retained only as an explicit `--template` compatibility input.
 
 ## Feature Context
 
@@ -17,34 +15,31 @@
 
 {{ACCEPTANCE_CRITERIA}}
 
-## Instructions
+## Your Mission
 
-You are running in **headless non-interactive mode** — no human is available for input.
-Infer what needs to be done from the feature context above and follow the active skill and runtime contracts. Do not exit while recoverable work remains. If a required gate is blocked or the workflow cannot safely continue, record the blocker and stop with a truthful blocked status; do not claim success or commit an incomplete change.
+Complete the feature in headless non-interactive mode using the active atomic skills and Python runtime contracts. Resolve only safe deterministic uncertainty; otherwise record a truthful blocker. Do not claim a failed gate passed and do not mutate Git.
 
-### Execution Steps
+## Context and State Boundaries
 
-1. **Read context**: Read `.prizmkit/prizm-docs/root.prizm` and the relevant module indexes and detail docs to understand the codebase.
+- Read `root.prizm`, then only relevant module/detail docs and source files.
+- Use `context-snapshot.md` for navigation, not as a substitute for current source, diffs, or authoritative artifacts.
+- Verify modifications with bounded reads, diffs, static checks, and focused tests as appropriate.
+- Atomic Skills return stage-local artifacts/results only. This injected session owns stage order, routing, and checkpoint updates; never hand-edit runner-owned family/session/heartbeat/progress/retry/checkout/daemon/log state.
+- Do not stage, commit, amend, merge, push, reset, clean, or perform destructive filesystem cleanup.
 
-2. **Plan**: Run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to produce `spec.md` and `plan.md`.
+{{CHECKPOINT_SYSTEM}}
 
-3. **Implement**: Run `/prizmkit-implement` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to execute the plan using TDD (write tests first, then implement).
+## Execution
 
-4. **Review**: Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` and follow the skill's current review contract for review execution, repairs, verification, evidence, and handoff. Require the last `## Final Result`. `REVIEW_PASS` proceeds to test; `REVIEW_NEEDS_FIXES` increments the shared outer repair round and routes implement → code-review → test. Do not invoke another review entry point or add a second review path outside the skill contract.
+1. Invoke `/prizmkit-plan` with the exact artifact root; validate `PLAN_READY`, then this session updates the planning checkpoint.
+2. Invoke `/prizmkit-implement` with the reviewed artifacts and any explicit repair input; validate `IMPLEMENTED`, then this session updates the implementation checkpoint.
+3. Invoke `/prizmkit-code-review`; map Skill `PASS`/`NEEDS_FIXES` to caller `REVIEW_PASS`/`REVIEW_NEEDS_FIXES` and own any bounded repair route.
+4. Complete configured Browser/Manual verification before the authoritative Test stage.
+5. Invoke `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`. Validate its report/result pair. For `TEST_NEEDS_FIXES`, classify the concrete correction into an allowed `repair_scope`; unknown/unsafe scope blocks, while a safe in-budget route re-enters Implement and requires fresh Review, configured verification, and Test. Do not duplicate the Skill's internal repair loop.
+6. Write `completion-summary.json` before retrospective and commit preparation.
+7. Invoke `/prizmkit-retrospective` with the exact artifact root, non-`.prizmkit/` `change_paths`, and `change_summary`; validate `outcome=RETRO_COMPLETE`.
+8. Before commit preparation, all `.prizmkit/**` paths are PrizmKit-internal and stay outside `intended_paths` together with recognized platform support; project-specific transient data must already be Git-ignored, while unknown Git-visible paths block. After validating every required artifact, invoke `/prizmkit-committer operation=prepare-runtime-commit artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/ evidence_paths=<exact paths> excluded_paths=.prizmkit/specs/{{FEATURE_SLUG}}/workflow-checkpoint.json request_path=.prizmkit/specs/{{FEATURE_SLUG}}/runtime-commit-request.json`. Require `COMMIT_REQUEST_READY`; this session then records `COMMIT_PENDING` and stops. The Python runtime executes and verifies the local commit.
 
-5. **Test**: After review passes, run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`. Consume the sibling `test-report.md` and `test-result.json`; they must agree. `TEST_PASS` proceeds to retrospective. `TEST_NEEDS_FIXES` or `TEST_BLOCKED` preserves its known correction or blocker and stops truthfully. Do not require an evidence package, reinterpret a testing result as a runtime crash, or recreate the skill's bounded review and repair loops.
+## Failure Capture
 
-6. **Retrospective**: Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/` with code changes.
-
-7. **Commit**: Run `/prizmkit-committer` to commit all changes.
-
-### Critical Rules
-
-- Do NOT ask for user input — decide autonomously.
-- Remote publication is controlled by the runtime after the local commit; do not make a publication decision in this session.
-- Write all artifacts to `.prizmkit/specs/{{FEATURE_SLUG}}/`.
-- If a step fails after 3 attempts, write a status report and stop.
-- **Never re-read unmodified files**: once you read a file into context, do NOT read it again unless it was modified by an Edit/Write after your last read — use `grep -n`/`sed -n` for specific lines. Before issuing a Read, ask: "Have I read this file before, and has it changed since?" If no — do NOT read it. Follow the active skill and runtime contracts when an execution unit is created; do not infer its permissions, continuation, or retry behavior from this fallback prompt.
-- **Read offset safety**: if Read returns "shorter than offset"/"empty" — run `wc -l` then `sed -n`, do NOT retry same offset.
-- Follow each skill's own bounded loops; do not add a second cross-skill test-fix loop in this fallback prompt.
-- **Layered test**: debug with single-file tests, only run full suite as gate when single-file is green.
+Before an incomplete exit, write `.prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md` with the failed stage, root cause, attempted recovery, next safe action, and any durable traps discovered.

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -12,7 +12,7 @@ You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATU
 
 **CRITICAL**: Do not exit while recoverable work remains. If a required gate is blocked or the workflow cannot safely continue, record the blocker and stop with a truthful blocked status; do not claim success or commit an incomplete change.
 
-**Tier 3 — Full Guardrails**: Follow the active skills and runtime contracts for context loading, planning, implementation, review, testing, recovery, and commit. The active contracts determine the execution topology and permissions for any execution units they create.
+**Canonical Guardrails**: Follow the active skills and runtime contracts for context loading, planning, implementation, review, testing, recovery, retrospective, and runtime-owned commit execution. The active contracts determine the execution topology and permissions for any execution units they create.
 
 **Execution-unit failure policy**:
 - Do not invoke another review skill/workflow or add review execution outside the contract owned by `prizmkit-code-review`.
@@ -43,34 +43,44 @@ You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATU
 
 {{GLOBAL_CONTEXT}}
 
-## ⚠️ 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 Phase 1-2 makes it 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 including those 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 bootstrap.
-4. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
-4. **One task at a time** — In Phase 4 (implement), complete and test one task before starting the next.
-5. **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.
-6. **No intermediate commits** — Do NOT run `git add`/`git commit` during Phase 1-5. All changes are committed once at the end in Phase 6 via `/prizmkit-committer`.
-7. **Batch independent operations** — Issue multiple independent `Write`/`Read` calls in a single message turn when they have no dependencies. Combine multiple `mkdir -p` into one command. Never run `npm test` twice just to apply a different grep filter — capture output to `/tmp/test-out.txt` once and grep the file.
-9. **Package version verification (BLOCKING)** — Verify dependency versions via registry query before writing them. NEVER guess.
-10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`.
-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. Resolve safe uncertainty from the task contract, current code, and project documentation. If no safe deterministic choice exists, record a truthful blocker.
+2. Read `root.prizm`, then only relevant module/detail docs and source. Use `context-snapshot.md` for navigation and handoff, not as a substitute for current source, diffs, or stage artifacts.
+3. Avoid repeated full-file reads, but reread the smallest relevant range after edits, compaction, possible staleness, or when verification requires final content. Never trust an unverified write.
+4. Verify edits with the smallest appropriate diff, parser, formatter, type check, focused test, or bounded read.
+5. Keep scope tied to the task contract, concrete dependency/caller evidence, and mandatory lifecycle gates.
+6. Use focused implementation checks; `/prizmkit-test` exclusively owns the complete affected-module gate and its bounded repair loop.
+7. Bound command output with host-appropriate temporary locations and inspect only relevant summaries. Do not require a fixed POSIX-only path.
+8. Follow project package-manager, lockfile, registry, and version-pinning conventions; do not guess versions.
+9. Keep generated binaries, caches, and temporary output out of the intended commit unless they are source artifacts.
+10. Do not stage, commit, amend, merge, push, reset, clean, or perform destructive filesystem cleanup. The committer prepares a request and the Python runtime executes the local commit.
+11. Atomic Skills return only stage-local artifacts and results. This injected session owns stage order, result routing, and checkpoint updates; never hand-edit runner-owned family/session/heartbeat/progress/retry/checkout/daemon/log state.
+12. After a failed bounded read, refresh a stable anchor or file length before another attempt; do not repeat an invalid offset.
 
 ---
 
-## PrizmKit Directory Convention
+## Requirement Artifact Manifest
 
 ```
-.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md  ← Main Agent writes Sections 1-4 + Implementation Log
-.prizmkit/specs/{{FEATURE_SLUG}}/spec.md
-.prizmkit/specs/{{FEATURE_SLUG}}/plan.md              ← includes Tasks section
+.prizmkit/specs/{{FEATURE_SLUG}}/
+├── spec.md
+├── plan.md
+├── context-snapshot.md
+├── review-report.md
+├── test-report.md
+├── test-result.json
+├── completion-summary.json
+├── retrospective-result.json
+├── failure-log.md
+├── workflow-checkpoint.json
+└── runtime-commit-request.json
 ```
 
+{{CHECKPOINT_SYSTEM}}
+
 **`context-snapshot.md`** is the implementation knowledge base. The Main Agent writes Sections 1-4 and the Implementation Log. Code Review writes only `review-report.md` and never appends separate Review Notes.
 
 ---
@@ -79,7 +89,7 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 
 If an execution unit times out:
 1. `{{RUNTIME_HELPER_CMD}} artifact list .prizmkit/specs/{{FEATURE_SLUG}}` — check what exists
-2. If `context-snapshot.md` exists: open a recovery prompt with `"Read .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md for project context and the Implementation Log from the previous execution. Run git diff HEAD to see actual code changes already made. Do NOT re-read individual source files unless the File Manifest directs you to."` + only remaining steps + `model: "lite"`
+2. If `context-snapshot.md` exists, use it for recovery navigation together with the current diff and the smallest relevant current-source reads. Continue only the remaining steps under the owning skill's execution budget.
 3. Apply the owning skill or runtime contract for retry, native continuation, strict downgrade, or Main-Agent fallback. Do not create an unapproved replacement execution unit.
 4. Do not poll indefinitely after the owning contract's retry budget is exhausted; write `failure-log.md` with the timeout and last observable state when recovery is blocked.
 
@@ -113,9 +123,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 Phase 1
-- 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
@@ -163,8 +173,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 feature description, existing code, and conservative existing-project patterns.
-- plan.md missing: Run `/prizmkit-plan` → generate plan.md (architecture, 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. It creates or validates both artifacts and returns only `PLAN_READY` or `PLAN_BLOCKED`. This injected session maps `PLAN_READY` to the planning checkpoint step; `PLAN_BLOCKED` records the blocker and stops.
 
 > All files go under `.prizmkit/specs/{{FEATURE_SLUG}}/`. Confirm each with `ls` after writing.
 
@@ -175,44 +184,33 @@ 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.
-
-### Phase 3: 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 acceptance criteria.
-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-2**: 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. This injected session validates artifact presence but does not perform a second planning review.
 
 
 ### 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. It 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)**:
@@ -235,32 +233,20 @@ For each Verification Gate from the Task Contract, write one evidence line to Im
 
 ### Review — Code Review
 
-Review the completed implementation before the full Feature test gate. Run `/prizmkit-code-review artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` and 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 root, spec, plan, and complete current change. It returns only `PASS` or `NEEDS_FIXES`; this injected session validates `review-report.md`, maps that result, updates the checkpoint, and chooses routing.
 
-- `REVIEW_PASS` → record `stage=code-review`, `status=completed`, `stage_result=REVIEW_PASS`, `next_stage=prizmkit-test`, and `resume_from=prizmkit-test`; then run the test gate.
-- `REVIEW_NEEDS_FIXES` → increment the shared outer `repair_round` and route `prizmkit-implement` → `prizmkit-code-review` → `prizmkit-test`.
+- Skill `PASS` with a valid report → map to `REVIEW_PASS`, mark the review checkpoint step completed, and continue to configured Browser/Manual verification; invoke `prizmkit-test` only after those checks finish.
+- Skill `NEEDS_FIXES` with a valid report → map to `REVIEW_NEEDS_FIXES`, classify concrete findings into an allowed `repair_scope`, and record both. The helper increments the outer `repair_round`; safe in-budget repair routes through `prizmkit-implement` → `prizmkit-code-review` → configured verification → `prizmkit-test`, while unknown/unsafe scope blocks.
 - Stop as `WORKFLOW_BLOCKED` when the outer repair round is already three. The Main-Agent review loop has its separate limit of up to ten completed rounds.
 
-`review-report.md` is the only persisted review artifact; do not append separate Review Notes to `context-snapshot.md`. Missing evidence, unsafe repair, failed verification, or non-convergence produces `REVIEW_NEEDS_FIXES`.
+`review-report.md` is the only persisted review artifact; do not append separate Review Notes to `context-snapshot.md`. Missing evidence, unsafe repair, failed verification, or non-convergence produces Skill `NEEDS_FIXES`, which this session maps to `REVIEW_NEEDS_FIXES`.
 
 **Gate Check — Final Review Result**:
 ```bash
 {{RUNTIME_HELPER_CMD}} text final-verdict .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md
 ```
 
-Only `REVIEW_PASS` can proceed to the structured Feature test gate. `REVIEW_INCOMPLETE` or `REVIEW_INVALID` writes `failure-log.md` and stops.
-
-### Scoped Feature Test Gate — PrizmKit Test
-
-Invoke the Feature test gate:
-
-```text
-/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/
-```
-
-Consume `.prizmkit/specs/{{FEATURE_SLUG}}/test-report.md` and `test-result.json`. They must agree. `TEST_PASS` completes the gate; `TEST_NEEDS_FIXES` preserves a known correction or delta-review requirement and stops truthfully; `TEST_BLOCKED` preserves the blocker and becomes `WORKFLOW_BLOCKED`. Do not require an evidence package, manifest, hashes, attestation, or test-internal checkpoint, and do not reinterpret a testing result as an AI CLI crash.
-
-Record only caller-owned `stage`, `status`, `stage_result`, `repair_scope`, `repair_round`, `next_stage`, and `resume_from` in recovery metadata. Keep testing reports/results separate from `workflow-checkpoint.json`. The skill owns its internal ten-round Main-Agent review, five-response optional independent review, and three-round execution-failure repair budgets.
+Only `REVIEW_PASS` can proceed to configured verification and the structured Feature test gate. `REVIEW_INCOMPLETE` or `REVIEW_INVALID` writes `failure-log.md` and stops.
 
 {{IF_BROWSER_INTERACTION}}
 ### Phase 5.5: Browser Verification — MANDATORY
@@ -420,50 +406,23 @@ If verification fails:
 You MUST attempt verification and MUST clean up the dev server in both cases.
 {{END_IF_BROWSER_INTERACTION}}
 
-### Phase 6: Retrospective & Commit (SINGLE COMMIT) — DO NOT SKIP
-
-**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}}):`.
-
-**6a.** 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 6d** (do NOT run /prizmkit-committer, do NOT run git reset, do NOT stage or unstage anything). Proceed directly to 6e Final verification.
-- If no existing commit → proceed normally with 6b–6d.
+### Scoped Feature Test Gate — PrizmKit Test
 
-**6b.** Run `/prizmkit-retrospective` (**before commit**, maintains `.prizmkit/prizm-docs/` architecture index):
-- **Structural sync**: update KEY_FILES/INTERFACES/DEPENDENCIES/file counts for changed modules
-- **Architecture knowledge** (feature sessions only): extract TRAPS, RULES, DECISIONS from completed work into `.prizmkit/prizm-docs/`
-- **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.
-- Stage doc changes: `git add .prizmkit/prizm-docs/`
-⚠️ Do NOT commit here. Only stage.
+After configured Browser/Manual verification, invoke the Feature test gate:
 
-**6c.** 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/
+```text
+/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/
 ```
 
-**6d.** 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.
+Consume `.prizmkit/specs/{{FEATURE_SLUG}}/test-report.md` and `test-result.json`. They must agree. `TEST_PASS` completes the gate. For `TEST_NEEDS_FIXES`, classify the concrete correction into an allowed `repair_scope`; safe in-budget repair re-enters Implement through the helper and requires fresh Review, configured verification, and Test, while unknown/unsafe scope or exhausted budget blocks. `TEST_BLOCKED` preserves the blocker and becomes `WORKFLOW_BLOCKED`. Do not require an evidence package, manifest, hashes, attestation, or test-internal checkpoint, and do not reinterpret a testing result as an AI CLI crash.
 
-**6e.** 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.
+Record only caller-owned `stage`, `status`, `stage_result`, `repair_scope`, `repair_round`, `next_stage`, and `resume_from` in recovery metadata. Keep testing reports/results separate from `workflow-checkpoint.json`. The skill owns its internal ten-round Main-Agent review, five-response optional independent review, and three-round execution-failure repair budgets.
 
-**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.
+### Phase 6: Reports, Retrospective & Runtime Commit Handoff — DO NOT SKIP
 
-**6f.** Write completion summary for downstream dependency context:
+**6a. Completion summary before commit preparation**
 
-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.
+Write `.prizmkit/specs/{{FEATURE_SLUG}}/completion-summary.json` with the key changes from this session before retrospective and commit preparation.
 
 ```json
 {
@@ -483,6 +442,16 @@ Rules for writing completion notes:
 - 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)
 
+**6b. Retrospective**
+
+Invoke `/prizmkit-retrospective` with the exact artifact root, exact non-`.prizmkit/` `change_paths`, and a concise `change_summary`. Validate `outcome=RETRO_COMPLETE`; do not stage or commit.
+
+**6c. Runtime commit preparation**
+
+Before commit preparation, all `.prizmkit/**` paths are PrizmKit-internal and stay outside `intended_paths`, together with `AGENTS.md`, `skills-lock.json`, installed platform directories, and local platform settings. Project-specific transient data must already be covered by Git ignore rules. Unknown Git-visible paths are not silently ignored: justify and include them as task output or block.
+
+After this injected session validates every required artifact, invoke `/prizmkit-committer operation=prepare-runtime-commit artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/ evidence_paths=<exact paths> excluded_paths=.prizmkit/specs/{{FEATURE_SLUG}}/workflow-checkpoint.json request_path=.prizmkit/specs/{{FEATURE_SLUG}}/runtime-commit-request.json`. Require `COMMIT_REQUEST_READY`; this session records `COMMIT_PENDING` and stops. The Python runtime validates the request, executes/verifies the local commit, and finalizes checkpoint `COMMITTED`.
+
 ## Critical Paths
 
 | Resource | Path |
@@ -511,14 +480,12 @@ If you encounter an unrecoverable error, context overflow, or are about to exit
 
 ## Reminders
 
-- Tier 3: orchestrator follows the active skill and runtime contracts; they determine execution topology, review ownership, and delegation boundaries
+- The orchestrator follows the active skill and runtime contracts; they determine execution topology, review ownership, and delegation boundaries
 - context-snapshot.md contains Main-Agent implementation context; Code Review writes only review-report.md
 - Gate checks require the Implementation Log and a valid review-report.md Final Result before proceeding
 - Review execution outside the owning skill contract is forbidden; execution-unit retry and background behavior come from the active skill/runtime contract
-- Commit phase must use `/prizmkit-committer`; do NOT replace with manual git commit commands
-- **NEVER delete, modify, or touch any file under `.prizmkit/state/`** — those are pipeline runtime files managed by the runner
+- `/prizmkit-committer operation=prepare-runtime-commit` validates gates and writes the exact request without Git mutation
+- Atomic Skills remain stage-local; this injected session alone maps their results to checkpoint transitions and later invocations
 - NEVER run `rm -rf`, `git clean`, or any destructive filesystem operations
-- Do NOT run `git add`/`git commit` during Phase 1-5 — all changes are committed once in Phase 6
-- If any files remain after the commit, amend the existing commit — do NOT create a follow-up commit
-- When staging files, always use explicit file names — NEVER use `git add -A` or `git add .`
+- Do not stage, commit, amend, merge, reset, or push; the Python runtime executes and verifies the prepared local commit
 - On execution-unit timeout: follow the owning skill/runtime contract, preserve the active checkout and artifacts, and record a truthful blocker when recovery is exhausted