bmad-module-skill-forge 1.4.1 → 1.5.1

package/src/shared/scripts/skf-forge-tier-rw.py

@@ -4,11 +4,11 @@
 # ///
 """SKF Forge Tier RW — Read/write primitives for forger-sidecar YAML files.
 
-Replaces the prose-driven YAML emission in `src/skf-setup/steps-c/
-step-02-write-config.md` §1-§3 (and the prose-driven cleanup logic in
-step-03 §5/§5b) with one Python invocation. The script is the source
+Replaces the prose-driven YAML emission in `src/skf-setup/references/
+write-config.md` §1-§3 (and the prose-driven cleanup logic in
+step 3 §5/§5b) with one Python invocation. The script is the source
 of truth for the on-disk forge-tier.yaml schema (matching the
-canonical template at step-02-write-config.md:24-58) and guarantees
+canonical template at write-config.md:24-58) and guarantees
 that registry arrays are PRESERVED across rewrites — losing
 `qmd_collections` or `ccc_index_registry` would break every
 downstream skill (skf-create-skill, skf-audit-skill, skf-update-skill,
@@ -37,7 +37,7 @@ Subcommands:
                 the same `name` is replaced, otherwise appended). All
                 other forge-tier state (tools / tier / ccc_index /
                 ccc_index_registry / other qmd_collections entries) is
-                preserved verbatim. Used by skf-brief-skill step-05 §5
+                preserved verbatim. Used by skf-brief-skill step 5 §5
                 and skf-create-skill to register Deep-tier QMD
                 collections without re-rendering the whole file in
                 prose.
@@ -61,7 +61,7 @@ exit non-zero (1 for user error, 2 for I/O failure).
 
 Cross-platform: pure stdlib + PyYAML. Atomic writes via temp + rename
 mirror skf-atomic-write.py's pattern. Concurrent access requires
-external `flock` coordination — see step-07 of skf-create-skill for
+external `flock` coordination — see step 7 of skf-create-skill for
 the precedent.
 
 CLI — invoke via `uv run` so the PEP 723 PyYAML dependency declared
@@ -177,7 +177,7 @@ def render_forge_tier_yaml(payload: dict) -> str:
     """Render the canonical forge-tier.yaml from a context payload.
 
     Preserves the human-readable section comments from the template at
-    step-02-write-config.md:24-58. Sections are emitted in a fixed order
+    write-config.md:24-58. Sections are emitted in a fixed order
     so re-runs against unchanged inputs produce byte-identical output.
     """
     tools = payload["tools"]
@@ -187,7 +187,7 @@ def render_forge_tier_yaml(payload: dict) -> str:
     ccc_index_registry = payload.get("ccc_index_registry", [])
     qmd_collections = payload.get("qmd_collections", [])
 
-    # Render `tools` block in the canonical key order (matches step-02 template).
+    # Render `tools` block in the canonical key order (matches step 2 template).
     tools_ordered = {
         "ast_grep": tools["ast_grep"],
         "gh_cli": tools["gh_cli"],
@@ -219,7 +219,7 @@ def render_forge_tier_yaml(payload: dict) -> str:
         f"tier: {tier}",
         f"tier_detected_at: {_yaml_scalar(tier_detected_at)}",
         "",
-        "# CCC semantic index state (managed by setup step-01b and extraction workflows)",
+        "# CCC semantic index state (managed by setup step 1b and extraction workflows)",
         _yaml_block({"ccc_index": ccc_ordered}),
         "",
         "# CCC index registry (tracks which source paths have been indexed for skill workflows)",
@@ -242,13 +242,13 @@ def _yaml_scalar(value) -> str:
 def _merge_preserved_fields(payload: dict, existing: dict | None) -> dict:
     """Inject preserved fields from the existing file into the new payload.
 
-    Three preservation rules (per step-02 §1 "Note on re-runs"):
+    Three preservation rules (per step 2 §1 "Note on re-runs"):
     - `qmd_collections` array — preserved entirely from existing.
     - `ccc_index_registry` array — preserved entirely from existing.
     - `ccc_index.staleness_threshold_hours` scalar — preserved if user set
       a non-default value; else uses payload value or DEFAULT.
     Note: `ccc_index.exclude_patterns` is NOT preserved (rewritten fresh
-    by step-01b on every run, per the explicit step-02 contract).
+    by step 1b on every run, per the explicit step 2 contract).
     """
     if existing is None:
         return payload

package/src/shared/scripts/skf-hash-content.py

@@ -0,0 +1,284 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Hash Content — SHA-256 hashing helpers for skill workflows.
+
+Two patterns recur across the update-skill workflow's stage prose:
+
+  1. **Single-file hash** — detect-changes.md §1b, when a candidate file is
+     promoted into `brief.scope.include`, the LLM is asked to "compute SHA-256
+     content hash of candidate.path" and emit a record
+     `{path, heuristic, size_bytes, line_count, content_hash}` for
+     `promoted_docs_new[]`. Deterministic file-read + hashlib.sha256.
+
+  2. **Bulk-compare against provenance** — detect-changes.md §Category D,
+     where the LLM is asked to "for each file_entry: compute current SHA-256
+     content hash, compare against stored hash" and classify entries as
+     MODIFIED_FILE / DELETED_FILE / (UNCHANGED). Same hashing primitive,
+     iterated, plus a stat-and-compare. NEW_FILE detection is intentionally
+     out of scope here — that lives in `skf-detect-scripts-assets.py`.
+
+Subcommands:
+  hash <path> [--include-path]
+      Emit JSON {"content_hash": "sha256:...", "size_bytes": N, "line_count": L}
+      for a single file. With --include-path, the record also includes
+      "path": <as given>, so batch callers can collect records by streaming
+      multiple invocations.
+
+  compare <source-root> --provenance-map <path>
+      Read `file_entries[]` from a provenance-map JSON and classify each row
+      against the current source tree. Emits
+        {
+          "comparisons": [
+            {"source_file": "...", "classification": "UNCHANGED|MODIFIED_FILE|DELETED_FILE",
+             "stored_hash": "sha256:...", "current_hash": "sha256:..."|null,
+             "current_size_bytes": N|null}, ...
+          ],
+          "stats": {"total": N, "unchanged": U, "modified": M, "deleted": D}
+        }
+      The provenance file must contain `file_entries` as a top-level array
+      OR be the array itself (handles both schemas).
+
+Hash format: `sha256:` prefix on a hex digest. Matches the convention used
+by skf-detect-scripts-assets.py and the existing prose ("SHA-256 content
+hash" — agnostic about prefix, but the prefix is the SKF convention to make
+hashes self-describing for future algorithm migrations).
+
+CLI examples:
+  uv run skf-hash-content.py hash docs/AGENTS.md
+  uv run skf-hash-content.py hash docs/AGENTS.md --include-path
+  uv run skf-hash-content.py compare /path/to/source \\
+      --provenance-map /path/to/provenance-map.json
+
+Exit codes:
+  0  — operation succeeded (including: file in compare missing on disk;
+       its classification is DELETED_FILE, not an error)
+  1  — user error (bad path, malformed JSON, missing required field)
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+
+# --------------------------------------------------------------------------
+# Hashing primitives
+# --------------------------------------------------------------------------
+
+
+def sha256_of_file(path: Path) -> str:
+    """SHA-256 of file content, with sha256: prefix."""
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(65536), b""):
+            h.update(chunk)
+    return "sha256:" + h.hexdigest()
+
+
+def count_lines(path: Path) -> int:
+    """Count newlines in file content; 0 if unreadable."""
+    n = 0
+    try:
+        with path.open("rb") as fh:
+            for chunk in iter(lambda: fh.read(65536), b""):
+                n += chunk.count(b"\n")
+    except OSError:
+        return 0
+    return n
+
+
+def hash_record(path: Path, *, include_path: bool = False) -> dict:
+    """Build a single-file record: content_hash + size_bytes + line_count."""
+    rec: dict = {
+        "content_hash": sha256_of_file(path),
+        "size_bytes": path.stat().st_size,
+        "line_count": count_lines(path),
+    }
+    if include_path:
+        rec = {"path": path.as_posix(), **rec}
+    return rec
+
+
+# --------------------------------------------------------------------------
+# Provenance comparison
+# --------------------------------------------------------------------------
+
+
+UNCHANGED = "UNCHANGED"
+MODIFIED_FILE = "MODIFIED_FILE"
+DELETED_FILE = "DELETED_FILE"
+
+
+def load_file_entries(provenance_path: Path) -> list[dict]:
+    """Extract the file_entries list from a provenance file.
+
+    Accepts two shapes:
+      - top-level object with a `file_entries` key (canonical)
+      - top-level array of entries (already-extracted)
+
+    Returns a copy of the list. Raises ValueError on malformed JSON or
+    missing key.
+    """
+    try:
+        data = json.loads(provenance_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        raise ValueError(f"failed to read provenance file {provenance_path}: {exc}") from exc
+
+    if isinstance(data, list):
+        return list(data)
+    if isinstance(data, dict):
+        entries = data.get("file_entries")
+        if entries is None:
+            raise ValueError(
+                f"provenance file {provenance_path} has no `file_entries` field"
+            )
+        if not isinstance(entries, list):
+            raise ValueError(
+                f"`file_entries` in {provenance_path} is not an array"
+            )
+        return list(entries)
+    raise ValueError(
+        f"provenance file {provenance_path} must be an object or array; "
+        f"got {type(data).__name__}"
+    )
+
+
+def classify_entry(source_root: Path, entry: dict) -> dict:
+    """Classify a single file_entry against the current source tree."""
+    source_file = entry.get("source_file")
+    stored_hash = entry.get("content_hash")
+    if not isinstance(source_file, str):
+        raise ValueError(f"file_entry missing required `source_file`: {entry!r}")
+
+    current = (source_root / source_file).resolve()
+    # guard against ../.. escapes — resolved path must stay inside source_root
+    try:
+        current.relative_to(source_root.resolve())
+    except ValueError:
+        return {
+            "source_file": source_file,
+            "classification": DELETED_FILE,
+            "stored_hash": stored_hash,
+            "current_hash": None,
+            "current_size_bytes": None,
+        }
+
+    if not current.is_file():
+        return {
+            "source_file": source_file,
+            "classification": DELETED_FILE,
+            "stored_hash": stored_hash,
+            "current_hash": None,
+            "current_size_bytes": None,
+        }
+
+    current_hash = sha256_of_file(current)
+    if current_hash == stored_hash:
+        classification = UNCHANGED
+    else:
+        classification = MODIFIED_FILE
+    return {
+        "source_file": source_file,
+        "classification": classification,
+        "stored_hash": stored_hash,
+        "current_hash": current_hash,
+        "current_size_bytes": current.stat().st_size,
+    }
+
+
+def compare(source_root: Path, provenance_path: Path) -> dict:
+    entries = load_file_entries(provenance_path)
+    comparisons = [classify_entry(source_root, entry) for entry in entries]
+    counts = {UNCHANGED: 0, MODIFIED_FILE: 0, DELETED_FILE: 0}
+    for c in comparisons:
+        counts[c["classification"]] += 1
+    return {
+        "comparisons": comparisons,
+        "stats": {
+            "total": len(comparisons),
+            "unchanged": counts[UNCHANGED],
+            "modified": counts[MODIFIED_FILE],
+            "deleted": counts[DELETED_FILE],
+        },
+    }
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+
+def _cmd_hash(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    if not path.is_file():
+        print(f"error: file not found: {path}", file=sys.stderr)
+        return 1
+    rec = hash_record(path, include_path=args.include_path)
+    json.dump(rec, sys.stdout)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _cmd_compare(args: argparse.Namespace) -> int:
+    source_root = Path(args.source_root)
+    provenance = Path(args.provenance_map)
+    if not source_root.is_dir():
+        print(f"error: source root not a directory: {source_root}", file=sys.stderr)
+        return 1
+    if not provenance.is_file():
+        print(f"error: provenance map not found: {provenance}", file=sys.stderr)
+        return 1
+    try:
+        result = compare(source_root, provenance)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skf-hash-content",
+        description="SHA-256 hashing helpers: single-file record or bulk-compare against provenance.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_hash = sub.add_parser("hash", help="emit hash record for a single file")
+    p_hash.add_argument("path", help="path to the file")
+    p_hash.add_argument(
+        "--include-path",
+        action="store_true",
+        help="include the path string in the emitted record",
+    )
+    p_hash.set_defaults(func=_cmd_hash)
+
+    p_cmp = sub.add_parser(
+        "compare",
+        help="classify provenance file_entries[] against current source tree",
+    )
+    p_cmp.add_argument("source_root", help="path to the source tree root")
+    p_cmp.add_argument(
+        "--provenance-map",
+        required=True,
+        help="path to provenance-map.json (object with file_entries[] or bare array)",
+    )
+    p_cmp.set_defaults(func=_cmd_compare)
+
+    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())

package/src/shared/scripts/skf-load-provenance.py

@@ -0,0 +1,295 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Load Provenance — normalize provenance-map.json into deterministic projections.
+
+Two places in `skf-audit-skill` walk the same provenance map to extract
+identical deterministic projections:
+
+  1. **init.md §4 Load Provenance Map + Stack Skill Detection** — extracts
+     `source_root`, `baseline_commit` (`source_commit`), `baseline_ref`
+     (`source_ref`), and detects stack-skill flags (`provenance_version` and
+     top-level `libraries` for legacy v1 stacks).
+
+  2. **structural-diff.md §1 Prepare Comparison Sets** — re-walks the map to
+     build a `reexport_map` from any `__init__.py` re-export mapping recorded
+     in the provenance map, used to canonicalize public-API renames before
+     diffing.
+
+Both files also reference the **bounded scan list** — the union of
+`entries[].source_file` and `file_entries[].source_file` — which `re-index.md`
+§2 consumes to constrain its scan. Collecting that list once at provenance
+load time and surfacing it as a normalized field removes ~80 lines of
+LLM walk-and-extract prose from the audit-skill references.
+
+The transforms here are pure projections — no I/O against the source tree,
+no comparisons. The script reads one JSON, emits one JSON. The downstream
+canonicalization transforms in structural-diff.md §1 (quote-style on string
+defaults, stdlib module qualification on signature components) STAY in the
+LLM prose because they require per-signature judgment; this script handles
+only the deterministic projections.
+
+Subcommand:
+  normalize <map.json>
+      Emit JSON:
+        {
+          "bounded_scan_files": ["<rel-path, forward-slash>", ...],
+          "is_stack_skill": <bool>,
+          "legacy_stack_provenance": <bool>,
+          "source_root": "<path or null>",
+          "baseline_commit": "<sha or null>",
+          "baseline_ref": "<ref or null>",
+          "reexport_map": {"<from-internal>": "<to-public>"}
+        }
+
+      Bounded scan = union of `entries[].source_file` and
+      `file_entries[].source_file`, deduplicated, sorted, normalized to
+      POSIX forward-slash separators.
+
+      Stack-skill detection mirrors `init.md` §Stack Skill Detection:
+        - `is_stack_skill` is true if `provenance_version >= "2.0"` AND a
+          top-level `libraries` key is present.
+        - `legacy_stack_provenance` is true if `provenance_version` is "1"
+          (or "1.0", or absent treated as v1) AND `skill_type == "stack"`.
+        Note: detecting `is_stack_skill` for a v1 map by the presence of
+        `libraries` alone (the documented behavior in init.md) is also
+        honored — see condition handling in `detect_stack_flags`.
+
+      Re-export map: read `reexport_map` field directly from the provenance
+      map if it exists (writer-side captures __init__.py walk results there).
+      Otherwise, walk `entries[]` for any `reexported_as` field on individual
+      entries — older provenance writers may have used that shape. Empty
+      object when neither is present.
+
+CLI examples:
+  uv run skf-load-provenance.py normalize /path/to/provenance-map.json
+
+Exit codes:
+  0  — normalization succeeded (including empty / well-formed map with no
+       entries — emits all-defaults JSON)
+  1  — user error (file not found, malformed JSON, structurally invalid map)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+# --------------------------------------------------------------------------
+# Provenance map I/O
+# --------------------------------------------------------------------------
+
+
+def load_provenance(path: Path) -> dict:
+    """Read a provenance map JSON. Returns the top-level object.
+
+    Raises ValueError on read failure or non-object top-level.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ValueError(f"failed to read provenance file {path}: {exc}") from exc
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"malformed JSON in provenance file {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"provenance file {path} must be a JSON object at top level; "
+            f"got {type(data).__name__}"
+        )
+    return data
+
+
+# --------------------------------------------------------------------------
+# Projections
+# --------------------------------------------------------------------------
+
+
+def _posix(p: str) -> str:
+    """Normalize a path string to forward-slash form."""
+    return p.replace("\\", "/")
+
+
+def bounded_scan_files(data: dict) -> list[str]:
+    """Union of entries[].source_file + file_entries[].source_file.
+
+    Deduplicated; sorted; forward-slash. Non-string source_file values are
+    silently skipped (consistent with downstream code that expects strings).
+    """
+    paths: set[str] = set()
+    entries = data.get("entries")
+    if isinstance(entries, list):
+        for entry in entries:
+            if not isinstance(entry, dict):
+                continue
+            sf = entry.get("source_file")
+            if isinstance(sf, str) and sf:
+                paths.add(_posix(sf))
+    file_entries = data.get("file_entries")
+    if isinstance(file_entries, list):
+        for entry in file_entries:
+            if not isinstance(entry, dict):
+                continue
+            sf = entry.get("source_file")
+            if isinstance(sf, str) and sf:
+                paths.add(_posix(sf))
+    return sorted(paths)
+
+
+def _normalize_version(v: object) -> tuple[int, ...] | None:
+    """Parse a provenance_version string like "2.0" / "1.5" into a tuple.
+
+    Returns None on absence or unparseable input (treat as legacy v1).
+    """
+    if v is None:
+        return None
+    if isinstance(v, (int, float)):
+        return (int(v),)
+    if not isinstance(v, str):
+        return None
+    parts: list[int] = []
+    for chunk in v.split("."):
+        try:
+            parts.append(int(chunk))
+        except ValueError:
+            return None
+    return tuple(parts) if parts else None
+
+
+def detect_stack_flags(data: dict) -> tuple[bool, bool]:
+    """Return (is_stack_skill, legacy_stack_provenance).
+
+    Mirrors init.md §Stack Skill Detection:
+      - v2+ with libraries → is_stack_skill=true
+      - v2+ with skill_type=="stack" → is_stack_skill=true
+      - v1 / no version with top-level `libraries` → is_stack_skill=true,
+        legacy_stack_provenance=true
+      - v1 / no version with skill_type=="stack" → is_stack_skill=true,
+        legacy_stack_provenance=true
+      - otherwise → both false
+    """
+    version = _normalize_version(data.get("provenance_version"))
+    has_libraries = isinstance(data.get("libraries"), (dict, list))
+    skill_type = data.get("skill_type") if isinstance(data.get("skill_type"), str) else None
+    is_v2 = version is not None and version[0] >= 2
+
+    if is_v2:
+        # v2 stack signaled by either skill_type or libraries presence
+        is_stack = (skill_type == "stack") or has_libraries
+        legacy = False
+        return is_stack, legacy
+
+    # v1 / unversioned — legacy detection by `libraries` key OR skill_type
+    if has_libraries or skill_type == "stack":
+        return True, True
+    return False, False
+
+
+def extract_reexport_map(data: dict) -> dict[str, str]:
+    """Build the public-API re-export map.
+
+    Two writer schemas are supported:
+
+      1. **Top-level `reexport_map`** — modern writers persist the
+         __init__.py walk results here directly, as `{"<internal>": "<public>"}`.
+
+      2. **Per-entry `reexported_as`** — legacy writers (or hand-edited maps)
+         may carry the re-export on each `entries[]` item as
+         `{"export_name": "_Impl", "reexported_as": "Public"}`. We collect
+         all such pairs into the same map shape.
+
+    Non-string keys/values are silently skipped.
+    """
+    out: dict[str, str] = {}
+    top = data.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 = data.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):
+                # per-entry value wins only if the top-level didn't already
+                # carry a binding for the internal name (top-level is the
+                # canonical aggregated form)
+                out.setdefault(internal, public)
+    return out
+
+
+def normalize(data: dict) -> dict:
+    """Build the full normalized projection record."""
+    is_stack, legacy = detect_stack_flags(data)
+    source_root = data.get("source_root") if isinstance(data.get("source_root"), str) else None
+    baseline_commit = (
+        data.get("source_commit") if isinstance(data.get("source_commit"), str) else None
+    )
+    baseline_ref = (
+        data.get("source_ref") if isinstance(data.get("source_ref"), str) else None
+    )
+    return {
+        "bounded_scan_files": bounded_scan_files(data),
+        "is_stack_skill": is_stack,
+        "legacy_stack_provenance": legacy,
+        "source_root": source_root,
+        "baseline_commit": baseline_commit,
+        "baseline_ref": baseline_ref,
+        "reexport_map": extract_reexport_map(data),
+    }
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+
+def _cmd_normalize(args: argparse.Namespace) -> int:
+    path = Path(args.provenance_map)
+    if not path.is_file():
+        print(f"error: provenance map not found: {path}", file=sys.stderr)
+        return 1
+    try:
+        data = load_provenance(path)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    result = normalize(data)
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skf-load-provenance",
+        description=(
+            "Normalize provenance-map.json into deterministic projections "
+            "(bounded scan, stack flags, source_root/commit/ref, reexport map)."
+        ),
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    p_norm = sub.add_parser(
+        "normalize", help="emit normalized projection JSON from a provenance map"
+    )
+    p_norm.add_argument("provenance_map", help="path to provenance-map.json")
+    p_norm.set_defaults(func=_cmd_normalize)
+    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())