bmad-module-skill-forge 2.2.0 → 3.0.0

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

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # dependencies = []
 # ///
 """SKF Hash Content — SHA-256 hashing helpers for skill workflows.
@@ -22,8 +22,8 @@ Two patterns recur across the update-skill workflow's stage prose:
   3. **[MANUAL]-section integrity** — the update-skill workflow's headline
      Workflow Rule is "[MANUAL] sections survive regeneration with zero
      content loss." init.md §5 captures a pre-write inventory of every
-     `<!-- [MANUAL:name] --> … <!-- [/MANUAL:name] -->` block; write.md §1
-     (HALT gate) and validate.md Check B verify the post-merge SKILL.md
+     `<!-- [MANUAL:name] --> … <!-- [/MANUAL:name] -->` block; merge.md §6b,
+     write.md §1 (HALT gate) and write.md §7 verify the merged SKILL.md
      against it. Doing that by an LLM marker-count + eyeball can silently
      pass a block whose interior was truncated (marker count unchanged).
      The `manual-inventory` / `manual-verify` subcommands extract each block
@@ -82,17 +82,41 @@ Subcommands:
       The inventory may be the object emitted by `manual-inventory` OR a bare
       `blocks[]` array (handles both shapes).
 
+  manual-inventory-amend --inventory <inventory.json> --plan <plan.json>
+                         --output <amended-inventory.json>
+      Apply the user's [MANUAL] conflict decisions to a captured inventory,
+      so the post-merge check verifies what the user approved instead of
+      the pre-merge blocks. The plan is
+        {"decisions": [
+          {"name": "...", "action": "keep" | "remove" | "edit",
+           "content_file": "<path>" | "content": "<text>"}, ...]}
+      `remove` (an [R]emove or an orphan the user removed) drops every
+      block of that name; `edit` (an [E]dit) rehashes the one block of that
+      name from the approved interior: the bytes of `content_file` (a path
+      relative to the plan's folder, or absolute), or `content` encoded as
+      UTF-8, exactly the bytes the merged file holds between the markers,
+      newlines included. `keep` and a block the plan does not name stay as
+      captured. Writes the amended inventory ({blocks[], count}, the shape
+      `manual-inventory` emits) to --output through a temporary file and a
+      rename, then prints
+        {"output": "...", "count": N, "removed": [names],
+         "edited": [names], "kept": [names]}
+      A plan with no decisions copies the inventory. A plan that names a
+      block the inventory does not hold, decides one name twice, edits a
+      name that several blocks share, or gives an edit no content (or both
+      forms) is refused with exit 1 and nothing written.
+
   compare-constituent-hashes <provenance-map.json> [--skills-root <root>]
       Constituent-drift detection for compose-mode stack skills. Replaces the
       per-constituent read + SHA-256 + compare loop at
-      `src/skf-audit-skill/references/init.md` (Stack Skill Detection). Reads
-      the `constituents[]` array from a compose-mode provenance map (each
-      entry carrying `skill_name`, `skill_path`, and the compile-time
-      `metadata_hash`), reads each constituent's live
-      `{skill_path}/active/{skill_name}/metadata.json`, recomputes its
-      SHA-256 with the same `sha256:` prefix convention the writer used
-      (`skf-enumerate-stack-skills._sha256_of_bytes`), and buckets each
-      constituent:
+      `src/skf-audit-skill/references/constituent-freshness.md` (step 1c,
+      Constituent Freshness). Reads the `constituents[]` array from a
+      compose-mode provenance map (each entry carrying `skill_name`,
+      `skill_path`, and the compile-time `metadata_hash`), reads each
+      constituent's live `{skill_path}/active/{skill_name}/metadata.json`,
+      recomputes its SHA-256 with the same `sha256:` prefix convention the
+      writer used (`skf-enumerate-stack-skills._sha256_of_bytes`), and
+      buckets each constituent:
         {
           "drifted":  [{"skill_name","skill_path","stored_hash","current_hash"}],
           "fresh":    [{"skill_name"}],
@@ -126,6 +150,8 @@ CLI examples:
       --provenance-map /path/to/provenance-map.json
   uv run skf-hash-content.py manual-inventory SKILL.md
   uv run skf-hash-content.py manual-verify --inventory inventory.json SKILL.md
+  uv run skf-hash-content.py manual-inventory-amend --inventory inventory.json \\
+      --plan manual-plan.json --output amended-inventory.json
 
 Exit codes:
   0  — operation succeeded (including: file in compare missing on disk, its
@@ -466,6 +492,102 @@ def manual_verify(inventory_path: Path, skill_md_path: Path) -> dict:
     return classify_manual_blocks(inv_blocks, cur_blocks)
 
 
+_PLAN_ACTIONS = ("keep", "remove", "edit")
+
+
+def _load_plan(plan_path: Path) -> list[dict]:
+    """The decisions[] of a manual plan. Raises ValueError on malformed input."""
+    try:
+        data = json.loads(plan_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        raise ValueError(f"failed to read plan file {plan_path}: {exc}") from exc
+    if not isinstance(data, dict) or not isinstance(data.get("decisions"), list):
+        raise ValueError(f"plan file {plan_path} must be an object with a `decisions` array")
+    decisions = data["decisions"]
+    for d in decisions:
+        if not isinstance(d, dict) or not isinstance(d.get("name"), str) or not d["name"].strip():
+            raise ValueError(f"every decision in {plan_path} needs a non-empty `name`: {d!r}")
+        if d.get("action") not in _PLAN_ACTIONS:
+            raise ValueError(f"decision for {d['name']!r}: `action` must be one of "
+                             f"{', '.join(_PLAN_ACTIONS)}, got {d.get('action')!r}")
+    return decisions
+
+
+def _edited_interior(decision: dict, plan_dir: Path) -> bytes:
+    """The approved interior bytes of an `edit` decision."""
+    has_file, has_text = "content_file" in decision, "content" in decision
+    if has_file == has_text:
+        raise ValueError(f"edit of {decision['name']!r} needs exactly one of `content_file` and `content`")
+    if has_text:
+        if not isinstance(decision["content"], str):
+            raise ValueError(f"edit of {decision['name']!r}: `content` must be a string")
+        return decision["content"].encode("utf-8")
+    raw = decision["content_file"]
+    if not isinstance(raw, str) or not raw:
+        raise ValueError(f"edit of {decision['name']!r}: `content_file` must be a path")
+    path = Path(raw)
+    if not path.is_absolute():
+        path = plan_dir / path
+    try:
+        return path.read_bytes()
+    except OSError as exc:
+        raise ValueError(f"edit of {decision['name']!r}: cannot read {path}: {exc}") from exc
+
+
+def amend_inventory(inv_blocks: list[dict], decisions: list[dict], plan_dir: Path) -> tuple[list[dict], dict]:
+    """The inventory blocks with the plan's decisions applied, and what changed.
+
+    Pure apart from reading each edit's content file. Raises ValueError for
+    a plan the inventory cannot take (see the module docstring).
+    """
+    names = [b.get("name") for b in inv_blocks]
+    seen: set[str] = set()
+    by_name: dict[str, dict] = {}
+    for d in decisions:
+        name = d["name"]
+        if name in seen:
+            raise ValueError(f"the plan decides {name!r} twice")
+        seen.add(name)
+        if name not in names:
+            raise ValueError(f"the plan names {name!r}, which the inventory does not hold")
+        if d["action"] == "edit" and names.count(name) > 1:
+            raise ValueError(f"the plan edits {name!r}, which {names.count(name)} blocks share")
+        by_name[name] = d
+    out: list[dict] = []
+    for block in inv_blocks:
+        decision = by_name.get(block.get("name"))
+        if decision is None or decision["action"] == "keep":
+            out.append(dict(block))
+        elif decision["action"] == "edit":
+            out.append({**block, "content_hash": sha256_of_bytes(_edited_interior(decision, plan_dir))})
+    changes = {action: [d["name"] for d in decisions if d["action"] == key]
+               for action, key in (("removed", "remove"), ("edited", "edit"), ("kept", "keep"))}
+    return out, changes
+
+
+def _write_atomic(path: Path, text: str) -> None:
+    """Write `text` to `path` through a temporary file and one rename."""
+    tmp = path.with_name(f".{path.name}.skf-tmp")
+    try:
+        tmp.write_bytes(text.encode("utf-8"))
+        tmp.replace(path)
+    except OSError:
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+        raise
+
+
+def manual_inventory_amend(inventory_path: Path, plan_path: Path, output_path: Path) -> dict:
+    """Write the amended inventory to `output_path` and return the summary."""
+    inv_blocks = load_inventory_blocks(inventory_path)
+    decisions = _load_plan(plan_path)
+    blocks, changes = amend_inventory(inv_blocks, decisions, plan_path.parent)
+    _write_atomic(output_path, json.dumps({"blocks": blocks, "count": len(blocks)}, indent=2) + "\n")
+    return {"output": output_path.as_posix(), "count": len(blocks), **changes}
+
+
 # --------------------------------------------------------------------------
 # Constituent-hash comparison (compose-mode stack drift)
 # --------------------------------------------------------------------------
@@ -516,7 +638,8 @@ def load_constituents(provenance_path: Path) -> list[dict]:
 def _constituent_metadata_path(skills_root: Path, skill_path: str, skill_name: str) -> Path:
     """Resolve a constituent's live metadata.json path.
 
-    Mirrors init.md's Stack Skill Detection prose:
+    Mirrors the by-hand fallback of constituent-freshness.md (audit-skill
+    step 1c):
     `{skill_path}/active/{skill_name}/metadata.json`. A relative `skill_path`
     resolves against `skills_root`; an absolute one is used as-is.
     """
@@ -675,6 +798,28 @@ def _cmd_manual_verify(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_manual_inventory_amend(args: argparse.Namespace) -> int:
+    inventory, plan, output = Path(args.inventory), Path(args.plan), Path(args.output)
+    for label, path in (("inventory", inventory), ("plan", plan)):
+        if not path.is_file():
+            print(f"error: {label} not found: {path}", file=sys.stderr)
+            return 1
+    if not output.parent.is_dir():
+        print(f"error: output folder not found: {output.parent}", file=sys.stderr)
+        return 1
+    try:
+        result = manual_inventory_amend(inventory, plan, output)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except OSError as exc:
+        print(f"error: cannot write {output}: {exc}", file=sys.stderr)
+        return 1
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
 def _cmd_compare_constituents(args: argparse.Namespace) -> int:
     provenance = Path(args.provenance_map)
     skills_root = Path(args.skills_root)
@@ -741,6 +886,15 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     p_ver.set_defaults(func=_cmd_manual_verify)
 
+    p_amend = sub.add_parser(
+        "manual-inventory-amend",
+        help="apply the user's [MANUAL] remove and edit decisions to a captured inventory",
+    )
+    p_amend.add_argument("--inventory", required=True, help="the manual-inventory JSON captured before the merge")
+    p_amend.add_argument("--plan", required=True, help="the plan JSON holding the user's decisions")
+    p_amend.add_argument("--output", required=True, help="where to write the amended inventory JSON")
+    p_amend.set_defaults(func=_cmd_manual_inventory_amend)
+
     p_con = sub.add_parser(
         "compare-constituent-hashes",
         help="classify compose-mode stack constituents as drifted/fresh/missing",

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

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.9"
+# requires-python = ">=3.11"
 # dependencies = []
 # ///
 """SKF Language Corpora — canonical companion prose corpora for a language.

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

@@ -1,46 +1,50 @@
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # 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:
+`skf-audit-skill` reads one provenance map in several steps, and each needs
+a projection of it with one correct answer:
 
   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.
+     (`source_ref`), detects stack-skill flags (`provenance_version` and
+     top-level `libraries` for legacy v1 stacks), and takes the baseline
+     facts init.md §7 shows (export count, generation time and age).
+
+  2. **re-index.md §2 and §3**: the **bounded scan list** (the union of
+     `entries[].source_file` and `file_entries[].source_file`), which the
+     recipe runner reads, and for a stack the library of each file
+     (`source_library_by_file`), which skf-extraction-snapshot.py gives each
+     export of the snapshot it builds (it loads this script beside it).
+
+skf-structural-diff.py derives the re-export map from the provenance map
+itself and applies the quote-style, stdlib-prefix and re-export transforms
+on both sides (structural-diff.md §1), so no step carries `reexport_map`
+from here; the field stays for a caller that passes it to the diff as
+`--reexport-map`.
 
 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.
+no comparisons. The script reads one JSON, emits one JSON.
 
 Subcommand:
-  normalize <map.json>
+  normalize <map.json> [--now <ISO-8601>]
       Emit JSON:
         {
           "bounded_scan_files": ["<rel-path, forward-slash>", ...],
           "is_stack_skill": <bool>,
           "legacy_stack_provenance": <bool>,
+          "compose_mode_stack": <bool>,
           "source_root": "<path or null>",
           "baseline_commit": "<sha or null>",
           "baseline_ref": "<ref or null>",
-          "reexport_map": {"<from-internal>": "<to-public>"}
+          "reexport_map": {"<from-internal>": "<to-public>"},
+          "source_library_by_file": {"<rel-path>": "<library>"},
+          "export_count": <int>,
+          "generated_at": "<YYYY-MM-DDTHH:MM:SSZ or null>",
+          "age_days": <int or null>,
+          "age_source": "generated_at" | "mtime" | null
         }
 
       Bounded scan = union of `entries[].source_file` and
@@ -55,6 +59,17 @@ Subcommand:
         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`.
+        - `compose_mode_stack` is true for a stack whose map holds a
+          `constituents` list: the compose-mode variant create-stack-skill
+          writes, whose entries come from constituent skills rather than a
+          source tree. Audit-skill checks its constituents' freshness
+          instead of re-indexing a source.
+
+      File-to-library map: each `entries[].source_file` (forward slashes)
+      with the `source_library` of its entries, for a stack's per-library
+      diff. A file whose entries name no library is left out, and when its
+      entries name two, the first one's wins. Empty for a single skill
+      whose entries carry no `source_library`.
 
       Re-export map: read `reexport_map` field directly from the provenance
       map if it exists (writer-side captures __init__.py walk results there).
@@ -62,8 +77,18 @@ Subcommand:
       entries — older provenance writers may have used that shape. Empty
       object when neither is present.
 
+      Baseline facts for init.md §7 (the audit baseline summary):
+        - `export_count` is the number of `entries[]` objects.
+        - `generated_at` is the map's `generated_at` in UTC, whatever zone
+          it was written in; null when absent or not an ISO-8601 date-time.
+        - `age_days` is the whole days from `generated_at` to now (never
+          below 0), or from the file's modification time when the map has
+          no usable `generated_at` (`age_source` says which; null when
+          neither is known). `--now` fixes "now" for a reproducible run.
+
 CLI examples:
   uv run skf-load-provenance.py normalize /path/to/provenance-map.json
+  uv run skf-load-provenance.py normalize /path/to/provenance-map.json --now 2026-05-01T00:00:00Z
 
 Exit codes:
   0  — normalization succeeded (including empty / well-formed map with no
@@ -75,7 +100,9 @@ from __future__ import annotations
 
 import argparse
 import json
+import re
 import sys
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
 
@@ -141,6 +168,25 @@ def bounded_scan_files(data: dict) -> list[str]:
     return sorted(paths)
 
 
+def source_library_by_file(data: dict) -> dict[str, str]:
+    """{source_file: source_library} from `entries[]`, paths forward-slash.
+
+    The first library named for a file wins; entries without a string
+    `source_library` add nothing.
+    """
+    out: dict[str, str] = {}
+    entries = data.get("entries")
+    if not isinstance(entries, list):
+        return out
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        sf, library = entry.get("source_file"), entry.get("source_library")
+        if isinstance(sf, str) and sf and isinstance(library, str) and library:
+            out.setdefault(_posix(sf), library)
+    return dict(sorted(out.items()))
+
+
 def _normalize_version(v: object) -> tuple[int, ...] | None:
     """Parse a provenance_version string like "2.0" / "1.5" into a tuple.
 
@@ -226,7 +272,77 @@ def extract_reexport_map(data: dict) -> dict[str, str]:
     return out
 
 
-def normalize(data: dict) -> dict:
+ISO_TIME_RE = re.compile(
+    r"(\d{4})-(\d{2})-(\d{2})"
+    r"(?:[Tt ](\d{2}):(\d{2})(?::(\d{2})(?:[.,](\d+))?)?)?"
+    r"\s*([Zz]|[+-]\d{2}(?::?\d{2})?)?")
+
+
+# Keep identical to _parse_iso_utc in skf-skill-inventory.py
+# (test/test-skf-skill-inventory.py pins the copies).
+def _parse_iso_utc(value):
+    """An ISO-8601 date or date-time as an aware UTC datetime, else None.
+
+    A time without a zone is read as UTC, a date alone as its midnight UTC.
+    """
+    if not isinstance(value, str):
+        return None
+    m = ISO_TIME_RE.fullmatch(value.strip())
+    if not m:
+        return None
+    year, month, day, hour, minute, second, fraction, zone = m.groups()
+    offset = timedelta(0)
+    if zone and zone not in ("Z", "z"):
+        digits = zone[1:].replace(":", "")
+        offset = timedelta(hours=int(digits[:2]), minutes=int(digits[2:] or 0))
+        if zone[0] == "-":
+            offset = -offset
+    try:
+        moment = datetime(int(year), int(month), int(day), int(hour or 0), int(minute or 0),
+                          int(second or 0), int((fraction or "0")[:6].ljust(6, "0")))
+        return (moment - offset).replace(tzinfo=timezone.utc)
+    except (ValueError, OverflowError):  # no such date, or out of datetime's range
+        return None
+
+
+def export_count(data: dict) -> int:
+    """The number of `entries[]` objects (the exports the map records)."""
+    entries = data.get("entries")
+    if not isinstance(entries, list):
+        return 0
+    return sum(1 for entry in entries if isinstance(entry, dict))
+
+
+def provenance_age(
+    data: dict, mtime: datetime | None = None, now: datetime | None = None
+) -> dict:
+    """{generated_at, age_days, age_source} for the audit baseline.
+
+    `generated_at` is the map's field in UTC (null when absent or not
+    ISO-8601). The age counts whole days from it to `now` (the current time
+    when None), else from `mtime` (the file's modification time), never
+    below 0.
+    """
+    generated = _parse_iso_utc(data.get("generated_at"))
+    if generated is not None:
+        since, source = generated, "generated_at"
+    elif mtime is not None:
+        since, source = mtime, "mtime"
+    else:
+        since, source = None, None
+    age_days = None
+    if since is not None:
+        age_days = max(0, ((now or datetime.now(timezone.utc)) - since).days)
+    return {
+        "generated_at": generated.strftime("%Y-%m-%dT%H:%M:%SZ") if generated else None,
+        "age_days": age_days,
+        "age_source": source,
+    }
+
+
+def normalize(
+    data: dict, mtime: datetime | None = None, now: datetime | None = None
+) -> 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
@@ -240,10 +356,14 @@ def normalize(data: dict) -> dict:
         "bounded_scan_files": bounded_scan_files(data),
         "is_stack_skill": is_stack,
         "legacy_stack_provenance": legacy,
+        "compose_mode_stack": is_stack and isinstance(data.get("constituents"), list),
         "source_root": source_root,
         "baseline_commit": baseline_commit,
         "baseline_ref": baseline_ref,
         "reexport_map": extract_reexport_map(data),
+        "source_library_by_file": source_library_by_file(data),
+        "export_count": export_count(data),
+        **provenance_age(data, mtime, now),
     }
 
 
@@ -257,12 +377,19 @@ def _cmd_normalize(args: argparse.Namespace) -> int:
     if not path.is_file():
         print(f"error: provenance map not found: {path}", file=sys.stderr)
         return 1
+    now = None
+    if args.now is not None:
+        now = _parse_iso_utc(args.now)
+        if now is None:
+            print(f"error: --now is not an ISO-8601 date-time: {args.now}", file=sys.stderr)
+            return 1
     try:
         data = load_provenance(path)
-    except ValueError as exc:
+        mtime = datetime.fromtimestamp(path.stat().st_mtime, timezone.utc)
+    except (ValueError, OSError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 1
-    result = normalize(data)
+    result = normalize(data, mtime=mtime, now=now)
     json.dump(result, sys.stdout, indent=2)
     sys.stdout.write("\n")
     return 0
@@ -273,7 +400,8 @@ def _build_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)."
+            "(bounded scan, stack flags, source_root/commit/ref, reexport map, "
+            "file-to-library map, export count, generated_at and age)."
         ),
     )
     sub = parser.add_subparsers(dest="cmd", required=True)
@@ -281,6 +409,10 @@ def _build_parser() -> argparse.ArgumentParser:
         "normalize", help="emit normalized projection JSON from a provenance map"
     )
     p_norm.add_argument("provenance_map", help="path to provenance-map.json")
+    p_norm.add_argument(
+        "--now",
+        help="ISO-8601 date-time that age_days counts to (default: the current time)",
+    )
     p_norm.set_defaults(func=_cmd_normalize)
     return parser
 

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

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # dependencies = []
 # ///
 """SKF Manifest Ops — CRUD operations on the export manifest.