bmad-module-skill-forge 2.0.0 → 2.0.2

package/src/shared/scripts/skf-count-tokens.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""SKF Count Tokens — Deterministic per-artifact token/word metrics for a skill package.
+
+Pre-pass that measures the exported artifacts of a single skill package and the
+shared managed section, so the export skill's token report (references/token-report.md)
+and snippet token check (references/generate-snippet.md §4) render exact numbers from
+JSON instead of re-reading every reference file to word-count it in-prompt.
+
+Metrics:
+  - words:  whitespace-split word count (`len(text.split())`) — the report's "Words" column
+  - tokens: char-over-four estimate (`len(text) // 4`) — the SKF-wide convention already
+            used by skf-validate-output.py, so every SKF token number agrees
+
+Measured artifacts (all relative to the positional skill-package dir):
+  - context-snippet.md   — the compressed passive-context snippet (if present)
+  - SKILL.md             — the active skill document
+  - metadata.json        — machine-readable metadata
+  - references/*         — every file under references/ (recursively), summed as references_total
+  - managed section      — the complete <!-- SKF:BEGIN ... --> ... <!-- SKF:END --> block,
+                           extracted from the first --target-file that contains one
+                           (shared across the batch; measured once)
+
+package_total sums context-snippet.md + SKILL.md + metadata.json + references_total and
+DELIBERATELY EXCLUDES the managed-section row — the managed section is a shared all-skills
+cost reported separately, and including it would double-count this skill's own snippet
+(see references/token-report.md §1).
+
+CLI:
+  python3 skf-count-tokens.py <skill-package-dir>
+  python3 skf-count-tokens.py <skill-package-dir> --target-file CLAUDE.md
+  python3 skf-count-tokens.py <skill-package-dir> --target-file CLAUDE.md --target-file AGENTS.md
+  python3 skf-count-tokens.py <skill-package-dir> -o report.json
+
+Exit codes: 0 = metrics emitted, 2 = error (skill package dir missing / not a directory).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# Mirrors skf-rebuild-managed-sections.py: a BEGIN marker may carry attributes
+# (e.g. `updated:2026-07-13`) before its closing `-->`; the END marker is fixed.
+MANAGED_SECTION_RE = re.compile(
+    r"<!-- SKF:BEGIN[^>]*-->.*?<!-- SKF:END -->",
+    re.DOTALL,
+)
+
+# Core per-skill artifacts, in report order. (references/ is handled separately.)
+CORE_ARTIFACTS = [
+    ("context-snippet.md", "context-snippet"),
+    ("SKILL.md", "skill-md"),
+    ("metadata.json", "metadata"),
+]
+
+
+def estimate_tokens(text: str) -> int:
+    """Char-over-four token estimate — the SKF-wide convention (see skf-validate-output.py)."""
+    return len(text) // 4
+
+
+def count_words(text: str) -> int:
+    """Whitespace-split word count — the token report's 'Words' column."""
+    return len(text.split())
+
+
+def measure(text: str) -> dict:
+    """Return the {words, tokens} metrics for a piece of text."""
+    return {"words": count_words(text), "tokens": estimate_tokens(text)}
+
+
+def _read_text(path: Path) -> str:
+    # encoding is pinned to utf-8 so non-ASCII content is not mojibaked on
+    # Windows (cp1252 default).
+    return path.read_text(encoding="utf-8")
+
+
+def extract_managed_section(text: str) -> str | None:
+    """Return the complete BEGIN..END managed-section span (markers included), or None."""
+    m = MANAGED_SECTION_RE.search(text)
+    return m.group(0) if m else None
+
+
+def measure_reference_files(references_dir: Path) -> tuple[list[dict], dict]:
+    """Measure every file under references/ (recursively, sorted). Returns (per-file rows, total)."""
+    rows: list[dict] = []
+    total_words = 0
+    total_tokens = 0
+    if references_dir.is_dir():
+        for path in sorted(references_dir.rglob("*"), key=lambda p: p.as_posix()):
+            if not path.is_file():
+                continue
+            text = _read_text(path)
+            metrics = measure(text)
+            rows.append(
+                {
+                    "path": path.relative_to(references_dir.parent).as_posix(),
+                    "role": "reference",
+                    "exists": True,
+                    **metrics,
+                }
+            )
+            total_words += metrics["words"]
+            total_tokens += metrics["tokens"]
+    total = {"count": len(rows), "words": total_words, "tokens": total_tokens}
+    return rows, total
+
+
+def count_package(skill_dir: Path, target_files: list[Path] | None = None) -> dict:
+    """Measure a skill package's artifacts and the shared managed section.
+
+    Returns the metrics dict (see module docstring for the shape). Missing core
+    artifacts are reported with exists=False and zero metrics so package_total is
+    always well-defined and callers can render 'N/A' rows without guessing.
+    """
+    skill_dir = Path(skill_dir)
+    target_files = target_files or []
+
+    files: list[dict] = []
+
+    # Core per-skill artifacts.
+    for name, role in CORE_ARTIFACTS:
+        path = skill_dir / name
+        if path.is_file():
+            metrics = measure(_read_text(path))
+            files.append({"path": name, "role": role, "exists": True, **metrics})
+        else:
+            files.append({"path": name, "role": role, "exists": False, "words": 0, "tokens": 0})
+
+    # references/ — per-file rows + summed total.
+    ref_rows, references_total = measure_reference_files(skill_dir / "references")
+    files.extend(ref_rows)
+
+    # package_total = snippet + SKILL.md + metadata + references_total; EXCLUDES managed section.
+    core_by_role = {row["role"]: row for row in files if row["role"] in {"context-snippet", "skill-md", "metadata"}}
+    package_total = {
+        "words": sum(core_by_role[r]["words"] for r in core_by_role) + references_total["words"],
+        "tokens": sum(core_by_role[r]["tokens"] for r in core_by_role) + references_total["tokens"],
+    }
+
+    # Managed section — first --target-file that actually contains a block wins.
+    managed_section = {"present": False, "source_file": None, "words": 0, "tokens": 0}
+    for tf in target_files:
+        tf = Path(tf)
+        if not tf.is_file():
+            continue
+        section = extract_managed_section(_read_text(tf))
+        if section is not None:
+            managed_section = {
+                "present": True,
+                "source_file": tf.as_posix(),
+                **measure(section),
+            }
+            break
+
+    return {
+        "status": "ok",
+        "skill_package": skill_dir.as_posix(),
+        "files": files,
+        "references_total": references_total,
+        "managed_section": managed_section,
+        "package_total": package_total,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-count-tokens.py",
+        description=(
+            "Deterministic per-artifact word/token metrics for a skill package. Emits JSON "
+            "with per-file rows, references_total, the shared managed-section block, and a "
+            "package_total that excludes the managed section (see references/token-report.md §1). "
+            "tokens = len(text)//4 (SKF-wide convention); words = whitespace-split count."
+        ),
+    )
+    parser.add_argument(
+        "skill_package",
+        help="Resolved skill-package directory (holds context-snippet.md, SKILL.md, metadata.json, references/)",
+    )
+    parser.add_argument(
+        "--target-file",
+        action="append",
+        default=[],
+        metavar="PATH",
+        help="Context file (CLAUDE.md / AGENTS.md / .cursorrules) to extract the managed "
+        "section from; repeatable — the first file with a BEGIN..END block is measured.",
+    )
+    parser.add_argument("-o", "--output", metavar="PATH", help="Write JSON here (default: stdout)")
+    parser.add_argument("--verbose", action="store_true", help="Emit diagnostics to stderr")
+    args = parser.parse_args(argv)
+
+    skill_dir = Path(args.skill_package)
+    if not skill_dir.is_dir():
+        print(f"error: skill package directory not found: {skill_dir}", file=sys.stderr)
+        return 2
+
+    if args.verbose:
+        print(f"measuring skill package: {skill_dir}", file=sys.stderr)
+        if args.target_file:
+            print(f"managed-section candidates: {args.target_file}", file=sys.stderr)
+
+    result = count_package(skill_dir, [Path(p) for p in args.target_file])
+
+    payload = json.dumps(result, indent=2)
+    if args.output:
+        Path(args.output).write_text(payload + "\n", encoding="utf-8")
+        if args.verbose:
+            print(f"wrote {args.output}", file=sys.stderr)
+    else:
+        print(payload)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -38,6 +38,42 @@ Exit codes:
   0  found >=1 documentation source
   1  no documentation sources found (empty array)
   2  error (invalid args, gh not found, etc.)
+
+---------------------------------------------------------------------------
+Subcommand: compare-hashes
+---------------------------------------------------------------------------
+
+Doc-drift detection for audit-skill.  Given a set of tracked doc sources
+(each `{url, content_hash}`), re-fetch every URL, hash the response bytes with
+the SAME fetch+sha256 primitive the compile side used, and classify each entry
+as changed / unchanged / fetch_failed / skipped_null_hash.  This replaces the
+per-URL fetch/hash/compare/count prose at
+`src/skf-audit-skill/references/step-doc-drift.md` §2-3 — the model no longer
+orchestrates HTTP GETs or computes sha256 by hand, and correctness no longer
+depends on whether a WebFetch tool is wired.
+
+  uv run src/shared/scripts/skf-detect-docs.py compare-hashes <source>
+
+Input `<source>`:
+  - a path to a JSON file that is EITHER an array of `{url, content_hash}`
+    entries OR an object with a `doc_sources` array (e.g. a skill's
+    metadata.json), OR
+  - `-` to read that JSON from stdin.
+
+Output (JSON object on stdout):
+  {
+    "changed":           [{"url","old_hash","new_hash"}],
+    "unchanged":         [{"url"}],
+    "fetch_failed":      [{"url","old_hash","reason"}],
+    "skipped_null_hash": [{"url"}],
+    "stats": {"total_tracked","changed","unchanged",
+              "fetch_failed","skipped_null_hash"}
+  }
+
+Each list is stably sorted by url.  Stored hashes are normalized (leading
+`algo:` prefix stripped) before comparison so a bare-hex writer form still
+matches.  Exit 0 on any well-formed input (never blocks the informational
+audit); exit 2 on malformed args or JSON.
 """
 
 from __future__ import annotations
@@ -47,12 +83,13 @@ import base64
 import hashlib
 import json
 import re
+import socket
 import subprocess
 import sys
 import urllib.error
 import urllib.request
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 _GITHUB_URL_RE = re.compile(
     r"https?://(?:www\.)?github\.com/([^/\s]+)/([^/\s.]+?)(?:\.git)?/?$",
@@ -224,6 +261,57 @@ def _fetch_and_hash(url: str) -> Optional[str]:
         return None
 
 
+# Leading algorithm-name prefix on a stored hash (`sha256:`, `sha1:`, ...) so a
+# bare-hex writer form and the prefixed form compare equal.
+_HASH_PREFIX_RE = re.compile(r"^[a-z0-9]+:")
+
+
+def _normalize_hash(value: Optional[str]) -> Optional[str]:
+    """Strip a leading `algo:` prefix from a hash so bare-hex and prefixed
+    forms compare equal. Returns None for non-string input. Idempotent."""
+    if not isinstance(value, str):
+        return None
+    return _HASH_PREFIX_RE.sub("", value, count=1)
+
+
+def _fetch_and_hash_reason(url: str) -> Tuple[Optional[str], Optional[str]]:
+    """Byte-symmetric sibling of `_fetch_and_hash` that surfaces WHY a fetch
+    failed for drift reporting.
+
+    Uses the identical fetch+sha256 primitive as the compile side — same
+    `USER_AGENT`, same `_FETCH_TIMEOUT`, sha256 of the raw response bytes with
+    the `sha256:` prefix — so a hash produced here compares byte-for-byte
+    against a `content_hash` written by `_fetch_and_hash` at compile time.
+
+    Returns `(content_hash, None)` on success or `(None, reason)` on failure.
+    Never raises: the doc-drift audit must never abort on a bad URL.
+    """
+    if url.startswith("file://"):
+        local_path = url[7:]
+        try:
+            with open(local_path, "rb") as fh:
+                content = fh.read()
+        except OSError as exc:
+            return None, f"local read failed: {exc}"
+        return "sha256:" + hashlib.sha256(content).hexdigest(), None
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    try:
+        with urllib.request.urlopen(req, timeout=_FETCH_TIMEOUT) as resp:
+            content = resp.read()
+    except urllib.error.HTTPError as exc:
+        return None, f"HTTP {exc.code}"
+    except (socket.timeout, TimeoutError):
+        return None, f"timeout after {_FETCH_TIMEOUT}s"
+    except urllib.error.URLError as exc:
+        reason = getattr(exc, "reason", exc)
+        if isinstance(reason, (socket.timeout, TimeoutError)):
+            return None, f"timeout after {_FETCH_TIMEOUT}s"
+        return None, f"URL error: {reason}"
+    except Exception as exc:  # never let a malformed URL crash the audit
+        return None, f"fetch failed: {exc}"
+    return "sha256:" + hashlib.sha256(content).hexdigest(), None
+
+
 # ---------------------------------------------------------------------------
 # Detection method 1 — homepageUrl
 # ---------------------------------------------------------------------------
@@ -376,11 +464,154 @@ def detect(
     return deduped
 
 
+# ---------------------------------------------------------------------------
+# compare-hashes subcommand — doc-drift detection for audit-skill
+# ---------------------------------------------------------------------------
+
+def _load_doc_sources(raw_text: str, source_label: str) -> List[Any]:
+    """Parse a compare-hashes input blob into a list of doc-source entries.
+
+    Accepts either a top-level JSON array of `{url, content_hash}` entries or a
+    top-level object with a `doc_sources` array (e.g. a skill's metadata.json).
+    An object without `doc_sources` yields an empty list (nothing tracked).
+
+    Raises ValueError on malformed JSON or an unexpected top-level shape.
+    """
+    try:
+        data = json.loads(raw_text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"malformed JSON in {source_label}: {exc}") from exc
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        entries = data.get("doc_sources")
+        if entries is None:
+            return []
+        if not isinstance(entries, list):
+            raise ValueError(f"`doc_sources` in {source_label} is not an array")
+        return entries
+    raise ValueError(
+        f"{source_label} must be a JSON array or an object with a "
+        f"`doc_sources` array; got {type(data).__name__}"
+    )
+
+
+def compare_doc_hashes(doc_sources: List[Any]) -> Dict[str, Any]:
+    """Fetch/hash/compare each tracked doc source and categorize it.
+
+    Deterministic: the same entries served the same upstream bytes always
+    yield the same categorization. Every entry lands in exactly one bucket, so
+    `stats.total_tracked` == the sum of the four category counts.
+    """
+    changed: List[Dict[str, Any]] = []
+    unchanged: List[Dict[str, Any]] = []
+    fetch_failed: List[Dict[str, Any]] = []
+    skipped_null_hash: List[Dict[str, Any]] = []
+
+    for entry in doc_sources:
+        if not isinstance(entry, dict):
+            fetch_failed.append(
+                {"url": "", "old_hash": None, "reason": "invalid entry: not an object"}
+            )
+            continue
+        url = entry.get("url")
+        if not isinstance(url, str) or not url:
+            fetch_failed.append({
+                "url": url if isinstance(url, str) else "",
+                "old_hash": entry.get("content_hash"),
+                "reason": "invalid entry: missing url",
+            })
+            continue
+        stored = entry.get("content_hash")
+        if stored is None:
+            # No baseline hash was recorded at compile time — nothing to
+            # compare against, so skip the fetch entirely.
+            skipped_null_hash.append({"url": url})
+            continue
+        new_hash, reason = _fetch_and_hash_reason(url)
+        if new_hash is None:
+            fetch_failed.append({"url": url, "old_hash": stored, "reason": reason})
+        elif _normalize_hash(new_hash) == _normalize_hash(stored):
+            unchanged.append({"url": url})
+        else:
+            changed.append({"url": url, "old_hash": stored, "new_hash": new_hash})
+
+    changed.sort(key=lambda e: e["url"])
+    unchanged.sort(key=lambda e: e["url"])
+    fetch_failed.sort(key=lambda e: e["url"])
+    skipped_null_hash.sort(key=lambda e: e["url"])
+
+    total = len(changed) + len(unchanged) + len(fetch_failed) + len(skipped_null_hash)
+    return {
+        "changed": changed,
+        "unchanged": unchanged,
+        "fetch_failed": fetch_failed,
+        "skipped_null_hash": skipped_null_hash,
+        "stats": {
+            "total_tracked": total,
+            "changed": len(changed),
+            "unchanged": len(unchanged),
+            "fetch_failed": len(fetch_failed),
+            "skipped_null_hash": len(skipped_null_hash),
+        },
+    }
+
+
+def _cmd_compare_hashes(argv: List[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-detect-docs.py compare-hashes",
+        description=(
+            "Re-fetch each tracked doc URL, hash the response bytes, and "
+            "compare against the stored content_hash to detect doc drift."
+        ),
+    )
+    parser.add_argument(
+        "source",
+        help=(
+            "path to a JSON file (array of {url, content_hash} entries, or an "
+            "object with a doc_sources array such as metadata.json), or - to "
+            "read that JSON from stdin"
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    if args.source == "-":
+        raw = sys.stdin.read()
+        label = "<stdin>"
+    else:
+        path = Path(args.source)
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            json.dump({"error": f"cannot read {path}: {exc}", "code": "READ_ERROR"}, sys.stderr)
+            sys.stderr.write("\n")
+            return 2
+        label = str(path)
+
+    try:
+        doc_sources = _load_doc_sources(raw, label)
+    except ValueError as exc:
+        json.dump({"error": str(exc), "code": "INVALID_JSON"}, sys.stderr)
+        sys.stderr.write("\n")
+        return 2
+
+    result = compare_doc_hashes(doc_sources)
+    json.dump(result, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # CLI entry point
 # ---------------------------------------------------------------------------
 
 def main() -> int:
+    # Additive subcommand: route `compare-hashes ...` to the doc-drift path
+    # before the existing detect parser runs. The default (no subcommand)
+    # invocation `--repo-url <url> ...` is unchanged.
+    if len(sys.argv) > 1 and sys.argv[1] == "compare-hashes":
+        return _cmd_compare_hashes(sys.argv[2:])
+
     parser = argparse.ArgumentParser(
         description="Detect documentation URLs for a GitHub repository.",
     )

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

@@ -58,6 +58,16 @@ Output (JSON on stdout):
   detection_source  — human-readable string naming what fired (manifest
                        basename, extension share, etc.)
   fallback_to_extension_frequency — bool (true when rule 10 fired)
+  detected_languages — ordered, deduplicated list of EVERY manifest-level
+                       match in the same priority order the winner walk uses.
+                       language == detected_languages[0] whenever the manifest
+                       table fired, so a caller can auto-pick detected_languages[0]
+                       and gate multi-language disambiguation on
+                       len(detected_languages) > 1. Special cases: a
+                       workspace_signal override (rule 0) is decisive and returns
+                       a single-element [language]; the extension-frequency
+                       fallback (rule 10) contributes [language] for a best guess
+                       or [] when language is "unknown".
 
 Exit codes:
   0 — recommendation produced (even when language is "unknown")
@@ -201,7 +211,74 @@ def _frequency_fallback(tree: list[str]) -> dict[str, Any]:
     }
 
 
+def _detected_languages(payload: dict[str, Any], winner: dict[str, Any]) -> list[str]:
+    """Accumulate every manifest-level match into an ordered, deduplicated list.
+
+    The walk mirrors the winner-selection priority order exactly, so
+    winner["language"] == detected_languages[0] whenever the manifest table
+    fired. Two decisive short-circuits diverge from a full walk on purpose:
+
+      * A workspace_signal override (rule 0) is authoritative — the workspace
+        root language wins over any nested package.json, so this returns a
+        single-element [winner_language] and never surfaces a spurious
+        multi-language gate for what workspace detection already resolved.
+      * When no manifest matched (rule 10 fired), the list carries the
+        extension-frequency best guess as a single element, or [] when the
+        guess was "unknown".
+    """
+    tree: list[str] = payload["tree"]  # validated non-empty by _winner()
+
+    workspace_signal = payload.get("workspace_signal")
+    if isinstance(workspace_signal, str) and workspace_signal in _WORKSPACE_SIGNAL_LANGUAGE:
+        return [winner["language"]]
+
+    langs: list[str] = []
+
+    def add(lang: str) -> None:
+        if lang not in langs:
+            langs.append(lang)
+
+    # Rule 1 — package.json (tsconfig.json disambiguation)
+    if _has_basename(tree, "package.json"):
+        add("typescript" if _has_basename(tree, "tsconfig.json") else "javascript")
+
+    # Rules 2-6 / 8 / 10 — single-basename manifests (same order as _MANIFEST_RULES)
+    for basename, language, _source in _MANIFEST_RULES:
+        if _has_basename(tree, basename):
+            add(language)
+
+    # Rule 7b — build.gradle (Groovy) Java/Kotlin disambiguation
+    if _has_basename(tree, "build.gradle"):
+        add("kotlin" if _has_path_segment(tree, "src/main/kotlin/") else "java")
+
+    # Rules 8-9 — suffix-based (csproj, sln)
+    for suffix, language, _source in _SUFFIX_RULES:
+        if _has_suffix(tree, suffix):
+            add(language)
+
+    if langs:
+        return langs
+
+    # No manifest matched — the winner came from the extension-frequency
+    # fallback (rule 10). Carry its best guess, or [] when it was "unknown".
+    fallback_language = winner["language"]
+    return [] if fallback_language == "unknown" else [fallback_language]
+
+
 def detect(payload: dict[str, Any]) -> dict[str, Any]:
+    """Apply the documented rule walk and annotate the full manifest match set.
+
+    Returns the single-winner envelope (language/confidence/detection_source/
+    fallback_to_extension_frequency) unchanged, plus detected_languages[] — the
+    ordered, deduplicated set of every manifest-level match — so a caller can
+    both auto-pick and gate multi-language disambiguation off one JSON shape.
+    """
+    winner = _winner(payload)
+    winner["detected_languages"] = _detected_languages(payload, winner)
+    return winner
+
+
+def _winner(payload: dict[str, Any]) -> dict[str, Any]:
     """Apply the documented rule walk. Always returns a recommendation."""
     tree = payload.get("tree")
     if not isinstance(tree, list):