bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-brief-skill/references/write-brief.md

@@ -1,5 +1,4 @@
 ---
-briefSchemaFile: 'assets/skill-brief-schema.md'
 versionResolutionFile: 'references/version-resolution.md'
 qmdRegistrationFile: 'references/qmd-collection-registration.md'
 nextStepFile: 'health-check.md'
@@ -19,20 +18,15 @@ forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 
 # Step 5: Write Brief
 
-## STEP GOAL:
-
-To generate the complete skill-brief.yaml from the approved brief data and write it to the forge data folder, completing the brief-skill workflow.
-
 ## Rules
 
 - Focus only on writing the file — all decisions have been made
 - Do not change any field values without user request — the brief was already approved
-- Create the output directory if it doesn't exist
 - Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing success summary is NOT the terminal step
 - All user-facing output in `{communication_language}`; written artifact (`description`, `notes`) in `{document_output_language}`
 - **Determinism delegation:** YAML rendering, version-precedence, atomic write, the headless result envelope, and the QMD-collection registry mutation are all delegated to shared SKF scripts. The LLM's job in this step is to assemble inputs, branch on script results, and surface user-facing prose — not to render YAML, JSON envelopes, or YAML-mutation diffs in the model.
 
-## MANDATORY SEQUENCE
+## Sequence
 
 ### 1. Reference the Schema (LLM context only)
 
@@ -98,7 +92,7 @@ Assemble the brief context as a **flat** JSON object — every approved value is
   "scope_rationale":  null | {"recommended":"...","chosen":"...","accepted_recommendation":true|false,"heuristic":"...","reason":"...","recorded":"YYYY-MM-DD"},
   "scope_tier_a_include": null | ["{tier-A authoring-surface patterns — from step 03 §3c capture, or hydrated on a ratify run}"],
   "scope_amendments":     null | [{"path":"...","action":"...","reason":"...","date":"YYYY-MM-DD","workflow":"..."}],
-  "doc_urls":         null | [{"url": "...", "label": "..."}],
+  "doc_urls":         null | [{"url": "...", "label": "...", "source": "{optional: language-registry|readme-detection|homepage|pages-api|docs-folder}"}],
   "scripts_intent":   null | "{detect|none|free-text}",
   "assets_intent":    null | "{detect|none|free-text}",
   "source_authority": null | "{official|community|internal}",
@@ -163,7 +157,7 @@ The script derives `exit_code` deterministically from `halt_reason` (null→0, i
 
 The script enforces the success/error halt_reason invariant (success requires null halt_reason; error requires non-null). The `user-cancelled` halt_reason is accepted for completeness (interactive `[X]` Cancel sites in step 1/03/04) but never appears on the headless code path.
 
-Invocation sites (each pointed at this block, not duplicated): step 1 §1 (write-failed pre-resolution), step 1 §8 (input-missing/input-invalid GATE), step 5 §2b (overwrite-cancelled), step 5 §3 (input-invalid/write-failed from script). Step-01 §1 forge-tier-missing and step 2 §1 (target-inaccessible/gh-auth-failed) currently HALT without emitting an envelope — pre-existing gaps tracked separately, not addressed by this canonicalization.
+Invocation sites (each pointed at this block, not duplicated): step 1 §1 (write-failed pre-resolution; forge-tier-missing), step 1 §8 (input-missing/input-invalid GATE), step 2 §1 (target-inaccessible/gh-auth-failed), step 5 §2b (overwrite-cancelled), step 5 §3 (input-invalid/write-failed from script). The step 1 §1 forge-tier-missing and step 2 §1 target-inaccessible/gh-auth-failed sites emit through this block too, so every headless HALT class surfaces a `SKF_BRIEF_RESULT_JSON` envelope — there are no envelope-silent failure classes.
 
 When `{headless_mode}` is false, skip this section silently — no envelope is emitted.
 
@@ -203,10 +197,22 @@ After compilation, you can:
 
 **Brief-skill workflow complete.**"
 
-### 7. Chain to Health Check
+### 6b. On-Complete Hook (pipeline integration)
+
+If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it now — after the brief has been written (§3) and the result contract finalized (§4b) — as:
+
+```bash
+{onCompleteCommand} --result-path={brief_path}
+```
+
+where `{brief_path}` is the absolute path captured from the §3 response envelope (the freshly written `skill-brief.yaml`, the stable artifact a downstream consumer chains from).
 
-ONLY WHEN the brief file has been written and the success summary displayed will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.
+- On success: log to `workflow_warnings[]` as informational only if the hook emitted stderr (`on_complete hook stderr: …`); otherwise no entry.
+- On non-zero exit / process error: log to `workflow_warnings[]` (`on_complete hook failed (exit {code}): {stderr_snippet}`).
+- **Never fail the workflow on hook errors** — the hook is for pipeline integration (chaining into create-skill, Slack, dashboards, CI), not for gating brief production.
 
-## CRITICAL STEP COMPLETION NOTE
+When `{onCompleteCommand}` is empty (bundled default), skip this section entirely — no hook is invoked.
+
+### 7. Chain to Health Check
 
-This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the brief-skill workflow is fully done.
+Once the brief file has been written and the success summary displayed, load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.

package/src/skf-campaign/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: skf-campaign
+description: Campaign orchestration — multi-library skill production with dependency tracking, file-based state, and resume. Use when the user asks to "run a campaign" or "orchestrate skills."
+---
+
+# Campaign
+
+## Overview
+
+Orchestrates the production of 15+ skills across multiple sessions by driving them through the full SKF pipeline (brief, generate, compile, test, export) in dependency order. Campaign sits atop the pipeline ladder: it sequences the workflows that produce skills rather than producing artifacts itself. File-based state (`_campaign-state.yaml`) survives context death, enabling resume from any point.
+
+## Conventions
+
+- Bare paths (e.g. `references/step-01-setup.md`) resolve from the skill root.
+- `references/` holds the stage-chained step files plus reference specs (e.g. the `_campaign-directive.md` contract at `references/campaign-directive-spec.md`); `templates/`, `scripts/`, and `assets/` hold templates, deterministic helpers, and the state schema.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## Role
+
+You are a campaign orchestrator operating in Ferris's Management mode. You sequence workflows, track per-skill state, enforce quality gates, and ensure every skill reaches its target tier — while the individual pipeline workflows handle the actual artifact production.
+
+## On Activation
+
+Run these steps once, in order, before dispatching to Mode Routing.
+
+1. **Load config.** Read `{project-root}/_bmad/skf/config.yaml` and `{sidecar_path}/preferences.yaml` in one batched message (independent files). From config resolve `project_name`, `user_name`, `communication_language`, `document_output_language`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`. From preferences resolve `headless_mode` (default false). If the config file is missing, fall back to `forge_data_folder = forge-data`.
+
+2. **Resolve `{headless_mode}`** — true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `preferences.yaml`. Default: false.
+
+3. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow
+   ```
+
+   The script merges three layers (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If it fails or is missing, fall back to `{skill-root}/customize.toml` directly. Resolve each scalar now (so step files never repeat the conditional) and stash as workflow-context variables:
+
+   - `{campaignWorkspacePath}` ← `workflow.campaign_workspace_path` if non-empty, else `{forge_data_folder}/_campaign`
+   - `{qualityGateHard}` / `{qualityGateSoftTarget}` / `{qualityGateSoftFallback}` ← the `quality_gate_*` scalars (defaults `zero-critical-high` / `90` / `80`)
+   - `{reportTemplatePath}` ← `workflow.report_template_path` if non-empty, else `templates/campaign-report-template.md`
+   - `{kickoffTemplatePath}` ← `workflow.kickoff_template_path` if non-empty, else `templates/kickoff-template.md`
+   - `{briefTemplatePath}` ← `workflow.brief_template_path` if non-empty, else `templates/campaign-brief-template.yaml`
+   - `{onComplete}` ← `workflow.on_complete` (empty = no-op)
+
+   Load `workflow.persistent_facts` (literal sentences and `file:` references, globs expanded) and keep them in mind for the whole campaign — they are injected into every per-skill kickoff. Run any `activation_steps_prepend` before step 1 and any `activation_steps_append` after this step.
+
+4. **Parse CLI overrides** into the workflow context:
+
+   | Flag | Effect |
+   | --- | --- |
+   | `--headless` / `-H` | Force `{headless_mode} = true` (see step 2). |
+   | `--brief <file>` | Seed step-01 targets from a `campaign-brief.yaml` instead of interactive prompts. Implies `--headless`. |
+   | `--manifest <file>` | Seed step-01 targets from a plain-text `name,repo_url,tier,pin` manifest. Implies `--headless`. |
+   | `--from <skill>` | Resume override — see Mode Routing. |
+
+   If `--brief` or `--manifest` is set, force `{headless_mode} = true` (log "headless: coerced by --brief/--manifest" if it was false).
+
+   **`--manifest` format:** one `name,repo_url,tier,pin` target per line (empty `pin` = latest); a trailing `;dep1,dep2` segment sets `depends_on`; blank and `#` lines are skipped. A malformed line HALTs step-01 with the offending line numbers — never a partial target set.
+
+5. **Dispatch** per Mode Routing below.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- State-first — write state to disk before chaining to the next step or workflow
+- Read-backup-modify-write for all state mutations (State Contract in `references/campaign-contracts.md`)
+- Validate `_campaign-state.yaml` on every load by running `uv run scripts/campaign-validate-state.py --state-file {stateFile}` and HALT (exit code 3, `invalid-state`) on non-zero — never hand-validate the schema
+- Zero memory dependency — campaign state is 100% recoverable from disk; never rely on conversation context for progress tracking
+- Treat a missing or unparseable `SKF_*_RESULT_JSON` envelope from any sub-skill as a sub-skill failure; never write partial state from an unparsed envelope
+- Append a one-line entry to the campaign decision log (`{campaignWorkspacePath}/_campaign-decision-log.md`, append-only) at every operator or auto-decision (skip/force, overwrite, export cancel/proceed, `.bak` recovery, user-cancel) so rationale survives compaction and resume
+- **Universal cancel affordance** — at any interactive gate between Setup and the Export gate, `cancel`/`exit`/`:q` triggers a HARD HALT with **exit code 12 (`user-cancelled`)**: log it and leave state intact and resumable. Exception: the Export gate's own `[C]ancel` stays exit code 11 (`export-cancelled`) — never also emit 12 there, so an automator's exit-code branch stays deterministic. These keywords count only as a response *to a prompt*; a skill or campaign named `cancel`/`exit` supplied as data is never treated as a cancel.
+- Always communicate in `{communication_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- If `{headless_mode}` is true, emit a single-line JSON progress event to **stderr** at each step's entry, exit, and HARD HALT so schedulers stream live progress — event format in `references/campaign-contracts.md` (Headless Progress Events)
+
+## Stages
+
+| # | Step | File | Auto-proceed |
+|---|------|------|--------------|
+| 0 | Setup | references/step-01-setup.md | Yes |
+| 1 | Strategy | references/step-02-strategy.md | Yes |
+| 2 | Pin Validation | references/step-03-pins.md | Yes |
+| 3 | Provenance | references/step-04-provenance.md | Yes |
+| 4 | Skill Loop | references/step-05-skill-loop.md | Yes |
+| 5 | Tier B Batch | references/step-06-batch.md | Yes |
+| 6 | Capstone | references/step-07-capstone.md | Yes |
+| 7 | Verification | references/step-08-verify.md | Yes |
+| 8 | Refinement | references/step-09-refine.md | Yes |
+| 9 | Export | references/step-10-export.md | No (write-gate HALT) |
+| 10 | Maintenance | references/step-11-maintenance.md | Yes |
+
+**Stage numbering:** step files are 1-indexed (`step-01` … `step-11`); `campaign.current_stage` in state is 0-indexed, so step-`NN` runs stage `NN − 1` (step-01 = stage 0, step-11 = stage 10). `references/step-resume.md` §3–§4 own how a resolved stage maps back to its step file on resume (including the `current_stage + 1` advance when no skill is active).
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | `campaign` to start a new campaign; `campaign resume [--from=<skill>]` to resume from last active or specified skill; `campaign status` for a read-only progress summary |
+| **Outputs** | `_campaign-state.yaml` (state), `campaign-brief.yaml` (machine-generated brief), `campaign-report.md` (post-campaign summary), `_campaign-decision-log.md` (append-only rationale), `SKF_CAMPAIGN_RESULT_JSON` (headless envelope) — all under `{campaignWorkspacePath}` |
+
+## Contracts
+
+Exit codes, the HARD-HALT error envelope, the read-backup-modify-write **State Contract**, the headless success envelope, and per-step progress events live in `references/campaign-contracts.md` — consult it when you HALT, mutate state, or emit headless output.
+
+## Mode Routing
+
+On invocation:
+
+1. **`campaign resume [--from=<skill>]`** — load `references/step-resume.md` (validates state, recovers from backup, chains to the right stage). `--from=<skill>` overrides the resume point to the named skill.
+2. **`campaign`** (new, no existing state) — run from stage 0 (Setup).
+3. **`campaign`** (state exists) — detect existing `{campaignWorkspacePath}/_campaign-state.yaml` and prompt **resume** (via `references/step-resume.md`) or **overwrite**. On overwrite, first archive the existing `_campaign-state.yaml` and `campaign-brief.yaml` to `{campaignWorkspacePath}/archive/{name}-{timestamp}/` and log it before chaining to step-01. In headless mode, default to **resume** (never silently clobber); archive-and-overwrite only when `--brief`/`--manifest` explicitly seeds a new campaign.
+4. **`campaign status`** (read-only) — load `{campaignWorkspacePath}/_campaign-state.yaml`, validate it via `campaign-validate-state.py`, then run `uv run scripts/campaign-status.py --state-file {campaignWorkspacePath}/_campaign-state.yaml` and display its summary (campaign name, current stage, completed-vs-total, per-status counts) followed by the last ~15 lines of `{campaignWorkspacePath}/_campaign-decision-log.md` for the recent decision trail, then stop. No backup, no mutation, no chaining. Exit 0 (or 9 if the state is unrecoverable).

package/src/skf-campaign/assets/campaign-state-schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "campaign-state",
+  "description": "Schema for _campaign-state.yaml — single source of truth for campaign orchestration state",
+  "type": "object",
+  "required": ["campaign", "skills", "dependency_graph"],
+  "additionalProperties": false,
+  "properties": {
+    "campaign": {
+      "type": "object",
+      "required": ["name", "started_at", "last_updated", "current_stage", "quality_gate", "health_findings_queue"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "started_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "last_updated": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "current_stage": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10
+        },
+        "directive_path": {
+          "type": "string"
+        },
+        "quality_gate": {
+          "type": "object",
+          "required": ["hard", "soft_target", "soft_fallback"],
+          "additionalProperties": false,
+          "properties": {
+            "hard": {
+              "type": "string"
+            },
+            "soft_target": {
+              "type": "number"
+            },
+            "soft_fallback": {
+              "type": "number"
+            }
+          }
+        },
+        "health_findings_queue": {
+          "type": "string",
+          "enum": ["local", "improvement"]
+        },
+        "architecture_doc_path": {
+          "type": ["string", "null"],
+          "description": "Path to the architecture document consumed by the verify (Stage 7) and refine (Stage 8) stages. Sourced at setup; null when the campaign runs no verification."
+        },
+        "capstone": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "description": "Capstone (stack) outcome composed from all completed campaign skills (Tier A and Tier B). Campaign-level summary; the composed skill itself lives at skill_path.",
+          "properties": {
+            "skill_path": {
+              "type": ["string", "null"]
+            },
+            "quality_score": {
+              "type": ["number", "null"]
+            },
+            "verified": {
+              "type": ["boolean", "null"]
+            },
+            "completed_at": {
+              "type": ["string", "null"],
+              "format": "date-time"
+            }
+          }
+        },
+        "verification": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "description": "Stage 7 verify-stack summary. Detailed findings live in the external report at report_path.",
+          "properties": {
+            "report_path": {
+              "type": ["string", "null"]
+            },
+            "overall_verdict": {
+              "type": ["string", "null"],
+              "enum": ["Verified", "Plausible", "Risky", "Blocked", null]
+            },
+            "coverage_percentage": {
+              "type": ["number", "null"]
+            },
+            "recommendation_count": {
+              "type": ["integer", "null"]
+            }
+          }
+        },
+        "refinement": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "description": "Stage 8 refine-architecture summary. The refined document lives at refined_path.",
+          "properties": {
+            "refined_path": {
+              "type": ["string", "null"]
+            },
+            "gap_count": {
+              "type": ["integer", "null"]
+            },
+            "issue_count": {
+              "type": ["integer", "null"]
+            },
+            "improvement_count": {
+              "type": ["integer", "null"]
+            }
+          }
+        }
+      }
+    },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "status", "tier"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pending", "active", "completed", "failed", "skipped"]
+          },
+          "depends_on": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "tier": {
+            "type": "string",
+            "enum": ["A", "B"]
+          },
+          "pin": {
+            "type": ["string", "null"]
+          },
+          "brief_path": {
+            "type": ["string", "null"]
+          },
+          "skill_path": {
+            "type": ["string", "null"]
+          },
+          "quality_score": {
+            "type": ["number", "null"]
+          },
+          "workarounds_applied": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "started_at": {
+            "type": ["string", "null"],
+            "format": "date-time"
+          },
+          "completed_at": {
+            "type": ["string", "null"],
+            "format": "date-time"
+          },
+          "commit_sha": {
+            "type": ["string", "null"]
+          }
+        }
+      }
+    },
+    "dependency_graph": {
+      "type": "object",
+      "required": ["execution_order", "circular_deps_detected"],
+      "additionalProperties": false,
+      "properties": {
+        "execution_order": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "circular_deps_detected": {
+          "type": "boolean"
+        }
+      }
+    }
+  }
+}

package/src/skf-campaign/customize.toml

@@ -0,0 +1,75 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-campaign.
+# Team overrides:     _bmad/custom/skf-campaign.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-campaign.user.toml (under {project-root})
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (config load, customization
+# resolve). Overrides append. Use for org-wide pre-flight checks (auth,
+# network, compliance) that must precede any orchestration work.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole campaign
+# (house style, naming conventions, quality guardrails). These are injected
+# into every per-skill kickoff, so project-scoped house facts propagate to
+# the whole campaign. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All skills must cite their upstream source."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/skill-style.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Workspace path ---
+#
+# Where the campaign keeps its state, backup, brief, batch input, archive,
+# and decision log. Empty string = use the bundled default
+# `{forge_data_folder}/_campaign`. Override to relocate campaign artifacts
+# (e.g. a shared volume) without editing every step file. Resolved once in
+# On Activation as {campaignWorkspacePath}.
+
+campaign_workspace_path = ""
+
+# --- Quality gate ---
+#
+# Campaign-wide quality bar applied to every skill. Scalars override the
+# bundled defaults; the per-campaign brief and any directive `## Quality
+# Overrides` still take precedence at runtime. Override here to change the
+# org-wide default without forking the skill.
+
+quality_gate_hard = "zero-critical-high"
+quality_gate_soft_target = 90
+quality_gate_soft_fallback = 80
+
+# --- Optional template overrides ---
+#
+# Lift the canonical template paths so orgs can substitute house-style copies
+# without forking the skill. Empty string = use the bundled default under
+# `templates/`.
+
+report_template_path = ""
+kickoff_template_path = ""
+brief_template_path = ""
+
+# Optional post-completion hook. When non-empty, the workflow invokes:
+#   <on_complete> --report-path=<path-to-campaign-report.md>
+# after the campaign report is finalized (step-11). Failures are logged to
+# the decision log but never fail the campaign. Empty = no-op.
+on_complete = ""

package/src/skf-campaign/manifest.yaml

@@ -0,0 +1,15 @@
+code: CA
+name: skf-campaign
+description: "Campaign orchestration — multi-library skill production with dependency tracking"
+version: "2.0.0"
+trigger: campaign
+parent_module: skf
+
+# Canonical internal filenames for the campaign workspace. Fixed contract (the
+# step chain references these names directly and test-skf-campaign-state guards
+# them against drift) — NOT an operator-override surface; customize.toml is the
+# only customization mechanism.
+config:
+  state_file: "_campaign-state.yaml"
+  backup_file: "_campaign-state.yaml.bak"
+  directive_file: "_campaign-directive.md"

package/src/skf-campaign/references/campaign-contracts.md

@@ -0,0 +1,67 @@
+<!-- Config: communicate in {communication_language}. -->
+
+# Campaign Contracts
+
+The self-contained contracts consulted at a specific moment — when a step HALTs, mutates state, or emits the final headless envelope. Each stands alone so it survives context compaction.
+
+## Exit Codes
+
+Every HARD HALT exits with a stable, documented code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning              | Raised by                                                   |
+| ---- | -------------------- | ----------------------------------------------------------- |
+| 0    | success              | step-11 (terminal); step-resume §3–§4 (campaign already complete — nothing to resume) |
+| 2    | invalid-input        | step-01 §1 (no targets, or a malformed `--manifest` line); steps 02/03/04/06 §4 (a helper reports unreadable input or a required tool such as `gh` unavailable); step-resume §1/§3 (resume targets a missing campaign or unknown skill) |
+| 3    | invalid-state        | any step §1 (`campaign-validate-state.py` non-zero on load) |
+| 4    | circular-deps        | step-02 §5 (a dependency cycle, or a dangling `depends_on` reference — either way the graph cannot be ordered) |
+| 5    | invalid-pin          | step-03 §5                                                  |
+| 6    | inaccessible-repo    | step-04 §5                                                  |
+| 7    | dependency-deadlock  | step-05 §4 (no skill ready and no recovery chosen)          |
+| 8    | missing-brief        | step-03/04/05 §2 and step-06 §4 (brief missing/unreadable, or a Tier B target has no matching brief entry) |
+| 9    | corrupt-state        | step-resume §1 (primary unrecoverable, `.bak` also invalid) |
+| 10   | report-failure       | step-11 §2 — **degraded only**: the report could not be generated; the campaign still completes and state stays intact (never a hard halt that discards a finished campaign) |
+| 11   | export-cancelled     | step-10 §4 (operator chose `[C]ancel` — graceful, resumable) |
+| 12   | user-cancelled       | any interactive gate (operator typed `cancel` / `exit` / `:q` at a prompt between Setup and the Export gate — graceful, resumable) |
+
+## Result Contract on HARD HALT
+
+In addition to the success-variant envelope (see Campaign Headless Envelope below), every HARD HALT emits an **error variant** so automators don't silently break. Emit one line on **stderr**:
+
+```
+SKF_CAMPAIGN_RESULT_JSON: {"status":"error","exit_code":<N>,"phase":"<slug>","error":{"code":"<class>","message":"<short>"},"skills_completed":N,"skills_failed":N,"campaign_report_path":null,"decision_log":"<path-or-null>"}
+```
+
+`<class>` is the Exit Codes meaning (e.g. `circular-deps`, `inaccessible-repo`); `<slug>` is the step where the HALT occurred. One line, no pretty-print.
+
+## State Contract
+
+All state mutations follow the read-backup-modify-write pattern:
+
+1. **Read** `_campaign-state.yaml`
+2. **Validate** via `uv run scripts/campaign-validate-state.py --state-file {stateFile}` (halt on invalid)
+3. **Backup** — copy current `_campaign-state.yaml` to `_campaign-state.yaml.bak`
+4. **Modify** in memory
+5. **Update** `campaign.last_updated` to current ISO-8601 timestamp
+6. **Write** modified state back to `_campaign-state.yaml`
+
+The `.bak` file is one-deep (overwritten on every write). If the primary file is corrupted (crash during write), the `.bak` file contains the last valid state — step-resume §1 recovers from it automatically rather than dead-halting.
+
+## Campaign Headless Envelope
+
+When `{headless_mode}` is true, the final step emits a single-line JSON envelope on stdout:
+
+```
+SKF_CAMPAIGN_RESULT_JSON: {"status":"success|error","skills_completed":0,"skills_failed":0,"quality_scores":{},"campaign_report_path":"","decision_log":"","duration":""}
+```
+
+`status` is `"success"` when the campaign completes normally, `"error"` on any unrecoverable halt (with `exit_code` per the Exit Codes table — see Result Contract on HARD HALT above). `skills_completed` and `skills_failed` count per-skill outcomes. `quality_scores` maps skill names to their test-skill scores. `campaign_report_path` points to the generated `campaign-report.md`. `decision_log` points to `_campaign-decision-log.md`. `duration` is the wall-clock time of the campaign run. Populate the counts, `quality_scores`, and `duration` directly from the `campaign-report.py` result JSON (step-11 §2) — do not recompute them by hand.
+
+## Headless Progress Events
+
+When `{headless_mode}` is true, emit a single-line JSON progress event to **stderr** at each step's entry, exit, and HARD HALT, so schedulers stream live progress instead of post-mortem-parsing the final envelope:
+
+- entry: `{"stage":N,"name":"<slug>","status":"start"}`
+- exit (just before chaining): `{"stage":N,"name":"<slug>","status":"done"}`
+- on HARD HALT: `{"stage":N,"name":"<slug>","status":"halt","exit":<code>}` instead of `"done"`
+
+`N` is the 0-indexed stage number (0–10) and `<slug>` is the kebab portion of the step filename. For the non-numbered routing/terminal steps (`resume`, `health-check`) emit `"stage":null` with the slug. One line per event; do not pretty-print.

package/src/skf-campaign/references/campaign-directive-spec.md

@@ -0,0 +1,32 @@
+---
+stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
+directiveFile: '_campaign-directive.md'
+---
+
+# Campaign Directive Specification
+
+Canonical contract for the campaign directive (`_campaign-directive.md`) — a
+file-based standing directive holding campaign-wide policy. When a step loads
+`campaign.directive_path` it re-reads the file fresh from disk at stage entry
+(no caching, so operator edits between stages are picked up) and applies the
+sections below as campaign-wide context. UTF-8 markdown; frontmatter not
+required; default filename `_campaign-directive.md`.
+
+## Recognized Sections
+
+All optional — the directive may hold any combination of these, or none:
+
+- **`## Quality Overrides`** — operator adjustments to quality gates for specific skills or the whole campaign.
+- **`## Skip List`** — skills to skip during processing, with rationale.
+- **`## Pipeline Flags`** — per-skill or campaign-wide pipeline modifiers.
+- **`## Notes`** — free-form operator context for the agent processing the campaign.
+
+Any heading not listed above is treated as general guidance: read it and apply
+judgment based on the content. This lets operators add ad-hoc context without
+modifying this specification.
+
+## Absence Behavior
+
+- If `campaign.directive_path` is not set in the state file: no error, proceed with defaults
+- If `campaign.directive_path` is set but the file does not exist at that path: no error, proceed with defaults
+- The directive is always optional — a campaign runs identically without one

package/src/skf-campaign/references/health-check.md

@@ -0,0 +1,35 @@
+---
+# Note: `shared/health-check.md` resolves relative to the SKF module root
+# ({project-root}/_bmad/skf/ when installed, {project-root}/src/ during
+# development), NOT relative to this step file.
+nextStepFile: 'shared/health-check.md'
+stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Workflow Health Check
+
+## STEP GOAL:
+
+Apply the operator's findings-routing consent, then chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of skf-campaign — after the shared health check completes, the workflow is fully done.
+
+## Rules
+
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 11.
+- The ONLY processing permitted here is reading the routing preference (below) and carrying it into `{nextStepFile}`; otherwise delegate directly with no additional commentary.
+
+## MANDATORY SEQUENCE
+
+### 1. Apply findings-routing consent
+
+Read `campaign.health_findings_queue` from `{stateFile}` and carry it into the shared health check as the operator's **already-decided** routing consent (so the shared step does not re-prompt, satisfying its "explicit opt-in" requirement for non-bug findings):
+
+- `"improvement"` — the operator opted in at setup: route this campaign's friction/gap findings to the shared improvement queue (the shared step's opt-in is pre-satisfied; do not re-prompt).
+- `"local"` (default) — keep findings in the local queue only; do not submit to the shared queue.
+
+If the state file is unreadable, default to `"local"` (never submit without consent).
+
+### 2. Delegate
+
+Load `{nextStepFile}`, read it fully, then execute it — applying the routing consent from step 1.