bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/shared/scripts/skf-manifest-ops.py

@@ -19,6 +19,12 @@ Commands:
   remove <skill-name>           — Remove skill from manifest
   deprecate <skill-name> [ver]  — Mark skill or version as deprecated
   rename <old-name> <new-name>  — Rename a skill entry
+  affected-versions <name>      — List every version of <name> that a rename must
+                                  touch: the union of manifest
+                                  exports.<name>.versions keys and on-disk
+                                  version dirs under <skills-folder>/<name>/
+                                  (excluding the `active` symlink), deduped and
+                                  sorted semver-descending (newest first)
 """
 
 from __future__ import annotations
@@ -217,10 +223,68 @@ def cmd_rename(manifest_path, old_name, new_name):
     return {"status": "ok", "action": "renamed", "from": old_name, "to": new_name}
 
 
+def _version_sort_key(version):
+    """Semver-descending sort key (used with reverse=True → newest first).
+
+    Splits `X.Y.Z[-prerelease][+build]` into numeric release components so
+    0.10.0 sorts above 0.9.0 (a known LLM-unreliable numeric-vs-lexical case).
+    A non-numeric component sorts below any numeric one at the same position;
+    per semver, a version WITHOUT a prerelease outranks the same version WITH
+    one (1.0.0 > 1.0.0-rc1).
+    """
+    core = str(version).split("+", 1)[0]
+    main_part, _, pre = core.partition("-")
+    release = []
+    for part in main_part.split("."):
+        if part.isdigit():
+            release.append((1, int(part), ""))
+        else:
+            release.append((0, 0, part))
+    # pre == "" (no prerelease) must sort ABOVE a prerelease, i.e. compare higher.
+    return (release, pre == "", pre)
+
+
+def cmd_affected_versions(manifest_path, skills_folder, skill_name):
+    data, err = read_manifest(manifest_path)
+    if err:
+        return {"status": "error", "error": err}
+
+    manifest_versions = []
+    entry = data.get("exports", {}).get(skill_name)
+    if entry:
+        versions = entry.get("versions", {})
+        if isinstance(versions, dict):
+            manifest_versions = list(versions.keys())
+        elif isinstance(versions, list):  # residual v1 safety
+            manifest_versions = list(versions)
+
+    on_disk_versions = []
+    skill_dir = Path(skills_folder) / skill_name
+    if skill_dir.is_dir():
+        for child in skill_dir.iterdir():
+            if child.name == "active":
+                continue  # the active symlink is not a version
+            if child.is_dir():
+                on_disk_versions.append(child.name)
+
+    union = sorted(set(manifest_versions) | set(on_disk_versions), key=_version_sort_key, reverse=True)
+
+    return {
+        "status": "ok",
+        "skill": skill_name,
+        "affected_versions": union,
+        "count": len(union),
+        "sources": {
+            "manifest": sorted(set(manifest_versions), key=_version_sort_key, reverse=True),
+            "on_disk": sorted(set(on_disk_versions), key=_version_sort_key, reverse=True),
+        },
+    }
+
+
 def main():
     if len(sys.argv) < 3:
         print("Usage: python3 skf-manifest-ops.py <skills-folder> <command> [args]", file=sys.stderr)
-        print("Commands: read, get <name>, set <name> <version> [--ides a,b], remove <name>, deprecate <name> [version], rename <old> <new>", file=sys.stderr)
+        print("Commands: read, get <name>, set <name> <version> [--ides a,b], remove <name>, deprecate <name> [version], rename <old> <new>, affected-versions <name>", file=sys.stderr)
         sys.exit(1)
 
     skills_folder = Path(sys.argv[1])
@@ -245,6 +309,8 @@ def main():
         result = cmd_deprecate(manifest_path, sys.argv[3], ver)
     elif command == "rename" and len(sys.argv) >= 5:
         result = cmd_rename(manifest_path, sys.argv[3], sys.argv[4])
+    elif command == "affected-versions" and len(sys.argv) >= 4:
+        result = cmd_affected_versions(manifest_path, skills_folder, sys.argv[3])
     else:
         result = {"status": "error", "error": f"Unknown command or missing args: {command}"}
 

package/src/shared/scripts/skf-merge-doc-urls.py

@@ -0,0 +1,244 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""SKF Merge Doc URLs — merge corpora-seeded + detected docs for a skill brief.
+
+Deterministic merge of an upstream brief's `doc_urls` (registry-seeded
+companion corpora, source: language-registry) with the docs freshly
+discovered by `skf-detect-docs.py` (mapped to the brief `{url, label, source}`
+contract). Replaces the prose dedup/suppression that lived inline in
+`skf-brief-skill/references/step-auto-brief.md` §3 — that logic is fiddly
+(normalized-URL collisions, non-corpus path segments, locale duplicates) and
+must behave identically on every run, so it belongs in a tested script.
+
+Three operations, in order:
+
+  1. Normalized-URL dedup — lowercase host, strip a trailing `/index.html`
+     and any trailing `/` before comparing, so a seeded `…/book/` and a
+     README's `…/book/index.html` collapse to one entry. Existing
+     (corpora-seeded) entries always win and are NEVER dropped.
+
+  2. Non-corpus segment suppression (whole-language references only) — when
+     the brief is a whole-language reference (scope_type == "full-library"
+     AND ≥1 existing entry carries source == "language-registry"), drop a
+     README-detected entry whose host matches a registry corpus host and
+     whose path contains a known non-corpus segment (whatsnew / contribute /
+     wiki). Path-component-anchored, never a bare substring — `/whatsnew/`
+     and `/whatsnew-2024/` drop, `/docs/whatsnewfeatures/` does not.
+
+  3. Non-primary-locale collapse (whole-language references only) — drop a
+     README-detected entry on a registry host whose leading path segment is a
+     non-primary locale (e.g. `/ja/master/`) when a locale-stripped twin is
+     already kept (e.g. a seeded `/en/master/` or `/master/`). Twin-required:
+     a `/ja/…` page with no `/en/…` counterpart is kept.
+
+Suppression is GATED on the whole-language marker so ordinary skills pass
+through with byte-identical merge behaviour (dedup only). N==0 whole-language
+references (registry miss → no seeded corpora) carry no language-registry
+entry, so the gate is inactive and their README docs are NOT suppressed — the
+DEGRADED case is intentionally out of scope (there is no canonical corpus host
+to anchor suppression against).
+
+CLI:
+  echo '{"scope_type": "...", "existing": [...], "detected": [...]}' \
+    | uv run src/shared/scripts/skf-merge-doc-urls.py
+
+Input (JSON object on stdin):
+  {
+    "scope_type": "full-library",
+    "existing":   [{"url": "...", "label": "...", "source": "language-registry"}, ...],
+    "detected":   [{"url": "...", "label": "...", "source": "readme-detection"}, ...]
+  }
+
+Output (JSON object on stdout):
+  {
+    "doc_urls":   [{"url": "...", "label": "...", "source": "..."}, ...],
+    "suppressed": [{"url": "...", "reason": "non-corpus-segment|non-primary-locale-dup"}, ...]
+  }
+
+Exit codes:
+  0  success (merged list emitted)
+  2  error (bad JSON, wrong input shape)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from typing import Any
+from urllib.parse import urlsplit
+
+# Path components (case-insensitive) that mark a non-corpus page on a doc host:
+# changelogs/news, contribution guides, wikis. Matched as whole path components
+# (or component + a separator), never as a bare substring.
+_NON_CORPUS_SEGMENTS = ("whatsnew", "contribute", "wiki")
+
+# Closed allowlist of plausible doc-site locale codes. A leading path segment is
+# treated as a locale only when it is in this set (or a `ll-rr` form whose
+# language part is). Keeps a genuine subsection like `/go/` or `/is/` from being
+# misread as a locale.
+_LOCALE_CODES = {
+    "en", "ja", "zh", "ko", "fr", "de", "es", "pt", "ru", "it", "nl", "pl",
+    "tr", "uk", "cs", "id", "vi", "fa", "ar", "hi", "th", "sv", "da", "fi",
+    "nb", "no", "hu", "ro", "el", "he", "bg", "hr", "sk", "sl", "et", "lv",
+    "lt", "sr", "ca",
+}
+_LOCALE_REGION_RE = re.compile(r"^([a-z]{2})-[a-z]{2}$")
+
+
+def _norm_parts(url: str) -> tuple[str, str]:
+    """Return (lowercased host, normalized path) for dedup / host matching.
+
+    Path normalization strips a trailing `/index.html` and any trailing `/`.
+    Scheme, query, and fragment are ignored — a doc page is identified by its
+    host + path.
+    """
+    parts = urlsplit(url.strip())
+    host = parts.netloc.lower()
+    path = parts.path
+    low = path.lower()
+    if low.endswith("/index.html"):
+        path = path[: -len("/index.html")]
+    path = path.rstrip("/")
+    return host, path
+
+
+def _norm_key(url: str) -> tuple[str, str]:
+    return _norm_parts(url)
+
+
+def _is_locale(seg: str) -> bool:
+    s = seg.lower()
+    if s in _LOCALE_CODES:
+        return True
+    m = _LOCALE_REGION_RE.match(s)
+    return bool(m) and m.group(1) in _LOCALE_CODES
+
+
+def _is_primary_locale(seg: str) -> bool:
+    s = seg.lower()
+    return s == "en" or s.startswith("en-")
+
+
+def _path_segments(path: str) -> list[str]:
+    return [s for s in path.split("/") if s]
+
+
+def _locale_stripped_key(url: str) -> tuple[str, str, bool, bool]:
+    """Return (host, path-without-leading-locale, has_locale, is_primary).
+
+    The third/fourth flags let the caller tell `/ja/master/` (non-primary
+    locale) apart from `/master/` (no locale) and `/en/master/` (primary).
+    """
+    host, path = _norm_parts(url)
+    segs = _path_segments(path)
+    has_locale = bool(segs) and _is_locale(segs[0])
+    is_primary = has_locale and _is_primary_locale(segs[0])
+    if has_locale:
+        segs = segs[1:]
+    return host, "/".join(segs), has_locale, is_primary
+
+
+def _matches_non_corpus_segment(path: str) -> bool:
+    for seg in _path_segments(path):
+        low = seg.lower()
+        for token in _NON_CORPUS_SEGMENTS:
+            if low == token:
+                return True
+            # component + separator (whatsnew-2024) — but NOT whatsnewfeatures
+            if low.startswith(token) and len(low) > len(token) and not low[len(token)].isalnum():
+                return True
+    return False
+
+
+def merge_doc_urls(
+    scope_type: str,
+    existing: list[dict[str, Any]],
+    detected: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Merge existing (seeded) + detected doc_urls. Returns (doc_urls, suppressed)."""
+    kept: list[dict[str, Any]] = []
+    suppressed: list[dict[str, Any]] = []
+    seen: set[tuple[str, str]] = set()
+
+    # 1. Existing (corpora-seeded) entries win and are never dropped.
+    for e in existing:
+        if not isinstance(e, dict) or not e.get("url"):
+            continue
+        key = _norm_key(e["url"])
+        if key in seen:
+            continue
+        seen.add(key)
+        kept.append(e)
+
+    # Whole-language gate: registry-seeded corpora present on a full-library brief.
+    registry_hosts = {
+        _norm_parts(e["url"])[0]
+        for e in kept
+        if isinstance(e, dict) and e.get("url") and e.get("source") == "language-registry"
+    }
+    suppression_active = scope_type == "full-library" and bool(registry_hosts)
+
+    for d in detected:
+        if not isinstance(d, dict) or not d.get("url"):
+            continue
+        url = d["url"]
+        key = _norm_key(url)
+        if key in seen:
+            continue  # dedup — a seeded/earlier entry already covers this URL
+
+        if suppression_active:
+            host, path = _norm_parts(url)
+            if host in registry_hosts:
+                if _matches_non_corpus_segment(path):
+                    suppressed.append({"url": url, "reason": "non-corpus-segment"})
+                    continue
+                dh, dpath, has_locale, is_primary = _locale_stripped_key(url)
+                if has_locale and not is_primary:
+                    twin = any(
+                        _locale_stripped_key(k["url"])[0] == dh
+                        and _locale_stripped_key(k["url"])[1] == dpath
+                        for k in kept
+                        if k.get("url")
+                    )
+                    if twin:
+                        suppressed.append({"url": url, "reason": "non-primary-locale-dup"})
+                        continue
+
+        seen.add(key)
+        kept.append(d)
+
+    return kept, suppressed
+
+
+def main() -> int:
+    raw = sys.stdin.read()
+    if not raw or not raw.strip():
+        sys.stderr.write("skf-merge-doc-urls: empty stdin (expected JSON object)\n")
+        return 2
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        sys.stderr.write(f"skf-merge-doc-urls: invalid JSON on stdin: {exc}\n")
+        return 2
+    if not isinstance(payload, dict):
+        sys.stderr.write("skf-merge-doc-urls: input must be a JSON object\n")
+        return 2
+
+    scope_type = payload.get("scope_type") or ""
+    existing = payload.get("existing") or []
+    detected = payload.get("detected") or []
+    if not isinstance(existing, list) or not isinstance(detected, list):
+        sys.stderr.write("skf-merge-doc-urls: 'existing' and 'detected' must be arrays\n")
+        return 2
+
+    doc_urls, suppressed = merge_doc_urls(scope_type, existing, detected)
+    json.dump({"doc_urls": doc_urls, "suppressed": suppressed}, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/shared/scripts/skf-preapply.py

@@ -9,7 +9,7 @@ registry, then scans target directory files for fingerprint matches and applies
 the corresponding fixes.
 
 CLI:
-  uv run python src/shared/scripts/skf-preapply.py \
+  uv run src/shared/scripts/skf-preapply.py \
       --target-dir <path> [--registry <path>] [--local-registry <path>] [--log-dir <path>]
 
 Input:

package/src/shared/scripts/skf-rebuild-managed-sections.py

@@ -16,10 +16,23 @@ Actions:
   clear         — Remove managed section entirely (markers + content)
   insert        — Insert managed section if not present (at end of file)
   check         — Check if managed section exists, report status
+
+Query actions (read-only, take positional file lists instead of <file> <action>):
+  orphan-detect <context-file>... --exported-skills a,b
+                — Parse `[skill-name v...]` rows across one or more context
+                  files, drop rows whose skill_name is in the exported set,
+                  and report the survivors (deduped by (skill_name, version),
+                  with verbatim snippet_text and sorted source_files provenance)
+                  as `orphan_managed_rows`.
+  root-probe <snippet-file>... --reference-root .claude/skills/
+                — Read each snippet's first line, parse its `root:` prefix
+                  (trailing `{skill-name}/` stripped), collect the unique
+                  `observed_prefixes`, and flag `mismatch` against the reference.
 """
 
 from __future__ import annotations
 
+import argparse
 import json
 import os
 import re
@@ -34,6 +47,16 @@ MARKER_PATTERN = re.compile(
     re.DOTALL,
 )
 
+# A managed-section skill row header: `[skill-name v1.2.3]…`, optionally
+# prefixed by the format's leading `|`. Requires a ` v<version>` inside the
+# brackets so the section header `[SKF Skills]|{n} skills|{m} stack` (no ` v`)
+# is never mistaken for a skill row.
+ROW_HEADER_PATTERN = re.compile(
+    r"^\|?\[(?P<name>[^\]]+?) v(?P<version>[^\]\s]+)\]"
+)
+# The `root:` field of a snippet's first line: `…|root: {prefix}{skill-name}/`.
+SNIPPET_ROOT_PATTERN = re.compile(r"root:\s*(?P<root>\S.*?)\s*$")
+
 
 def read_context_file(file_path):
     """Read a context file. Returns (content, None) or (None, error)."""
@@ -222,7 +245,164 @@ def cmd_insert(file_path, new_content):
     return {"status": "ok", "action": "inserted", "bytes_written": len(updated)}
 
 
+def _is_row_separator(line):
+    """A blank/separator line between snippets: bare `|` or empty."""
+    return line.strip() in ("", "|")
+
+
+def parse_managed_rows(body):
+    """Split the between-marker `body` into skill rows.
+
+    Returns a list of {skill_name, version, snippet_text} dicts, one per
+    `[skill-name v...]` header found. `snippet_text` is the header line plus its
+    continuation lines, captured verbatim (byte-preserved) up to — but not
+    including — the next bare-`|` separator, the next row header, or end of body.
+    Non-row lines (the `[SKF Skills]` header, the IMPORTANT preamble) are skipped.
+    """
+    lines = body.split("\n")
+    rows = []
+    i = 0
+    n = len(lines)
+    while i < n:
+        m = ROW_HEADER_PATTERN.match(lines[i])
+        if not m:
+            i += 1
+            continue
+        start = i
+        i += 1
+        while i < n and not ROW_HEADER_PATTERN.match(lines[i]) and not _is_row_separator(lines[i]):
+            i += 1
+        rows.append(
+            {
+                "skill_name": m.group("name"),
+                "version": m.group("version"),
+                "snippet_text": "\n".join(lines[start:i]),
+            }
+        )
+    return rows
+
+
+def cmd_orphan_detect(context_files, exported_skills):
+    """Detect managed-section rows absent from the exported skill set.
+
+    Scans every context file that exists and has a managed section, parses its
+    skill rows, drops those whose skill_name is in `exported_skills`, and
+    accumulates the survivors keyed by (skill_name, version). The first-seen
+    snippet_text wins; each file the row appears in is added to source_files.
+    Deterministic: rows sorted by (skill_name, version), source_files sorted.
+    """
+    exported = {s.strip() for s in exported_skills.split(",") if s.strip()}
+    orphans = {}  # (name, version) -> {skill_name, version, snippet_text, source_files:set}
+    for cf in context_files:
+        content, err = read_context_file(cf)
+        if err:
+            continue  # missing file — no orphans by definition
+        match = find_managed_section(content)
+        if not match:
+            continue  # no managed section — no orphans
+        for row in parse_managed_rows(match.group(2)):
+            if row["skill_name"] in exported:
+                continue  # not an orphan — it is being (re)exported
+            key = (row["skill_name"], row["version"])
+            if key in orphans:
+                orphans[key]["source_files"].add(cf)  # keep first-seen snippet_text
+            else:
+                orphans[key] = {
+                    "skill_name": row["skill_name"],
+                    "version": row["version"],
+                    "snippet_text": row["snippet_text"],
+                    "source_files": {cf},
+                }
+    orphan_rows = [
+        {
+            "skill_name": v["skill_name"],
+            "version": v["version"],
+            "snippet_text": v["snippet_text"],
+            "source_files": sorted(v["source_files"]),
+        }
+        for _, v in sorted(orphans.items())
+    ]
+    return {"status": "ok", "orphan_managed_rows": orphan_rows}
+
+
+def cmd_root_probe(snippet_files, reference_root):
+    """Observe snippet root prefixes and flag mismatch against a reference.
+
+    Reads the first line of each snippet that exists, parses its `root:` value,
+    strips the trailing `{skill-name}/` to recover the prefix, and collects the
+    unique prefixes. `mismatch` is True when any observed prefix differs from
+    `reference_root`. Deterministic: observed_prefixes sorted.
+    """
+    observed = set()
+    for sf in snippet_files:
+        content, err = read_context_file(sf)
+        if err:
+            continue  # missing snippet — skip
+        first_line = content.split("\n", 1)[0]
+        header = ROW_HEADER_PATTERN.match(first_line)
+        root_match = SNIPPET_ROOT_PATTERN.search(first_line)
+        if not root_match:
+            continue  # no root: field — skip
+        root_value = root_match.group("root")
+        prefix = root_value
+        if header:
+            suffix = header.group("name") + "/"
+            if root_value.endswith(suffix):
+                prefix = root_value[: -len(suffix)]
+        observed.add(prefix)
+    observed_prefixes = sorted(observed)
+    return {
+        "status": "ok",
+        "reference_root": reference_root,
+        "observed_prefixes": observed_prefixes,
+        "mismatch": any(p != reference_root for p in observed_prefixes),
+    }
+
+
+def _run_query_action(argv):
+    """Dispatch the read-only query actions (orphan-detect / root-probe).
+
+    These take a positional file list rather than the legacy `<file> <action>`
+    shape, so they are parsed with argparse and routed here before the legacy
+    path. Returns (result_dict, exit_code).
+    """
+    action = argv[0]
+    if action == "orphan-detect":
+        parser = argparse.ArgumentParser(
+            prog="skf-rebuild-managed-sections.py orphan-detect",
+            description="Detect managed-section rows absent from the exported skill set.",
+        )
+        parser.add_argument("context_files", nargs="+", help="Context file paths to scan")
+        parser.add_argument(
+            "--exported-skills",
+            default="",
+            help="Comma-separated skill names being exported (excluded from orphans)",
+        )
+        args = parser.parse_args(argv[1:])
+        return cmd_orphan_detect(args.context_files, args.exported_skills), 0
+    # action == "root-probe"
+    parser = argparse.ArgumentParser(
+        prog="skf-rebuild-managed-sections.py root-probe",
+        description="Observe snippet root prefixes and flag mismatch against a reference.",
+    )
+    parser.add_argument("snippet_files", nargs="+", help="Snippet file paths to probe")
+    parser.add_argument(
+        "--reference-root",
+        required=True,
+        help="Reference skill root prefix to compare observed prefixes against",
+    )
+    args = parser.parse_args(argv[1:])
+    return cmd_root_probe(args.snippet_files, args.reference_root), 0
+
+
 def main():
+    # Query actions take a positional file list, so they are action-first
+    # (`orphan-detect <file>...`) rather than the legacy `<file> <action>` shape.
+    if len(sys.argv) >= 2 and sys.argv[1] in ("orphan-detect", "root-probe"):
+        result, code = _run_query_action(sys.argv[1:])
+        print(json.dumps(result, indent=2))
+        sys.exit(code)
+
     if len(sys.argv) < 3:
         print("Usage: python3 skf-rebuild-managed-sections.py <context-file> <action> [--content <text>]", file=sys.stderr)
         print("Actions: read, replace, clear, insert, check", file=sys.stderr)

package/src/shared/scripts/skf-recommend-scope-type.py

@@ -15,7 +15,7 @@ The five-rule ladder (apply in order, first match wins):
      entries or `Component[]` annotation when contents available;
      presence-only when contents not available)
   2. reference-app    — intent text mentions wiring / integration / starter
-     / lifecycle / build-config keywords, OR analysis flagged as demo/example
+     / build-config keywords, OR analysis flagged as demo/example
   3. specific-modules — intent names a specific subset ("just the X",
      "only the Y") OR module_count >= 6
   4. public-api       — export_count <= 8 AND intent mentions "the API",
@@ -71,7 +71,6 @@ REFERENCE_APP_KEYWORDS = (
     "integration example",
     "integration sample",
     "starter",
-    "lifecycle",
     "build config",
     "build-config",
     "demo app",