prizmkit 1.1.129 → 1.1.131

package/bundled/skills/prizmkit-plan/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-retrospective/SKILL.md

@@ -1,95 +1,153 @@
 ---
 name: "prizmkit-retrospective"
-description: "Incremental .prizmkit/prizm-docs/ maintainer and normal development docs writer. Performs structural sync for changed modules and injects durable TRAPS/RULES/DECISIONS when feature, bugfix, refactor, or test work creates lasting project knowledge. Run after code review or implementation when the chosen lifecycle path changed structure, interfaces, dependencies, behavior, or durable knowledge, and before committing those changes. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete'. (project)"
+description: "Mandatory retrospective stage after a formal requirement passes code review and testing. Synchronizes durable Prizm documentation or records that no documentation change is needed, updates workflow state, and hands off to prizmkit-committer. (project)"
 ---
 
 # PrizmKit Retrospective
 
-`/prizmkit-retrospective` is the normal development writer for `.prizmkit/prizm-docs/`.
+`/prizmkit-retrospective` is the mandatory documentation and durable-knowledge stage after `prizmkit-test` returns `TEST_PASS`.
 
 It performs two jobs:
 
-1. **Structural Sync** — reflect changed code structure, interfaces, dependencies, and file mappings in `.prizmkit/prizm-docs/`.
-2. **Knowledge Injection** — add durable TRAPS, RULES, and DECISIONS discovered during the task.
+1. **Structural Sync** — reflect changed code structure, interfaces, dependencies, and file mappings in `.prizmkit/prizm-docs/` when the documentation system exists.
+2. **Knowledge Injection** — add durable TRAPS, RULES, and DECISIONS discovered during the task when such knowledge exists.
 
-For first-time documentation setup, validation, rebuild, migration, or out-of-band repair after docs drift, use `/prizmkit-prizm-docs` instead.
+The stage must always run for a formal requirement. When no documentation update is warranted, it records `NO_DOC_CHANGE` as a successful retrospective result rather than silently skipping the stage.
+
+For first-time documentation setup, validation, rebuild, migration, or out-of-band repair after docs drift, use `/prizmkit-prizm-docs` independently.
+
+## Formal Lifecycle Position
+
+```text
+prizmkit-plan
+  → prizmkit-implement
+  → prizmkit-code-review
+  → prizmkit-test
+  → prizmkit-retrospective
+  → prizmkit-committer
+```
+
+## Atomic Stage Boundary
+
+`prizmkit-retrospective` owns only structural documentation synchronization, durable knowledge injection, and retrospective result recording. It writes its truthful completion status and result plus `next_stage`, then returns control. It must not invoke `prizmkit-committer` itself; the active orchestrator owns the next-stage invocation.
 
 ## When to Use
 
-- Full path: after code review passes and before commit when code/docs knowledge changed.
-- Fast path: before commit only when structure, interfaces, dependencies, behavior, or durable project knowledge changed.
-- Bug fixes: run structural sync when the fix changes interfaces/dependencies/observable behavior; run knowledge injection only when the fix reveals durable TRAPS/RULES/DECISIONS.
-- Test-only changes: run only when tests reveal durable boundaries, traps, interface constraints, behavior rules, or regression knowledge worth preserving.
-- User says "retrospective", "retro", "update docs", "sync docs", or "wrap up" during normal development.
+- After `/prizmkit-test` returns `TEST_PASS` for a formal requirement.
+- When workflow state resumes a previously interrupted retrospective.
+- When the user explicitly requests a retrospective or documentation synchronization outside a formal requirement.
 
 ## When NOT to Use
 
-- Direct edit with no structural, behavioral, dependency, interface, or durable-knowledge change.
-- Only comments, whitespace, or formatting changed.
-- Only `.prizm` files changed — avoid circular updates.
-- Test-only changes that merely add coverage for already documented behavior and reveal no new durable knowledge.
-- Out-of-band doc repair/resync after merges or branch switches — use `/prizmkit-prizm-docs` Update/Rebuild/Validate.
+- The requirement has not passed code review and testing.
+- `TEST_FAIL` or `TEST_BLOCKED` remains unresolved.
+- The request is a direct edit outside the formal requirement lifecycle, unless the user explicitly asks for documentation maintenance.
+- First-time docs initialization or out-of-band docs repair; use `/prizmkit-prizm-docs` instead.
+
+## Preconditions and Artifact Identity
 
-## Input
+1. Reuse the caller's `artifact_dir`; do not select another requirement.
+2. Confirm the latest review result is `PASS`.
+3. Confirm the latest testing result is `TEST_PASS`.
+4. Read the final source diff with `.prizmkit/` excluded, then use `spec.md`, `plan.md`, the final `review-report.md`, and final test evidence only as supporting context for the non-`.prizmkit/` changes.
+5. If the workflow state is missing or stale, reconstruct it from those authoritative artifacts and report the reconstruction.
 
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `artifact_dir` | No | Directory containing `spec.md`, `plan.md`, and optionally `review-report.md`. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a `plan.md`. When invoked as a handoff step, reuse the caller's `artifact_dir` rather than re-detecting. If no artifact directory is found, run standalone structural sync from `git diff`. |
+`.prizmkit/` is always excluded from retrospective project-change input scope. Do not treat any file under `.prizmkit/`—including plans, artifacts, state, evidence, or existing Prizm docs—as a changed project file from which structural or durable knowledge is inferred. Required lifecycle state/evidence writes and targeted `.prizmkit/prizm-docs/` updates remain outputs; documentation changes must be justified only by observed non-`.prizmkit/` project changes.
 
 ## Job 1: Structural Sync
 
-Synchronize `.prizmkit/prizm-docs/` structure with actual codebase changes from this session.
+When `.prizmkit/prizm-docs/` exists, read `${SKILL_DIR}/references/structural-sync-steps.md` and synchronize documentation with the final codebase changes.
+
+Review only changed project files outside `.prizmkit/`:
 
-Read `${SKILL_DIR}/references/structural-sync-steps.md` for the detailed procedure.
+- added, modified, deleted, and renamed source files;
+- structural module files, configuration, interfaces, and tests when they reveal durable project behavior;
+- documentation mappings affected by those non-`.prizmkit/` project changes;
+- stale pointers and stale traps implicated by those project changes;
+- format, pointer, size, and memory-hygiene constraints for any docs the retrospective updates.
 
-Key outputs:
-- L1 file counts and module mappings
-- L2 KEY_FILES / INTERFACES / DATA_FLOW / DEPENDENCIES for affected diff files
-- New L1/L2 docs when newly changed source directories require them
-- Stale TRAPS cleanup when needed
+Never use `.prizmkit/` changes themselves as structural-sync input.
 
-Memory hygiene: `.prizmkit/prizm-docs/` must not contain CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths. Convert artifact-scoped wording into durable product/domain language before writing.
+When `.prizmkit/prizm-docs/` does not exist, do not pretend structural sync occurred. Record `NO_DOC_CHANGE` with reason `PRIZM_DOCS_NOT_INITIALIZED` and recommend `/prizmkit-init` or `/prizmkit-prizm-docs` for a future setup. The formal lifecycle may still continue because initialization is a soft prerequisite.
+
+Do not create an L2 document merely because one was missing during implementation. Create it only when the final change contains meaningful durable module knowledge.
 
 ## Job 2: Knowledge Injection
 
-Inject newly discovered durable project knowledge into architecture docs.
+When the final project change outside `.prizmkit/` reveals durable knowledge, read `${SKILL_DIR}/references/knowledge-injection-steps.md` and inject only stable product/domain knowledge into Prizm docs.
 
-Read `${SKILL_DIR}/references/knowledge-injection-steps.md` for the detailed procedure.
+Candidate knowledge includes:
 
-### Review Gate
+- new traps, race conditions, or surprising coupling;
+- architectural rules or decisions;
+- interface or contract changes;
+- dependencies affecting module behavior;
+- observable behavior changes;
+- test-discovered boundaries or regression rules.
 
-Before Job 2, check `review-report.md` in the artifact directory when present:
+Do not write transient artifact paths, task IDs, branch names, dates, session/run metadata, or changelog material into Prizm docs.
 
-- Verdict `PASS` → proceed.
-- Verdict `NEEDS_FIXES` → skip Job 2 and warn: "Review report has unresolved findings. Skipping knowledge injection."
-- No `review-report.md` → proceed with warning for Fast path or standalone mode.
-- No artifact directory → skip Job 2 unless the user explicitly provides durable knowledge to record.
+When no durable structural or knowledge change exists, return `NO_DOC_CHANGE` and explain why.
 
-### Knowledge Injection Triggers
+## Verification and Staging
 
-Run Job 2 when the task produced durable knowledge such as:
+1. Validate any updated docs using the project documentation rules.
+2. Review the final diff and ensure only intended documentation changes are present.
+3. Do not change the target project's Git or ignore policy. If the host or project workflow stages docs, report what was staged; otherwise leave staging to `/prizmkit-committer`.
+4. Never claim documentation synchronization passed if validation failed.
 
-- New TRAPS, gotchas, race conditions, or surprising coupling
-- New architectural rules or decisions
-- Interface signature or contract changes
-- Dependency additions/removals that affect module behavior
-- Observable behavior changes to existing features
-- Test-only discoveries that document new boundary conditions, regression rules, or interface constraints
+## Retrospective Result
 
-Skip Job 2 for pure refactors with no durable design or behavior knowledge.
+Write `{artifact_dir}/retrospective-result.json` for every formal requirement:
 
-## Final: Stage Docs
+```json
+{
+  "status": "RETRO_COMPLETE",
+  "result": "DOCS_UPDATED",
+  "reason": "Durable module interfaces and traps changed",
+  "review_verdict": "PASS",
+  "test_verdict": "TEST_PASS"
+}
+```
 
-Stage doc changes only after verifying they are intended:
+`status=RETRO_COMPLETE` is the stable completion status. `result` must be exactly `DOCS_UPDATED` or `NO_DOC_CHANGE`; do not use either result as a substitute for completion status. Use `result=NO_DOC_CHANGE` with a concrete reason when no documentation update is warranted. This artifact is the retrospective gate evidence consumed by the committer and external automation; workflow state alone does not prove completion.
 
-```bash
-git add .prizmkit/prizm-docs/
+## Workflow State and Handoff
+
+Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
+
+On successful completion, update `.prizmkit/state/workflows/<requirement-slug>.json`:
+
+```json
+{
+  "stage": "retrospective",
+  "status": "RETRO_COMPLETE",
+  "completed_stages": ["plan", "implement", "code-review", "test", "retrospective"],
+  "next_stage": "committer",
+  "resume_from": "prizmkit-committer"
+}
 ```
 
-Do not stage unrelated files.
+Use `status=RETRO_COMPLETE` for both successful outcomes, with `result=DOCS_UPDATED` when durable docs changed or `result=NO_DOC_CHANGE` when the stage completed without a docs update. Both result values permit the commit stage.
+
+If documentation validation or synchronization cannot safely complete, return `RETRO_BLOCKED`, do not commit, and provide the exact recovery entry.
+
+## Output and Handoff
 
-## Output
+Report:
+
+- `{artifact_dir}/retrospective-result.json` with `DOCS_UPDATED` or `NO_DOC_CHANGE`;
+- docs updated, created, or intentionally unchanged;
+- durable knowledge decisions;
+- validation evidence;
+- workflow state path and status;
+- the same `artifact_dir` for the next stage.
+
+After `RETRO_COMPLETE`:
+
+```text
+RETRO_COMPLETE
+  → /prizmkit-committer
+```
 
-- Updated `.prizmkit/prizm-docs/*.prizm` files when sync or knowledge injection applies
-- Summary of updated, created, and skipped docs with reasons
-- Handoff: `/prizmkit-committer`
+If workflow state names an active `orchestrator`, return `RETRO_COMPLETE`, `stage_result`, the retrospective/state paths, and `next_stage=committer` to it; do not invoke the committer independently. For direct stage use, provide the deterministic `/prizmkit-committer` invocation; a host may perform that semantic handoff on the user's behalf.

package/bundled/skills/prizmkit-retrospective/references/knowledge-injection-steps.md

@@ -1,12 +1,13 @@
 # Knowledge Injection — Detailed Steps (2a–2c)
 
-**2a.** Gather context — read the **actual code that was changed** plus any available artifacts:
+**2a.** Gather context from the **actual project files changed outside `.prizmkit/`**:
 
-- `git diff HEAD` — the real source of truth for what happened
-- `review-report.md` in the artifact directory — read the findings and fix instructions. If this file exists, use it as a source for pre-categorized decisions and findings.
-- `plan.md` in the artifact directory — read planned vs actual
-- Any companion documents in the artifact directory (e.g., `refactor-analysis.md`, `fix-report.md`) — read what was discovered
-- The relevant `.prizmkit/prizm-docs/` L1/L2 docs for affected modules
+- `git diff HEAD -- . ':(exclude).prizmkit/**'` — the source of truth for eligible project changes
+- Current Main-Agent context for the requirement — reuse it rather than rereading artifacts by default
+- Targeted unchanged source, interfaces, callers, dependents, or tests only when an eligible diff raises a concrete ambiguity
+- The affected Prizm docs only as update targets and existing-knowledge checks, never as changed project input
+
+Do not scan or mine any `.prizmkit/` file for retrospective knowledge. Plans, review reports, test evidence, workflow state, and existing Prizm docs may describe transient or generated material; they must not create a retrospective fact independently of an observed non-`.prizmkit/` code or project-file change.
 
 **2b.** Extract knowledge from what was **observed in code**, not invented:
 

package/bundled/skills/prizmkit-retrospective/references/structural-sync-steps.md

@@ -2,13 +2,15 @@
 
 ## 1. Get changed files
 
-Get changed files from staged and unstaged changes relative to HEAD:
+Get changed project files from staged and unstaged changes relative to HEAD while excluding the entire `.prizmkit/` tree:
 
 ```bash
-git diff HEAD --name-status
+git diff HEAD --name-status -- . ':(exclude).prizmkit/**'
 ```
 
-If the caller supplied an explicit file list, use that list instead and note the source in the report.
+If pathspec exclusion is unavailable, filter every result whose normalized repository-relative path is exactly `.prizmkit` or starts with `.prizmkit/` before classification. Do not infer project structure or durable knowledge from excluded files.
+
+If the caller supplied an explicit file list, apply the same `.prizmkit/` exclusion before using it and note the source in the report. If no files remain, structural sync is not needed.
 
 ## 2. Map files to modules
 
@@ -33,7 +35,6 @@ If a changed source file maps to no module, evaluate whether its directory quali
 Skip structural sync when changes are limited to:
 
 - comments, whitespace, or formatting
-- `.prizm` files only
 - internal implementation details with no interface, dependency, data-flow, or module mapping impact
 - test-only changes that reveal no durable boundaries, traps, interface constraints, behavior rules, or regression knowledge
 

package/bundled/skills/prizmkit-retrospective/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.