bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/shared/scripts/skf-preflight.py

@@ -0,0 +1,164 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pyyaml"]
+# ///
+"""SKF Preflight — Config and sidecar loader for all SKF skills.
+
+Loads config.yaml, validates sidecar_path, loads preferences.yaml and
+forge-tier.yaml, and outputs a unified JSON blob for step consumption.
+
+CLI: python3 skf-preflight.py <project-root>
+     python3 skf-preflight.py <project-root> --config-path <alt-config>
+
+Output: JSON to stdout with all resolved config variables and sidecar state.
+Exit 0 on success, exit 1 on hard-halt conditions (missing config, bad sidecar).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print(
+        json.dumps({"error": "PyYAML not installed. Run: pip install pyyaml", "code": "MISSING_DEPENDENCY"}),
+    )
+    sys.exit(1)
+
+
+def load_yaml_file(path):
+    """Load a YAML file, returning (data, None) or (None, error_string)."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+        return data or {}, None
+    except FileNotFoundError:
+        return None, f"File not found: {path}"
+    except yaml.YAMLError as e:
+        return None, f"YAML parse error in {path}: {e}"
+
+
+def run_preflight(project_root, config_path=None):
+    """Run preflight checks and return a result dict."""
+    project_root = Path(project_root).resolve()
+
+    # 1. Load config.yaml
+    if config_path:
+        cfg_path = Path(config_path)
+    else:
+        cfg_path = project_root / "_bmad" / "skf" / "config.yaml"
+
+    config, err = load_yaml_file(cfg_path)
+    if err:
+        return {
+            "status": "hard-halt",
+            "error": f"Cannot initialize. SKF config not found at {cfg_path}. Run the skf-setup skill to initialize your forge environment.",
+            "code": "CONFIG_MISSING",
+        }
+
+    # 2. Resolve config variables
+    resolved = {
+        "project_root": str(project_root),
+        "config_path": str(cfg_path),
+        "project_name": config.get("project_name", ""),
+        "output_folder": config.get("output_folder", ""),
+        "user_name": config.get("user_name", ""),
+        "communication_language": config.get("communication_language", "English"),
+        "document_output_language": config.get("document_output_language", "English"),
+        "sidecar_path": config.get("sidecar_path", ""),
+        "skills_output_folder": config.get("skills_output_folder", ""),
+        "forge_data_folder": config.get("forge_data_folder", ""),
+    }
+
+    # 3. Validate sidecar_path
+    sidecar_path = resolved["sidecar_path"]
+    if not sidecar_path or sidecar_path == "{sidecar_path}":
+        return {
+            "status": "hard-halt",
+            "error": (
+                "Cannot initialize. sidecar_path is not defined in your installed config.yaml. "
+                f"Add sidecar_path: {project_root}/_bmad/_memory/forger-sidecar to your project "
+                "config.yaml and retry. This is a known installer issue with prompt: false config variables."
+            ),
+            "code": "SIDECAR_UNDEFINED",
+            "config": resolved,
+        }
+
+    sidecar_dir = Path(sidecar_path)
+    if not sidecar_dir.is_absolute():
+        sidecar_dir = project_root / sidecar_path
+
+    if not sidecar_dir.is_dir():
+        return {
+            "status": "hard-halt",
+            "error": f"Sidecar directory not found: {sidecar_dir}. Run skf-setup to initialize.",
+            "code": "SIDECAR_MISSING",
+            "config": resolved,
+        }
+
+    resolved["sidecar_path_resolved"] = str(sidecar_dir)
+
+    # 4. Load sidecar files
+    sidecar = {}
+
+    prefs_path = sidecar_dir / "preferences.yaml"
+    prefs, prefs_err = load_yaml_file(prefs_path)
+    if prefs_err:
+        sidecar["preferences"] = None
+        sidecar["preferences_error"] = prefs_err
+    else:
+        sidecar["preferences"] = prefs
+
+    tier_path = sidecar_dir / "forge-tier.yaml"
+    tier, tier_err = load_yaml_file(tier_path)
+    if tier_err:
+        sidecar["forge_tier"] = None
+        sidecar["forge_tier_error"] = tier_err
+    else:
+        sidecar["forge_tier"] = tier
+
+    # 5. Derive convenience fields
+    tier_value = None
+    if tier:
+        tier_value = tier.get("tier")
+
+    compact_greeting = False
+    if prefs:
+        compact_greeting = prefs.get("compact_greeting", False) is True
+
+    tier_override = None
+    if prefs:
+        tier_override = prefs.get("tier_override")
+
+    return {
+        "status": "ok",
+        "config": resolved,
+        "sidecar": sidecar,
+        "derived": {
+            "tier": tier_override or tier_value,
+            "tier_source": "override" if tier_override else ("detected" if tier_value else None),
+            "compact_greeting": compact_greeting,
+            "is_first_run": tier_value is None,
+        },
+    }
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python3 skf-preflight.py <project-root> [--config-path <path>]", file=sys.stderr)
+        sys.exit(1)
+
+    proj_root = sys.argv[1]
+    cfg_path = None
+
+    if "--config-path" in sys.argv:
+        idx = sys.argv.index("--config-path")
+        if idx + 1 < len(sys.argv):
+            cfg_path = sys.argv[idx + 1]
+
+    result = run_preflight(proj_root, cfg_path)
+    print(json.dumps(result, indent=2))
+    sys.exit(1 if result["status"] == "hard-halt" else 0)

package/src/shared/scripts/skf-rebuild-managed-sections.py

@@ -0,0 +1,201 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Rebuild Managed Sections — Context file marker surgery.
+
+Reads a context file (CLAUDE.md/AGENTS.md/.cursorrules), finds the
+<!-- SKF:BEGIN --> / <!-- SKF:END --> markers, and replaces the managed
+section with new content. Preserves all content outside the markers.
+
+CLI: python3 skf-rebuild-managed-sections.py <context-file> <action> [args]
+
+Actions:
+  read          — Extract current managed section content
+  replace       — Replace managed section with content from stdin or --content
+  clear         — Remove managed section entirely (markers + content)
+  insert        — Insert managed section if not present (at end of file)
+  check         — Check if managed section exists, report status
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+BEGIN_MARKER_PREFIX = "<!-- SKF:BEGIN"
+END_MARKER = "<!-- SKF:END -->"
+MARKER_PATTERN = re.compile(
+    r"(<!-- SKF:BEGIN[^>]*-->)(.*?)(<!-- SKF:END -->)",
+    re.DOTALL,
+)
+
+
+def read_context_file(file_path):
+    """Read a context file. Returns (content, None) or (None, error)."""
+    try:
+        return Path(file_path).read_text(encoding="utf-8"), None
+    except FileNotFoundError:
+        return None, f"File not found: {file_path}"
+
+
+def find_managed_section(content):
+    """Find the managed section in content. Returns match or None."""
+    return MARKER_PATTERN.search(content)
+
+
+def cmd_check(file_path):
+    """Check if managed section exists."""
+    content, err = read_context_file(file_path)
+    if err:
+        return {"status": "error", "error": err}
+
+    has_begin = BEGIN_MARKER_PREFIX in content
+    has_end = END_MARKER in content
+    match = find_managed_section(content)
+
+    if match:
+        section_content = match.group(2)
+        return {
+            "status": "ok",
+            "has_managed_section": True,
+            "markers_valid": True,
+            "section_length": len(section_content.strip()),
+            "section_line_count": len(section_content.strip().split("\n")) if section_content.strip() else 0,
+        }
+    elif has_begin and not has_end:
+        return {
+            "status": "ok",
+            "has_managed_section": False,
+            "markers_valid": False,
+            "error_detail": "Found <!-- SKF:BEGIN but no matching <!-- SKF:END -->",
+        }
+    elif not has_begin and has_end:
+        return {
+            "status": "ok",
+            "has_managed_section": False,
+            "markers_valid": False,
+            "error_detail": "Found <!-- SKF:END --> but no matching <!-- SKF:BEGIN",
+        }
+    else:
+        return {"status": "ok", "has_managed_section": False, "markers_valid": True}
+
+
+def cmd_read(file_path):
+    """Extract the managed section content."""
+    content, err = read_context_file(file_path)
+    if err:
+        return {"status": "error", "error": err}
+
+    match = find_managed_section(content)
+    if not match:
+        return {"status": "ok", "has_managed_section": False, "content": None}
+
+    return {"status": "ok", "has_managed_section": True, "content": match.group(2)}
+
+
+def cmd_replace(file_path, new_content):
+    """Replace managed section content between markers."""
+    content, err = read_context_file(file_path)
+    if err:
+        return {"status": "error", "error": err}
+
+    match = find_managed_section(content)
+    if not match:
+        return {"status": "error", "error": "No managed section found. Use 'insert' to create one."}
+
+    # Replace content between markers with fresh timestamp
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    new_section = f"<!-- SKF:BEGIN updated:{today} -->\n{new_content}\n{END_MARKER}"
+    updated = content[: match.start()] + new_section + content[match.end() :]
+
+    Path(file_path).write_text(updated, encoding="utf-8")
+    return {"status": "ok", "action": "replaced", "bytes_written": len(updated)}
+
+
+def cmd_clear(file_path):
+    """Remove managed section entirely (markers + content)."""
+    content, err = read_context_file(file_path)
+    if err:
+        return {"status": "error", "error": err}
+
+    match = find_managed_section(content)
+    if not match:
+        return {"status": "ok", "action": "no_change", "reason": "No managed section found"}
+
+    # Remove the entire marker block, plus any surrounding blank lines
+    before = content[: match.start()].rstrip("\n")
+    after = content[match.end() :].lstrip("\n")
+    updated = before + ("\n\n" if before and after else "") + after
+
+    Path(file_path).write_text(updated, encoding="utf-8")
+    return {"status": "ok", "action": "cleared", "bytes_written": len(updated)}
+
+
+def cmd_insert(file_path, new_content):
+    """Insert managed section at end of file if not present."""
+    content, err = read_context_file(file_path)
+    if err:
+        # File doesn't exist — create it
+        if "not found" in err.lower():
+            content = ""
+        else:
+            return {"status": "error", "error": err}
+
+    match = find_managed_section(content)
+    if match:
+        return {"status": "error", "error": "Managed section already exists. Use 'replace' instead."}
+
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    section = f"\n<!-- SKF:BEGIN updated:{today} -->\n{new_content}\n{END_MARKER}\n"
+    updated = content.rstrip("\n") + "\n" + section if content.strip() else section.lstrip("\n")
+
+    Path(file_path).write_text(updated, encoding="utf-8")
+    return {"status": "ok", "action": "inserted", "bytes_written": len(updated)}
+
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: python3 skf-rebuild-managed-sections.py <context-file> <action> [--content <text>]", file=sys.stderr)
+        print("Actions: read, replace, clear, insert, check", file=sys.stderr)
+        sys.exit(1)
+
+    file_path = sys.argv[1]
+    action = sys.argv[2]
+
+    content_arg = None
+    if "--content" in sys.argv:
+        idx = sys.argv.index("--content")
+        if idx + 1 < len(sys.argv):
+            content_arg = sys.argv[idx + 1]
+    elif action in ("replace", "insert") and not sys.stdin.isatty():
+        content_arg = sys.stdin.read()
+
+    if action == "check":
+        result = cmd_check(file_path)
+    elif action == "read":
+        result = cmd_read(file_path)
+    elif action == "replace":
+        if content_arg is None:
+            result = {"status": "error", "error": "replace requires --content or stdin"}
+        else:
+            result = cmd_replace(file_path, content_arg)
+    elif action == "clear":
+        result = cmd_clear(file_path)
+    elif action == "insert":
+        if content_arg is None:
+            result = {"status": "error", "error": "insert requires --content or stdin"}
+        else:
+            result = cmd_insert(file_path, content_arg)
+    else:
+        result = {"status": "error", "error": f"Unknown action: {action}"}
+
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["status"] == "ok" else 1)
+
+
+if __name__ == "__main__":
+    main()

package/src/shared/scripts/skf-severity-classify.py

@@ -0,0 +1,163 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Severity Classify — Rule-based severity classification for drift findings.
+
+Applies severity rules to a list of drift findings and computes an overall
+drift score. Used by audit-skill and test-skill.
+
+CLI: python3 skf-severity-classify.py <findings-json>
+     echo '<JSON>' | python3 skf-severity-classify.py -
+
+Input: JSON array of findings, each with:
+  - type: "removed"|"added"|"changed"|"moved"|"semantic"
+  - category: "export"|"signature"|"parameter"|"module"|"pattern"|"convention"|...
+  - detail: description string
+
+Output: JSON with classified findings and overall drift score.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+# --- Severity Rules (from severity-rules.md) ---
+
+CRITICAL_RULES = [
+    {"type": "removed", "categories": {"export", "module", "class", "interface"}},
+    {"type": "changed", "categories": {"signature", "parameter_count", "return_type", "inheritance", "interface_contract"}},
+    {"type": "renamed", "categories": {"export", "module"}},
+]
+
+HIGH_RULES = [
+    {"type": "added", "categories": {"export"}, "threshold": 3},  # >3 new exports
+    {"type": "removed", "categories": {"internal_helper"}},
+    {"type": "changed", "categories": {"default_value", "required_parameter"}},
+    {"type": "deprecated", "categories": {"export"}},
+]
+
+MEDIUM_RULES = [
+    {"type": "changed", "categories": {"implementation", "optional_parameter", "internal_pattern"}},
+    {"type": "added", "categories": {"export"}, "threshold_max": 3},  # 1-3 new exports
+    {"type": "moved", "categories": {"export", "function"}},
+]
+
+LOW_CATEGORIES = {"style", "convention", "comment", "documentation", "whitespace", "test", "internal", "private"}
+
+
+def classify_finding(finding, added_export_count=0):
+    """Classify a single finding's severity. Returns severity string."""
+    f_type = finding.get("type", "").lower()
+    f_category = finding.get("category", "").lower()
+
+    # Check CRITICAL
+    for rule in CRITICAL_RULES:
+        if f_type == rule["type"] and f_category in rule["categories"]:
+            return "CRITICAL"
+
+    # Check HIGH
+    for rule in HIGH_RULES:
+        if f_type == rule["type"]:
+            if f_category in rule["categories"]:
+                if "threshold" in rule:
+                    if f_type == "added" and f_category == "export" and added_export_count > rule["threshold"]:
+                        return "HIGH"
+                else:
+                    return "HIGH"
+
+    # Check MEDIUM
+    for rule in MEDIUM_RULES:
+        if f_type == rule["type"]:
+            if f_category in rule["categories"]:
+                if "threshold_max" in rule:
+                    if f_type == "added" and f_category == "export" and added_export_count <= rule["threshold_max"]:
+                        return "MEDIUM"
+                else:
+                    return "MEDIUM"
+
+    # Check LOW
+    if f_category in LOW_CATEGORIES:
+        return "LOW"
+
+    # Semantic findings default to MEDIUM
+    if f_type == "semantic":
+        return "MEDIUM"
+
+    # Default: MEDIUM for unrecognized patterns
+    return "MEDIUM"
+
+
+def compute_drift_score(classified):
+    """Compute overall drift score from classified findings."""
+    severities = {f["severity"] for f in classified}
+
+    if not classified:
+        return "CLEAN"
+    if "CRITICAL" in severities:
+        return "CRITICAL"
+    if "HIGH" in severities or "MEDIUM" in severities:
+        return "SIGNIFICANT"
+    return "MINOR"
+
+
+def classify_all(findings):
+    """Classify all findings and compute drift score."""
+    if not isinstance(findings, list):
+        return {"status": "error", "error": "Input must be a JSON array of findings"}
+
+    # Count added exports for threshold rules
+    added_export_count = sum(
+        1 for f in findings
+        if f.get("type", "").lower() == "added" and f.get("category", "").lower() == "export"
+    )
+
+    classified = []
+    for finding in findings:
+        severity = classify_finding(finding, added_export_count)
+        classified.append({**finding, "severity": severity})
+
+    # Sort by severity: CRITICAL > HIGH > MEDIUM > LOW
+    severity_order = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3}
+    classified.sort(key=lambda f: severity_order.get(f["severity"], 4))
+
+    drift_score = compute_drift_score(classified)
+
+    # Summary
+    by_severity = {"CRITICAL": 0, "HIGH": 0, "MEDIUM": 0, "LOW": 0}
+    for f in classified:
+        by_severity[f["severity"]] = by_severity.get(f["severity"], 0) + 1
+
+    return {
+        "status": "ok",
+        "drift_score": drift_score,
+        "total_findings": len(classified),
+        "by_severity": by_severity,
+        "findings": classified,
+    }
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python3 skf-severity-classify.py <findings-json-or-file>", file=sys.stderr)
+        print("       echo '<JSON>' | python3 skf-severity-classify.py -", file=sys.stderr)
+        sys.exit(1)
+
+    arg = sys.argv[1]
+
+    try:
+        if arg == "-":
+            data = json.load(sys.stdin)
+        elif arg.startswith("["):
+            data = json.loads(arg)
+        else:
+            with open(arg, encoding="utf-8") as f:
+                data = json.load(f)
+    except (json.JSONDecodeError, FileNotFoundError) as e:
+        print(json.dumps({"status": "error", "error": str(e)}))
+        sys.exit(1)
+
+    result = classify_all(data)
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["status"] == "ok" else 1)