prizmkit 1.1.129 → 1.1.131

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

@@ -1,101 +1,185 @@
 ---
 name: "prizmkit-committer"
-description: "Pure git commit workflow with safety checks. Stages intended files safely, generates a Conventional Commit message, commits, and verifies the result. Does not modify CHANGELOG.md or .prizmkit/prizm-docs/ by default; run /prizmkit-retrospective first only when the chosen lifecycle path requires docs sync. Trigger on: 'commit', 'submit', 'finish', 'done'. If the user says only 'ship it', clarify whether they mean commit or deploy. (project)"
+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 never pushes without separate authorization. (project)"
 ---
 
 # PrizmKit Committer
 
-### When to Use
-- User says "commit", "submit", "finish", "done with this task"
-- The current lifecycle path is ready to record changes in git
-- Required gates for the chosen path have passed or been explicitly deemed not applicable
+`/prizmkit-committer` is the final stage of the formal requirement lifecycle:
 
-### When NOT to Use
-- No uncommitted changes exist — nothing to commit
-- User says only "ship it" — clarify commit vs deploy first
-- Current path still has required unresolved gates, such as failed tests, unresolved review findings, or required retrospective work
-- Mid-merge conflict resolution — handle conflicts manually before committing
+```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 `RETRO_COMPLETE` with 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
+
+- 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_FAIL`/`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.
 
-## Gate Policy
+## Mandatory Gate Policy
 
-`/prizmkit-committer` does not decide the entire lifecycle. It checks that the gates required by the chosen path are satisfied:
+For a formal requirement, all gates are mandatory:
 
-| Path | Commit gate expectation |
+| Gate | Required evidence |
 |---|---|
-| Direct edit | Verify the specific edit as appropriate; no spec/review/retro artifact required. |
-| Fast path | Simplified plan tasks complete; run tests or retrospective only if risk/knowledge triggers apply. |
-| Full path | Implementation complete; review passed; retrospective completed when docs or durable knowledge changed; tests completed when risk-triggered. |
+| 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 | Final evidence result `TEST_PASS` for the final reviewed workspace |
+| Retrospective | `retrospective-result.json` with `status=RETRO_COMPLETE` and `result=DOCS_UPDATED` or `result=NO_DOC_CHANGE` |
 
-If a gate is missing but not applicable, state why before committing. If a gate is missing and applicable, stop and run or request the missing gate.
+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.
 
 ## Workflow
 
-Follow these steps in order. The goal is to commit exactly the intended changes and avoid staging secrets or unrelated files.
+### Step 1: Status and Gate Check
 
-### Step 1: Status Check
+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`, validated test evidence, `retrospective-result.json`, and the current workspace.
+3. Inspect:
 
 ```bash
 git status
+git diff --stat
+git diff
 ```
 
-- If the working tree is clean, inform the user and stop.
-- If changes exist, inspect modified, deleted, and untracked files before staging.
-- Warn about sensitive-looking files: `.env*`, `*credential*`, `*secret*`, `*.pem`, `*.key`.
+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.
 
 ### Step 2: Generate Commit Message
 
-Analyze the staged/unstaged diff and task context to generate a concise Conventional Commit message:
+Analyze the final diff and requirement context. Propose a concise Conventional Commit message:
 
-```bash
+```text
 <type>(<scope>): <description>
 ```
 
-The message should capture what changed and why it matters.
+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, `local_commit_authorized=true`, and `push_authorized=false` 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, waits, or pushes.
 
-### Step 3: Stage Safely
+### Step 4: Stage Safely After Authorization
 
-Never use `git add .` or `git add -A`; broad staging can accidentally include secrets or unrelated files.
+Never use `git add .` or `git add -A`.
 
-1. Stage tracked modified/deleted files with `git add -u` when all tracked changes are intended.
-2. Stage new files explicitly by path after confirming they belong in the commit.
+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:
 
 ```bash
 git diff --cached --stat
+git diff --cached
 ```
 
-If staged content differs from the intended change set, unstage and correct it before committing.
+If staged content differs from the confirmed change set, unstage and correct it before committing.
 
-### Step 4: Commit
+### Step 5: Commit and Verify
+
+After authorization and staged-content verification:
 
 ```bash
 git commit -m "<type>(<scope>): <description>"
+git log -1 --stat
+git status
 ```
 
-Do not update `CHANGELOG.md` by default. Changelog updates belong to release, publish, version-bump workflows, or explicit user requests.
+Report the commit hash and whether the working tree is clean or contains intentionally uncommitted changes.
+
+### Step 6: Optional Push
 
-### Step 5: Verification
+Pushing is separate from committing and is never part of trusted headless execution. In interactive mode ask explicitly:
 
-```bash
-git log -1 --stat
-git status
+```text
+Push this commit to the remote?
 ```
 
-Confirm the commit was recorded and report whether the working tree is clean or has remaining intentionally uncommitted changes.
+A refusal or lack of permission means stop after the local commit. Never push automatically.
 
-### Step 6: Optional Push
+## Workflow State
 
-Ask user: "Push to remote?"
+Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
 
-- Yes: run `git push`
-- No: stop after reporting the commit hash
+Before the authorization preview, set or validate:
 
-**Headless mode**: If invoked with `--headless`, skip the push question, do not push, and stop after Step 5 verification.
+```json
+{
+  "stage": "committer",
+  "status": "COMMIT_PENDING",
+  "stage_result": "COMMIT_PENDING",
+  "completed_stages": ["plan", "implement", "code-review", "test", "retrospective"],
+  "next_stage": "committer",
+  "resume_from": "prizmkit-committer"
+}
+```
 
-## Examples
+For trusted headless execution, the validated execution context additionally contains:
 
-```bash
-git commit -m "feat(avatar): add user avatar upload with S3 storage"
-git commit -m "fix(auth): handle null token in refresh flow"
-git commit -m "docs(prizm): clarify lifecycle gate policy"
+```json
+{
+  "mode": "<host-defined-headless-mode>",
+  "owner": "<trusted-host-identifier>",
+  "local_commit_authorized": true,
+  "push_authorized": false
+}
 ```
+
+After a successful local commit, update the runtime state to:
+
+```json
+{
+  "stage": "committer",
+  "status": "COMMITTED",
+  "completed_stages": ["plan", "implement", "code-review", "test", "retrospective", "committer"],
+  "next_stage": null,
+  "resume_from": null
+}
+```
+
+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.

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

@@ -0,0 +1,181 @@
+# PrizmKit Workflow State Protocol
+
+`workflow-state.json` is lifecycle runtime metadata for one formal requirement. It preserves stage handoff, repair routing, orchestrator ownership, and resume information without replacing authoritative artifacts or any host-owned execution checkpoint.
+
+## Location and Identity
+
+```text
+.prizmkit/state/workflows/<requirement-slug>.json
+```
+
+The state file is created only when a lifecycle runs. The active `artifact_dir` is the generic requirement artifact root and must be preserved exactly across every stage:
+
+```text
+.prizmkit/specs/<requirement-slug>/
+.prizmkit/bugfix/<bug-id>/
+.prizmkit/refactor/<refactor-id>/
+```
+
+Never select a different most-recent plan when resuming or handing off. Any execution checkpoint maintained by an external host remains separate from this lifecycle state. Never merge, substitute, or infer one schema from the other. The target project controls whether generated `.prizmkit/` files are committed, ignored, or shared.
+
+## Authority
+
+The state file is an index, not the authority for stage completion:
+
+| Information | Authority |
+|---|---|
+| Requirement goals and acceptance criteria | `{artifact_dir}/spec.md` |
+| Implementation tasks and completion | `{artifact_dir}/plan.md` plus current workspace |
+| Review findings and verdict | `{artifact_dir}/review-report.md` final result |
+| Test execution, verdict, and repair scope | Validated evidence package and authoritative `verdict.json` |
+| Test report presentation | `{artifact_dir}/test-report.md` as a derived view only |
+| Retrospective completion and result | `{artifact_dir}/retrospective-result.json` |
+| Durable architecture knowledge | `.prizmkit/prizm-docs/` |
+| Local commit | Git history and confirmed or authorized commit identity |
+| Current stage, orchestrator, and resume entry | Workflow state |
+| External orchestration progress | The external host's own checkpoint, never this state |
+
+Every consumer compares workflow state with authoritative artifacts and the current workspace. Missing or stale state is reconstructed from those sources and is never accepted as success by itself.
+
+## Schema
+
+```json
+{
+  "schema_version": 1,
+  "artifact_dir": ".prizmkit/specs/example",
+  "orchestrator": "prizmkit-workflow",
+  "stage": "test",
+  "status": "TEST_PASS",
+  "stage_result": "TEST_PASS",
+  "completed_stages": ["plan", "implement", "code-review", "test"],
+  "repair_scope": null,
+  "repair_round": 0,
+  "next_stage": "retrospective",
+  "resume_from": "prizmkit-retrospective"
+}
+```
+
+### Fields
+
+| Field | Meaning |
+|---|---|
+| `schema_version` | State schema version. Current value is `1`. |
+| `artifact_dir` | The single generic requirement artifact root reused by every stage. |
+| `orchestrator` | `prizmkit-workflow`, another semantic coordinator identifier, or `null` for direct stage use. |
+| `stage` | The stage that most recently wrote state. |
+| `status` | Lifecycle progression status, distinct from the domain `stage_result`. |
+| `stage_result` | Domain result such as `PASS`, `NEEDS_FIXES`, `TEST_*`, `DOCS_UPDATED`, or `NO_DOC_CHANGE`. |
+| `completed_stages` | Ordered stages completed for this requirement. |
+| `repair_scope` | `null`, `test-infrastructure`, `production`, `runtime`, `schema`, `dependency`, `public-interface`, or `unknown`. |
+| `repair_round` | Outer cross-stage repair round, from `0` through `3`. |
+| `next_stage` | Next semantic stage, or `null` after commit. |
+| `resume_from` | Exact atomic skill that can resume, or `null` after commit. |
+
+## Lifecycle and Verdict Mappings
+
+The mandatory formal lifecycle is:
+
+```text
+PLAN_READY
+  → IMPLEMENTED
+  → REVIEW_PASS
+  → TEST_PASS
+  → RETRO_COMPLETE
+  → COMMIT_PENDING
+  → COMMITTED
+```
+
+No formal stage is silently optional. Domain evidence maps as follows:
+
+```text
+review-report final PASS        → status=REVIEW_PASS, stage_result=PASS
+review-report final NEEDS_FIXES → status=REVIEW_NEEDS_FIXES, stage_result=NEEDS_FIXES
+validated verdict TEST_PASS     → status=TEST_PASS, stage_result=TEST_PASS
+validated verdict TEST_FAIL     → status=TEST_FAIL, stage_result=TEST_FAIL
+validated verdict TEST_BLOCKED  → status=TEST_BLOCKED, stage_result=TEST_BLOCKED
+retrospective result DOCS_UPDATED  → status=RETRO_COMPLETE, stage_result=DOCS_UPDATED
+retrospective result NO_DOC_CHANGE → status=RETRO_COMPLETE, stage_result=NO_DOC_CHANGE
+```
+
+`RETRO_COMPLETE` is the stable completion status. `DOCS_UPDATED` and `NO_DOC_CHANGE` are mutually exclusive retrospective results, not substitute statuses. A derived Markdown test report never establishes a `TEST_*` status without validated authoritative evidence.
+
+## Repair Routing
+
+```text
+REVIEW_NEEDS_FIXES
+  → implement
+  → code-review
+  → test
+
+TEST_FAIL with repair_scope=test-infrastructure
+  → implement
+  → test
+
+TEST_FAIL with repair_scope=production|runtime|schema|dependency|public-interface
+  → implement
+  → code-review
+  → test
+
+TEST_FAIL with repair_scope=unknown
+  → conservative production route only when safe
+  → otherwise WORKFLOW_BLOCKED
+
+TEST_BLOCKED
+  → never make speculative production edits
+  → interactive execution stops with a prizmkit-test resume entry
+  → a trusted headless host may perform bounded environment recovery, then records WORKFLOW_BLOCKED if unresolved
+
+RETRO_BLOCKED
+  → WORKFLOW_BLOCKED
+WORKFLOW_BLOCKED
+  → resume only after the recorded blocker is resolved
+```
+
+The outer workflow permits at most three automatic repair rounds. These are cross-stage rounds (`repair_round` `0` through `3`). The code-review internal loop permits at most ten completed review rounds and is separate; review-internal repairs do not increment the outer counter.
+
+## Orchestrator Ownership and Handoff
+
+1. An atomic stage performs only its own stage, writes the truthful terminal result and `next_stage`, and returns control.
+2. When `orchestrator` is non-null, only that orchestrator invokes the next skill. The atomic stage must not auto-invoke it again.
+3. Direct stage use may report one deterministic next invocation but does not claim the next stage ran.
+4. Every handoff preserves the same `artifact_dir`.
+5. External automation invokes atomic stages directly and does not invoke `prizmkit-workflow` as a nested coordinator.
+6. Workflow state never replaces or absorbs an external host's checkpoint.
+
+## Commit Authorization
+
+Interactive execution:
+
+```text
+committer previews intended files and message
+→ waits for explicit confirmation from the current user
+→ creates the local commit
+```
+
+Trusted headless execution:
+
+```text
+a trusted host explicitly authorizes the current local task commit
+→ host injects mode=<host-defined-headless-mode>, owner=<trusted-host-identifier>,
+  local_commit_authorized=true, push_authorized=false
+→ committer verifies gates and commits automatically
+→ no question, wait, or push is permitted
+```
+
+A self-declared or otherwise untrusted headless context does not authorize a commit. Push is never implied by either mode.
+
+## Recovery
+
+When state is missing, stale, or inconsistent:
+
+1. Read `spec.md` and `plan.md` from `artifact_dir` only when they are not already available in current context.
+2. Inspect task markers and the current workspace.
+3. Read the latest review report and final result when needed to establish review authority.
+4. Validate authoritative test evidence and `repair_scope`.
+5. Validate `retrospective-result.json` when retrospective is claimed complete.
+6. Verify the commit when commit is claimed complete.
+7. When an external host is active, let that host validate its own checkpoint independently; never merge the schemas.
+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 host checkpoint enforcement.

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

@@ -1,102 +1,128 @@
 ---
 name: "prizmkit-implement"
-description: "Execute plan.md tasks with a TDD-oriented approach. Respects task ordering, checkpoints, and dependencies for Fast path or Full path change artifacts. Reads Prizm docs before editing; optional inline implementation subagent delegation uses this skill's references and active-checkout/no-worktree constraints. Use after /prizmkit-plan. Trigger on: 'implement', 'build', 'code it', 'start coding', 'execute', 'write the code'. (project)"
+description: "Execute the reviewed plan for a formal PrizmKit requirement, update task checkpoints, preserve the shared workflow artifact directory, and hand off to prizmkit-code-review. Use after prizmkit-plan or when resuming implementation repair. (project)"
 ---
 
 # PrizmKit Implement
 
-### When to Use
-- After `/prizmkit-plan` when ready to write code
-- Fast path or Full path has a `plan.md` with unchecked tasks
-- User says "implement", "build", "code it", "start coding", "develop", or "execute"
+`/prizmkit-implement` executes the tasks in one formal requirement's `plan.md`. It is the implementation stage, including implementation repairs requested by code review or testing.
 
-### When NOT to Use
-- No `plan.md` exists and the task is not a Direct edit — run `/prizmkit-plan` first
-- All tasks in `plan.md` are checked off
-- Direct edit: typo, pure formatting, small docs edit, or tiny config tweak with no behavior impact
-- User is still asking for design/planning rather than implementation
+## When to Use
 
-## Preconditions
+- After `/prizmkit-plan` reports `PLAN_READY`.
+- When workflow state routes a review or test repair back to implementation.
+- When `plan.md` contains unchecked tasks for the active requirement.
+- User says "implement", "build", "code it", "start coding", "develop", or "execute".
 
-| Required Artifact | Check | If Missing |
+## When NOT to Use
+
+- No `spec.md` and `plan.md` exist for the formal requirement.
+- All planned tasks are complete and no repair scope is recorded.
+- The user is still deciding scope or asking for planning.
+- The request is a direct low-risk edit outside the formal requirement lifecycle.
+
+## Preconditions and Artifact Identity
+
+| Required artifact | Check | If missing |
 |---|---|---|
-| `plan.md` with Tasks section | File exists and has unchecked tasks | Run `/prizmkit-plan` |
-| `spec.md` | File exists in same artifact directory | Run `/prizmkit-plan` |
+| `plan.md` with Tasks | Exists and contains incomplete or explicitly repairable work | Return `IMPLEMENT_BLOCKED` and direct the user to `/prizmkit-plan`. |
+| `spec.md` | Exists in the same artifact directory | Return `IMPLEMENT_BLOCKED` and direct the user to `/prizmkit-plan`. |
+| Workflow state | Reusable or reconstructable | Reconstruct from artifacts and report the result when absent or stale. |
 
-Artifact directory: accept `artifact_dir` from caller. If not provided, scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks. When invoked as a handoff step, reuse the previous skill's `artifact_dir`; re-detection can select the wrong change artifact in a multi-task workspace.
+Accept `artifact_dir` from the preceding skill or workflow state. Do not scan for a different most-recent plan when invoked as a handoff. A single requirement must reuse the same `artifact_dir` throughout all stages.
 
 ## Context Loading
 
-Before implementation, load context once:
+Before editing:
 
-1. **Task context**: read `plan.md` and `spec.md`. If companion documents exist in the artifact directory, read only those relevant to the change.
-2. **Architecture context**:
-   - Read `.prizmkit/prizm-docs/root.prizm`.
-   - Read relevant L1 docs for affected modules.
-   - Read relevant L2 docs when they exist, especially INTERFACES, TRAPS, and DECISIONS.
-   - If a relevant L2 doc does not exist, read the target source files as fallback and note that no L2 was available. Do not stop implementation only because L2 is missing; `/prizmkit-retrospective` can create L2 after the change if durable detail exists.
-3. **Dev rules**: if root Prizm docs reference `.prizmkit/rules/<layer>-rules.md`, read the relevant rule files. If a referenced rule file is missing, skip it and continue.
+1. Read `plan.md`, `spec.md`, and only relevant companion artifacts.
+2. Read `.prizmkit/prizm-docs/root.prizm` when present.
+3. Read relevant L1 docs and relevant L2 docs when present.
+4. If an affected L2 doc is missing, read the target source files as fallback and record that no L2 context was available. Do not create L2 merely because it was read; retrospective decides whether durable knowledge warrants it.
+5. Read referenced layer rules when present. If a rule conflicts with the plan, stop and ask the user unless the plan clearly supersedes the rule.
 
-If a dev rule conflicts with `plan.md`, call out the conflict and ask the user unless the plan clearly supersedes the rule.
+## Optional Inline Delegation
 
-## Optional Inline Implementation Subagent Delegation
+The default is direct Main-Agent implementation. If a narrow slice is delegated, use `prompt_reference: ${SKILL_DIR}/references/implementation-subagent-procedure.md` and follow its active-checkout/no-worktree constraints. Delegation is optional implementation detail and does not alter lifecycle handoff or ownership.
 
-The default execution mode is direct Main Agent implementation. If delegation is useful for a narrow implementation slice, use only this skill's local reference:
+## Atomic Stage Boundary
 
-```yaml
-prompt_reference: ${SKILL_DIR}/references/implementation-subagent-procedure.md
-isolation: current-workspace / active-checkout / no-worktree
-subagent_kind: inline implementation prompt, not a platform-installed named agent
-```
+`prizmkit-implement` owns only execution of plan tasks and implementation repairs. It writes its truthful terminal result and `next_stage`, then returns control. When an external orchestrator is active, it must not invoke code review or test itself. The active orchestrator owns the next-stage invocation.
 
-Delegation rules:
-- Read `${SKILL_DIR}/references/implementation-subagent-procedure.md` before preparing the subagent prompt.
-- Pass the expected active checkout git top-level and the exact delegated task/file scope.
-- Do not use worktree isolation, copied checkouts, remote isolated checkouts, branch switching, or a platform-installed named implementation agent.
-- If active-checkout/no-worktree launch cannot be satisfied, stop with:
+## Execution
 
-```text
-Cannot delegate /prizmkit-implement because this platform cannot start an inline implementation subagent in the active checkout without worktree, copy, remote, or branch isolation.
-```
+For each unchecked or explicitly repair-scoped task, in plan order:
 
-## Execution
+1. Confirm the target scope and relevant context.
+2. Apply TDD when appropriate:
+   - add or update a failing test first for behavior changes;
+   - use the smallest meaningful verification for docs, configuration, UI-only, or mechanical changes.
+3. Cover relevant happy paths, domain edges, and errors without inventing meaningless tests.
+4. Avoid unrelated edits and preserve the requirement's artifact identity.
+5. Mark a task complete immediately after its implementation is complete.
+6. Stop dependent tasks on failure; run `[P]` tasks in parallel only when safe.
+7. Execute only local implementation verification here. The mandatory full lifecycle code review follows implementation and the mandatory auditable test stage follows code review.
+
+### Repair Scope
+
+When routed from a failed test or review, read `repair_scope` from workflow state and constrain edits accordingly:
 
-For each unchecked task in `plan.md`, in order:
-
-1. Confirm relevant context for the target files is loaded: L1, L2 when present, or source fallback when L2 is absent.
-2. Apply TDD where applicable:
-   - Write or update a failing test first for behavior changes.
-   - For UI-only, docs, configuration, or mechanical refactors where test-first does not apply, use the smallest meaningful verification instead.
-3. Follow internal ID hygiene: do not place PrizmKit feature/bug/refactor IDs, task IDs, session/run IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths in `.prizmkit/prizm-docs/`, user-visible UI text, API responses, emails, notifications, or tests that assert visible product copy.
-4. Cover relevant paths for changed logic:
-   - happy path
-   - domain-specific edge cases
-   - error conditions
-   Do not force meaningless edge/error tests when the function has none.
-5. Avoid redundant tests. Check existing coverage before adding a new test; each new test should exercise a distinct behavior or boundary.
-6. Test your own code and integration points, not framework internals, third-party library internals, or language built-ins.
-7. Mark the task as `[x]` immediately after completion. Immediate marking makes interrupted sessions resumable.
-8. Respect task semantics:
-   - Sequential tasks stop on failure when later tasks depend on them.
-   - `[P]` tasks may run in parallel within the same safe group.
-   - `CP:` checkpoint tasks require build/tests/verification specified by the plan before continuing.
-9. After all tasks complete, run the verification appropriate to the chosen path and risk. Full test orchestration via `/prizmkit-test` is risk-triggered, not mandatory for every change.
+- `production`, `runtime`, `schema`, `dependency`, or `public-interface`: production-affecting changes. Completion must hand off to `prizmkit-code-review`.
+- `test-infrastructure`: tests, fixtures, test runner configuration, or evidence setup only. Completion may hand off directly to `prizmkit-test`.
+- `unknown`: stop and ask the user; do not guess which downstream gates can be skipped.
 
 ## Recovery
 
-If a session is interrupted:
+If interrupted:
+
+- Reuse completed task markers and the same `artifact_dir`.
+- Inspect any partially edited files before continuing.
+- Reconcile workflow state with the plan and current diff.
+- Never report `IMPLEMENTED` when incomplete tasks or unresolved repair work remain.
+
+## Workflow State
+
+Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
 
-- Completed tasks should already be marked `[x]`.
-- Re-run `/prizmkit-implement`; it resumes from the first unchecked task.
-- If partially edited files exist without a completed task marker, inspect the diff and either finish the task or revert incomplete work before continuing.
+On successful implementation, update `.prizmkit/state/workflows/<requirement-slug>.json` with:
 
-## Output
+```json
+{
+  "stage": "implement",
+  "status": "IMPLEMENTED",
+  "completed_stages": ["plan", "implement"],
+  "repair_round": 0,
+  "repair_scope": null,
+  "next_stage": "code-review",
+  "resume_from": "prizmkit-code-review"
+}
+```
+
+For a repair, increment `repair_round`, set `status` to `IMPLEMENT_REPAIR`, preserve the triggering failure in the state, and select the next stage according to `repair_scope`. The outer workflow permits at most three repair rounds; the implementation stage must return a blocked result rather than start a fourth round.
+
+## Output and Handoff
+
+Report:
+
+- implementation summary;
+- completed and remaining tasks;
+- files changed;
+- local verification performed;
+- workflow state path and status;
+- exact next stage.
+
+On initial implementation or a production-affecting repair:
+
+```text
+IMPLEMENTED
+  → /prizmkit-code-review
+```
+
+On a test-infrastructure-only repair:
+
+```text
+IMPLEMENTED
+  → /prizmkit-test
+```
 
-- Code files created/modified as specified in `plan.md`
-- `plan.md` Tasks section updated with `[x]` markers
-- Implementation summary
-- Suggested next step:
-  - Full path or review-triggered risk: `/prizmkit-code-review`
-  - Risk-triggered testing: `/prizmkit-test`
-  - Docs/durable knowledge changed: `/prizmkit-retrospective`
-  - Otherwise: `/prizmkit-committer`
+If workflow state names an active `orchestrator`, return the terminal result, state path, and selected next stage to it; do not invoke another stage independently. For direct stage use, provide the deterministic next invocation with the same `artifact_dir`; a host may perform that semantic handoff on the user's behalf.

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

@@ -10,7 +10,7 @@ The Main Agent must provide:
 - The exact plan tasks or files delegated.
 - Any loaded Prizm docs traps/rules relevant to the delegated files.
 
-The implementation subagent must run in the same active checkout as the Main Agent.
+The implementation subagent must run in the same active checkout as the Main Agent. This is an inline subagent constraint, not a permission to create an isolated execution unit or worktree.
 
 ## Active Checkout Guard