bmad-module-skill-forge 1.4.1 → 1.5.1

package/src/shared/scripts/skf-detect-tools.py

@@ -1,19 +1,19 @@
 # /// script
 # requires-python = ">=3.10"
-# dependencies = []
+# dependencies = ["pyyaml"]
 # ///
 """SKF Detect Tools — Parallel tool detection + tier calculation for skf-setup.
 
-Replaces the prose-driven tool-detection sequence in `src/skf-setup/steps-c/
-step-01-detect-and-tier.md` §3-§8b with one Python invocation. Probes ast-grep,
+Replaces the prose-driven tool-detection sequence in `src/skf-setup/references/
+detect-and-tier.md` §3-§8b with one Python invocation. Probes ast-grep,
 gh, qmd, and ccc concurrently, applies the 4-rule tier decision table (see
 `src/skf-setup/references/tier-rules.md`), evaluates --tier-override (with
 sanity check) and --require-tier (with tool-prerequisite check independent of
 the tier name), and emits one JSON document on stdout.
 
 Schema documented in DETECT_OUTPUT_SCHEMA at the bottom of this docstring.
-The output is consumed by step-01 prose, step-02 (forge-tier.yaml writer),
-and step-04 (status report + envelope).
+The output is consumed by step 1 prose, step 2 (forge-tier.yaml writer),
+and step 4 (status report + envelope).
 
 Tier rules (first match wins):
   Deep   = ast-grep + gh-cli + qmd (all healthy)
@@ -21,12 +21,12 @@ Tier rules (first match wins):
   Forge  = ast-grep
   Quick  = otherwise
 
-CCC verification is two-step (matches step-01 §7):
+CCC verification is two-step (matches step 1 §7):
   Step A: `ccc --help` exits 0 AND output contains "CocoIndex Code" marker.
           Rejects code2prompt-aliased-as-ccc and similar PATH shadowing.
   Step B: `ccc doctor` succeeds (daemon healthy).
 
-QMD verification is two-step (matches step-01 §5 post-PR-#248):
+QMD verification is two-step (matches step 1 §5 post-PR-#248):
   Step A: `qmd --version` exits 0 (binary identity, falls back to --help).
   Step B: `qmd status` succeeds (daemon healthy).
   qmd_status: "absent" | "daemon_stopped" | "healthy" — affects climb hint.
@@ -88,13 +88,26 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import shutil
 import subprocess
 import sys
+import tempfile
 from concurrent.futures import ThreadPoolExecutor
 
 
 VALID_TIERS = ("Quick", "Forge", "Forge+", "Deep")
 PROBE_TIMEOUT_SEC = 8  # per-tool subprocess.run timeout
+# Prefer the OS `timeout(1)` utility to bound each probe. A daemon-backed
+# tool (e.g. `qmd status`) can block in an uninterruptible syscall against
+# its daemon; `subprocess.run`'s own post-timeout `process.wait()` is
+# unbounded and never returns in that case, hanging the whole detector.
+# `timeout --kill-after` reaps the child (and its session) at the OS level,
+# so Python's wait always returns. POSIX-only: Windows' `timeout.exe` is an
+# unrelated builtin (waits for input; cannot run a command), and the
+# uninterruptible-wait hang is itself POSIX-specific (Windows uses a
+# forcible TerminateProcess), so on Windows we fall back to subprocess.run's
+# own timeout. None when unavailable.
+_TIMEOUT_BIN = shutil.which("timeout") if os.name == "posix" else None
 CCC_IDENTITY_MARKER = "cocoindex code"  # case-insensitive substring
 
 
@@ -115,16 +128,45 @@ def _run(cmd: list[str], timeout: int = PROBE_TIMEOUT_SEC) -> tuple[int, str, st
     Treats every failure mode (FileNotFoundError, TimeoutExpired, OSError,
     CalledProcessError) as a failed probe — returns rc=127 and an empty
     stdout/stderr. Tool detection should never crash the workflow.
+
+    The child is wrapped in the OS `timeout(1)` utility (when available) so a
+    daemon-backed probe blocked in an uninterruptible syscall (e.g.
+    `qmd status` waiting on its daemon socket) is reaped at the OS level —
+    `subprocess.run`'s own post-timeout `process.wait()` is unbounded and
+    would otherwise never return, hanging the whole detector. Child
+    stdout/stderr are redirected to temp files (no pipe to drain), and
+    `start_new_session=True` isolates the child's process group; the
+    Python-level timeout is a secondary net set slightly above the OS one.
     """
+    if _TIMEOUT_BIN:
+        run_cmd = [_TIMEOUT_BIN, "--kill-after=2", str(timeout), *cmd]
+        py_timeout = timeout + 5
+    else:
+        run_cmd = cmd
+        py_timeout = timeout
     try:
-        result = subprocess.run(
-            cmd,
-            capture_output=True,
-            text=True,
-            timeout=timeout,
-            check=False,
-        )
-        return result.returncode, result.stdout or "", result.stderr or ""
+        with tempfile.TemporaryFile() as out_f, tempfile.TemporaryFile() as err_f:
+            result = subprocess.run(
+                run_cmd,
+                stdin=subprocess.DEVNULL,
+                stdout=out_f,
+                stderr=err_f,
+                timeout=py_timeout,
+                check=False,
+                start_new_session=True,
+            )
+            # Mocked unit tests patch `subprocess.run` to return a fake with
+            # `.stdout`/`.stderr` strings set; real runs redirect to the temp
+            # files (so `result.stdout` is None — read the files instead).
+            stdout = result.stdout
+            if stdout is None:
+                out_f.seek(0)
+                stdout = out_f.read().decode("utf-8", "replace")
+            stderr = result.stderr
+            if stderr is None:
+                err_f.seek(0)
+                stderr = err_f.read().decode("utf-8", "replace")
+            return result.returncode, stdout or "", stderr or ""
     except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
         return 127, "", ""
 
@@ -251,6 +293,50 @@ def tier_prerequisites_met(tier: str, tools: dict) -> tuple[bool, list[str]]:
     return (len(missing) == 0, missing)
 
 
+def read_prior_state(prior_state_path) -> dict:
+    """Read forge-tier.yaml from a previous run, return prior tier / tools / detection_date.
+
+    Returns a flat dict (always present, keys always set) so callers don't
+    branch on missing-file vs empty-file vs malformed-file — the script owns
+    that classification. On any read failure or absent file, returns the
+    "first-run" shape (everything null/empty). The CCC freshness fields are
+    surfaced separately so the caller doesn't reparse YAML in prose.
+    """
+    empty = {
+        "previous_tier": None,
+        "previous_detection_date": None,
+        "previous_tools": {},
+        "previous_ccc_index_status": None,
+        "previous_ccc_indexed_path": None,
+        "previous_ccc_last_indexed": None,
+        "previous_ccc_staleness_threshold_hours": None,
+    }
+    if not prior_state_path:
+        return empty
+    try:
+        import yaml  # local import — only needed when --prior-state-from is used
+        from pathlib import Path as _P
+        p = _P(prior_state_path)
+        if not p.exists():
+            return empty
+        data = yaml.safe_load(p.read_text(encoding="utf-8")) or {}
+    except Exception:
+        return empty
+
+    tools_map = data.get("tools") if isinstance(data.get("tools"), dict) else {}
+    ccc_index = data.get("ccc_index") if isinstance(data.get("ccc_index"), dict) else {}
+
+    return {
+        "previous_tier": data.get("tier") if data.get("tier") in VALID_TIERS else None,
+        "previous_detection_date": data.get("tier_detected_at"),
+        "previous_tools": tools_map,
+        "previous_ccc_index_status": ccc_index.get("status"),
+        "previous_ccc_indexed_path": ccc_index.get("indexed_path"),
+        "previous_ccc_last_indexed": ccc_index.get("last_indexed"),
+        "previous_ccc_staleness_threshold_hours": ccc_index.get("staleness_threshold_hours"),
+    }
+
+
 def detect(args: argparse.Namespace) -> dict:
     tools: dict = {}
     with ThreadPoolExecutor(max_workers=4) as ex:
@@ -302,6 +388,9 @@ def detect(args: argparse.Namespace) -> dict:
     else:
         require_satisfied = None
 
+    prior = read_prior_state(getattr(args, "prior_state_from", None))
+    deltas = compute_deltas(tools, prior, calculated)
+
     return {
         "tools": tools,
         "tier": {
@@ -320,6 +409,38 @@ def detect(args: argparse.Namespace) -> dict:
             "satisfied": require_satisfied,
             "missing_tools": require_missing,
         },
+        "prior": prior,
+        "deltas": deltas,
+    }
+
+
+def compute_deltas(current_tools: dict, prior: dict, calculated_tier: str) -> dict:
+    """Compute re-run deltas (tools added/removed, tier_changed, ccc_index_is_fresh).
+
+    Removes ~80 tokens of LLM-side set arithmetic + string compare from the
+    interactive banner branch in references/report.md. First-run convention
+    (prior.previous_tier is null): tools_added = currently-available tools,
+    tools_removed = [], tier_changed = false.
+    """
+    tool_keys = ("ast_grep", "gh_cli", "qmd", "ccc")
+    cur_avail = {k: bool((current_tools.get(k) or {}).get("available")) for k in tool_keys}
+
+    prev_tools_raw = prior.get("previous_tools") or {}
+    if prev_tools_raw:
+        prev_avail = {k: bool(prev_tools_raw.get(k, False)) for k in tool_keys}
+        tools_added = sorted(k for k in tool_keys if cur_avail[k] and not prev_avail[k])
+        tools_removed = sorted(k for k in tool_keys if prev_avail[k] and not cur_avail[k])
+    else:
+        tools_added = sorted(k for k in tool_keys if cur_avail[k])
+        tools_removed = []
+
+    prior_tier = prior.get("previous_tier")
+    tier_changed = bool(prior_tier and prior_tier != calculated_tier)
+
+    return {
+        "tools_added": tools_added,
+        "tools_removed": tools_removed,
+        "tier_changed": tier_changed,
     }
 
 
@@ -332,7 +453,7 @@ def main() -> None:
         "--tier-override",
         default=None,
         help="Force a specific tier (must be one of Quick, Forge, Forge+, Deep — case-sensitive)."
-             " Invalid values are flagged in the output rather than rejected, so step-04 can"
+             " Invalid values are flagged in the output rather than rejected, so step 4 can"
              " surface the warning to the user.",
     )
     parser.add_argument(
@@ -349,6 +470,16 @@ def main() -> None:
         help="Environment variable name to check for security-scan availability"
              " (informational only — does NOT affect tier). Default: SNYK_TOKEN.",
     )
+    parser.add_argument(
+        "--prior-state-from",
+        default=None,
+        help="Optional path to a previous-run forge-tier.yaml. When provided,"
+             " the script reads it and surfaces previous_tier, previous_tools,"
+             " previous_detection_date, and previous_ccc_* fields under the 'prior'"
+             " key — removing YAML-parse responsibility from the step prompt."
+             " Missing file or unreadable YAML returns the first-run shape (all"
+             " null/empty) without erroring.",
+    )
     args = parser.parse_args()
 
     payload = detect(args)

package/src/shared/scripts/skf-detect-workspaces.py

@@ -8,7 +8,7 @@ Takes a JSON payload on stdin describing a target repo's file tree plus the
 contents of a small set of root manifests, and returns whether a workspace
 layout is present, which manifest kind drives it, and the list of resolved
 workspaces. The helper does NO file I/O — the caller (typically
-skf-brief-skill step-02 §1b) fetches files via `gh api` / local filesystem
+skf-brief-skill step 2 §1b) fetches files via `gh api` / local filesystem
 and pipes the relevant content in.
 
 Detection runs in priority order; the first matching detector wins: