prizmkit 1.1.99 → 1.1.101

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

@@ -0,0 +1,345 @@
+"""Data models and legacy argument normalization for Python pipeline runners."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .paths import RuntimePaths
+
+
+@dataclass(frozen=True)
+class RunnerFamily:
+    """Static metadata for one foreground pipeline family."""
+
+    kind: str
+    id_prefix: str
+    list_key: str
+    list_arg: str
+    item_id_arg: str
+    state_dir: Path
+    plan_path: Path
+    updater_script: Path
+    prompt_script: Path
+    branch_prefix: str
+    artifact_root_name: str
+
+    @property
+    def task_type(self) -> str:
+        return self.kind
+
+
+@dataclass(frozen=True)
+class RunnerEnvironment:
+    """Legacy runner environment controls modeled as one cohesive unit."""
+
+    stop_on_failure: bool = False
+    auto_push: bool = False
+    use_worktree: bool = True
+    dev_branch: str = ""
+    enable_deploy: bool = False
+    verbose: bool = False
+    heartbeat_interval_seconds: int = 30
+    heartbeat_stale_threshold_seconds: int = 600
+    stale_kill_threshold_seconds: int = 600
+    max_log_size: int | None = None
+    strict_behavior_check: bool = True
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> "RunnerEnvironment":
+        values = dict(os.environ if env is None else env)
+        return cls(
+            stop_on_failure=_truthy(values.get("STOP_ON_FAILURE")),
+            auto_push=_truthy(values.get("AUTO_PUSH")),
+            use_worktree=not _falsey(values.get("USE_WORKTREE")),
+            dev_branch=values.get("DEV_BRANCH", ""),
+            enable_deploy=_truthy(values.get("ENABLE_DEPLOY")),
+            verbose=_truthy(values.get("VERBOSE")),
+            heartbeat_interval_seconds=_int_value(values, "HEARTBEAT_INTERVAL", 30),
+            heartbeat_stale_threshold_seconds=_int_value(
+                values,
+                "HEARTBEAT_STALE_THRESHOLD",
+                _int_value(values, "HEARTBEAT_TIMEOUT_SECONDS", 600),
+            ),
+            stale_kill_threshold_seconds=_int_value(values, "STALE_KILL_THRESHOLD", 600),
+            max_log_size=_optional_int(values.get("MAX_LOG_SIZE")),
+            strict_behavior_check=not _falsey(values.get("STRICT_BEHAVIOR_CHECK")),
+        )
+
+
+@dataclass(frozen=True)
+class RunnerInvocation:
+    """Normalized legacy CLI arguments for one runner invocation."""
+
+    action: str
+    list_path: Path
+    item_id: str = ""
+    item_filter: str = ""
+    max_infra_retries: int = 3
+    mode: str | None = None
+    critic: bool | None = None
+    dry_run: bool = False
+    clean: bool = False
+    no_reset: bool = False
+    resume_phase: str = "null"
+    help_requested: bool = False
+    unknown_args: tuple[str, ...] = ()
+    raw_args: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class PromptGenerationResult:
+    """Structured output from the existing prompt generators."""
+
+    output_path: Path
+    model: str = ""
+    pipeline_mode: str = ""
+    agent_count: int = 0
+    critic_enabled: bool = False
+    checkpoint_path: Path | None = None
+    artifact_path: Path | None = None
+    raw: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SessionPaths:
+    """Canonical per-session runtime paths."""
+
+    session_dir: Path
+    prompt_path: Path
+    logs_dir: Path
+    session_log: Path
+    progress_json: Path
+    heartbeat_json: Path
+    session_status_json: Path
+
+    @classmethod
+    def for_item(cls, state_dir: Path, item_id: str, session_id: str) -> "SessionPaths":
+        session_dir = state_dir / item_id / "sessions" / session_id
+        logs_dir = session_dir / "logs"
+        return cls(
+            session_dir=session_dir,
+            prompt_path=session_dir / "bootstrap-prompt.md",
+            logs_dir=logs_dir,
+            session_log=logs_dir / "session.log",
+            progress_json=logs_dir / "progress.json",
+            heartbeat_json=logs_dir / "heartbeat.json",
+            session_status_json=session_dir / "session-status.json",
+        )
+
+
+@dataclass(frozen=True)
+class ContinuationState:
+    """Context-overflow continuation inputs for the next prompt/status update."""
+
+    active: bool = False
+    previous_session_id: str = ""
+    continuation_count: int = 0
+    context_overflow_count: int = 0
+    no_progress_count: int = 0
+    summary_path: Path | None = None
+    active_dev_branch: str = ""
+    base_branch: str = ""
+    fatal_error_code: str = "context_overflow"
+
+
+@dataclass(frozen=True)
+class SessionClassification:
+    """Final runner-owned session outcome before status updater mutation."""
+
+    session_status: str
+    reason: str = ""
+    fatal_error_code: str = ""
+    progress_fingerprint: Mapping[str, object] = field(default_factory=dict)
+    no_progress_count: int = 0
+
+
+@dataclass(frozen=True)
+class PipelineRunResult:
+    """Aggregated result for one foreground runner command."""
+
+    completed: bool
+    processed: int
+    stopped_reason: str = ""
+    last_status: str = ""
+    details: tuple[str, ...] = ()
+
+
+FAMILY_KINDS = ("feature", "bugfix", "refactor")
+
+
+def family_for(kind: str, paths: RuntimePaths) -> RunnerFamily:
+    """Return runner metadata for a supported pipeline family."""
+    script_dir = paths.pipeline_root / "scripts"
+    if kind == "feature":
+        return RunnerFamily(
+            kind="feature",
+            id_prefix="F-",
+            list_key="features",
+            list_arg="--feature-list",
+            item_id_arg="--feature-id",
+            state_dir=paths.feature_state_dir,
+            plan_path=paths.feature_plan,
+            updater_script=script_dir / "update-feature-status.py",
+            prompt_script=script_dir / "generate-bootstrap-prompt.py",
+            branch_prefix="dev",
+            artifact_root_name="specs",
+        )
+    if kind == "bugfix":
+        return RunnerFamily(
+            kind="bugfix",
+            id_prefix="B-",
+            list_key="bugs",
+            list_arg="--bug-list",
+            item_id_arg="--bug-id",
+            state_dir=paths.bugfix_state_dir,
+            plan_path=paths.bugfix_plan,
+            updater_script=script_dir / "update-bug-status.py",
+            prompt_script=script_dir / "generate-bugfix-prompt.py",
+            branch_prefix="bugfix",
+            artifact_root_name="bugfix",
+        )
+    if kind == "refactor":
+        return RunnerFamily(
+            kind="refactor",
+            id_prefix="R-",
+            list_key="refactors",
+            list_arg="--refactor-list",
+            item_id_arg="--refactor-id",
+            state_dir=paths.refactor_state_dir,
+            plan_path=paths.refactor_plan,
+            updater_script=script_dir / "update-refactor-status.py",
+            prompt_script=script_dir / "generate-refactor-prompt.py",
+            branch_prefix="refactor",
+            artifact_root_name="refactor",
+        )
+    raise ValueError(f"Unsupported runner family: {kind}")
+
+
+def parse_invocation(
+    family: RunnerFamily,
+    action: str,
+    legacy_args: Sequence[str] = (),
+) -> RunnerInvocation:
+    """Normalize legacy shell runner arguments without redesigning the interface."""
+    args = tuple(str(arg) for arg in legacy_args)
+    list_path = family.plan_path
+    item_id = ""
+    item_filter = ""
+    max_infra_retries = 3
+    mode: str | None = None
+    critic: bool | None = None
+    dry_run = False
+    clean = False
+    no_reset = False
+    resume_phase = "null"
+    unknown: list[str] = []
+    positional: list[str] = []
+    help_requested = False
+
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg in {"--help", "-h", "help"}:
+            help_requested = True
+        elif arg == "--dry-run":
+            dry_run = True
+        elif arg == "--clean":
+            clean = True
+        elif arg == "--no-reset":
+            no_reset = True
+        elif arg == "--critic":
+            critic = True
+        elif arg == "--no-critic":
+            critic = False
+        elif arg == "--features" and index + 1 < len(args):
+            index += 1
+            item_filter = args[index]
+        elif arg.startswith("--features="):
+            item_filter = arg.split("=", 1)[1]
+        elif arg == "--max-infra-retries" and index + 1 < len(args):
+            index += 1
+            max_infra_retries = _safe_int(args[index], 3)
+        elif arg.startswith("--max-infra-retries="):
+            max_infra_retries = _safe_int(arg.split("=", 1)[1], 3)
+        elif arg == "--mode" and index + 1 < len(args):
+            index += 1
+            mode = args[index]
+        elif arg.startswith("--mode="):
+            mode = arg.split("=", 1)[1]
+        elif arg == "--resume-phase" and index + 1 < len(args):
+            index += 1
+            resume_phase = args[index]
+        elif arg.startswith("--resume-phase="):
+            resume_phase = arg.split("=", 1)[1]
+        elif arg.startswith("-"):
+            unknown.append(arg)
+        else:
+            positional.append(arg)
+        index += 1
+
+    for value in positional:
+        if _looks_like_item_id(value, family.id_prefix) and not item_id:
+            item_id = _normalize_item_id(value, family.id_prefix)
+        elif list_path == family.plan_path:
+            list_path = Path(value).expanduser()
+        else:
+            unknown.append(value)
+
+    return RunnerInvocation(
+        action=action,
+        list_path=list_path,
+        item_id=item_id,
+        item_filter=item_filter,
+        max_infra_retries=max_infra_retries,
+        mode=mode,
+        critic=critic,
+        dry_run=dry_run,
+        clean=clean,
+        no_reset=no_reset,
+        resume_phase=resume_phase or "null",
+        help_requested=help_requested,
+        unknown_args=tuple(unknown),
+        raw_args=args,
+    )
+
+
+def _looks_like_item_id(value: str, prefix: str) -> bool:
+    upper = value.upper()
+    return upper.startswith(prefix.upper())
+
+
+def _normalize_item_id(value: str, prefix: str) -> str:
+    upper = value.upper()
+    if upper.startswith(prefix.upper()):
+        suffix = upper[len(prefix) :]
+        if suffix.isdigit():
+            return f"{prefix}{int(suffix):03d}"
+    return upper
+
+
+def _truthy(value: str | None) -> bool:
+    return str(value or "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _falsey(value: str | None) -> bool:
+    return str(value or "").strip().lower() in {"0", "false", "no", "off"}
+
+
+def _safe_int(value: str | None, default: int) -> int:
+    try:
+        return int(str(value))
+    except (TypeError, ValueError):
+        return default
+
+
+def _int_value(values: Mapping[str, str], name: str, default: int) -> int:
+    return _safe_int(values.get(name), default)
+
+
+def _optional_int(value: str | None) -> int | None:
+    if value is None or str(value).strip() == "":
+        return None
+    return _safe_int(value, 0)

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

@@ -0,0 +1,118 @@
+"""Prompt generator bridge for Python foreground runners."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from .runner_models import PromptGenerationResult, RunnerFamily, RunnerInvocation, SessionPaths
+
+
+def generate_prompt(
+    family: RunnerFamily,
+    invocation: RunnerInvocation,
+    *,
+    item_id: str,
+    session_id: str,
+    run_id: str,
+    retry_count: int,
+    session_paths: SessionPaths,
+    project_root: Path,
+    execution_root: Path | None = None,
+    continuation: dict[str, object] | None = None,
+) -> PromptGenerationResult:
+    """Run the existing prompt generator and return its structured JSON result."""
+    visible_root = execution_root or project_root
+    command = [
+        sys.executable,
+        str(family.prompt_script),
+        family.list_arg,
+        str(invocation.list_path),
+        family.item_id_arg,
+        item_id,
+        "--session-id",
+        session_id,
+        "--run-id",
+        run_id,
+        "--retry-count",
+        str(retry_count),
+        "--resume-phase",
+        invocation.resume_phase,
+        "--state-dir",
+        str(family.state_dir),
+        "--project-root",
+        str(visible_root),
+        "--output",
+        str(session_paths.prompt_path),
+    ]
+    if invocation.mode:
+        command.extend(["--mode", invocation.mode])
+    if invocation.critic is not None:
+        command.extend(["--critic", "true" if invocation.critic else "false"])
+    if continuation:
+        command.extend(["--continuation-mode", "context_overflow"])
+        for flag, key in (
+            ("--previous-session-id", "previous_session_id"),
+            ("--continuation-count", "continuation_count"),
+            ("--context-overflow-count", "context_overflow_count"),
+            ("--task-type", "task_type"),
+            ("--active-dev-branch", "active_dev_branch"),
+            ("--base-branch", "base_branch"),
+            ("--continuation-summary-path", "continuation_summary_path"),
+        ):
+            value = continuation.get(key)
+            if value not in (None, ""):
+                command.extend([flag, str(value)])
+
+    completed = subprocess.run(
+        command,
+        cwd=str(project_root),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        check=False,
+    )
+    if completed.returncode != 0:
+        raise RuntimeError(completed.stdout.strip() or completed.stderr.strip() or "prompt generation failed")
+    try:
+        data = json.loads(completed.stdout)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"prompt generator returned non-JSON output: {completed.stdout[:500]}") from exc
+    if not data.get("success"):
+        raise RuntimeError(str(data.get("error") or "prompt generation failed"))
+
+    checkpoint = data.get("checkpoint_path")
+    output_path = Path(str(data.get("output_path") or session_paths.prompt_path))
+    return PromptGenerationResult(
+        output_path=output_path,
+        model=str(data.get("model") or ""),
+        pipeline_mode=str(data.get("pipeline_mode") or ""),
+        agent_count=int(data.get("agent_count") or 0),
+        critic_enabled=_truthy(data.get("critic_enabled")),
+        checkpoint_path=Path(str(checkpoint)) if checkpoint else None,
+        artifact_path=_artifact_path(family, visible_root, item_id, data),
+        raw=data,
+    )
+
+
+def _artifact_path(
+    family: RunnerFamily,
+    project_root: Path,
+    item_id: str,
+    data: dict[str, object],
+) -> Path:
+    if family.kind == "feature" and data.get("checkpoint_path"):
+        return Path(str(data["checkpoint_path"])).parent
+    if family.kind == "bugfix":
+        return project_root / ".prizmkit" / "bugfix" / item_id
+    if family.kind == "refactor":
+        return project_root / ".prizmkit" / "refactor" / item_id
+    return project_root / ".prizmkit" / family.artifact_root_name / item_id
+
+
+def _truthy(value: object) -> bool:
+    if isinstance(value, bool):
+        return value
+    return str(value or "").strip().lower() in {"1", "true", "yes", "on"}

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

@@ -0,0 +1,187 @@
+"""Recovery detection and execution for Python foreground runner commands."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import load_runtime_config
+from .paths import RuntimePaths
+from .runner_models import RunnerEnvironment, SessionPaths
+from .sessions import AISessionConfig, AISessionLauncher
+
+
+@dataclass(frozen=True)
+class RecoveryDetectorResolver:
+    """Resolve recovery detector sources without coupling to one platform copy."""
+
+    paths: RuntimePaths
+
+    def candidates(self) -> tuple[Path, ...]:
+        project = self.paths.project_root
+        return (
+            project / ".agents" / "skills" / "recovery-workflow" / "scripts" / "detect-recovery-state.py",
+            project / ".claude" / "command-assets" / "recovery-workflow" / "scripts" / "detect-recovery-state.py",
+            project / ".codebuddy" / "skills" / "recovery-workflow" / "scripts" / "detect-recovery-state.py",
+            project
+            / "core"
+            / "skills"
+            / "orchestration-skill"
+            / "workflows"
+            / "recovery-workflow"
+            / "scripts"
+            / "detect-recovery-state.py",
+        )
+
+    def resolve(self) -> Path:
+        for candidate in self.candidates():
+            if candidate.is_file():
+                return candidate
+        raise FileNotFoundError("recovery detector script not found")
+
+
+def run_recovery_detect(paths: RuntimePaths) -> tuple[int, str, str, dict[str, object] | None]:
+    """Run recovery state detection and parse the JSON report."""
+    detector = RecoveryDetectorResolver(paths).resolve()
+    completed = subprocess.run(
+        [sys.executable, str(detector), "--project-root", str(paths.project_root)],
+        cwd=str(paths.project_root),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        check=False,
+    )
+    data = None
+    if completed.stdout.strip():
+        try:
+            data = json.loads(completed.stdout)
+        except json.JSONDecodeError:
+            data = None
+    return completed.returncode, completed.stdout, completed.stderr, data
+
+
+def run_recovery(paths: RuntimePaths, legacy_args: tuple[str, ...] = ()) -> tuple[int, str, str]:
+    """Detect recovery state, render a prompt, launch an AI session, and classify."""
+    dry_run = "--dry-run" in legacy_args
+    model_override = _option_value(legacy_args, "--model")
+    code, stdout, stderr, detection = run_recovery_detect(paths)
+    if code != 0 or not detection:
+        return code or 1, stdout, stderr
+    if not detection.get("detected"):
+        return 0, stdout, stderr
+
+    session_id = "recovery-{}-{}".format(
+        str(detection.get("workflow_type") or "workflow"),
+        time.strftime("%Y%m%d-%H%M%S"),
+    )
+    session_dir = paths.recovery_state_dir / session_id
+    session_paths = SessionPaths(
+        session_dir=session_dir,
+        prompt_path=session_dir / "bootstrap-prompt.md",
+        logs_dir=session_dir / "logs",
+        session_log=session_dir / "logs" / "session.log",
+        progress_json=session_dir / "logs" / "progress.json",
+        heartbeat_json=session_dir / "logs" / "heartbeat.json",
+        session_status_json=session_dir / "session-status.json",
+    )
+    detection_json = session_paths.session_dir / "detection.json"
+    session_paths.session_dir.mkdir(parents=True, exist_ok=True)
+    detection_json.write_text(json.dumps(detection, indent=2, ensure_ascii=False), encoding="utf-8")
+    prompt_output = session_paths.prompt_path
+    generator = paths.pipeline_root / "scripts" / "generate-recovery-prompt.py"
+    prompt_cmd = [
+        sys.executable,
+        str(generator),
+        "--detection-json",
+        str(detection_json),
+        "--output",
+        str(prompt_output),
+        "--project-root",
+        str(paths.project_root),
+        "--session-id",
+        session_id,
+    ]
+    prompt_result = subprocess.run(
+        prompt_cmd,
+        cwd=str(paths.project_root),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        check=False,
+    )
+    if prompt_result.returncode != 0:
+        return prompt_result.returncode, prompt_result.stdout, prompt_result.stderr
+    if dry_run:
+        return 0, prompt_result.stdout, prompt_result.stderr
+
+    config = load_runtime_config(paths)
+    if not config.ai_client.command:
+        return 1, "", "No supported AI CLI command was found for recovery\n"
+    env = RunnerEnvironment.from_env()
+    launcher = AISessionLauncher(
+        AISessionConfig(
+            cli_command=config.ai_client.command,
+            platform=config.ai_client.platform or "codebuddy",
+            model=model_override or config.model,
+            prompt_path=prompt_output,
+            cwd=paths.project_root,
+            log_path=session_paths.session_log,
+            progress_path=session_paths.progress_json,
+            heartbeat_path=session_paths.heartbeat_json,
+            effort=config.effort,
+            verbose=env.verbose,
+            stale_kill_threshold_seconds=env.stale_kill_threshold_seconds,
+        )
+    )
+    result = launcher.run()
+    outcome = _recovery_outcome(paths.project_root, result.exit_code)
+    session_paths.session_status_json.write_text(
+        json.dumps({"session_id": session_id, "outcome": outcome}, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    return 0 if outcome in {"success", "success_wip", "no_changes"} else 1, outcome + "\n", ""
+
+
+def _option_value(args: tuple[str, ...], flag: str) -> str | None:
+    for index, arg in enumerate(args):
+        if arg == flag and index + 1 < len(args):
+            return args[index + 1]
+        if arg.startswith(flag + "="):
+            return arg.split("=", 1)[1]
+    return None
+
+
+def _recovery_outcome(project_root: Path, exit_code: int | None) -> str:
+    commits = subprocess.run(
+        ["git", "-C", str(project_root), "rev-list", "--count", "HEAD", "^main"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        text=True,
+        check=False,
+    )
+    if commits.returncode == 0 and commits.stdout.strip() not in {"", "0"}:
+        return "success"
+    status = subprocess.run(
+        ["git", "-C", str(project_root), "status", "--porcelain"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        text=True,
+        check=False,
+    )
+    has_changes = bool(status.stdout.strip())
+    if exit_code == 0 and has_changes:
+        subprocess.run(["git", "-C", str(project_root), "add", "-A"], check=False)
+        subprocess.run(
+            ["git", "-C", str(project_root), "commit", "--no-verify", "-m", "chore: save recovery work"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
+        return "success_wip"
+    if exit_code == 0:
+        return "no_changes"
+    return "partial" if has_changes else "failed"