prizmkit 1.1.154 → 1.1.155

package/bundled/skills/app-planner/scripts/validate-rules-configuration.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+"""Validate app-planner Rules Configuration resources as one coherent contract."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+LAYERS = ("frontend", "backend", "database", "mobile")
+SCHEMA_VERSION = "app-planner-question-manifest-v2"
+REQUIRED_RENDER_CONTRACT = {
+    "fixed_rules_policy": "invariants_only",
+    "selected_decision_precedence": True,
+    "quick_mode_requires_explicit_authorization": True,
+    "unmapped_option_policy": "semantic_fallback",
+    "not_applicable_policy": "explicit_statement",
+    "conflict_policy": "fail_generation",
+}
+QUESTION_HEADING_RE = re.compile(r"^###\s+(Q[0-9]+[a-z]?)\.", re.MULTILINE)
+PLACEHOLDER_RE = re.compile(r"\{\{\s*([A-Za-z0-9_]+)\s*\}\}")
+CONDITION_RE = re.compile(
+    r"^(Q[0-9]+[a-z]?)\s*(?:==|!=)\s*[A-Z][A-Z0-9_-]*$"
+    r"|^(Q[0-9]+[a-z]?)\s+in\s+\[[A-Z][A-Z0-9_-]*(?:,\s*[A-Z][A-Z0-9_-]*)*\]$"
+)
+CONDITION_FIELDS = (
+    "required_if",
+    "auto_derived_when",
+    "dual_native_repeat_when",
+    "note_open_ended_when",
+)
+FIXED_RULE_FORBIDDEN_PATTERNS = (
+    "all user-facing text must use i18n keys",
+    "only add dependencies after explicit permission",
+    "all apis must follow rest conventions",
+    "jwt is the default authentication mechanism",
+    "every module must have unit tests",
+    "all deep links must use universal links",
+)
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("root must be a JSON object")
+    return data
+
+
+def _as_string_list(value: object, label: str, errors: list[str]) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        errors.append(f"{label} must be an array of strings")
+        return []
+    return list(value)
+
+
+def _validate_layer(rules_root: Path, layer: str, errors: list[str]) -> None:
+    layer_root = rules_root / layer
+    required_files = {
+        "manifest": layer_root / "question-manifest.json",
+        "bank": layer_root / "question-bank.md",
+        "fixed": layer_root / "fixed-rules.md",
+        "derivation": layer_root / "derivation-rules.md",
+        "template": layer_root / "template.md",
+    }
+    missing = [name for name, path in required_files.items() if not path.is_file()]
+    if missing:
+        errors.append(f"{layer}: missing resources: {', '.join(missing)}")
+        return
+
+    try:
+        manifest = _load_json(required_files["manifest"])
+    except (OSError, json.JSONDecodeError, ValueError) as exc:
+        errors.append(f"{layer}: invalid question-manifest.json: {exc}")
+        return
+
+    if manifest.get("schema_version") != SCHEMA_VERSION:
+        errors.append(
+            f"{layer}: schema_version must be {SCHEMA_VERSION!r}, "
+            f"got {manifest.get('schema_version')!r}"
+        )
+    if manifest.get("layer") != layer:
+        errors.append(f"{layer}: manifest layer must equal directory name")
+
+    render_contract = manifest.get("render_contract")
+    if not isinstance(render_contract, dict):
+        errors.append(f"{layer}: render_contract must be an object")
+        render_contract = {}
+    for key, expected in REQUIRED_RENDER_CONTRACT.items():
+        if render_contract.get(key) != expected:
+            errors.append(
+                f"{layer}: render_contract.{key} must be {expected!r}, "
+                f"got {render_contract.get(key)!r}"
+            )
+
+    questions = manifest.get("questions")
+    if not isinstance(questions, list) or not all(isinstance(item, dict) for item in questions):
+        errors.append(f"{layer}: questions must be an array of objects")
+        questions = []
+    question_ids = [str(item.get("id") or "") for item in questions]
+    if any(not question_id for question_id in question_ids):
+        errors.append(f"{layer}: every question must have a non-empty id")
+    if len(question_ids) != len(set(question_ids)):
+        errors.append(f"{layer}: duplicate question ids in manifest")
+    if manifest.get("total_questions") != len(question_ids):
+        errors.append(
+            f"{layer}: total_questions={manifest.get('total_questions')!r} "
+            f"does not match {len(question_ids)} manifest questions"
+        )
+
+    groups = manifest.get("groups")
+    if not isinstance(groups, list) or not all(isinstance(item, dict) for item in groups):
+        errors.append(f"{layer}: groups must be an array of objects")
+        groups = []
+    group_ids = {str(item.get("id") or "") for item in groups}
+    question_positions = {question_id: index for index, question_id in enumerate(question_ids)}
+    for index, question in enumerate(questions):
+        question_id = str(question.get("id") or "")
+        if question.get("group") not in group_ids:
+            errors.append(
+                f"{layer}: question {question_id!r} references unknown group "
+                f"{question.get('group')!r}"
+            )
+        varying_parent = question.get("options_vary_by")
+        if varying_parent is not None:
+            if not isinstance(varying_parent, str) or varying_parent not in question_positions:
+                errors.append(
+                    f"{layer}: question {question_id} options_vary_by references "
+                    f"unknown question {varying_parent!r}"
+                )
+            elif question_positions[varying_parent] >= index:
+                errors.append(
+                    f"{layer}: question {question_id} options_vary_by must reference "
+                    "an earlier question"
+                )
+        for field in CONDITION_FIELDS:
+            condition = question.get(field)
+            if condition is None:
+                continue
+            if not isinstance(condition, str):
+                errors.append(f"{layer}: question {question_id} {field} must be a string")
+                continue
+            match = CONDITION_RE.fullmatch(condition)
+            if match is None:
+                errors.append(
+                    f"{layer}: question {question_id} {field} has invalid option-ID "
+                    f"condition syntax: {condition!r}"
+                )
+                continue
+            referenced_question = match.group(1) or match.group(2)
+            if referenced_question not in question_positions:
+                errors.append(
+                    f"{layer}: question {question_id} {field} references unknown "
+                    f"question {referenced_question}"
+                )
+            elif question_positions[referenced_question] >= index:
+                errors.append(
+                    f"{layer}: question {question_id} {field} must reference an earlier question"
+                )
+
+    bank_text = required_files["bank"].read_text(encoding="utf-8")
+    bank_question_ids = QUESTION_HEADING_RE.findall(bank_text)
+    if question_ids != bank_question_ids:
+        errors.append(
+            f"{layer}: question bank/manifest drift; manifest={question_ids}, "
+            f"question_bank={bank_question_ids}"
+        )
+
+    fallback_questions = _as_string_list(
+        render_contract.get("semantic_fallback_questions"),
+        f"{layer}: render_contract.semantic_fallback_questions",
+        errors,
+    )
+    if fallback_questions != question_ids:
+        errors.append(
+            f"{layer}: semantic_fallback_questions must match manifest question order; "
+            f"got {fallback_questions}"
+        )
+
+    placeholders = manifest.get("template_placeholders")
+    if not isinstance(placeholders, dict):
+        errors.append(f"{layer}: template_placeholders must be an object")
+        placeholders = {}
+    declared: set[str] = set()
+    for category in ("from_questions", "from_fixed_rules", "auto_generated", "metadata"):
+        values = _as_string_list(
+            placeholders.get(category),
+            f"{layer}: template_placeholders.{category}",
+            errors,
+        )
+        overlap = declared.intersection(values)
+        if overlap:
+            errors.append(
+                f"{layer}: placeholders declared in multiple categories: {sorted(overlap)}"
+            )
+        declared.update(values)
+
+    template_text = required_files["template"].read_text(encoding="utf-8")
+    actual = set(PLACEHOLDER_RE.findall(template_text))
+    undeclared = sorted(actual - declared)
+    unused = sorted(declared - actual)
+    if undeclared:
+        errors.append(f"{layer}: template has undeclared placeholders: {undeclared}")
+    if unused:
+        errors.append(f"{layer}: manifest declares unused placeholders: {unused}")
+    if "Generated by app-planner Rules Configuration" not in template_text:
+        errors.append(f"{layer}: template must identify app-planner Rules Configuration as owner")
+    if ".claude/skills/" in template_text:
+        errors.append(f"{layer}: template contains a platform-specific source pointer")
+    if re.search(r"generated by the `(?:frontend|backend|database|mobile)-rules` skill", template_text, re.I):
+        errors.append(f"{layer}: template references a retired independent layer-rules skill")
+
+    fixed_text = required_files["fixed"].read_text(encoding="utf-8")
+    if "POLICY_CLASS: invariant" not in fixed_text:
+        errors.append(f"{layer}: fixed-rules.md must declare POLICY_CLASS: invariant")
+    if "Selected-decision boundary" not in fixed_text:
+        errors.append(f"{layer}: fixed-rules.md must state the selected-decision boundary")
+    normalized_fixed_text = " ".join(fixed_text.lower().split())
+    for forbidden_pattern in FIXED_RULE_FORBIDDEN_PATTERNS:
+        if forbidden_pattern in normalized_fixed_text:
+            errors.append(
+                f"{layer}: fixed-rules.md contains decision-owned policy: "
+                f"{forbidden_pattern!r}"
+            )
+    for placeholder in placeholders.get("from_fixed_rules", []):
+        if f"{{{{ {placeholder} }}}}" not in fixed_text:
+            errors.append(
+                f"{layer}: fixed-rules.md has no injection mapping for {{{{ {placeholder} }}}}"
+            )
+
+    derivation_text = required_files["derivation"].read_text(encoding="utf-8")
+    if "SEMANTIC_FALLBACK_POLICY" not in derivation_text:
+        errors.append(f"{layer}: derivation-rules.md must define SEMANTIC_FALLBACK_POLICY")
+
+    multi_profile = manifest.get("multi_profile_contract")
+    if layer == "mobile":
+        expected_multi_profile = {
+            "when": "Q1 == E",
+            "dimensions": ["Q4", "Q6", "Q7", "Q8", "Q13", "Q14"],
+            "profiles": ["ios", "android"],
+            "output_placeholder": "platform_profiles",
+        }
+        if multi_profile != expected_multi_profile:
+            errors.append("mobile: multi_profile_contract does not match the dual-native contract")
+        if "platform_profiles" not in placeholders.get("auto_generated", []):
+            errors.append("mobile: platform_profiles must be an auto-generated placeholder")
+    elif multi_profile is not None:
+        errors.append(f"{layer}: multi_profile_contract is only valid for mobile")
+
+
+def validate_rules_root(rules_root: Path) -> dict[str, object]:
+    errors: list[str] = []
+    if not rules_root.is_dir():
+        errors.append(f"rules root does not exist: {rules_root}")
+    else:
+        actual_layers = sorted(path.name for path in rules_root.iterdir() if path.is_dir())
+        unexpected = sorted(set(actual_layers) - set(LAYERS))
+        missing = sorted(set(LAYERS) - set(actual_layers))
+        if unexpected:
+            errors.append(f"unexpected rules layers: {unexpected}")
+        if missing:
+            errors.append(f"missing rules layers: {missing}")
+        for layer in LAYERS:
+            if (rules_root / layer).is_dir():
+                _validate_layer(rules_root, layer, errors)
+    return {
+        "valid": not errors,
+        "layers": list(LAYERS),
+        "errors": errors,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate app-planner Rules Configuration manifests and rendering resources."
+    )
+    parser.add_argument(
+        "--rules-root",
+        type=Path,
+        default=Path(__file__).resolve().parent.parent / "references" / "rules",
+        help="Path containing frontend/backend/database/mobile rules resources.",
+    )
+    args = parser.parse_args()
+    report = validate_rules_root(args.rules_root.expanduser().resolve())
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report["valid"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled/skills/prizmkit/SKILL.md

@@ -57,7 +57,7 @@ prizmkit-plan
   → prizmkit-committer
 ```
 
-The lifecycle starts at `/prizmkit-plan`. For a one-entry experience, invoke `/prizmkit-workflow` with the requirement; it coordinates the same stages without replacing their responsibilities. When the host supports skill-to-skill handoff, the stages continue automatically. Otherwise, each stage writes the next semantic skill and the workflow state provides the deterministic resume context.
+For a one-entry experience, invoke `/prizmkit-workflow`; it owns ordering, state, repair routing, and stage invocation without replacing stage responsibilities. Atomic Skills receive explicit stage-local input, return stage-local results, and never read or write the coordinator's state. External injected Prompts may provide the same orchestration around atomic Skills.
 
 All six stages are required for a formal requirement. A stage may choose a verification depth appropriate to the change, but it may not be silently skipped.
 
@@ -67,14 +67,14 @@ Typos, pure formatting, small documentation edits, and other explicitly low-risk
 
 ### Stage Responsibilities
 
-| Stage | Responsibility | Success handoff |
+| Stage | Responsibility | Stage-local success |
 |---|---|---|
-| `prizmkit-plan` | Clarify the requirement and create/review `spec.md` and `plan.md`. | `status=completed`, `stage_result=PLAN_READY` → `prizmkit-implement` |
-| `prizmkit-implement` | Execute the plan tasks and record completion. | `status=completed`, `stage_result=IMPLEMENTED` → `prizmkit-code-review` |
-| `prizmkit-code-review` | Main Agent reviews, repairs, verifies, and loops until convergence. | `status=completed`, `stage_result=REVIEW_PASS` → `prizmkit-test` |
-| `prizmkit-test` | Validate the final reviewed workspace with project-native tests and a consistent terminal report/result pair. | `status=completed`, `stage_result=TEST_PASS` → `prizmkit-retrospective` |
-| `prizmkit-retrospective` | Synchronize durable project documentation or record no documentation change. | `status=completed`, `stage_result=RETRO_COMPLETE` → `prizmkit-committer` |
-| `prizmkit-committer` | Verify gates, request commit confirmation, and create the local commit. | `status=completed`, `stage_result=COMMITTED` |
+| `prizmkit-plan` | Clarify the requirement and create/review `spec.md` and `plan.md`. | `PLAN_READY` |
+| `prizmkit-implement` | Execute supplied plan tasks and record completion. | `IMPLEMENTED` |
+| `prizmkit-code-review` | Review, repair, verify, and converge on the supplied change. | `PASS` |
+| `prizmkit-test` | Test the supplied change with a consistent report/result pair. | `TEST_PASS` |
+| `prizmkit-retrospective` | Synchronize durable documentation or record no change. | `RETRO_COMPLETE` |
+| `prizmkit-committer` | Create a confirmed interactive commit or prepare an exact Runtime request. | `COMMITTED` or `COMMIT_REQUEST_READY` |
 
 ### `prizmkit-workflow`
 
@@ -86,9 +86,8 @@ Use for a one-entry formal requirement workflow. It coordinates all six lifecycl
 
 Initialization is a soft prerequisite, not a hard dependency:
 
-- If project initialization is missing, `/prizmkit-plan` recommends `/prizmkit-init`.
-- The user may continue without initialization.
-- Planning then reads the source tree, README, manifests, and available project rules as fallback context.
+- If project initialization is missing, the user may still invoke `/prizmkit-init` separately or continue without it.
+- Planning reads the source tree, README, manifests, and available project rules as fallback context.
 - Later documentation synchronization reports when the Prizm documentation system is not initialized instead of pretending that synchronization completed.
 
 ## Independent Skills
@@ -110,7 +109,7 @@ REVIEW_NEEDS_FIXES
 
 TEST_NEEDS_FIXES
   → preserve test-report.md and test-result.json
-  → stop with the known correction or delta-review requirement
+  → stop with the known correction
   → caller owns any later review/retest route
 
 TEST_BLOCKED
@@ -122,7 +121,7 @@ Automatic outer repair is limited to three rounds. The workflow stops with a res
 
 ## Commit and Deployment Boundary
 
-`prizmkit-committer` must not create a commit until the preceding five formal stages have succeeded. Before creating the local commit, it presents the intended files, diff summary, and Conventional Commit message and waits for user confirmation.
+The active coordinator validates all required evidence before invoking `prizmkit-committer` with exact `evidence_paths` and any caller-state `excluded_paths`. Interactive use confirms and creates a local commit. Preparation use returns `COMMIT_REQUEST_READY` without Git mutation; the injected Prompt records its pending state and Python Runtime executes the request.
 
 Pushing to a remote is a separate explicit action. Deployment is always a separate invocation of `/prizmkit-deploy`.
 
@@ -131,10 +130,10 @@ Pushing to a remote is a separate explicit action. Deployment is always a separa
 An active requirement may use:
 
 ```text
-.prizmkit/state/workflows/<requirement-slug>.json
+.prizmkit/state/workflows/<requirement-identity>.json
 ```
 
-This runtime state records the current stage, terminal status, repair scope, repair round, and resume entry. The skill set does not prescribe whether the target project commits, ignores, or shares this file.
+`<requirement-identity>` is the validated exact basename of the active artifact directory. An existing state file that records a different artifact directory is a blocking collision and is never silently overwritten or suffixed. This coordinator-owned state records current stage, terminal status, repair scope, repair round, and resume entry. Atomic Skills do not read or write it. The target project controls whether the file is committed, ignored, or shared.
 
 Read `${SKILL_DIR}/references/workflow-state-protocol.md` for the state protocol. If the state file is missing or stale, use `spec.md`, `plan.md`, the review report, `test-report.md`, and `test-result.json` to reconstruct the safest recoverable stage and report that reconstruction.
 
@@ -152,19 +151,19 @@ Then:
 1. Optionally run /prizmkit-init when entering a project for the first time.
 2. Start a formal requirement with /prizmkit-plan.
 3. Continue through implement → code-review → test → retrospective → committer.
-4. Confirm the local commit when /prizmkit-committer presents it.
+4. For interactive use, confirm the local commit when `/prizmkit-committer operation=interactive-commit` presents it; pipeline runtimes use preparation mode and execute Git themselves.
 5. Invoke /prizmkit-deploy separately when deployment or operations work is needed.
 ```
 
 ## Scope Boundary
 
-This toolkit is self-contained: its skills describe only this toolkit's lifecycle and independent entry points. External systems may integrate through the published skill inputs, outputs, state, and authorization contracts, but their internal architecture and names are outside this toolkit's protocol.
+This toolkit is self-contained. External coordinators integrate through atomic stage inputs, stage-owned artifacts, and domain results; coordinator state and routing remain outside atomic Skill contracts.
 
 The toolkit does not promise universal automatic handoff, universal deployment automation, automatic remote push, or access beyond the host platform's permissions and environment.
 
 If the user says only "ship it", ask whether they mean:
 
-1. Commit the current changes with `/prizmkit-committer`.
+1. Use `/prizmkit-committer operation=interactive-commit` for a user-confirmed local commit, or preparation mode when a Python pipeline runtime owns Git execution.
 2. Deploy or operate the project with `/prizmkit-deploy`.
 
 Do not route an ambiguous "ship it" directly to either action.

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

@@ -4,11 +4,13 @@
 
 ## Location and Identity
 
+The state filename uses the validated exact basename of `artifact_dir` without a second slug transformation:
+
 ```text
-.prizmkit/state/workflows/<requirement-slug>.json
+.prizmkit/state/workflows/<requirement-identity>.json
 ```
 
-The active `artifact_dir` is preserved exactly across every stage:
+An existing state path whose recorded `artifact_dir` differs from the active artifact is a blocking collision; never overwrite, merge, or suffix it automatically. The active `artifact_dir` is preserved exactly across every stage:
 
 ```text
 .prizmkit/specs/<requirement-slug>/
@@ -31,7 +33,7 @@ The state file is an index, not the authority for stage completion:
 | Terminal testing result | `{artifact_dir}/test-result.json` |
 | Retrospective completion | `{artifact_dir}/retrospective-result.json` |
 | Durable architecture knowledge | `.prizmkit/prizm-docs/` |
-| Local commit | Git history and confirmed or authorized commit identity |
+| Local commit | Git history and runtime- or user-verified commit identity |
 | Current stage, orchestrator, and resume entry | Workflow state |
 | External orchestration progress | External host checkpoint |
 
@@ -64,7 +66,7 @@ Every consumer compares workflow state with the skill-owned artifacts and curren
 | `orchestrator` | Semantic coordinator identifier, or null for direct stage use. |
 | `stage` | Stage that most recently wrote state. |
 | `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`. |
+| `stage_result` | Coordinator-recorded lifecycle result mapped from a validated atomic result and its required artifacts, 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. |
@@ -97,10 +99,10 @@ review-report NEEDS_FIXES        → status=failed,     stage_result=REVIEW_NEED
 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
+retrospective outcome=RETRO_COMPLETE, result=DOCS_UPDATED   → status=completed, stage_result=RETRO_COMPLETE
+retrospective outcome=RETRO_COMPLETE, result=NO_DOC_CHANGE  → status=completed, stage_result=RETRO_COMPLETE
+retrospective outcome=RETRO_BLOCKED                         → status=failed,    stage_result=RETRO_BLOCKED
+runtime commit preparation       → status=in_progress, stage_result=COMMIT_PENDING
 local commit confirmed           → status=completed,  stage_result=COMMITTED
 commit blocked                   → status=failed,     stage_result=COMMIT_BLOCKED
 ```
@@ -115,8 +117,8 @@ commit blocked                   → status=failed,     stage_result=COMMIT_BLOC
 
 ```text
 TEST_NEEDS_FIXES
-→ known correction or required delta review remains
-→ caller decides whether and how to arrange another stage
+→ a known correction remains
+→ caller decides whether and how to arrange another invocation
 
 TEST_BLOCKED
 → truth, input, safe environment, or reliable execution prevents a verdict
@@ -132,30 +134,32 @@ Any outer repair or continuation policy is independently owned by the caller and
 
 1. An atomic stage performs only its own stage, writes its truthful result and artifact paths, and returns control.
 2. When `orchestrator` is non-null, only that orchestrator invokes the next skill.
-3. Direct stage use may report a possible next invocation but does not claim it ran.
+3. Direct atomic use returns only its local result and artifacts; it does not report or select another invocation.
 4. Every handoff preserves the same `artifact_dir`.
 5. External automation invokes atomic stages directly and does not nest the composite workflow.
 6. Workflow state never replaces or absorbs an external host checkpoint.
 
-## Commit Authorization
+## Commit Execution Ownership
 
 Interactive execution:
 
 ```text
 committer previews intended files and message
 → waits for explicit current-user confirmation
-→ creates the local commit
+→ stages, creates, and verifies the local commit
 ```
 
-Trusted headless execution:
+Pipeline execution:
 
 ```text
-trusted host explicitly authorizes the current local task commit
-→ committer verifies gates and commits automatically
+external coordinator validates its required gates and supplies exact readiness evidence
+→ committer validates only that evidence and writes an exact runtime-commit-request.json
+→ external coordinator maps COMMIT_REQUEST_READY to its checkpoint's in_progress/COMMIT_PENDING state
+→ Python runtime validates the request, commits, verifies Git, and writes checkpoint completed/COMMITTED
 → remote publication remains separate
 ```
 
-A self-declared or untrusted headless context does not authorize a commit.
+The preparation request is data for runtime validation, not prompt-level authorization. The committer must not stage, commit, or predeclare COMMITTED in pipeline preparation mode.
 
 ## Recovery
 
@@ -171,4 +175,4 @@ When state is missing, stale, or inconsistent:
 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 checkpoint enforcement.
+Stale state never bypasses review, testing, retrospective, commit preparation/execution, or external checkpoint enforcement.

package/bundled/skills/prizmkit-code-review/SKILL.md

@@ -1,49 +1,47 @@
 ---
 name: "prizmkit-code-review"
-description: "Review the complete current change for a formal PrizmKit requirement with a mandatory bounded Main-Agent loop and optional capability-gated independent correctness review. Directly repair accepted corrections, verify repairs, converge to PASS or stop with NEEDS_FIXES, and hand off to prizmkit-test. (project)"
+description: "Review one supplied complete change with a bounded Main-Agent review/repair loop and optional capability-gated independent correctness review. Produces review-report.md and returns PASS or NEEDS_FIXES. (project)"
 ---
 
 # PrizmKit Code Review
 
-`/prizmkit-code-review` is the mandatory review stage after implementation and before the full test stage. The current Main Agent owns the complete baseline review loop: it discovers findings, adjudicates them, directly repairs accepted findings, verifies repairs, and continues until the review converges or stops safely. After convergence, one strictly capability-gated independent Reviewer may objectively check the complete current implementation without taking mutation or final-decision authority.
+`/prizmkit-code-review` reviews one caller-supplied complete change. The current Main Agent owns the complete baseline review loop: it discovers findings, adjudicates them, directly repairs accepted findings, verifies repairs, and continues until the review converges or stops safely. After convergence, one strictly capability-gated independent Reviewer may objectively check the complete current implementation without taking mutation or final-decision authority.
 
 ## Execution Boundary
 
 - Main-Agent review remains mandatory and must not be delegated directly or indirectly.
 - After Main-Agent convergence only, this skill may create the single independent Reviewer defined by `${SKILL_DIR}/references/independent-code-review.md` when every structural capability in that reference is proven.
-- Do not invoke another review skill or review workflow from inside this skill.
+- Do not invoke another review process from inside this skill.
 - Do not launch any additional review work through a general-purpose execution unit or relabel it as a finder, verifier, audit, compatibility review, verification, or gap sweep.
 - The independent Reviewer cannot mutate, execute arbitrary commands, or create downstream execution units; prompt instructions never substitute for these structural guarantees.
 - The Main Agent may directly read, search, edit, and run targeted verification in the active workspace.
-- Review repairs occur before the full `/prizmkit-test` stage so project-native tests run against the final reviewed workspace.
+- Review repairs use targeted verification appropriate to each accepted finding.
 - `{artifact_dir}/review-report.md` is the only persisted review artifact for this execution.
 
 ## Atomic Stage Boundary
 
-`prizmkit-code-review` owns the complete mandatory Main-Agent review, the optional independent correctness review, accepted-correction repairs, and review verification. It writes its truthful terminal result and `next_stage`, then returns control. It must not invoke `prizmkit-test` or `prizmkit-implement` itself; the active orchestrator owns outer repair routing and the next-stage invocation.
+`prizmkit-code-review` owns the complete review, accepted-correction repairs, targeted verification, and `review-report.md` for one supplied change. It returns `PASS` or `NEEDS_FIXES` and stops.
 
 ## When to Use
 
-- After `/prizmkit-implement` reports `IMPLEMENTED`.
-- After implementation repairs that changed production code, runtime configuration, schema, dependencies, or public interfaces.
-- When a caller routes a high-risk production repair reported by `prizmkit-test` back for delta review.
-- When the user asks for a complete review or commit readiness decision.
+- A caller supplies a complete implementation for review.
+- A caller supplies a production-affecting repair for delta review.
+- The user asks for a complete current-change correctness review.
 
 ## When NOT to Use
 
 - No valid `spec.md` and `plan.md` exist for the active requirement.
 - Implementation tasks or required repair work remain incomplete.
-- A test-stage environment stop is caused by availability rather than a review concern; resume from test when the environment is available.
-- The request is a direct low-risk edit outside the formal requirement lifecycle.
+- The request has no review input and does not require this bounded review contract.
 
-## Input and State
+## Input
 
 | Parameter | Required | Description |
 |---|---|---|
-| `artifact_dir` | No | Directory containing `spec.md` and `plan.md`. Reuse the caller's directory or workflow-state value. |
+| `artifact_dir` | Yes | Caller-supplied directory containing the exact `spec.md` and `plan.md` for this review. |
 | `review_scope` | No | `full` for the initial review; `delta` for a production-affecting repair after a prior review pass. |
 
-Every invocation must reuse the same `artifact_dir`. If workflow state is missing, reconstruct it from `spec.md`, `plan.md`, `review-report.md`, the current diff, and any current test report/result pair, and report the reconstruction.
+Review only the caller-supplied `artifact_dir`; never discover a different recent artifact. Missing or inconsistent stage input produces `NEEDS_FIXES` with the exact input blocker.
 
 ## Phase 0: Initialize Report and Reuse Current Context
 
@@ -51,7 +49,7 @@ Every invocation must reuse the same `artifact_dir`. If workflow state is missin
 2. At the start of each execution, replace any prior report with a new execution header using `${SKILL_DIR}/references/review-report-template.md`.
 3. Within that execution, append progress after every review round, repair batch, final verification, and exactly one `## Final Result`.
 4. Start from the Main Agent's current requirement context and inspect the complete workspace change first: `git status --short`, the staged diff, and the unstaged diff. Include untracked, deleted, and renamed files in the review scope.
-5. Do not reread `spec.md`, `plan.md`, project rules, progressive docs, or unchanged source merely to recreate context the Main Agent already holds. Load only the missing or potentially stale material required to resolve a concrete ambiguity, verify an acceptance criterion, understand a changed contract, or reconstruct missing workflow state.
+5. Reuse current context and load only missing or potentially stale material required to resolve a concrete ambiguity, verify an acceptance criterion, or understand a changed contract.
 6. Inspect unchanged callers, dependents, contracts, or tests only when the diff changes or may violate an interface, shared behavior, or regression boundary. Do not perform an unconditional repository-wide dependency sweep.
 7. For `review_scope=delta`, focus on files and behavior affected since the prior review pass and expand only across contracts implicated by that delta.
 8. If no changes exist, record final verification and `PASS` only when the current requirement context and prior implementation state prove there is nothing left to review.
@@ -109,7 +107,7 @@ For accepted findings while the round limit remains:
 3. Inspect the complete resulting diff for unrelated changes and regressions.
 4. Append repair verification and continue the review loop.
 
-Do not run the full auditable testing protocol as a substitute for this review stage. The full testing stage follows only after review `PASS`.
+Do not turn review verification into a broad unrelated test campaign; use targeted checks that establish each repair.
 
 If a repair is unsafe, incomplete, or unverifiable, record an unresolved finding and finish with `NEEDS_FIXES`.
 
@@ -141,49 +139,15 @@ Valid results:
 PASS | NEEDS_FIXES
 ```
 
-`PASS` requires review convergence, no unresolved findings, and credible targeted verification. `NEEDS_FIXES` means an outer implementation repair is required or completion must stop safely.
+`PASS` requires review convergence, no unresolved findings, and credible targeted verification. `NEEDS_FIXES` means a concrete correction remains or safe completion was not established.
 
-## Workflow State and Outer Repair Routing
+## Output
 
-Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
+Return only review-stage outputs:
 
-On `PASS`, update workflow state:
+- `artifact_dir` and `review-report.md` path;
+- `PASS` when review converged with all accepted findings repaired;
+- `NEEDS_FIXES` when accepted or unresolved findings remain;
+- finding counts, repair verification, and concrete remaining findings.
 
-```json
-{
-  "stage": "code-review",
-  "status": "completed",
-  "stage_result": "REVIEW_PASS",
-  "completed_stages": ["plan", "implement", "code-review"],
-  "next_stage": "test",
-  "resume_from": "prizmkit-test"
-}
-```
-
-On `NEEDS_FIXES` caused by code findings, update workflow state:
-
-```json
-{
-  "stage": "code-review",
-  "status": "failed",
-  "stage_result": "REVIEW_NEEDS_FIXES",
-  "repair_scope": "production",
-  "next_stage": "implement",
-  "resume_from": "prizmkit-implement"
-}
-```
-
-Increment the outer `repair_round` only when returning to implementation; the review-internal ten-round loop never increments it. The outer workflow permits at most three repair rounds and must return a truthful unresolved `NEEDS_FIXES` result instead of beginning a fourth.
-
-## Handoff
-
-After `PASS`:
-
-```text
-REVIEW_PASS
-  → /prizmkit-test
-```
-
-If workflow state names an active `orchestrator`, return `REVIEW_PASS`, the report/state paths, and `next_stage=test` to it; do not invoke test independently. For direct stage use, report the exact `/prizmkit-test` invocation and same `artifact_dir`; a host may perform that semantic handoff on the user's behalf.
-
-After `NEEDS_FIXES`, stop and hand off to `/prizmkit-implement`; do not test or commit the unrepaired production change.
+Return only the listed review outputs. Do not invoke another Skill.