prizmkit 1.1.153 → 1.1.155

package/bundled/skills/prizmkit/references/workflow-state-protocol.md

@@ -4,11 +4,13 @@
 
 ## Location and Identity
 
+The state filename uses the validated exact basename of `artifact_dir` without a second slug transformation:
+
 ```text
-.prizmkit/state/workflows/<requirement-slug>.json
+.prizmkit/state/workflows/<requirement-identity>.json
 ```
 
-The active `artifact_dir` is preserved exactly across every stage:
+An existing state path whose recorded `artifact_dir` differs from the active artifact is a blocking collision; never overwrite, merge, or suffix it automatically. The active `artifact_dir` is preserved exactly across every stage:
 
 ```text
 .prizmkit/specs/<requirement-slug>/
@@ -31,7 +33,7 @@ The state file is an index, not the authority for stage completion:
 | Terminal testing result | `{artifact_dir}/test-result.json` |
 | Retrospective completion | `{artifact_dir}/retrospective-result.json` |
 | Durable architecture knowledge | `.prizmkit/prizm-docs/` |
-| Local commit | Git history and confirmed or authorized commit identity |
+| Local commit | Git history and runtime- or user-verified commit identity |
 | Current stage, orchestrator, and resume entry | Workflow state |
 | External orchestration progress | External host checkpoint |
 
@@ -64,7 +66,7 @@ Every consumer compares workflow state with the skill-owned artifacts and curren
 | `orchestrator` | Semantic coordinator identifier, or null for direct stage use. |
 | `stage` | Stage that most recently wrote state. |
 | `status` | Lifecycle status: `pending`, `in_progress`, `completed`, `failed`, or `skipped`. |
-| `stage_result` | Domain result for the current stage, such as `PLAN_READY`, `IMPLEMENTED`, `REVIEW_PASS`, `REVIEW_NEEDS_FIXES`, `TEST_*`, `RETRO_COMPLETE`, or `COMMITTED`. |
+| `stage_result` | Coordinator-recorded lifecycle result mapped from a validated atomic result and its required artifacts, such as `PLAN_READY`, `IMPLEMENTED`, `REVIEW_PASS`, `REVIEW_NEEDS_FIXES`, `TEST_*`, `RETRO_COMPLETE`, or `COMMITTED`. |
 | `completed_stages` | Ordered stages completed for this requirement. |
 | `repair_scope` | Optional caller-owned routing scope. The test skill reports high-risk repairs through `test-result.json` instead of scheduling another stage. |
 | `repair_round` | Optional outer cross-stage repair round, from 0 through 3. It is not a test-internal repair counter. |
@@ -97,10 +99,10 @@ review-report NEEDS_FIXES        → status=failed,     stage_result=REVIEW_NEED
 test-result TEST_PASS            → status=completed,  stage_result=TEST_PASS
 test-result TEST_NEEDS_FIXES     → status=failed,     stage_result=TEST_NEEDS_FIXES
 test-result TEST_BLOCKED         → status=failed,     stage_result=TEST_BLOCKED
-retrospective DOCS_UPDATED       → status=completed,  stage_result=RETRO_COMPLETE
-retrospective NO_DOC_CHANGE      → status=completed,  stage_result=RETRO_COMPLETE
-retrospective blocked            → status=failed,     stage_result=RETRO_BLOCKED
-commit authorization pending     → status=in_progress, stage_result=COMMIT_PENDING
+retrospective outcome=RETRO_COMPLETE, result=DOCS_UPDATED   → status=completed, stage_result=RETRO_COMPLETE
+retrospective outcome=RETRO_COMPLETE, result=NO_DOC_CHANGE  → status=completed, stage_result=RETRO_COMPLETE
+retrospective outcome=RETRO_BLOCKED                         → status=failed,    stage_result=RETRO_BLOCKED
+runtime commit preparation       → status=in_progress, stage_result=COMMIT_PENDING
 local commit confirmed           → status=completed,  stage_result=COMMITTED
 commit blocked                   → status=failed,     stage_result=COMMIT_BLOCKED
 ```
@@ -115,8 +117,8 @@ commit blocked                   → status=failed,     stage_result=COMMIT_BLOC
 
 ```text
 TEST_NEEDS_FIXES
-→ known correction or required delta review remains
-→ caller decides whether and how to arrange another stage
+→ a known correction remains
+→ caller decides whether and how to arrange another invocation
 
 TEST_BLOCKED
 → truth, input, safe environment, or reliable execution prevents a verdict
@@ -132,30 +134,32 @@ Any outer repair or continuation policy is independently owned by the caller and
 
 1. An atomic stage performs only its own stage, writes its truthful result and artifact paths, and returns control.
 2. When `orchestrator` is non-null, only that orchestrator invokes the next skill.
-3. Direct stage use may report a possible next invocation but does not claim it ran.
+3. Direct atomic use returns only its local result and artifacts; it does not report or select another invocation.
 4. Every handoff preserves the same `artifact_dir`.
 5. External automation invokes atomic stages directly and does not nest the composite workflow.
 6. Workflow state never replaces or absorbs an external host checkpoint.
 
-## Commit Authorization
+## Commit Execution Ownership
 
 Interactive execution:
 
 ```text
 committer previews intended files and message
 → waits for explicit current-user confirmation
-→ creates the local commit
+→ stages, creates, and verifies the local commit
 ```
 
-Trusted headless execution:
+Pipeline execution:
 
 ```text
-trusted host explicitly authorizes the current local task commit
-→ committer verifies gates and commits automatically
+external coordinator validates its required gates and supplies exact readiness evidence
+→ committer validates only that evidence and writes an exact runtime-commit-request.json
+→ external coordinator maps COMMIT_REQUEST_READY to its checkpoint's in_progress/COMMIT_PENDING state
+→ Python runtime validates the request, commits, verifies Git, and writes checkpoint completed/COMMITTED
 → remote publication remains separate
 ```
 
-A self-declared or untrusted headless context does not authorize a commit.
+The preparation request is data for runtime validation, not prompt-level authorization. The committer must not stage, commit, or predeclare COMMITTED in pipeline preparation mode.
 
 ## Recovery
 
@@ -171,4 +175,4 @@ When state is missing, stale, or inconsistent:
 8. Reconstruct the latest safe predecessor and report the reconstruction.
 9. Continue only from the first incomplete or invalid stage.
 
-Stale state never bypasses review, testing, retrospective, commit authorization, or external checkpoint enforcement.
+Stale state never bypasses review, testing, retrospective, commit preparation/execution, or external checkpoint enforcement.

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

@@ -1,49 +1,47 @@
 ---
 name: "prizmkit-code-review"
-description: "Review the complete current change for a formal PrizmKit requirement with a mandatory bounded Main-Agent loop and optional capability-gated independent correctness review. Directly repair accepted corrections, verify repairs, converge to PASS or stop with NEEDS_FIXES, and hand off to prizmkit-test. (project)"
+description: "Review one supplied complete change with a bounded Main-Agent review/repair loop and optional capability-gated independent correctness review. Produces review-report.md and returns PASS or NEEDS_FIXES. (project)"
 ---
 
 # PrizmKit Code Review
 
-`/prizmkit-code-review` is the mandatory review stage after implementation and before the full test stage. The current Main Agent owns the complete baseline review loop: it discovers findings, adjudicates them, directly repairs accepted findings, verifies repairs, and continues until the review converges or stops safely. After convergence, one strictly capability-gated independent Reviewer may objectively check the complete current implementation without taking mutation or final-decision authority.
+`/prizmkit-code-review` reviews one caller-supplied complete change. The current Main Agent owns the complete baseline review loop: it discovers findings, adjudicates them, directly repairs accepted findings, verifies repairs, and continues until the review converges or stops safely. After convergence, one strictly capability-gated independent Reviewer may objectively check the complete current implementation without taking mutation or final-decision authority.
 
 ## Execution Boundary
 
 - Main-Agent review remains mandatory and must not be delegated directly or indirectly.
 - After Main-Agent convergence only, this skill may create the single independent Reviewer defined by `${SKILL_DIR}/references/independent-code-review.md` when every structural capability in that reference is proven.
-- Do not invoke another review skill or review workflow from inside this skill.
+- Do not invoke another review process from inside this skill.
 - Do not launch any additional review work through a general-purpose execution unit or relabel it as a finder, verifier, audit, compatibility review, verification, or gap sweep.
 - The independent Reviewer cannot mutate, execute arbitrary commands, or create downstream execution units; prompt instructions never substitute for these structural guarantees.
 - The Main Agent may directly read, search, edit, and run targeted verification in the active workspace.
-- Review repairs occur before the full `/prizmkit-test` stage so project-native tests run against the final reviewed workspace.
+- Review repairs use targeted verification appropriate to each accepted finding.
 - `{artifact_dir}/review-report.md` is the only persisted review artifact for this execution.
 
 ## Atomic Stage Boundary
 
-`prizmkit-code-review` owns the complete mandatory Main-Agent review, the optional independent correctness review, accepted-correction repairs, and review verification. It writes its truthful terminal result and `next_stage`, then returns control. It must not invoke `prizmkit-test` or `prizmkit-implement` itself; the active orchestrator owns outer repair routing and the next-stage invocation.
+`prizmkit-code-review` owns the complete review, accepted-correction repairs, targeted verification, and `review-report.md` for one supplied change. It returns `PASS` or `NEEDS_FIXES` and stops.
 
 ## When to Use
 
-- After `/prizmkit-implement` reports `IMPLEMENTED`.
-- After implementation repairs that changed production code, runtime configuration, schema, dependencies, or public interfaces.
-- When a caller routes a high-risk production repair reported by `prizmkit-test` back for delta review.
-- When the user asks for a complete review or commit readiness decision.
+- A caller supplies a complete implementation for review.
+- A caller supplies a production-affecting repair for delta review.
+- The user asks for a complete current-change correctness review.
 
 ## When NOT to Use
 
 - No valid `spec.md` and `plan.md` exist for the active requirement.
 - Implementation tasks or required repair work remain incomplete.
-- A test-stage environment stop is caused by availability rather than a review concern; resume from test when the environment is available.
-- The request is a direct low-risk edit outside the formal requirement lifecycle.
+- The request has no review input and does not require this bounded review contract.
 
-## Input and State
+## Input
 
 | Parameter | Required | Description |
 |---|---|---|
-| `artifact_dir` | No | Directory containing `spec.md` and `plan.md`. Reuse the caller's directory or workflow-state value. |
+| `artifact_dir` | Yes | Caller-supplied directory containing the exact `spec.md` and `plan.md` for this review. |
 | `review_scope` | No | `full` for the initial review; `delta` for a production-affecting repair after a prior review pass. |
 
-Every invocation must reuse the same `artifact_dir`. If workflow state is missing, reconstruct it from `spec.md`, `plan.md`, `review-report.md`, the current diff, and any current test report/result pair, and report the reconstruction.
+Review only the caller-supplied `artifact_dir`; never discover a different recent artifact. Missing or inconsistent stage input produces `NEEDS_FIXES` with the exact input blocker.
 
 ## Phase 0: Initialize Report and Reuse Current Context
 
@@ -51,7 +49,7 @@ Every invocation must reuse the same `artifact_dir`. If workflow state is missin
 2. At the start of each execution, replace any prior report with a new execution header using `${SKILL_DIR}/references/review-report-template.md`.
 3. Within that execution, append progress after every review round, repair batch, final verification, and exactly one `## Final Result`.
 4. Start from the Main Agent's current requirement context and inspect the complete workspace change first: `git status --short`, the staged diff, and the unstaged diff. Include untracked, deleted, and renamed files in the review scope.
-5. Do not reread `spec.md`, `plan.md`, project rules, progressive docs, or unchanged source merely to recreate context the Main Agent already holds. Load only the missing or potentially stale material required to resolve a concrete ambiguity, verify an acceptance criterion, understand a changed contract, or reconstruct missing workflow state.
+5. Reuse current context and load only missing or potentially stale material required to resolve a concrete ambiguity, verify an acceptance criterion, or understand a changed contract.
 6. Inspect unchanged callers, dependents, contracts, or tests only when the diff changes or may violate an interface, shared behavior, or regression boundary. Do not perform an unconditional repository-wide dependency sweep.
 7. For `review_scope=delta`, focus on files and behavior affected since the prior review pass and expand only across contracts implicated by that delta.
 8. If no changes exist, record final verification and `PASS` only when the current requirement context and prior implementation state prove there is nothing left to review.
@@ -109,7 +107,7 @@ For accepted findings while the round limit remains:
 3. Inspect the complete resulting diff for unrelated changes and regressions.
 4. Append repair verification and continue the review loop.
 
-Do not run the full auditable testing protocol as a substitute for this review stage. The full testing stage follows only after review `PASS`.
+Do not turn review verification into a broad unrelated test campaign; use targeted checks that establish each repair.
 
 If a repair is unsafe, incomplete, or unverifiable, record an unresolved finding and finish with `NEEDS_FIXES`.
 
@@ -141,49 +139,15 @@ Valid results:
 PASS | NEEDS_FIXES
 ```
 
-`PASS` requires review convergence, no unresolved findings, and credible targeted verification. `NEEDS_FIXES` means an outer implementation repair is required or completion must stop safely.
+`PASS` requires review convergence, no unresolved findings, and credible targeted verification. `NEEDS_FIXES` means a concrete correction remains or safe completion was not established.
 
-## Workflow State and Outer Repair Routing
+## Output
 
-Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
+Return only review-stage outputs:
 
-On `PASS`, update workflow state:
+- `artifact_dir` and `review-report.md` path;
+- `PASS` when review converged with all accepted findings repaired;
+- `NEEDS_FIXES` when accepted or unresolved findings remain;
+- finding counts, repair verification, and concrete remaining findings.
 
-```json
-{
-  "stage": "code-review",
-  "status": "completed",
-  "stage_result": "REVIEW_PASS",
-  "completed_stages": ["plan", "implement", "code-review"],
-  "next_stage": "test",
-  "resume_from": "prizmkit-test"
-}
-```
-
-On `NEEDS_FIXES` caused by code findings, update workflow state:
-
-```json
-{
-  "stage": "code-review",
-  "status": "failed",
-  "stage_result": "REVIEW_NEEDS_FIXES",
-  "repair_scope": "production",
-  "next_stage": "implement",
-  "resume_from": "prizmkit-implement"
-}
-```
-
-Increment the outer `repair_round` only when returning to implementation; the review-internal ten-round loop never increments it. The outer workflow permits at most three repair rounds and must return a truthful unresolved `NEEDS_FIXES` result instead of beginning a fourth.
-
-## Handoff
-
-After `PASS`:
-
-```text
-REVIEW_PASS
-  → /prizmkit-test
-```
-
-If workflow state names an active `orchestrator`, return `REVIEW_PASS`, the report/state paths, and `next_stage=test` to it; do not invoke test independently. For direct stage use, report the exact `/prizmkit-test` invocation and same `artifact_dir`; a host may perform that semantic handoff on the user's behalf.
-
-After `NEEDS_FIXES`, stop and hand off to `/prizmkit-implement`; do not test or commit the unrepaired production change.
+Return only the listed review outputs. Do not invoke another Skill.

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

@@ -47,7 +47,7 @@ Rules:
 
 ## Review Input
 
-Resolve exact requirement identity from workflow state or explicit handoff on every response:
+Use the exact caller-supplied review identity on every response:
 
 ```text
 artifact_dir: [EXACT_ARTIFACT_DIR]
@@ -95,7 +95,7 @@ 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 re-enter delegation or another review process.
 - Do not modify, create, delete, rename, stage, commit, or otherwise mutate files.
 - Do not execute shell, Git, tests, builds, network calls, external processes, or any operation that can change state.
 - Use read-only checkout access beyond changed files only for concrete module, caller, consumer, schema, type, configuration, fixture, or test coupling.
@@ -139,7 +139,7 @@ All initial execution boundaries and the Reviewer Output Protocol remain mandato
 
 ## Reviewer Output Protocol
 
-Return exactly one of these forms. Do not add severity, confidence, dimension, workflow impact, or acceptance fields.
+Return exactly one of these forms. Do not add severity, confidence, dimension, caller routing, or acceptance fields.
 
 ### No Correction Needed
 
@@ -187,7 +187,7 @@ Every correction contains only `Target`, `Problem`, `Evidence`, and `Correction`
 No review verdict was produced.
 ```
 
-`REVIEW_BLOCKED` is an internal independent-review result, not a lifecycle verdict.
+`REVIEW_BLOCKED` is an internal independent-review result, not the code-review stage verdict.
 
 ## Main-Agent Adjudication
 
@@ -234,11 +234,11 @@ Behavior:
 6. Reviewer input problems may be corrected within remaining shared budget using native continuation or a compliant replacement.
 7. Report temporary input-cleanup failures honestly; cleanup failure does not change an otherwise verified review result.
 
-Strict downgrade is visible reduced assurance, not a new lifecycle verdict and not permission to weaken the gate.
+Strict downgrade is visible reduced assurance, not a new terminal review verdict and not permission to weaken the gate.
 
 ## Report Recording
 
-Use the existing append-only `review-report.md` lifecycle and renderer events:
+Use the existing append-only `review-report.md` structure and renderer events:
 
 - `independent-review-round`: response number `1..5`, result, correction count, adjudication counts, and next action;
 - `independent-adjudication`: correction summary, `accepted | rejected | unresolved`, evidence, and actual modification;

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

@@ -114,7 +114,7 @@ Exactly one Final Result terminates a completed execution:
 - Start of a new execution removes stale progress and terminal results from prior executions.
 - A phase appends its result before the next phase starts.
 - Main-Agent round numbers are from `1` through `10`; independent Reviewer response numbers are from `1` through `5`.
-- Independent Reviewer results are `NO_CORRECTION_NEEDED`, `CORRECTION_NEEDED`, or `REVIEW_BLOCKED`; they never replace the terminal lifecycle verdict.
+- Independent Reviewer results are `NO_CORRECTION_NEEDED`, `CORRECTION_NEEDED`, or `REVIEW_BLOCKED`; they never replace the terminal review verdict.
 - For an independent round, `accepted + rejected + unresolved = corrections`; `NO_CORRECTION_NEEDED` requires zero corrections.
 - Finding counts satisfy `accepted + rejected + unresolved = findings`.
 - `PASS` requires every accepted finding fixed and zero unresolved findings.
@@ -122,4 +122,4 @@ Exactly one Final Result terminates a completed execution:
 - An IN_PROGRESS report without Final Result is incomplete.
 - Generic or incidental verdict text outside the last Final Result does not prove completion.
 - Do not append any section after Final Result.
-- A separate review-state JSON file is not required; the shared workflow state under `.prizmkit/state/workflows/` may record lifecycle handoff and recovery metadata.
+- Do not create a separate review-state JSON file; `review-report.md` is the complete stage artifact.

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

@@ -1,179 +1,129 @@
 ---
 name: "prizmkit-committer"
-description: "Final commit stage for a formal PrizmKit requirement. Verifies plan, implementation, Main-Agent review, testing, and retrospective evidence; previews and confirms interactive commits; automatically creates authorized local commits in trusted headless sessions; verifies the result; and leaves remote publication to the host runtime. (project)"
+description: "Perform one commit stage for a caller-supplied final change. Either preview and create an explicitly confirmed interactive local commit, or validate the final diff and write an exact runtime-commit-request.json without Git mutation. Returns only commit-stage results. (project)"
 ---
 
 # PrizmKit Committer
 
-`/prizmkit-committer` is the final stage of the formal requirement lifecycle:
+`/prizmkit-committer` handles one caller-supplied final change through one explicit operation:
 
-```text
-prizmkit-plan
-  → prizmkit-implement
-  → prizmkit-code-review
-  → prizmkit-test
-  → prizmkit-retrospective
-  → prizmkit-committer
-```
-
-It does not decide which formal gates can be omitted. It verifies that all five preceding stages completed for the same `artifact_dir`, then applies the commit authorization semantics for the current execution context.
-
-## Atomic Stage Boundary
-
-`prizmkit-committer` owns only final gate verification, authorization-boundary handling, local staging, commit creation, and commit verification. It writes its truthful terminal result and returns control; it must not invoke deployment or any hidden seventh stage. The active orchestrator owns lifecycle completion reporting.
-
-## When to Use
-
-- Workflow state reports `status=completed` with `stage_result=RETRO_COMPLETE` and a valid `retrospective-result.json` for the active formal requirement.
-- An interactive user confirms they want to create the local commit.
-- A trusted headless execution context authorizes an automatic local commit.
-- User says "commit", "submit", "finish", or "done" after the formal gates have completed.
-
-## When NOT to Use
+- `operation=interactive-commit`: preview, confirm, stage, commit, and verify locally.
+- `operation=prepare-runtime-commit`: validate the intended change and write an exact commit request without staging or committing.
 
-- The working tree is clean and there is nothing to commit.
-- Any preceding formal stage is missing, failed, blocked, or associated with a different artifact directory.
-- Review has `NEEDS_FIXES` or tests have `TEST_NEEDS_FIXES`/`TEST_BLOCKED`.
-- Retrospective has not completed, including an explicit `NO_DOC_CHANGE` result.
-- User says only "ship it"; clarify commit versus deployment in interactive mode.
-- A merge conflict is unresolved.
-- An unknown headless caller has not supplied trusted commit authorization.
+Remote publication is outside this Skill.
 
-## Mandatory Gate Policy
+## Input
 
-For a formal requirement, all gates are mandatory:
+| Parameter | Required | Description |
+|---|---|---|
+| `artifact_dir` | Yes | Exact caller-supplied artifact root for this commit stage. |
+| `operation` | Yes | `interactive-commit` or `prepare-runtime-commit`. |
+| `evidence_paths` | Yes | Exact caller-supplied project-relative artifacts that establish commit readiness. |
+| `excluded_paths` | No | Exact caller-owned metadata paths that must remain outside the commit and are also excluded by the selected operation's consumer contract. It is not an allowlist for unrelated project changes. |
+| `request_path` | Preparation only | Must equal `{artifact_dir}/runtime-commit-request.json`. |
 
-| Gate | Required evidence |
-|---|---|
-| Plan | `spec.md`, `plan.md`, and `PLAN_READY` for the same `artifact_dir` |
-| Implement | All required tasks complete and `IMPLEMENTED` |
-| Code review | Final `review-report.md` result `PASS` |
-| Test | Consistent `TEST_PASS` report/result pair for the final reviewed workspace |
-| Retrospective | `retrospective-result.json` with workflow `status=completed`, `stage_result=RETRO_COMPLETE`, and artifact `result=DOCS_UPDATED` or `result=NO_DOC_CHANGE` |
+Do not discover another artifact root or infer the operation from provider, platform, prompt style, or human availability.
 
-The committer must reject a state that merely claims a gate passed when the underlying artifact or current workspace contradicts it. If workflow state is missing, reconstruct it from authoritative artifacts and report the reconstruction before asking for confirmation.
+## Stage Boundary
 
-## Workflow
+This Skill owns only final-change inspection and its selected commit operation. It does not invoke another Skill.
 
-### Step 1: Status and Gate Check
+In preparation mode it must not stage, unstage, commit, amend, reset, merge, or push.
 
-1. Read the workflow state and resolve the same `artifact_dir` used by all prior stages.
-2. Verify `spec.md`, `plan.md`, final `review-report.md`, the consistent `test-report.md`/`test-result.json` pair, `retrospective-result.json`, and the current workspace.
-3. Inspect:
+## Step 1: Validate Supplied Evidence and Final Change
 
-```bash
-git status
-git diff --stat
-git diff
-```
+1. Resolve `artifact_dir` and every `evidence_paths` entry exactly as supplied by the caller.
+2. Reject missing, unreadable, stale, contradictory, blocked, or explicitly non-passing evidence.
+3. Inspect staged, unstaged, untracked, deleted, and renamed files with bounded Git status/diff commands.
+4. Confirm every changed path belongs to the supplied change, a concrete dependency, its tests, durable documentation, or caller-required artifacts.
+5. Reject unresolved merge state and sensitive files such as real environment files, credentials, secrets, private keys, certificates, or local settings.
+6. Confirm no requested task output remains to be generated after this stage.
 
-4. Inspect modified, deleted, renamed, and untracked files.
-5. Warn about sensitive-looking files such as `.env*`, credentials, secrets, private keys, and certificates.
-6. Stop when any required gate is missing, stale, contradictory, failed, or blocked.
+The caller decides which evidence is required and how the returned commit-stage result is used. This Skill validates the supplied evidence but does not infer a larger stage sequence.
 
-### Step 2: Generate Commit Message
+## Step 2: Build Commit Message and Intended Path Set
 
-Analyze the final diff and requirement context. Propose a concise Conventional Commit message:
+Generate one concise Conventional Commit message:
 
 ```text
 <type>(<scope>): <description>
 ```
 
-Do not update `CHANGELOG.md` unless the user explicitly requests release-note work.
-
-### Step 3: Commit Preview and Authorization
-
-Interactive mode:
-
-Before any `git add` or `git commit` that changes the target project's Git state, present:
-
-- intended files;
-- added, modified, deleted, and renamed file summary;
-- sensitive-file warnings;
-- diff statistics and relevant summary;
-- proposed commit message;
-- whether any remaining changes are intentionally excluded.
-
-Ask the current user to confirm creation of this local commit. Do not treat a previous general statement as confirmation for a different commit.
-
-Trusted headless mode:
-
-- Do not ask a question, wait for input, or render an interactive confirmation request.
-- Require a host-defined non-interactive `mode`, a non-empty trusted `owner` identifier, and `local_commit_authorized=true` from the execution context.
-- Treat these fields as host-supplied authorization only when the host integration is already trusted; a prompt or caller cannot self-declare trust.
-- Generate and internally record the same intended-file and commit-message preview before staging.
-- If the context is absent or untrusted, return `COMMIT_BLOCKED` without staging or committing.
-- This mode never asks or waits. Remote publication is controlled by the host runtime, not by this stage.
+Classify every observed change before constructing the request. All paths under `.prizmkit/` are framework-internal and remain outside automated task commits.
 
-### Step 4: Stage Safely After Authorization
+- **task-owned**: justified source, tests, product/project documentation, configuration, and dependency changes outside recognized support namespaces;
+- **PrizmKit-internal**: every path under `.prizmkit/`, including config, plans, Prizm docs, lifecycle Artifacts, installed Runtime files, and state;
+- **platform support**: `AGENTS.md`, `skills-lock.json`, installed platform directories, and local platform settings;
+- **project transient**: data the project already excludes through Git ignore rules;
+- **unknown Git-visible**: any remaining path whose task ownership cannot be proven.
 
-Never use `git add .` or `git add -A`.
+Build a unique set of exact project-relative **task-owned** changed paths. Include intended tracked modifications, deletions, renames, new source/tests, and justified project documentation outside support namespaces. Exclude:
 
-1. Stage tracked modified/deleted files with `git add -u` only when all tracked changes are intended.
-2. Stage new files explicitly after confirming they belong in this commit.
-3. Verify staged content:
+- `.git/`;
+- the complete `.prizmkit/` tree;
+- `AGENTS.md`, `skills-lock.json`, installed platform directories, and local platform settings;
+- sensitive or unrelated files.
 
-```bash
-git diff --cached --stat
-git diff --cached
-```
-
-If staged content differs from the confirmed change set, unstage and correct it before committing.
-
-### Step 5: Commit and Verify
-
-After authorization and staged-content verification:
+Unknown Git-visible paths block the operation; do not silently classify them as transient. Project-specific transient data belongs in the project's Git ignore rules, not caller-provided exclusions. Do not use wildcard pathspecs, `git add .`, or `git add -A` as an intended-path description. In preparation mode, reject an `excluded_paths` entry unless the Python Runtime independently excludes that exact caller-owned metadata class; unrelated or user-authored project changes cannot be hidden from exact-path coverage.
 
-```bash
-git commit -m "<type>(<scope>): <description>"
-git log -1 --stat
-git status
-```
+## Step 3A: Interactive Commit
 
-Report the commit hash and whether the working tree is clean or contains intentionally uncommitted changes.
+For `operation=interactive-commit`:
 
-### Step 6: Remote Publication
+1. Present intended paths, change summary, sensitive-file warnings, diff statistics, proposed message, and intentionally excluded changes.
+2. Ask the current user to confirm that exact local commit.
+3. Only after confirmation, stage tracked changes safely and new files explicitly.
+4. Verify the staged diff exactly matches the confirmed path set.
+5. Create the local commit and verify its hash, committed paths, and remaining workspace changes.
+6. Return `COMMITTED`, the commit hash/message, committed paths, and intentional remaining changes.
 
-Remote publication is outside this atomic commit stage. The host runtime may perform it only when its own explicit configuration authorizes the operation; this skill does not ask the user or decide whether to publish.
+If confirmation is declined, return `COMMIT_DECLINED` without Git mutation.
 
-## Workflow State
+## Step 3B: Runtime Commit Request
 
-Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
+For `operation=prepare-runtime-commit`:
 
-Before the authorization preview, set or validate:
+1. Require `request_path={artifact_dir}/runtime-commit-request.json`.
+2. Read the current full `HEAD` hash as `base_head`.
+3. Write this JSON atomically:
 
 ```json
 {
-  "stage": "committer",
-  "status": "in_progress",
-  "stage_result": "COMMIT_PENDING",
-  "completed_stages": ["plan", "implement", "code-review", "test", "retrospective"],
-  "next_stage": "committer",
-  "resume_from": "prizmkit-committer"
+  "schema_version": 1,
+  "artifact_dir": ".prizmkit/specs/example",
+  "base_head": "<full current HEAD hash>",
+  "commit_message": "feat(scope): concise description",
+  "intended_paths": [
+    "src/example.py",
+    "tests/test_example.py"
+  ]
 }
 ```
 
-For trusted headless execution, the validated execution context additionally contains:
+4. Verify:
+   - `artifact_dir` identifies the supplied artifact root;
+   - `base_head` equals current `HEAD`;
+   - `commit_message` is one non-empty line;
+   - `intended_paths` is non-empty, unique, exact, project-relative, and covers the complete task-owned Git-visible change outside recognized support namespaces;
+   - no path escapes the checkout or enters `.prizmkit/`, another support namespace, or a sensitive location;
+   - every unknown Git-visible path caused a block rather than an implicit exclusion.
+5. Return `COMMIT_REQUEST_READY`, the request path, message, intended paths, and explicit confirmation that no Git mutation occurred.
+6. Stop.
 
-```json
-{
-  "mode": "<host-defined-headless-mode>",
-  "owner": "<trusted-host-identifier>",
-  "local_commit_authorized": true
-}
+The request is preparation data. Its consumer independently validates it before any Git mutation.
+
+## Output
+
+Interactive operation returns exactly one of:
+
+```text
+COMMITTED | COMMIT_DECLINED | COMMIT_BLOCKED
 ```
 
-After a successful local commit, update the runtime state to:
+Preparation operation returns exactly one of:
 
-```json
-{
-  "stage": "committer",
-  "status": "completed",
-  "stage_result": "COMMITTED",
-  "completed_stages": ["plan", "implement", "code-review", "test", "retrospective", "committer"],
-  "next_stage": null,
-  "resume_from": null
-}
+```text
+COMMIT_REQUEST_READY | COMMIT_BLOCKED
 ```
 
-The state file is generated in the target project under `.prizmkit/state/workflows/`; this skill does not prescribe whether the target project commits, ignores, or shares it.
+Every blocked result includes concrete missing evidence, unsafe paths, or validation errors. Return only the listed commit-operation outputs.