tasks-toolkit 0.1.4__tar.gz → 0.1.6__tar.gz

{tasks_toolkit-0.1.4/tasks_toolkit.egg-info → tasks_toolkit-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasks-toolkit
-Version: 0.1.4
+Version: 0.1.6
 Summary: Task tracker toolkit: CLI + MCP server for sprint/task/subtask management, delegation helpers.
 Author: prachwal
 License: MIT License
@@ -101,17 +101,112 @@ export TASKS_ROOT=/path/to/data
 python3 scripts/tasks.py overview
 ```
 
-## MCP (OpenCode)
+## MCP clients
 
-```jsonc
-"tasks": {
-  "type": "local",
-  "command": ["python3", "{env:HOME}/src/tasks-toolkit/scripts/tasks_mcp.py"],
-  "cwd": "{env:HOME}/src/tasks-toolkit",
-  "environment": { "TASKS_ROOT": "{env:HOME}/src/tasks-toolkit" }
+The `tasks-mcp` command runs the same stdio server for every client. Set `TASKS_ROOT`
+to the absolute path of the project whose tasks you want to manage. It points to
+the project, not to the toolkit installation. An installed server needs no copy of
+this source repository. Use an absolute executable path if the client cannot find
+`tasks-mcp` on its PATH; `command -v tasks-mcp` shows it on Unix.
+
+### Claude Desktop
+
+Open **Settings → Developer → Edit Config**, merge this entry into
+`claude_desktop_config.json`, and restart the app:
+
+```json
+{
+  "mcpServers": {
+    "tasks": {
+      "command": "/absolute/path/to/tasks-mcp",
+      "args": [],
+      "env": {"TASKS_ROOT": "/absolute/path/to/your-project"}
+    }
+  }
+}
+```
+
+See the [official local-server setup guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers)
+for configuration locations and troubleshooting. The toolkit currently uses POSIX
+file locking (`fcntl`); run the server on macOS or Linux. The Windows Desktop app
+needs a launcher into a Linux environment such as WSL, rather than a native Windows
+Python process.
+
+### Claude Code
+
+From your project directory, register a project-scoped stdio server:
+
+```bash
+claude mcp add --transport stdio --scope project \
+  --env TASKS_ROOT="$(pwd)" tasks -- /absolute/path/to/tasks-mcp
+claude mcp list
+```
+
+Claude Code saves project-scoped servers to `.mcp.json`; see its
+[official MCP documentation](https://code.claude.com/docs/en/mcp).
+
+### VS Code / GitHub Copilot
+
+Add a server to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "tasks": {
+      "type": "stdio",
+      "command": "/absolute/path/to/tasks-mcp",
+      "args": [],
+      "env": {"TASKS_ROOT": "${workspaceFolder}"}
+    }
+  }
 }
 ```
 
+See [VS Code's MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).
+
+### Cursor
+
+Add this to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for all projects):
+
+```json
+{
+  "mcpServers": {
+    "tasks": {
+      "command": "/absolute/path/to/tasks-mcp",
+      "env": {"TASKS_ROOT": "/absolute/path/to/your-project"}
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add this entry to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "tasks": {
+      "type": "local",
+      "command": ["/absolute/path/to/tasks-mcp"],
+      "enabled": true,
+      "environment": {"TASKS_ROOT": "/absolute/path/to/your-project"}
+    }
+  }
+}
+```
+
+See the [OpenCode MCP documentation](https://opencode.ai/docs/mcp-servers/).
+
+### Other stdio clients and source installs
+
+Configure any MCP client to launch `tasks-mcp`, use stdio transport and pass
+`TASKS_ROOT` in the server environment. Clients use different JSON keys; adapt one
+of the examples above to the client's schema. To run from a source checkout,
+replace the executable with `python3` and pass
+`/absolute/path/to/tasks-toolkit/scripts/tasks_mcp.py` as its first argument
+(or use that two-element array for OpenCode's `command`).
+
 ## Verified task and sprint execution
 
 Copy `.tasks-toolkit.example.json` to `.tasks-toolkit.json`, choose the checks for
@@ -119,12 +214,40 @@ Copy `.tasks-toolkit.example.json` to `.tasks-toolkit.json`, choose the checks f
 no shell interpolation is performed. Every configured check must pass. Keep
 `tmp/` and generated `tasks/` files in `.gitignore`, as in this repository.
 
-The default coder uses [Codex non-interactive mode](https://developers.openai.com/codex/noninteractive):
-`codex exec --sandbox workspace-write -`. Install and authenticate its CLI separately.
-To use Junie or Kilo, set `runners.junie` or `runners.kilo` to the argument array for
-your local adapter. Adapters receive the spec on stdin, edit files in their current
-working directory, leave changes uncommitted, and return nonzero on failure.
-The same `runners.codex` setting can select a custom Codex adapter.
+Runner names and commands are defined entirely in `.tasks-toolkit.json`:
+
+```json
+{
+  "default_runner": "coder",
+  "runners": {
+    "coder": ["python3", "tools/coder_adapter.py"],
+    "backup-coder": ["/absolute/path/to/another-adapter"]
+  },
+  "checks": [["python3", "-m", "pytest", "-q"]],
+  "timeout": 120
+}
+```
+
+Replace these sample adapter commands with your own. Adapters receive the spec on
+stdin, edit files in their current working directory, leave changes uncommitted,
+and return nonzero on failure. There are no built-in providers or model choices.
+`--runner NAME` selects any registered adapter; otherwise `default_runner` is used.
+If no default is configured, select a runner explicitly. `--fallback NAME` uses
+the same registry; `none` is reserved to disable fallback. Reports and statistics
+accept any runner name containing letters, digits, underscores and hyphens.
+
+Optional `protected_paths` adds project-specific files or directories to the built-in
+protection, for example `"protected_paths": ["config/private/", "./credentials.json"]`.
+Entries are relative to the project root; `./` and trailing separators are normalized.
+Absolute paths and entries containing `..` are rejected. Directory entries protect
+the directory and its descendants. Planner commands resolve the project using the
+same current-directory, Git-worktree and `TASKS_ROOT` rules as the tracker; their
+helper scripts are loaded from the toolkit installation.
+
+When upgrading from 0.1.4, register the command you previously relied on explicitly:
+implicit provider commands and the implicit default have been removed. Existing
+checkpoint and report runner names remain valid when registered in the configuration.
+Changing configuration still invalidates a resume checkpoint's approval fingerprint.
 
 Installed commands are `tasks-run` and `tasks-sprint`; from source, the corresponding
 wrappers are `scripts/run-task.sh` and `scripts/sprint-auto.sh`.
@@ -133,7 +256,7 @@ Run one task in a clean working tree, with an explicit allowed scope:
 
 ```bash
 tasks-run result \
-  --file tmp/tasks/result.md --scope src/ --runner codex
+  --file tmp/tasks/result.md --scope src/ --runner coder
 ```
 
 Alternatively, `--task-id 1.1` reads scope links from the tracker. The runner checks
@@ -147,14 +270,15 @@ that left the working tree clean.
 For a complete sprint, supply a plan containing `sprint` (`slug`, `title`, `goal`)
 and `tasks` (`key`, `title`, `scope`, `spec_name`, `spec`, `depends_on`). Specs must
 pass `scripts/spec-lint.sh`; dependencies reference earlier task keys. An answers
-file binds the reviewed goal, allowed paths and execution policy:
+file binds the reviewed goal, allowed paths and execution policy. `policy.runner`
+overrides the configured default; delegated decisions use the same registry:
 
 ```json
 {
   "goal_reviewed": true,
   "allowed_scopes": ["src/"],
   "policy": {
-    "runner": "codex", "serial": true, "fallback": "none", "retries": 0,
+    "runner": "coder", "serial": true, "fallback": "none", "retries": 0,
     "push": false, "accept_flags": false, "reset": false, "clean": false
   }
 }
@@ -220,6 +344,7 @@ builds to pass. VS Code tracker commands are provided in `.vscode/tasks.json`.
 | `sprint_auto_resume.py` | Resume and finish owned sprints. |
 | `apply-plan.sh` | Import a validated sprint plan (`tmp/plans/<name>.json`) into the tracker. |
 | `run-task.sh` / `task_runner.py` | Run configured coders and verify actual changes before committing. |
+| `runner_config.py` | Provider-independent runner registry, default selection and configuration validation. |
 | `task-report.sh` | Report delegation progress to the tracker. |
 | `run_summary.py` | Write a run summary JSON for finished runs. |
 | `run_stats.py` | Delivery-speed statistics for delegation runners. |

{tasks_toolkit-0.1.4 → tasks_toolkit-0.1.6}/README.md

@@ -52,17 +52,112 @@ export TASKS_ROOT=/path/to/data
 python3 scripts/tasks.py overview
 ```
 
-## MCP (OpenCode)
-
-```jsonc
-"tasks": {
-  "type": "local",
-  "command": ["python3", "{env:HOME}/src/tasks-toolkit/scripts/tasks_mcp.py"],
-  "cwd": "{env:HOME}/src/tasks-toolkit",
-  "environment": { "TASKS_ROOT": "{env:HOME}/src/tasks-toolkit" }
+## MCP clients
+
+The `tasks-mcp` command runs the same stdio server for every client. Set `TASKS_ROOT`
+to the absolute path of the project whose tasks you want to manage. It points to
+the project, not to the toolkit installation. An installed server needs no copy of
+this source repository. Use an absolute executable path if the client cannot find
+`tasks-mcp` on its PATH; `command -v tasks-mcp` shows it on Unix.
+
+### Claude Desktop
+
+Open **Settings → Developer → Edit Config**, merge this entry into
+`claude_desktop_config.json`, and restart the app:
+
+```json
+{
+  "mcpServers": {
+    "tasks": {
+      "command": "/absolute/path/to/tasks-mcp",
+      "args": [],
+      "env": {"TASKS_ROOT": "/absolute/path/to/your-project"}
+    }
+  }
+}
+```
+
+See the [official local-server setup guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers)
+for configuration locations and troubleshooting. The toolkit currently uses POSIX
+file locking (`fcntl`); run the server on macOS or Linux. The Windows Desktop app
+needs a launcher into a Linux environment such as WSL, rather than a native Windows
+Python process.
+
+### Claude Code
+
+From your project directory, register a project-scoped stdio server:
+
+```bash
+claude mcp add --transport stdio --scope project \
+  --env TASKS_ROOT="$(pwd)" tasks -- /absolute/path/to/tasks-mcp
+claude mcp list
+```
+
+Claude Code saves project-scoped servers to `.mcp.json`; see its
+[official MCP documentation](https://code.claude.com/docs/en/mcp).
+
+### VS Code / GitHub Copilot
+
+Add a server to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "tasks": {
+      "type": "stdio",
+      "command": "/absolute/path/to/tasks-mcp",
+      "args": [],
+      "env": {"TASKS_ROOT": "${workspaceFolder}"}
+    }
+  }
+}
+```
+
+See [VS Code's MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).
+
+### Cursor
+
+Add this to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for all projects):
+
+```json
+{
+  "mcpServers": {
+    "tasks": {
+      "command": "/absolute/path/to/tasks-mcp",
+      "env": {"TASKS_ROOT": "/absolute/path/to/your-project"}
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add this entry to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "tasks": {
+      "type": "local",
+      "command": ["/absolute/path/to/tasks-mcp"],
+      "enabled": true,
+      "environment": {"TASKS_ROOT": "/absolute/path/to/your-project"}
+    }
+  }
 }
 ```
 
+See the [OpenCode MCP documentation](https://opencode.ai/docs/mcp-servers/).
+
+### Other stdio clients and source installs
+
+Configure any MCP client to launch `tasks-mcp`, use stdio transport and pass
+`TASKS_ROOT` in the server environment. Clients use different JSON keys; adapt one
+of the examples above to the client's schema. To run from a source checkout,
+replace the executable with `python3` and pass
+`/absolute/path/to/tasks-toolkit/scripts/tasks_mcp.py` as its first argument
+(or use that two-element array for OpenCode's `command`).
+
 ## Verified task and sprint execution
 
 Copy `.tasks-toolkit.example.json` to `.tasks-toolkit.json`, choose the checks for
@@ -70,12 +165,40 @@ Copy `.tasks-toolkit.example.json` to `.tasks-toolkit.json`, choose the checks f
 no shell interpolation is performed. Every configured check must pass. Keep
 `tmp/` and generated `tasks/` files in `.gitignore`, as in this repository.
 
-The default coder uses [Codex non-interactive mode](https://developers.openai.com/codex/noninteractive):
-`codex exec --sandbox workspace-write -`. Install and authenticate its CLI separately.
-To use Junie or Kilo, set `runners.junie` or `runners.kilo` to the argument array for
-your local adapter. Adapters receive the spec on stdin, edit files in their current
-working directory, leave changes uncommitted, and return nonzero on failure.
-The same `runners.codex` setting can select a custom Codex adapter.
+Runner names and commands are defined entirely in `.tasks-toolkit.json`:
+
+```json
+{
+  "default_runner": "coder",
+  "runners": {
+    "coder": ["python3", "tools/coder_adapter.py"],
+    "backup-coder": ["/absolute/path/to/another-adapter"]
+  },
+  "checks": [["python3", "-m", "pytest", "-q"]],
+  "timeout": 120
+}
+```
+
+Replace these sample adapter commands with your own. Adapters receive the spec on
+stdin, edit files in their current working directory, leave changes uncommitted,
+and return nonzero on failure. There are no built-in providers or model choices.
+`--runner NAME` selects any registered adapter; otherwise `default_runner` is used.
+If no default is configured, select a runner explicitly. `--fallback NAME` uses
+the same registry; `none` is reserved to disable fallback. Reports and statistics
+accept any runner name containing letters, digits, underscores and hyphens.
+
+Optional `protected_paths` adds project-specific files or directories to the built-in
+protection, for example `"protected_paths": ["config/private/", "./credentials.json"]`.
+Entries are relative to the project root; `./` and trailing separators are normalized.
+Absolute paths and entries containing `..` are rejected. Directory entries protect
+the directory and its descendants. Planner commands resolve the project using the
+same current-directory, Git-worktree and `TASKS_ROOT` rules as the tracker; their
+helper scripts are loaded from the toolkit installation.
+
+When upgrading from 0.1.4, register the command you previously relied on explicitly:
+implicit provider commands and the implicit default have been removed. Existing
+checkpoint and report runner names remain valid when registered in the configuration.
+Changing configuration still invalidates a resume checkpoint's approval fingerprint.
 
 Installed commands are `tasks-run` and `tasks-sprint`; from source, the corresponding
 wrappers are `scripts/run-task.sh` and `scripts/sprint-auto.sh`.
@@ -84,7 +207,7 @@ Run one task in a clean working tree, with an explicit allowed scope:
 
 ```bash
 tasks-run result \
-  --file tmp/tasks/result.md --scope src/ --runner codex
+  --file tmp/tasks/result.md --scope src/ --runner coder
 ```
 
 Alternatively, `--task-id 1.1` reads scope links from the tracker. The runner checks
@@ -98,14 +221,15 @@ that left the working tree clean.
 For a complete sprint, supply a plan containing `sprint` (`slug`, `title`, `goal`)
 and `tasks` (`key`, `title`, `scope`, `spec_name`, `spec`, `depends_on`). Specs must
 pass `scripts/spec-lint.sh`; dependencies reference earlier task keys. An answers
-file binds the reviewed goal, allowed paths and execution policy:
+file binds the reviewed goal, allowed paths and execution policy. `policy.runner`
+overrides the configured default; delegated decisions use the same registry:
 
 ```json
 {
   "goal_reviewed": true,
   "allowed_scopes": ["src/"],
   "policy": {
-    "runner": "codex", "serial": true, "fallback": "none", "retries": 0,
+    "runner": "coder", "serial": true, "fallback": "none", "retries": 0,
     "push": false, "accept_flags": false, "reset": false, "clean": false
   }
 }
@@ -171,6 +295,7 @@ builds to pass. VS Code tracker commands are provided in `.vscode/tasks.json`.
 | `sprint_auto_resume.py` | Resume and finish owned sprints. |
 | `apply-plan.sh` | Import a validated sprint plan (`tmp/plans/<name>.json`) into the tracker. |
 | `run-task.sh` / `task_runner.py` | Run configured coders and verify actual changes before committing. |
+| `runner_config.py` | Provider-independent runner registry, default selection and configuration validation. |
 | `task-report.sh` | Report delegation progress to the tracker. |
 | `run_summary.py` | Write a run summary JSON for finished runs. |
 | `run_stats.py` | Delivery-speed statistics for delegation runners. |

{tasks_toolkit-0.1.4 → tasks_toolkit-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tasks-toolkit"
-version = "0.1.4"
+version = "0.1.6"
 description = "Task tracker toolkit: CLI + MCP server for sprint/task/subtask management, delegation helpers."
 readme = "README.md"
 license = { file = "LICENSE" }

{tasks_toolkit-0.1.4 → tasks_toolkit-0.1.6}/scripts/run_stats.py

@@ -2,7 +2,7 @@
 """Delivery-speed statistics for the delegation runners.
 
 Reads tmp/runs/<name>.summary.json when present (exact) and falls back to the last line of
-tmp/runs/<name>.status for older runs ("[mm:ss] done - junie exit 0, verification PASSED").
+tmp/runs/<name>.status for older runs ("[mm:ss] done - worker exit 0, verification PASSED").
 A run whose status never reached "done" counts as unfinished (killed, stalled or crashed).
 Prints, per runner: runs, verified, failed, unfinished, median and p90 duration, plus the
 share of runs that did not end verified ("rework rate"). Standard library only, read-only.
@@ -21,7 +21,7 @@ from pathlib import Path
 
 LAST_STAMP = re.compile(r"^\[(\d+):(\d{2})\]\s+(.*)$")
 RUNNER_TAIL = re.compile(r"\brunner=(\w+)")
-DONE_RUNNER = re.compile(r"^done - (junie|kilo|codex|haiku) exit (\d+), verification (PASSED|FAILED)")
+DONE_RUNNER = re.compile(r"^done - ([A-Za-z0-9][A-Za-z0-9_-]*) exit (\d+), verification (PASSED|FAILED)")
 
 
 def parse_status(path: Path) -> dict | None:

{tasks_toolkit-0.1.4 → tasks_toolkit-0.1.6}/scripts/run_summary.py

@@ -11,13 +11,13 @@ Usage: scripts/run_summary.py <outfile> <key=value> [<key=value> ...]
 
 Keys:
     name, runner, model, task_id, patch    str (required)
-    agent                                  str (required for runner=kilo only)
+    agent                                  str (optional, for any runner)
     started, finished                      int, epoch seconds (required)
     agent_exit, verify_exit                int (required)
     files_changed                          int (required)
     verdict                                verified|verify_failed|agent_failed
 
-duration_s is derived as finished - started. Unknown keys, a wrong runner or verdict, or
+duration_s is derived as finished - started. Unknown keys, an invalid runner name or verdict, or
 a missing field are errors and nothing is written. Output is deterministic (sorted keys,
 2-space indent, trailing newline).
 """
@@ -25,11 +25,14 @@ from __future__ import annotations
 
 import json
 import sys
+from pathlib import Path
 from typing import Any
 
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from scripts.runner_config import valid_runner_name
+
 STR_FIELDS = ("name", "runner", "model", "agent", "task_id", "patch", "verdict")
 INT_FIELDS = ("started", "finished", "agent_exit", "verify_exit", "files_changed")
-RUNNERS = ("junie", "kilo", "codex")
 VERDICTS = ("verified", "verify_failed", "agent_failed")
 
 
@@ -63,19 +66,12 @@ def main(argv: list[str]) -> int:
         print(f"error: missing fields: {', '.join(missing)}", file=sys.stderr)
         return 2
 
-    if data["runner"] not in RUNNERS:
-        print(f"error: runner must be one of {', '.join(RUNNERS)}, got {data['runner']!r}", file=sys.stderr)
+    if not valid_runner_name(data["runner"]):
+        print("error: runner must be a name containing letters, digits, underscores or hyphens; 'none' is reserved", file=sys.stderr)
         return 2
     if data["verdict"] not in VERDICTS:
         print(f"error: verdict must be one of {', '.join(VERDICTS)}, got {data['verdict']!r}", file=sys.stderr)
         return 2
-    if data["runner"] == "kilo" and "agent" not in data:
-        print("error: field 'agent' is required for runner=kilo", file=sys.stderr)
-        return 2
-    if data["runner"] == "junie" and "agent" in data:
-        print("error: field 'agent' is only allowed for runner=kilo", file=sys.stderr)
-        return 2
-
     duration = int(data["finished"]) - int(data["started"])
     if duration < 0:
         print("error: finished is before started", file=sys.stderr)

tasks_toolkit-0.1.6/scripts/runner_config.py

@@ -0,0 +1,104 @@
+"""Provider-independent runner registry and execution configuration.
+
+Each registered command receives a task spec on stdin and runs in the task
+worktree. Providers and their CLI arguments belong in project configuration.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path, PurePosixPath, PureWindowsPath
+
+CONFIG_FILE = ".tasks-toolkit.json"
+RUNNER_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]*")
+
+# Always protected: version control, the tracker's own data and the config itself.
+# Project-specific paths (agent or tool config dirs) go in `protected_paths` in CONFIG_FILE.
+BUILTIN_PROTECTED = (".git", ".githooks", "tmp", "tasks/tasks.db", "tasks/.lock", CONFIG_FILE)
+
+
+class RunnerError(Exception):
+    """Runner configuration or an execution prerequisite is invalid."""
+
+
+def _normalize_protected_path(path: object) -> str:
+    """Normalize harmless dot/separator spelling and reject ambiguous or escaping paths."""
+    if not isinstance(path, str) or not path or path != path.strip():
+        raise RunnerError("protected_paths entries must be non-empty repo-relative paths")
+    if (PurePosixPath(path).is_absolute() or PureWindowsPath(path).drive or "\\" in path
+            or ".." in path.split("/") or any(ord(char) < 32 for char in path)):
+        raise RunnerError(f"protected_paths entry must be repo-relative without '..': {path!r}")
+    normalized = str(PurePosixPath(path))
+    if normalized == ".":
+        raise RunnerError("protected_paths entries must name a file or directory inside the project")
+    return normalized
+
+
+def protected_paths(root: Path) -> tuple[str, ...]:
+    """Built-in protected paths plus `protected_paths` from the project config, if present."""
+    path = root / CONFIG_FILE
+    extra: object = []
+    if path.is_file():
+        config = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(config, dict):
+            raise RunnerError("runner config must be an object")
+        extra = config.get("protected_paths", [])
+    if not isinstance(extra, list):
+        raise RunnerError("protected_paths must be a list of repo-relative paths")
+    return BUILTIN_PROTECTED + tuple(_normalize_protected_path(p) for p in extra)
+
+
+def is_protected(path: str, protected: tuple[str, ...]) -> bool:
+    path = str(PurePosixPath(path))
+    return any(path == p or path.startswith(p + "/") for p in protected)
+
+
+def valid_runner_name(name: object) -> bool:
+    return isinstance(name, str) and name != "none" and RUNNER_NAME.fullmatch(name) is not None
+
+
+def valid_command(command: object) -> bool:
+    return isinstance(command, list) and bool(command) and all(isinstance(v, str) and bool(v) for v in command)
+
+
+def runner_command(config: dict, runner: str) -> list[str]:
+    if not valid_runner_name(runner):
+        raise RunnerError("runner must be a name containing letters, digits, underscores or hyphens; 'none' is reserved")
+    command = config.get("runners", {}).get(runner)
+    if not valid_command(command):
+        raise RunnerError(f"configure runners.{runner} in {CONFIG_FILE}; the command receives the spec on stdin")
+    return list(command)
+
+
+def select_runner(config: dict, requested: str | None = None) -> str:
+    name = requested if requested is not None else config.get("default_runner")
+    if name is None:
+        raise RunnerError(f"choose --runner or policy.runner, or set default_runner in {CONFIG_FILE}")
+    runner_command(config, name)
+    return str(name)
+
+
+def load_config(root: Path) -> dict:
+    path = root / CONFIG_FILE
+    if not path.is_file():
+        raise RunnerError(f"create {CONFIG_FILE} with runners and a non-empty checks list before running tasks")
+    config = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(config, dict):
+        raise RunnerError("runner config must be an object")
+    checks = config.get("checks")
+    if not isinstance(checks, list) or not checks or not all(valid_command(c) for c in checks):
+        raise RunnerError("checks must be a non-empty list of command argument arrays")
+    runners = config.get("runners")
+    if not isinstance(runners, dict) or not runners:
+        raise RunnerError("runners must be a non-empty mapping of names to command argument arrays")
+    for name in runners:
+        runner_command(config, name)
+    if "default_runner" in config:
+        if not valid_runner_name(config["default_runner"]):
+            raise RunnerError("default_runner must name a configured runner")
+        select_runner(config)
+    timeout = config.get("timeout", 120)
+    if type(timeout) is not int or timeout < 1:
+        raise RunnerError("timeout must be a positive integer")
+    protected_paths(root)  # validates the optional protected_paths list
+    return config

{tasks_toolkit-0.1.4 → tasks_toolkit-0.1.6}/scripts/sprint_auto.py

@@ -10,6 +10,7 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 from scripts import sprint_auto_execute as execute
+from scripts import sprint_auto_preflight as preflight
 from scripts import sprint_auto_prepare as prepare
 from scripts import sprint_auto_state as sas
 from scripts import task_runner as runner
@@ -61,7 +62,10 @@ def run(root: Path, goal: str, name: str, answers: dict, plan: Path) -> dict:
     if not runner.NAME.fullmatch(name):
         raise runner.RunnerError("invalid run name")
     config = runner.load_config(root)
-    policy = answers.get("policy", {})
+    report = preflight.collect_preflight(root, {"goal": goal}, answers)
+    if report["blockers"] or report["questions"]:
+        return {"status": "blocked" if report["blockers"] else "needs_answers", "preflight": report}
+    policy = report["approval_scope"]["policy"]
     if policy.get("fallback", "none") != "none" or policy.get("retries", 0) != 0:
         raise runner.RunnerError("automated sprints require fallback=none and retries=0")
     for flag in ("push", "accept_flags", "reset", "clean"):
@@ -69,9 +73,7 @@ def run(root: Path, goal: str, name: str, answers: dict, plan: Path) -> dict:
             raise runner.RunnerError(f"automated sprints do not support {flag}=true")
     if policy.get("serial", True) is not True:
         raise runner.RunnerError("automated sprints execute serially")
-    runner_command = runner.runner_command(config, policy.get("runner", "codex"))
-    if not runner_command:
-        raise runner.RunnerError("runner command missing")
+    runner.select_runner(config, policy.get("runner"))
     prepared = prepare.prepare_run(root, {"goal": goal}, answers, name, plan)
     if prepared["status"] != "prepared":
         return prepared

{tasks_toolkit-0.1.4 → tasks_toolkit-0.1.6}/scripts/sprint_auto_execute.py

@@ -12,7 +12,6 @@ sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 from scripts import sprint_auto_state as sas
 from scripts import task_runner as runner
 
-RUNNER_DEFAULT = "codex"
 check_scope_conformity = runner.scope_conformity