prizmkit 1.1.141 → 1.1.143

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

@@ -45,7 +45,7 @@ Every consumer compares workflow state with the skill-owned artifacts and curren
   "artifact_dir": ".prizmkit/specs/example",
   "orchestrator": "prizmkit-workflow",
   "stage": "test",
-  "status": "TEST_PASS",
+  "status": "completed",
   "stage_result": "TEST_PASS",
   "completed_stages": ["plan", "implement", "code-review", "test"],
   "repair_scope": null,
@@ -63,14 +63,16 @@ Every consumer compares workflow state with the skill-owned artifacts and curren
 | `artifact_dir` | Generic requirement artifact root reused by every stage. |
 | `orchestrator` | Semantic coordinator identifier, or null for direct stage use. |
 | `stage` | Stage that most recently wrote state. |
-| `status` | Lifecycle progression status, distinct from `stage_result`. |
-| `stage_result` | Domain result such as `PASS`, `NEEDS_FIXES`, `TEST_*`, `DOCS_UPDATED`, or `NO_DOC_CHANGE`. |
+| `status` | Lifecycle status: `pending`, `in_progress`, `completed`, `failed`, or `skipped`. |
+| `stage_result` | Domain result for the current stage, such as `PLAN_READY`, `IMPLEMENTED`, `REVIEW_PASS`, `REVIEW_NEEDS_FIXES`, `TEST_*`, `RETRO_COMPLETE`, or `COMMITTED`. |
 | `completed_stages` | Ordered stages completed for this requirement. |
 | `repair_scope` | Optional caller-owned routing scope. The test skill reports high-risk repairs through `test-result.json` instead of scheduling another stage. |
 | `repair_round` | Optional outer cross-stage repair round, from 0 through 3. It is not a test-internal repair counter. |
 | `next_stage` | Next semantic stage, or null when stopped. |
 | `resume_from` | Exact atomic skill that can resume, or null when none is selected. |
 
+`status` and `stage_result` are deliberately separate. Lifecycle status values must never be replaced with domain result values.
+
 ## Lifecycle and Result Mappings
 
 ```text
@@ -83,18 +85,28 @@ PLAN_READY
 → COMMITTED
 ```
 
-No formal stage is silently optional. Domain artifacts map as follows:
+No formal stage is silently optional. Domain artifacts map to workflow state as follows:
 
 ```text
-review-report PASS               → status=REVIEW_PASS, stage_result=PASS
-review-report NEEDS_FIXES        → status=REVIEW_NEEDS_FIXES, stage_result=NEEDS_FIXES
-test-result TEST_PASS            → status=TEST_PASS, stage_result=TEST_PASS
-test-result TEST_NEEDS_FIXES     → status=TEST_NEEDS_FIXES, stage_result=TEST_NEEDS_FIXES
-test-result TEST_BLOCKED         → status=TEST_BLOCKED, stage_result=TEST_BLOCKED
-retrospective DOCS_UPDATED       → status=RETRO_COMPLETE, stage_result=DOCS_UPDATED
-retrospective NO_DOC_CHANGE      → status=RETRO_COMPLETE, stage_result=NO_DOC_CHANGE
+plan PLAN_READY                  → status=completed,  stage_result=PLAN_READY
+plan PLAN_BLOCKED                → status=failed,     stage_result=PLAN_BLOCKED
+implementation IMPLEMENTED       → status=completed,  stage_result=IMPLEMENTED
+implementation repair/block      → status=failed,     stage_result=IMPLEMENT_REPAIR or IMPLEMENT_BLOCKED
+review-report PASS               → status=completed,  stage_result=REVIEW_PASS
+review-report NEEDS_FIXES        → status=failed,     stage_result=REVIEW_NEEDS_FIXES
+test-result TEST_PASS            → status=completed,  stage_result=TEST_PASS
+test-result TEST_NEEDS_FIXES     → status=failed,     stage_result=TEST_NEEDS_FIXES
+test-result TEST_BLOCKED         → status=failed,     stage_result=TEST_BLOCKED
+retrospective DOCS_UPDATED       → status=completed,  stage_result=RETRO_COMPLETE
+retrospective NO_DOC_CHANGE      → status=completed,  stage_result=RETRO_COMPLETE
+retrospective blocked            → status=failed,     stage_result=RETRO_BLOCKED
+commit authorization pending     → status=in_progress, stage_result=COMMIT_PENDING
+local commit confirmed           → status=completed,  stage_result=COMMITTED
+commit blocked                   → status=failed,     stage_result=COMMIT_BLOCKED
 ```
 
+`DOCS_UPDATED` and `NO_DOC_CHANGE` remain retrospective artifact `result` values. The workflow `stage_result` is the retrospective stage result `RETRO_COMPLETE`.
+
 `TEST_PASS` requires both `test-report.md` and a consistent `test-result.json`. No manifest, attestation, evidence package, or test-internal checkpoint is part of this contract.
 
 ## Non-Pass Results and Routing Boundary

package/bundled/templates/hooks/commit-intent-status.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Report whether staged source changes include Prizm documentation updates."""
+
+from __future__ import annotations
+
+import subprocess
+
+SOURCE_EXTENSIONS = (".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java")
+PRIZM_DOCS_PREFIX = ".prizmkit/prizm-docs/"
+
+
+def staged_files() -> list[str]:
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--name-only"],
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        check=False,
+    )
+    if result.returncode != 0:
+        return []
+    return [path for path in result.stdout.splitlines() if path.strip()]
+
+
+def main() -> int:
+    files = staged_files()
+    source_files = [path for path in files if path.endswith(SOURCE_EXTENSIONS)]
+    if not source_files:
+        return 0
+
+    prizm_docs = [path for path in files if path.startswith(PRIZM_DOCS_PREFIX)]
+    if prizm_docs:
+        print(
+            f"PRIZMKIT_DOC_STATUS: {len(source_files)} source file(s) staged | "
+            f".prizmkit/prizm-docs/ updated ({len(prizm_docs)} file(s))",
+            end="",
+        )
+    else:
+        print(
+            f"PRIZMKIT_DOC_STATUS: {len(source_files)} source file(s) staged | "
+            ".prizmkit/prizm-docs/ NOT UPDATED — update if this is a feature change",
+            end="",
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled/templates/hooks/commit-intent.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 -c \"import subprocess,sys; r=subprocess.run(['git','diff','--cached','--name-only'],text=True,encoding='utf-8',errors='replace',stdout=subprocess.PIPE,stderr=subprocess.DEVNULL); files=[p for p in r.stdout.splitlines() if p.strip()] if r.returncode==0 else []; src=[p for p in files if p.endswith(('.ts','.tsx','.js','.jsx','.py','.go','.rs','.java'))]; prizm=[p for p in files if p.startswith('.prizmkit/prizm-docs/')]; print(f'PRIZMKIT_DOC_STATUS: {len(src)} source file(s) staged | .prizmkit/prizm-docs/ updated ({len(prizm)} file(s))' if src and prizm else (f'PRIZMKIT_DOC_STATUS: {len(src)} source file(s) staged | .prizmkit/prizm-docs/ NOT UPDATED — update if this is a feature change' if src else ''), end='')\""
+            "command": "python3 .prizmkit/scripts/commit-intent-status.py"
           }
         ]
       }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 -c \"import os,re,subprocess,sys; data=os.environ.get('CLAUDE_TOOL_INPUT') or os.environ.get('CODEBUDDY_TOOL_INPUT') or ''; script='.prizmkit/scripts/diff-prizm-docs.py'; should=bool(re.search(r'git\\s+(commit|merge|rebase)', data)); res=subprocess.run([sys.executable, script],text=True,encoding='utf-8',errors='replace',stdout=subprocess.PIPE,stderr=subprocess.DEVNULL) if should and os.path.isfile(script) else None; drift=(res.stdout.strip() if res else ''); print('PRIZMKIT_DRIFT_DETECTED: prizm-docs structural differences found:\\n'+drift+'\\nPlease update affected .prizmkit/prizm-docs/ files.') if drift else None\""
+            "command": "python3 .prizmkit/scripts/post-command-prizm-drift.py"
           }
         ]
       }

package/bundled/templates/hooks/post-command-prizm-drift.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Report Prizm documentation drift after relevant Git commands."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+DRIFT_SCRIPT = Path(".prizmkit/scripts/diff-prizm-docs.py")
+RELEVANT_GIT_COMMAND = re.compile(r"git\s+(commit|merge|rebase)")
+
+
+def tool_input() -> str:
+    return os.environ.get("CLAUDE_TOOL_INPUT") or os.environ.get("CODEBUDDY_TOOL_INPUT") or ""
+
+
+def main() -> int:
+    if not RELEVANT_GIT_COMMAND.search(tool_input()) or not DRIFT_SCRIPT.is_file():
+        return 0
+
+    result = subprocess.run(
+        [sys.executable, str(DRIFT_SCRIPT)],
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        check=False,
+    )
+    drift = result.stdout.strip()
+    if drift:
+        print(
+            "PRIZMKIT_DRIFT_DETECTED: prizm-docs structural differences found:\n"
+            f"{drift}\n"
+            "Please update affected .prizmkit/prizm-docs/ files."
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.141",
+  "version": "1.1.143",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {

package/src/scaffold.js

@@ -724,6 +724,8 @@ export async function installPrizmkitScripts(projectRoot, dryRun, runtime = 'pyt
   const scripts = [
     'validate-prizm-docs.py',
     'diff-prizm-docs.py',
+    'commit-intent-status.py',
+    'post-command-prizm-drift.py',
   ];
   const legacyManagedScripts = [
     'validate-prizm-docs.sh',