bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/shared/scripts/skf-render-metadata-stats.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # dependencies = []
 # ///
 """SKF Render Metadata Stats — derive metadata.json's computed stats block and
@@ -40,9 +40,16 @@ distribution ALWAYS bins `entries[]`, so it always sums to `len(entries)`. What
     to the *citation count* (= `len(entries)`), NOT to `exports_documented`
     (which is the pattern-surface proxy `pattern_surfaces_documented`, a
     judgment value). `effective_denominator` is never emitted.
-  - **stack** — `entries[]` are the cited constituent contracts, so the
-    distribution sums to the *constituent count* (= `len(entries)`), NOT to
-    `exports_documented` (a stack's own barrel is empty by design).
+  - **stack**: `exports_documented` comes from the payload (a stack's own
+    barrel is empty by design), and the distribution still sums to the
+    *entry count* (= `len(entries)`), one per provenance entry. A stack's
+    metadata.json counts libraries instead: its `confidence_distribution`
+    bins each library once, by the library's tier, and sums to
+    `library_count`. So create-stack-skill runs this shape in compute mode
+    for the label check (`coherence`) and for its evidence report's
+    per-entry counts, and writes neither `stats` nor
+    `confidence_distribution` into metadata.json; `--check` does not fit a
+    stack.
 
 Modes
 -----
@@ -57,7 +64,10 @@ metadata.json; re-derive the computed values (taking the judgment values —
 on-disk metadata itself) and compare against what is on disk. `coherence.ok`
 is false with a `violations[]` list when the on-disk file drifted; the emitted
 `stats`/`confidence_distribution` are the corrected values `validate.md §7`
-writes back.
+writes back. While label violations are present (see Label agreement below)
+they are not: the distribution is binned from the mislabeled
+`signature_source`, so the caller relabels the provenance-map, re-runs the
+helper, and writes the re-run's values.
 
 Judgment payload (stdin JSON, compute mode)::
 
@@ -88,11 +98,45 @@ Output JSON (both modes)::
       "coherence": {"ok": true, "violations": []}
     }
 
+Label agreement (both modes)
+---------------------------
+
+Every `entries[]` row whose `confidence` is T1 or T1-low (case-insensitive)
+must carry the labels its `extraction_method` implies, so a label always names
+the tool that produced the entry, never the forge tier:
+
+  - `extraction_method` is one of ast-grep, source-read, ast_bridge,
+    source_reading, qmd_bridge, compose-from-skill.
+  - ast-grep and ast_bridge need confidence T1; ast-grep also needs a
+    non-null `ast_node_type` (the `kind` the matching ast-grep recipe declares
+    in create-skill's extraction-patterns.md).
+  - source-read and source_reading need confidence T1-low and a
+    `signature_source` other than T1; source-read also needs `ast_node_type`
+    null (an absent key counts as null).
+  - qmd_bridge and compose-from-skill carry no pairing.
+
+A row read by eye (source-read, source_reading) is checked at any other
+`confidence` (T2, T3, none) too, for its `signature_source` alone: the
+distribution bins every row by `signature_source`, so a T1 there would count
+a signature read by eye as T1. The other rows with another confidence
+(ast-grep, ast_bridge, qmd_bridge, compose-from-skill, an unknown method)
+and `file_entries[]` are not checked. Each disagreement is a violation keyed
+by the row's index, because reference-app and stack maps repeat export
+names::
+
+    {"field": "provenance.entries[12].confidence", "export_name": "search",
+     "expected": "T1-low", "actual": "T1",
+     "note": "extraction_method source-read pairs with confidence T1-low"}
+
+The step that runs the helper relabels the entry to match its method (never
+the reverse) and runs the helper again.
+
 Exit codes:
-  0  — coherence ok (no violations)
-  1  — coherence violations present (drift to auto-fix / bad signature_source);
-       the JSON on stdout is still authoritative — rely on it, not the code
-  2  — usage / IO / JSON-decode error
+  0: coherence ok (no violations)
+  1: coherence violations present (drift to auto-fix, a bad signature_source,
+     or a label that disagrees with extraction_method); the JSON on stdout is
+     still authoritative, so rely on it, not the code
+  2: usage, IO or JSON-decode error
 """
 
 from __future__ import annotations
@@ -109,6 +153,16 @@ _SIG_MAP = {"T1": "t1", "T1-LOW": "t1_low", "T2": "t2", "T3": "t3"}
 _VALID_SHAPES = ("library", "stack", "reference-app")
 _DIST_KEYS = ("t1", "t1_low", "t2", "t3")
 
+# extraction_method values a T1 or T1-low entry may carry, and the labels
+# each one implies. ast-grep / source-read are what create-skill and
+# update-skill write; the other four come from stack maps.
+_KNOWN_METHODS = (
+    "ast-grep", "source-read", "ast_bridge", "source_reading", "qmd_bridge", "compose-from-skill",
+)
+_T1_METHODS = ("ast-grep", "ast_bridge")            # confidence T1
+_T1_LOW_METHODS = ("source-read", "source_reading")  # confidence T1-low, signature_source never T1
+_LABELED_CONFIDENCE = ("T1", "T1-LOW")
+
 
 # --------------------------------------------------------------------------
 # IO
@@ -275,13 +329,95 @@ def _cmp_ratio(violations: list, field: str, expected, actual) -> None:
         violations.append({"field": field, "expected": expected, "actual": actual})
 
 
+def _upper(value: object) -> str | None:
+    return value.strip().upper() if isinstance(value, str) else None
+
+
+def check_label_agreement(prov: dict) -> list[dict]:
+    """Check that each T1 / T1-low entry's labels match its extraction_method,
+    and that no entry read by eye claims a T1 signature_source.
+
+    Returns one violation per disagreeing field, keyed by the entry's index
+    (`provenance.entries[<i>].<field>`) since export names repeat in
+    reference-app and stack maps. `expected` is the value the method implies;
+    the caller relabels the entry to it and never changes a known method.
+    An entry read by eye (source-read, source_reading) with any other
+    confidence is checked for its signature_source alone; the other entries
+    with another confidence, and `file_entries[]`, are not checked.
+    """
+    entries = prov.get("entries")
+    if not isinstance(entries, list):
+        return []
+    violations: list[dict] = []
+
+    for i, entry in enumerate(entries):
+        if not isinstance(entry, dict):
+            continue
+        confidence = entry.get("confidence")
+        method = entry.get("extraction_method")
+        labeled = _upper(confidence) in _LABELED_CONFIDENCE
+        # Off T1 / T1-low only an entry read by eye is checked, for its
+        # signature_source: binning reads that label whatever the confidence,
+        # so a T1 there would count a signature read by eye as T1.
+        if not labeled and method not in _T1_LOW_METHODS:
+            continue
+        name = entry.get("export_name")
+
+        def flag(field: str, expected: object, actual: object, note: str) -> None:
+            violations.append({
+                "field": f"provenance.entries[{i}].{field}",
+                "export_name": name,
+                "expected": expected,
+                "actual": actual,
+                "note": note,
+            })
+
+        if method not in _KNOWN_METHODS:
+            flag("extraction_method", sorted(_KNOWN_METHODS), method,
+                 "a T1 or T1-low entry names the tool that produced it: set ast-grep for an "
+                 "ast-grep match or source-read for an entry read by eye")
+            continue
+
+        if method in _T1_METHODS:
+            if _upper(confidence) != "T1":
+                flag("confidence", "T1", confidence,
+                     f"extraction_method {method} pairs with confidence T1")
+            node = entry.get("ast_node_type")
+            # "non-null" is the violation's own expected value, not a node kind:
+            # a fixer that copied it has still not recorded the kind.
+            if method == "ast-grep" and (not (isinstance(node, str) and node.strip())
+                                         or _upper(node) == "NON-NULL"):
+                flag("ast_node_type", "non-null", node,
+                     "extraction_method ast-grep pairs with a non-null ast_node_type: copy "
+                     "the kind the matching recipe declares")
+        elif method in _T1_LOW_METHODS:
+            if labeled and _upper(confidence) != "T1-LOW":
+                flag("confidence", "T1-low", confidence,
+                     f"extraction_method {method} pairs with confidence T1-low")
+            sig = entry.get("signature_source")
+            if _upper(sig) == "T1":
+                flag("signature_source", "T1-low", sig,
+                     f"extraction_method {method} pairs with a signature_source other than T1 "
+                     "(any tier but T1 passes)")
+            node = entry.get("ast_node_type")
+            if labeled and method == "source-read" and node is not None:
+                flag("ast_node_type", None, node,
+                     "extraction_method source-read pairs with ast_node_type null: no ast-grep "
+                     "rule matched this entry")
+        # qmd_bridge and compose-from-skill carry no pairing.
+
+    return violations
+
+
 def coherence_compute(derived: dict, prov: dict) -> dict:
     """Internal-consistency checks for compute mode.
 
     The distribution must account for every provenance entry (a bin-sum below
     the entry count means some entries carry a missing/unrecognized
     signature_source). When the provenance-map already tracks scripts/assets in
-    file_entries[], those counts must agree with the stats counts.
+    file_entries[], those counts must agree with the stats counts. Every T1 or
+    T1-low entry's labels must match its extraction_method, and no entry read
+    by eye may claim a T1 signature_source (check_label_agreement).
     """
     violations: list[dict] = []
     entry_count = derived["_derivation"]["entry_count"]
@@ -311,6 +447,7 @@ def coherence_compute(derived: dict, prov: dict) -> dict:
         _cmp_int(violations, "stats.assets_count", fe["asset"], ac,
                  "stats.assets_count disagrees with provenance-map file_entries[file_type=asset]")
 
+    violations.extend(check_label_agreement(prov))
     return {"ok": not violations, "violations": violations}
 
 
@@ -320,6 +457,8 @@ def check_stats(derived: dict, metadata: dict, prov: dict) -> dict:
     Every mismatch is a `{field, expected, actual}` violation, where `expected`
     is the re-derived (correct) value and `actual` is what is on disk.
     validate.md §7 either writes `derived` verbatim or fixes each violation.
+    Label violations from check_label_agreement are appended too; they concern
+    the provenance-map, which is relabeled before the stats are fixed.
     """
     violations: list[dict] = []
     m_stats = metadata.get("stats") if isinstance(metadata.get("stats"), dict) else {}
@@ -364,6 +503,8 @@ def check_stats(derived: dict, metadata: dict, prov: dict) -> dict:
             _cmp_int(violations, "provenance.file_entries.asset", claimed_ac, fe["asset"],
                      "provenance-map file_entries[file_type=asset] count disagrees with metadata assets_count")
 
+    # provenance entry labels vs extraction_method (the map, not metadata.json)
+    violations.extend(check_label_agreement(prov))
     return {"ok": not violations, "violations": violations}
 
 
@@ -406,8 +547,11 @@ def build_parser() -> argparse.ArgumentParser:
         description=(
             "Derive metadata.json stats + confidence_distribution from the staged "
             "provenance-map (compute mode), or re-verify an on-disk metadata.json "
-            "against the map (--check). Replaces the hand-binning/summing in "
-            "skf-create-skill compile.md §4 and validate.md §7."
+            "against the map (--check). Both modes also check that each T1 or "
+            "T1-low entry's confidence, signature_source and ast_node_type match "
+            "its extraction_method, and that no entry read by eye claims a T1 "
+            "signature_source at any confidence. Replaces the hand-binning/summing "
+            "in skf-create-skill compile.md §4 and validate.md §7."
         ),
     )
     parser.add_argument("provenance_map", help="path to the staged provenance-map.json")

package/src/shared/scripts/skf-render-quick-metadata.py

@@ -1,14 +1,16 @@
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # dependencies = []
 # ///
-"""SKF Render Quick Metadata — render metadata.json per the canonical
+"""SKF Render Quick Metadata: render metadata.json per the canonical
 skill-template.md schema with quick-skill-specific population rules.
 
-Pure renderer — no I/O beyond stdin/stdout. Reads a JSON payload of
-extracted state on stdin and emits the corresponding metadata.json
-on stdout. Replaces the hand-assembly the LLM previously did in
-skf-quick-skill step 4 §4.
+Replaces the hand-assembly the LLM previously did in skf-quick-skill step 4
+section 4. The export list, the dependencies and the package's version come
+from the files step 3 wrote (skf-extract-public-api.py's output, or
+skf-skills-module.py extract's), and the SKF version from the installed
+module, so the model stages only the fields it decides: no export list and
+no file probe passes through a shell string.
 
 Constants vs. input-derived split mirrors step 4's documentation:
 
@@ -23,7 +25,7 @@ Constants vs. input-derived split mirrors step 4's documentation:
     stats.exports_internal, stats.scripts_count, stats.assets_count 0
     stats.public_api_coverage, stats.total_coverage                 1.0
 
-  Input-derived (from stdin payload):
+  Input-derived:
     name, version, description, language, source_repo,
     source_root, source_commit, source_package,
     exports[], dependencies[], compatibility,
@@ -35,7 +37,33 @@ Constants vs. input-derived split mirrors step 4's documentation:
     confidence_distribution.t1_low  count(exports)
     stats.exports_documented / public_api / total  count(exports)
 
-Input JSON shape (stdin):
+CLI:
+
+  uv run skf-render-quick-metadata.py --input <metadata-input.json> \\
+      [--extraction <file>]... [--skf-root <dir>] [--output <metadata.json>]
+  python3 skf-render-quick-metadata.py < payload.json
+
+With --input, the payload is that file (a quoted heredoc stages it, so a
+description holding an apostrophe, a quote or a `$` arrives as written),
+and each --extraction file is the JSON step 3 printed for one module, in
+module order (the parent first). A payload field that is absent or null
+takes its value from them:
+
+  exports        every extraction's exports[] names, in order, each once
+                 (a payload `exports` list is the --exports override and
+                 wins)
+  dependencies   every extraction's dependencies[], each once
+  version        the first extraction's version that is set, else "1.0.0"
+                 (a payload version, the target's pinned version, wins)
+  source_package the first extraction's package_name, else name
+  description    the first extraction's description
+
+and tool_versions.skf, unless the payload names skf_version, is probed
+under --skf-root (the installed module, {project-root}/_bmad/skf): the
+`version` of its package.json, else the first line of its VERSION file,
+else "unknown". --output also writes the rendered metadata.json there.
+
+Without --input, the whole payload comes on stdin, every field typed:
 
   {
     "name":           "foo",
@@ -54,15 +82,15 @@ Input JSON shape (stdin):
     "skf_version":    "1.2.0"                        (default "unknown")
   }
 
-CLI:
-
-  python3 skf-render-quick-metadata.py < input.json
+The rendered metadata.json is printed on stdout either way.
 
 Exit codes:
 
   0   success
-  1   payload-level error (missing required field)
-  2   stdin / argparse / JSON-decode error
+  1   payload-level error (missing required field: name, language or
+      source_repo)
+  2   stdin / argparse / JSON-decode error, or an --input, --extraction or
+      --output file that cannot be read or written
 """
 
 from __future__ import annotations
@@ -71,6 +99,7 @@ import argparse
 import datetime as dt
 import json
 import sys
+from pathlib import Path
 
 
 REQUIRED_FIELDS = ("name", "language", "source_repo")
@@ -103,6 +132,46 @@ def _iso_utc_now() -> str:
     return dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
+def probe_skf_version(skf_root: str | Path | None) -> str:
+    """The installed SKF's version: package.json `version`, else the VERSION file's first line, else "unknown"."""
+    if not skf_root:
+        return "unknown"
+    root = Path(skf_root)
+    try:
+        version = json.loads((root / "package.json").read_text(encoding="utf-8-sig")).get("version")
+        if isinstance(version, str) and version.strip():
+            return version.strip()
+    except (OSError, ValueError, AttributeError):
+        pass
+    try:
+        lines = (root / "VERSION").read_text(encoding="utf-8-sig").strip().splitlines()
+        if lines and lines[0].strip():
+            return lines[0].strip()
+    except (OSError, UnicodeDecodeError):
+        pass
+    return "unknown"
+
+
+def merge_extractions(payload: dict, extractions: list[dict], skf_version: str | None = None) -> dict:
+    """The full renderer payload: the staged fields, then what the extraction files give."""
+    merged = dict(payload)
+
+    def first(key: str):
+        return next((e[key] for e in extractions if isinstance(e.get(key), str) and e[key].strip()), None)
+
+    if not isinstance(merged.get("exports"), list):
+        merged["exports"] = [x for e in extractions for x in (e.get("exports") or []) if isinstance(x, (dict, str))]
+    if not isinstance(merged.get("dependencies"), list):
+        deps = [d for e in extractions for d in (e.get("dependencies") or []) if isinstance(d, str)]
+        merged["dependencies"] = list(dict.fromkeys(deps))
+    for key, source in (("version", "version"), ("source_package", "package_name"), ("description", "description")):
+        if not merged.get(key):
+            merged[key] = first(source)
+    if not merged.get("skf_version") and skf_version is not None:
+        merged["skf_version"] = skf_version
+    return merged
+
+
 def render_metadata(payload: dict, *, now_fn=_iso_utc_now) -> dict:
     """Render the metadata.json envelope. Pass `now_fn` to inject a
     deterministic timestamp in tests.
@@ -161,30 +230,65 @@ def render_metadata(payload: dict, *, now_fn=_iso_utc_now) -> dict:
     return metadata
 
 
+def _read_object(path: str, flag: str) -> dict:
+    """A JSON object from a file; raises ValueError with the message to print."""
+    try:
+        data = json.loads(Path(path).read_text(encoding="utf-8-sig"))
+    except (OSError, UnicodeDecodeError) as e:
+        raise ValueError(f"cannot read {flag} {path}: {getattr(e, 'strerror', None) or e}") from e
+    except json.JSONDecodeError as e:
+        raise ValueError(f"{flag} {path} is not valid JSON: {e}") from e
+    if not isinstance(data, dict):
+        raise ValueError(f"{flag} {path} must hold a JSON object")
+    return data
+
+
 def main(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(
-        description="Render skf-quick-skill metadata.json from extracted state on stdin.",
+        description="Render skf-quick-skill metadata.json from staged fields and the extraction files "
+                    "(or from a whole payload on stdin).",
     )
-    parser.parse_args(argv)  # currently no flags; kept for forward compat
+    parser.add_argument("--input", help="the staged fields (metadata-input.json); without it, stdin")
+    parser.add_argument("--extraction", action="append", default=[],
+                        help="step 3's extraction output for one module (repeatable, parent first)")
+    parser.add_argument("--skf-root", help="the installed SKF module folder to read its version from")
+    parser.add_argument("--output", help="also write the rendered metadata.json here")
+    args = parser.parse_args(argv)
 
-    raw = sys.stdin.read()
-    if not raw.strip():
-        sys.stderr.write("error: no input on stdin (expected JSON payload)\n")
-        return 2
-    try:
-        payload = json.loads(raw)
-    except json.JSONDecodeError as e:
-        sys.stderr.write(f"error: stdin JSON parse error: {e}\n")
-        return 2
-    if not isinstance(payload, dict):
-        sys.stderr.write("error: stdin payload must be a JSON object\n")
-        return 2
+    if args.input is None:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            sys.stderr.write("error: no input on stdin (expected JSON payload)\n")
+            return 2
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError as e:
+            sys.stderr.write(f"error: stdin JSON parse error: {e}\n")
+            return 2
+        if not isinstance(payload, dict):
+            sys.stderr.write("error: stdin payload must be a JSON object\n")
+            return 2
+    else:
+        try:
+            payload = _read_object(args.input, "--input")
+            extractions = [_read_object(path, "--extraction") for path in args.extraction]
+        except ValueError as e:
+            sys.stderr.write(f"error: {e}\n")
+            return 2
+        payload = merge_extractions(payload, extractions, probe_skf_version(args.skf_root))
 
     result = render_metadata(payload)
     if "_error" in result:
         sys.stderr.write(f"error: {result['_error']}\n")
         return 1
-    print(json.dumps(result, indent=2))
+    text = json.dumps(result, indent=2)
+    if args.output:
+        try:
+            Path(args.output).write_text(text + "\n", encoding="utf-8")
+        except OSError as e:
+            sys.stderr.write(f"error: cannot write --output {args.output}: {e.strerror or e}\n")
+            return 2
+    print(text)
     return 0