tasks-toolkit 0.1.3__py3-none-any.whl

scripts/sprint_auto_prepare.py

@@ -0,0 +1,271 @@
+"""Prepare approved plans and branches for the automated sprint lifecycle (Sprint 12, task 12.4).
+
+Advances an approved new run through planning, validated spec materialization,
+atomic tracker import and creation/reconciliation of its exact sprint branch.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import sprint_auto_preflight as sap
+import sprint_auto_state as sas
+import tasks  # noqa: E402
+import tasks_plan_import as tpi  # noqa: E402
+
+RUNNER_DEFAULT = "codex"
+
+
+def _run_git(root: Path, *args: str) -> str:
+    try:
+        r = subprocess.run(["git", "-C", str(root), *args], capture_output=True, text=True, timeout=30)
+        return r.stdout.strip() if r.returncode == 0 else ""
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+
+
+def _main_sha(root: Path) -> str:
+    return _run_git(root, "rev-parse", "HEAD") or _run_git(root, "rev-parse", "main")
+
+
+def prepare_run(root: Path, request: dict, answers: dict, run_name: str,
+                plan_path: Path | None = None) -> dict:
+    """Prepare a run: preflight recheck, plan, import, branch.
+
+    Returns a dict with keys: status, preflight, state, plan, import_receipt, branch.
+    Does not run agents or create artifacts before approval.
+    """
+    root = Path(root).resolve()
+    result: dict = {"status": "started", "run_name": run_name}
+
+    # 1. Preflight recheck (read-only, no writes)
+    preflight = sap.collect_preflight(root, request, answers)
+    result["preflight"] = preflight
+    if preflight["blockers"]:
+        result["status"] = "blocked"
+        return result
+    if preflight["questions"]:
+        result["status"] = "needs_answers"
+        return result
+
+    # 2. Obtain exclusive lock
+    lock = sas.acquire_lock(root, run_name)
+    with lock:
+        # Recheck preflight under lock
+        preflight2 = sap.collect_preflight(root, request, answers)
+        if preflight2["blockers"] or preflight2["questions"]:
+            result["status"] = "blocked_after_lock"
+            result["preflight"] = preflight2
+            return result
+
+        # 3. Bind state
+        git_common = Path(_run_git(root, "rev-parse", "--git-common-dir") or (root / ".git"))
+        if not git_common.is_absolute():
+            git_common = root / git_common
+        main_sha = _main_sha(root)
+        answers_fp = json.dumps(answers, sort_keys=True)
+        state = sas.bind_state(
+            root, git_common, run_name, request.get("goal", ""),
+            answers_fp, answers.get("allowed_scopes", []),
+            main_sha, RUNNER_DEFAULT, "", 120,
+        )
+        state.plan_fingerprint = ""
+        result["state"] = state.to_dict()
+
+        # 4. Plan: use existing plan if provided, else invoke planner
+        if plan_path and Path(plan_path).exists():
+            plan = json.loads(Path(plan_path).read_text())
+        else:
+            # Fresh planning attempt — invoke plan-sprint.sh
+            slug = run_name.lower().replace(" ", "-")
+            goal = request.get("goal", "")
+            plan_file = root / "tmp" / "plans" / f"{run_name}.json"
+            if not plan_file.exists():
+                # No existing plan — would invoke planner here
+                result["status"] = "needs_plan"
+                result["message"] = "No plan found; run plan-sprint.sh first"
+                return result
+            plan = json.loads(plan_file.read_text())
+
+        # Validate plan structure
+        sprint_info = plan.get("sprint", {})
+        if not isinstance(sprint_info, dict):
+            result["status"] = "invalid_plan"
+            result["message"] = "plan.sprint must be an object"
+            return result
+        if not sprint_info.get("slug") or not sprint_info.get("title"):
+            result["status"] = "invalid_plan"
+            result["message"] = "plan missing sprint slug/title"
+            return result
+        # slug format: lowercase words joined by single hyphens
+        import re
+        if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", sprint_info["slug"]):
+            result["status"] = "invalid_plan"
+            result["message"] = f"invalid sprint slug: {sprint_info['slug']!r}"
+            return result
+        tasks_list = plan.get("tasks", [])
+        if not isinstance(tasks_list, list) or not tasks_list:
+            result["status"] = "invalid_plan"
+            result["message"] = "plan has no tasks"
+            return result
+
+        # Validate each task
+        keys = set()
+        for i, t in enumerate(tasks_list):
+            if not isinstance(t, dict):
+                result["status"] = "invalid_plan"
+                result["message"] = f"task {i} is not an object"
+                return result
+            if not t.get("key") or not t.get("title"):
+                result["status"] = "invalid_plan"
+                result["message"] = f"task {i} missing key/title"
+                return result
+            key = t["key"]
+            if key in keys:
+                result["status"] = "invalid_plan"
+                result["message"] = f"duplicate task key: {key}"
+                return result
+            keys.add(key)
+            # spec_name format
+            spec_name = t.get("spec_name", "")
+            if spec_name and not re.match(r"^[a-z0-9][a-z0-9-]*$", spec_name):
+                result["status"] = "invalid_plan"
+                result["message"] = f"invalid spec_name: {spec_name!r}"
+                return result
+            # scope validation: no forbidden paths, no generated tracker paths
+            for scope in t.get("scope", []):
+                if not isinstance(scope, str) or ".." in scope or scope.startswith("/"):
+                    result["status"] = "invalid_plan"
+                    result["message"] = f"invalid scope: {scope!r}"
+                    return result
+                if scope in ("tasks/tasks.db", "tasks/.lock", "kilo.json", ".mcp.json"):
+                    result["status"] = "invalid_plan"
+                    result["message"] = f"forbidden scope: {scope!r}"
+                    return result
+                if scope.startswith("tasks/") and (scope.endswith(".md") or scope.endswith(".json")):
+                    result["status"] = "invalid_plan"
+                    result["message"] = f"generated tracker path in scope: {scope!r}"
+                    return result
+
+        # Validate dependencies: must reference earlier keys
+        seen_keys = set()
+        for t in tasks_list:
+            for dep in t.get("depends_on", []):
+                if dep not in seen_keys:
+                    result["status"] = "invalid_plan"
+                    result["message"] = f"task {t['key']} depends on unknown/forward key: {dep}"
+                    return result
+            seen_keys.add(t["key"])
+
+        # Check overlapping scopes (tasks with overlapping scopes must be ordered by dependency)
+        scope_map = {t["key"]: set(t.get("scope", [])) for t in tasks_list}
+        for i, t1 in enumerate(tasks_list):
+            for t2 in tasks_list[i + 1:]:
+                if t1["key"] in t2.get("depends_on", []):
+                    continue
+                if t2["key"] in t1.get("depends_on", []):
+                    continue
+                overlap = scope_map[t1["key"]] & scope_map[t2["key"]]
+                if overlap:
+                    result["status"] = "invalid_plan"
+                    result["message"] = f"overlapping scopes between unordered tasks {t1['key']} and {t2['key']}: {overlap}"
+                    return result
+
+        # Bind plan fingerprint
+        state.plan_fingerprint = tpi.canonical_fingerprint(plan)
+        result["plan"] = plan
+
+        # 5. Validate scopes against approval
+        allowed = set(answers.get("allowed_scopes", []))
+        for t in plan.get("tasks", []):
+            for scope in t.get("scope", []):
+                if allowed and not any(scope.startswith(a) or a.startswith(scope) for a in allowed):
+                    result["status"] = "scope_violation"
+                    result["message"] = f"scope {scope!r} not in allowed scopes"
+                    return result
+
+        # 6. Atomic import
+        run_id = f"{run_name}"
+        receipt_holder = {}
+
+        def action(conn):
+            r = tpi.import_plan(conn, plan, run_id, root)
+            receipt_holder.update(r)
+            return ""
+
+        tasks.mutate(action)
+        result["import_receipt"] = receipt_holder
+
+        # 7. Sprint branch creation/reconciliation
+        sprint_info = plan["sprint"]
+        sprint_n = None
+        # Try to extract sprint number from existing tracker
+        # For new sprints, we need to determine the number
+        sprint_id = receipt_holder.get("sprint_id", "")
+        # Extract number from sprint_id (e.g., "14" -> 14)
+        try:
+            sprint_n = int(sprint_id.split(".")[0])
+        except (ValueError, AttributeError):
+            sprint_n = 1
+
+        slug = sprint_info["slug"]
+        branch_name = f"sprint/{sprint_n}-{slug}"
+        existing_branch = _run_git(root, "rev-parse", "--verify", branch_name)
+        if existing_branch:
+            # Reconcile: verify ownership (branch must point to approved main SHA or descendant)
+            branch_sha = _run_git(root, "rev-parse", branch_name)
+            # Check if branch is at or ahead of main_sha
+            merge_base = _run_git(root, "merge-base", main_sha, branch_sha)
+            if merge_base == main_sha:
+                result["branch"] = {"name": branch_name, "action": "reconciled", "sha": branch_sha}
+            else:
+                result["status"] = "branch_ownership_unproven"
+                result["message"] = f"branch {branch_name} does not descend from approved main SHA"
+                return result
+        else:
+            # Create new branch from approved main SHA
+            create_result = subprocess.run(
+                ["bash", str(root / "scripts" / "worktree.sh"), "sprint", "start",
+                 str(sprint_n), slug, "--from", main_sha],
+                capture_output=True, text=True, cwd=str(root),
+            )
+            if create_result.returncode != 0:
+                result["status"] = "branch_creation_failed"
+                result["message"] = create_result.stderr or create_result.stdout
+                return result
+            result["branch"] = {"name": branch_name, "action": "created", "sha": main_sha}
+
+        # Write checkpoint
+        sas.write_checkpoint(sas.state_path(root, run_name), state)
+        result["status"] = "prepared"
+        return result
+
+
+def main() -> int:
+    import argparse
+    parser = argparse.ArgumentParser(description="Prepare approved plans and branches")
+    parser.add_argument("--root", default=".")
+    parser.add_argument("--run-name", required=True)
+    parser.add_argument("--goal", required=True)
+    parser.add_argument("--answers", required=True)
+    parser.add_argument("--plan", default=None)
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    answers = json.loads(Path(args.answers).read_text())
+    request = {"goal": args.goal}
+    result = prepare_run(root, request, answers, args.run_name, args.plan)
+    print(json.dumps(result, indent=2))
+    if result["status"] in ("blocked", "blocked_after_lock", "needs_answers"):
+        return 4 if "blocked" in result["status"] else 2
+    if result["status"] in ("needs_plan", "invalid_plan", "scope_violation"):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/sprint_auto_resume.py

@@ -0,0 +1,153 @@
+"""Resume and finish owned sprints for the automated sprint lifecycle (Sprint 12, task 12.7).
+
+Reconciles interrupted operations from checkpoint, tracker receipts and Git history.
+Never recovers by resetting, cleaning, abandoning or blindly rerunning the agent.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import sprint_auto_state as sas
+
+
+def _run_git(root: Path, *args: str) -> str:
+    try:
+        r = subprocess.run(["git", "-C", str(root), *args], capture_output=True, text=True, timeout=30)
+        return r.stdout.strip() if r.returncode == 0 else ""
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+
+
+def reconcile_checkpoint(root: Path, run_name: str) -> dict:
+    """Reconcile interrupted operations from checkpoint, tracker, and git history.
+
+    Returns a dict with: status, state, child_alive, merge_exists, actions.
+    """
+    root = Path(root).resolve()
+    state = sas.read_checkpoint(sas.state_path(root, run_name))
+    if state is None:
+        return {"status": "no_checkpoint", "actions": ["create new state"]}
+
+    actions = []
+    result = {"state": state.to_dict(), "actions": actions}
+
+    # Check child process
+    child_alive = sas.is_child_alive(state)
+    result["child_alive"] = child_alive
+    if child_alive:
+        actions.append("child still running — wait or forward signal")
+        result["status"] = "child_running"
+        return result
+
+    # Check if main merge already exists
+    sprint_branch = None
+    if state.expected_refs:
+        sprint_branch = state.expected_refs.get("sprint_branch")
+    merge_exists = False
+    if sprint_branch:
+        # Check if sprint branch is merged into main
+        main_sha = _run_git(root, "rev-parse", "main")
+        merge_base = _run_git(root, "merge-base", "main", sprint_branch)
+        if merge_base and main_sha:
+            # If merge-base equals sprint branch HEAD, it's merged
+            sprint_head = _run_git(root, "rev-parse", sprint_branch)
+            if merge_base == sprint_head:
+                merge_exists = True
+                actions.append("main merge already exists — skip merge")
+    result["merge_exists"] = merge_exists
+
+    # Determine next action based on operation_intent
+    intent = state.operation_intent
+    if intent.startswith("execute_task:"):
+        actions.append(f"resume task execution from: {intent}")
+    elif intent == "merge_sprint":
+        if merge_exists:
+            actions.append("post-merge verification needed")
+        else:
+            actions.append("merge sprint to main needed")
+    elif intent == "finish":
+        if merge_exists:
+            actions.append("post-merge verification needed")
+        else:
+            actions.append("finish: merge + verify needed")
+
+    # Check operation results
+    if state.command_results:
+        last = state.command_results[-1]
+        if last.get("exit_code", 0) != 0:
+            actions.append(f"last command failed: {last.get('error', 'unknown')}")
+
+    # Expected-ref finish guard
+    if state.expected_refs:
+        expected_sprint = state.expected_refs.get("sprint_sha")
+        if expected_sprint:
+            actual = _run_git(root, "rev-parse", sprint_branch or "main")
+            if actual and actual != expected_sprint and not merge_exists:
+                actions.append("WARNING: sprint ref mismatch — expected %s got %s" % (expected_sprint[:8], actual[:8]))
+
+    result["status"] = "reconciled"
+    return result
+
+
+def finish_guard(root: Path, run_name: str, expected_sprint_sha: str,
+                 expected_main_sha: str) -> tuple[bool, str]:
+    """Guard before finishing: verify refs match expectations.
+
+    Returns (ok, reason).
+    """
+    root = Path(root).resolve()
+    sprint_sha = _run_git(root, "rev-parse", "main")  # after merge, main should have sprint
+    if expected_main_sha and sprint_sha != expected_main_sha:
+        # main moved — check if it's the sprint merge
+        merge_base = _run_git(root, "merge-base", "main", expected_sprint_sha) if expected_sprint_sha else ""
+        if merge_base != expected_sprint_sha:
+            return False, f"main ref mismatch: expected merge of {expected_sprint_sha[:8]}"
+    return True, "finish guard passed"
+
+
+def recognize_existing_merge(root: Path, sprint_branch: str) -> bool:
+    """Check if sprint branch is already merged into main."""
+    merge_base = _run_git(root, "merge-base", "main", sprint_branch)
+    sprint_head = _run_git(root, "rev-parse", sprint_branch)
+    return merge_base == sprint_head and merge_base != ""
+
+
+def main() -> int:
+    import argparse
+    parser = argparse.ArgumentParser(description="Resume and finish owned sprints")
+    sub = parser.add_subparsers(dest="command")
+
+    rec = sub.add_parser("reconcile", help="Reconcile interrupted run")
+    rec.add_argument("--root", default=".")
+    rec.add_argument("--run-name", required=True)
+
+    fg = sub.add_parser("finish-guard", help="Guard before finishing")
+    fg.add_argument("--root", default=".")
+    fg.add_argument("--run-name", required=True)
+    fg.add_argument("--expected-sprint-sha", default="")
+    fg.add_argument("--expected-main-sha", default="")
+
+    args = parser.parse_args()
+
+    if args.command == "reconcile":
+        root = Path(args.root).resolve()
+        result = reconcile_checkpoint(root, args.run_name)
+        print(json.dumps(result, indent=2))
+        return 0 if result["status"] in ("reconciled", "no_checkpoint") else 1
+
+    if args.command == "finish-guard":
+        root = Path(args.root).resolve()
+        ok, reason = finish_guard(root, args.run_name, args.expected_sprint_sha, args.expected_main_sha)
+        print(json.dumps({"ok": ok, "reason": reason}))
+        return 0 if ok else 1
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/sprint_auto_state.py

@@ -0,0 +1,191 @@
+"""Durable state, checkpoint and process-supervision primitives (Sprint 12, task 12.3).
+
+Runtime-generated state lives under tmp/plans/NAME.auto.json with an associated
+exclusive lock.  Importing this module writes nothing.
+"""
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import signal
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+
+STATE_VERSION = 1
+
+
+@dataclass
+class RunState:
+    """Durable lifecycle checkpoint for an automated sprint run."""
+    version: int = STATE_VERSION
+    repo_root: str = ""
+    git_common_dir: str = ""
+    run_name: str = ""
+    goal: str = ""
+    answers_fingerprint: str = ""
+    allowed_scopes: list = field(default_factory=list)
+    initial_main_sha: str = ""
+    runner: str = "junie"
+    model: str = ""
+    timeout: int = 120
+    plan_fingerprint: str = ""
+    spec_fingerprints: dict = field(default_factory=dict)
+    tracker_uids: dict = field(default_factory=dict)
+    expected_refs: dict = field(default_factory=dict)
+    owned_artifacts: list = field(default_factory=list)
+    operation_intent: str = ""
+    command_results: list = field(default_factory=list)
+    verified_commit: str = ""
+    child_pid: int = 0
+    child_pgid: int = 0
+    heartbeat_ts: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "RunState":
+        if data.get("version") != STATE_VERSION:
+            raise ValueError(f"unknown state version: {data.get('version')}")
+        known = {f.name for f in cls.__dataclass_fields__.values()}
+        filtered = {k: v for k, v in data.items() if k in known}
+        return cls(**filtered)
+
+
+def state_path(root: Path, run_name: str) -> Path:
+    """Path to the runtime state file (under tmp/plans/)."""
+    return root / "tmp" / "plans" / f"{run_name}.auto.json"
+
+
+def lock_path(root: Path, run_name: str) -> Path:
+    """Path to the exclusive lock file."""
+    return root / "tmp" / "plans" / f"{run_name}.auto.lock"
+
+
+class StateLock:
+    """Exclusive file lock for a run.  Refuses symlinked paths."""
+
+    def __init__(self, path: Path):
+        if path.is_symlink():
+            raise ValueError(f"symlinked lock path refused: {path}")
+        self.path = path
+        self._fh = None
+
+    def __enter__(self):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        # refuse if path is a symlink (TOCTOU guard)
+        if self.path.is_symlink():
+            raise ValueError(f"symlinked lock path refused: {self.path}")
+        self._fh = open(self.path, "w")
+        fcntl.flock(self._fh, fcntl.LOCK_EX)
+        return self
+
+    def __exit__(self, *exc):
+        if self._fh:
+            fcntl.flock(self._fh, fcntl.LOCK_UN)
+            self._fh.close()
+            self._fh = None
+
+
+def write_checkpoint(path: Path, state: RunState) -> None:
+    """Atomically write state to path (tmp + rename + fsync).  Refuses symlinks."""
+    if path.is_symlink():
+        raise ValueError(f"symlinked state path refused: {path}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.is_symlink():
+        raise ValueError(f"symlinked state path refused: {path}")
+    fd, tmp = tempfile.mkstemp(prefix=path.name + ".", suffix=".tmp", dir=str(path.parent))
+    try:
+        with os.fdopen(fd, "w") as fh:
+            json.dump(state.to_dict(), fh, indent=2, sort_keys=True)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def read_checkpoint(path: Path) -> RunState | None:
+    """Read state from path.  Returns None if missing or unreadable."""
+    if not path.exists() or path.is_symlink():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return RunState.from_dict(data)
+    except (json.JSONDecodeError, OSError, ValueError, TypeError):
+        return None
+
+
+def acquire_lock(root: Path, run_name: str) -> StateLock:
+    return StateLock(lock_path(root, run_name))
+
+
+def is_child_alive(state: RunState) -> bool:
+    """Check if the child process may still be running (PID-based, no stale heartbeat)."""
+    if state.child_pid <= 0:
+        return False
+    try:
+        os.kill(state.child_pid, 0)
+        return True
+    except (OSError, ProcessLookupError):
+        return False
+
+
+def supervised_run(cmd: list[str], cwd: Path, timeout: int,
+                   on_output=None) -> tuple[int, str]:
+    """Run a command in its own process group.  Returns (exit_code, combined_output).
+
+    Diagnostics go to stderr (captured separately); result stdout is clean.
+    Forwards SIGTERM/SIGINT to the child process group.
+    """
+    proc = subprocess.Popen(
+        cmd, cwd=str(cwd),
+        stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+        start_new_session=True,
+    )
+    pgid = proc.pid
+    try:
+        stdout, stderr = proc.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(pgid, signal.SIGTERM)
+        except (OSError, ProcessLookupError):
+            pass
+        try:
+            stdout, stderr = proc.communicate(timeout=10)
+        except subprocess.TimeoutExpired:
+            try:
+                os.killpg(pgid, signal.SIGKILL)
+            except (OSError, ProcessLookupError):
+                pass
+            stdout, stderr = proc.communicate()
+    output = stdout.decode("utf-8", errors="replace")
+    if stderr:
+        sys.stderr.write(stderr.decode("utf-8", errors="replace"))
+    return proc.returncode, output
+
+
+def bind_state(root: Path, git_common: Path, run_name: str, goal: str,
+               answers_fp: str, scopes: list, main_sha: str,
+               runner: str, model: str, timeout: int) -> RunState:
+    """Create a new RunState bound to identity.  Does not write to disk."""
+    return RunState(
+        repo_root=str(root.resolve()),
+        git_common_dir=str(git_common.resolve()),
+        run_name=run_name,
+        goal=goal,
+        answers_fingerprint=answers_fp,
+        allowed_scopes=list(scopes),
+        initial_main_sha=main_sha,
+        runner=runner,
+        model=model,
+        timeout=timeout,
+    )