prizmkit 1.1.100 → 1.1.101

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

@@ -0,0 +1,389 @@
+"""Manual reset commands for the unified Python runtime."""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from .commands import CommandResult  # type: ignore  # runtime boundary import
+from .gitops import default_branch, list_reset_branches, reset_cleanup_branch
+from .runner_models import RunnerFamily, family_for
+
+
+@dataclass(frozen=True)
+class ResetOptions:
+    """Parsed legacy reset arguments for one family."""
+
+    list_path: Path
+    item_id: str = ""
+    item_range: tuple[str, str] | None = None
+    filter_mode: str = ""
+    clean: bool = False
+    run_after: bool = False
+    help_requested: bool = False
+    unknown_args: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ResetItem:
+    """Resolved reset target from the plan list."""
+
+    item_id: str
+    title: str
+    slug: str
+    status: str
+
+
+FAMILY_LABELS = {
+    "feature": "feature",
+    "bugfix": "bug",
+    "refactor": "refactor",
+}
+
+FILTER_FLAGS = {
+    "--auto-skipped": "auto_skipped",
+    "--failed": "failed",
+    "--stalled": "stalled",
+}
+
+
+ID_FIELD_BY_KIND = {
+    "feature": "id",
+    "bugfix": "id",
+    "refactor": "id",
+}
+
+
+TITLE_FIELD_BY_KIND = {
+    "feature": "title",
+    "bugfix": "title",
+    "refactor": "title",
+}
+
+
+BRANCH_PREFIX_BY_KIND = {
+    "feature": "dev",
+    "bugfix": "bugfix",
+    "refactor": "refactor",
+}
+
+STALLED_FILTER_STATUSES = {
+    "failed",
+    "auto_skipped",
+    "needs_info",
+    "stalled",
+    "stalled_context_continuation",
+}
+
+
+def run_reset_command(kind: str, legacy_args: tuple[str, ...], paths) -> CommandResult:
+    """Run a manual reset command for feature, bugfix, or refactor."""
+    family = family_for(kind, paths)
+    options = _parse_reset_args(family, legacy_args)
+    if options.help_requested:
+        return CommandResult(0, f"Python {kind} reset", _help_text(family), stdout=_help_text(family))
+
+    list_path = _resolve_list_path(options.list_path, paths.project_root)
+    if not list_path.is_file():
+        return CommandResult(1, f"Python {kind} reset", f"{kind} list not found: {list_path}")
+    if not (family.state_dir / "pipeline.json").is_file():
+        return CommandResult(1, f"Python {kind} reset", f"No pipeline state found. Run the {kind} pipeline first to initialize.")
+
+    options = ResetOptions(
+        list_path=list_path,
+        item_id=options.item_id,
+        item_range=options.item_range,
+        filter_mode=options.filter_mode,
+        clean=options.clean,
+        run_after=options.run_after,
+        help_requested=options.help_requested,
+        unknown_args=options.unknown_args,
+    )
+    try:
+        items = _resolve_items(family, options)
+    except ValueError as exc:
+        return CommandResult(1, f"Python {kind} reset", str(exc))
+    if not items:
+        return CommandResult(0, f"Python {kind} reset", f"No {FAMILY_LABELS[kind]}s found with status: {options.filter_mode}")
+
+    if options.run_after and len(items) > 1:
+        options = ResetOptions(
+            list_path=options.list_path,
+            item_id=options.item_id,
+            item_range=options.item_range,
+            filter_mode=options.filter_mode,
+            clean=options.clean,
+            run_after=False,
+            help_requested=False,
+            unknown_args=options.unknown_args,
+        )
+
+    lines: list[str] = []
+    success = 0
+    failed = 0
+    return_branch = default_branch(paths.project_root)
+    for item in items:
+        ok = _reset_one(family, item, options, paths.project_root, return_branch, lines)
+        if ok:
+            success += 1
+        else:
+            failed += 1
+
+    lines.append(f"Reset complete: {success} succeeded, {failed} failed")
+    if options.run_after and len(items) == 1 and failed == 0:
+        from .runners import run_pipeline_command
+
+        lines.append(f"Auto-retrying {items[0].item_id} via Python foreground runner...")
+        retry_result = run_pipeline_command(kind, "run", (items[0].item_id, str(options.list_path)), paths)
+        lines.append(retry_result.render())
+        return CommandResult(retry_result.exit_code, f"Python {kind} reset", "\n".join(lines), stdout="\n".join(lines))
+
+    return CommandResult(0 if failed == 0 else 1, f"Python {kind} reset", "\n".join(lines), stdout="\n".join(lines))
+
+
+def _parse_reset_args(family: RunnerFamily, legacy_args: Sequence[str]) -> ResetOptions:
+    args = tuple(str(arg) for arg in legacy_args)
+    list_path = family.plan_path
+    item_id = ""
+    item_range: tuple[str, str] | None = None
+    filter_mode = ""
+    clean = False
+    run_after = False
+    help_requested = False
+    unknown: list[str] = []
+    positional: list[str] = []
+
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg in {"--help", "-h", "help"}:
+            help_requested = True
+        elif arg == "--clean":
+            clean = True
+        elif arg == "--run":
+            run_after = True
+        elif arg in FILTER_FLAGS:
+            filter_mode = FILTER_FLAGS[arg]
+        elif arg.startswith("-"):
+            unknown.append(arg)
+        else:
+            positional.append(arg)
+        index += 1
+
+    for value in positional:
+        if _looks_like_range(value, family.id_prefix):
+            item_range = _normalize_range(value, family.id_prefix)
+        elif _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 ResetOptions(
+        list_path=list_path,
+        item_id=item_id,
+        item_range=item_range,
+        filter_mode=filter_mode,
+        clean=clean,
+        run_after=run_after,
+        help_requested=help_requested,
+        unknown_args=tuple(unknown),
+    )
+
+
+def _resolve_list_path(path: Path, project_root: Path) -> Path:
+    return path.resolve() if path.is_absolute() else (project_root / path).resolve()
+
+
+def _resolve_items(family: RunnerFamily, options: ResetOptions) -> tuple[ResetItem, ...]:
+    data = json.loads(options.list_path.read_text(encoding="utf-8"))
+    raw_items = data.get(family.list_key, [])
+    if not isinstance(raw_items, list):
+        raw_items = []
+    by_id = {_item_id(family, item): item for item in raw_items if isinstance(item, dict) and _item_id(family, item)}
+
+    ids: list[str]
+    if options.filter_mode:
+        ids = []
+        for item in raw_items:
+            if not isinstance(item, dict):
+                continue
+            status = str(item.get("status") or "")
+            if options.filter_mode == "auto_skipped" and status == "auto_skipped":
+                ids.append(_item_id(family, item))
+            elif options.filter_mode == "failed" and status == "failed":
+                ids.append(_item_id(family, item))
+            elif options.filter_mode == "stalled" and status in STALLED_FILTER_STATUSES:
+                ids.append(_item_id(family, item))
+    elif options.item_range:
+        start, end = options.item_range
+        start_num = _numeric_suffix(start, family.id_prefix)
+        end_num = _numeric_suffix(end, family.id_prefix)
+        if start_num <= 0 or end_num <= 0 or start_num > end_num:
+            raise ValueError(f"Invalid range: {start}:{end} (start must be <= end)")
+        ids = [f"{family.id_prefix}{number:03d}" for number in range(start_num, end_num + 1)]
+    elif options.item_id:
+        ids = [options.item_id]
+    else:
+        raise ValueError(_help_text(family))
+
+    resolved: list[ResetItem] = []
+    for item_id in ids:
+        item = by_id.get(item_id)
+        if not isinstance(item, dict):
+            continue
+        title = str(item.get(TITLE_FIELD_BY_KIND[family.kind]) or "")
+        resolved.append(ResetItem(item_id=item_id, title=title, slug=_slug_for_item(family, item_id, title), status=str(item.get("status") or "unknown")))
+    return tuple(resolved)
+
+
+def _reset_one(family: RunnerFamily, item: ResetItem, options: ResetOptions, project_root: Path, return_branch: str, lines: list[str]) -> bool:
+    label = FAMILY_LABELS[family.kind]
+    status_file = family.state_dir / item.item_id / "status.json"
+    lines.append(f"Reset: {item.item_id} — {item.title}")
+    status_data = _load_status(status_file)
+    if status_data:
+        lines.append(f"Current status: {item.status} (retry {status_data.get('retry_count', 0)}, {len(status_data.get('sessions') or [])} sessions)")
+        _append_continuation_warning(lines, status_data, item.item_id, label)
+    else:
+        lines.append(f"Current status: {item.status} (no runtime state file)")
+
+    for branch in list_reset_branches(project_root, BRANCH_PREFIX_BY_KIND[family.kind], item.item_id):
+        cleanup = reset_cleanup_branch(project_root, branch, return_branch=return_branch, delete=options.clean)
+        lines.append(f"Discarded uncommitted changes on dev branch: {cleanup.branch}")
+        if cleanup.deleted:
+            lines.append(f"Deleted dev branch: {cleanup.branch}")
+        elif not options.clean:
+            lines.append(f"Dev branch preserved for debugging: {cleanup.branch}")
+        lines.extend(f"WARN: {warning}" for warning in cleanup.warnings)
+
+    action = "clean" if options.clean else "reset"
+    lines.append(f"{'Cleaning' if options.clean else 'Resetting'} {item.item_id} status...")
+    result = _run_updater(family, action, options, item, project_root)
+    if result.returncode == 0 and _json_without_error(result.stdout):
+        lines.append(f"{item.item_id} {action} complete: status -> pending, retry count -> 0")
+        return True
+    error = _error_text(result.stdout) or result.stderr.strip() or "unknown"
+    lines.append(f"ERROR: Reset {item.item_id} failed: {error}")
+    return False
+
+
+def _run_updater(family: RunnerFamily, action: str, options: ResetOptions, item: ResetItem, project_root: Path) -> subprocess.CompletedProcess[str]:
+    command = [
+        sys.executable,
+        str(family.updater_script),
+        family.list_arg,
+        str(options.list_path),
+        "--state-dir",
+        str(family.state_dir),
+        family.item_id_arg,
+        item.item_id,
+        "--action",
+        action,
+        "--max-retries",
+        "3",
+        "--max-infra-retries",
+        "3",
+    ]
+    if action == "clean":
+        command.extend(["--project-root", str(project_root)])
+        if family.kind == "feature":
+            command.extend(["--feature-slug", item.slug])
+    return subprocess.run(command, cwd=str(project_root), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, check=False)
+
+
+def _append_continuation_warning(lines: list[str], status_data: dict[str, object], item_id: str, item_label: str) -> None:
+    if status_data.get("continuation_pending") is True:
+        reason = str(status_data.get("continuation_reason") or "context_overflow")
+        lines.append(
+            f"WARN: Continuation pending for {item_label} {item_id} ({reason}). Manual reset will abandon automatic continuation progress."
+        )
+        branch = str(status_data.get("active_dev_branch") or "")
+        if branch:
+            lines.append(f"WARN: Pending continuation branch: {branch}")
+
+
+def _load_status(path: Path) -> dict[str, object]:
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _json_without_error(text: str) -> bool:
+    try:
+        data = json.loads(text or "{}")
+    except json.JSONDecodeError:
+        return False
+    return isinstance(data, dict) and "error" not in data
+
+
+def _error_text(text: str) -> str:
+    try:
+        data = json.loads(text or "{}")
+    except json.JSONDecodeError:
+        return text.strip()
+    return str(data.get("error") or "") if isinstance(data, dict) else ""
+
+
+def _item_id(family: RunnerFamily, item: dict[str, object]) -> str:
+    return _normalize_item_id(str(item.get(ID_FIELD_BY_KIND[family.kind]) or ""), family.id_prefix)
+
+
+def _slug_for_item(family: RunnerFamily, item_id: str, title: str) -> str:
+    if family.kind != "feature":
+        return item_id
+    numeric = item_id.replace("F-", "").replace("f-", "").zfill(3)
+    slug = re.sub(r"[^a-z0-9\s-]", "", title.lower())
+    slug = re.sub(r"[\s]+", "-", slug.strip())
+    slug = re.sub(r"-+", "-", slug).strip("-") or "feature"
+    return f"{numeric}-{slug}"
+
+
+def _looks_like_item_id(value: str, prefix: str) -> bool:
+    return value.upper().startswith(prefix.upper())
+
+
+def _looks_like_range(value: str, prefix: str) -> bool:
+    if ":" not in value:
+        return False
+    left, right = value.split(":", 1)
+    return _looks_like_item_id(left, prefix) and _looks_like_item_id(right, prefix)
+
+
+def _normalize_range(value: str, prefix: str) -> tuple[str, str]:
+    left, right = value.split(":", 1)
+    return _normalize_item_id(left, prefix), _normalize_item_id(right, prefix)
+
+
+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 _numeric_suffix(value: str, prefix: str) -> int:
+    normalized = _normalize_item_id(value, prefix)
+    suffix = normalized[len(prefix) :]
+    return int(suffix) if suffix.isdigit() else 0
+
+
+def _help_text(family: RunnerFamily) -> str:
+    label = FAMILY_LABELS[family.kind]
+    return (
+        f"Usage: prizmkit-runtime reset {family.kind} <{label}-id|range> [--clean] [--run] "
+        "[--auto-skipped|--failed|--stalled] [list-path]\n"
+        "Reset is a destructive manual operation and is not used for automatic context continuation."
+    )

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

@@ -0,0 +1,51 @@
+"""Bookkeeping git helpers for Python foreground runners.
+
+These helpers model the shell runner bookkeeping boundaries without hiding git
+failures. They are intentionally small wrappers so task runners can preserve the
+legacy ordering around branch creation and final status updates.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .gitops import GitCommandResult, git_status_safe, run_git_command
+from .runner_models import RunnerFamily
+
+
+@dataclass(frozen=True)
+class BookkeepingResult:
+    """Result from an optional bookkeeping commit boundary."""
+
+    attempted: bool
+    committed: bool
+    result: GitCommandResult | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.result is None or self.result.return_code == 0
+
+
+def has_workspace_changes(project_root: Path) -> bool:
+    """Return true when git status has non-hidden-tool worktree changes."""
+    return bool(git_status_safe(project_root).strip())
+
+
+def commit_all_changes(project_root: Path, message: str) -> BookkeepingResult:
+    """Stage and commit current workspace changes when present."""
+    if not has_workspace_changes(project_root):
+        return BookkeepingResult(attempted=False, committed=False)
+    run_git_command(project_root, ("add", "-A", "--", "."))
+    result = run_git_command(project_root, ("commit", "--no-verify", "-m", message))
+    return BookkeepingResult(attempted=True, committed=result.return_code == 0, result=result)
+
+
+def commit_pre_branch_bookkeeping(project_root: Path, family: RunnerFamily, item_id: str) -> BookkeepingResult:
+    """Commit status/list changes before creating the item dev branch."""
+    return commit_all_changes(project_root, f"chore({item_id}): mark in_progress")
+
+
+def commit_final_bookkeeping(project_root: Path, family: RunnerFamily, item_id: str, status: str) -> BookkeepingResult:
+    """Commit final list/state changes after returning to the base branch."""
+    return commit_all_changes(project_root, f"chore({item_id}): update {family.kind} status {status}")

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

@@ -0,0 +1,179 @@
+"""Session classification and continuation helpers for Python runners."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from pathlib import Path
+
+from .gitops import HIDDEN_TOOL_WORKTREE_EXCLUDES, git_status_safe, run_git_command
+from .runner_models import PromptGenerationResult, SessionClassification
+from .sessions import AISessionResult
+
+CONTEXT_OVERFLOW = "context_overflow"
+STALL_REASON = "context_overflow_without_git_checkpoint_or_artifact_progress"
+CONTEXT_MARKERS = (
+    "context_overflow",
+    "input exceeds the context window",
+    "context_length_exceeded",
+    "maximum context length exceeded",
+    "prompt is too long",
+    "too many tokens",
+    "input token count exceeds",
+)
+INFRA_MARKERS = (
+    "rate limit",
+    "overloaded",
+    "gateway",
+    "authentication",
+    "unauthorized",
+    "api error",
+)
+
+
+def classify_session(
+    result: AISessionResult,
+    *,
+    project_root: Path,
+    base_head: str,
+    prompt: PromptGenerationResult | None = None,
+    previous_fingerprint: object | None = None,
+    previous_no_progress_count: int = 0,
+) -> SessionClassification:
+    """Classify raw AI session signals with durable success precedence."""
+    fingerprint = progress_fingerprint(project_root, prompt)
+    if _has_commit_since(project_root, base_head):
+        return SessionClassification("success", reason="commit_since_base", progress_fingerprint=fingerprint)
+
+    if _is_context_overflow(result):
+        no_progress_count = _next_no_progress_count(previous_fingerprint, fingerprint, previous_no_progress_count)
+        if no_progress_count >= 2:
+            return SessionClassification(
+                "stalled_context_continuation",
+                reason=STALL_REASON,
+                fatal_error_code=result.fatal_error_code or CONTEXT_OVERFLOW,
+                progress_fingerprint=fingerprint,
+                no_progress_count=no_progress_count,
+            )
+        return SessionClassification(
+            CONTEXT_OVERFLOW,
+            reason=CONTEXT_OVERFLOW,
+            fatal_error_code=result.fatal_error_code or CONTEXT_OVERFLOW,
+            progress_fingerprint=fingerprint,
+            no_progress_count=no_progress_count,
+        )
+
+    if _is_infra_error(result):
+        return SessionClassification("infra_error", reason="ai_runtime_or_provider_error", progress_fingerprint=fingerprint)
+    if result.termination_reason == "stale_session":
+        return SessionClassification("crashed", reason="stale_session", progress_fingerprint=fingerprint)
+    if result.timed_out or result.termination_reason == "timeout":
+        return SessionClassification("timed_out", reason="timeout", progress_fingerprint=fingerprint)
+    if result.exit_code not in (0, None):
+        return SessionClassification("crashed", reason=f"exit_code={result.exit_code}", progress_fingerprint=fingerprint)
+    if _has_workspace_changes(project_root):
+        _auto_commit_workspace(project_root)
+        return SessionClassification("success", reason="auto_commit_uncommitted_changes", progress_fingerprint=fingerprint)
+    return SessionClassification("crashed", reason="no_durable_success", progress_fingerprint=fingerprint)
+
+
+def progress_fingerprint(project_root: Path, prompt: PromptGenerationResult | None = None) -> dict[str, object]:
+    """Build the no-progress continuation fingerprint used by runner status metadata."""
+    status_text = git_status_safe(project_root)
+    head = run_git_command(project_root, ("rev-parse", "HEAD")).stdout.strip()
+    artifact_hash = ""
+    checkpoint_cursor = ""
+    if prompt and prompt.artifact_path and prompt.artifact_path.exists():
+        artifact_hash = _hash_tree(prompt.artifact_path)
+    if prompt and prompt.checkpoint_path and prompt.checkpoint_path.is_file():
+        try:
+            data = json.loads(prompt.checkpoint_path.read_text(encoding="utf-8"))
+            checkpoint_cursor = _checkpoint_cursor(data)
+        except (OSError, json.JSONDecodeError):
+            checkpoint_cursor = "unreadable"
+    return {
+        "git_diff_fingerprint": hashlib.sha256(status_text.encode()).hexdigest(),
+        "checkpoint_cursor": checkpoint_cursor,
+        "artifact_fingerprint": artifact_hash,
+        "head_commit": head,
+    }
+
+
+def _next_no_progress_count(previous: object | None, current: object, count: int) -> int:
+    if previous and previous == current:
+        return max(0, count) + 1
+    return 0
+
+
+def _is_context_overflow(result: AISessionResult) -> bool:
+    if (result.fatal_error_code or "").lower() == CONTEXT_OVERFLOW:
+        return True
+    text = "\n".join(
+        [
+            result.progress_summary.fatal_error_code,
+            result.progress_summary.terminal_result_text,
+            *result.progress_summary.errors,
+            _tail(result.session_log),
+        ]
+    ).lower()
+    return any(marker in text for marker in CONTEXT_MARKERS)
+
+
+def _is_infra_error(result: AISessionResult) -> bool:
+    text = "\n".join([result.progress_summary.terminal_result_text, *result.progress_summary.errors, _tail(result.session_log)]).lower()
+    return bool(result.fatal_error_code and result.fatal_error_code != CONTEXT_OVERFLOW) or any(marker in text for marker in INFRA_MARKERS)
+
+
+def _has_commit_since(project_root: Path, base_head: str) -> bool:
+    if not base_head:
+        return False
+    current = run_git_command(project_root, ("rev-parse", "HEAD")).stdout.strip()
+    return bool(current and current != base_head)
+
+
+def _has_workspace_changes(project_root: Path) -> bool:
+    return bool(git_status_safe(project_root).strip())
+
+
+def _auto_commit_workspace(project_root: Path) -> None:
+    run_git_command(project_root, ("add", "-A", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES))
+    run_git_command(project_root, ("commit", "--no-verify", "-m", "chore: save runner session changes"))
+
+
+def _tail(path: Path, max_bytes: int = 8192) -> str:
+    try:
+        data = path.read_bytes()
+    except OSError:
+        return ""
+    return data[-max_bytes:].decode("utf-8", errors="ignore")
+
+
+def _hash_tree(path: Path) -> str:
+    digest = hashlib.sha256()
+    if path.is_file():
+        digest.update(path.name.encode())
+        digest.update(path.read_bytes())
+        return digest.hexdigest()
+    for child in sorted(path.rglob("*")):
+        if child.is_file():
+            try:
+                rel = child.relative_to(path).as_posix()
+                digest.update(rel.encode())
+                digest.update(child.read_bytes())
+            except OSError:
+                continue
+    return digest.hexdigest()
+
+
+def _checkpoint_cursor(data: dict[str, object]) -> str:
+    steps = data.get("steps")
+    if not isinstance(steps, list):
+        return ""
+    for step in steps:
+        if not isinstance(step, dict):
+            continue
+        status = step.get("status", "pending")
+        if status not in {"completed", "skipped"}:
+            return f"{step.get('id', '?')}:{step.get('skill', 'unknown')}:{status}"
+    return "complete"