bmad-module-skill-forge 1.4.1 → 1.5.1

package/src/shared/scripts/skf-disqualify-candidates.py

@@ -0,0 +1,576 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Disqualify Candidates — deterministic filter for skillable-unit boundaries.
+
+`identify-units.md` step 2 §D asks the LLM to evaluate each detected boundary
+against a fixed disqualification list (too-few-files, too-low-loc,
+generated-code, auto-generated-tag, etc.). The boundary checks are fully
+deterministic — file counts, line counts, path-substring matches against a
+known generated-code roster, header sentinel scans — and prior runs have
+shown LLMs miscount files, miss generated-code paths inside nested
+`node_modules/`, and forget to scan for `@generated`. This script collapses
+that work into one call.
+
+Canonical disqualification rules (kept in sync with
+`src/skf-analyze-source/references/unit-detection-heuristics.md`):
+
+  - too-few-files     : files_count < {MIN_FILES} (default 3)
+  - too-low-loc       : loc_total < {MIN_LOC} (default 100)
+  - generated-code    : any file path contains a known generated/vendor
+                         directory segment (node_modules/, vendor/, dist/,
+                         build/, __pycache__/, .next/, target/, .gradle/)
+  - auto-generated-tag: any file's first 10 lines contain a known
+                         "auto-generated" sentinel string (`@generated`,
+                         `// GENERATED CODE`, `# AUTOGENERATED`,
+                         `<!-- generated -->`); case-insensitive matching
+                         on the full sentinel phrases.
+
+Rules NOT enforced by this script (still LLM-judged in step 2 §D):
+  - pure-configuration
+  - test-only
+  - already-skilled (requires existing_skills cross-reference)
+
+LoC counting: per file, count lines with NON-empty content. A "blank line"
+is one whose stripped form is empty (whitespace-only lines count as blank).
+This matches the spec phrasing "lines with content (strip empty lines)".
+
+The check order matters because heuristics are reported as a single
+`reason`; the first match wins. Order is:
+  1. generated-code      (path-based, cheapest, often the dominant signal)
+  2. auto-generated-tag  (header scan)
+  3. too-few-files       (file count after the above)
+  4. too-low-loc         (loc after the above)
+
+Subcommand:
+  filter --boundaries <json-file-or--for-stdin> [--source-root <path>]
+                     [--min-files N] [--min-loc N]
+
+      Read a boundaries JSON of the shape:
+        [
+          {"name": "<unit-name>",
+           "path": "<rel-from-source-root>",
+           "files": ["<rel-path>", ...]},
+          ...
+        ]
+      and emit:
+        {
+          "kept":    [{"name": "...", "path": "...",
+                       "files_count": N, "loc_total": L}, ...],
+          "dropped": [{"name": "...",
+                       "reason": "<too-few-files|too-low-loc|generated-code|"
+                                 "auto-generated-tag>",
+                       "context": {"files_count": N, "loc_total": L,
+                                   "first_match": "..."}}, ...],
+          "stats":   {"kept": N, "dropped": N,
+                       "by_reason": {"<reason>": N, ...}}
+        }
+
+  --source-root defaults to the current working directory. File paths in
+  the `files[]` array are resolved against `<source-root>/<boundary-path>`
+  first (to match `path` from the earlier scan-project step), and falling
+  back to `<source-root>/<file-rel>` if that doesn't exist. Missing files
+  are treated as 0-line zero-byte files; the boundary is still subject to
+  count/loc thresholds.
+
+CLI examples:
+  uv run skf-disqualify-candidates.py filter --boundaries boundaries.json
+  cat boundaries.json | uv run skf-disqualify-candidates.py filter \\
+      --boundaries - --source-root /path/to/project
+
+Exit codes:
+  0  — operation succeeded (including: empty input → empty kept/dropped)
+  1  — user error (bad JSON, missing required keys, malformed entry)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+# --------------------------------------------------------------------------
+# Constants — disqualification rules (single source of truth)
+# --------------------------------------------------------------------------
+
+
+MIN_FILES = 3
+MIN_LOC = 100
+
+# Path segments that mark generated / vendored / build-output trees.
+# Trailing slash is significant — we match the segment as a directory.
+GENERATED_PATH_SEGMENTS = (
+    "node_modules/",
+    "vendor/",
+    "dist/",
+    "build/",
+    "__pycache__/",
+    ".next/",
+    "target/",
+    ".gradle/",
+)
+
+# Header-sentinel scan: case-insensitive substring match on each of the
+# first AUTO_GEN_HEADER_LINES of a file. The strings are spec-canonical;
+# we apply case-insensitive matching (compare to a lowercased line).
+AUTO_GEN_SENTINELS = (
+    "@generated",
+    "// generated code",
+    "# autogenerated",
+    "<!-- generated -->",
+)
+
+AUTO_GEN_HEADER_LINES = 10
+
+
+# Reason codes — exported as module-level constants so callers (and tests)
+# can reference them without string typos.
+REASON_TOO_FEW_FILES = "too-few-files"
+REASON_TOO_LOW_LOC = "too-low-loc"
+REASON_GENERATED_CODE = "generated-code"
+REASON_AUTO_GENERATED_TAG = "auto-generated-tag"
+
+ALL_REASONS = (
+    REASON_GENERATED_CODE,
+    REASON_AUTO_GENERATED_TAG,
+    REASON_TOO_FEW_FILES,
+    REASON_TOO_LOW_LOC,
+)
+
+
+# --------------------------------------------------------------------------
+# Boundary validation
+# --------------------------------------------------------------------------
+
+
+def validate_boundaries(boundaries: object) -> list[dict]:
+    """Validate the boundaries input is a list of {name, path, files} records.
+
+    Returns the list with each entry's `files` normalized to forward-slash
+    strings. Raises ValueError on any structural defect.
+    """
+    if not isinstance(boundaries, list):
+        raise ValueError(
+            f"boundaries input must be a JSON array; got {type(boundaries).__name__}"
+        )
+    normalized: list[dict] = []
+    for idx, entry in enumerate(boundaries):
+        if not isinstance(entry, dict):
+            raise ValueError(
+                f"boundary entry at index {idx} is not an object: {entry!r}"
+            )
+        name = entry.get("name")
+        if not isinstance(name, str) or not name:
+            raise ValueError(
+                f"boundary entry at index {idx} missing required `name` field"
+            )
+        path = entry.get("path")
+        if not isinstance(path, str):
+            raise ValueError(
+                f"boundary entry {name!r} missing required `path` field"
+            )
+        files = entry.get("files")
+        if not isinstance(files, list):
+            raise ValueError(
+                f"boundary entry {name!r} missing required `files` array"
+            )
+        norm_files: list[str] = []
+        for f_idx, f in enumerate(files):
+            if not isinstance(f, str):
+                raise ValueError(
+                    f"boundary {name!r} files[{f_idx}] is not a string: {f!r}"
+                )
+            norm_files.append(f.replace("\\", "/"))
+        normalized.append({
+            "name": name,
+            "path": path.replace("\\", "/"),
+            "files": norm_files,
+        })
+    return normalized
+
+
+# --------------------------------------------------------------------------
+# Path-based detection (generated-code)
+# --------------------------------------------------------------------------
+
+
+def find_generated_segment(file_path: str) -> str | None:
+    """Return the first generated-path segment that appears in `file_path`,
+    or None if none match.
+
+    The match is on the raw string with forward slashes. We compare against
+    `<segment>` at any position (start or interior); a `node_modules/` at
+    the root counts the same as one nested deeper.
+    """
+    norm = file_path.replace("\\", "/")
+    # accept matches at the very start (no leading slash needed) too —
+    # so `node_modules/foo.js` and `pkg/node_modules/foo.js` both hit.
+    bracketed = "/" + norm  # so segments can match at the head consistently
+    for seg in GENERATED_PATH_SEGMENTS:
+        if "/" + seg in bracketed:
+            return seg
+    return None
+
+
+# --------------------------------------------------------------------------
+# Header-sentinel scan (auto-generated-tag)
+# --------------------------------------------------------------------------
+
+
+_AUTO_GEN_SENTINELS_LC = tuple(s.lower() for s in AUTO_GEN_SENTINELS)
+
+
+def has_auto_generated_marker(file_abs: Path) -> str | None:
+    """Scan the first AUTO_GEN_HEADER_LINES lines of `file_abs` for any of
+    the AUTO_GEN_SENTINELS (case-insensitive substring match).
+
+    Returns the matched sentinel (lowercased) on first hit, or None.
+    Unreadable / non-UTF-8 files return None — header-sentinel detection
+    is opportunistic; binary blobs will simply not match.
+    """
+    try:
+        with file_abs.open("r", encoding="utf-8", errors="replace") as fh:
+            for i, raw_line in enumerate(fh):
+                if i >= AUTO_GEN_HEADER_LINES:
+                    break
+                lc = raw_line.lower()
+                for sentinel in _AUTO_GEN_SENTINELS_LC:
+                    if sentinel in lc:
+                        return sentinel
+    except OSError:
+        return None
+    return None
+
+
+# --------------------------------------------------------------------------
+# LoC counting
+# --------------------------------------------------------------------------
+
+
+def count_nonblank_lines(file_abs: Path) -> int:
+    """Count lines whose stripped form is non-empty. Whitespace-only lines
+    count as blank. Returns 0 for unreadable files.
+    """
+    try:
+        with file_abs.open("r", encoding="utf-8", errors="replace") as fh:
+            n = 0
+            for line in fh:
+                if line.strip():
+                    n += 1
+            return n
+    except OSError:
+        return 0
+
+
+# --------------------------------------------------------------------------
+# Per-boundary evaluation
+# --------------------------------------------------------------------------
+
+
+def _resolve_file(source_root: Path, boundary_path: str, file_rel: str) -> Path:
+    """Resolve a boundary's `files[]` entry to an absolute path.
+
+    Tries in order:
+      1. <source_root>/<file_rel>            (file_rel already source-root-relative)
+      2. <source_root>/<boundary_path>/<file_rel>  (file_rel boundary-relative)
+
+    The first existing path wins; otherwise returns the source-root option
+    so downstream code can decide what "missing" means.
+    """
+    candidate_a = source_root / file_rel
+    if candidate_a.is_file():
+        return candidate_a
+    candidate_b = source_root / boundary_path / file_rel
+    if candidate_b.is_file():
+        return candidate_b
+    # neither exists — return the source-root form for missing-file accounting
+    return candidate_a
+
+
+def evaluate_boundary(
+    boundary: dict,
+    *,
+    source_root: Path,
+    min_files: int = MIN_FILES,
+    min_loc: int = MIN_LOC,
+) -> dict:
+    """Evaluate a single boundary against all disqualification rules.
+
+    Returns a record:
+      - kept:    {"name", "path", "files_count", "loc_total"}
+      - dropped: {"name", "reason", "context": {...}}
+
+    Check order:
+      1. generated-code     (path segment match)
+      2. auto-generated-tag (header sentinel scan)
+      3. too-few-files      (count < min_files)
+      4. too-low-loc        (sum < min_loc)
+    """
+    name = boundary["name"]
+    path = boundary["path"]
+    files = boundary["files"]
+    files_count = len(files)
+
+    # 1. generated-code — path-substring match (cheapest signal)
+    for f in files:
+        seg = find_generated_segment(f)
+        if seg:
+            return {
+                "kind": "dropped",
+                "record": {
+                    "name": name,
+                    "reason": REASON_GENERATED_CODE,
+                    "context": {
+                        "files_count": files_count,
+                        "first_match": f,
+                        "matched_segment": seg,
+                    },
+                },
+            }
+
+    # 2. auto-generated-tag — header sentinel scan
+    for f in files:
+        abs_path = _resolve_file(source_root, path, f)
+        sentinel = has_auto_generated_marker(abs_path)
+        if sentinel:
+            return {
+                "kind": "dropped",
+                "record": {
+                    "name": name,
+                    "reason": REASON_AUTO_GENERATED_TAG,
+                    "context": {
+                        "files_count": files_count,
+                        "first_match": f,
+                        "matched_sentinel": sentinel,
+                    },
+                },
+            }
+
+    # Compute loc_total for the remaining checks (and for kept records).
+    loc_total = 0
+    for f in files:
+        abs_path = _resolve_file(source_root, path, f)
+        loc_total += count_nonblank_lines(abs_path)
+
+    # 3. too-few-files
+    if files_count < min_files:
+        return {
+            "kind": "dropped",
+            "record": {
+                "name": name,
+                "reason": REASON_TOO_FEW_FILES,
+                "context": {
+                    "files_count": files_count,
+                    "loc_total": loc_total,
+                    "threshold": min_files,
+                },
+            },
+        }
+
+    # 4. too-low-loc
+    if loc_total < min_loc:
+        return {
+            "kind": "dropped",
+            "record": {
+                "name": name,
+                "reason": REASON_TOO_LOW_LOC,
+                "context": {
+                    "files_count": files_count,
+                    "loc_total": loc_total,
+                    "threshold": min_loc,
+                },
+            },
+        }
+
+    return {
+        "kind": "kept",
+        "record": {
+            "name": name,
+            "path": path,
+            "files_count": files_count,
+            "loc_total": loc_total,
+        },
+    }
+
+
+# --------------------------------------------------------------------------
+# Top-level filter
+# --------------------------------------------------------------------------
+
+
+def filter_boundaries(
+    boundaries: list[dict],
+    *,
+    source_root: Path,
+    min_files: int = MIN_FILES,
+    min_loc: int = MIN_LOC,
+) -> dict:
+    """Run evaluate_boundary on each entry; aggregate kept/dropped/stats."""
+    kept: list[dict] = []
+    dropped: list[dict] = []
+    by_reason: dict[str, int] = {r: 0 for r in ALL_REASONS}
+
+    for b in boundaries:
+        result = evaluate_boundary(
+            b,
+            source_root=source_root,
+            min_files=min_files,
+            min_loc=min_loc,
+        )
+        if result["kind"] == "kept":
+            kept.append(result["record"])
+        else:
+            dropped.append(result["record"])
+            by_reason[result["record"]["reason"]] += 1
+
+    # prune zero-count reasons from by_reason — keeps the report tight
+    by_reason_compact = {r: n for r, n in by_reason.items() if n > 0}
+
+    return {
+        "kept": kept,
+        "dropped": dropped,
+        "stats": {
+            "kept": len(kept),
+            "dropped": len(dropped),
+            "by_reason": by_reason_compact,
+        },
+    }
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+
+def _read_boundaries_source(source: str) -> object:
+    """Read boundaries JSON from a file path or stdin (if source == '-')."""
+    if source == "-":
+        try:
+            text = sys.stdin.read()
+        except OSError as exc:
+            raise ValueError(
+                f"failed to read boundaries JSON from stdin: {exc}"
+            ) from exc
+    else:
+        path = Path(source)
+        if not path.is_file():
+            raise ValueError(f"boundaries file not found: {path}")
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ValueError(
+                f"failed to read boundaries file {path}: {exc}"
+            ) from exc
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"malformed JSON in boundaries input: {exc}") from exc
+
+
+def _cmd_filter(args: argparse.Namespace) -> int:
+    try:
+        raw = _read_boundaries_source(args.boundaries)
+        boundaries = validate_boundaries(raw)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    source_root = Path(args.source_root or ".").resolve()
+    if not source_root.is_dir():
+        print(
+            f"error: source-root not a directory: {source_root}", file=sys.stderr
+        )
+        return 1
+
+    if args.min_files < 0:
+        print(
+            f"error: --min-files must be >= 0; got {args.min_files}",
+            file=sys.stderr,
+        )
+        return 1
+    if args.min_loc < 0:
+        print(
+            f"error: --min-loc must be >= 0; got {args.min_loc}",
+            file=sys.stderr,
+        )
+        return 1
+
+    result = filter_boundaries(
+        boundaries,
+        source_root=source_root,
+        min_files=args.min_files,
+        min_loc=args.min_loc,
+    )
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skf-disqualify-candidates",
+        description=(
+            "Filter detected boundaries against the unit-detection "
+            "disqualification list (too-few-files, too-low-loc, "
+            "generated-code, auto-generated-tag)."
+        ),
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_filter = sub.add_parser(
+        "filter",
+        help="emit kept/dropped/stats partition as JSON",
+    )
+    p_filter.add_argument(
+        "--boundaries",
+        required=True,
+        help=(
+            "path to boundaries JSON, or '-' to read from stdin. "
+            "Shape: [{\"name\": \"<unit>\", \"path\": \"<rel>\", "
+            "\"files\": [\"<rel>\", ...]}, ...]"
+        ),
+    )
+    p_filter.add_argument(
+        "--source-root",
+        default=None,
+        help=(
+            "project root for resolving file paths in `files[]` "
+            "(default: current working directory). Each file is resolved as "
+            "<source-root>/<file-rel> first, falling back to "
+            "<source-root>/<boundary-path>/<file-rel>."
+        ),
+    )
+    p_filter.add_argument(
+        "--min-files",
+        type=int,
+        default=MIN_FILES,
+        help=(
+            f"minimum files for too-few-files (default {MIN_FILES}; "
+            "matches unit-detection-heuristics.md)"
+        ),
+    )
+    p_filter.add_argument(
+        "--min-loc",
+        type=int,
+        default=MIN_LOC,
+        help=(
+            f"minimum non-blank LoC for too-low-loc (default {MIN_LOC}; "
+            "matches unit-detection-heuristics.md)"
+        ),
+    )
+    p_filter.set_defaults(func=_cmd_filter)
+
+    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-emit-brief-result-envelope.py

@@ -4,8 +4,8 @@
 # ///
 """SKF Emit Brief Result Envelope — Schema-locked headless output for skf-brief-skill.
 
-Replaces the prose-driven envelope assembly in `src/skf-brief-skill/steps-c/
-step-05-write-brief.md` §4b with one Python invocation. The envelope contract
+Replaces the prose-driven envelope assembly in `src/skf-brief-skill/references/
+write-brief.md` §4b with one Python invocation. The envelope contract
 (SKF_BRIEF_RESULT_JSON) is documented in src/skf-brief-skill/SKILL.md Result
 Contract section.
 
@@ -239,7 +239,7 @@ def main() -> int:
         "--target",
         choices=["stdout", "stderr"],
         default="stdout",
-        help="Output stream for the prefixed envelope line. step-05 §4b uses stdout on success and stderr on HARD HALT.",
+        help="Output stream for the prefixed envelope line. step 5 §4b uses stdout on success and stderr on HARD HALT.",
     )
 
     sub.add_parser("validate", help="Read envelope JSON on stdin, exit 0 if schema-valid")