bmad-module-skill-forge 2.2.0 → 4.0.0

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # ///
 """SKF Count Tokens — Deterministic per-artifact token/word metrics for a skill package.
 

package/src/shared/scripts/skf-derive-assembly-shape.py

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # dependencies = ["pyyaml"]
 # ///
 """SKF Derive Assembly Shape — decide whether a brief is a whole-language reference.
@@ -15,7 +15,8 @@ The gate is a single, structured, schema-validated condition: the brief's
 `doc_urls` contains at least one entry with `source: "language-registry"`
 (issue #432). Registry-sourced corpora are stamped ONLY by
 skf-language-corpora.py, which is invoked ONLY for a whole-language reference
-(a grammar_file:/tree_triad: signal) in step-auto-scope.md §6b. So the gate
+(a grammar_file:/tree_triad: signal) in step-auto-scope-corpora.md, which
+step-auto-scope.md §6 loads for that signal. So the gate
 fires exactly when there is registry-guaranteed prose to foreground, and never
 for an ordinary library, a parser library (pest), a component-library, a
 reference-app, or a docs-only brief — none of which carry a language-registry
@@ -45,6 +46,7 @@ Exit codes:
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import sys
 from pathlib import Path
@@ -52,6 +54,8 @@ from typing import Any
 
 import yaml
 
+RESOLVER = Path(__file__).resolve().parent / "skf-resolve-authoritative-files.py"
+
 
 def derive_assembly_shape(brief: dict[str, Any]) -> dict[str, Any]:
     """Return the assembly-shape decision for a parsed brief."""
@@ -72,6 +76,20 @@ def _die(message: str) -> None:
     sys.exit(2)
 
 
+def _parse_brief_yaml(text: str):
+    """The brief's YAML as skf-resolve-authoritative-files.py (from this
+    folder) reads it: an SKF 1.x brief's trailing `---` is no second document."""
+    spec = importlib.util.spec_from_file_location("skf_resolve_authoritative_files", RESOLVER)
+    if spec is None or spec.loader is None:
+        _die(f"cannot load {RESOLVER.name} beside {Path(__file__).name}")
+    resolver = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(resolver)
+    except (OSError, ImportError, SyntaxError) as exc:
+        _die(f"cannot load {RESOLVER.name} beside {Path(__file__).name}: {exc}")
+    return resolver.parse_brief_yaml(text)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="skf-derive-assembly-shape",
@@ -92,7 +110,7 @@ def main(argv: list[str] | None = None) -> int:
         text = p.read_text(encoding="utf-8")
 
     try:
-        brief = yaml.safe_load(text)
+        brief = _parse_brief_yaml(text)
     except yaml.YAMLError as exc:
         _die(f"Brief is not valid YAML: {exc}")
     if not isinstance(brief, dict):

package/src/shared/scripts/skf-description-guard.py

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # dependencies = ["pyyaml"]
 # ///
 """SKF Description Guard — defend SKILL.md frontmatter description against
@@ -23,7 +23,7 @@ Subcommands:
       where schema_hash covers the full frontmatter block (handy for
       tamper detection if the caller wants belt-and-braces verification).
 
-  verify-restore <skill-md> --captured-description <STR>
+  verify-restore <skill-md> (--captured-description <STR> | --captured-file <PATH>)
       Re-read the file, compare current description against the captured
       value using token-stream equality (split on whitespace, compare
       element-by-element). If diverged, atomically rewrite the frontmatter
@@ -32,10 +32,22 @@ Subcommands:
          "current_description": "..."}
       If not diverged (including whitespace-only differences), emit
         {"diverged": false, "restored": false, "diff_kind": "none"|"whitespace-only"}
-      An empty or whitespace-only --captured-description is refused with
-      exit 1 before the file is read: there is nothing to restore from, and
+      --captured-file names a JSON file whose `description` string is the
+      captured value: `capture`'s output saved to a file, or a metadata.json,
+      so the value never passes through a shell string. A file that cannot
+      be read, is not a JSON object or has no string `description` exits 1.
+      An empty or whitespace-only captured value is refused with exit 1
+      before the skill file is read: there is nothing to restore from, and
       writing it back would blank the very field this guard protects.
 
+  sanitize <skill-md>
+      Replace every `<` with `{` and every `>` with `}` in the on-disk
+      `description` (create-skill's compile-time substitution, applied
+      again) and rewrite the frontmatter only when something changed. Emits
+        {"substitutions": N, "sanitized": true|false, "description": "..."}
+      where `description` is the value now on disk. No shell quoting of the
+      description is involved, so backticks and `$` in it are safe.
+
 Token-stream comparison is the documented sweet spot — catches replaced
 words, truncation, and reintroduced angle-brackets while ignoring cosmetic
 whitespace fixes (trailing newline, re-wrapped quoted strings). See
@@ -47,12 +59,16 @@ is auto-resolved:
   uv run skf-description-guard.py capture <skill-md>
   uv run skf-description-guard.py verify-restore <skill-md> \\
       --captured-description "the snapshot string"
+  uv run skf-description-guard.py capture <skill-md> > guard.json
+  uv run skf-description-guard.py verify-restore <skill-md> \\
+      --captured-file guard.json
+  uv run skf-description-guard.py sanitize <skill-md>
 
 Exit codes:
   0  — operation succeeded (including no-divergence verify)
   1  — user error (bad args, empty captured description, file missing,
        frontmatter unparseable)
-  2  — operation failure (restore write failed)
+  2  — operation failure (restore or sanitize write failed)
 """
 
 from __future__ import annotations
@@ -61,6 +77,7 @@ import argparse
 import hashlib
 import json
 import os
+import stat
 import sys
 import tempfile
 from pathlib import Path
@@ -172,7 +189,7 @@ def restore_description(skill_md: Path, captured: str) -> None:
     block scalars and nested `description:` keys in sibling mappings.
 
     Key order is preserved (PyYAML's `safe_dump` honours dict insertion order;
-    this module's `requires-python = ">=3.10"` guarantees ordered dicts).
+    this module's `requires-python = ">=3.11"` guarantees ordered dicts).
     Quoting style of *other* fields may change to whatever `safe_dump`
     chooses for each scalar — downstream readers parse YAML, so any valid
     YAML emission is acceptable.
@@ -215,7 +232,9 @@ def restore_description(skill_md: Path, captured: str) -> None:
         prefix=skill_md.name + ".", suffix=".skf-guard.tmp", dir=skill_md.parent
     )
     try:
-        with os.fdopen(fd, "w", encoding="utf-8") as tmp:
+        # newline="" writes "\n" untranslated: text mode would turn every
+        # line ending into "\r\n" on Windows.
+        with os.fdopen(fd, "w", encoding="utf-8", newline="") as tmp:
             tmp.write(new_text)
             tmp.flush()
             os.fsync(tmp.fileno())
@@ -246,15 +265,40 @@ def _cmd_capture(args: argparse.Namespace) -> int:
     return 0
 
 
+def read_captured_file(path: Path) -> str:
+    """The `description` string of a JSON file: capture's output, or a metadata.json.
+
+    Raises ValueError when the file cannot be read, holds no JSON object, or
+    has no string `description`.
+    """
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError) as exc:
+        raise ValueError(f"cannot read {path}: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{path} is not JSON: {exc}") from exc
+    if not isinstance(data, dict) or not isinstance(data.get("description"), str):
+        raise ValueError(f"{path} has no string `description`")
+    return data["description"]
+
+
 def _cmd_verify_restore(args: argparse.Namespace) -> int:
-    captured = args.captured_description
+    if args.captured_file is not None:
+        try:
+            captured = read_captured_file(Path(args.captured_file))
+        except ValueError as exc:
+            _fail(str(exc))
+        source = f"the description in {args.captured_file}"
+    else:
+        captured = args.captured_description
+        source = "--captured-description"
     if not captured.strip():
         # Restoring an empty snapshot would blank the field the guard exists
         # to protect. The snapshot was lost from context, or the description
         # was already empty before the tool ran; either way there is nothing
         # to restore, so refuse before touching the file.
         _fail(
-            "--captured-description is empty or whitespace-only; refusing to "
+            f"{source} is empty or whitespace-only; refusing to "
             "overwrite the on-disk description with an empty value (the capture "
             "was lost, or the field was already empty before the tool ran)"
         )
@@ -291,6 +335,39 @@ def _cmd_verify_restore(args: argparse.Namespace) -> int:
     return 0
 
 
+def sanitize_angle_brackets(description: str) -> tuple[str, int]:
+    """Replace every `<` with `{` and every `>` with `}`; return (value, substitutions)."""
+    count = description.count("<") + description.count(">")
+    return description.replace("<", "{").replace(">", "}"), count
+
+
+def _cmd_sanitize(args: argparse.Namespace) -> int:
+    skill_md = Path(args.skill_md)
+    try:
+        st = os.stat(skill_md)  # not Path.is_file(): Python 3.14 hides EACCES there
+    except OSError as exc:
+        _fail(f"cannot read {skill_md}: {exc.strerror or exc}")
+    if not stat.S_ISREG(st.st_mode):
+        _fail(f"not a file: {skill_md}")
+    try:
+        current, _ = read_description(skill_md)
+    except (OSError, ValueError) as exc:
+        _fail(str(exc))
+    sanitized, count = sanitize_angle_brackets(current)
+    result = {"substitutions": count, "sanitized": False, "description": current}
+    if count:
+        try:
+            restore_description(skill_md, sanitized)
+        except (OSError, ValueError) as exc:
+            json.dump({**result, "write_error": str(exc)}, sys.stdout)
+            sys.stdout.write("\n")
+            return 2
+        result.update(sanitized=True, description=sanitized)
+    json.dump(result, sys.stdout)
+    sys.stdout.write("\n")
+    return 0
+
+
 def _fail(msg: str) -> None:
     print(f"error: {msg}", file=sys.stderr)
     raise SystemExit(1)
@@ -312,13 +389,24 @@ def _build_parser() -> argparse.ArgumentParser:
         help="verify on-disk description against captured snapshot; restore if diverged",
     )
     p_ver.add_argument("skill_md", help="path to SKILL.md")
-    p_ver.add_argument(
+    captured = p_ver.add_mutually_exclusive_group(required=True)
+    captured.add_argument(
         "--captured-description",
-        required=True,
         help="the description string captured before the tool call",
     )
+    captured.add_argument(
+        "--captured-file",
+        help="a JSON file whose `description` is the captured value (capture's output saved to a file)",
+    )
     p_ver.set_defaults(func=_cmd_verify_restore)
 
+    p_san = sub.add_parser(
+        "sanitize",
+        help="replace every < with { and every > with } in the on-disk description",
+    )
+    p_san.add_argument("skill_md", help="path to SKILL.md")
+    p_san.set_defaults(func=_cmd_sanitize)
+
     return parser