bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-campaign/scripts/campaign-render-batch.py

@@ -0,0 +1,199 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""Campaign Render Batch — build the QS `--batch` input file for Tier B skills.
+
+step-06 batches every Tier B skill through `skf-quick-skill --batch`. The batch
+input file is a machine-consumed cross-tool contract: one target per line in the
+exact single-target shape `skf-quick-skill` parses (see
+src/skf-quick-skill/references/batch-mode.md). Hand-building that file in prose
+is filter + join + reformat-structured-data — the same mechanical, all-or-nothing
+work campaign-parse-manifest.py owns for the inverse direction, where a silent
+format slip corrupts the whole run. This script is the single source of truth for
+the generation side so the line format lives in one place, aligned with the
+consumer's contract, instead of being re-derived in the step prose.
+
+What it does:
+  - Filters `skills[]` for `tier == "B" && status == "pending"` (skips Tier A and
+    any already completed/failed/skipped — resume-safe).
+  - Looks up each skill's `repo_url` from the brief's `targets[]` (matched by
+    name); repo URLs live only in the brief, never in the state schema.
+  - Emits one line per skill in the CONSUMER's single-target shape:
+      {repo_url}                        (pin is null → latest)
+      {repo_url}@{pin}                  (skills[].pin is non-null)
+    with optional ` language=<lang>` / ` scope=<path>` modifiers appended when the
+    brief target carries a `language_hint`/`language` or `scope_hint`/`scope` hint.
+  - No skill-name field, no bare pin token — that would not parse as a target.
+
+CLI:
+  uv run campaign-render-batch.py --state-file <p> --brief-file <p> [-o <batchFile>]
+
+Output:
+  - Batch text (one target per line) to {batchFile} via -o, else to stdout.
+  - JSON summary {written, count, skipped_non_tierB, skipped_non_pending} to stderr.
+
+Exit codes:
+  0  batch file written (0+ targets)
+  2  state file missing / unreadable / bad YAML
+  8  brief missing / unreadable (missing-brief HALT), or a pending Tier B skill
+     has no matching brief target with a repo_url (unmatched-target)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+import yaml
+
+
+def _err(message: str, code: str, exit_code: int, **extra: Any) -> int:
+    payload: Dict[str, Any] = {"error": message, "code": code}
+    payload.update(extra)
+    json.dump(payload, sys.stderr)
+    sys.stderr.write("\n")
+    return exit_code
+
+
+def _target_line(repo_url: str, pin: Any, target: Dict[str, Any]) -> str:
+    """Render one batch line in the consumer's single-target shape."""
+    line = repo_url
+    if pin:
+        line += f"@{pin}"
+    lang = target.get("language_hint") or target.get("language")
+    scope = target.get("scope_hint") or target.get("scope")
+    if lang:
+        line += f" language={lang}"
+    if scope:
+        line += f" scope={scope}"
+    return line
+
+
+def build_batch(state: Dict[str, Any], brief: Dict[str, Any]) -> Tuple[List[str], Dict[str, Any]]:
+    """Filter Tier B pending skills and render batch lines.
+
+    Returns (lines, summary). `summary["unmatched"]` lists any pending Tier B
+    skill names with no brief target / repo_url; the caller HALTs (exit 8) when
+    it is non-empty.
+    """
+    skills = state.get("skills") or []
+    targets: Dict[str, Dict[str, Any]] = {
+        t.get("name"): t
+        for t in (brief.get("targets") or [])
+        if isinstance(t, dict) and t.get("name")
+    }
+
+    lines: List[str] = []
+    unmatched: List[str] = []
+    skipped_non_tierb = 0
+    skipped_non_pending = 0
+
+    for skill in skills:
+        if not isinstance(skill, dict):
+            continue
+        if skill.get("tier") != "B":
+            skipped_non_tierb += 1
+            continue
+        if skill.get("status") != "pending":
+            skipped_non_pending += 1
+            continue
+
+        name = skill.get("name")
+        target = targets.get(name)
+        repo_url = (target or {}).get("repo_url") or ""
+        if not repo_url:
+            unmatched.append(name)
+            continue
+
+        lines.append(_target_line(repo_url, skill.get("pin"), target))
+
+    summary = {
+        "count": len(lines),
+        "skipped_non_tierB": skipped_non_tierb,
+        "skipped_non_pending": skipped_non_pending,
+        "unmatched": unmatched,
+    }
+    return lines, summary
+
+
+def _load_yaml_mapping(path: str) -> Dict[str, Any]:
+    data = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError("top-level document is not a mapping")
+    return data
+
+
+def run(state_file: str, brief_file: str, output: str | None) -> int:
+    # State problems are plain file/parse errors (exit 2).
+    if not Path(state_file).is_file():
+        return _err(f"State file not found: {state_file}", "STATE_NOT_FOUND", 2)
+    try:
+        state = _load_yaml_mapping(state_file)
+    except (yaml.YAMLError, ValueError) as exc:
+        return _err(f"Failed to parse state YAML: {exc}", "STATE_PARSE_ERROR", 2)
+
+    # Brief problems preserve step-06 §4's missing-brief HALT (exit 8): repo_urls
+    # live only in the brief, so a missing/unreadable/corrupt brief is fatal here.
+    if not Path(brief_file).is_file():
+        return _err(f"Brief file not found: {brief_file}", "missing-brief", 8)
+    try:
+        brief = _load_yaml_mapping(brief_file)
+    except OSError as exc:
+        return _err(f"Brief unreadable: {exc}", "missing-brief", 8)
+    except (yaml.YAMLError, ValueError) as exc:
+        return _err(f"Brief unparseable: {exc}", "missing-brief", 8)
+
+    lines, summary = build_batch(state, brief)
+
+    unmatched = summary.pop("unmatched")
+    if unmatched:
+        return _err(
+            "No matching brief target (repo_url) for pending Tier B skill(s): "
+            + ", ".join(str(n) for n in unmatched),
+            "unmatched-target",
+            8,
+            skills=unmatched,
+        )
+
+    batch_text = "\n".join(lines)
+    if batch_text:
+        batch_text += "\n"
+
+    if output:
+        Path(output).write_text(batch_text, encoding="utf-8")
+        summary["written"] = output
+    else:
+        sys.stdout.write(batch_text)
+        summary["written"] = "<stdout>"
+
+    ordered = {
+        "written": summary["written"],
+        "count": summary["count"],
+        "skipped_non_tierB": summary["skipped_non_tierB"],
+        "skipped_non_pending": summary["skipped_non_pending"],
+    }
+    json.dump(ordered, sys.stderr)
+    sys.stderr.write("\n")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="campaign-render-batch",
+        description="Build the QS --batch input file for pending Tier B skills.",
+    )
+    parser.add_argument("--state-file", required=True)
+    parser.add_argument("--brief-file", required=True)
+    parser.add_argument("-o", "--output", dest="output", help="batch file path (default: stdout)")
+    args = parser.parse_args(argv)
+    return run(args.state_file, args.brief_file, args.output)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-campaign/scripts/campaign-render-kickoff.py

@@ -0,0 +1,158 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""Campaign Render Kickoff — fill the mechanical kickoff-template placeholders.
+
+step-05 emits a kickoff message per Tier-A skill. Most of its placeholders are
+direct field copies from state + brief (campaign name, stage, quality gate,
+skill identity, repo, pin, commit, the dependency-status table, the workaround
+list) — mechanical substitution that an LLM should not hand-perform 15× per
+campaign. This script renders those deterministically and leaves the three
+judgment slots untouched for the LLM to fill in context:
+
+  {{brief_summary}}        — concise summary of the brief target entry
+  {{persistent_facts}}     — campaign-wide facts resolved in On Activation
+  {{directive_content}}    — raw directive file content
+
+CLI:
+  uv run campaign-render-kickoff.py --state-file <p> --brief-file <p> \
+      --skill <name> --template <p> [--workarounds '<json-list>']
+
+Output: the rendered kickoff markdown on stdout (judgment slots preserved).
+
+Exit codes:
+  0  rendered
+  2  error (missing file, bad YAML, skill/target not found, bad --workarounds)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+# Placeholders this script intentionally leaves for the LLM to fill.
+JUDGMENT_SLOTS = ("{{brief_summary}}", "{{persistent_facts}}", "{{directive_content}}")
+
+
+def _err(message: str, code: str) -> int:
+    json.dump({"error": message, "code": code}, sys.stderr)
+    sys.stderr.write("\n")
+    return 2
+
+
+def _quality_gate_summary(qg: Dict[str, Any]) -> str:
+    return (
+        f"Hard: {qg.get('hard', 'N/A')} | "
+        f"Soft: {qg.get('soft_target', 'N/A')} (fallback: {qg.get('soft_fallback', 'N/A')})"
+    )
+
+
+def _dependency_status_table(skill: Dict[str, Any], skill_map: Dict[str, Dict[str, Any]]) -> str:
+    deps = skill.get("depends_on", []) or []
+    if not deps:
+        return "No dependencies."
+    rows = ["| Dependency | Status |", "|------------|--------|"]
+    for dep in deps:
+        status = skill_map.get(dep, {}).get("status", "unknown")
+        rows.append(f"| {dep} | {status} |")
+    return "\n".join(rows)
+
+
+def _workarounds_list(workarounds: List[str]) -> str:
+    if not workarounds:
+        return "None"
+    return "\n".join(f"- {w}" for w in workarounds)
+
+
+def render_kickoff(
+    state: Dict[str, Any],
+    brief: Dict[str, Any],
+    skill_name: str,
+    template: str,
+    workarounds: Optional[List[str]] = None,
+) -> str:
+    campaign = state.get("campaign", {})
+    skills = state.get("skills", [])
+    skill_map = {s["name"]: s for s in skills}
+    if skill_name not in skill_map:
+        raise KeyError(f"Skill '{skill_name}' not found in state")
+    skill = skill_map[skill_name]
+
+    targets = {t["name"]: t for t in brief.get("targets", [])}
+    repo_url = targets.get(skill_name, {}).get("repo_url", "")
+
+    wa = workarounds if workarounds is not None else (skill.get("workarounds_applied", []) or [])
+
+    mechanical = {
+        "{{campaign_name}}": str(campaign.get("name", "")),
+        "{{current_stage}}": str(campaign.get("current_stage", "")),
+        "{{quality_gate_summary}}": _quality_gate_summary(campaign.get("quality_gate", {})),
+        "{{skill_name}}": skill_name,
+        "{{skill_tier}}": str(skill.get("tier", "")),
+        "{{pin}}": skill.get("pin") or "latest",
+        "{{commit_sha}}": skill.get("commit_sha") or "unknown",
+        "{{repo_url}}": repo_url,
+        "{{workarounds_list}}": _workarounds_list(wa),
+        "{{dependency_status_table}}": _dependency_status_table(skill, skill_map),
+    }
+
+    out = template
+    for key, value in mechanical.items():
+        out = out.replace(key, value)
+    return out
+
+
+def run(state_file: str, brief_file: str, skill: str, template_file: str, workarounds_json: Optional[str]) -> int:
+    for label, p in (("State", state_file), ("Brief", brief_file), ("Template", template_file)):
+        if not Path(p).is_file():
+            return _err(f"{label} file not found: {p}", f"{label.upper()}_NOT_FOUND")
+
+    try:
+        state = yaml.safe_load(Path(state_file).read_text(encoding="utf-8"))
+        brief = yaml.safe_load(Path(brief_file).read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        return _err(f"Failed to parse YAML: {exc}", "PARSE_ERROR")
+    template = Path(template_file).read_text(encoding="utf-8")
+
+    workarounds: Optional[List[str]] = None
+    if workarounds_json:
+        try:
+            workarounds = json.loads(workarounds_json)
+            if not isinstance(workarounds, list):
+                raise ValueError("not a list")
+        except ValueError as exc:
+            return _err(f"--workarounds must be a JSON list: {exc}", "BAD_WORKAROUNDS")
+
+    try:
+        rendered = render_kickoff(state, brief, skill, template, workarounds)
+    except KeyError as exc:
+        return _err(str(exc), "SKILL_NOT_FOUND")
+
+    sys.stdout.write(rendered)
+    if not rendered.endswith("\n"):
+        sys.stdout.write("\n")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="campaign-render-kickoff",
+        description="Render the mechanical placeholders in the campaign kickoff template.",
+    )
+    parser.add_argument("--state-file", required=True)
+    parser.add_argument("--brief-file", required=True)
+    parser.add_argument("--skill", required=True, help="skill name (must exist in state)")
+    parser.add_argument("--template", required=True, dest="template_file")
+    parser.add_argument("--workarounds", dest="workarounds_json", help="JSON list of applied workarounds")
+    args = parser.parse_args(argv)
+    return run(args.state_file, args.brief_file, args.skill, args.template_file, args.workarounds_json)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,249 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""Campaign Report — generate a markdown report from campaign state + template.
+
+CLI:
+  uv run campaign-report.py \
+      --state-file <path> --template-file <path> --output-file <path>
+
+Output (JSON on stdout):
+  {"status":"success","report_path":"...","skills_completed":N,"skills_failed":N,
+   "quality_scores":{"skill":score,...},"duration":"..."}
+
+Exit codes:
+  0  success
+  2  error (missing file, bad YAML, template error)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+
+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 _parse_iso(value: Optional[str]) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def _format_duration(start: Optional[datetime], end: Optional[datetime]) -> str:
+    if not start or not end:
+        return "N/A"
+    delta = end - start
+    total_seconds = int(delta.total_seconds())
+    if total_seconds < 0:
+        return "N/A"
+    hours, remainder = divmod(total_seconds, 3600)
+    minutes, seconds = divmod(remainder, 60)
+    if hours > 0:
+        return f"{hours}h {minutes}m {seconds}s"
+    if minutes > 0:
+        return f"{minutes}m {seconds}s"
+    return f"{seconds}s"
+
+
+def _compute_aggregates(state: Dict[str, Any]) -> Dict[str, Any]:
+    campaign = state.get("campaign", {})
+    skills: List[Dict[str, Any]] = state.get("skills", [])
+
+    started_at_str = campaign.get("started_at", "")
+    last_updated_str = campaign.get("last_updated", "")
+    started_at = _parse_iso(started_at_str)
+    last_updated = _parse_iso(last_updated_str)
+
+    completed = [s for s in skills if s.get("status") == "completed"]
+    failed = [s for s in skills if s.get("status") == "failed"]
+    skipped = [s for s in skills if s.get("status") == "skipped"]
+
+    scores = [s["quality_score"] for s in completed if s.get("quality_score") is not None]
+    quality_min = min(scores) if scores else 0
+    quality_max = max(scores) if scores else 0
+    quality_avg = round(sum(scores) / len(scores), 1) if scores else 0
+
+    all_workarounds: List[str] = []
+    skills_with_wa = 0
+    for s in skills:
+        wa = s.get("workarounds_applied", []) or []
+        if wa:
+            skills_with_wa += 1
+            all_workarounds.extend(wa)
+
+    skills_table_rows = []
+    for s in skills:
+        wa = s.get("workarounds_applied", []) or []
+        skills_table_rows.append(
+            f"| {s.get('name', '')} "
+            f"| {s.get('tier', '')} "
+            f"| {s.get('status', '')} "
+            f"| {s.get('quality_score', 'N/A')} "
+            f"| {s.get('pin', 'N/A')} "
+            f"| {len(wa)} |"
+        )
+
+    quality_breakdown_rows = []
+    for s in completed:
+        qs = s.get("quality_score")
+        quality_breakdown_rows.append(f"- **{s['name']}**: {qs if qs is not None else 'N/A'}")
+
+    if not quality_breakdown_rows:
+        quality_breakdown_rows.append("No completed skills with quality scores.")
+
+    if all_workarounds:
+        workarounds_list_items = [f"- `{fp}`" for fp in all_workarounds]
+    else:
+        workarounds_list_items = ["No workarounds applied."]
+
+    duration_table_rows = []
+    for s in skills:
+        s_start = _parse_iso(s.get("started_at"))
+        s_end = _parse_iso(s.get("completed_at"))
+        s_start_str = s.get("started_at", "N/A") or "N/A"
+        s_end_str = s.get("completed_at", "N/A") or "N/A"
+        dur = _format_duration(s_start, s_end)
+        duration_table_rows.append(f"| {s.get('name', '')} | {s_start_str} | {s_end_str} | {dur} |")
+
+    failed_skipped_lines = []
+    if failed:
+        failed_skipped_lines.append("### Failed Skills\n")
+        for s in failed:
+            failed_skipped_lines.append(f"- **{s['name']}** (Tier {s.get('tier', '?')})")
+    if skipped:
+        failed_skipped_lines.append("\n### Skipped Skills\n")
+        for s in skipped:
+            failed_skipped_lines.append(f"- **{s['name']}** (Tier {s.get('tier', '?')})")
+    if not failed and not skipped:
+        if skills:
+            failed_skipped_lines.append("All skills completed successfully.")
+        else:
+            failed_skipped_lines.append("No skills in campaign.")
+
+    quality_gate = campaign.get("quality_gate", {})
+
+    return {
+        "campaign_name": campaign.get("name", ""),
+        "started_at": started_at_str or "N/A",
+        "completed_at": last_updated_str or "N/A",
+        "duration": _format_duration(started_at, last_updated),
+        "quality_gate_hard": quality_gate.get("hard", "N/A"),
+        "quality_gate_soft_target": str(quality_gate.get("soft_target", "N/A")),
+        "quality_gate_soft_fallback": str(quality_gate.get("soft_fallback", "N/A")),
+        "skills_completed": str(len(completed)),
+        "skills_failed": str(len(failed)),
+        "skills_skipped": str(len(skipped)),
+        "skills_table": "\n".join(skills_table_rows),
+        "quality_min": str(quality_min),
+        "quality_max": str(quality_max),
+        "quality_avg": str(quality_avg),
+        "quality_breakdown": "\n".join(quality_breakdown_rows),
+        "total_workarounds": str(len(all_workarounds)),
+        "skills_with_workarounds": str(skills_with_wa),
+        "workarounds_list": "\n".join(workarounds_list_items),
+        "duration_table": "\n".join(duration_table_rows),
+        "failed_skipped_section": "\n".join(failed_skipped_lines),
+    }
+
+
+def run(state_file: str, template_file: str, output_file: str) -> int:
+    state_path = Path(state_file)
+    template_path = Path(template_file)
+    output_path = Path(output_file)
+
+    if not state_path.is_file():
+        _emit_error(f"State file not found: {state_file}", "STATE_NOT_FOUND")
+        return 2
+
+    if not template_path.is_file():
+        _emit_error(f"Template file not found: {template_file}", "TEMPLATE_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
+
+    if not isinstance(state, dict):
+        _emit_error("State file root is not a mapping", "INVALID_STATE")
+        return 2
+
+    try:
+        template = template_path.read_text(encoding="utf-8")
+    except Exception as exc:
+        _emit_error(f"Failed to read template file: {exc}", "TEMPLATE_READ_ERROR")
+        return 2
+
+    try:
+        aggregates = _compute_aggregates(state)
+    except Exception as exc:
+        _emit_error(f"Failed to compute report aggregates: {exc}", "AGGREGATE_ERROR")
+        return 2
+
+    report = template
+    for key, value in aggregates.items():
+        report = report.replace("{{" + key + "}}", value)
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        output_path.write_text(report, encoding="utf-8")
+    except Exception as exc:
+        _emit_error(f"Failed to write report: {exc}", "WRITE_ERROR")
+        return 2
+
+    skills = state.get("skills", [])
+    completed_count = sum(1 for s in skills if s.get("status") == "completed")
+    failed_count = sum(1 for s in skills if s.get("status") == "failed")
+    quality_scores = {
+        s["name"]: s["quality_score"]
+        for s in skills
+        if s.get("status") == "completed" and s.get("quality_score") is not None
+    }
+
+    result = {
+        "status": "success",
+        "report_path": output_path.as_posix(),
+        "skills_completed": completed_count,
+        "skills_failed": failed_count,
+        "quality_scores": quality_scores,
+        "duration": aggregates["duration"],
+    }
+    json.dump(result, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Generate a campaign report from state and template.",
+    )
+    parser.add_argument("--state-file", required=True, help="Path to _campaign-state.yaml")
+    parser.add_argument("--template-file", required=True, help="Path to campaign-report-template.md")
+    parser.add_argument("--output-file", required=True, help="Path to write the generated report")
+    args = parser.parse_args()
+    return run(args.state_file, args.template_file, args.output_file)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())