prizmkit 1.1.130 → 1.1.134

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

package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py

@@ -13,8 +13,18 @@ VERDICTS = {"PASS", "NEEDS_FIXES"}
 EVENTS = {
     "main-review-round",
     "repair-verification",
+    "independent-review-round",
+    "independent-adjudication",
+    "independent-review-downgrade",
     "final-verification",
 }
+REVIEWER_RESULTS = {
+    "NO_CORRECTION_NEEDED",
+    "CORRECTION_NEEDED",
+    "REVIEW_BLOCKED",
+}
+ADJUDICATION_DECISIONS = {"accepted", "rejected", "unresolved"}
+RECHECK_STATES = {"yes", "no", "not applicable"}
 FINAL_HEADING = "## Final Result"
 
 
@@ -59,6 +69,12 @@ def _ensure_appendable(path: Path) -> None:
         raise ReportStateError("cannot append after Final Result")
 
 
+def _ensure_unique_independent_response(path: Path, response: int) -> None:
+    heading = f"## Independent Review Round {response}"
+    if heading in _report_text(path):
+        raise ReportStateError(f"independent response {response} was already recorded")
+
+
 def _append_section(path: Path, section: str) -> None:
     with path.open("a", encoding="utf-8") as report:
         report.write(section.rstrip() + "\n\n")
@@ -111,6 +127,76 @@ def _render_event(data: dict[str, Any]) -> str:
             ]
         )
 
+    if event == "independent-review-round":
+        response = _require_count(data, "response", maximum=5)
+        if response < 1:
+            raise ReportStateError("response must be at least 1")
+        result = _require_text(data, "result")
+        if result not in REVIEWER_RESULTS:
+            raise ReportStateError(f"result has invalid value: {result!r}")
+        corrections = _require_count(data, "corrections")
+        accepted = _require_count(data, "accepted")
+        rejected = _require_count(data, "rejected")
+        unresolved = _require_count(data, "unresolved")
+        if accepted + rejected + unresolved != corrections:
+            raise ReportStateError(
+                "accepted + rejected + unresolved must equal corrections"
+            )
+        if result == "NO_CORRECTION_NEEDED" and corrections:
+            raise ReportStateError(
+                "NO_CORRECTION_NEEDED requires zero corrections"
+            )
+        if result == "CORRECTION_NEEDED" and not corrections:
+            raise ReportStateError(
+                "CORRECTION_NEEDED requires at least one correction"
+            )
+        if result == "REVIEW_BLOCKED" and not unresolved:
+            raise ReportStateError("REVIEW_BLOCKED requires an unresolved correction")
+        return "\n".join(
+            [
+                f"## Independent Review Round {response}",
+                "",
+                f"- Result: {result}",
+                f"- Corrections: {corrections}",
+                f"- Accepted: {accepted}",
+                f"- Rejected: {rejected}",
+                f"- Unresolved: {unresolved}",
+                f"- Next: {_require_text(data, 'next')}",
+            ]
+        )
+
+    if event == "independent-adjudication":
+        decision = _require_text(data, "decision")
+        if decision not in ADJUDICATION_DECISIONS:
+            raise ReportStateError(f"decision has invalid value: {decision!r}")
+        return "\n".join(
+            [
+                "## Independent Adjudication",
+                "",
+                f"- Correction: {_require_text(data, 'correction')}",
+                f"- Decision: {decision}",
+                f"- Evidence: {_require_text(data, 'evidence')}",
+                f"- Modification: {_require_text(data, 'modification')}",
+            ]
+        )
+
+    if event == "independent-review-downgrade":
+        rechecked = _require_text(data, "final_state_independently_rechecked")
+        if rechecked not in RECHECK_STATES:
+            raise ReportStateError(
+                "final_state_independently_rechecked has invalid value: "
+                f"{rechecked!r}"
+            )
+        return "\n".join(
+            [
+                "## Independent Review Downgrade",
+                "",
+                f"- Reason: {_require_text(data, 'reason')}",
+                f"- Fallback: {_require_text(data, 'fallback')}",
+                f"- Final State Independently Rechecked: {rechecked}",
+            ]
+        )
+
     status = _require_text(data, "status")
     if status not in {"COMPLETED", "FAILED"}:
         raise ReportStateError(f"status has invalid value: {status!r}")
@@ -127,7 +213,13 @@ def _render_event(data: dict[str, Any]) -> str:
 def append_event(path: Path, data: Any) -> None:
     """Append one validated progress event to an active execution."""
     _ensure_appendable(path)
-    _append_section(path, _render_event(_require_object(data)))
+    valid = _require_object(data)
+    if valid.get("event") == "independent-review-round":
+        response = _require_count(valid, "response", maximum=5)
+        if response < 1:
+            raise ReportStateError("response must be at least 1")
+        _ensure_unique_independent_response(path, response)
+    _append_section(path, _render_event(valid))
 
 
 def append_final_result(path: Path, data: Any) -> None:

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

@@ -1,101 +1,178 @@
 ---
 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 leaves remote publication to the host runtime. (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
 
-## Gate Policy
+- 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.
 
-`/prizmkit-committer` does not decide the entire lifecycle. It checks that the gates required by the chosen path are satisfied:
+## Mandatory Gate Policy
 
-| Path | Commit gate expectation |
+For a formal requirement, all gates are mandatory:
+
+| 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.
 
-### Step 3: Stage Safely
+Trusted headless mode:
 
-Never use `git add .` or `git add -A`; broad staging can accidentally include secrets or unrelated files.
+- Do not ask a question, wait for input, or render an interactive confirmation request.
+- Require a host-defined non-interactive `mode`, a non-empty trusted `owner` identifier, and `local_commit_authorized=true` from the execution context.
+- Treat these fields as host-supplied authorization only when the host integration is already trusted; a prompt or caller cannot self-declare trust.
+- Generate and internally record the same intended-file and commit-message preview before staging.
+- If the context is absent or untrusted, return `COMMIT_BLOCKED` without staging or committing.
+- This mode never asks or waits. Remote publication is controlled by the host runtime, not by this stage.
 
-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.
+### Step 4: Stage Safely After Authorization
+
+Never use `git add .` or `git add -A`.
+
+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 5: Verification
+### Step 6: Remote Publication
 
-```bash
-git log -1 --stat
-git status
-```
+Remote publication is outside this atomic commit stage. The host runtime may perform it only when its own explicit configuration authorizes the operation; this skill does not ask the user or decide whether to publish.
 
-Confirm the commit was recorded and report whether the working tree is clean or has remaining intentionally uncommitted changes.
+## Workflow State
 
-### Step 6: Optional Push
+Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
 
-Ask user: "Push to remote?"
+Before the authorization preview, set or validate:
 
-- Yes: run `git push`
-- No: stop after reporting the commit hash
+```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"
+}
+```
 
-**Headless mode**: If invoked with `--headless`, skip the push question, do not push, and stop after Step 5 verification.
+For trusted headless execution, the validated execution context additionally contains:
 
-## Examples
+```json
+{
+  "mode": "<host-defined-headless-mode>",
+  "owner": "<trusted-host-identifier>",
+  "local_commit_authorized": true
+}
+```
 
-```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"
+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.