bmad-module-skill-forge 2.0.0 → 2.0.1

package/src/shared/scripts/skf-verify-no-trace.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""SKF Verify No Trace — post-rename commit gate.
+
+Confirms that no structural reference to the old skill name survives inside the
+freshly-materialized new location before the rename is committed (before the old
+directories are deleted). Every check is a fixed-file-set, case-sensitive scan
+plus a region partition — fully deterministic, so the prompt keeps only the
+roll-back-or-commit decision.
+
+The scan matches the old name only as a complete skill-name token: an occurrence
+NOT adjacent to another skill-name character `[a-z0-9-]` on either side. This is
+what a literal substring grep intends but gets wrong when the old name is a
+substring of the new name (rename -> rename-skill): a bare substring scan would
+flag every correctly-renamed `rename-skill` as a leftover and make the rename
+un-committable. Token matching flags a genuine leftover path segment
+(`.claude/skills/rename/`), JSON value (`"rename"`), or header (`[rename v...]`)
+while ignoring `rename-skill` and `renamed`.
+
+For each version under --versions it scans:
+
+  {skill_group}/{v}/{new_name}/SKILL.md          -> frontmatter matches are HARD;
+                                                    body matches (below the closing
+                                                    `---`) are advisory warnings
+  {skill_group}/{v}/{new_name}/metadata.json     -> any match is HARD
+  {skill_group}/{v}/{new_name}/context-snippet.md-> any match is HARD
+  {forge_group}/{v}/provenance-map.json          -> any match is HARD
+
+and the directory listing:
+
+  {skill_group}/{v}/  MUST contain {new_name}/ and MUST NOT contain {old_name}/
+
+The SKILL.md frontmatter/body split uses the same closing-`---`-on-its-own-line
+rule as skf-validate-output.py, so a legitimate body mention of the old name (a
+changelog line, a cross-reference) is a warning, never a blocker.
+
+Output (stdout, always JSON):
+  {hard_matches[], body_warnings[], dir_violations[], skipped[], clean}
+
+Exit codes:
+  0  clean (no hard_matches and no dir_violations)
+  1  not clean (at least one hard match or dir violation)
+  2  operation error (bad args)
+
+CLI example:
+  python3 skf-verify-no-trace.py /out/rename-skill \
+      --forge-group /forge/rename-skill \
+      --old-name rename --new-name rename-skill --versions 1.0.0,0.9.0
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def _name_token_re(old_name: str) -> "re.Pattern[str]":
+    """Match old_name only where it is a complete skill-name token.
+
+    Negative lookbehind/lookahead on `[a-z0-9-]` so `rename` matches inside
+    `/rename/` or `"rename"` but not inside `rename-skill` or `renamed`.
+    """
+    return re.compile(r"(?<![a-z0-9-])" + re.escape(old_name) + r"(?![a-z0-9-])")
+
+
+def _split_frontmatter_body(content: str):
+    """Return (frontmatter_lines, body_lines) as lists of (lineno, text).
+
+    Uses the closing-`---`-on-its-own-line rule (matching skf-validate-output.py).
+    When there is no valid frontmatter block, the whole file is treated as body —
+    a SKILL.md without frontmatter has no "structural" region to protect, so any
+    old-name match there is advisory, and the separate metadata/snippet/provenance
+    scans still gate the commit.
+    """
+    lines = content.split("\n")
+    numbered = list(enumerate(lines, start=1))
+    if not content.startswith("---\n"):
+        return [], numbered
+    close_idx = None  # 0-based index into `lines` of the closing '---'
+    for i in range(1, len(lines)):
+        if lines[i].rstrip() == "---":
+            close_idx = i
+            break
+    if close_idx is None:
+        return [], numbered
+    # Frontmatter = lines strictly between the opening (line 1) and closing '---'.
+    frontmatter = numbered[1:close_idx]
+    body = numbered[close_idx + 1 :]
+    return frontmatter, body
+
+
+def _scan_lines(numbered, pattern):
+    """Return [(lineno, text)] for every line where pattern matches (name token)."""
+    return [(n, text) for (n, text) in numbered if pattern.search(text)]
+
+
+def verify(skill_group: Path, forge_group: Path, old_name: str, new_name: str, versions):
+    hard_matches = []
+    body_warnings = []
+    dir_violations = []
+    skipped = []
+    pattern = _name_token_re(old_name)
+
+    def scan_file(path: Path, region: str, version: str):
+        if not path.exists():
+            skipped.append({"version": version, "file": str(path), "reason": "missing"})
+            return None
+        try:
+            return path.read_text(encoding="utf-8")
+        except OSError as e:
+            skipped.append({"version": version, "file": str(path), "reason": f"read-error: {e}"})
+            return None
+
+    for v in versions:
+        inner = skill_group / v / new_name
+
+        # SKILL.md — region-partitioned (frontmatter=hard, body=warning).
+        skill_md = inner / "SKILL.md"
+        content = scan_file(skill_md, "skill-md", v)
+        if content is not None:
+            fm, body = _split_frontmatter_body(content)
+            for n, text in _scan_lines(fm, pattern):
+                hard_matches.append(
+                    {"version": v, "file": str(skill_md), "region": "skill-frontmatter",
+                     "line": n, "text": text.strip()}
+                )
+            for n, text in _scan_lines(body, pattern):
+                body_warnings.append(
+                    {"version": v, "file": str(skill_md), "region": "skill-body",
+                     "line": n, "text": text.strip()}
+                )
+
+        # Whole-file hard scans.
+        for rel, region, base in (
+            (inner / "metadata.json", "metadata-json", skill_group),
+            (inner / "context-snippet.md", "context-snippet", skill_group),
+            (forge_group / v / "provenance-map.json", "provenance-json", forge_group),
+        ):
+            content = scan_file(rel, region, v)
+            if content is None:
+                continue
+            for n, text in _scan_lines(list(enumerate(content.split("\n"), start=1)), pattern):
+                hard_matches.append(
+                    {"version": v, "file": str(rel), "region": region,
+                     "line": n, "text": text.strip()}
+                )
+
+        # Directory listing: must contain {new_name}/, must not contain {old_name}/.
+        version_dir = skill_group / v
+        old_dir = version_dir / old_name
+        new_dir = version_dir / new_name
+        if old_dir.exists():
+            dir_violations.append(
+                {"version": v, "path": str(version_dir),
+                 "issue": "old-name-dir-present", "detail": f"{old_name}/"}
+            )
+        if not new_dir.exists():
+            dir_violations.append(
+                {"version": v, "path": str(version_dir),
+                 "issue": "new-name-dir-missing", "detail": f"{new_name}/"}
+            )
+
+    clean = not hard_matches and not dir_violations
+    return {
+        "status": "ok",
+        "old_name": old_name,
+        "new_name": new_name,
+        "versions": list(versions),
+        "hard_matches": hard_matches,
+        "body_warnings": body_warnings,
+        "dir_violations": dir_violations,
+        "skipped": skipped,
+        "clean": clean,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument("skill_group", type=Path, help="new_skill_group ({skills_output_folder}/{new_name})")
+    parser.add_argument("--forge-group", type=Path, required=True, help="new_forge_group ({forge_data_folder}/{new_name})")
+    parser.add_argument("--old-name", required=True, help="Old skill name to scan for")
+    parser.add_argument("--new-name", required=True, help="New skill name")
+    parser.add_argument("--versions", required=True, help="Comma-separated version list (affected_versions)")
+    parser.add_argument("--verbose", action="store_true", help="Diagnostics to stderr")
+    args = parser.parse_args()
+
+    versions = [v for v in (s.strip() for s in args.versions.split(",")) if v]
+    if not versions:
+        print(json.dumps({"status": "error", "message": "no versions provided"}), file=sys.stderr)
+        sys.exit(2)
+
+    result = verify(args.skill_group, args.forge_group, args.old_name, args.new_name, versions)
+
+    if args.verbose:
+        print(
+            f"[skf-verify-no-trace] hard={len(result['hard_matches'])} "
+            f"warn={len(result['body_warnings'])} dir={len(result['dir_violations'])} "
+            f"clean={result['clean']}",
+            file=sys.stderr,
+        )
+
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["clean"] else 1)
+
+
+if __name__ == "__main__":
+    main()

package/src/shared/scripts/skf-verify-provenance-completeness.py

@@ -0,0 +1,439 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Verify Provenance Completeness — deterministic Check D for update-skill.
+
+`skf-update-skill/references/validate.md §2 Check D (Provenance Completeness)`
+previously asked the model to perform three deterministic set/citation
+operations by eye, against in-context data:
+
+  1. **Completeness** — verify every documented export has a provenance-map
+     entry (metadata `exports[]` \\ provenance `entries[].export_name`).
+  2. **Orphans** — flag provenance entries whose export was removed
+     (provenance `entries[].export_name` \\ metadata `exports[]`).
+  3. **Stale citations** — flag entries whose `source_file:source_line`
+     no longer resolves (file gone, or line past end of file).
+
+An LLM set-diff can silently pass a dropped or orphaned entry, and eyeballing
+whether a cited line still exists is not something the model can do reliably.
+Both inputs are machine-readable — `metadata.json` (`exports[]`, a list of
+export-name strings) and `provenance-map.json` (`entries[]` with
+`export_name` / `source_file` / `source_line`, plus an optional
+`reexport_map` for stack-skill barrel renames) are written by
+`write.md` §2 and §3. This script diffs the two sets and re-checks the
+citations exactly, so Check D consumes JSON rather than computing it.
+
+Timing: this runs **post-write** (`write.md` §6), after `metadata.json`
+(§2) and `provenance-map.json` (§3) are on disk. `validate.md` Check D
+defers here — the provenance map does not exist yet at validate time.
+
+Determinism:
+  - Set operations are pure over the two JSON inputs.
+  - Citation resolution reads the source tree at `source_root` (from the
+    provenance map, or `--source-root`). When no source root resolves on
+    disk, the stale check is SKIPPED (`summary.stale_check` reports it) and
+    only completeness + orphan diffs run — those need no source tree. Same
+    input tree → same output.
+
+Stack-skill canonicalization: a provenance entry's `export_name` may be the
+internal name of a barrel-renamed export (e.g. `_Impl` re-exported as
+`Public`). Names are canonicalized through `reexport_map`
+(`{internal: public}`) before the set-diff, mirroring
+`skf-load-provenance.extract_reexport_map`, so an internal-named entry does
+not read as a missing public export nor as an orphan.
+
+Subcommand:
+  verify --metadata <metadata.json> --provenance <provenance-map.json>
+         [--source-root <path>] [-o <out.json>]
+
+    Emit JSON:
+      {
+        "status": "pass" | "findings",
+        "missing":  ["<export documented but not in provenance>", ...],
+        "orphaned": ["<provenance entry with no documented export>", ...],
+        "stale": [
+          {"export_name": "<raw entry name>",
+           "source_file": "<rel path>",
+           "source_line": <int|null>,
+           "reason": "file-missing" | "line-out-of-bounds" | "line-invalid"},
+          ...
+        ],
+        "summary": {
+          "exports_checked":  <int>,   # documented exports (metadata)
+          "entries_checked":  <int>,   # provenance entries with export_name
+          "missing_count":    <int>,
+          "orphaned_count":   <int>,
+          "stale_count":      <int>,
+          "citations_checked": <int>,  # entries whose citation was resolved
+          "stale_check": "checked" | "skipped-no-source-root"
+        }
+      }
+
+    `missing` / `orphaned` are sorted, deduplicated public names.
+    `stale` is sorted by (export_name, source_file).
+
+CLI examples:
+  uv run skf-verify-provenance-completeness.py verify \\
+      --metadata {skill_package}/metadata.json \\
+      --provenance {forge_version}/provenance-map.json \\
+      --source-root {source_root}
+
+Exit codes:
+  0  — verification ran and found nothing (status "pass")
+  1  — verification ran and found missing / orphaned / stale entries
+       (status "findings"); advisory — the caller decides how to surface it
+  2  — error (input file not found, malformed JSON, invalid structure)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+STALE_FILE_MISSING = "file-missing"
+STALE_LINE_OOB = "line-out-of-bounds"
+STALE_LINE_INVALID = "line-invalid"
+
+
+# --------------------------------------------------------------------------
+# I/O
+# --------------------------------------------------------------------------
+
+
+def load_json_object(path: Path, label: str) -> dict:
+    """Read a JSON file and require a top-level object. Raises ValueError."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ValueError(f"failed to read {label} {path}: {exc}") from exc
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"malformed JSON in {label} {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"{label} {path} must be a JSON object at top level; "
+            f"got {type(data).__name__}"
+        )
+    return data
+
+
+# --------------------------------------------------------------------------
+# Extraction / canonicalization
+# --------------------------------------------------------------------------
+
+
+def extract_export_names(metadata: dict) -> list[str]:
+    """Pull documented export names from metadata.exports.
+
+    `exports` is a list of export-name strings (per the skill templates).
+    Defensively also accept dict items carrying `name` / `export_name`.
+    Non-string / unnamed items are skipped. Order preserved; caller dedupes.
+    """
+    names: list[str] = []
+    exports = metadata.get("exports")
+    if not isinstance(exports, list):
+        return names
+    for item in exports:
+        if isinstance(item, str) and item:
+            names.append(item)
+        elif isinstance(item, dict):
+            nm = item.get("name") or item.get("export_name")
+            if isinstance(nm, str) and nm:
+                names.append(nm)
+    return names
+
+
+def extract_reexport_map(prov: dict) -> dict[str, str]:
+    """Build the `{internal: public}` re-export map.
+
+    Mirrors `skf-load-provenance.extract_reexport_map`: top-level
+    `reexport_map` is authoritative; per-entry `reexported_as` fills gaps.
+    Non-string keys/values skipped.
+    """
+    out: dict[str, str] = {}
+    top = prov.get("reexport_map")
+    if isinstance(top, dict):
+        for k, v in top.items():
+            if isinstance(k, str) and isinstance(v, str):
+                out[k] = v
+    entries = prov.get("entries")
+    if isinstance(entries, list):
+        for entry in entries:
+            if not isinstance(entry, dict):
+                continue
+            internal = entry.get("export_name")
+            public = entry.get("reexported_as")
+            if isinstance(internal, str) and isinstance(public, str):
+                out.setdefault(internal, public)
+    return out
+
+
+def canon(name: str, reexport_map: dict[str, str]) -> str:
+    """Canonicalize an export name to its public form via reexport_map.
+
+    Idempotent for names that are not internal (public names are not keys).
+    """
+    return reexport_map.get(name, name)
+
+
+def provenance_entry_names(prov: dict) -> list[str]:
+    """Raw `export_name` of every well-formed provenance entry (order kept)."""
+    names: list[str] = []
+    entries = prov.get("entries")
+    if not isinstance(entries, list):
+        return names
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        nm = entry.get("export_name")
+        if isinstance(nm, str) and nm:
+            names.append(nm)
+    return names
+
+
+# --------------------------------------------------------------------------
+# Citation resolution
+# --------------------------------------------------------------------------
+
+
+def _coerce_line(value: object) -> int | None | str:
+    """Return an int line number, None (tolerated), or a sentinel str for
+    an un-coercible non-null value (reported as line-invalid)."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        # bool is an int subclass — a boolean line number is nonsense
+        return "invalid"
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        s = value.strip()
+        if not s:
+            return None
+        try:
+            return int(s)
+        except ValueError:
+            return "invalid"
+    return "invalid"
+
+
+def check_citation(
+    source_file: object, source_line: object, source_root: Path
+) -> str | None:
+    """Resolve a single `source_file:source_line` citation under source_root.
+
+    Returns a stale reason (one of the STALE_* constants) when the citation
+    does not resolve, or None when it is valid OR tolerated.
+
+    Tolerated (returns None): source_file missing/empty, or source_line null
+    or empty — `unknown`-outcome entries legitimately carry null citations
+    (write.md §3), so an absent citation is not "stale".
+    """
+    if not isinstance(source_file, str) or not source_file.strip():
+        return None
+    line = _coerce_line(source_line)
+    if line is None:
+        return None
+    if isinstance(line, str):  # sentinel for un-coercible non-null value
+        return STALE_LINE_INVALID
+
+    rel = source_file.strip().replace("\\", "/")
+    target = (source_root / rel).resolve()
+    if not target.is_file():
+        return STALE_FILE_MISSING
+
+    if line < 1:
+        return STALE_LINE_OOB
+    try:
+        with target.open("r", encoding="utf-8", errors="replace") as fh:
+            line_count = sum(1 for _ in fh)
+    except OSError:
+        return STALE_FILE_MISSING
+    if line > line_count:
+        return STALE_LINE_OOB
+    return None
+
+
+# --------------------------------------------------------------------------
+# Verification
+# --------------------------------------------------------------------------
+
+
+def resolve_source_root(prov: dict, override: str | None) -> Path | None:
+    """Pick the source root for citation resolution.
+
+    `--source-root` override wins; otherwise the provenance map's top-level
+    `source_root`. Returns None when neither resolves to an on-disk dir.
+    """
+    candidate: str | None = None
+    if override:
+        candidate = override
+    else:
+        sr = prov.get("source_root")
+        if isinstance(sr, str) and sr:
+            candidate = sr
+    if not candidate:
+        return None
+    root = Path(candidate)
+    return root if root.is_dir() else None
+
+
+def verify(metadata: dict, prov: dict, source_root: Path | None) -> dict:
+    """Compute the completeness / orphan / stale report over the two maps."""
+    reexport_map = extract_reexport_map(prov)
+
+    documented = extract_export_names(metadata)
+    documented_canon = {canon(n, reexport_map) for n in documented}
+
+    raw_entry_names = provenance_entry_names(prov)
+    entry_canon = {canon(n, reexport_map) for n in raw_entry_names}
+
+    missing = sorted(documented_canon - entry_canon)
+    orphaned = sorted(entry_canon - documented_canon)
+
+    stale: list[dict] = []
+    citations_checked = 0
+    if source_root is not None:
+        entries = prov.get("entries")
+        if isinstance(entries, list):
+            for entry in entries:
+                if not isinstance(entry, dict):
+                    continue
+                name = entry.get("export_name")
+                if not isinstance(name, str) or not name:
+                    continue
+                sf = entry.get("source_file")
+                sl = entry.get("source_line")
+                # Only count a resolvable (non-null) citation as "checked".
+                if isinstance(sf, str) and sf.strip() and _coerce_line(sl) is not None:
+                    citations_checked += 1
+                reason = check_citation(sf, sl, source_root)
+                if reason is not None:
+                    stale.append(
+                        {
+                            "export_name": name,
+                            "source_file": sf if isinstance(sf, str) else None,
+                            "source_line": sl if isinstance(sl, int)
+                            and not isinstance(sl, bool) else sl,
+                            "reason": reason,
+                        }
+                    )
+        stale.sort(key=lambda s: (s["export_name"], s.get("source_file") or ""))
+
+    status = "pass" if not (missing or orphaned or stale) else "findings"
+    return {
+        "status": status,
+        "missing": missing,
+        "orphaned": orphaned,
+        "stale": stale,
+        "summary": {
+            "exports_checked": len(documented_canon),
+            "entries_checked": len(raw_entry_names),
+            "missing_count": len(missing),
+            "orphaned_count": len(orphaned),
+            "stale_count": len(stale),
+            "citations_checked": citations_checked,
+            "stale_check": "checked"
+            if source_root is not None
+            else "skipped-no-source-root",
+        },
+    }
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    meta_path = Path(args.metadata)
+    prov_path = Path(args.provenance)
+    if not meta_path.is_file():
+        print(f"error: metadata not found: {meta_path}", file=sys.stderr)
+        return 2
+    if not prov_path.is_file():
+        print(f"error: provenance map not found: {prov_path}", file=sys.stderr)
+        return 2
+    try:
+        metadata = load_json_object(meta_path, "metadata")
+        prov = load_json_object(prov_path, "provenance map")
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    source_root = resolve_source_root(prov, args.source_root)
+    if args.verbose:
+        if source_root is None:
+            print(
+                "verbose: no source root resolved — skipping stale-citation "
+                "check (completeness + orphan diffs only)",
+                file=sys.stderr,
+            )
+        else:
+            print(f"verbose: resolving citations under {source_root}", file=sys.stderr)
+
+    result = verify(metadata, prov, source_root)
+
+    out_text = json.dumps(result, indent=2) + "\n"
+    if args.output and args.output != "-":
+        Path(args.output).write_text(out_text, encoding="utf-8")
+    else:
+        sys.stdout.write(out_text)
+
+    return 0 if result["status"] == "pass" else 1
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skf-verify-provenance-completeness",
+        description=(
+            "Cross-reference documented exports (metadata.json) against "
+            "provenance-map entries — completeness, orphans, and stale "
+            "file:line citations — emitting findings as JSON."
+        ),
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser(
+        "verify",
+        help="emit provenance completeness / orphan / stale-citation findings",
+    )
+    p.add_argument("--metadata", required=True, help="path to metadata.json")
+    p.add_argument(
+        "--provenance", required=True, help="path to provenance-map.json"
+    )
+    p.add_argument(
+        "--source-root",
+        default=None,
+        help=(
+            "source tree root for citation resolution; overrides the "
+            "provenance map's source_root. Stale check is skipped when no "
+            "root resolves on disk."
+        ),
+    )
+    p.add_argument(
+        "-o",
+        "--output",
+        default=None,
+        help="write JSON to this file instead of stdout ('-' for stdout)",
+    )
+    p.add_argument(
+        "--verbose", action="store_true", help="diagnostics to stderr"
+    )
+    p.set_defaults(func=_cmd_verify)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())