bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-campaign/scripts/campaign-deps.py

@@ -0,0 +1,244 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""Campaign Deps — dependency computation and enforcement for campaign skills.
+
+Two modes:
+  --compute: topological sort of all skills from depends_on edges
+  --check:   verify a single skill's dependencies are satisfied
+
+CLI:
+  uv run campaign-deps.py --compute --state-file <path>
+  uv run campaign-deps.py --check --state-file <path> --skill <name>
+  uv run campaign-deps.py --check --state-file <path> --skill <name> --force
+
+Output (JSON on stdout):
+  --compute:
+    {"execution_order": [...], "circular_deps_detected": bool,
+     "cycle_participants": [...] | null, "tier_counts": {"A": int, "B": int}}
+
+  --check:
+    {"skill": "name", "ready": bool, "unmet_deps": [...], "forced": bool}
+
+Exit codes:
+  0  success / ready / force-override
+  1  circular deps / unmet deps / dangling reference
+  2  error (missing file, bad YAML)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import heapq
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+
+def _emit_error(message: str, code: str) -> None:
+    json.dump({"error": message, "code": code}, sys.stderr)
+    sys.stderr.write("\n")
+
+
+def _load_yaml(path: Path) -> Any:
+    with open(path, encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def _build_skill_map(skills: List[Dict[str, Any]]) -> Dict[str, Dict[str, Any]]:
+    return {s["name"]: s for s in skills}
+
+
+def _validate_deps(
+    skill_map: Dict[str, Dict[str, Any]],
+) -> Optional[List[str]]:
+    dangling: List[str] = []
+    for name, skill in skill_map.items():
+        for dep in skill.get("depends_on", []) or []:
+            if dep not in skill_map:
+                dangling.append(f"{name} depends on unknown skill '{dep}'")
+    return dangling if dangling else None
+
+
+def compute(state_file: str) -> int:
+    path = Path(state_file)
+    if not path.is_file():
+        _emit_error(f"State file not found: {state_file}", "STATE_NOT_FOUND")
+        return 2
+
+    try:
+        state = _load_yaml(path)
+    except Exception as exc:
+        _emit_error(f"Failed to parse state file: {exc}", "STATE_PARSE_ERROR")
+        return 2
+
+    skills = state.get("skills", [])
+    if not isinstance(skills, list):
+        _emit_error("State file 'skills' is not an array", "INVALID_STATE")
+        return 2
+
+    skill_map = _build_skill_map(skills)
+
+    tier_counts = {"A": 0, "B": 0}
+    for skill in skill_map.values():
+        tier = skill.get("tier")
+        if tier in tier_counts:
+            tier_counts[tier] += 1
+
+    dangling = _validate_deps(skill_map)
+    if dangling:
+        _emit_error(
+            f"Dangling dependency references: {'; '.join(dangling)}",
+            "DANGLING_DEPENDENCY",
+        )
+        return 1
+
+    in_degree: Dict[str, int] = {name: 0 for name in skill_map}
+    adjacency: Dict[str, List[str]] = {name: [] for name in skill_map}
+
+    for name, skill in skill_map.items():
+        for dep in skill.get("depends_on", []) or []:
+            adjacency[dep].append(name)
+            in_degree[name] += 1
+
+    def _tier_key(n: str) -> tuple[int, str]:
+        return (0 if skill_map[n].get("tier") == "A" else 1, n)
+
+    heap: List[tuple[int, str]] = []
+    for n in skill_map:
+        if in_degree[n] == 0:
+            heapq.heappush(heap, _tier_key(n))
+
+    execution_order: List[str] = []
+
+    while heap:
+        _, current = heapq.heappop(heap)
+        execution_order.append(current)
+
+        for dependent in adjacency[current]:
+            in_degree[dependent] -= 1
+            if in_degree[dependent] == 0:
+                heapq.heappush(heap, _tier_key(dependent))
+
+    if len(execution_order) < len(skill_map):
+        cycle_participants = sorted(
+            n for n in skill_map if n not in set(execution_order)
+        )
+        output = {
+            "execution_order": execution_order,
+            "circular_deps_detected": True,
+            "cycle_participants": cycle_participants,
+            "tier_counts": tier_counts,
+        }
+        json.dump(output, sys.stdout, separators=(",", ":"))
+        sys.stdout.write("\n")
+        return 1
+
+    output = {
+        "execution_order": execution_order,
+        "circular_deps_detected": False,
+        "cycle_participants": None,
+        "tier_counts": tier_counts,
+    }
+    json.dump(output, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+    return 0
+
+
+def check(state_file: str, skill_name: str, force: bool = False) -> int:
+    path = Path(state_file)
+    if not path.is_file():
+        _emit_error(f"State file not found: {state_file}", "STATE_NOT_FOUND")
+        return 2
+
+    try:
+        state = _load_yaml(path)
+    except Exception as exc:
+        _emit_error(f"Failed to parse state file: {exc}", "STATE_PARSE_ERROR")
+        return 2
+
+    skills = state.get("skills", [])
+    if not isinstance(skills, list):
+        _emit_error("State file 'skills' is not an array", "INVALID_STATE")
+        return 2
+
+    skill_map = _build_skill_map(skills)
+
+    if skill_name not in skill_map:
+        _emit_error(f"Skill '{skill_name}' not found in state", "SKILL_NOT_FOUND")
+        return 2
+
+    deps = skill_map[skill_name].get("depends_on", []) or []
+    unmet: List[str] = []
+    for dep in deps:
+        if dep not in skill_map:
+            _emit_error(
+                f"Skill '{skill_name}' depends on unknown skill '{dep}'",
+                "DANGLING_DEPENDENCY",
+            )
+            return 1
+        if skill_map[dep].get("status") != "completed":
+            unmet.append(dep)
+
+    ready = len(unmet) == 0
+    forced = force and not ready
+
+    if forced:
+        json.dump(
+            {"warning": f"Forcing past unmet dependencies for '{skill_name}'", "unmet": unmet},
+            sys.stderr,
+        )
+        sys.stderr.write("\n")
+
+    output = {
+        "skill": skill_name,
+        "ready": ready,
+        "unmet_deps": unmet,
+        "forced": forced,
+    }
+    json.dump(output, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+
+    if not ready and not force:
+        return 1
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Campaign dependency computation and enforcement.",
+    )
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument(
+        "--compute",
+        action="store_true",
+        help="Compute execution order via topological sort",
+    )
+    mode.add_argument(
+        "--check",
+        action="store_true",
+        help="Check if a skill's dependencies are satisfied",
+    )
+    parser.add_argument("--state-file", required=True, help="Path to _campaign-state.yaml")
+    parser.add_argument("--skill", help="Skill name (required for --check)")
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force past dependency check (--check only)",
+    )
+    args = parser.parse_args()
+
+    if args.check and not args.skill:
+        parser.error("--skill is required when using --check")
+
+    if args.compute:
+        return compute(args.state_file)
+    return check(args.state_file, args.skill, force=args.force)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-campaign/scripts/campaign-parse-manifest.py

@@ -0,0 +1,119 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""Campaign Parse Manifest — deterministic parse of a --manifest target list.
+
+step-01 (Setup) seeds a headless campaign's targets from a plain-text manifest.
+Parsing that format by hand risks silently dropping a malformed line — exactly
+the kind of mechanical, all-or-nothing work that belongs in a script. This
+parser is the single source of truth for the format documented in SKILL.md
+"On Activation".
+
+Format (one target per line):
+
+    name,repo_url,tier,pin[;dep1,dep2,...]
+
+- `pin` may be empty (latest): `name,repo_url,tier,`  or  `name,repo_url,tier`
+- a trailing `;`-segment lists depends_on names (comma-separated)
+- blank lines and lines starting with `#` are skipped
+- `tier` must be `A` or `B`
+
+CLI:
+  uv run campaign-parse-manifest.py <path/to/manifest.txt>
+  cat manifest.txt | uv run campaign-parse-manifest.py -
+
+Output (JSON on stdout):
+  {"targets": [{"name","repo_url","tier","pin","depends_on"}], "errors": [{"line","message"}]}
+
+Exit codes:
+  0  parsed cleanly (no errors)
+  1  one or more malformed lines (errors[] populated; targets[] omits bad lines)
+  2  file error (not found / unreadable)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+
+def parse_manifest_text(text: str) -> Dict[str, Any]:
+    targets: List[Dict[str, Any]] = []
+    errors: List[Dict[str, Any]] = []
+    seen: set = set()
+
+    for lineno, raw in enumerate(text.splitlines(), start=1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+
+        body, sep, deps_part = line.partition(";")
+        fields = [f.strip() for f in body.split(",")]
+        if len(fields) < 3:
+            errors.append({"line": lineno, "message": f"expected `name,repo_url,tier[,pin]`, got {len(fields)} field(s)"})
+            continue
+
+        name, repo_url, tier = fields[0], fields[1], fields[2]
+        pin = fields[3] if len(fields) >= 4 and fields[3] != "" else None
+
+        if not name:
+            errors.append({"line": lineno, "message": "empty `name`"})
+            continue
+        if not repo_url:
+            errors.append({"line": lineno, "message": f"`{name}` has empty `repo_url`"})
+            continue
+        if tier not in ("A", "B"):
+            errors.append({"line": lineno, "message": f"`{name}` has invalid tier `{tier}` (must be A or B)"})
+            continue
+        if name in seen:
+            errors.append({"line": lineno, "message": f"duplicate target name `{name}`"})
+            continue
+        seen.add(name)
+
+        depends_on = [d.strip() for d in deps_part.split(",") if d.strip()] if sep else []
+
+        targets.append(
+            {"name": name, "repo_url": repo_url, "tier": tier, "pin": pin, "depends_on": depends_on}
+        )
+
+    return {"targets": targets, "errors": errors}
+
+
+def run(path: str) -> int:
+    if path == "-":
+        text = sys.stdin.read()
+    else:
+        p = Path(path)
+        if not p.is_file():
+            json.dump({"error": f"Manifest not found: {path}", "code": "MANIFEST_NOT_FOUND"}, sys.stderr)
+            sys.stderr.write("\n")
+            return 2
+        try:
+            text = p.read_text(encoding="utf-8")
+        except OSError as exc:
+            json.dump({"error": f"Manifest unreadable: {exc}", "code": "MANIFEST_READ_ERROR"}, sys.stderr)
+            sys.stderr.write("\n")
+            return 2
+
+    result = parse_manifest_text(text)
+    json.dump(result, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+    return 1 if result["errors"] else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="campaign-parse-manifest",
+        description="Parse a --manifest target list into structured targets.",
+    )
+    parser.add_argument("path", help="path to manifest text file, or `-` for stdin")
+    args = parser.parse_args(argv)
+    return run(args.path)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-campaign/scripts/campaign-provenance.py

@@ -0,0 +1,247 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""Campaign Provenance — verify repo access and record commit SHAs for all targets.
+
+Replaces the step-04 prose that asked the LLM to string-munge each repo_url
+("handle trailing .git or slashes"), run `gh repo view` + `gh api commits/{ref}`
+per target, and aggregate failures across 15+ targets in-context. All of that
+is deterministic; doing it by hand is both token-expensive and a fragile-parse
+risk. This script owns the parse, the gh calls, and the aggregation, and — when
+every (or nearly every) target fails the same way — collapses the wall of
+near-identical errors into a single actionable root-cause hint instead of N
+independent failures.
+
+For each skill it resolves `{owner}/{repo}` from the brief's repo_url, picks the
+ref (the skill's pin, or the repo default branch), verifies access, and records
+the commit SHA.
+
+CLI:
+  uv run campaign-provenance.py --state-file <path> --brief-file <path>
+
+Output (JSON on stdout):
+  {
+    "results": [
+      {"name": "...", "repo_url": "...", "owner": "...", "repo": "...",
+       "ref": "...", "commit_sha": "..." | null,
+       "status": "accessible" | "inaccessible", "error": "..." | null}
+    ],
+    "all_accessible": bool,
+    "inaccessible_count": N,
+    "systemic_hint": "..." | null
+  }
+
+Exit codes:
+  0  all targets accessible
+  1  one or more targets inaccessible
+  2  error (missing files, bad YAML, gh not installed)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess  # noqa: S404 — invoking the user's authenticated `gh` CLI is the point
+import sys
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+import yaml
+
+# A command runner returns (returncode, stdout, stderr). Injectable for tests.
+Runner = Callable[[List[str]], Tuple[int, str, str]]
+
+
+def _emit_error(message: str, code: str) -> None:
+    json.dump({"error": message, "code": code}, sys.stderr)
+    sys.stderr.write("\n")
+
+
+def _load_yaml(path: Path) -> Any:
+    with open(path, encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def parse_owner_repo(repo_url: str) -> Optional[Tuple[str, str]]:
+    """Extract (owner, repo) from a GitHub URL or `owner/repo` shorthand.
+
+    Tolerates trailing `.git`, trailing slashes, `git@` SSH form, and a bare
+    `owner/repo`. Returns None when no owner/repo pair can be recovered.
+    """
+    if not repo_url or not isinstance(repo_url, str):
+        return None
+    url = repo_url.strip().rstrip("/")
+    if url.endswith(".git"):
+        url = url[:-4]
+    # git@github.com:owner/repo
+    ssh = re.match(r"^git@[^:]+:(?P<owner>[^/]+)/(?P<repo>[^/]+)$", url)
+    if ssh:
+        return ssh.group("owner"), ssh.group("repo")
+    # https://host/owner/repo (take the last two path segments)
+    https = re.match(r"^[a-zA-Z]+://[^/]+/(?P<rest>.+)$", url)
+    rest = https.group("rest") if https else url
+    parts = [p for p in rest.split("/") if p]
+    if len(parts) >= 2:
+        return parts[-2], parts[-1]
+    return None
+
+
+def _default_runner(args: List[str]) -> Tuple[int, str, str]:
+    proc = subprocess.run(args, capture_output=True, text=True)  # noqa: S603
+    return proc.returncode, proc.stdout, proc.stderr
+
+
+def _classify_error(stderr: str) -> str:
+    """Bucket a gh failure so systemic root causes can be detected."""
+    low = stderr.lower()
+    if "authentication" in low or "gh auth" in low or "not logged" in low or "401" in low:
+        return "auth"
+    if "could not resolve" in low or "network" in low or "timeout" in low or "dial tcp" in low:
+        return "network"
+    if "rate limit" in low or "403" in low:
+        return "rate-limit"
+    if "not found" in low or "404" in low:
+        return "not-found"
+    return "other"
+
+
+_SYSTEMIC_HINTS = {
+    "auth": "All targets failed authentication — run `gh auth status` / `gh auth login`, then `campaign resume`.",
+    "network": "All targets failed with network errors — check connectivity, then `campaign resume`.",
+    "rate-limit": "All targets hit GitHub rate limiting — wait for the limit to reset, then `campaign resume`.",
+}
+
+
+def run(state_file: str, brief_file: str, runner: Runner = _default_runner) -> int:
+    state_path = Path(state_file)
+    brief_path = Path(brief_file)
+
+    if not state_path.is_file():
+        _emit_error(f"State file not found: {state_file}", "STATE_NOT_FOUND")
+        return 2
+    if not brief_path.is_file():
+        _emit_error(f"Brief file not found: {brief_file}", "BRIEF_NOT_FOUND")
+        return 2
+    if shutil.which("gh") is None and runner is _default_runner:
+        _emit_error("GitHub CLI `gh` not found on PATH", "GH_NOT_FOUND")
+        return 2
+
+    try:
+        state = _load_yaml(state_path)
+    except Exception as exc:  # noqa: BLE001
+        _emit_error(f"Failed to parse state file: {exc}", "STATE_PARSE_ERROR")
+        return 2
+    try:
+        brief = _load_yaml(brief_path)
+    except Exception as exc:  # noqa: BLE001
+        _emit_error(f"Failed to parse brief file: {exc}", "BRIEF_PARSE_ERROR")
+        return 2
+
+    skills = state.get("skills", [])
+    if not isinstance(skills, list):
+        _emit_error("State file 'skills' is not an array", "INVALID_STATE")
+        return 2
+    targets = brief.get("targets", [])
+    if not isinstance(targets, list):
+        _emit_error("Brief file 'targets' is not an array", "INVALID_BRIEF")
+        return 2
+
+    name_to_repo: Dict[str, str] = {t["name"]: t["repo_url"] for t in targets}
+
+    results: List[Dict[str, Any]] = []
+    error_classes: List[str] = []
+
+    for skill in skills:
+        name = skill["name"]
+        repo_url = name_to_repo.get(name)
+        record: Dict[str, Any] = {
+            "name": name,
+            "repo_url": repo_url,
+            "owner": None,
+            "repo": None,
+            "ref": None,
+            "commit_sha": None,
+            "status": "inaccessible",
+            "error": None,
+        }
+        if repo_url is None:
+            record["error"] = f"Skill '{name}' has no repo_url in brief targets"
+            error_classes.append("other")
+            results.append(record)
+            continue
+
+        parsed = parse_owner_repo(repo_url)
+        if parsed is None:
+            record["error"] = f"Could not parse owner/repo from '{repo_url}'"
+            error_classes.append("other")
+            results.append(record)
+            continue
+        owner, repo = parsed
+        record["owner"], record["repo"] = owner, repo
+
+        rc, _out, err = runner(["gh", "repo", "view", f"{owner}/{repo}", "--json", "name"])
+        if rc != 0:
+            record["error"] = err.strip() or "gh repo view failed"
+            error_classes.append(_classify_error(err))
+            results.append(record)
+            continue
+
+        ref = skill.get("pin")
+        if not ref:
+            rc, out, err = runner(
+                ["gh", "repo", "view", f"{owner}/{repo}", "--json", "defaultBranchRef", "--jq", ".defaultBranchRef.name"]
+            )
+            if rc != 0:
+                record["error"] = err.strip() or "could not resolve default branch"
+                error_classes.append(_classify_error(err))
+                results.append(record)
+                continue
+            ref = out.strip()
+        record["ref"] = ref
+
+        rc, out, err = runner(["gh", "api", f"repos/{owner}/{repo}/commits/{ref}", "--jq", ".sha"])
+        if rc != 0:
+            record["error"] = err.strip() or f"could not resolve commit for ref '{ref}'"
+            error_classes.append(_classify_error(err))
+            results.append(record)
+            continue
+
+        record["commit_sha"] = out.strip()
+        record["status"] = "accessible"
+        results.append(record)
+
+    inaccessible = [r for r in results if r["status"] != "accessible"]
+    systemic_hint: Optional[str] = None
+    if inaccessible and len(inaccessible) == len(results):
+        # Every target failed — if they share a class, surface one root cause.
+        distinct = set(error_classes)
+        if len(distinct) == 1:
+            systemic_hint = _SYSTEMIC_HINTS.get(next(iter(distinct)))
+
+    output = {
+        "results": results,
+        "all_accessible": not inaccessible,
+        "inaccessible_count": len(inaccessible),
+        "systemic_hint": systemic_hint,
+    }
+    json.dump(output, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+    return 0 if not inaccessible else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="campaign-provenance",
+        description="Verify repo access and record commit SHAs for all campaign targets.",
+    )
+    parser.add_argument("--state-file", required=True, help="Path to _campaign-state.yaml")
+    parser.add_argument("--brief-file", required=True, help="Path to campaign-brief.yaml")
+    args = parser.parse_args(argv)
+    return run(args.state_file, args.brief_file)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())