bmad-module-skill-forge 2.2.0 → 3.0.0

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

@@ -2,6 +2,10 @@
 stateSchemaFile: 'assets/campaign-state-schema.json'
 stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
 backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+briefFile: '{campaignWorkspacePath}/campaign-brief.yaml'
+resultContextFile: '{campaignWorkspacePath}/_result-context.json'
+decisionLogFile: '{campaignWorkspacePath}/_campaign-decision-log.md'
+stateScript: 'scripts/campaign-state.py'
 validateScript: 'scripts/campaign-validate-state.py'
 statusScript: 'scripts/campaign-status.py'
 ---
@@ -12,104 +16,69 @@ statusScript: 'scripts/campaign-status.py'
 
 ## 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.
+Validate campaign state integrity, recover it from its backup when it must, get the resume point from the state helper, and chain to that stage's step file.
 
 ## 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.
+- Leave state untouched except for the two recovery or reset choices below (§1 backup restore, §3 `[R]e-run`), each through `{stateScript}`, and on a non-zero exit HALT with the same code. A log entry is `uv run {stateScript} log --log-file {decisionLogFile} --type <decision|auto|event> --text '<entry>'`.
+- The chain target is the `step_file` the helper's `resume` operation (`{stateScript}`) returns: never work the stage out by hand.
+- If `{headless_mode}` is true, auto-proceed through any confirmation gates with the default action and log each auto-decision (type `auto`); emit the progress events, and at any HARD HALT the error envelope, per `references/campaign-contracts.md`. A campaign already complete (§3) is no error halt: it ends with the success line.
 
 ## TASKS
 
-### §1 — Read + Validate State (with `.bak` recovery)
+### §1: Read + Validate State (with `.bak` recovery)
 
-Load `{stateFile}`. If the file does not exist, HALT (exit code 2, `invalid-input`): "No campaign state found. Run `campaign` to start a new campaign."
+If neither `{stateFile}` nor `{backupFile}` exists, HALT (exit code 2, `invalid-input`): "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:
+If it fails (primary missing, corrupt YAML or schema-invalid), recover from the backup rather than dead-halting. `{stateScript}` writes atomically, so its writes never leave a broken primary: the cause is a hand edit, disk damage, or a state written before v3.0.0.
 
-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 deterministically: run `uv run {statusScript} --state-file {stateFile} --backup-file {backupFile}` and read `backup_comparison.primary_behind` (the script does the ISO-8601 timestamp and `current_stage` compares — do not order the timestamps by hand). If it is `true`, 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.
+```
+uv run {stateScript} recover --state-file {stateFile}
+```
 
-### §3 — Determine Resume Point
+It copies `{backupFile}` over `{stateFile}` only when the backup validates. On exit 0, log "primary corrupt: recovered from backup as of {last_updated}" (type `event`, with the `last_updated` it returns), inform the operator, and continue with the recovered state. On exit 9 (the backup is missing or invalid too), HALT with exit code 9 (`corrupt-state`), reporting both the primary's validation errors and the recover call's `errors[]`, so the operator knows neither is usable.
 
-Two paths based on whether `--from=<skill>` was provided in the invocation:
+### §2: Backup Check
 
-**With `--from=<skill>`:**
+Unless §1 recovered from it, check `{backupFile}`. When it does not exist, warn "No backup file found: campaign may have been created but never modified." When `uv run {validateScript} --state-file {backupFile}` fails, warn "Backup file fails validation: cannot use for recovery." Continue with the primary either way: each write copies the primary it replaces to `.bak`, so a valid primary is never older than its backup.
 
-1. Find the named skill in `skills[]` by `name`.
-2. If not found → HALT (exit code 2, `invalid-input`): "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 (exit code 0, campaign already complete): "All remaining skills are complete. Run `campaign` to start a new campaign."
-   - `[H]alt` — stop without resuming.
+### §3: Determine Resume Point
 
-   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`)
+Ask the state helper, passing `--from` when the invocation named a skill:
 
-**Without `--from`:**
+```
+uv run {stateScript} resume --state-file {stateFile} [--from <skill>]
+```
 
-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.
+It returns the stage to resume and its `step_file`, with the `reason`: `active-skill` (a skill an interruption left `active` resumes its own stage, with no `+1`: a Tier A skill the skill loop, which skips finished skills until it reaches it; a Tier B skill the batch stage, whose batch script, `campaign-render-batch.py`, selects the interrupted active Tier B skills together with the pending ones, so resume resets no status), `next-stage` (the stage after `current_stage`, the highest completed stage), `terminal-cap` (stage 10 runs again, never a stage 11), `from-skill` or `from-next`. Then:
 
-### §4 — Resume Routing
+- **`complete: true`:** nothing is left to resume, which is no error halt: stop with exit code 0 and display "Campaign has reached its final stage. All skills have been processed." (after `--next`: "All remaining skills are complete. Run `campaign` to start a new campaign.") In headless mode, end with the campaign's success line instead of an error envelope. When `reason` is `complete` and `{resultContextFile}` exists (step-11 §2 wrote it), run `uv run {emitEnvelopeHelper} emit --workflow skf-campaign < {resultContextFile}` (the shared emitter: Result Contract in `references/campaign-contracts.md`); otherwise give the same command `{"status": "success", "skills_completed": <completed>, "skills_failed": <failed>, "decision_log": "{decisionLogFile}"}` on stdin, with the counts `uv run {statusScript} --state-file {stateFile}` returns. Display the line it prints verbatim as the run's last line, with nothing after it.
+- **`stage` 1 with no `{briefFile}`:** Setup stopped after it wrote the state but before the brief, which every later stage reads: HALT (exit code 8, `missing-brief`): "Setup did not finish. Run `campaign` and choose overwrite to start the campaign again."
+- **Exit 2** (an unknown `--from` skill): HALT (exit code 2, `invalid-input`) with its `error`, which lists the known skills.
+- **`needs_choice: true`:** the `--from` skill is already `completed`, `failed` or `skipped` (`from_status`), and 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 it with `uv run {stateScript} set-skill --state-file {stateFile} --skill <skill> --status pending`, then run the `resume` call again: it now resumes that skill's stage.
+  - `[N]ext`: run the `resume` call again with `--next`, which resumes at the next pending or active skill after it in `dependency_graph.execution_order`.
+  - `[H]alt`: stop without resuming.
 
-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.
+  **GATE [default: N]**: in headless mode, default to `[N]ext` and log the auto-decision. Log the chosen action (type `decision`).
+- **`active_other`** set: warn "Skill '{active_other}' is currently active: honoring explicit --from override."
 
-| 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 |
+### §4: Resume Routing
 
-Derive the skill counts deterministically — `uv run {statusScript} --state-file {stateFile}` returns `completed`, `total`, and the per-status counts (`pending` / `active` / `failed` / `skipped`); do not hand-count `skills[]`. Display a resume summary before chaining:
+Derive the skill counts deterministically: `uv run {statusScript} --state-file {stateFile}` returns `completed`, `total`, and the per-status counts (`pending` / `active` / `failed` / `skipped`); do not hand-count `skills[]`. 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")
+  Resuming from: Stage {stage} ({step_file})
+  Target skill:  {skill} (if --from was used, otherwise "auto-detected" or "N/A")
   Skills completed: {completed} / {total}
   Skills remaining: {pending} pending, {active} active, {failed} failed, {skipped} skipped
   Last updated:  {campaign.last_updated}
 ```
 
-If `campaign.current_stage` is `10` and all skills have status `"completed"`, `"failed"`, or `"skipped"`:
-HALT (exit code 0, campaign already complete): "Campaign has reached its final stage. All skills have been processed."
-
 ## OUTPUT
 
-Chain to the determined step file.
+Chain to the `step_file` §3 returned (a file in `references/`).

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

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.9"
+# requires-python = ">=3.11"
 # dependencies = ["pyyaml"]
 # ///
 """Campaign Deps — dependency computation and enforcement for campaign skills.
@@ -8,6 +8,19 @@ Two modes:
   --compute: topological sort of all skills from depends_on edges
   --check:   verify a single skill's dependencies are satisfied
 
+A Tier A skill may not depend on a Tier B skill: Tier B skills are built in
+the batch stage, after the skill loop that builds Tier A skills, so the Tier A
+skill could never pass its dependency gate. --compute reports each such edge
+in `tier_inversions` and exits 1, so the strategy stage rejects the plan
+before any skill is built. That rule and the dangling-reference rule come
+from campaign-parse-manifest.py's dependency_problems, the one statement of
+both, so Setup and Strategy report the same entries.
+
+At a blocked skill, --check names the status of each unmet dependency and the
+headless default: `skip` when every unmet dependency failed or was skipped
+(it can never complete in this run), `halt` when one is still pending or
+active (an order the loop cannot follow).
+
 CLI:
   uv run campaign-deps.py --compute --state-file <path>
   uv run campaign-deps.py --check --state-file <path> --skill <name>
@@ -16,28 +29,41 @@ CLI:
 Output (JSON on stdout):
   --compute:
     {"execution_order": [...], "circular_deps_detected": bool,
-     "cycle_participants": [...] | null, "tier_counts": {"A": int, "B": int}}
+     "cycle_participants": [...] | null, "tier_counts": {"A": int, "B": int},
+     "tier_inversions": [{"skill": "<Tier A>", "depends_on": "<Tier B>"}]}
 
   --check:
-    {"skill": "name", "ready": bool, "unmet_deps": [...], "forced": bool}
+    {"skill": "name", "ready": bool, "unmet_deps": [...], "forced": bool,
+     "unmet_status": {"<dep>": "<status>"}, "default_action": "skip" | "halt" | null}
 
 Exit codes:
   0  success / ready / force-override
-  1  circular deps / unmet deps / dangling reference
+  1  circular deps / tier inversion / unmet deps / dangling reference
   2  error (missing file, bad YAML)
 """
 
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import sys
 import heapq
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List
 
 import yaml
 
+MANIFEST_SCRIPT = Path(__file__).resolve().with_name("campaign-parse-manifest.py")
+
+
+def _dependency_problems(skills: List[Dict[str, Any]]) -> Dict[str, List[Dict[str, str]]]:
+    """campaign-parse-manifest.py's dependency_problems (one rule for Setup and Strategy)."""
+    spec = importlib.util.spec_from_file_location("campaign_parse_manifest", MANIFEST_SCRIPT)
+    manifest = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(manifest)
+    return manifest.dependency_problems(skills)
+
 
 def _emit_error(message: str, code: str) -> None:
     json.dump({"error": message, "code": code}, sys.stderr)
@@ -53,17 +79,6 @@ 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():
@@ -89,7 +104,11 @@ def compute(state_file: str) -> int:
         if tier in tier_counts:
             tier_counts[tier] += 1
 
-    dangling = _validate_deps(skill_map)
+    problems = _dependency_problems(list(skill_map.values()))
+    dangling = [
+        f"{d['skill']} depends on unknown skill '{d['depends_on']}'"
+        for d in problems["dangling_depends_on"]
+    ]
     if dangling:
         _emit_error(
             f"Dangling dependency references: {'; '.join(dangling)}",
@@ -97,6 +116,8 @@ def compute(state_file: str) -> int:
         )
         return 1
 
+    inversions = problems["tier_inversions"]
+
     in_degree: Dict[str, int] = {name: 0 for name in skill_map}
     adjacency: Dict[str, List[str]] = {name: [] for name in skill_map}
 
@@ -133,20 +154,29 @@ def compute(state_file: str) -> int:
             "circular_deps_detected": True,
             "cycle_participants": cycle_participants,
             "tier_counts": tier_counts,
+            "tier_inversions": inversions,
         }
         json.dump(output, sys.stdout, separators=(",", ":"))
         sys.stdout.write("\n")
         return 1
 
+    if inversions:
+        _emit_error(
+            "Tier A skills depend on Tier B skills, which are built after them: "
+            + "; ".join(f"{i['skill']} depends on {i['depends_on']}" for i in inversions),
+            "TIER_INVERSION",
+        )
+
     output = {
         "execution_order": execution_order,
         "circular_deps_detected": False,
         "cycle_participants": None,
         "tier_counts": tier_counts,
+        "tier_inversions": inversions,
     }
     json.dump(output, sys.stdout, separators=(",", ":"))
     sys.stdout.write("\n")
-    return 0
+    return 1 if inversions else 0
 
 
 def check(state_file: str, skill_name: str, force: bool = False) -> int:
@@ -186,6 +216,13 @@ def check(state_file: str, skill_name: str, force: bool = False) -> int:
 
     ready = len(unmet) == 0
     forced = force and not ready
+    unmet_status = {dep: skill_map[dep].get("status") for dep in unmet}
+    if ready:
+        default_action = None
+    elif all(status in ("failed", "skipped") for status in unmet_status.values()):
+        default_action = "skip"
+    else:
+        default_action = "halt"
 
     if forced:
         json.dump(
@@ -199,6 +236,8 @@ def check(state_file: str, skill_name: str, force: bool = False) -> int:
         "ready": ready,
         "unmet_deps": unmet,
         "forced": forced,
+        "unmet_status": unmet_status,
+        "default_action": default_action,
     }
     json.dump(output, sys.stdout, separators=(",", ":"))
     sys.stdout.write("\n")