bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/shared/scripts/skf-validate-brief-inputs.py

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.9"
+# requires-python = ">=3.11"
 # dependencies = []
 # ///
 """SKF Validate Brief Inputs — pre-pass validation for brief-skill headless invocation.
@@ -12,6 +12,14 @@ or step 5.
 CLI:
   uv run skf-validate-brief-inputs.py --json '{...}'
   echo '{...}' | uv run skf-validate-brief-inputs.py
+  echo '{"target_version": "18"}' | uv run skf-validate-brief-inputs.py --only target_version
+
+Field-only mode (--only FIELD, repeatable): checks only the named fields, each
+as the full check would, and skips every other field's check; the required
+target_repo and skill_name checks apply only when one of them is named.
+`normalized` holds only the named fields that were given. The interactive
+step 1 checks a typed or pre-filled `target_version` this way, with the same
+SEMVER_RE as a headless argument.
 
 Input (JSON object on stdin or via --json):
   Required (derive route — deriving a new brief from a repo/docs target):
@@ -39,8 +47,11 @@ Input (JSON object on stdin or via --json):
   Optional with format constraints:
     target_version — loose semver string (matches 1.2.3, 1.2.3-rc.1, 1.2.3+build.5)
 
-  Conditional:
-    doc_urls — required when source_type == "docs-only"
+  Conditional (derive route only):
+    doc_urls: required when source_type == "docs-only"
+    include:  required when scope_type == "reference-app": no headless
+              boundary default covers a reference app's pattern surface, so
+              the run stops here instead of after step 2 reads the target
 
   Free-text / pass-through:
     scope_hint, language_hint, intent, include, exclude, force
@@ -88,8 +99,8 @@ KNOWN_FIELDS = {
     "exclude",
     "force",
 }
-# `preset` is intentionally NOT in KNOWN_FIELDS — it is consumed at the step 1 §8 GATE
-# (the LLM merges the named preset YAML into the args dict and drops the `preset` key
+# `preset` is intentionally NOT in KNOWN_FIELDS: it is consumed by the headless input gate
+# (headless-args.md: the LLM merges the named preset YAML into the args dict and drops the `preset` key
 # before calling the validator). If the key leaks through, the validator's existing
 # unknown-field handling emits `"unrecognized field 'preset' — passed through unchanged"`
 # in `warnings[]` so the missed drop is debuggable rather than silent.
@@ -113,6 +124,10 @@ KEBAB_RE = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
 SEMVER_RE = re.compile(
     r"^v?\d+\.\d+\.\d+([.\-+][0-9A-Za-z][0-9A-Za-z.\-+]*)?$"
 )
+# A pin that stops short of X.Y.Z (`react@18`, `django==4.2`, `repo@v2`), as
+# parse-target hands it back: the error names what is missing.
+PARTIAL_PIN_RE = re.compile(r"^v?\d+(\.\d+)?$")
+FULL_FORM = "write the full X.Y.Z (for example 1.2.3, v1.2.3, 1.2.3-rc.1 or 1.2.3+build.5)"
 URL_RE = re.compile(r"^https?://", re.IGNORECASE)
 
 
@@ -120,6 +135,24 @@ def _err(field: str, message: str) -> dict[str, str]:
     return {"field": field, "message": message}
 
 
+def _version_error(value: str) -> str:
+    partial = PARTIAL_PIN_RE.match(value)
+    if partial:
+        kind = "a major and minor version" if partial.group(1) else "a major version"
+        return f"target_version {value!r} is {kind} only: {FULL_FORM}"
+    return f"target_version {value!r} does not look like semver: {FULL_FORM}"
+
+
+def _halt_reason(errors: list[dict[str, str]]) -> str | None:
+    if not errors:
+        return None
+    missing_required = any(
+        e["message"].startswith("missing required") or "is required" in e["message"]
+        for e in errors
+    )
+    return "input-missing" if missing_required else "input-invalid"
+
+
 def validate(inp: dict[str, Any]) -> dict[str, Any]:
     errors: list[dict[str, str]] = []
     warnings: list[dict[str, str]] = []
@@ -233,14 +266,7 @@ def validate(inp: dict[str, Any]) -> dict[str, Any]:
                 )
             )
         elif not SEMVER_RE.match(target_version):
-            errors.append(
-                _err(
-                    "target_version",
-                    f"target_version does not look like semver. Got: {target_version!r}. "
-                    f"Expected forms: 1.2.3, v1.2.3, 1.2.3-rc.1, 1.2.3+build.5. "
-                    f"Partial forms like '1' or '1.2' are not accepted — write the explicit triple.",
-                )
-            )
+            errors.append(_err("target_version", _version_error(target_version)))
 
     # docs-only requires doc_urls — derive route only. On the ratify route the
     # brief on disk is the source of truth for source_type/doc_urls, so a
@@ -252,6 +278,17 @@ def validate(inp: dict[str, Any]) -> dict[str, Any]:
             _err("doc_urls", "doc_urls is required when source_type is docs-only")
         )
 
+    # reference-app requires include, derive route only: only the caller knows the pattern
+    # surface, so step 3 has no headless boundary default for it (scope-definition.md §3).
+    if not ratify_route and scope_type == "reference-app" and not inp.get("include"):
+        errors.append(
+            _err(
+                "include",
+                "include is required when scope_type is reference-app: pass the files or "
+                "folders of the pattern surface as comma-separated globs",
+            )
+        )
+
     # target_repo shape (warning only — script doesn't HEAD-check). Skipped on
     # the ratify route, where target_repo is already flagged as ignored above —
     # a second "doesn't look like a URL" warning would just be noise.
@@ -279,10 +316,11 @@ def validate(inp: dict[str, Any]) -> dict[str, Any]:
     normalized: dict[str, Any] = dict(inp)
     normalized.setdefault("source_type", "source")
     # `source_authority` is intentionally NOT setdefault'd here for source-type targets:
-    # step 1 §3.3's headless detection branch runs `gh api user` and may resolve to
-    # `official` for repos owned by the authenticated user. Stamping a default at
-    # validator time would pre-empt the detection because step 1 §8 GATE treats the
-    # `normalized` object as the source of truth. Absence is the signal "run detection."
+    # the headless input gate's source-authority section (headless-args.md) runs
+    # `gh api user` and may resolve to `official` for repos owned by the authenticated
+    # user. Stamping a default at validator time would pre-empt the detection because
+    # the gate treats the `normalized` object as the source of truth. Absence is the
+    # signal "run detection."
     # The docs-only branch below still forces `community` since detection cannot apply.
     normalized.setdefault("scripts_intent", "detect")
     normalized.setdefault("assets_intent", "detect")
@@ -299,22 +337,27 @@ def validate(inp: dict[str, Any]) -> dict[str, Any]:
             )
         normalized["source_authority"] = "community"
 
-    # halt_reason classification
-    if errors:
-        missing_required = any(
-            e["message"].startswith("missing required") or "is required" in e["message"]
-            for e in errors
-        )
-        halt_reason = "input-missing" if missing_required else "input-invalid"
-    else:
-        halt_reason = None
-
     return {
         "valid": not errors,
         "errors": errors,
         "warnings": warnings,
         "normalized": normalized,
-        "halt_reason": halt_reason,
+        "halt_reason": _halt_reason(errors),
+    }
+
+
+def validate_fields(inp: dict[str, Any], fields: list[str]) -> dict[str, Any]:
+    """The verdict of validate() on the named fields alone: every finding on a
+    field not named is left out, the required target_repo and skill_name
+    checks included, so one value can be checked before the rest is known."""
+    full = validate(inp)
+    errors = [e for e in full["errors"] if e["field"] in fields]
+    return {
+        "valid": not errors,
+        "errors": errors,
+        "warnings": [w for w in full["warnings"] if w["field"] in fields],
+        "normalized": {k: v for k, v in full["normalized"].items() if k in fields and k in inp},
+        "halt_reason": _halt_reason(errors),
     }
 
 
@@ -324,6 +367,14 @@ def main() -> int:
         "--json",
         help="JSON object as a string. If omitted, the script reads JSON from stdin.",
     )
+    p.add_argument(
+        "--only",
+        action="append",
+        choices=sorted(KNOWN_FIELDS),
+        metavar="FIELD",
+        help=("Check only this field (repeatable); the required target_repo and skill_name "
+              "checks apply only to a named one."),
+    )
     args = p.parse_args()
 
     raw = args.json
@@ -344,11 +395,23 @@ def main() -> int:
         sys.stderr.write("skf-validate-brief-inputs: input must be a JSON object\n")
         return 2
 
-    result = validate(inp)
+    result = validate_fields(inp, args.only) if args.only else validate(inp)
     json.dump(result, sys.stdout, indent=2, sort_keys=True)
     sys.stdout.write("\n")
     return 0 if result["valid"] else 1
 
 
+def _force_utf8(*streams) -> None:
+    """Reconfigure stdin and the JSON streams to UTF-8 (a Windows console uses cp1252)."""
+    for stream in streams:
+        if hasattr(stream, "reconfigure"):
+            errors = getattr(stream, "errors", None)
+            if errors is None:
+                stream.reconfigure(encoding="utf-8")
+            else:
+                stream.reconfigure(encoding="utf-8", errors=errors)
+
+
 if __name__ == "__main__":
+    _force_utf8(sys.stdin, sys.stdout, sys.stderr)
     sys.exit(main())

package/src/shared/scripts/skf-validate-brief-schema.py

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # dependencies = ["pyyaml", "jsonschema>=4.0"]
 # ///
 """SKF Validate Brief Schema — schema check for a skill-brief.yaml on disk.
@@ -52,6 +52,7 @@ from __future__ import annotations
 
 import argparse
 import datetime
+import importlib.util
 import json
 import sys
 from pathlib import Path
@@ -62,6 +63,23 @@ from jsonschema import Draft202012Validator
 
 
 SCHEMA_PATH = Path(__file__).resolve().parent / "schemas" / "skill-brief.v1.json"
+RESOLVER_PATH = Path(__file__).resolve().parent / "skf-resolve-authoritative-files.py"
+
+
+def _load_resolver():
+    """skf-resolve-authoritative-files.py from this folder: its
+    parse_brief_yaml reads a brief's YAML, an SKF 1.x brief's trailing `---`
+    included. A missing file raises OSError, which skf-quick-batch.py
+    reports as a validator that cannot be loaded."""
+    spec = importlib.util.spec_from_file_location("skf_resolve_authoritative_files", RESOLVER_PATH)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load {RESOLVER_PATH.name} beside {Path(__file__).name}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+_RESOLVER = _load_resolver()
 
 
 # --------------------------------------------------------------------------
@@ -77,7 +95,7 @@ def load_schema() -> dict:
 def load_brief_text(text: str) -> tuple[dict | None, str | None]:
     """Parse YAML text. Returns (brief, error_message)."""
     try:
-        brief = yaml.safe_load(text)
+        brief = _RESOLVER.parse_brief_yaml(text)
     except yaml.YAMLError as exc:
         return None, f"Brief is not valid YAML: {exc}"
     if brief is None:
@@ -111,6 +129,9 @@ def _translate_jsonschema_error(err) -> dict:
 
     if validator == "required":
         missing = err.message.split("'")[1] if "'" in err.message else "(unknown)"
+        if err.absolute_path:
+            # A nested object's field (`scope.ui_variants[0].name`), not a top-level one.
+            missing = f"{field}.{missing}"
         return {
             "field": missing,
             "message": (