bmad-module-skill-forge 1.8.0 → 2.0.0

package/src/skf-campaign/references/step-11-maintenance.md

@@ -0,0 +1,84 @@
+---
+nextStepFile: 'health-check.md'
+stateSchemaFile: 'assets/campaign-state-schema.json'
+stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
+backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+reportFile: '{campaignWorkspacePath}/campaign-report.md'
+reportScript: 'scripts/campaign-report.py'
+reportTemplate: '{reportTemplatePath}'
+validateScript: 'scripts/campaign-validate-state.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Maintenance
+
+## STEP GOAL:
+
+Generate a comprehensive campaign report from the accumulated state, emit the headless result envelope, and chain to the shared health check as the campaign's terminal step.
+
+## RULES
+
+- This step uses the **read-backup-modify-write** pattern.
+- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
+- Update `campaign.last_updated` to current ISO-8601 with timezone on every write.
+- Update `campaign.current_stage` to `10`.
+- If `{headless_mode}` is true, auto-proceed through confirmation gates. Emit the headless envelope on stdout.
+
+## TASKS
+
+### §1 — Read + Validate State
+
+Load `{stateFile}`. Run `uv run {validateScript} --state-file {stateFile}`; on non-zero, HALT (exit 3) with the script's `errors[]`.
+
+### §2 — Generate Campaign Report
+
+Invoke the campaign report script:
+
+```
+uv run {reportScript} \
+    --state-file {stateFile} \
+    --template-file {reportTemplate} \
+    --output-file {reportFile}
+```
+
+Capture the JSON result from stdout — it carries `skills_completed`, `skills_failed`, `quality_scores`, and `duration` already computed. Do not recompute these by hand in §3.
+
+**On success** (exit code 0): log the report path and summary stats from the result JSON.
+
+**On failure** (exit code 2): the campaign itself has already completed — do NOT discard it over a missing summary artifact. Display the error from stderr, log "report generation failed (degraded): {error}" to the decision log, set the envelope's `campaign_report_path` to `null`, and CONTINUE to §3. Surface `report-failure` only as a degraded signal in the envelope (`status:"error"`, `exit_code:10`), never as a hard halt that throws away a finished campaign.
+
+Display: "**Campaign report generated:** `{reportFile}`" (or, on degrade, "**Campaign complete — report generation failed (see decision log); state is intact.**")
+
+**Optional post-completion hook:** if `{onComplete}` (resolved in On Activation) is non-empty, invoke `{onComplete} --report-path={reportFile}`. Log the outcome to the decision log; a hook failure is recorded but never fails the campaign.
+
+### §3 — Emit Headless Envelope
+
+When `{headless_mode}` is true, emit the campaign result envelope on stdout, copying the counts, `quality_scores`, and `duration` straight from the §2 report-script result (do not recompute):
+
+```
+SKF_CAMPAIGN_RESULT_JSON: {"status":"success","skills_completed":N,"skills_failed":N,"quality_scores":{...},"campaign_report_path":"{reportFile}","decision_log":"{campaignWorkspacePath}/_campaign-decision-log.md","duration":"..."}
+```
+
+- `status`: "success" if the campaign completed normally (HARD HALTs emit the error variant per SKILL.md "Result Contract on HARD HALT")
+- `skills_completed` / `skills_failed` / `quality_scores` / `duration`: from the §2 report-script result JSON
+- `campaign_report_path`: `{reportFile}`
+- `decision_log`: path to the append-only decision log
+
+When not in headless mode, skip this section silently.
+
+### §4 — Stage Completion
+
+Set `campaign.current_stage` to `10`. Update `campaign.last_updated` to current ISO-8601 with timezone. Backup `{stateFile}` to `{backupFile}`, then write the updated state.
+
+### §5 — Chain to Health Check
+
+The operator's findings-routing consent (`campaign.health_findings_queue`) is applied by the terminal health-check step: `references/health-check.md` §1 reads it from state and carries it into the shared health check as the pre-decided opt-in (`"improvement"` → route non-bug findings to the shared improvement queue without re-prompting; `"local"` → local queue only). That is what makes the §2 setup consent prompt actionable rather than cosmetic — surface the active setting here for visibility.
+
+Display: "**Campaign complete.** Report at `{reportFile}`. Findings routing: {campaign.health_findings_queue}. Chaining to health check..."
+
+Chain to `{nextStepFile}` (shared/health-check.md).
+
+## OUTPUT
+
+Display campaign completion summary: skills completed, skills failed, report path, total duration. Chain to `{nextStepFile}`.

package/src/skf-campaign/references/step-resume.md

@@ -0,0 +1,114 @@
+---
+stateSchemaFile: 'assets/campaign-state-schema.json'
+stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
+backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+validateScript: 'scripts/campaign-validate-state.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Resume
+
+## STEP GOAL:
+
+Validate campaign state integrity, determine the resume point, and chain to the appropriate stage step file. This is a read-only routing step — it does not modify state.
+
+## RULES
+
+- This step is **read-only by default** — it does NOT modify `{stateFile}` except in the one recovery case below (restoring a valid `.bak` over a corrupt primary), which is the State Contract's advertised safety net.
+- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; the recovery path in §1 governs what happens on failure.
+- The chain target is determined dynamically from state — there is no fixed `nextStepFile`.
+- If `{headless_mode}` is true, auto-proceed through any confirmation gates with the default action and log each auto-decision.
+
+## TASKS
+
+### §1 — Read + Validate State (with `.bak` recovery)
+
+Load `{stateFile}`. If the file does not exist, HALT: "No campaign state found. Run `campaign` to start a new campaign."
+
+Run `uv run {validateScript} --state-file {stateFile}`. If it succeeds (exit 0), proceed to §2.
+
+If it fails (primary missing/corrupt YAML/schema-invalid), **attempt automatic recovery from the backup** rather than dead-halting — this is exactly the crash-during-write case the State Contract promises `.bak` covers:
+
+1. If `{backupFile}` exists, run `uv run {validateScript} --state-file {backupFile}`.
+2. If the backup is valid: copy `{backupFile}` over `{stateFile}`, log to the decision log "primary corrupt — recovered from backup as of {bak.last_updated}", inform the operator, and continue with the recovered state.
+3. If the backup is missing or also invalid: HALT with exit code 9 (`corrupt-state`), reporting both the primary and backup validation errors so the operator knows neither is usable.
+
+### §2 — Backup Consistency Check
+
+Check if `{backupFile}` exists.
+
+**If `.bak` does not exist:** warn "No backup file found — campaign may have been created but never modified." Continue.
+
+**If `.bak` exists** (and §1 did not already recover from it):
+
+1. Run `uv run {validateScript} --state-file {backupFile}`. If invalid, warn: "Backup file fails validation — cannot use for recovery." Continue with the primary.
+2. Compare primary vs backup. If `primary.campaign.last_updated < backup.campaign.last_updated` OR `primary.campaign.current_stage < backup.campaign.current_stage`, the primary looks behind the backup (possible crash during last write). Present a recovery choice:
+   - `[R]ecover` — copy `{backupFile}` over `{stateFile}` and resume from the backup's state.
+   - `[K]eep` — keep the primary as authoritative (the default).
+
+   In headless mode, default to `[K]eep` and log the auto-decision (a behind-backup primary may be intentional; never silently overwrite without a clear corruption signal — that case is handled in §1). Otherwise the primary is authoritative.
+
+### §3 — Determine Resume Point
+
+Two paths based on whether `--from=<skill>` was provided in the invocation:
+
+**With `--from=<skill>`:**
+
+1. Find the named skill in `skills[]` by `name`.
+2. If not found → HALT: "Unknown skill '{name}'. Known skills: {comma-separated list of all skill names from state}."
+3. If the skill's `status` is `"completed"`, `"failed"`, or `"skipped"`, the operator may have meant to re-run it (e.g. it passed with a low score) rather than skip past it. Present a choice:
+   - `[R]e-run` — reset the named skill to `"pending"` and resume from its stage. (Read-only step caveat: this single status reset follows read-backup-modify-write — back up first.)
+   - `[N]ext` — find the next skill in `dependency_graph.execution_order` after the named one whose `status` is `"pending"` or `"active"` and resume there. If none found → HALT: "All remaining skills are complete. Run `campaign` to start a new campaign."
+   - `[H]alt` — stop without resuming.
+
+   In headless mode, default to `[N]ext` and log the auto-decision. Log the chosen action to the decision log.
+4. If an active skill already exists in `skills[]` AND it is a different skill from the `--from` target, warn: "Skill '{active_name}' is currently active — honoring explicit --from override."
+5. Determine the target step file:
+   - Tier A skill with status `"pending"` or `"active"` → stage 4 (`step-05-skill-loop.md`)
+   - Tier B skill with status `"pending"` or `"active"` → stage 5 (`step-06-batch.md`)
+
+**Without `--from`:**
+
+1. Scan `skills[]` for any skill with `status == "active"`.
+   - If found and `tier == "A"` → resume target is stage 4 (`step-05-skill-loop.md`). The skill loop's §4 will skip completed skills until it reaches the active one.
+   - If found and `tier == "B"` → resume target is stage 5 (`step-06-batch.md`). The batch step processes Tier B skills.
+2. If no active skill → the next stage to run is `campaign.current_stage + 1`, because `current_stage` records the highest **completed** stage (each stage writes its own number only after its work and gates finish, so a mid-stage halt leaves the previous stage's number on disk). **Terminal cap:** if `campaign.current_stage` is `10`, the resolved stage is `10` itself (`step-11-maintenance.md`) — never `11`; the existing terminal-HALT check in §4 governs whether a stage-10 campaign is already done.
+3. Map the resolved stage number to the corresponding step file using the stage table in §4.
+
+### §4 — Resume Routing
+
+Map the resolved stage number to its step file. Both §3 branches feed this table an **already-resolved** stage number: the active-skill branch supplies stage 4 or 5 directly (and BYPASSES the `+1`), while the no-active-skill branch supplies `current_stage + 1` (terminal-capped at 10). Do not apply the `+1` again here.
+
+| Stage | Step File |
+|-------|-----------|
+| 0 | step-01-setup.md |
+| 1 | step-02-strategy.md |
+| 2 | step-03-pins.md |
+| 3 | step-04-provenance.md |
+| 4 | step-05-skill-loop.md |
+| 5 | step-06-batch.md |
+| 6 | step-07-capstone.md |
+| 7 | step-08-verify.md |
+| 8 | step-09-refine.md |
+| 9 | step-10-export.md |
+| 10 | step-11-maintenance.md |
+
+Display a resume summary before chaining:
+
+```
+CAMPAIGN RESUME: {campaign.name}
+
+  Resuming from: Stage {stage_number} — {stage_name}
+  Target skill:  {skill_name} (if --from was used, otherwise "auto-detected" or "N/A")
+  Skills completed: {completed_count} / {total_count}
+  Skills remaining: {pending_count} pending, {active_count} active, {failed_count} failed, {skipped_count} skipped
+  Last updated:  {campaign.last_updated}
+```
+
+If `campaign.current_stage` is `10` and all skills have status `"completed"`, `"failed"`, or `"skipped"`:
+HALT: "Campaign has reached its final stage. All skills have been processed."
+
+## OUTPUT
+
+Chain to the determined step file.

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

@@ -0,0 +1,235 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""Campaign Deps — dependency computation and enforcement for campaign skills.
+
+Two modes:
+  --compute: topological sort of all skills from depends_on edges
+  --check:   verify a single skill's dependencies are satisfied
+
+CLI:
+  uv run campaign-deps.py --compute --state-file <path>
+  uv run campaign-deps.py --check --state-file <path> --skill <name>
+  uv run campaign-deps.py --check --state-file <path> --skill <name> --force
+
+Output (JSON on stdout):
+  --compute:
+    {"execution_order": [...], "circular_deps_detected": bool, "cycle_participants": [...] | null}
+
+  --check:
+    {"skill": "name", "ready": bool, "unmet_deps": [...], "forced": bool}
+
+Exit codes:
+  0  success / ready / force-override
+  1  circular deps / unmet deps / dangling reference
+  2  error (missing file, bad YAML)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import heapq
+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 _build_skill_map(skills: List[Dict[str, Any]]) -> Dict[str, Dict[str, Any]]:
+    return {s["name"]: s for s in skills}
+
+
+def _validate_deps(
+    skill_map: Dict[str, Dict[str, Any]],
+) -> Optional[List[str]]:
+    dangling: List[str] = []
+    for name, skill in skill_map.items():
+        for dep in skill.get("depends_on", []) or []:
+            if dep not in skill_map:
+                dangling.append(f"{name} depends on unknown skill '{dep}'")
+    return dangling if dangling else None
+
+
+def compute(state_file: str) -> int:
+    path = Path(state_file)
+    if not path.is_file():
+        _emit_error(f"State file not found: {state_file}", "STATE_NOT_FOUND")
+        return 2
+
+    try:
+        state = _load_yaml(path)
+    except Exception as exc:
+        _emit_error(f"Failed to parse state file: {exc}", "STATE_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
+
+    skill_map = _build_skill_map(skills)
+
+    dangling = _validate_deps(skill_map)
+    if dangling:
+        _emit_error(
+            f"Dangling dependency references: {'; '.join(dangling)}",
+            "DANGLING_DEPENDENCY",
+        )
+        return 1
+
+    in_degree: Dict[str, int] = {name: 0 for name in skill_map}
+    adjacency: Dict[str, List[str]] = {name: [] for name in skill_map}
+
+    for name, skill in skill_map.items():
+        for dep in skill.get("depends_on", []) or []:
+            adjacency[dep].append(name)
+            in_degree[name] += 1
+
+    def _tier_key(n: str) -> tuple[int, str]:
+        return (0 if skill_map[n].get("tier") == "A" else 1, n)
+
+    heap: List[tuple[int, str]] = []
+    for n in skill_map:
+        if in_degree[n] == 0:
+            heapq.heappush(heap, _tier_key(n))
+
+    execution_order: List[str] = []
+
+    while heap:
+        _, current = heapq.heappop(heap)
+        execution_order.append(current)
+
+        for dependent in adjacency[current]:
+            in_degree[dependent] -= 1
+            if in_degree[dependent] == 0:
+                heapq.heappush(heap, _tier_key(dependent))
+
+    if len(execution_order) < len(skill_map):
+        cycle_participants = sorted(
+            n for n in skill_map if n not in set(execution_order)
+        )
+        output = {
+            "execution_order": execution_order,
+            "circular_deps_detected": True,
+            "cycle_participants": cycle_participants,
+        }
+        json.dump(output, sys.stdout, separators=(",", ":"))
+        sys.stdout.write("\n")
+        return 1
+
+    output = {
+        "execution_order": execution_order,
+        "circular_deps_detected": False,
+        "cycle_participants": None,
+    }
+    json.dump(output, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+    return 0
+
+
+def check(state_file: str, skill_name: str, force: bool = False) -> int:
+    path = Path(state_file)
+    if not path.is_file():
+        _emit_error(f"State file not found: {state_file}", "STATE_NOT_FOUND")
+        return 2
+
+    try:
+        state = _load_yaml(path)
+    except Exception as exc:
+        _emit_error(f"Failed to parse state file: {exc}", "STATE_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
+
+    skill_map = _build_skill_map(skills)
+
+    if skill_name not in skill_map:
+        _emit_error(f"Skill '{skill_name}' not found in state", "SKILL_NOT_FOUND")
+        return 2
+
+    deps = skill_map[skill_name].get("depends_on", []) or []
+    unmet: List[str] = []
+    for dep in deps:
+        if dep not in skill_map:
+            _emit_error(
+                f"Skill '{skill_name}' depends on unknown skill '{dep}'",
+                "DANGLING_DEPENDENCY",
+            )
+            return 1
+        if skill_map[dep].get("status") != "completed":
+            unmet.append(dep)
+
+    ready = len(unmet) == 0
+    forced = force and not ready
+
+    if forced:
+        json.dump(
+            {"warning": f"Forcing past unmet dependencies for '{skill_name}'", "unmet": unmet},
+            sys.stderr,
+        )
+        sys.stderr.write("\n")
+
+    output = {
+        "skill": skill_name,
+        "ready": ready,
+        "unmet_deps": unmet,
+        "forced": forced,
+    }
+    json.dump(output, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+
+    if not ready and not force:
+        return 1
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Campaign dependency computation and enforcement.",
+    )
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument(
+        "--compute",
+        action="store_true",
+        help="Compute execution order via topological sort",
+    )
+    mode.add_argument(
+        "--check",
+        action="store_true",
+        help="Check if a skill's dependencies are satisfied",
+    )
+    parser.add_argument("--state-file", required=True, help="Path to _campaign-state.yaml")
+    parser.add_argument("--skill", help="Skill name (required for --check)")
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force past dependency check (--check only)",
+    )
+    args = parser.parse_args()
+
+    if args.check and not args.skill:
+        parser.error("--skill is required when using --check")
+
+    if args.compute:
+        return compute(args.state_file)
+    return check(args.state_file, args.skill, force=args.force)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-campaign/scripts/campaign-parse-manifest.py

@@ -0,0 +1,119 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""Campaign Parse Manifest — deterministic parse of a --manifest target list.
+
+step-01 (Setup) seeds a headless campaign's targets from a plain-text manifest.
+Parsing that format by hand risks silently dropping a malformed line — exactly
+the kind of mechanical, all-or-nothing work that belongs in a script. This
+parser is the single source of truth for the format documented in SKILL.md
+"On Activation".
+
+Format (one target per line):
+
+    name,repo_url,tier,pin[;dep1,dep2,...]
+
+- `pin` may be empty (latest): `name,repo_url,tier,`  or  `name,repo_url,tier`
+- a trailing `;`-segment lists depends_on names (comma-separated)
+- blank lines and lines starting with `#` are skipped
+- `tier` must be `A` or `B`
+
+CLI:
+  uv run campaign-parse-manifest.py <path/to/manifest.txt>
+  cat manifest.txt | uv run campaign-parse-manifest.py -
+
+Output (JSON on stdout):
+  {"targets": [{"name","repo_url","tier","pin","depends_on"}], "errors": [{"line","message"}]}
+
+Exit codes:
+  0  parsed cleanly (no errors)
+  1  one or more malformed lines (errors[] populated; targets[] omits bad lines)
+  2  file error (not found / unreadable)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+
+def parse_manifest_text(text: str) -> Dict[str, Any]:
+    targets: List[Dict[str, Any]] = []
+    errors: List[Dict[str, Any]] = []
+    seen: set = set()
+
+    for lineno, raw in enumerate(text.splitlines(), start=1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+
+        body, sep, deps_part = line.partition(";")
+        fields = [f.strip() for f in body.split(",")]
+        if len(fields) < 3:
+            errors.append({"line": lineno, "message": f"expected `name,repo_url,tier[,pin]`, got {len(fields)} field(s)"})
+            continue
+
+        name, repo_url, tier = fields[0], fields[1], fields[2]
+        pin = fields[3] if len(fields) >= 4 and fields[3] != "" else None
+
+        if not name:
+            errors.append({"line": lineno, "message": "empty `name`"})
+            continue
+        if not repo_url:
+            errors.append({"line": lineno, "message": f"`{name}` has empty `repo_url`"})
+            continue
+        if tier not in ("A", "B"):
+            errors.append({"line": lineno, "message": f"`{name}` has invalid tier `{tier}` (must be A or B)"})
+            continue
+        if name in seen:
+            errors.append({"line": lineno, "message": f"duplicate target name `{name}`"})
+            continue
+        seen.add(name)
+
+        depends_on = [d.strip() for d in deps_part.split(",") if d.strip()] if sep else []
+
+        targets.append(
+            {"name": name, "repo_url": repo_url, "tier": tier, "pin": pin, "depends_on": depends_on}
+        )
+
+    return {"targets": targets, "errors": errors}
+
+
+def run(path: str) -> int:
+    if path == "-":
+        text = sys.stdin.read()
+    else:
+        p = Path(path)
+        if not p.is_file():
+            json.dump({"error": f"Manifest not found: {path}", "code": "MANIFEST_NOT_FOUND"}, sys.stderr)
+            sys.stderr.write("\n")
+            return 2
+        try:
+            text = p.read_text(encoding="utf-8")
+        except OSError as exc:
+            json.dump({"error": f"Manifest unreadable: {exc}", "code": "MANIFEST_READ_ERROR"}, sys.stderr)
+            sys.stderr.write("\n")
+            return 2
+
+    result = parse_manifest_text(text)
+    json.dump(result, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+    return 1 if result["errors"] else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="campaign-parse-manifest",
+        description="Parse a --manifest target list into structured targets.",
+    )
+    parser.add_argument("path", help="path to manifest text file, or `-` for stdin")
+    args = parser.parse_args(argv)
+    return run(args.path)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())