bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-test-skill/scripts/validate-inventory.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Deterministic schema validation of the §1 subagent inventory JSON.
+
+Structural validator for the SKF test-skill coverage step (coverage-check.md
+§1a "Schema validation" block). test-skill is a quality gate, so it must not
+trust subagent output blindly: before any downstream step consumes the
+documented inventory, the shape is validated. That validation is pure
+structural checking — strip wrapping fences, parse JSON, assert required keys
+and types, assert each export entry is a dict with a non-empty `name` and a
+`kind` drawn from a fixed enum, and assert each cross-check mismatch carries its
+five fields — with exactly one correct pass/fail per input and no
+interpretation of meaning. It is therefore script work, not prompt work; the
+prompt reads this verdict and owns the HALT decision plus the separate
+grep ground-truth spot-check.
+
+Distinct from reconcile-coverage.py (coverage numerator arithmetic) and
+compute-score.py (weight tables): this script only validates the *shape* of the
+subagent inventory and, on success, echoes the fence-stripped parsed inventory
+back so the prompt consumes it directly instead of re-parsing the raw response.
+
+CLI usage (mirrors reconcile-coverage.py):
+  uv run validate-inventory.py '<raw response>'                 # positional
+  uv run validate-inventory.py --json-input '<raw response>'    # explicit flag
+  echo '<raw response>' | uv run validate-inventory.py --stdin  # piped input
+
+Input: the subagent's RAW response text (JSON, optionally wrapped in a markdown
+code fence — a leading line of three backticks with an optional language tag and
+a trailing line of three backticks are stripped before parsing).
+
+Output (stdout, one object):
+  {
+    "valid": <bool>,             # true only when parse + every schema check pass
+    "violations": [<str>, ...],  # human-readable failures; empty when valid
+    "rejectedCount": <int>,      # count of malformed exports[] entries
+    "exportsCount": <int>,       # len(exports) when parsed; 0 otherwise
+    "inventory": {...} | null    # fence-stripped parsed inventory when valid; null otherwise
+  }
+
+Exit codes:
+  0  — inventory valid
+  1  — no input provided (usage error)
+  2  — inventory invalid (parse failure or schema violation; result JSON emitted)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+
+# Fixed enum for exports[].kind — the constructs SKF documents across languages
+# and skill types: JS/TS (function/class/type/constant/hook/interface/method),
+# Rust public-API items (struct/enum/trait/macro, alongside the shared
+# type/constant/function), and stack-composition scaffolds (adapter). Mirrors the
+# enum documented in coverage-check.md §1a.
+VALID_KINDS = (
+    "function",
+    "class",
+    "type",
+    "constant",
+    "hook",
+    "interface",
+    "method",
+    "struct",
+    "enum",
+    "trait",
+    "macro",
+    "adapter",
+)
+
+REQUIRED_MISMATCH_FIELDS = (
+    "export",
+    "skill_md_line",
+    "reference_file",
+    "reference_line",
+    "issue",
+)
+
+_FENCE_OPEN = re.compile(r"^```[A-Za-z0-9_-]*$")
+_FENCE_CLOSE = re.compile(r"^```$")
+
+
+def strip_fences(text):
+    """Remove a wrapping markdown code fence, matching coverage-check.md §1a step 1.
+
+    When the first non-empty line is three backticks (optionally with a language
+    tag) and the last non-empty line is three backticks, drop those two lines.
+    Otherwise return the text unchanged.
+    """
+    lines = text.split("\n")
+    non_empty_idx = [i for i, ln in enumerate(lines) if ln.strip()]
+    if len(non_empty_idx) < 2:
+        return text
+    first, last = non_empty_idx[0], non_empty_idx[-1]
+    if _FENCE_OPEN.match(lines[first].strip()) and _FENCE_CLOSE.match(lines[last].strip()):
+        kept = [ln for i, ln in enumerate(lines) if i != first and i != last]
+        return "\n".join(kept)
+    return text
+
+
+def validate_inventory(raw):
+    """Pure structural validation of the subagent inventory response.
+
+    `raw` is the raw response text. Returns the result dict documented in the
+    module docstring. Deterministic: identical input yields an identical verdict.
+    """
+    violations = []
+    inner = strip_fences(raw)
+    try:
+        data = json.loads(inner)
+    except json.JSONDecodeError as exc:
+        return {
+            "valid": False,
+            "violations": [f"subagent response not valid JSON: {exc.msg}"],
+            "rejectedCount": 0,
+            "exportsCount": 0,
+            "inventory": None,
+        }
+
+    if not isinstance(data, dict):
+        return {
+            "valid": False,
+            "violations": ["subagent response is not a JSON object"],
+            "rejectedCount": 0,
+            "exportsCount": 0,
+            "inventory": None,
+        }
+
+    exports = data.get("exports")
+    if not isinstance(exports, list):
+        violations.append(
+            "missing/typo: `exports` must be present and a list"
+        )
+        exports = []
+
+    cross = data.get("cross_check_mismatches")
+    if not isinstance(cross, list):
+        violations.append(
+            "missing/typo: `cross_check_mismatches` must be present and a list (may be empty)"
+        )
+        cross = []
+
+    # Per-entry export validation — count rejections.
+    rejected = 0
+    for idx, entry in enumerate(exports):
+        if not isinstance(entry, dict):
+            rejected += 1
+            continue
+        name = entry.get("name")
+        kind = entry.get("kind")
+        if not (isinstance(name, str) and name):
+            rejected += 1
+            continue
+        if kind not in VALID_KINDS:
+            rejected += 1
+            continue
+    if rejected > 0:
+        subject = "entry does" if rejected == 1 else "entries do"
+        violations.append(
+            f"{rejected} exports[] {subject} not match schema "
+            f"(each needs a non-empty string `name` and a `kind` in "
+            f"{{{', '.join(VALID_KINDS)}}})"
+        )
+
+    # Non-empty cross-check mismatch entries must carry all five fields.
+    for idx, entry in enumerate(cross):
+        if not isinstance(entry, dict):
+            violations.append(f"cross_check_mismatches[{idx}] is not an object")
+            continue
+        missing = [f for f in REQUIRED_MISMATCH_FIELDS if f not in entry]
+        if missing:
+            violations.append(
+                f"cross_check_mismatches[{idx}] missing field(s): {', '.join(missing)}"
+            )
+
+    valid = not violations
+    return {
+        "valid": valid,
+        "violations": violations,
+        "rejectedCount": rejected,
+        "exportsCount": len(exports),
+        "inventory": data if valid else None,
+    }
+
+
+# --- CLI --------------------------------------------------------------------
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="validate-inventory",
+        description=(
+            "Deterministic schema validation of the §1 subagent inventory JSON "
+            "(coverage-check.md §1a). Strips wrapping fences, parses, and asserts "
+            "the required-keys/types/enum/mismatch-field contract, returning "
+            "{valid, violations, rejectedCount, exportsCount, inventory}."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    src = parser.add_mutually_exclusive_group()
+    src.add_argument(
+        "raw_input",
+        nargs="?",
+        help="Raw subagent response as a positional argument.",
+    )
+    src.add_argument(
+        "--json-input",
+        dest="raw_input_flag",
+        help="Raw subagent response passed via flag (overrides positional).",
+    )
+    src.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read the raw subagent response from stdin.",
+    )
+    return parser
+
+
+def _resolve_input(args):
+    if args.stdin:
+        return sys.stdin.read()
+    if args.raw_input_flag is not None:
+        return args.raw_input_flag
+    if args.raw_input is not None:
+        return args.raw_input
+    return ""
+
+
+def main(argv=None):
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    raw = _resolve_input(args)
+    if not raw.strip():
+        parser.print_usage(file=sys.stderr)
+        print(
+            "error: no input provided (positional arg, --json-input, or --stdin)",
+            file=sys.stderr,
+        )
+        return 1
+
+    result = validate_inventory(raw)
+    print(json.dumps(result, indent=2))
+    return 0 if result["valid"] else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-test-skill/scripts/verify-declared-numerator.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""Deterministic numerator ground-truth verifier.
+
+Grep-and-count helper for the SKF test-skill workflow (coverage-check.md §4b
+"Numerator ground-truth"). It fires only on the inflation signature
+(`stats.exports_documented == effective_denominator` exactly): the numerator
+equals the denominator, the tell of a documented count padded to force 100%
+coverage. On that signature the declared count is not trusted — every declared
+export name is greped against the skill's documentation surface and only the
+names that actually appear count toward coverage.
+
+Distinct from reconcile-coverage.py (whose scalar/stack branches grep the §1
+inventory names and return only a residual missing *count*): this script greps
+the full declared metadata/provenance set and enumerates the *absent* names so
+§4b can list them in a High-severity gap. Both scripts share the same grep
+semantics (SKILL.md ∪ sorted references/*.md, UTF-8, case-sensitive substring
+containment — mirroring `grep "{name}"`) so their numerators agree.
+
+Input schema (one JSON object):
+  {
+    "declaredNames": ["foo", "Bar::baz", ...],  # metadata.exports[] / provenance declared set
+    "skillPackagePath": "/path/to/skill"        # SKILL.md ∪ references/*.md
+  }
+
+Output (stdout, one object):
+  {
+    "declared":  <int>,           # de-duplicated declared name count
+    "verified":  <int>,           # declared names present in the doc surface
+    "present":   [names],         # sorted
+    "absent":    [names],         # sorted (declared − verified) — the gap list
+    "inflated":  <bool>           # verified < declared (numerator was padded)
+  }
+  or {"error": ..., "code": "INVALID_INPUT"} on a schema violation.
+
+`verified` is the numerator §4b uses for Export Coverage (it overrides the
+declared count when `inflated` is true).
+
+CLI usage (mirrors reconcile-coverage.py):
+  uv run verify-declared-numerator.py '<JSON>'                  # positional
+  uv run verify-declared-numerator.py --json-input '<JSON>'     # explicit flag
+  cat input.json | uv run verify-declared-numerator.py --stdin  # piped input
+
+Exit codes:
+  0  — verification emitted successfully
+  1  — no input / input could not be parsed as JSON
+  2  — input parsed but schema/semantics invalid (error object emitted as JSON)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def make_error(message):
+    return {"error": message, "code": "INVALID_INPUT"}
+
+
+def load_doc_text(skill_package_path):
+    """Concatenate SKILL.md ∪ references/*.md text for name-presence grepping.
+
+    Deterministic: references are read in sorted order. Reads as UTF-8 so
+    non-ASCII exports do not mojibake on Windows (cp1252 default). Mirrors
+    reconcile-coverage.py.load_doc_text so the two numerators agree.
+    """
+    root = Path(skill_package_path)
+    parts = []
+    skill_md = root / "SKILL.md"
+    if skill_md.is_file():
+        parts.append(skill_md.read_text(encoding="utf-8"))
+    refs_dir = root / "references"
+    if refs_dir.is_dir():
+        for ref in sorted(refs_dir.glob("*.md")):
+            parts.append(ref.read_text(encoding="utf-8"))
+    return "\n".join(parts)
+
+
+def _validate(inp):
+    if inp is None or not isinstance(inp, dict):
+        return "Input must be a JSON object"
+    names = inp.get("declaredNames")
+    if not isinstance(names, list) or not names:
+        return "declaredNames must be a non-empty list of strings"
+    if not inp.get("skillPackagePath"):
+        return "skillPackagePath is required to grep SKILL.md ∪ references"
+    return None
+
+
+def verify(inp, doc_text=None):
+    """Pure verification. `doc_text` may be injected (tests); else loaded from disk."""
+    err = _validate(inp)
+    if err:
+        return make_error(err)
+
+    declared_set = sorted({n for n in inp["declaredNames"] if isinstance(n, str) and n})
+    if doc_text is None:
+        doc_text = load_doc_text(inp["skillPackagePath"])
+
+    present = sorted(n for n in declared_set if n in doc_text)
+    absent = sorted(n for n in declared_set if n not in doc_text)
+
+    return {
+        "declared": len(declared_set),
+        "verified": len(present),
+        "present": present,
+        "absent": absent,
+        "inflated": len(present) < len(declared_set),
+    }
+
+
+# --- CLI --------------------------------------------------------------------
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="verify-declared-numerator",
+        description=(
+            "Deterministic numerator ground-truth verifier (coverage-check.md "
+            "§4b). Greps the full declared export set against SKILL.md ∪ "
+            "references/*.md and enumerates the present/absent names so a padded "
+            "numerator is caught and the verified count replaces it."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Example:\n"
+            "  uv run verify-declared-numerator.py "
+            "'{\"declaredNames\":[\"foo\",\"bar\"],"
+            "\"skillPackagePath\":\"/path/to/skill\"}'"
+        ),
+    )
+    src = parser.add_mutually_exclusive_group()
+    src.add_argument(
+        "json_input",
+        nargs="?",
+        help="JSON object as a positional argument (single-quote it on the shell).",
+    )
+    src.add_argument(
+        "--json-input",
+        dest="json_input_flag",
+        help="JSON object passed via flag (overrides positional).",
+    )
+    src.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read the JSON object from stdin.",
+    )
+    return parser
+
+
+def _resolve_input(args):
+    if args.stdin:
+        return sys.stdin.read()
+    if args.json_input_flag is not None:
+        return args.json_input_flag
+    if args.json_input is not None:
+        return args.json_input
+    return ""
+
+
+def main(argv=None):
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    raw = _resolve_input(args)
+    if not raw.strip():
+        parser.print_usage(file=sys.stderr)
+        print(
+            "error: no input provided (positional arg, --json-input, or --stdin)",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        print(json.dumps(make_error(f"Invalid JSON: {exc.msg}"), indent=2))
+        return 1
+
+    result = verify(data)
+    print(json.dumps(result, indent=2))
+    if isinstance(result, dict) and result.get("code") == "INVALID_INPUT":
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-update-skill/SKILL.md

@@ -12,6 +12,7 @@ Surgically updates existing skills when source code changes, preserving all [MAN
 ## Conventions
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root — stage files reference `knowledge/version-paths.md` and `knowledge/tool-resolution.md`, and the terminal step chains to `shared/health-check.md`.
 - `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
 - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
 - `{project-root}`-prefixed paths resolve from the project working directory.
@@ -50,11 +51,11 @@ These rules apply to every step in this workflow:
 | Aspect | Detail |
 |--------|--------|
 | **Inputs** | skill_name [required] |
-| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--from-test-report` (gap-driven mode); `--allow-workspace-drift` (gap-driven only — bypass §0.a pinning guard); `--detect-only` (run detect-changes only, exit before re-extract; envelope `status="detect-only"`); `--dry-run` (run detect-changes + re-extract, exit before merge/write; envelope `status="dry-run"` describes what would change). If both `--detect-only` and `--dry-run` are passed, `--detect-only` wins. |
+| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--from-test-report` (gap-driven mode); `--allow-workspace-drift` (gap-driven only — bypass §0.a pinning guard); `--allow-degraded` (headless only — pre-authorize the lossy degraded full re-extraction when the provenance map is missing, instead of halting `blocked`; init.md §4); `--detect-only` (run detect-changes only, exit before re-extract; envelope `status="detect-only"`); `--dry-run` (run detect-changes + re-extract, exit before merge/write; envelope `status="dry-run"` describes what would change). If both `--detect-only` and `--dry-run` are passed, `--detect-only` wins. |
 | **Gates** | step 1: Confirm Gate [C] | step 4: Confirm Gate [C if clean merge, HALT if conflicts] |
-| **Outputs** | Updated SKILL.md, updated provenance-map.json, evidence-report.md (none when `--detect-only` or `--dry-run` is set — those modes are read-only inspection paths) |
-| **Concurrency** | Two simultaneous real-update runs against the same skill would corrupt provenance. init.md §1b acquires a PID-file lock at `{forge_data_folder}/{skill_name}/.skf-update.lock` before any artifact read; live-PID collisions halt with `status: "halted-for-concurrent-run"`. Stale locks (dead PID) are cleared silently with a warning. The lock is released by the terminal health-check step (step 8) and by every documented halt path. Read-only modes (`--detect-only`, `--dry-run`) skip the lock entirely — they're safe alongside a concurrent real update. |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Each auto-resolved gate appends a `{gate, default_action, taken_action, reason, evidence?}` entry to `headless_decisions[]`, surfaced in step 7's `SKF_UPDATE_RESULT_JSON` envelope so non-interactive runs can be audited post-hoc. Pipeline branches on the envelope's top-level `status` field (`success`, `no-changes`, `detect-only`, `dry-run`, or one of the documented `halted-for-*` codes). The first four are successful exits — pipelines treating non-success as failure must include them in the success set. Schema: `src/shared/scripts/schemas/skf-update-result-envelope.v1.json`. |
+| **Outputs** | Updated SKILL.md, metadata.json, provenance-map.json, evidence-report.md (none when `--detect-only` or `--dry-run` is set — those modes are read-only inspection paths) |
+| **Concurrency** | Two simultaneous real-update runs against the same skill would corrupt provenance. init.md §1b acquires a PID-file lock at `{forge_data_folder}/{skill_name}/.skf-update.lock` before any artifact read; live-PID collisions halt with `status: "halted-for-concurrent-run"`. Stale locks (dead PID) are cleared silently with a warning. The lock is released by the terminal health-check step (step 8) on the normal path and by the two init-stage headless halts (§4/§6); mid-workflow halts leave it for the next run's stale-lock self-heal (see init.md §1b Release contract). Read-only modes (`--detect-only`, `--dry-run`) skip the lock entirely — they're safe alongside a concurrent real update. |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Each auto-resolved gate appends a `{gate, default_action, taken_action, reason, evidence?}` entry to `headless_decisions[]`, surfaced in step 7's `SKF_UPDATE_RESULT_JSON` envelope so non-interactive runs can be audited post-hoc. A HALT reached in headless mode emits its own `SKF_UPDATE_RESULT_JSON` at the halt site (the site's `status` code plus an `error: {phase, path?, reason}` object) and exits — halts do not fall through to step 7. Pipeline branches on the envelope's top-level `status` field (`success`, `no-changes`, `detect-only`, `dry-run`, or one of the documented `halted-for-*`/`blocked` codes). The first four are successful exits — pipelines treating non-success as failure must include them in the success set. The status enum is defined once in `src/shared/scripts/schemas/skf-update-result-envelope.v1.json`. |
 
 ## On Activation
 
@@ -64,4 +65,15 @@ These rules apply to every step in this workflow:
 
 2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
 
-3. Load, read the full file, and then execute `references/init.md` to begin the workflow.
+3. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   This merges the three layers per `bmad-customize` rules (scalars override, arrays append): `{skill-root}/customize.toml` (bundled defaults), `_bmad/custom/<skill-name>.toml` under `{project-root}` (team overrides), and `_bmad/custom/<skill-name>.user.toml` under `{project-root}` (personal overrides). If the script is missing or fails, read `{skill-root}/customize.toml` directly.
+
+   Apply the resolved values so no surface is a silent no-op: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (entries prefixed `file:` are paths or globs whose contents load as facts — the bundled default loads any `project-context.md` under `{project-root}`); resolve `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string, and stash it in workflow context (`references/report.md` §5b invokes it after the result contract is written; empty string = the hook is a no-op). After activation completes, execute each entry in `workflow.activation_steps_append` in order before `init.md` runs.
+
+4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-update-skill/customize.toml

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-update-skill.
+# Team overrides:     _bmad/custom/skf-update-skill.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-update-skill.user.toml (under {project-root})
 
 [workflow]
 
@@ -34,11 +36,14 @@ persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
-# --- Optional gate thresholds ---
+# Pipeline-integration hook invoked after report.md §5b writes the result
+# contract (the per-run record plus update-skill-result-latest.json). The
+# command is called as:
+#   <on_complete> --result-path=<{forge_version}/update-skill-result-latest.json>
+# Useful for Slack notifications, dashboard ingest, CI hooks, or chaining a
+# downstream skill (audit, export, test). Failures are logged to the run's
+# warnings[] but never fail the workflow.
 #
-# Override the default thresholds used by detect-changes and merge. Empty
-# string or commented = use the bundled default (50% deletion ratio,
-# 80% rename similarity).
+# Empty string = no-op (default).
 
-deletion_ratio_threshold = ""
-rename_similarity_threshold = ""
+on_complete = ""