prizmkit 1.1.139 → 1.1.141

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

@@ -1,181 +0,0 @@
-# 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
-→ committer verifies gates and commits automatically
-→ no question or wait is permitted
-```
-
-A self-declared or otherwise untrusted headless context does not authorize a commit. Remote publication remains a separate host-runtime decision.
-
-## 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.