@julioborges/gantry 0.1.0

package/.agents/skills/gantry/scripts/cleanup.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Print or execute an explicit cleanup plan for merged done Issue worktrees."""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from common import issue_branch, load_policy_issues, repo_root, resolve_policy  # noqa: E402
+
+
+def git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    """Run Git in the repository and retain output for a caller-facing error."""
+    return subprocess.run(
+        ["git", *args],
+        cwd=root,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+
+
+def git_output(root: Path, *args: str) -> str:
+    result = git(root, *args)
+    if result.returncode:
+        raise ValueError((result.stderr or result.stdout).strip())
+    return result.stdout
+
+
+def current_branch(root: Path) -> str:
+    branch = git_output(root, "branch", "--show-current").strip()
+    if not branch:
+        raise ValueError("cleanup requires a checked-out run branch; use --run-branch from a branch checkout")
+    return branch
+
+
+def worktrees(root: Path) -> dict[str, str]:
+    """Map checked-out local branches to their registered worktree paths."""
+    result: dict[str, str] = {}
+    path: str | None = None
+    for line in git_output(root, "worktree", "list", "--porcelain").splitlines():
+        if line.startswith("worktree "):
+            path = line.removeprefix("worktree ")
+        elif line.startswith("branch refs/heads/") and path:
+            result[line.removeprefix("branch refs/heads/")] = path
+        elif not line:
+            path = None
+    return result
+
+
+def branch_exists(root: Path, branch: str) -> bool:
+    return git(root, "show-ref", "--verify", "--quiet", f"refs/heads/{branch}").returncode == 0
+
+
+def merged_into_run(root: Path, branch: str, run_branch: str) -> bool:
+    return git(root, "merge-base", "--is-ancestor", branch, run_branch).returncode == 0
+
+
+def branch_head(root: Path, branch: str) -> str:
+    return git_output(root, "rev-parse", "--verify", branch).strip()
+
+
+def cleanup_plan(root: Path, run_branch: str) -> dict:
+    """Plan cleanup only for done Issue branches merged into the run branch."""
+    policy = resolve_policy(root)
+    checked_out = worktrees(root)
+    candidates: list[tuple[str, str]] = []
+    for issue in load_policy_issues(root).values():
+        branch = issue_branch(policy, issue)
+        if issue.done and branch != run_branch and branch_exists(root, branch) and merged_into_run(root, branch, run_branch):
+            candidates.append((issue.ref, branch))
+
+    branches = [{"issue": ref, "name": branch} for ref, branch in sorted(candidates)]
+    planned_worktrees = [
+        {"issue": ref, "path": checked_out[branch], "branch": branch}
+        for ref, branch in sorted(candidates)
+        if branch in checked_out
+    ]
+    return {
+        "run_branch": run_branch,
+        "worktrees": planned_worktrees,
+        "branches": branches,
+        "state": {
+            "run_head": branch_head(root, run_branch),
+            "branch_heads": [
+                {"name": branch, "head": branch_head(root, branch)}
+                for _, branch in sorted(candidates)
+            ],
+        },
+    }
+
+
+def execute_plan(root: Path, plan: dict) -> tuple[dict[str, list[str]], list[str]]:
+    """Remove the exact worktrees then branches in an authorized plan."""
+    removed = {"worktrees": [], "branches": []}
+    errors: list[str] = []
+    for item in plan["worktrees"]:
+        result = git(root, "worktree", "remove", "--", item["path"])
+        if result.returncode:
+            errors.append(f"could not remove worktree {item['path']}: {(result.stderr or result.stdout).strip()}")
+        else:
+            removed["worktrees"].append(item["path"])
+    if errors:
+        return removed, errors
+    for item in plan["branches"]:
+        result = git(root, "branch", "-d", "--", item["name"])
+        if result.returncode:
+            errors.append(f"could not remove branch {item['name']}: {(result.stderr or result.stdout).strip()}")
+        else:
+            removed["branches"].append(item["name"])
+    return removed, errors
+
+
+def load_authorized_plan(path: str) -> dict:
+    """Read the exact cleanup plan accepted by the operator."""
+    try:
+        plan = json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError(f"could not read authorized cleanup plan: {exc}") from exc
+    if not isinstance(plan, dict):
+        raise ValueError("authorized cleanup plan must be a JSON object")
+    return plan
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    action = parser.add_mutually_exclusive_group()
+    action.add_argument("--plan", action="store_true", help="print the read-only cleanup plan (default)")
+    action.add_argument("--yes", action="store_true", help="execute an unchanged authorized cleanup plan")
+    parser.add_argument("--plan-file", help="JSON output from the authorized --plan invocation; required with --yes")
+    parser.add_argument("--run-branch", help="run branch used to determine whether Issue branches are merged")
+    parser.add_argument("--cwd", default=".", help="repository or worktree to inspect")
+    parser.add_argument("--json", action="store_true", help="emit the cleanup plan as JSON")
+    args = parser.parse_args()
+
+    root = repo_root(Path(args.cwd))
+    try:
+        run_branch = args.run_branch or current_branch(root)
+        current_plan = cleanup_plan(root, run_branch)
+        if args.plan_file and not args.yes:
+            raise ValueError("--plan-file is only valid with --yes")
+        if args.yes:
+            if not args.plan_file:
+                raise ValueError("--yes requires --plan-file from the authorized --plan output")
+            plan = load_authorized_plan(args.plan_file)
+            if plan != current_plan:
+                raise ValueError("authorized cleanup plan no longer matches the repository state")
+        else:
+            plan = current_plan
+    except ValueError as error:
+        payload = {"error": str(error)}
+        print(json.dumps(payload, indent=2) if args.json else f"ERROR: {payload['error']}", file=sys.stderr)
+        return 1
+
+    if args.yes:
+        removed, errors = execute_plan(root, plan)
+        plan["removed"] = removed
+        if errors:
+            plan["errors"] = errors
+    if args.json:
+        print(json.dumps(plan, indent=2))
+    else:
+        print(f"run branch: {plan['run_branch']}")
+        for item in plan["worktrees"]:
+            print(f"worktree: {item['path']} ({item['branch']}, {item['issue']})")
+        for item in plan["branches"]:
+            print(f"branch: {item['name']} ({item['issue']})")
+        if not plan["worktrees"] and not plan["branches"]:
+            print("nothing eligible for cleanup")
+        if args.yes:
+            for path in plan["removed"]["worktrees"]:
+                print(f"removed worktree: {path}")
+            for branch in plan["removed"]["branches"]:
+                print(f"removed branch: {branch}")
+        for error in plan.get("errors", []):
+            print(f"ERROR: {error}", file=sys.stderr)
+    if plan.get("errors"):
+        return 1
+    return 0 if plan["worktrees"] or plan["branches"] else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.agents/skills/gantry/scripts/common.py

@@ -0,0 +1,361 @@
+"""Shared parsing and policy helpers for the Gantry workflow scripts."""
+from __future__ import annotations
+
+import copy
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_POLICY = {
+    "artifacts": {
+        "specs": ".scratch/{slug}/spec.md",
+        "issues": ".scratch/{slug}/issues",
+        "adrs": "docs/adr",
+        "decisions": "docs/adr",
+        "context": "CONTEXT.md",
+        "issueTracker": "docs/agents/issue-tracker.md",
+    },
+    "templates": {"dir": ".gantry/templates", "headingMap": {}},
+    "checks": [],
+    "git": {
+        "target": "main",
+        "prefix": "gantry/",
+        "issueBranch": "{prefix}{spec}-{number:02d}",
+    },
+    "hooks": {"record": [], "deny": []},
+    "budget": {"corrections": 2, "contextShare": 0.15},
+    "dashboard": {"staleAfterSeconds": 900},
+}
+
+REF_RE = re.compile(r"`?([a-z0-9][a-z0-9-]*)#(\d{2,})`?")
+STATUS_RE = re.compile(r"^Status:\s*(.+?)\s*$", re.MULTILINE)
+SLICE_RE = re.compile(r"^Slice:\s*`?([a-z0-9-]+#\d+)`?\s*$", re.MULTILINE)
+TITLE_RE = re.compile(r"^#\s+(.+?)\s*$", re.MULTILINE)
+CHECKBOX_RE = re.compile(r"^(\s*)- \[( |x|X)\]\s+(.*)$")
+ISSUE_FILE_RE = re.compile(r"^(\d{2,})-[a-z0-9-]+\.md$")
+DONE_STATUSES = {"done"}
+PARKED_STATUSES = {"blocked", "needs-operator", "draft"}
+
+
+def repo_root(start: Path | None = None) -> Path:
+    """Find the enclosing repository, including linked worktrees."""
+    path = (start or Path.cwd()).resolve()
+    for candidate in [path, *path.parents]:
+        if (candidate / ".git").exists():
+            return candidate
+    return path
+
+
+def _merge_policy(base: dict, overlay: dict) -> dict:
+    result = copy.deepcopy(base)
+    for key, value in overlay.items():
+        result[key] = _merge_policy(result[key], value) if isinstance(value, dict) and isinstance(result.get(key), dict) else copy.deepcopy(value)
+    return result
+
+
+def resolve_policy(root: Path | None = None) -> dict:
+    """Overlay optional repository policy onto portable pack defaults."""
+    root = repo_root(root)
+    path = root / ".gantry" / "config.json"
+    if not path.exists():
+        return copy.deepcopy(DEFAULT_POLICY)
+    try:
+        overlay = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{path} is not valid JSON: {exc}") from exc
+    if not isinstance(overlay, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    return _merge_policy(DEFAULT_POLICY, overlay)
+
+
+def resolve_effective_template(root: Path | None, kind: str) -> Path:
+    """Locate a repository template, falling back to the pack default."""
+    if kind not in {"spec", "prd", "issue"}:
+        raise ValueError(f"unknown template kind: {kind}")
+    root = repo_root(root)
+    configured = root / resolve_policy(root)["templates"]["dir"] / f"{kind}.md"
+    if configured.exists():
+        return configured
+    return Path(__file__).resolve().parent.parent / "templates" / f"{kind}.md"
+
+
+def resolve_heading_map(root: Path | None = None) -> dict[str, str]:
+    """Return policy-declared equivalent headings as canonical Markdown headings."""
+    raw_map = resolve_policy(root)["templates"].get("headingMap", {})
+    if not isinstance(raw_map, dict) or not all(isinstance(key, str) and isinstance(value, str) for key, value in raw_map.items()):
+        raise ValueError("templates.headingMap must map heading strings to heading strings")
+
+    def heading(value: str) -> str:
+        value = value.strip()
+        return value if value.startswith("## ") else f"## {value.lstrip('#').strip()}"
+
+    return {heading(alias): heading(canonical) for alias, canonical in raw_map.items()}
+
+
+def resolve_workflow_paths(root: Path, slug: str) -> dict[str, Path]:
+    """Render the effective policy's repository paths for a workflow run."""
+    root = repo_root(root)
+    artifacts = resolve_policy(root)["artifacts"]
+
+    def render(name: str) -> Path:
+        return root / artifacts[name].format(slug=slug)
+
+    issue_dir = render("issues")
+    existing = sorted(issue_dir.glob("*.md"))
+    return {
+        "specPath": render("specs"),
+        "issueDir": issue_dir,
+        "exemplarIssue": existing[0] if existing else render("issueTracker"),
+        "decisions": render("decisions"),
+        "issueTracker": render("issueTracker"),
+        "context": render("context"),
+        "adrs": render("adrs"),
+    }
+
+
+def artifact_path(root: Path, name: str, slug: str) -> Path:
+    """Render one effective artifact path for an Issue's parent Spec."""
+    root = repo_root(root)
+    return root / resolve_policy(root)["artifacts"][name].format(slug=slug)
+
+
+def load_policy_issues(root: Path, policy: dict | None = None) -> dict[str, Issue]:
+    """Load Issue files from the policy's rendered, slug-aware issue directory."""
+    root = repo_root(root)
+    effective = policy or resolve_policy(root)
+    pattern = effective["artifacts"]["issues"].format(slug="*").rstrip("/")
+    issues: dict[str, Issue] = {}
+    for path in sorted(root.glob(f"{pattern}/*.md")):
+        if ISSUE_FILE_RE.match(path.name):
+            issue = parse_issue(path)
+            issues[issue.ref] = issue
+    return issues
+
+
+def policy_spec_numbers(root: Path, policy: dict | None = None) -> dict[str, int]:
+    """Read Spec numbers from the policy's rendered, slug-aware spec paths."""
+    root = repo_root(root)
+    effective = policy or resolve_policy(root)
+    template = effective["artifacts"]["specs"]
+    pattern = template.format(slug="*")
+    slug_matcher = re.compile("^" + re.escape(template).replace(re.escape("{slug}"), r"(?P<slug>[^/]+)") + "$")
+    result: dict[str, int] = {}
+    for path in sorted(root.glob(pattern)):
+        match = re.search(r"\(spec\s+(\d+)", path.read_text(encoding="utf-8"))
+        if match:
+            relative = path.relative_to(root).as_posix()
+            slug = slug_matcher.match(relative)
+            if slug:
+                result[slug.group("slug")] = int(match.group(1))
+    return result
+
+
+def section(text: str, heading: str) -> str:
+    """Return a level-two Markdown section body."""
+    match = re.search(rf"^##\s+{re.escape(heading)}\s*$", text, re.MULTILINE | re.IGNORECASE)
+    if not match:
+        return ""
+    rest = text[match.end():]
+    next_heading = re.search(r"^##\s+", rest, re.MULTILINE)
+    return rest[:next_heading.start()] if next_heading else rest
+
+
+@dataclass
+class Criterion:
+    index: int
+    text: str
+    checked: bool
+    line_no: int
+
+
+@dataclass
+class Issue:
+    ref: str
+    spec: str
+    number: int
+    path: Path
+    title: str
+    status: str
+    blocked_by: list[str] = field(default_factory=list)
+    criteria: list[Criterion] = field(default_factory=list)
+
+    @property
+    def done(self) -> bool:
+        return self.status.lower() in DONE_STATUSES
+
+    @property
+    def parked(self) -> bool:
+        return self.status.lower() in PARKED_STATUSES
+
+    def to_dict(self, root: Path) -> dict:
+        return {
+            "ref": self.ref, "spec": self.spec, "number": self.number,
+            "path": str(self.path.relative_to(root)), "title": self.title,
+            "status": self.status, "blocked_by": self.blocked_by,
+            "criteria_total": len(self.criteria),
+            "criteria_checked": sum(criterion.checked for criterion in self.criteria),
+        }
+
+
+def parse_criteria(text: str) -> list[Criterion]:
+    body = section(text, "Acceptance criteria")
+    if not body:
+        return []
+    start_line = text[:text.index(body)].count("\n")
+    criteria: list[Criterion] = []
+    for offset, line in enumerate(body.splitlines()):
+        match = CHECKBOX_RE.match(line)
+        if match:
+            criteria.append(Criterion(len(criteria) + 1, match.group(3).strip(), match.group(2).lower() == "x", start_line + offset + 1))
+    return criteria
+
+
+def parse_blocked_by(text: str, own_spec: str) -> list[str]:
+    refs: list[str] = []
+    for line in section(text, "Blocked by").splitlines():
+        if line.strip().startswith("-"):
+            for spec, number in REF_RE.findall(line):
+                ref = f"{spec}#{int(number):02d}"
+                if ref not in refs:
+                    refs.append(ref)
+    return refs
+
+
+def parse_issue(path: Path) -> Issue:
+    path = path.resolve()
+    text = path.read_text(encoding="utf-8")
+    spec = path.parent.parent.name
+    file_match = ISSUE_FILE_RE.match(path.name)
+    number = int(file_match.group(1)) if file_match else 0
+    ref_match = SLICE_RE.search(text)
+    raw_ref = ref_match.group(1) if ref_match else f"{spec}#{number:02d}"
+    ref_spec, raw_number = raw_ref.split("#")
+    ref = f"{ref_spec}#{int(raw_number):02d}"
+    title = TITLE_RE.search(text)
+    status = STATUS_RE.search(text)
+    return Issue(ref, ref_spec, int(raw_number), path, title.group(1) if title else path.stem,
+                 status.group(1) if status else "unknown", parse_blocked_by(text, ref_spec), parse_criteria(text))
+
+
+def issue_branch(policy: dict, issue: Issue) -> str:
+    """Render the policy's branch name for an Issue."""
+    template = policy["git"]["issueBranch"]
+    try:
+        branch = template.format(
+            prefix=policy["git"]["prefix"],
+            spec=issue.spec,
+            number=issue.number,
+        )
+    except (AttributeError, KeyError, ValueError) as exc:
+        raise ValueError("git.issueBranch must use only {prefix}, {spec}, and {number}") from exc
+    if not branch:
+        raise ValueError("git.issueBranch must render a non-empty branch name")
+    return branch
+
+
+def load_issues(scratch: Path) -> dict[str, Issue]:
+    issues: dict[str, Issue] = {}
+    for directory in sorted(scratch.glob("*/issues")):
+        for path in sorted(directory.glob("*.md")):
+            if ISSUE_FILE_RE.match(path.name):
+                issue = parse_issue(path)
+                issues[issue.ref] = issue
+    return issues
+
+
+def normalise_ref(raw: str) -> str | None:
+    match = REF_RE.fullmatch(raw.strip().strip("`"))
+    return f"{match.group(1)}#{int(match.group(2)):02d}" if match else None
+
+
+def resolve_issue_arg(arg: str, root: Path, issues: dict[str, Issue]) -> Issue | None:
+    ref = normalise_ref(arg)
+    if ref and ref in issues:
+        return issues[ref]
+    path = Path(arg)
+    path = path if path.is_absolute() else root / path
+    return parse_issue(path) if path.exists() else None
+
+
+def roadmap_waves(roadmap_text: str) -> dict[int, list[str]]:
+    waves: dict[int, list[str]] = {}
+    current: int | None = None
+    for line in roadmap_text.splitlines():
+        match = re.match(r"^###\s+Wave\s+(\d+)", line)
+        if match:
+            current = int(match.group(1))
+            waves.setdefault(current, [])
+            continue
+        item = re.match(r"^- \[( |x|X)\] \*\*`([a-z0-9-]+#\d+)`\*\*", line)
+        if item and current is not None:
+            spec, number = item.group(2).split("#")
+            waves[current].append(f"{spec}#{int(number):02d}")
+    return waves
+
+
+def spec_numbers(scratch: Path) -> dict[str, int]:
+    result: dict[str, int] = {}
+    for spec in sorted(scratch.glob("*/spec.md")):
+        match = re.search(r"\(spec\s+(\d+)", spec.read_text(encoding="utf-8"))
+        if match:
+            result[spec.parent.name] = int(match.group(1))
+    return result
+
+
+def issue_levels(issues: dict[str, Issue]) -> dict[str, int]:
+    levels: dict[str, int] = {}
+    visiting: set[str] = set()
+
+    def depth(ref: str) -> int:
+        if ref in levels:
+            return levels[ref]
+        if ref in visiting:
+            raise ValueError(f"dependency cycle through {ref}")
+        visiting.add(ref)
+        blockers = [blocker for blocker in issues[ref].blocked_by if blocker in issues]
+        levels[ref] = 0 if not blockers else 1 + max(depth(blocker) for blocker in blockers)
+        visiting.remove(ref)
+        return levels[ref]
+
+    for reference in sorted(issues):
+        depth(reference)
+    return levels
+
+
+def main() -> int:
+    """Print the portable policy and rendered workflow paths."""
+    parser = argparse.ArgumentParser(description=main.__doc__)
+    parser.add_argument("--cwd", default=".", help="repository or worktree to inspect")
+    parser.add_argument("--scope-slug", default="sample", help="slug used to render artifact paths")
+    parser.add_argument("--issue", help="Issue reference or path whose configured branch to render")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    root = repo_root(Path(args.cwd))
+    paths = resolve_workflow_paths(root, args.scope_slug)
+    payload = {
+        "repo_root": str(root),
+        "policy": resolve_policy(root),
+        "paths": {name: str(path) for name, path in paths.items()},
+    }
+    if args.issue:
+        issue = resolve_issue_arg(args.issue, root, load_policy_issues(root, payload["policy"]))
+        if issue is None:
+            raise ValueError(f"could not resolve Issue {args.issue!r}")
+        payload["issueBranch"] = issue_branch(payload["policy"], issue)
+    if args.json:
+        print(json.dumps(payload, indent=2))
+    else:
+        print(f"repo_root: {payload['repo_root']}")
+        if "issueBranch" in payload:
+            print(f"issue_branch: {payload['issueBranch']}")
+        for name, path in payload["paths"].items():
+            print(f"{name}: {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())