bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-campaign/scripts/campaign-status.py

@@ -0,0 +1,162 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""Campaign Status — deterministic state summary + optional backup-drift verdict.
+
+Collapses two in-prompt determinism leaks into one helper the LLM calls instead
+of hand-deriving:
+
+  - `campaign status` and the resume summary block tallied `skills[]` by status
+    ("N completed / M total, K pending, ...") in-prompt over a 15+ skill array.
+  - the `.bak` recovery path compared `primary` vs `backup` timestamps and stage
+    numbers by hand (an ISO-8601 + int compare across two YAML files).
+
+Both are mechanical, one-correct-answer computations. This script owns them so
+identical state always yields identical output.
+
+CLI:
+  uv run campaign-status.py --state-file <path>
+  uv run campaign-status.py --state-file <path> --backup-file <path>
+
+Output (JSON on stdout):
+  {
+    "campaign_name": "...",
+    "current_stage": 0,
+    "last_updated": "...",
+    "total": 0, "completed": 0, "pending": 0,
+    "active": 0, "failed": 0, "skipped": 0,
+    "backup_comparison": null | {
+      "primary_behind": bool,
+      "primary_last_updated": "...", "backup_last_updated": "...",
+      "primary_stage": 0, "backup_stage": 0
+    }
+  }
+
+Exit codes:
+  0  ok
+  2  error (state missing / unreadable / not a mapping)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import yaml
+
+STATUSES = ("pending", "active", "completed", "failed", "skipped")
+
+
+def _err(message: str, code: str) -> int:
+    json.dump({"error": message, "code": code}, sys.stderr)
+    sys.stderr.write("\n")
+    return 2
+
+
+def _load_state(path: Path) -> Optional[Dict[str, Any]]:
+    if not path.is_file():
+        return None
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (yaml.YAMLError, OSError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _parse_iso(value: Any) -> Optional[datetime]:
+    if not isinstance(value, str) or not value:
+        return None
+    text = value[:-1] + "+00:00" if value.endswith("Z") else value
+    try:
+        return datetime.fromisoformat(text)
+    except (ValueError, TypeError):
+        return None
+
+
+def _counts(state: Dict[str, Any]) -> Dict[str, int]:
+    skills = state.get("skills", []) or []
+    tally = {s: 0 for s in STATUSES}
+    for skill in skills:
+        status = skill.get("status")
+        if status in tally:
+            tally[status] += 1
+    tally["total"] = len(skills)
+    return tally
+
+
+def _compare_backup(primary: Dict[str, Any], backup: Dict[str, Any]) -> Dict[str, Any]:
+    p_c = primary.get("campaign", {}) or {}
+    b_c = backup.get("campaign", {}) or {}
+    p_updated = p_c.get("last_updated")
+    b_updated = b_c.get("last_updated")
+    p_stage = p_c.get("current_stage")
+    b_stage = b_c.get("current_stage")
+
+    stage_behind = (
+        isinstance(p_stage, int) and isinstance(b_stage, int) and p_stage < b_stage
+    )
+
+    ts_behind = False
+    p_ts = _parse_iso(p_updated)
+    b_ts = _parse_iso(b_updated)
+    if p_ts is not None and b_ts is not None:
+        try:
+            ts_behind = p_ts < b_ts
+        except TypeError:
+            # naive vs aware datetime — cannot order; defer to stage compare.
+            ts_behind = False
+
+    return {
+        "primary_behind": bool(stage_behind or ts_behind),
+        "primary_last_updated": p_updated,
+        "backup_last_updated": b_updated,
+        "primary_stage": p_stage,
+        "backup_stage": b_stage,
+    }
+
+
+def run(state_file: str, backup_file: Optional[str]) -> int:
+    state = _load_state(Path(state_file))
+    if state is None:
+        return _err(f"State not readable as a mapping: {state_file}", "STATE_UNREADABLE")
+
+    campaign = state.get("campaign", {}) or {}
+    result: Dict[str, Any] = {
+        "campaign_name": campaign.get("name", ""),
+        "current_stage": campaign.get("current_stage"),
+        "last_updated": campaign.get("last_updated"),
+        **_counts(state),
+        "backup_comparison": None,
+    }
+
+    if backup_file:
+        backup = _load_state(Path(backup_file))
+        if backup is not None:
+            result["backup_comparison"] = _compare_backup(state, backup)
+
+    json.dump(result, sys.stdout, separators=(",", ":"), default=str)
+    sys.stdout.write("\n")
+    return 0
+
+
+def main(argv: Optional[list] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="campaign-status",
+        description="Summarize campaign state and (optionally) compare it to its backup.",
+    )
+    parser.add_argument("--state-file", required=True, help="Path to _campaign-state.yaml")
+    parser.add_argument(
+        "--backup-file",
+        help="Path to _campaign-state.yaml.bak; when given, emit backup_comparison",
+    )
+    args = parser.parse_args(argv)
+    return run(args.state_file, args.backup_file)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-campaign/scripts/campaign-validate-pins.py

@@ -0,0 +1,174 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""Campaign Validate Pins — validate all version pins in a campaign state file.
+
+Campaign-specific wrapper around the shared skf-validate-pins.py module.
+Reads the campaign state and brief, validates every skill's pin against
+real GitHub releases/tags, and outputs consolidated JSON.
+
+CLI:
+  uv run src/skf-campaign/scripts/campaign-validate-pins.py \
+      --state-file <path> --brief-file <path>
+
+Input:
+  --state-file   Path to _campaign-state.yaml
+  --brief-file   Path to campaign-brief.yaml
+
+Output (JSON on stdout):
+  {
+    "results": [
+      {
+        "name": "skill-name",
+        "status": "valid|invalid|resolved",
+        "pin": "input-pin-or-null",
+        "resolved_ref": "actual-tag-or-branch",
+        "ref_type": "tag|branch|null",
+        "version": "semver-or-null",
+        "suggestions": []
+      }
+    ],
+    "all_valid": true,
+    "invalid_count": 0,
+    "resolved_count": 0
+  }
+
+Exit codes:
+  0  all valid/resolved
+  1  one or more invalid pins
+  2  error (missing files, bad YAML, gh unavailable)
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+import yaml
+
+SHARED_SCRIPTS = Path(__file__).parent.parent.parent / "shared" / "scripts"
+VALIDATE_PINS_PATH = SHARED_SCRIPTS / "skf-validate-pins.py"
+
+
+def _load_validate_pin():
+    spec = importlib.util.spec_from_file_location("skf_validate_pins", VALIDATE_PINS_PATH)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod.validate_pin
+
+
+def _emit_error(message: str, code: str) -> None:
+    json.dump({"error": message, "code": code}, sys.stderr)
+    sys.stderr.write("\n")
+
+
+def _load_yaml(path: Path) -> Any:
+    with open(path, encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def run(state_file: str, brief_file: str) -> int:
+    state_path = Path(state_file)
+    brief_path = Path(brief_file)
+
+    if not state_path.is_file():
+        _emit_error(f"State file not found: {state_file}", "STATE_NOT_FOUND")
+        return 2
+
+    if not brief_path.is_file():
+        _emit_error(f"Brief file not found: {brief_file}", "BRIEF_NOT_FOUND")
+        return 2
+
+    try:
+        state = _load_yaml(state_path)
+    except Exception as exc:
+        _emit_error(f"Failed to parse state file: {exc}", "STATE_PARSE_ERROR")
+        return 2
+
+    try:
+        brief = _load_yaml(brief_path)
+    except Exception as exc:
+        _emit_error(f"Failed to parse brief file: {exc}", "BRIEF_PARSE_ERROR")
+        return 2
+
+    skills = state.get("skills", [])
+    if not isinstance(skills, list):
+        _emit_error("State file 'skills' is not an array", "INVALID_STATE")
+        return 2
+
+    targets = brief.get("targets", [])
+    if not isinstance(targets, list):
+        _emit_error("Brief file 'targets' is not an array", "INVALID_BRIEF")
+        return 2
+
+    name_to_repo: Dict[str, str] = {}
+    for target in targets:
+        name_to_repo[target["name"]] = target["repo_url"]
+
+    if not VALIDATE_PINS_PATH.is_file():
+        _emit_error(
+            f"Shared module not found: {VALIDATE_PINS_PATH.as_posix()}",
+            "SHARED_MODULE_NOT_FOUND",
+        )
+        return 2
+
+    validate_pin = _load_validate_pin()
+
+    results: List[Dict[str, Any]] = []
+    invalid_count = 0
+    resolved_count = 0
+
+    for skill in skills:
+        skill_name = skill["name"]
+        repo_url = name_to_repo.get(skill_name)
+        if repo_url is None:
+            _emit_error(
+                f"Skill '{skill_name}' not found in brief targets",
+                "SKILL_NOT_IN_BRIEF",
+            )
+            return 2
+
+        pin = skill.get("pin")
+        result = validate_pin(repo_url, pin=pin)
+        result["name"] = skill_name
+
+        if result["status"] == "invalid":
+            invalid_count += 1
+        elif result["status"] == "resolved":
+            resolved_count += 1
+
+        results.append(result)
+
+    all_valid = invalid_count == 0
+    output = {
+        "results": results,
+        "all_valid": all_valid,
+        "invalid_count": invalid_count,
+        "resolved_count": resolved_count,
+    }
+
+    json.dump(output, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+
+    if not all_valid:
+        return 1
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate all version pins in a campaign state file.",
+    )
+    parser.add_argument("--state-file", required=True, help="Path to _campaign-state.yaml")
+    parser.add_argument("--brief-file", required=True, help="Path to campaign-brief.yaml")
+    args = parser.parse_args()
+    return run(args.state_file, args.brief_file)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-campaign/scripts/campaign-validate-state.py

@@ -0,0 +1,207 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml", "jsonschema>=4.0"]
+# ///
+"""Campaign Validate State — schema check for _campaign-state.yaml on disk.
+
+Replaces the per-step "mentally validate the loaded state against the schema"
+prose with a deterministic check. Every campaign step that loads state runs
+this once on entry instead of asking the LLM to validate a draft-07 schema
+(nested objects, enums, additionalProperties:false, date-time) by hand — the
+exact check an LLM does unreliably and which, when wrong, silently corrupts a
+multi-session campaign.
+
+Loads the campaign state YAML, validates it against
+`assets/campaign-state-schema.json` (resolved relative to this script unless
+`--schema-file` overrides), and emits skill-friendly error records the calling
+step can forward verbatim.
+
+CLI:
+  uv run campaign-validate-state.py --state-file <path>
+  uv run campaign-validate-state.py --state-file <path> --schema-file <path>
+
+Output (JSON on stdout):
+  {
+    "valid": bool,
+    "errors":   [{"field": "campaign.current_stage", "message": "..."}, ...],
+    "halt_reason": "state-missing" | "state-malformed" | "state-invalid" | null
+  }
+
+Exit codes:
+  0  valid (errors empty)
+  1  invalid (schema violations) OR file/yaml load failed
+  2  configuration error (schema file missing or unreadable)
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+from jsonschema import Draft7Validator
+
+DEFAULT_SCHEMA_PATH = Path(__file__).resolve().parent.parent / "assets" / "campaign-state-schema.json"
+
+
+def _emit(envelope: dict) -> None:
+    json.dump(envelope, sys.stdout, separators=(",", ":"), default=str)
+    sys.stdout.write("\n")
+
+
+def _load_yaml_text(text: str) -> tuple[Any, str | None]:
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        return None, f"State is not valid YAML: {exc}"
+    if data is None:
+        return None, "State file is empty"
+    if not isinstance(data, dict):
+        return None, f"State root must be a YAML mapping; got {type(data).__name__}"
+    return data, None
+
+
+def _field_path(error_path) -> str:
+    parts: list[str] = []
+    for p in error_path:
+        if isinstance(p, int):
+            parts.append(f"[{p}]")
+        else:
+            parts.append(f".{p}" if parts else str(p))
+    return "".join(parts) or "(root)"
+
+
+def _translate(err) -> dict:
+    field = _field_path(err.absolute_path)
+    validator = err.validator
+    inst = err.instance
+
+    if validator == "required":
+        missing = err.message.split("'")[1] if "'" in err.message else "(unknown)"
+        return {
+            "field": missing,
+            "message": f"State validation failed: missing required field `{missing}`.",
+        }
+    if validator == "enum":
+        return {
+            "field": field,
+            "message": (
+                f"State validation failed: `{field}` value `{inst}` is not one of "
+                f"{err.validator_value}."
+            ),
+        }
+    if validator == "type":
+        if isinstance(inst, datetime.date) and "string" in str(err.validator_value):
+            return {
+                "field": field,
+                "message": (
+                    f"State validation failed: `{field}` parsed as a YAML date, not a "
+                    f"string. Quote it (e.g. `'2026-05-01T00:00:00Z'`)."
+                ),
+            }
+        return {
+            "field": field,
+            "message": (
+                f"State validation failed: `{field}` has type `{type(inst).__name__}`, "
+                f"expected `{err.validator_value}`."
+            ),
+        }
+    if validator == "additionalProperties":
+        return {
+            "field": field,
+            "message": f"State validation failed: `{field}` — {err.message}",
+        }
+    if validator in ("minimum", "maximum"):
+        return {
+            "field": field,
+            "message": f"State validation failed: `{field}` value `{inst}` violates {validator} `{err.validator_value}`.",
+        }
+    return {
+        "field": field,
+        "message": f"State validation failed: `{field}` — {err.message}",
+    }
+
+
+def validate_state(state: dict, schema: dict) -> dict:
+    validator = Draft7Validator(schema)
+    errors = [
+        _translate(err)
+        for err in sorted(validator.iter_errors(state), key=lambda e: list(e.absolute_path))
+    ]
+    return {"valid": not errors, "errors": errors}
+
+
+def run(state_file: str, schema_file: str | None = None) -> int:
+    schema_path = Path(schema_file) if schema_file else DEFAULT_SCHEMA_PATH
+    if not schema_path.is_file():
+        _emit(
+            {
+                "valid": False,
+                "errors": [{"field": "(schema)", "message": f"Schema not found at `{schema_path}`."}],
+                "halt_reason": "state-invalid",
+            }
+        )
+        return 2
+    try:
+        schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        _emit(
+            {
+                "valid": False,
+                "errors": [{"field": "(schema)", "message": f"Schema unreadable: {exc}"}],
+                "halt_reason": "state-invalid",
+            }
+        )
+        return 2
+
+    state_path = Path(state_file)
+    if not state_path.is_file():
+        _emit(
+            {
+                "valid": False,
+                "errors": [{"field": "(file)", "message": f"State not found at `{state_path}`."}],
+                "halt_reason": "state-missing",
+            }
+        )
+        return 1
+
+    state, load_err = _load_yaml_text(state_path.read_text(encoding="utf-8"))
+    if load_err is not None:
+        _emit(
+            {
+                "valid": False,
+                "errors": [{"field": "(file)", "message": load_err}],
+                "halt_reason": "state-malformed",
+            }
+        )
+        return 1
+
+    result = validate_state(state, schema)
+    if not result["valid"]:
+        _emit({**result, "halt_reason": "state-invalid"})
+        return 1
+
+    _emit({**result, "halt_reason": None})
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="campaign-validate-state",
+        description="Validate _campaign-state.yaml against the campaign state schema.",
+    )
+    parser.add_argument("--state-file", required=True, help="Path to _campaign-state.yaml")
+    parser.add_argument(
+        "--schema-file",
+        help="Path to campaign-state-schema.json (defaults to the bundled schema)",
+    )
+    args = parser.parse_args(argv)
+    return run(args.state_file, args.schema_file)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-campaign/templates/campaign-brief-template.yaml

@@ -0,0 +1,34 @@
+# Machine-generated campaign brief — resume context for fresh sessions
+# Populated by step-01-setup.md from operator inputs
+
+# Campaign identifier
+campaign_name: ""
+
+# ISO-8601 timestamp of campaign creation
+created_at: ""
+
+# Target skills for this campaign run
+targets: []
+# Each target entry:
+#   name: ""
+#   repo_url: ""
+#   tier: "A"           # A (full pipeline) or B (batch)
+#   pin: null            # version pin, or null for latest
+#   depends_on: []       # list of skill names this target depends on
+
+# Quality thresholds applied to all skills in this campaign
+quality_gate:
+  hard: "zero-critical-high"
+  soft_target: 90
+  soft_fallback: 80
+
+# Where health findings are routed: "local" (project-local) or "improvement" (shared queue)
+health_findings_queue: "local"
+
+# Optional path to the architecture document the verify (Stage 7) and refine
+# (Stage 8) stages consume. Empty string means those stages discover it at
+# runtime (docs/architecture.md, then _bmad-output/planning-artifacts/architecture.md).
+architecture_doc_path: ""
+
+# Operator-provided context or directives for this campaign
+notes: ""

package/src/skf-campaign/templates/campaign-report-template.md

@@ -0,0 +1,54 @@
+# Campaign Report — {{campaign_name}}
+
+## Campaign Summary
+
+| Field | Value |
+|-------|-------|
+| **Campaign** | {{campaign_name}} |
+| **Started** | {{started_at}} |
+| **Completed** | {{completed_at}} |
+| **Duration** | {{duration}} |
+| **Quality Gate (Hard)** | {{quality_gate_hard}} |
+| **Quality Gate (Soft Target)** | {{quality_gate_soft_target}} |
+| **Quality Gate (Soft Fallback)** | {{quality_gate_soft_fallback}} |
+| **Skills Completed** | {{skills_completed}} |
+| **Skills Failed** | {{skills_failed}} |
+| **Skills Skipped** | {{skills_skipped}} |
+
+## Skills Overview
+
+| Name | Tier | Status | Quality Score | Pin | Workarounds |
+|------|------|--------|---------------|-----|-------------|
+{{skills_table}}
+
+## Quality Scores
+
+| Metric | Value |
+|--------|-------|
+| **Minimum** | {{quality_min}} |
+| **Maximum** | {{quality_max}} |
+| **Average** | {{quality_avg}} |
+
+### Per-Skill Breakdown
+
+{{quality_breakdown}}
+
+## Findings Summary
+
+- **Total workarounds applied:** {{total_workarounds}}
+- **Skills with workarounds:** {{skills_with_workarounds}}
+- **Doc-rot corrections:** tracked per-skill in health-check findings (not aggregated in campaign state)
+
+## Workarounds Applied
+
+{{workarounds_list}}
+
+## Duration Breakdown
+
+| Skill | Started | Completed | Duration |
+|-------|---------|-----------|----------|
+{{duration_table}}
+
+## Failed / Skipped Skills
+
+{{failed_skipped_section}}

package/src/skf-campaign/templates/kickoff-template.md

@@ -0,0 +1,48 @@
+# Skill Kickoff — {{skill_name}}
+
+## Campaign Context
+
+- **Campaign:** {{campaign_name}}
+- **Current Stage:** {{current_stage}}
+- **Quality Gate:** {{quality_gate_summary}}
+
+## Skill Identity
+
+- **Skill:** {{skill_name}}
+- **Tier:** {{skill_tier}}
+- **Repository:** {{repo_url}}
+- **Pin:** {{pin}}
+- **Commit:** {{commit_sha}}
+
+## Brief Summary
+
+{{brief_summary}}
+
+## Campaign Facts
+
+{{persistent_facts}}
+
+## Dependency State
+
+{{dependency_status_table}}
+
+## Standing Directive
+
+{{directive_content}}
+
+## Workarounds Applied
+
+{{workarounds_list}}
+
+## Pipeline Instructions
+
+Execute the standard forge pipeline for **{{skill_name}}**:
+
+1. **AN** (Analyze) — scope and source intelligence
+2. **BS** (Brief Synthesis) — generate or validate the skill brief
+3. **CS** (Compile Skill) — compile the SKILL.md artifact
+4. **TS** (Test Skill) — run health-check validation
+
+**Parameters:**
+- Pin: {{pin}}
+- Quality target: {{quality_gate_summary}}