spec-runner 2.3.1__tar.gz → 2.4.1__tar.gz

{spec_runner-2.3.1/src/spec_runner.egg-info → spec_runner-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec-runner
-Version: 2.3.1
+Version: 2.4.1
 Summary: Task automation from markdown specs via Claude CLI
 Author: Andrei
 License-Expression: MIT
@@ -178,6 +178,14 @@ spec-runner report --json                  # JSON matrix output
 # Planning
 spec-runner plan "description"             # Interactive task planning
 spec-runner plan --full "description"      # Generate full spec (requirements + design + tasks)
+spec-runner plan --full --from-file spec.md  # Read the description from a file instead of an arg
+
+# Diagnostics
+spec-runner doctor                              # Probe the configured CLI/model (real mini-task)
+spec-runner doctor --cli=codex --model=gpt-5.4  # Probe an ad-hoc CLI+model
+spec-runner doctor --with-review                # Also probe the review stage
+spec-runner doctor --json --yes                 # Machine-readable, no confirmation (CI)
+spec-runner doctor --strict                     # Exit non-zero on DEGRADED too
 
 # Integration
 spec-runner mcp                            # Launch MCP server (stdio)
@@ -369,7 +377,7 @@ paths:
 | CLI | Auto-detected | Example template |
 |-----|--------------|------------------|
 | Claude | Yes | `{cmd} -p {prompt} --model {model}` |
-| Codex | Yes | `{cmd} -p {prompt} --model {model}` |
+| Codex | Yes | `{cmd} exec -m {model} {prompt}` (codex's `-p` is `--profile`, not the prompt) |
 | OpenCode ([sst/opencode](https://opencode.ai)) | Yes | `{cmd} run --model {model} {prompt}` |
 | Pi Agent ([pi.dev](https://pi.dev)) | Yes (basename match) | `{cmd} -p --model {model} {prompt}` |
 | Ollama | Yes | `{cmd} run {model} {prompt}` |
@@ -381,6 +389,22 @@ paths:
 > script — no core code. See [docs/pi-workflow.md](docs/pi-workflow.md) and the runnable
 > [examples/pi-loop/](examples/pi-loop/).
 
+### Checking CLI/model compatibility
+
+`spec-runner doctor` runs a real one-task probe through the actual execution
+path and reports, per capability, whether your CLI/model works:
+
+- **invocation** — the command runs and authenticates
+- **completion_marker** — the model prints `TASK_COMPLETE` (not all models do)
+- **task_action** — the model actually performs the work
+- **cost_tracking** — token/cost parsing works (needed for `costs`/`--budget`)
+- **error_classification** — failures are classified (diagnostic)
+- **review** *(with `--with-review`)* — the reviewer prints `REVIEW_PASSED`/`FAILED`
+
+Verdict: **READY** / **DEGRADED** (works, but something like cost tracking is
+unavailable) / **BROKEN**. It makes real, billable model calls (capped by
+`--budget`, default $0.50) and asks for confirmation unless `--yes`.
+
 ## Project Structure
 
 ```
@@ -397,6 +421,8 @@ project/
 │       ├── cli_info.py          # Status, costs, logs, validate, verify, report, TUI, MCP
 │       ├── cli_plan.py          # Interactive planning command
 │       ├── execution.py         # Task execution + retry logic
+│       ├── errors.py            # CLI stderr → human-readable failure reasons
+│       ├── stages.py            # Per-task sub-stage tracking (StageReporter)
 │       ├── config.py            # ExecutorConfig + YAML loading
 │       ├── state.py             # SQLite state persistence + degraded-mode fallback
 │       ├── prompt.py            # Prompt building + templates
@@ -413,7 +439,8 @@ project/
 │       ├── report.py            # Traceability matrix generation
 │       ├── validate.py          # Config + task validation
 │       ├── plugins.py           # Plugin discovery + hooks
-│       ├── logging.py           # Structured logging (structlog)
+│       ├── logging.py           # Structured logging (structlog back-compat shim)
+│       ├── obs.py               # OTel JSONL observability emitter (shared contract)
 │       ├── events.py            # EventBus for streaming to TUI
 │       ├── notifications.py     # Telegram + webhook notifications
 │       ├── tui.py               # Textual TUI dashboard

{spec_runner-2.3.1 → spec_runner-2.4.1}/README.md

@@ -143,6 +143,14 @@ spec-runner report --json                  # JSON matrix output
 # Planning
 spec-runner plan "description"             # Interactive task planning
 spec-runner plan --full "description"      # Generate full spec (requirements + design + tasks)
+spec-runner plan --full --from-file spec.md  # Read the description from a file instead of an arg
+
+# Diagnostics
+spec-runner doctor                              # Probe the configured CLI/model (real mini-task)
+spec-runner doctor --cli=codex --model=gpt-5.4  # Probe an ad-hoc CLI+model
+spec-runner doctor --with-review                # Also probe the review stage
+spec-runner doctor --json --yes                 # Machine-readable, no confirmation (CI)
+spec-runner doctor --strict                     # Exit non-zero on DEGRADED too
 
 # Integration
 spec-runner mcp                            # Launch MCP server (stdio)
@@ -334,7 +342,7 @@ paths:
 | CLI | Auto-detected | Example template |
 |-----|--------------|------------------|
 | Claude | Yes | `{cmd} -p {prompt} --model {model}` |
-| Codex | Yes | `{cmd} -p {prompt} --model {model}` |
+| Codex | Yes | `{cmd} exec -m {model} {prompt}` (codex's `-p` is `--profile`, not the prompt) |
 | OpenCode ([sst/opencode](https://opencode.ai)) | Yes | `{cmd} run --model {model} {prompt}` |
 | Pi Agent ([pi.dev](https://pi.dev)) | Yes (basename match) | `{cmd} -p --model {model} {prompt}` |
 | Ollama | Yes | `{cmd} run {model} {prompt}` |
@@ -346,6 +354,22 @@ paths:
 > script — no core code. See [docs/pi-workflow.md](docs/pi-workflow.md) and the runnable
 > [examples/pi-loop/](examples/pi-loop/).
 
+### Checking CLI/model compatibility
+
+`spec-runner doctor` runs a real one-task probe through the actual execution
+path and reports, per capability, whether your CLI/model works:
+
+- **invocation** — the command runs and authenticates
+- **completion_marker** — the model prints `TASK_COMPLETE` (not all models do)
+- **task_action** — the model actually performs the work
+- **cost_tracking** — token/cost parsing works (needed for `costs`/`--budget`)
+- **error_classification** — failures are classified (diagnostic)
+- **review** *(with `--with-review`)* — the reviewer prints `REVIEW_PASSED`/`FAILED`
+
+Verdict: **READY** / **DEGRADED** (works, but something like cost tracking is
+unavailable) / **BROKEN**. It makes real, billable model calls (capped by
+`--budget`, default $0.50) and asks for confirmation unless `--yes`.
+
 ## Project Structure
 
 ```
@@ -362,6 +386,8 @@ project/
 │       ├── cli_info.py          # Status, costs, logs, validate, verify, report, TUI, MCP
 │       ├── cli_plan.py          # Interactive planning command
 │       ├── execution.py         # Task execution + retry logic
+│       ├── errors.py            # CLI stderr → human-readable failure reasons
+│       ├── stages.py            # Per-task sub-stage tracking (StageReporter)
 │       ├── config.py            # ExecutorConfig + YAML loading
 │       ├── state.py             # SQLite state persistence + degraded-mode fallback
 │       ├── prompt.py            # Prompt building + templates
@@ -378,7 +404,8 @@ project/
 │       ├── report.py            # Traceability matrix generation
 │       ├── validate.py          # Config + task validation
 │       ├── plugins.py           # Plugin discovery + hooks
-│       ├── logging.py           # Structured logging (structlog)
+│       ├── logging.py           # Structured logging (structlog back-compat shim)
+│       ├── obs.py               # OTel JSONL observability emitter (shared contract)
 │       ├── events.py            # EventBus for streaming to TUI
 │       ├── notifications.py     # Telegram + webhook notifications
 │       ├── tui.py               # Textual TUI dashboard

{spec_runner-2.3.1 → spec_runner-2.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spec-runner"
-version = "2.3.1"
+version = "2.4.1"
 description = "Task automation from markdown specs via Claude CLI"
 readme = "README.md"
 requires-python = ">=3.10"

{spec_runner-2.3.1 → spec_runner-2.4.1}/src/spec_runner/cli.py

@@ -117,6 +117,27 @@ def _print_dry_run(tasks_to_run: list[Task], config: ExecutorConfig, state: Exec
     print(json.dumps({"dry_run": True, "tasks": data}, indent=2))
 
 
+def _acquire_run_lock(config: ExecutorConfig) -> ExecutorLock:
+    """Acquire the exclusive executor lock, or exit(1) if another run holds it."""
+    lock = ExecutorLock(config.state_file.with_suffix(".lock"))
+    if not lock.acquire():
+        held_by = getattr(lock, "_held_by", {})
+        alive = held_by.get("alive", "true")
+        logger.error(
+            "Another executor is already running",
+            lock_file=str(config.state_file.with_suffix(".lock")),
+            held_by_pid=held_by.get("pid", "unknown"),
+            started=held_by.get("started", "unknown"),
+            process_alive=alive,
+        )
+        if alive == "false":
+            logger.error(
+                "Lock holder is dead. Use --force to override, or delete the lock file manually."
+            )
+        sys.exit(1)
+    return lock
+
+
 def cmd_run(args: argparse.Namespace, config: ExecutorConfig) -> None:
     """Execute tasks."""
     # HITL review incompatible with TUI mode
@@ -124,61 +145,52 @@ def cmd_run(args: argparse.Namespace, config: ExecutorConfig) -> None:
         logger.warning("--hitl-review ignored in TUI mode (TUI owns the screen)")
         config.hitl_review = False
 
-    if getattr(args, "tui", False):
-        import threading
-
-        from .logging import setup_logging
-        from .tui import SpecRunnerApp
+    # Acquire the exclusive lock unless --force. TUI mode also holds it (one
+    # executor per project) — when held, stale-task recovery can safely reset all
+    # orphaned 'running' tasks; with --force a concurrent runner may exist, so we
+    # fall back to the age-based heuristic.
+    if getattr(args, "force", False):
+        logger.warning("Skipping lock check (--force)")
+        lock = None
+    else:
+        lock = _acquire_run_lock(config)
+    lock_held = lock is not None
 
-        # TUI mode: log to file, TUI owns screen
-        log_file = config.logs_dir / f"run-{datetime.now().strftime('%Y%m%d-%H%M%S')}.log"
-        config.logs_dir.mkdir(parents=True, exist_ok=True)
-        setup_logging(level=config.log_level, tui_mode=True, log_file=log_file)
+    try:
+        if getattr(args, "tui", False):
+            import threading
 
-        app = SpecRunnerApp(config=config)
+            from .logging import setup_logging
+            from .tui import SpecRunnerApp
 
-        def _start_execution() -> None:
-            t = threading.Thread(target=lambda: _run_tasks(args, config), daemon=True)
-            t.start()
+            # TUI mode: log to file, TUI owns screen
+            log_file = config.logs_dir / f"run-{datetime.now().strftime('%Y%m%d-%H%M%S')}.log"
+            config.logs_dir.mkdir(parents=True, exist_ok=True)
+            setup_logging(level=config.log_level, tui_mode=True, log_file=log_file)
 
-        app.call_later(_start_execution)
-        app.run()
-        return
+            app = SpecRunnerApp(config=config)
 
-    if getattr(args, "force", False):
-        logger.warning("Skipping lock check (--force)")
-        _run_tasks(args, config)
-    else:
-        # Acquire lock to prevent concurrent runs
-        lock = ExecutorLock(config.state_file.with_suffix(".lock"))
-        if not lock.acquire():
-            held_by = getattr(lock, "_held_by", {})
-            pid = held_by.get("pid", "unknown")
-            started = held_by.get("started", "unknown")
-            alive = held_by.get("alive", "true")
-
-            logger.error(
-                "Another executor is already running",
-                lock_file=str(config.state_file.with_suffix(".lock")),
-                held_by_pid=pid,
-                started=started,
-                process_alive=alive,
-            )
-            if alive == "false":
-                logger.error(
-                    "Lock holder is dead. Use --force to override, "
-                    "or delete the lock file manually."
+            def _start_execution() -> None:
+                t = threading.Thread(
+                    target=lambda: _run_tasks(args, config, lock_held=lock_held), daemon=True
                 )
-            sys.exit(1)
+                t.start()
 
-        try:
-            _run_tasks(args, config)
-        finally:
+            app.call_later(_start_execution)
+            app.run()
+        else:
+            _run_tasks(args, config, lock_held=lock_held)
+    finally:
+        if lock is not None:
             lock.release()
 
 
-def _run_tasks(args, config: ExecutorConfig):
-    """Internal task execution logic."""
+def _run_tasks(args, config: ExecutorConfig, *, lock_held: bool = False):
+    """Internal task execution logic.
+
+    lock_held: True when the caller holds the exclusive executor lock, so any
+    orphaned 'running' task can be safely reset regardless of age.
+    """
     # Clear any leftover stop file from previous runs
     clear_stop_file(config)
 
@@ -194,17 +206,23 @@ def _run_tasks(args, config: ExecutorConfig):
             task_filter=getattr(args, "task", None),
         )
 
-        # Recover tasks stuck in 'running' from previous crash
+        # Recover tasks stuck in 'running' from a previous crashed/interrupted run.
+        # When we hold the exclusive lock (lock_held), no other runner exists — any
+        # 'running' task is orphaned and is reset regardless of age (otherwise a
+        # session interruption, e.g. a dropped remote shell, leaves a half-done
+        # task that the next run re-picks first and hangs re-doing it). Without the
+        # lock (--force), a concurrent runner may be active, so fall back to the
+        # age-based heuristic (2x the task timeout).
         stale_timeout = config.task_timeout_minutes * 2
-        recovered = recover_stale_tasks(state, stale_timeout, config.tasks_file)
+        recovered = recover_stale_tasks(
+            state, stale_timeout, config.tasks_file, recover_all=lock_held
+        )
         if recovered:
             logger.warning("Recovered stale tasks", task_ids=recovered)
             tasks = parse_tasks(config.tasks_file)
 
         # v2.3.0: reset failed-task state on `run --all` unless opted out.
-        reset_enabled = getattr(args, "all", False) and not getattr(
-            args, "no_reset_failed", False
-        )
+        reset_enabled = getattr(args, "all", False) and not getattr(args, "no_reset_failed", False)
         previously_failed: set[str] = set()  # used by T17 second-pass detection
         if reset_enabled:
             previously_failed = state.reset_failed_to_pending()
@@ -416,8 +434,7 @@ def _run_tasks(args, config: ExecutorConfig):
                     else:
                         stop_reason = "max_consecutive_failures"
                         stop_detail = (
-                            f"{state.consecutive_failures}/"
-                            f"{config.max_consecutive_failures}"
+                            f"{state.consecutive_failures}/{config.max_consecutive_failures}"
                         )
                     logger.warning("Stopping: too many consecutive failures")
                     break
@@ -460,8 +477,7 @@ def _run_tasks(args, config: ExecutorConfig):
                     else:
                         stop_reason = "max_consecutive_failures"
                         stop_detail = (
-                            f"{state.consecutive_failures}/"
-                            f"{config.max_consecutive_failures}"
+                            f"{state.consecutive_failures}/{config.max_consecutive_failures}"
                         )
                     logger.warning("Stopping: too many consecutive failures")
                     break
@@ -663,6 +679,25 @@ def cmd_watch(args: argparse.Namespace, config: ExecutorConfig) -> None:
         time.sleep(1)
 
 
+def cmd_doctor(args: argparse.Namespace, config: ExecutorConfig) -> None:
+    """Run the CLI/model compatibility probe and exit with its status code."""
+    from .doctor import run_doctor
+
+    code = run_doctor(
+        config,
+        cli=args.cli,
+        model=args.model,
+        with_review=args.with_review,
+        budget=args.budget,
+        timeout_min=getattr(args, "timeout", None),
+        assume_yes=args.yes,
+        strict=args.strict,
+        as_json=args.json,
+        keep=args.keep,
+    )
+    raise SystemExit(code)
+
+
 # === Main ===
 
 
@@ -853,7 +888,14 @@ def _build_parser() -> argparse.ArgumentParser:
 
     # plan
     plan_parser = subparsers.add_parser("plan", parents=[common], help="Interactive task planning")
-    plan_parser.add_argument("description", help="Feature description")
+    plan_parser.add_argument(
+        "description", nargs="?", default=None, help="Feature description (or use --from-file)"
+    )
+    plan_parser.add_argument(
+        "--from-file",
+        metavar="PATH",
+        help="Read the feature description from a file instead of the positional argument",
+    )
     plan_parser.add_argument(
         "--full",
         action="store_true",
@@ -943,6 +985,28 @@ def _build_parser() -> argparse.ArgumentParser:
     # mcp
     subparsers.add_parser("mcp", parents=[common], help="Launch read-only MCP server")
 
+    # doctor
+    doctor_parser = subparsers.add_parser(
+        "doctor", parents=[common], help="Probe CLI/model compatibility (real mini-task)"
+    )
+    doctor_parser.add_argument("--cli", help="Override the CLI command (claude/codex/pi/...)")
+    doctor_parser.add_argument("--model", help="Override the model (executor + review)")
+    doctor_parser.add_argument(
+        "--with-review",
+        action="store_true",
+        help="Also probe the review stage (2nd model call)",
+    )
+    doctor_parser.add_argument(
+        "--yes", "-y", action="store_true", help="Skip the cost-gate confirmation"
+    )
+    doctor_parser.add_argument(
+        "--strict", action="store_true", help="Exit non-zero on DEGRADED too"
+    )
+    doctor_parser.add_argument("--json", action="store_true", help="Machine-readable output")
+    doctor_parser.add_argument("--keep", action="store_true", help="Keep the scratch workspace")
+    # --budget is inherited from common (default None); override default to 0.50 for doctor
+    doctor_parser.set_defaults(budget=0.5)
+
     # task (unified: replaces spec-task binary)
     task_parser = subparsers.add_parser(
         "task", help="Task management (list, show, start, done, graph, sync)"
@@ -1038,6 +1102,7 @@ def main():
         "tui": cmd_tui,
         "watch": cmd_watch,
         "mcp": cmd_mcp,
+        "doctor": cmd_doctor,
     }
 
     # Handle unified task subcommand

{spec_runner-2.3.1 → spec_runner-2.4.1}/src/spec_runner/cli_plan.py

@@ -4,6 +4,7 @@ import re
 import subprocess
 import sys
 from datetime import datetime
+from pathlib import Path
 
 from .config import ExecutorConfig
 from .logging import get_logger
@@ -23,6 +24,32 @@ from .task import (
 logger = get_logger("cli")
 
 
+def resolve_plan_description(description: str | None, from_file: str | None) -> str:
+    """Resolve the plan description from --from-file (preferred) or the positional
+    argument. Exits with an error if neither is usable.
+
+    Args:
+        description: the positional description (may be None when --from-file is used).
+        from_file: path to a file whose contents are the description.
+    """
+    if from_file:
+        path = Path(from_file)
+        if not path.is_file():
+            raise SystemExit(f"plan --from-file: not a readable file: {from_file}")
+        try:
+            text = path.read_text(encoding="utf-8").strip()
+        except UnicodeDecodeError as e:
+            raise SystemExit(f"plan --from-file: not valid UTF-8 text: {from_file}") from e
+        except OSError as e:
+            raise SystemExit(f"plan --from-file: cannot read {from_file}: {e}") from e
+        if not text:
+            raise SystemExit(f"plan --from-file: file is empty: {from_file}")
+        return text
+    if description and description.strip():
+        return description
+    raise SystemExit("plan: provide a description argument or --from-file PATH")
+
+
 def cmd_plan(args, config: ExecutorConfig):
     """Interactive task planning via Claude.
 
@@ -30,7 +57,7 @@ def cmd_plan(args, config: ExecutorConfig):
     requirements, design, and tasks files from a description.
     """
 
-    description = args.description
+    description = resolve_plan_description(args.description, getattr(args, "from_file", None))
 
     if getattr(args, "full", False):
         from .prompt import build_generation_prompt, parse_spec_marker

{spec_runner-2.3.1 → spec_runner-2.4.1}/src/spec_runner/config.py

@@ -153,6 +153,7 @@ class ExecutorConfig:
     create_git_branch: bool = True  # Create branch on start
     auto_commit: bool = True  # Auto-commit on success
     main_branch: str = ""  # Main branch name (empty = auto-detect: main/master)
+    sync_deps: bool = True  # Run `uv sync` in pre_start_hook (doctor disables this)
 
     # Code review
     run_review: bool = True  # Run code review after task completion
@@ -377,6 +378,7 @@ def load_config_from_yaml(config_path: Path | None = None) -> dict:
             "claude_model": executor_config.get("claude_model"),
             "skip_permissions": executor_config.get("skip_permissions"),
             "create_git_branch": pre_start.get("create_git_branch"),
+            "sync_deps": pre_start.get("sync_deps"),
             "main_branch": executor_config.get("main_branch"),
             "run_tests_on_done": post_done.get("run_tests"),
             "run_lint_on_done": post_done.get("run_lint"),