prizmkit 1.1.107 → 1.1.109

package/bin/create-prizmkit.js

@@ -46,6 +46,8 @@ program
   .option('--no-open-cli-auto-download', 'Skip auto-download, show manual steps only')
   .option('--rules <preset>', 'Rules preset: recommended, minimal, or none', 'recommended')
   .option('--ai-cli <command>', 'AI CLI executable command (e.g. cbc, claude, codex)')
+  .option('--headless-prompt-arg <arg>', 'Prompt injection argv token for a custom AI CLI (e.g. -p or -i)')
+  .option('--headless-extra-args <args>', 'Additional headless argv tokens for a custom AI CLI')
   .option('--external-skills <names>', 'Comma-separated external skill names to install (e.g. find-skills,impeccable)')
   .option('--non-interactive', 'Skip interactive prompts (requires --platform)')
   .option('--dry-run', 'Show what would be created without making changes')
@@ -95,6 +97,8 @@ program
   .option('--skills <suite>', 'Skill suite: core, minimal, or recommended:<type>')
   .option('--rules <preset>', 'Rules preset: recommended, minimal, or none')
   .option('--ai-cli <command>', 'AI CLI executable command (e.g. cbc, claude, codex)')
+  .option('--headless-prompt-arg <arg>', 'Prompt injection argv token for a custom AI CLI (e.g. -p or -i)')
+  .option('--headless-extra-args <args>', 'Additional headless argv tokens for a custom AI CLI')
   .option('--team', 'Enable multi-agent team mode')
   .option('--no-team', 'Disable multi-agent team mode')
   .option('--pipeline', 'Enable dev-pipeline')

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.107",
-  "bundledAt": "2026-07-07T11:02:06.367Z",
-  "bundledFrom": "93afdd5"
+  "frameworkVersion": "1.1.109",
+  "bundledAt": "2026-07-08T05:29:47.417Z",
+  "bundledFrom": "814bf2f"
 }

package/bundled/dev-pipeline/prizmkit_runtime/cli.py

@@ -9,6 +9,7 @@ from collections.abc import Sequence
 from .commands import CommandResult, handle_diagnostics, handle_runtime_command
 from .compat import UnsupportedPythonVersion, ensure_supported_python
 from .paths import resolve_runtime_paths
+from .runtime_helper import render_result, run_helper_command
 
 DESCRIPTION = (
     "PrizmKit canonical Python runtime CLI.\n"
@@ -81,6 +82,16 @@ def _add_diagnostics_subparsers(subparsers: argparse._SubParsersAction[argparse.
         action_parser.set_defaults(handler="diagnostics", action=action)
 
 
+def _add_helper_subparser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    helper_parser = subparsers.add_parser("helper", help="Cross-platform prompt runtime helper commands")
+    helper_parser.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        help="Arguments forwarded to prizmkit-runtime-helper.",
+    )
+    helper_parser.set_defaults(handler="helper", group="helper", action="run", target=None)
+
+
 _PIPELINE_GROUPS = {"feature", "bugfix", "refactor", "recovery"}
 _GLOBAL_OPTIONS_WITH_VALUES = {"--project-root", "--pipeline-root"}
 
@@ -150,6 +161,7 @@ def build_parser() -> argparse.ArgumentParser:
     _add_daemon_subparsers(subparsers)
     _add_status_subparsers(subparsers)
     _add_diagnostics_subparsers(subparsers)
+    _add_helper_subparser(subparsers)
     return parser
 
 
@@ -161,6 +173,14 @@ def _dispatch(args: argparse.Namespace) -> CommandResult:
     paths = _runtime_paths_from_args(args)
     if args.handler == "diagnostics":
         return handle_diagnostics(args.action, paths)
+    if args.handler == "helper":
+        helper_result = run_helper_command(tuple(getattr(args, "args", ()) or ()))
+        return CommandResult(
+            helper_result.exit_code,
+            "Python runtime helper",
+            "Cross-platform prompt runtime helper result.",
+            stdout=render_result(helper_result, json_output="--json" in tuple(getattr(args, "args", ()) or ())),
+        )
     return handle_runtime_command(
         args.group,
         args.action,

package/bundled/dev-pipeline/prizmkit_runtime/commands.py

@@ -280,6 +280,7 @@ def diagnostics_entrypoints(paths: RuntimePaths | None = None) -> CommandResult:
     details: list[str] = [
         f"runtime:cli: {runtime_paths.pipeline_root / 'cli.py'}",
         f"runtime:module: {runtime_paths.pipeline_root / 'prizmkit_runtime'}",
+        f"runtime:helper-module: {runtime_paths.pipeline_root / 'prizmkit_runtime' / 'runtime_helper.py'}",
     ]
     for name, relative_path in sorted(UTILITY_ENTRYPOINTS.items()):
         invocation = describe_existing_entrypoint("utility", name, paths=runtime_paths)

package/bundled/dev-pipeline/prizmkit_runtime/config.py

@@ -4,11 +4,13 @@ from __future__ import annotations
 
 import json
 import os
+import shlex
 import shutil
 from collections.abc import Mapping
 from dataclasses import dataclass
 from pathlib import Path
 
+from .launch_profiles import HeadlessLaunchProfile
 from .paths import RuntimePaths
 
 
@@ -33,6 +35,7 @@ class AIClientResolution:
     source: str
     precedence: tuple[str, ...]
     notes: tuple[str, ...] = ()
+    launch_profile: HeadlessLaunchProfile | None = None
 
 
 @dataclass(frozen=True)
@@ -65,6 +68,7 @@ class RuntimeConfig:
 AI_CLIENT_PRECEDENCE = (
     "AI_CLI",
     ".prizmkit/config.json:ai_cli",
+    ".prizmkit/config.json:ai_cli_launch",
     ".prizmkit/manifest.json:platform",
     ".prizmkit/config.json:platform",
     "CODEBUDDY_CLI",
@@ -137,13 +141,18 @@ def _int_from_env(env: Mapping[str, str], name: str, default: int) -> int:
         return default
 
 
-def _read_json_value(path: Path, key: str) -> str | None:
+def _read_json_object(path: Path) -> dict[str, object]:
     if not path.is_file():
-        return None
+        return {}
     try:
         data = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError):
-        return None
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _read_json_value(path: Path, key: str) -> str | None:
+    data = _read_json_object(path)
     value = data.get(key)
     return value if isinstance(value, str) and value.strip() else None
 
@@ -170,13 +179,16 @@ def _cli_names_for_platform(platform: str | None) -> tuple[str, ...]:
 def _known_platform_from_cli(cli_command: str | None) -> str | None:
     if not cli_command:
         return None
-    token = cli_command.split()[0].strip("'\"")
+    try:
+        token = shlex.split(cli_command)[0]
+    except ValueError:
+        token = cli_command.split()[0].strip("'\"")
     name = Path(token).name.lower()
-    if "claude" in name:
+    if name == "claude":
         return "claude"
-    if "codex" in name:
+    if name == "codex":
         return "codex"
-    if "cbc" in name or "codebuddy" in name:
+    if name in {"cbc", "codebuddy"}:
         return "codebuddy"
     return None
 
@@ -204,24 +216,73 @@ def _expected_cli_text(platform: str | None) -> str:
     return ", ".join(_cli_names_for_platform(platform))
 
 
+def _normalize_extra_args(value: object) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, list):
+        if not all(isinstance(item, str) for item in value):
+            raise RuntimeConfigError("Custom AI CLI extra arguments must be strings.")
+        return tuple(value)
+    if isinstance(value, str):
+        if not value.strip():
+            return ()
+        try:
+            return tuple(shlex.split(value))
+        except ValueError as exc:
+            raise RuntimeConfigError(f"Invalid custom AI CLI extra arguments: {exc}") from exc
+    raise RuntimeConfigError("Custom AI CLI extra arguments must be an array of argv tokens.")
+
+
+def _one_token(value: object, label: str) -> str:
+    text = value.strip() if isinstance(value, str) else ""
+    if not text:
+        raise RuntimeConfigError("Custom AI CLI requires both executable and prompt injection argument.")
+    try:
+        tokens = shlex.split(text)
+    except ValueError as exc:
+        raise RuntimeConfigError(f"Invalid custom AI CLI {label}: {exc}") from exc
+    if len(tokens) != 1 or not tokens[0]:
+        raise RuntimeConfigError(f"Custom AI CLI {label} must be exactly one argv token.")
+    return tokens[0]
+
+
+def _custom_launch_profile(config_data: Mapping[str, object], config_ai_cli: str | None) -> HeadlessLaunchProfile | None:
+    launch = config_data.get("ai_cli_launch")
+    custom_cli = bool(config_ai_cli) and _known_platform_from_cli(config_ai_cli) is None
+    if not custom_cli:
+        return None
+    if launch is None:
+        raise RuntimeConfigError("Custom AI CLI requires both executable and prompt injection argument in .prizmkit/config.json:ai_cli_launch.prompt_arg.")
+    if not isinstance(launch, Mapping):
+        raise RuntimeConfigError(".prizmkit/config.json:ai_cli_launch must be an object.")
+    if launch.get("profile") != "custom":
+        raise RuntimeConfigError("Custom AI CLI requires .prizmkit/config.json:ai_cli_launch.profile to be 'custom'.")
+    prompt_arg = _one_token(launch.get("prompt_arg"), "prompt injection argument")
+    return HeadlessLaunchProfile(
+        profile="custom",
+        prompt_arg=prompt_arg,
+        extra_args=_normalize_extra_args(launch.get("extra_args")),
+    )
+
+
 def _installed_platform_cli(
     paths: RuntimePaths,
     env: Mapping[str, str],
 ) -> tuple[str | None, str | None]:
     if (
         (paths.project_root / ".codex" / "agents" / "prizm-dev-team-dev.toml").is_file()
-        or (paths.project_root / ".agents" / "skills" / "prizm-kit" / "SKILL.md").is_file()
+        or (paths.project_root / ".agents" / "skills" / "prizmkit" / "SKILL.md").is_file()
     ):
         resolved = _resolve_cli_name("codex", env)
         if resolved:
             return resolved, "installed-platform:codex"
-    if (paths.project_root / ".claude" / "commands" / "prizm-kit.md").is_file():
+    if (paths.project_root / ".claude" / "commands" / "prizmkit.md").is_file():
         resolved = _resolve_cli_name("claude", env)
         if resolved:
             return resolved, "installed-platform:claude"
     if (
         (paths.project_root / ".codebuddy" / "agents" / "prizm-dev-team-dev.md").is_file()
-        or (paths.project_root / ".codebuddy" / "skills" / "prizm-kit" / "SKILL.md").is_file()
+        or (paths.project_root / ".codebuddy" / "skills" / "prizmkit" / "SKILL.md").is_file()
     ):
         resolved = _resolve_cli_name("cbc", env)
         if resolved:
@@ -255,8 +316,12 @@ def resolve_ai_client(
 
 
 def _resolve_ai_client(paths: RuntimePaths, env: Mapping[str, str]) -> AIClientResolution:
-    config_ai_cli = _read_json_value(paths.prizmkit_dir / "config.json", "ai_cli")
-    config_platform = _read_json_value(paths.prizmkit_dir / "config.json", "platform")
+    config_path = paths.prizmkit_dir / "config.json"
+    config_data = _read_json_object(config_path)
+    config_ai_cli_value = config_data.get("ai_cli")
+    config_ai_cli = config_ai_cli_value if isinstance(config_ai_cli_value, str) and config_ai_cli_value.strip() else None
+    config_platform_value = config_data.get("platform")
+    config_platform = config_platform_value if isinstance(config_platform_value, str) and config_platform_value.strip() else None
     manifest_platform = _read_json_value(paths.prizmkit_dir / "manifest.json", "platform")
 
     explicit_command = env.get("AI_CLI")
@@ -269,11 +334,13 @@ def _resolve_ai_client(paths: RuntimePaths, env: Mapping[str, str]) -> AIClientR
         )
 
     if config_ai_cli:
+        custom_launch = _custom_launch_profile(config_data, config_ai_cli)
         return AIClientResolution(
             command=config_ai_cli,
-            platform=_project_platform_for_cli(config_ai_cli, env, manifest_platform, config_platform),
-            source="prizmkit-config:ai_cli",
+            platform="custom" if custom_launch is not None else _project_platform_for_cli(config_ai_cli, env, manifest_platform, config_platform),
+            source="prizmkit-config:ai_cli_launch" if custom_launch is not None else "prizmkit-config:ai_cli",
             precedence=AI_CLIENT_PRECEDENCE,
+            launch_profile=custom_launch,
         )
 
     for platform, source, configured_label in (

package/bundled/dev-pipeline/prizmkit_runtime/gitops.py

@@ -33,6 +33,8 @@ HIDDEN_TOOL_WORKTREE_EXCLUDES = (
     ":(top,exclude).prizmkit/manifest.json",
     ":(top,exclude).prizmkit/dev-pipeline/scripts",
     ":(top,exclude,glob).prizmkit/dev-pipeline/scripts/**",
+    ":(top,exclude).prizmkit/dev-pipeline/prizmkit_runtime",
+    ":(top,exclude,glob).prizmkit/dev-pipeline/prizmkit_runtime/**",
 )
 
 WORKTREE_PLATFORM_SUPPORT_DIRS = (".claude", ".codebuddy", ".codex", ".agents")
@@ -242,6 +244,14 @@ def materialize_worktree_support_assets(runtime: WorktreeRuntimeContext) -> Work
             target = target_root / ".prizmkit" / "dev-pipeline" / "scripts"
             changed = _copy_support_entry(runtime_scripts, target)
             (copied if changed else existing).append(target)
+
+        runtime_package = _runtime_support_package_source(source_root)
+        if runtime_package is None:
+            missing.append(".prizmkit/dev-pipeline/prizmkit_runtime")
+        else:
+            target = target_root / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime"
+            changed = _copy_support_entry(runtime_package, target)
+            (copied if changed else existing).append(target)
     except OSError as exc:
         return WorktreeSupportAssetsResult(False, tuple(copied), tuple(existing), tuple(missing), str(exc))
 
@@ -276,6 +286,17 @@ def _runtime_support_scripts_source(project_root: Path) -> Path | None:
     return None
 
 
+def _runtime_support_package_source(project_root: Path) -> Path | None:
+    candidates = (
+        project_root / ".prizmkit" / "dev-pipeline" / "prizmkit_runtime",
+        project_root / "dev-pipeline" / "prizmkit_runtime",
+    )
+    for candidate in candidates:
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
 def _copy_support_entry(source: Path, target: Path) -> bool:
     if source.is_symlink():
         if target.exists() or target.is_symlink():

package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py

@@ -100,11 +100,16 @@ def observe_heartbeat_state(
         or (progress_signature and progress_signature != previous.progress_signature)
         or (child_signature and child_signature != previous.child_activity_signature)
     )
-    stale_seconds = 0 if progressed else (previous.stale_seconds + config.interval_seconds if previous else 0)
+    if progressed:
+        last_seen_epoch = now
+        stale_seconds = 0.0
+    else:
+        last_seen_epoch = previous.last_seen_epoch if previous and previous.last_seen_epoch is not None else now
+        stale_seconds = max(0.0, now - last_seen_epoch)
     stale = bool(config.stale_after_seconds > 0 and stale_seconds >= config.stale_after_seconds)
     details = "progress" if progressed else "no progress"
     return HeartbeatState(
-        last_seen_epoch=now if progressed else (previous.last_seen_epoch if previous else now),
+        last_seen_epoch=last_seen_epoch,
         stale=stale,
         details=details,
         stale_seconds=stale_seconds,
@@ -118,6 +123,11 @@ def _utc_marker_time() -> str:
     return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
 
 
+def _marker_number(value: float) -> int | float:
+    normalized = max(0.0, float(value))
+    return int(normalized) if normalized.is_integer() else normalized
+
+
 def _progress_fatal_error_code(path: Path | None) -> str:
     if path is None or not path.is_file():
         return ""
@@ -142,8 +152,8 @@ def write_stale_marker(
     payload = {
         "killed_at": _utc_marker_time(),
         "reason": reason,
-        "stale_seconds": int(stale_seconds),
-        "threshold": int(threshold),
+        "stale_seconds": _marker_number(stale_seconds),
+        "threshold": _marker_number(threshold),
     }
     if fatal_error_code:
         payload["fatal_error_code"] = fatal_error_code
@@ -164,8 +174,8 @@ def write_fatal_marker(
         "killed_at": _utc_marker_time(),
         "reason": fatal_error_code,
         "fatal_error_code": fatal_error_code,
-        "stale_seconds": int(stale_seconds),
-        "threshold": int(threshold),
+        "stale_seconds": _marker_number(stale_seconds),
+        "threshold": _marker_number(threshold),
     }
     fatal_path = marker_dir / "fatal-error.json"
     stale_path = marker_dir / "stale-kill.json"
@@ -231,13 +241,14 @@ class HeartbeatMonitor:
                 self._killed = True
                 self._reason = fatal_error_code
                 break
-            if self._state.stale and self.config.kill_after_seconds > 0:
+            should_kill = bool(self.config.kill_after_seconds > 0 and self._state.stale_seconds >= self.config.kill_after_seconds)
+            if should_kill:
                 marker_dir = self.config.marker_dir or (self.config.session_log.parent if self.config.session_log else self.config.heartbeat_file.parent)
                 self._marker_path = write_stale_marker(
                     marker_dir,
                     reason="stale_session",
                     stale_seconds=self._state.stale_seconds,
-                    threshold=self.config.stale_after_seconds,
+                    threshold=self.config.kill_after_seconds,
                 )
                 terminate_process_tree(self.handle, "stale_session", grace_seconds=self.config.grace_seconds)
                 self._killed = True

package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py

@@ -24,7 +24,7 @@ UTILITY_ENTRYPOINTS = {
     "init-refactor-pipeline": "scripts/init-refactor-pipeline.py",
     "parse-stream-progress": "scripts/parse-stream-progress.py",
     "patch-completion-notes": "scripts/patch-completion-notes.py",
-    "prizmkit-test-gate": "scripts/prizmkit-test-gate.py",
+    "prizmkit-runtime-helper": "scripts/prizmkit-runtime-helper.py",
     "update-bug-status": "scripts/update-bug-status.py",
     "update-checkpoint": "scripts/update-checkpoint.py",
     "update-feature-status": "scripts/update-feature-status.py",

package/bundled/dev-pipeline/prizmkit_runtime/launch_profiles.py

@@ -0,0 +1,18 @@
+"""Provider-neutral headless launch profile models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class HeadlessLaunchProfile:
+    """Custom AI CLI headless prompt injection contract."""
+
+    profile: str
+    prompt_arg: str
+    extra_args: tuple[str, ...] = ()
+
+    @property
+    def is_custom(self) -> bool:
+        return self.profile == "custom"

package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py

@@ -0,0 +1,208 @@
+"""Shared AI platform and skill path detection for prompt/runtime helpers."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+SUPPORTED_PLATFORMS = ("claude", "codex", "codebuddy")
+
+
+@dataclass(frozen=True)
+class PlatformResolution:
+    """Resolved AI platform plus the source that selected it."""
+
+    platform: str
+    source: str
+    notes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class SkillCandidate:
+    """One possible filesystem location for a skill."""
+
+    platform: str
+    scope: str
+    path: Path
+
+
+@dataclass(frozen=True)
+class SkillResolution:
+    """Resolved skill lookup result."""
+
+    marker: str
+    platform: str
+    skill: str
+    path: Path | None
+    candidates: tuple[SkillCandidate, ...]
+
+
+_PLATFORM_MARKERS = {
+    "claude": (".claude/agents", ".claude/commands", ".claude/skills"),
+    "codex": (".codex/agents", ".agents/skills"),
+    "codebuddy": (".codebuddy/agents", ".codebuddy/skills"),
+}
+
+
+_PLATFORM_SKILL_PATTERNS = {
+    "claude": (
+        ("project-command-file", ".claude/commands/{skill}.md"),
+        ("project-command-dir", ".claude/commands/{skill}"),
+        ("project-skill", ".claude/skills/{skill}"),
+        ("home-skill", "~/.claude/skills/{skill}"),
+    ),
+    "codex": (
+        ("project-skill", ".agents/skills/{skill}"),
+        ("project-codex-skill", ".codex/skills/{skill}"),
+    ),
+    "codebuddy": (
+        ("project-skill", ".codebuddy/skills/{skill}"),
+        ("home-skill", "~/.codebuddy/skills/{skill}"),
+        ("legacy-home-skill", "~/.cbc/skills/{skill}"),
+    ),
+}
+
+
+def read_json_object(path: str | Path) -> dict:
+    """Read a JSON object, returning an empty dict when unavailable."""
+    try:
+        with Path(path).expanduser().open("r", encoding="utf-8") as handle:
+            data = json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def platform_from_command(command: object) -> str:
+    """Map an AI CLI command/config value to a PrizmKit platform name."""
+    cmd = str(command or "").strip().lower()
+    if not cmd:
+        return ""
+    base = os.path.basename(cmd.split()[0])
+    if base in ("claude", "claude-code") or "claude" in base:
+        return "claude"
+    if base in ("codex", "openai-codex") or "codex" in base:
+        return "codex"
+    if base in ("cbc", "codebuddy") or "codebuddy" in base:
+        return "codebuddy"
+    return ""
+
+
+def valid_prompt_platform(value: object) -> str:
+    """Normalize a platform value for prompt path rendering."""
+    platform = str(value or "").strip().lower()
+    return platform if platform in SUPPORTED_PLATFORMS else ""
+
+
+def resolve_platform(project_root: str | Path, env: Mapping[str, str] | None = None) -> PlatformResolution:
+    """Resolve the platform whose paths should appear in prompts/helper output.
+
+    Precedence mirrors prompt generation: explicit environment, active/configured
+    AI CLI, PrizmKit config/manifest platform, then filesystem markers.
+    """
+    environment = os.environ if env is None else env
+    root = Path(project_root).expanduser().resolve()
+
+    explicit = valid_prompt_platform(environment.get("PRIZMKIT_PLATFORM", ""))
+    if explicit:
+        return PlatformResolution(explicit, "environment:PRIZMKIT_PLATFORM")
+
+    for env_name in ("AI_CLI", "CLAUDECODE", "CLAUDE_CODE", "CODEBUDDY_CLI"):
+        detected = platform_from_command(environment.get(env_name, ""))
+        if detected:
+            return PlatformResolution(detected, f"environment:{env_name}")
+
+    config = read_json_object(root / ".prizmkit" / "config.json")
+    for key in ("ai_cli", "aiCli"):
+        detected = platform_from_command(config.get(key, ""))
+        if detected:
+            return PlatformResolution(detected, f"config:{key}")
+    detected = valid_prompt_platform(config.get("platform", ""))
+    if detected:
+        return PlatformResolution(detected, "config:platform")
+
+    manifest = read_json_object(root / ".prizmkit" / "manifest.json")
+    options = manifest.get("options", {}) if isinstance(manifest.get("options"), dict) else {}
+    for key, value in (("aiCli", manifest.get("aiCli", "")), ("options.aiCli", options.get("aiCli", ""))):
+        detected = platform_from_command(value)
+        if detected:
+            return PlatformResolution(detected, f"manifest:{key}")
+    detected = valid_prompt_platform(manifest.get("platform", ""))
+    if detected:
+        return PlatformResolution(detected, "manifest:platform")
+
+    for platform in SUPPORTED_PLATFORMS:
+        for marker in _PLATFORM_MARKERS[platform]:
+            if (root / marker).is_dir():
+                return PlatformResolution(platform, f"filesystem:{marker}")
+
+    return PlatformResolution(
+        "",
+        "unresolved",
+        (
+            "No supported platform marker found. Set PRIZMKIT_PLATFORM, configure .prizmkit/config.json, "
+            "or install Claude/Codex/CodeBuddy platform files.",
+        ),
+    )
+
+
+def _expand_skill_pattern(project_root: Path, skill: str, platform: str, scope: str, pattern: str) -> SkillCandidate:
+    rendered = pattern.format(skill=skill)
+    if rendered.startswith("~"):
+        path = Path(rendered).expanduser()
+    else:
+        path = project_root / rendered
+    return SkillCandidate(platform=platform, scope=scope, path=path.resolve())
+
+
+def skill_candidates(project_root: str | Path, skill: str, platform: str) -> tuple[SkillCandidate, ...]:
+    """Return deterministic candidate locations for a skill on one platform."""
+    normalized = valid_prompt_platform(platform)
+    if not normalized:
+        return ()
+    root = Path(project_root).expanduser().resolve()
+    return tuple(
+        _expand_skill_pattern(root, skill, normalized, scope, pattern)
+        for scope, pattern in _PLATFORM_SKILL_PATTERNS[normalized]
+    )
+
+
+def _candidate_matches(candidate: SkillCandidate, skill: str, *, prefix: bool) -> bool:
+    path = candidate.path
+    if path.exists():
+        return True
+    if not prefix:
+        return False
+    parent = path.parent
+    if not parent.is_dir():
+        return False
+    return any(child.name.startswith(skill) for child in parent.iterdir())
+
+
+def resolve_skill(
+    project_root: str | Path,
+    skill: str,
+    *,
+    platform: str = "auto",
+    env: Mapping[str, str] | None = None,
+    prefix: bool = False,
+) -> SkillResolution:
+    """Resolve a skill path for the selected platform."""
+    normalized_skill = str(skill or "").strip()
+    selected_platform = valid_prompt_platform(platform)
+    if platform == "auto" or not platform:
+        selected_platform = resolve_platform(project_root, env=env).platform
+    if not selected_platform:
+        return SkillResolution("NOT_INSTALLED", "", normalized_skill, None, ())
+
+    candidates = skill_candidates(project_root, normalized_skill, selected_platform)
+    for candidate in candidates:
+        if _candidate_matches(candidate, normalized_skill, prefix=prefix):
+            if candidate.path.exists():
+                return SkillResolution("SKILL_EXISTS", selected_platform, normalized_skill, candidate.path, candidates)
+            matches = sorted(child for child in candidate.path.parent.iterdir() if child.name.startswith(normalized_skill))
+            return SkillResolution("SKILL_EXISTS", selected_platform, normalized_skill, matches[0].resolve(), candidates)
+    return SkillResolution("SKILL_MISSING", selected_platform, normalized_skill, None, candidates)

package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py

@@ -67,7 +67,21 @@ def commit_bookkeeping_changes(
     if not paths:
         return BookkeepingResult(attempted=False, committed=False)
     run_git_command(project_root, ("add", "-A", "--", *paths))
-    result = run_git_command(project_root, ("commit", "--no-verify", "-m", message))
+    result = run_git_command(project_root, ("commit", "--no-verify", "-m", message, "--", *paths))
+    return BookkeepingResult(attempted=True, committed=result.return_code == 0, result=result)
+
+
+def commit_preflight_ready_changes(project_root: Path, item_id: str) -> BookkeepingResult:
+    """Preserve visible pre-existing changes before task branch setup."""
+    if not git_status_safe(project_root).strip():
+        return BookkeepingResult(attempted=False, committed=False)
+    add_result = run_git_command(project_root, ("add", "-A", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES))
+    if add_result.return_code != 0:
+        return BookkeepingResult(attempted=True, committed=False, result=add_result)
+    result = run_git_command(
+        project_root,
+        ("commit", "--no-verify", "-m", f"chore: ready for {item_id}", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES),
+    )
     return BookkeepingResult(attempted=True, committed=result.return_code == 0, result=result)
 
 
@@ -84,7 +98,10 @@ def commit_task_branch_changes(
     if not git_status_safe(project_root).strip():
         return BookkeepingResult(attempted=False, committed=False)
     run_git_command(project_root, ("add", "-A", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES))
-    result = run_git_command(project_root, ("commit", "--no-verify", "-m", message))
+    result = run_git_command(
+        project_root,
+        ("commit", "--no-verify", "-m", message, "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES),
+    )
     return BookkeepingResult(attempted=True, committed=result.return_code == 0, result=result)
 
 
@@ -107,6 +124,9 @@ def commit_wip_changes(
             f"wip({item_id}): preserve {family.kind} {status} state",
             "-m",
             "Pipeline preserved task branch work without merging it to the base branch.",
+            "--",
+            ".",
+            *HIDDEN_TOOL_WORKTREE_EXCLUDES,
         ),
     )
     return BookkeepingResult(attempted=True, committed=result.return_code == 0, result=result)