bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/shared/scripts/skf-enumerate-stack-skills.py

@@ -22,7 +22,7 @@ SKILL.md, then extract usage patterns per skill (the part that does
 benefit from LLM judgment).
 
 Subcommand:
-  enumerate <skills-root>
+  enumerate <skills-root> [--pairs] [--reliability]
       Emit JSON {"skills": [...], "cycles": [...], "warnings": [...]}
       describing every subdirectory of <skills-root> that resolves to a
       skill package. Both layouts from knowledge/version-paths.md are
@@ -84,18 +84,47 @@ Symlink handling:
 Per-skill errors (malformed metadata.json, OSError, etc.) are captured
 as warnings on the top-level result; they do not exit the process.
 
+Optional derived output (additive flags — off by default, so existing
+consumers that read only skills/cycles/warnings are unaffected):
+
+  --pairs
+      Attach the complete set of unique library pairs derived from the
+      inventory: `pairs = [{"library_a": a, "library_b": b}, ...]` over
+      `itertools.combinations` of the sorted, deduplicated skill names,
+      plus `pair_count == N*(N-1)/2`. This is the deterministic
+      combinatorics the refine-architecture gap-analysis prompt used to
+      do in-context (where a dropped pair is a silently missed
+      integration gap). Sorting the names first makes ordering
+      independent of directory-scan order and byte-stable across runs.
+
+  --reliability
+      Attach the inventory reliability verdict computed from the counts
+      the script already owns:
+        skill_count       — len(skills)
+        warning_count     — len(warnings)
+        unreliable_ratio  — warning_count / (skill_count + warning_count),
+                            or 0.0 when the inventory is empty
+        inventory_reliable — unreliable_ratio <= 0.20 (the RELIABILITY
+                            THRESHOLD lives here, in one unit-tested place,
+                            so consuming prompts read a boolean instead of
+                            re-deriving a ratio + threshold comparison).
+      The raw counts are emitted alongside the boolean so a caller's halt
+      message can still render "{warning_count}/{skill_count+warning_count}
+      skills returned malformed metadata".
+
 Exit codes:
   0  enumeration succeeded (including zero skills found)
   1  user error (bad skills-root path)
 
 CLI:
-  uv run skf-enumerate-stack-skills.py enumerate <skills-root>
+  uv run skf-enumerate-stack-skills.py enumerate <skills-root> [--pairs] [--reliability]
 """
 
 from __future__ import annotations
 
 import argparse
 import hashlib
+import itertools
 import json
 import re
 import sys
@@ -112,6 +141,13 @@ SOURCE_REFERENCES = "references"
 SOURCE_SKILL_MD = "skill-md"
 SOURCE_UNKNOWN = "unknown"
 
+# Inventory reliability policy (single source of truth). If the fraction of
+# skip/malformed warnings exceeds this threshold, the inventory is deemed
+# unreliable. The gate is `ratio <= THRESHOLD` (i.e. a ratio of exactly 0.20
+# is still reliable) so a single malformed skill in a small 3-5 skill
+# inventory does not trip the halt.
+RELIABILITY_THRESHOLD = 0.20
+
 _CONFIDENCE_BY_SOURCE = {
     SOURCE_METADATA: "T1",
     SOURCE_REFERENCES: "T2",
@@ -552,6 +588,53 @@ def enumerate_stack_skills(skills_root: Path) -> dict:
     return result
 
 
+# --------------------------------------------------------------------------
+# Derived output: unique library pairs (--pairs)
+# --------------------------------------------------------------------------
+
+
+def compute_pairs(skills: list[dict]) -> list[dict]:
+    """Deterministic unique library pairs from an inventory's skills[].
+
+    Returns `[{"library_a": a, "library_b": b}, ...]` over every
+    combination of the sorted, deduplicated skill names — exactly
+    N*(N-1)/2 entries for N distinct names. Sorting first makes the order
+    independent of directory-scan order and byte-stable across runs; the
+    dedup guards against a pathological repeated name yielding a duplicate
+    pair. Never drops or duplicates a pair, unlike in-context enumeration
+    at larger N.
+    """
+    names = sorted({e["name"] for e in skills})
+    return [
+        {"library_a": a, "library_b": b}
+        for a, b in itertools.combinations(names, 2)
+    ]
+
+
+# --------------------------------------------------------------------------
+# Derived output: inventory reliability verdict (--reliability)
+# --------------------------------------------------------------------------
+
+
+def compute_reliability(skill_count: int, warning_count: int) -> dict:
+    """Reliability verdict from the inventory's own counts.
+
+    `unreliable_ratio` = warning_count / (skill_count + warning_count),
+    or 0.0 for an empty inventory (no ZeroDivisionError). The inventory is
+    reliable when that ratio is <= RELIABILITY_THRESHOLD (boundary
+    inclusive). Emits the raw counts too so a caller's halt message can
+    render "{warning_count}/{skill_count+warning_count}".
+    """
+    total = skill_count + warning_count
+    unreliable_ratio = (warning_count / total) if total else 0.0
+    return {
+        "inventory_reliable": unreliable_ratio <= RELIABILITY_THRESHOLD,
+        "unreliable_ratio": unreliable_ratio,
+        "skill_count": skill_count,
+        "warning_count": warning_count,
+    }
+
+
 # --------------------------------------------------------------------------
 # CLI
 # --------------------------------------------------------------------------
@@ -566,6 +649,15 @@ def _cmd_enumerate(args: argparse.Namespace) -> int:
         )
         return 1
     result = enumerate_stack_skills(skills_root)
+    # Additive derived output — attached only when the flag is set, so the
+    # default shape stays {skills, cycles, warnings} for existing consumers.
+    if args.pairs:
+        result["pairs"] = compute_pairs(result["skills"])
+        result["pair_count"] = len(result["pairs"])
+    if args.reliability:
+        result.update(
+            compute_reliability(len(result["skills"]), len(result["warnings"]))
+        )
     json.dump(result, sys.stdout, indent=2)
     sys.stdout.write("\n")
     return 0
@@ -590,6 +682,23 @@ def _build_parser() -> argparse.ArgumentParser:
         "skills_root",
         help="directory containing skill packages (each subdir has SKILL.md)",
     )
+    p_enum.add_argument(
+        "--pairs",
+        action="store_true",
+        help=(
+            "additionally emit `pairs[]` (unique {library_a, library_b} "
+            "combinations over the sorted skill names) and `pair_count`"
+        ),
+    )
+    p_enum.add_argument(
+        "--reliability",
+        action="store_true",
+        help=(
+            "additionally emit the reliability verdict "
+            "(`inventory_reliable`, `unreliable_ratio`, `skill_count`, "
+            f"`warning_count`; threshold {RELIABILITY_THRESHOLD})"
+        ),
+    )
     p_enum.set_defaults(func=_cmd_enumerate)
 
     return parser

package/src/shared/scripts/skf-extract-public-api.py

@@ -261,6 +261,29 @@ def parse_settings_gradle(content: str) -> list[str]:
     return modules
 
 
+def parse_package_swift(content: str) -> dict:
+    """Best-effort parse of a SwiftPM Package.swift manifest.
+
+    SwiftPM has no version field in the manifest (versions come from git tags),
+    so `version` is always None; the brief falls back to target_version / default.
+    """
+    name_m = re.search(r"\bPackage\s*\(\s*name:\s*['\"]([^'\"]+)['\"]", content, re.DOTALL)
+    deps: list[str] = []
+    for m in re.finditer(r"\.package\s*\(\s*url:\s*['\"]([^'\"]+)['\"]", content):
+        seg = m.group(1).rstrip("/").rsplit("/", 1)[-1]
+        if seg.endswith(".git"):
+            seg = seg[: -len(".git")]
+        if seg:
+            deps.append(seg)
+    return {
+        "name": name_m.group(1).strip() if name_m else None,
+        "version": None,
+        "description": None,
+        "dependencies": deps,
+        "modules": [],
+    }
+
+
 # --------------------------------------------------------------------------
 # Export scanners
 # --------------------------------------------------------------------------
@@ -388,6 +411,35 @@ def scan_exports_kotlin(content: str, source_file: str) -> list[dict]:
     return out
 
 
+# Swift declarations are public only when explicitly marked `public`/`open`
+# (the default is internal). The lazy `[^\n]*?` skips intervening modifiers
+# (final/static/class-method/@attributes) between the access keyword and the
+# declaration keyword.
+_SWIFT_DECL_RE = re.compile(
+    r"^\s*(?:public|open)\b[^\n]*?\b"
+    r"(func|class|struct|enum|protocol|actor|typealias|var|let)\s+([A-Za-z_]\w*)",
+    re.MULTILINE,
+)
+_SWIFT_DECL_KEYWORDS = {
+    "func", "class", "struct", "enum", "protocol", "actor", "typealias", "var", "let",
+}
+
+
+def scan_exports_swift(content: str, source_file: str) -> list[dict]:
+    """Swift defaults to internal — emit only public/open declarations."""
+    out: list[dict] = []
+    seen: set[str] = set()
+    for m in _SWIFT_DECL_RE.finditer(content):
+        name = m.group(2)
+        # Guard the rare `public class func foo` case where the lazy skip stops
+        # on the `class` modifier and captures the next keyword as the name.
+        if name in _SWIFT_DECL_KEYWORDS or name in seen:
+            continue
+        seen.add(name)
+        out.append({"name": name, "type": m.group(1), "source_file": source_file})
+    return out
+
+
 # --------------------------------------------------------------------------
 # Orchestrator
 # --------------------------------------------------------------------------
@@ -405,6 +457,7 @@ LANGUAGE_DISPATCH: dict[str, tuple[ManifestParser, ExportScanner]] = {
     "go": (parse_go_mod, scan_exports_go),
     "java": (parse_pom_xml, scan_exports_java),
     "kotlin": (parse_gradle, scan_exports_kotlin),
+    "swift": (parse_package_swift, scan_exports_swift),
 }
 
 

package/src/shared/scripts/skf-find-cycles.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Find Cycles — enumerate the simple directed cycles in a pair graph.
+
+`skf-verify-stack`'s `integrations.md` §4 (Cross-Reference Each Integration
+Pair → Cycle detection) asks the LLM to build a directed pair graph — an edge
+`A → B` exists when skill A literally cites skill B via Check 4 — and then to
+"run cycle detection (DFS with visited + recursion stack)", appending one
+synthetic `Risky` verdict row per circular integration dependency found.
+
+Deciding *which* edges exist is a semantic judgment (Check-4 literal-citation
+analysis) and stays in the prompt. But once the edge set is fixed, the set of
+directed cycles is fully determined — a graph traversal with exactly one
+correct answer per edge set. In-prompt DFS silently misses real multi-hop
+cycles or invents spurious ones as the pair count grows; this helper makes the
+traversal deterministic and unit-testable. The prompt hands over the edges as
+JSON and appends the synthetic rows from `cycles[]` — no traversal by hand.
+
+Subcommand:
+  find --edges <json-file-or-'-'>
+      --edges  path to the edges JSON, or '-' to read from stdin.
+
+      Input shape (the Check-4 citation edges, one [from, to] pair each):
+        {"edges": [["A", "B"], ["B", "C"], ["C", "A"], ...]}
+
+      Emit JSON:
+        {
+          "cycles": [["A", "B", "C", "A"], ...],
+          "cycle_count": N
+        }
+
+      Each cycle is a closed node path: the first node is repeated at the end
+      (`A → B → C → A` renders as ["A", "B", "C", "A"]). Every simple directed
+      cycle is enumerated exactly once — de-duplicated across its rotations by
+      canonicalising to the lexicographically-minimal rotation. `cycles[]` is
+      sorted by length ASC then lexicographically for stable, reproducible
+      ordering. A self-loop edge (["A", "A"]) is a 1-node cycle ["A", "A"].
+
+CLI examples:
+  uv run skf-find-cycles.py find --edges edges.json
+  echo '{"edges": [["A","B"],["B","A"]]}' | uv run skf-find-cycles.py find --edges -
+
+Exit codes:
+  0  — operation succeeded (including: no cycles / empty edge set → empty list)
+  2  — malformed input (bad JSON, wrong shape, non-string node) or internal
+       error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+class InputError(Exception):
+    """A malformed-input error → exit code 2."""
+
+
+# --------------------------------------------------------------------------
+# Input validation
+# --------------------------------------------------------------------------
+
+
+def parse_edges(payload: object) -> list[tuple[str, str]]:
+    """Validate and normalise the edges payload.
+
+    Accepts `{"edges": [[from, to], ...]}`; each edge must be a two-element
+    array of non-empty strings. Raises InputError on any structural defect.
+    Returns a list of (from, to) tuples (order preserved; duplicates kept —
+    they collapse during adjacency construction).
+    """
+    if not isinstance(payload, dict):
+        raise InputError(
+            f"input must be a JSON object with an `edges` key; "
+            f"got {type(payload).__name__}"
+        )
+    edges = payload.get("edges")
+    if not isinstance(edges, list):
+        raise InputError("input `edges` must be a JSON array of [from, to] pairs")
+    normalized: list[tuple[str, str]] = []
+    for idx, edge in enumerate(edges):
+        if not isinstance(edge, list) or len(edge) != 2:
+            raise InputError(
+                f"edges[{idx}] must be a two-element [from, to] array; got {edge!r}"
+            )
+        src, dst = edge
+        if not isinstance(src, str) or not src:
+            raise InputError(f"edges[{idx}][0] must be a non-empty string; got {src!r}")
+        if not isinstance(dst, str) or not dst:
+            raise InputError(f"edges[{idx}][1] must be a non-empty string; got {dst!r}")
+        normalized.append((src, dst))
+    return normalized
+
+
+# --------------------------------------------------------------------------
+# Cycle enumeration
+# --------------------------------------------------------------------------
+
+
+def _canonicalize(cycle_nodes: list[str]) -> tuple[str, ...]:
+    """Return the lexicographically-minimal rotation of a cycle's node list.
+
+    `cycle_nodes` is the cycle without the closing repeat (e.g. ["B","C","A"]
+    for B → C → A → B). All rotations describe the same directed cycle; the
+    minimal rotation is the stable de-duplication key ((A, B, C) here).
+    """
+    n = len(cycle_nodes)
+    rotations = [tuple(cycle_nodes[i:] + cycle_nodes[:i]) for i in range(n)]
+    return min(rotations)
+
+
+def find_cycles(edges: list[tuple[str, str]]) -> dict:
+    """Enumerate every simple directed cycle in the edge set.
+
+    Deterministic: same edge set → byte-identical output. Runs a DFS from each
+    node (in sorted order) tracking the current recursion path; whenever the
+    walk returns to its start node a cycle is recorded, canonicalised to its
+    minimal rotation, and de-duplicated. Graphs here are small pair graphs, so
+    the exhaustive enumeration is inexpensive.
+    """
+    # Build sorted, de-duplicated adjacency for deterministic traversal.
+    adj: dict[str, list[str]] = {}
+    nodes: set[str] = set()
+    for src, dst in edges:
+        adj.setdefault(src, [])
+        if dst not in adj[src]:
+            adj[src].append(dst)
+        nodes.add(src)
+        nodes.add(dst)
+    for src in adj:
+        adj[src].sort()
+
+    seen: set[tuple[str, ...]] = set()
+
+    def dfs(start: str, current: str, path: list[str], on_stack: set[str]) -> None:
+        for nxt in adj.get(current, ()):
+            if nxt == start:
+                canon = _canonicalize(path)
+                seen.add(canon)
+            elif nxt not in on_stack:
+                on_stack.add(nxt)
+                path.append(nxt)
+                dfs(start, nxt, path, on_stack)
+                path.pop()
+                on_stack.discard(nxt)
+
+    for start in sorted(nodes):
+        dfs(start, start, [start], {start})
+
+    # Stable output order: by cycle length, then lexicographically.
+    ordered = sorted(seen, key=lambda c: (len(c), c))
+    cycles = [list(c) + [c[0]] for c in ordered]
+    return {"cycles": cycles, "cycle_count": len(cycles)}
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+
+def _read_source(source: str) -> str:
+    """Read text from a file path or stdin (if source == '-')."""
+    if source == "-":
+        try:
+            return sys.stdin.read()
+        except OSError as exc:
+            raise InputError(f"failed to read --edges from stdin: {exc}") from exc
+    path = Path(source)
+    if not path.is_file():
+        raise InputError(f"--edges file not found: {path}")
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise InputError(f"failed to read --edges file {path}: {exc}") from exc
+
+
+def _cmd_find(args: argparse.Namespace) -> int:
+    text = _read_source(args.edges)
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise InputError(f"malformed JSON in --edges input: {exc}") from exc
+    edges = parse_edges(payload)
+    result = find_cycles(edges)
+    if args.verbose:
+        print(
+            f"analyzed {len(edges)} edge(s); found {result['cycle_count']} cycle(s)",
+            file=sys.stderr,
+        )
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skf-find-cycles",
+        description=(
+            "Enumerate the simple directed cycles in an integration pair graph "
+            "(skf-verify-stack integrations.md §4 cycle detection)."
+        ),
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_find = sub.add_parser(
+        "find",
+        help="emit the de-duplicated simple directed cycles as JSON",
+    )
+    p_find.add_argument(
+        "--edges",
+        required=True,
+        help=(
+            "path to the edges JSON, or '-' for stdin. "
+            'Shape: {"edges": [["<from>", "<to>"], ...]}'
+        ),
+    )
+    p_find.add_argument(
+        "--verbose",
+        action="store_true",
+        help="print a one-line summary to stderr",
+    )
+    p_find.set_defaults(func=_cmd_find)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except InputError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except Exception as exc:  # noqa: BLE001 — last-resort guard → exit 2
+        print(f"internal error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())