prizmkit 1.1.153 → 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/bug-planner/references/schema-validation.md

@@ -17,7 +17,7 @@ Use this checklist for manual validation when `validate-bug-list.py` is not avai
 - [ ] `error_source.type`: one of `stack_trace`, `user_report`, `failed_test`, `log_pattern`, `monitoring_alert`
 - [ ] `verification_type`: one of `automated`, `manual`, `hybrid`
 - [ ] `acceptance_criteria`: non-empty array of strings
-- [ ] `status`: one of `pending`, `in_progress`, `completed`, `failed`, `skipped`, `needs_info`; new bugs should start as `pending`
+- [ ] `status`: one of `pending`, `in_progress`, `completed`, `failed`, `skipped`, `needs_info`, `auto_skipped`; new bugs should start as `pending`, while `auto_skipped` is runtime-managed for blocked descendants
 - [ ] `dependencies` if present: array of existing `B-NNN` IDs; no self-dependencies
 
 ## Consistency Checks

package/bundled/skills/bug-planner/scripts/validate-bug-list.py

@@ -29,7 +29,7 @@ from datetime import datetime, timezone
 VALID_SEVERITIES = {"critical", "high", "medium", "low"}
 VALID_SOURCE_TYPES = {"stack_trace", "user_report", "failed_test", "log_pattern", "monitoring_alert"}
 VALID_VERIFICATION_TYPES = {"automated", "manual", "hybrid"}
-VALID_STATUSES = {"pending", "in_progress", "completed", "failed", "skipped", "needs_info"}
+VALID_STATUSES = {"pending", "in_progress", "completed", "failed", "skipped", "needs_info", "auto_skipped"}
 BUG_ID_PATTERN = re.compile(r"^B-\d{3}$")
 SCHEMA_VERSION = "dev-pipeline-bug-fix-list-v1"
 

package/bundled/skills/bugfix-pipeline-launcher/SKILL.md

@@ -67,7 +67,7 @@ Only the start intent uses the execution-mode and configuration rounds.
 
 Use one `AskUserQuestion` call with exactly one question:
 
-- **Foreground (Recommended)** — build `bugfix run`; output remains attached to the user's terminal.
+- **Foreground (Recommended)** — build `run bugfix`; output remains attached to the user's terminal.
 - **Background daemon** — build `daemon bugfix start`; the runtime manages detached execution and logs.
 
 Wait for the response before asking configuration.
@@ -100,7 +100,7 @@ Foreground template:
 
 ```bash
 VERBOSE=1 MAX_RETRIES=3 \
-  python3 ./.prizmkit/dev-pipeline/cli.py bugfix run .prizmkit/plans/bug-fix-list.json
+  python3 ./.prizmkit/dev-pipeline/cli.py run bugfix .prizmkit/plans/bug-fix-list.json
 ```
 
 Background template:
@@ -118,7 +118,7 @@ Return:
 
 ```bash
 python3 ./.prizmkit/dev-pipeline/cli.py daemon bugfix status
-python3 ./.prizmkit/dev-pipeline/cli.py bugfix status .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py status bugfix .prizmkit/plans/bug-fix-list.json
 ```
 
 Do not infer completion from the plan file alone when runtime state may exist.
@@ -151,39 +151,47 @@ Optionally include the daemon status command for the user to run afterward. Do n
 
 ## Retry Command
 
-Reset changes state only; it never starts execution and rejects `--run`. Always return reset and run as separate commands.
+Reset never starts execution and rejects `--run`. Every reset command must select exactly one mode: `--state-only`, `--fresh-checkout`, `--clean`, or `--preserve-runtime`. Always return reset and run as separate commands.
 
-A standard reset can discard uncommitted changes when the target task branch is currently checked out and records a fresh-checkout boundary. Clean reset additionally deletes the task branch and clears task history/artifacts. Preserve-runtime failed recovery instead scans the whole selected list, restores every failed root and its causal `auto_skipped` descendants, and retains valid checkout identity, sessions, checkpoints, artifacts, branches, worktrees, and WIP. If a recorded branch is missing, it creates a replacement from the recorded base, retains old artifacts for reference, and rewinds implementation-and-later checkpoint stages. Never hide these effects behind the word “retry.”
+State-only recovery resets selected failed/skipped/needs-info roots and only causal `auto_skipped` descendants whose complete blocker set is recovered. It resets retry/session/continuation state but never changes checkout identity, branches, worktrees, source changes, checkpoints, or artifact files. Selecting an auto-skipped bug includes all of its transitive blocking roots; `--all` recovers all eligible chains. Fresh-checkout performs the former standard reset, can discard uncommitted changes on the active task branch, and records a new checkout boundary. Clean additionally deletes the task branch and clears task history/artifacts. Preserve-runtime scans the whole list for failed roots, retains runtime history and valid checkout/WIP, and alone may replace a missing branch from the recorded base and rewind implementation-and-later checkpoints. Never hide these effects behind the word “retry.”
 
 Use `AskUserQuestion` before constructing retry commands:
 
-- **Preserve failed runtime (Recommended for continuing failed work)** — recover all failed chains in the selected list without cleanup, then run the list; disclose that this is whole-list recovery rather than a single-ID reset.
-- **Standard fresh retry** — reset one bug, then run that bug separately; warn that the active task branch can lose uncommitted changes.
+- **State-only causal recovery** — recover one bug closure, or all closures with `--all`, while preserving Git/checkouts/checkpoints/artifact files.
+- **Preserve failed runtime (Recommended for continuing failed work)** — recover all failed chains without cleanup while retaining history and continuation evidence; disclose that this is whole-list failed-only recovery.
+- **Fresh-checkout retry** — reset one bug, then run it separately; warn that the active task branch can lose uncommitted changes.
 - **Clean retry** — reset one bug, delete its task branch/history/artifacts, then run it separately.
 - **Cancel** — return no reset or run command.
 
+State-only template:
+
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix B-001 --state-only .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py run bugfix B-001 .prizmkit/plans/bug-fix-list.json
+```
+
 Preserve-runtime template:
 
 ```bash
 python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix --failed --preserve-runtime .prizmkit/plans/bug-fix-list.json
-python3 ./.prizmkit/dev-pipeline/cli.py bugfix run .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py run bugfix .prizmkit/plans/bug-fix-list.json
 ```
 
-Standard template:
+Fresh-checkout template:
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix B-001 .prizmkit/plans/bug-fix-list.json
-python3 ./.prizmkit/dev-pipeline/cli.py bugfix run B-001 .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix B-001 --fresh-checkout .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py run bugfix B-001 .prizmkit/plans/bug-fix-list.json
 ```
 
 Clean template:
 
 ```bash
 python3 ./.prizmkit/dev-pipeline/cli.py reset bugfix B-001 --clean .prizmkit/plans/bug-fix-list.json
-python3 ./.prizmkit/dev-pipeline/cli.py bugfix run B-001 .prizmkit/plans/bug-fix-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py run bugfix B-001 .prizmkit/plans/bug-fix-list.json
 ```
 
-`--preserve-runtime` requires `--failed` and cannot be combined with `--clean`, an ID, a range, or another reset filter. Retry-budget flags such as `--max-retries` and `--max-infra-retries` belong on the run command, never reset. For clean retry, require explicit acknowledgement of branch deletion and possible uncommitted-change loss before displaying either command.
+State-only requires exactly one ID or explicit `--all` and rejects ranges/status filters. Fresh-checkout and clean accept one ID, range, or supported status filter. Preserve-runtime requires `--failed`, scans the whole list, and rejects IDs, ranges, `--all`, clean, other modes, and other filters. Retry-budget flags belong on the run command, never reset. For fresh-checkout or clean retry, require explicit acknowledgement of possible uncommitted-change loss; clean additionally requires acknowledgement of branch/history/artifact deletion.
 
 ## Output Contract
 

package/bundled/skills/feature-pipeline-launcher/SKILL.md

@@ -71,7 +71,7 @@ Only the start intent uses the execution-mode and configuration rounds.
 
 Use one `AskUserQuestion` call with exactly one question:
 
-- **Foreground (Recommended)** — build `feature run`; output remains attached to the user's terminal.
+- **Foreground (Recommended)** — build `run feature`; output remains attached to the user's terminal.
 - **Background daemon** — build `daemon feature start`; the runtime manages detached execution and logs.
 
 Wait for the response before asking configuration.
@@ -104,14 +104,14 @@ Foreground template:
 
 ```bash
 VERBOSE=1 MAX_RETRIES=3 \
-  python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
+  python3 ./.prizmkit/dev-pipeline/cli.py run feature .prizmkit/plans/feature-list.json
 ```
 
 Foreground subset template:
 
 ```bash
 VERBOSE=1 MAX_RETRIES=3 \
-  python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json --features F-001:F-005
+  python3 ./.prizmkit/dev-pipeline/cli.py run feature .prizmkit/plans/feature-list.json --features F-001:F-005
 ```
 
 Background template:
@@ -136,7 +136,7 @@ Return both commands when the user asks for overall status:
 
 ```bash
 python3 ./.prizmkit/dev-pipeline/cli.py daemon feature status
-python3 ./.prizmkit/dev-pipeline/cli.py feature status .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py status feature .prizmkit/plans/feature-list.json
 ```
 
 Do not infer completion from the plan file alone when runtime state may exist.
@@ -169,39 +169,47 @@ Optionally include the daemon status command for the user to run afterward. Do n
 
 ## Retry Command
 
-Reset changes state only; it never starts execution and rejects `--run`. Always return reset and run as separate commands.
+Reset never starts execution and rejects `--run`. Every reset command must select exactly one mode: `--state-only`, `--fresh-checkout`, `--clean`, or `--preserve-runtime`. Always return reset and run as separate commands.
 
-A standard reset can discard uncommitted changes when the target task branch is currently checked out and records a fresh-checkout boundary. Clean reset additionally deletes the task branch and clears task history/artifacts. Preserve-runtime failed recovery instead scans the whole selected list, restores every failed root and its causal `auto_skipped` descendants, and retains valid checkout identity, sessions, checkpoints, artifacts, branches, worktrees, and WIP. If a recorded branch is missing, it creates a replacement from the recorded base, retains old artifacts for reference, and rewinds implementation-and-later checkpoint stages. Never hide these effects behind the word “retry.”
+State-only recovery resets selected failed/skipped roots and only causal `auto_skipped` descendants whose complete blocker set is recovered. It resets retry/session/continuation state but never changes checkout identity, branches, worktrees, source changes, checkpoints, or artifact files. Selecting an auto-skipped feature includes all of its transitive blocking roots; `--all` recovers all eligible chains. Fresh-checkout performs the former standard reset, can discard uncommitted changes on the active task branch, and records a new checkout boundary. Clean additionally deletes the task branch and clears task history/artifacts. Preserve-runtime scans the whole list for failed roots, retains runtime history and valid checkout/WIP, and alone may replace a missing branch from the recorded base and rewind implementation-and-later checkpoints. Never hide these effects behind the word “retry.”
 
 Use `AskUserQuestion` before constructing retry commands:
 
-- **Preserve failed runtime (Recommended for continuing failed work)** — recover all failed chains in the selected list without cleanup, then run the list; disclose that this is whole-list recovery rather than a single-ID reset.
-- **Standard fresh retry** — reset one feature, then run that feature separately; warn that the active task branch can lose uncommitted changes.
+- **State-only causal recovery** — recover one feature closure, or all closures with `--all`, while preserving Git/checkouts/checkpoints/artifact files.
+- **Preserve failed runtime (Recommended for continuing failed work)** — recover all failed chains without cleanup while retaining history and continuation evidence; disclose that this is whole-list failed-only recovery.
+- **Fresh-checkout retry** — reset one feature, then run it separately; warn that the active task branch can lose uncommitted changes.
 - **Clean retry** — reset one feature, delete its task branch/history/artifacts, then run it separately.
 - **Cancel** — return no reset or run command.
 
+State-only template:
+
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-001 --state-only .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py run feature F-001 .prizmkit/plans/feature-list.json
+```
+
 Preserve-runtime template:
 
 ```bash
 python3 ./.prizmkit/dev-pipeline/cli.py reset feature --failed --preserve-runtime .prizmkit/plans/feature-list.json
-python3 ./.prizmkit/dev-pipeline/cli.py feature run .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py run feature .prizmkit/plans/feature-list.json
 ```
 
-Standard template:
+Fresh-checkout template:
 
 ```bash
-python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-001 .prizmkit/plans/feature-list.json
-python3 ./.prizmkit/dev-pipeline/cli.py feature run F-001 .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-001 --fresh-checkout .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py run feature F-001 .prizmkit/plans/feature-list.json
 ```
 
 Clean template:
 
 ```bash
 python3 ./.prizmkit/dev-pipeline/cli.py reset feature F-001 --clean .prizmkit/plans/feature-list.json
-python3 ./.prizmkit/dev-pipeline/cli.py feature run F-001 .prizmkit/plans/feature-list.json
+python3 ./.prizmkit/dev-pipeline/cli.py run feature F-001 .prizmkit/plans/feature-list.json
 ```
 
-`--preserve-runtime` requires `--failed` and cannot be combined with `--clean`, an ID, a range, or another reset filter. Retry-budget flags such as `--max-retries` and `--max-infra-retries` belong on the run command, never reset. For clean retry, require explicit acknowledgement of branch deletion and possible uncommitted-change loss before displaying either command.
+State-only requires exactly one ID or explicit `--all` and rejects ranges/status filters. Fresh-checkout and clean accept one ID, range, or supported status filter. Preserve-runtime requires `--failed`, scans the whole list, and rejects IDs, ranges, `--all`, clean, other modes, and other filters. Retry-budget flags belong on the run command, never reset. For fresh-checkout or clean retry, require explicit acknowledgement of possible uncommitted-change loss; clean additionally requires acknowledgement of branch/history/artifact deletion.
 
 ## Output Contract
 

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.