prizmkit 1.1.130 → 1.1.134

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

@@ -15,9 +15,44 @@ Choose project-semantic parameters from the target project: framework, commands,
 
 Fix only the protocol mechanisms needed for safe, replayable evidence: project/evidence/request locators, schema-shaped requests, path confinement, real process execution, complete raw capture, runner-generated chained receipts, hash binding, append-only history, differential isolation/cleanup, and resume invalidation. Read `${SKILL_DIR}/references/trusted-evidence-execution.md` before inventory, execution, differential proof, resume, or replay; it defines the trust boundary and builder commands. Read `${SKILL_DIR}/references/evidence-request-protocol.md` when authoring any request or authoritative JSON record; it defines request ownership, structured N/A, and the schema map.
 
-## When to Use
+## Canonical Evidence Builder Lifecycle
+
+The Main Agent supplies semantic requests only; it does not author authoritative package records. Initialize and drive one evidence directory through the builder in this order:
+
+```text
+init → capture-change → inventory → execute/differential → finalize → render-report → validate --attest → resume
+```
+
+Use `${SKILL_DIR}/scripts/build_test_evidence.py` for every lifecycle command:
+
+- `init`: creates the package directories and immutable baseline identity.
+- `capture-change`: captures the complete canonical change, including untracked, deleted, renamed, and copied files; never substitute plain `git diff`.
+- `inventory`: hashes current source/tests/contracts/lockfiles, rejects category overlap, excludes runtime-only paths, and validates directory roots plus explicit changed-file sets.
+- `execute`: runs native project commands and owns `executions.json`, `receipts/`, and `raw/`.
+- `differential`: records executable proof or a mechanically validated `NOT_APPLICABLE` decision only for genuinely new behavior or textual-contract behavior.
+- `finalize`: owns manifest, stage hashes, verdict, generated-test snapshots, and evidence identity.
+- `render-report`: derives `test-report.md`; it is never authoritative.
+- `resume`: preserves prior receipts and refuses to rebind an identity-changing package; create a new package after scope/source identity changes.
+
+Before testing, inspect and reuse repository-native tests and their runner configuration. Existing tests are the default. Add or modify a project-native test only after recording a concrete behavior gap. Classify each planned test as `existing`, `added`, or `modified`; `generated-tests/` is empty for unchanged existing tests and contains only snapshots of added/modified native test sources.
+
+`test-plan.json` is the only source of test IDs. Execution requests may reference only IDs declared there, and the builder rejects unknown IDs or layer mappings. Assess all five layers explicitly, but set `required=true` only when risk requires it; every omitted layer needs structured N/A evidence. The same binding applies test ↔ behavior ↔ execution ↔ differential proof.
+
+The builder/validator, not the Main Agent, produces or updates `manifest.json`, `executions.json`, `receipts/*`, `validation.json`, `verdict.json`, `test-report.md`, and `source-change.patch`. `validation.json` is produced only by `validate_test_evidence.py --attest`; a package is not a `TEST_PASS` until the second strict validation succeeds.
+
+
+For a formal requirement, `/prizmkit-test` runs after the Main-Agent code-review stage reaches `PASS` and before retrospective:
+
+```text
+plan → implement → code-review → test → retrospective → committer
+```
+
+Read `${SKILL_DIR}/references/workflow-state-protocol.md` before reading or updating lifecycle state. Reuse the caller's `artifact_dir`; do not select another recent plan. When an active `orchestrator` is recorded, return the testing result and next-stage metadata to it instead of invoking another skill independently.
+
+## Atomic Stage Boundary
+
+`prizmkit-test` owns only auditable test evidence generation, validation, and the testing-domain verdict. It writes the authoritative `TEST_*` result and `next_stage`, then returns control. When an external orchestrator is active, it must not invoke retrospective or implementation itself. The active orchestrator owns the next-stage invocation and repair routing.
 
-Use for:
 
 - behavior-changing source code;
 - runtime configuration, schema, migration, generated-runtime, lockfile, or dependency changes;
@@ -35,6 +70,7 @@ Documentation, comment, and formatting-only scopes use deterministic lightweight
 3. Preserve complete command/environment/output values as requested. Mark the package `sensitivity=project-controlled`; the project owns access control, retention, and upload policy.
 4. Treat code-level dependencies as mock-first. Real deployed test-environment validation is a separate authorized activity.
 5. Never delete existing tests.
+6. For `TEST_FAIL`, classify and persist an evidence-backed `repair_scope` of `test-infrastructure`, `production`, `runtime`, `schema`, `dependency`, `public-interface`, or `unknown`. Test-infrastructure scope routes to implement then test; production-family scope routes to implement, code-review, then test. If evidence cannot support a safe classification, return `TEST_BLOCKED`.
 
 If test infrastructure is missing, the infrastructure preparation state establishes only the necessary project-native infrastructure autonomously. Do not ask the user to install routine test dependencies in a headless run; verify dependency versions before editing manifests.
 
@@ -171,7 +207,7 @@ Create `.prizmkit/test/evidence/<evidence-id>/` from the package template with:
 - `contracts/` snapshots
 - derived `test-report.md`
 
-Hash baseline, diff, the stable source snapshot, inventoried source/tests/contracts/lockfiles, environment, plan, and every evidence file. Runtime state, evidence output, linked Agent worktrees, Git metadata, and bytecode caches are outside source identity; evidence files remain independently content-addressed through `manifest.json`. Set `environment_claim=mocked-code-level-only` and `compatibility=legacy-test-report-interface-not-supported`.
+Hash baseline, diff, the stable source snapshot, inventoried source/tests/contracts/lockfiles, environment, plan, and every evidence file. Runtime state, evidence output, linked Agent worktrees, Git metadata, and bytecode caches are outside source identity; evidence files remain independently content-addressed through `manifest.json`. Set `environment_claim=mocked-code-level-only`.
 
 ### 9. EVIDENCE_VALIDATE
 
@@ -203,11 +239,17 @@ For a large module or bounded budget, persist matrix/checkpoint progress and ret
 Only these testing-domain outcomes are valid:
 
 - `TEST_PASS`: every required module behavior/risk and Regression Ring check is proven, required executions pass reliably, cleanup succeeds, no verdict-capable unresolved edge remains, and deterministic validation passes.
-- `TEST_FAIL`: a valid reliable test reproduces an implementation or resolved-contract failure.
+- `TEST_FAIL`: a valid reliable test reproduces an implementation or resolved-contract failure. The authoritative verdict record must include `repair_scope` and enough evidence for the next stage to route safely.
 - `TEST_BLOCKED`: unknown scope, conflicting truth, unavailable/unreliable/flaky necessary execution, incomplete evidence, unproven tests, failed cleanup, budget truncation, or deterministic validation failure.
 
 No conditional pass exists.
 
+## Workflow State and Handoff
+
+Before writing state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
+
+On `TEST_PASS`, update the active workflow state with `status=TEST_PASS`, `stage_result=TEST_PASS`, and `next_stage=retrospective`. On `TEST_FAIL`, persist the evidence-backed `repair_scope`, set `status=TEST_FAIL` and `stage_result=TEST_FAIL`, and return to implementation; test-infrastructure scope selects `next_stage=implement` with a direct test resume, while production-family scope selects `next_stage=implement` and requires code review before testing again. On `TEST_BLOCKED`, preserve the blocker, do not modify production code speculatively, and return a blocked result. The authoritative verdict is the validated evidence record; the derived Markdown report is only a compatibility view. If an active orchestrator exists, return the terminal result and `next_stage` to it; do not invoke the next skill independently.
+
 ## Derived Report and Handoff
 
 Generate `test-report.md` from structured evidence using `${SKILL_DIR}/references/test-report-template.md`. It is a replaceable view, not the source of truth. Report only:
@@ -216,9 +258,13 @@ Generate `test-report.md` from structured evidence using `${SKILL_DIR}/reference
 - evidence directory and ID;
 - validator result and key execution pointers;
 - sensitivity and mocked-versus-real warning;
-- explicit notice that the legacy test-report interface is not supported.
+- authoritative evidence pointers for external automation and interactive consumers.
+
+Do not embed an independent AI reviewer, decide overall code quality, claim broad Spec compliance, repair a validly detected business defect, authorize commit/release, or perform deployed test/production validation. The derived report is a view; `verdict.json`, validation records, and the evidence manifest remain authoritative.
+
+## Compatibility
 
-Do not embed an independent AI reviewer, decide overall code quality, claim broad Spec compliance, repair a validly detected business defect, authorize commit/release, or perform deployed test/production validation.
+Consumers must read authoritative `TEST_*` evidence. During migration, a legacy Markdown report may be used only as a compatibility view after the authoritative verdict has passed validation.
 
 Existing Pipeline and Skill consumers are not migrated by this protocol. Temporary post-install incompatibility with callers expecting the legacy report is accepted and must be stated, not hidden.
 

package/bundled/skills/prizmkit-test/assets/authoritative-records.schema.json

@@ -183,12 +183,33 @@
           }
         },
         "changed_files": { "$ref": "#/$defs/stringArray" },
-        "module_roots": { "$ref": "#/$defs/stringArray" },
+        "module_roots": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "oneOf": [
+              { "$ref": "#/$defs/path" },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["path", "changed_files"],
+                "properties": {
+                  "path": { "$ref": "#/$defs/path" },
+                  "changed_files": { "$ref": "#/$defs/stringArray" }
+                }
+              }
+            ]
+          }
+        },
         "module_root_files": {
           "type": "object",
           "minProperties": 1,
           "additionalProperties": { "$ref": "#/$defs/stringArray" }
         },
+        "module_root_changed_files": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/stringArray" }
+        },
         "exclusions": { "type": "array", "items": { "$ref": "#/$defs/path" } },
         "discovery_evidence": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/discoveryEvidence" } },
         "plan_inputs": { "type": "object", "minProperties": 1 }
@@ -225,8 +246,9 @@
             "properties": {
               "id": { "type": "string", "minLength": 1 },
               "behavior_ids": { "$ref": "#/$defs/stringArray" },
+              "change_status": { "enum": ["existing", "added", "modified"] },
               "project_path": { "$ref": "#/$defs/path" },
-              "snapshot_path": { "$ref": "#/$defs/path" },
+              "snapshot_path": { "type": ["string", "null"] },
               "inventory_path": { "$ref": "#/$defs/path" },
               "layers": { "$ref": "#/$defs/stringArray" }
             }
@@ -289,19 +311,47 @@
     },
     "executionLog": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/executionReceipt" } },
     "differentialRequest": {
+      "type": "object",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["request_version", "behavior_id", "method", "execution_request", "baseline_commit", "current_tree_sha256", "mutation_patch_path", "test_overlay_paths", "expected_failure_signals"],
+          "properties": {
+            "request_version": { "const": "1.0" },
+            "behavior_id": { "type": "string", "minLength": 1 },
+            "method": { "enum": ["baseline", "controlled-mutation"] },
+            "execution_request": { "$ref": "#/$defs/executionRequest" },
+            "baseline_commit": { "type": "string", "minLength": 1 },
+            "current_tree_sha256": { "$ref": "#/$defs/sha256" },
+            "mutation_patch_path": { "type": ["string", "null"] },
+            "test_overlay_paths": { "$ref": "#/$defs/stringArray" },
+            "expected_failure_signals": { "$ref": "#/$defs/stringArray" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["request_version", "behavior_id", "method", "not_applicable"],
+          "properties": {
+            "request_version": { "const": "1.0" },
+            "behavior_id": { "type": "string", "minLength": 1 },
+            "method": { "const": "not-applicable" },
+            "not_applicable": { "$ref": "#/$defs/differentialNotApplicable" }
+          }
+        }
+      ]
+    },
+    "differentialNotApplicable": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["request_version", "behavior_id", "method", "execution_request", "baseline_commit", "current_tree_sha256", "mutation_patch_path", "test_overlay_paths", "expected_failure_signals"],
+      "required": ["reason", "rationale", "evidence", "considered_signals", "conflicts"],
       "properties": {
-        "request_version": { "const": "1.0" },
-        "behavior_id": { "type": "string", "minLength": 1 },
-        "method": { "enum": ["baseline", "controlled-mutation"] },
-        "execution_request": { "$ref": "#/$defs/executionRequest" },
-        "baseline_commit": { "type": "string", "minLength": 1 },
-        "current_tree_sha256": { "$ref": "#/$defs/sha256" },
-        "mutation_patch_path": { "type": ["string", "null"] },
-        "test_overlay_paths": { "$ref": "#/$defs/stringArray" },
-        "expected_failure_signals": { "$ref": "#/$defs/stringArray" }
+        "reason": { "enum": ["new-behavior", "textual-contract"] },
+        "rationale": { "type": "string", "minLength": 16 },
+        "evidence": { "$ref": "#/$defs/stringArray" },
+        "considered_signals": { "$ref": "#/$defs/stringArray" },
+        "conflicts": { "type": "array", "items": { "type": "object" } }
       }
     },
     "differentialProof": {
@@ -375,6 +425,7 @@
         "real_environment_validated": { "const": false },
         "repairs_business_defects": { "const": false },
         "code_evidence_replayable": { "type": "boolean" },
+        "repair_scope": { "enum": ["test-infrastructure", "production", "runtime", "schema", "dependency", "public-interface"] },
         "blockers": { "type": "array", "items": { "type": "string", "minLength": 1 } },
         "reproduced_failures": { "type": "array", "items": { "type": "string", "minLength": 1 } }
       }

package/bundled/skills/prizmkit-test/assets/evidence-manifest.schema.json

@@ -56,7 +56,7 @@
     },
     "files": {
       "type": "array",
-      "minItems": 10,
+      "minItems": 1,
       "items": { "$ref": "#/$defs/file" }
     },
     "final_verdict": { "enum": ["TEST_PASS", "TEST_FAIL", "TEST_BLOCKED"] },

package/bundled/skills/prizmkit-test/assets/evidence-package-template.json

@@ -1,5 +1,16 @@
 {
   "protocol_version": "1.0",
+  "lifecycle_commands": [
+    "init",
+    "capture-change",
+    "inventory",
+    "execute",
+    "differential",
+    "finalize",
+    "render-report",
+    "resume"
+  ],
+  "generated_tests_policy": "Only added or modified repository-native tests are snapshotted; existing tests have no generated snapshot.",
   "records": {
     "change_classification": "change-classification.json",
     "scope": "scope.json",
@@ -13,6 +24,8 @@
     "verdict": "verdict.json",
     "validation": "validation.json",
     "source_patch": "source-change.patch",
+    "change_capture": "change-capture.json",
+    "lifecycle": "lifecycle.json",
     "derived_report": "test-report.md"
   },
   "directories": {

package/bundled/skills/prizmkit-test/references/evidence-protocol.md

@@ -23,7 +23,12 @@ Hashes and validator receipts provide byte-level binding and drift detection, no
 
 `source-change.patch` preserves the complete target diff. Snapshot generated/changed tests under `generated-tests/`, contracts under `contracts/`, and raw stdout/stderr under `raw/`. Never replace old execution/output records.
 
-## Ordered State Machine
+## Existing Tests and Package Finalization
+
+The evidence package is an audit of repository behavior, not a request to invent a parallel test suite. Discover and execute the smallest relevant native tests before adding anything. `generated-tests/` is a snapshot area for added or modified repository-native tests only; it may be empty when existing tests cover the behavior.
+
+The canonical package lifecycle is `init → capture-change → inventory → execute/differential → finalize → render-report → validate --attest → resume`. Builder commands own `source-change.patch`, receipts, raw outputs, manifest, verdict, and report. The validator alone owns `validation.json`. Evidence identity is derived from the resolved baseline, canonical patch hash, and scope hash; identity-changing resume creates a new package instead of rewriting the old directory.
+
 
 Run exactly these states in order:
 

package/bundled/skills/prizmkit-test/references/evidence-request-protocol.md

@@ -2,7 +2,14 @@
 
 Load this reference when writing an inventory, execution, differential, resume, or replay request. Validate every authoritative record against `${SKILL_DIR}/assets/authoritative-records.schema.json`; the validator loads the named `$defs` for each file.
 
-## Request Ownership
+## Canonical Lifecycle Ownership
+
+Start every new package with `init`, then run builder-owned `capture-change` before semantic inventory. `capture-change` is the only producer of `source-change.patch`; it records tracked, untracked, deleted, renamed, and copied paths against the resolved baseline. The Main Agent must not create or edit the patch.
+
+Use existing project-native tests first. A test plan must identify each test as `existing`, `added`, or `modified`; only the latter two may receive a `generated-tests/` snapshot. Existing tests are executed from their repository paths and do not need generated snapshots. `test-plan.json` is the sole authority for test IDs, and execution requests with unknown IDs are rejected by the builder.
+
+`finalize` creates the manifest, stage dependency hashes, verdict, evidence identity, and deterministic report inputs. `render-report` only renders the derived Markdown view. The validator alone creates `validation.json` during `--attest`; never hand-author a validation attestation or rebind a finalized package after identity inputs change.
+
 
 The model writes project-semantic requests after inspecting manifests, runner configuration, contracts, test conventions, changed files, and module boundaries. The bundled builder owns process execution, raw output, receipts, isolation, tree hashes, and invalidation calculations.
 

package/bundled/skills/prizmkit-test/references/examples.md

@@ -99,4 +99,4 @@ A comments-only diff is deterministically classified and parser/format/generated
 
 ## Compatibility Notice
 
-The legacy `PASS | NEEDS_FIXES | BLOCKED` Markdown report interface is intentionally not preserved. Existing Pipeline and Skill consumers are not migrated here and may be temporarily incompatible after installation.
+The testing-domain verdict remains `TEST_PASS | TEST_FAIL | TEST_BLOCKED`. Consumers must use validated authoritative evidence and may use `test-report.md` only as a derived compatibility view. The formal lifecycle does not reinterpret a testing result as a review or commit verdict.

package/bundled/skills/prizmkit-test/references/test-generation-steps.md

@@ -2,7 +2,10 @@
 
 Use this reference during `INFRA_READY`, `TEST_BUILD`, and `EXECUTE_PROVE`. The authoritative scope and completeness inputs are `scope.json`, `behavior-risk-matrix.json`, and `test-plan.json`.
 
-## Scope Guard
+## Existing-Test-First Rule
+
+Before creating a test, inspect the repository's native test files, runner configuration, and existing behavior assertions. Execute the smallest relevant existing tests first. Add or modify a repository-native test only when a concrete behavior gap is identified and recorded in the test plan. Mark each test `existing`, `added`, or `modified`; only `added` and `modified` tests are copied into `generated-tests/`. An unchanged existing test has no generated snapshot.
+
 
 For `scope=this-change`, changed files locate the affected module; they do not restrict tests to changed lines. Fill observable behavior/risk gaps across the whole affected module and execute its Regression Ring. Unrelated modules remain out of scope unless they are direct callers, consumers, shared contracts, or state dependencies.
 

package/bundled/skills/prizmkit-test/references/test-report-template.md

@@ -78,7 +78,7 @@ Verdict: TEST_PASS | TEST_FAIL | TEST_BLOCKED
 - Real deployed environment validated: no
 
 ## Compatibility
-The legacy test-report interface is not supported. Existing Pipeline or other Skill consumers were not migrated and may be temporarily incompatible after installation.
+The formal lifecycle consumes validated authoritative `TEST_*` evidence through workflow state and structured evidence pointers. `test-report.md` is a derived compatibility view and must not be interpreted as a review, retrospective, commit, or release verdict.
 ```
 
 ## Verdict Rendering Rules

package/bundled/skills/prizmkit-test/references/trusted-evidence-execution.md

@@ -41,6 +41,21 @@ Treat evidence as auditable project-controlled provenance, not a defense against
 
 ## Builder Commands
 
+Drive a new package through the canonical lifecycle. Semantic request files remain model-authored; authoritative package records remain tool-owned:
+
+```bash
+python3 ${SKILL_DIR}/scripts/build_test_evidence.py --project-root <root> --evidence-dir <staging> init --baseline <commit>
+python3 ${SKILL_DIR}/scripts/build_test_evidence.py --project-root <root> --evidence-dir <staging> capture-change
+python3 ${SKILL_DIR}/scripts/build_test_evidence.py --project-root <root> --evidence-dir <staging> inventory --request requests/inventory.json
+python3 ${SKILL_DIR}/scripts/build_test_evidence.py --project-root <root> --evidence-dir <staging> execute --request requests/focused.json
+python3 ${SKILL_DIR}/scripts/build_test_evidence.py --project-root <root> --evidence-dir <staging> differential --request requests/differential.json
+python3 ${SKILL_DIR}/scripts/build_test_evidence.py --project-root <root> --evidence-dir <staging> finalize --request requests/finalize.json
+python3 ${SKILL_DIR}/scripts/build_test_evidence.py --project-root <root> --evidence-dir <staging> render-report
+```
+
+`capture-change` includes tracked modifications, untracked files, deletions, renames, and copies. `finalize` owns the manifest, verdict, stage hashes, evidence identity, and generated-test snapshots. The validator is the only producer of `validation.json`.
+
+
 Write requests beneath the evidence directory, then invoke the bundled script:
 
 ```bash

package/bundled/skills/prizmkit-test/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
+→ 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.