bmad-module-skill-forge 2.0.0 → 2.0.1

package/src/skf-campaign/SKILL.md

@@ -7,12 +7,12 @@ description: Campaign orchestration — multi-library skill production with depe
 
 ## 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 at the top of the pipeline ladder — it does not produce skill artifacts directly but sequences the workflows that do. File-based state (`_campaign-state.yaml`) survives context death, enabling resume from any point.
+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 step files chained by stage number, plus the directive contract at `references/campaign-directive-spec.md` (the canonical spec for `_campaign-directive.md`); `templates/` holds workflow-loaded templates; `scripts/` and `assets/` hold deterministic helpers and the state schema.
+- `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.
@@ -41,7 +41,7 @@ Run these steps once, in order, before dispatching to Mode Routing.
    - `_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. Apply the fallback for each scalar now so step files never repeat the conditional, and stash as workflow-context variables:
+   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`)
@@ -52,8 +52,6 @@ Run these steps once, in order, before dispatching to Mode Routing.
 
    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.
 
-   Every step file resolves its frontmatter path vars (`stateFile`, `backupFile`, …) under `{campaignWorkspacePath}` — overriding `campaign_workspace_path` relocates the whole campaign workspace without editing a single step.
-
 4. **Parse CLI overrides** into the workflow context:
 
    | Flag | Effect |
@@ -65,7 +63,7 @@ Run these steps once, in order, before dispatching to 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 target per line, comma-separated `name,repo_url,tier,pin` (omit `pin` or leave it empty for latest); add a trailing `;dep1,dep2` segment for `depends_on`. Blank lines and `#` comments are skipped. If any line fails to parse, HALT in step-01 listing the offending line numbers rather than silently dropping targets — a partial target set is never run.
+   **`--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.
 
@@ -74,20 +72,15 @@ Run these steps once, in order, before dispatching to Mode Routing.
 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 (see State Contract below)
+- 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 (NFR-2) — campaign state is 100% recoverable from disk; never rely on conversation context for progress tracking
+- 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 decision or auto-decision (skip/force, architecture-doc skip, export cancel/proceed, campaign overwrite, `.bak` recovery, user-cancel) so rationale survives compaction and resume
-- **Universal cancel affordance** — at any interactive gate the operator may type `cancel`, `exit`, or `:q` to leave cleanly. HARD HALT with **exit code 12 (`user-cancelled`)**, log the cancellation to the decision log, and leave state intact and resumable. This gives the operator a documented way out at every prompt between Setup and the Export gate. **The Export gate is the one exception:** it has its own `[C]ancel` with exit code 11 (`export-cancelled`), which remains canonical there — do not also emit 12 at the export gate, so an automator's exit-code branch stays deterministic. These keywords are recognized only as a response *to an interactive prompt*; a skill or campaign named `cancel`/`exit` supplied as data is never treated as a cancel.
+- 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 and exit 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 stage number (0–10, per the Stages table) 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.
+- 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
 
@@ -105,86 +98,24 @@ These rules apply to every step in this workflow:
 | 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` (e.g. step-01 = stage 0, step-11 = stage 10). The Resume Routing table in `references/step-resume.md` maps a resolved stage number to its step file; because `current_stage` records the highest *completed* stage, resume without an active skill advances to `current_stage + 1` (the stage that still needs to run) before consulting the table.
+**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 |
-| **Overrides** | `--headless` / `-H`, `--brief <file>`, `--manifest <file>`, `--from <skill>` — see On Activation step 4 |
-| **Gates** | Step 9 (Export): write-gate HALT — requires explicit user approval before writing exported skills to disk |
 | **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}` |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
-| **Exit codes** | See "Exit Codes" below |
-
-## 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)                                          |
-| 3    | invalid-state        | any step §1 (`campaign-validate-state.py` non-zero on load) |
-| 4    | circular-deps        | step-02 §5                                                  |
-| 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 (brief missing or unreadable)              |
-| 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` — graceful, resumable; see Workflow Rules) |
 
-## Result Contract on HARD HALT
+## Contracts
 
-In addition to the success-variant envelope (see Campaign Headless Envelope), 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.
+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 integrity, checks backup consistency, and chains to the appropriate stage step file. If `--from=<skill>` is provided, override the resume point to the named skill.
+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** with a new campaign. On overwrite, first archive the existing `_campaign-state.yaml` and `campaign-brief.yaml` to `{campaignWorkspacePath}/archive/{name}-{timestamp}/`, log the archive to the decision log, and show a one-line summary of what is being set aside 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`, display the Resume Detection summary block followed by the last ~15 lines of `{campaignWorkspacePath}/_campaign-decision-log.md` (so the operator sees the recent decision trail without flooding the terminal on a long campaign), then stop. No backup, no mutation, no chaining. Exit 0 (or 9 if the state is unrecoverable).
-
-## Resume Detection
-
-When resuming:
-
-1. Read `_campaign-state.yaml`
-2. Validate via `campaign-validate-state.py` (halt on invalid; attempt `.bak` recovery per step-resume)
-3. Find last active or completed stage from `campaign.current_stage` (the highest completed stage); when no skill is active, resume continues from the stage *after* it (`current_stage + 1`, terminal-capped)
-4. Skip completed skills (status = `completed` or `skipped`)
-5. If `--from=<skill>` is provided, find the named skill and resume from its stage
-6. Continue from the next incomplete skill in `dependency_graph.execution_order`
-
-## 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). `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.
+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/customize.toml

@@ -1,6 +1,8 @@
 # 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]
 

package/src/skf-campaign/manifest.yaml

@@ -5,6 +5,10 @@ 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"

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

@@ -5,117 +5,28 @@ directiveFile: '_campaign-directive.md'
 
 # Campaign Directive Specification
 
-This is the **canonical contract** for the campaign directive. SKILL.md and the
-step files' "Read Directive" sections defer to it rather than re-specifying the
-format — when a step loads `campaign.directive_path`, it applies the contents
-per the sections below.
-
-## Purpose
-
-The campaign directive (`_campaign-directive.md`) is a file-based standing directive that provides campaign-wide policy persisting across context boundaries. It is:
-
-- **Human-readable** — plain markdown, editable with any text editor
-- **Auditable** — version-controllable alongside campaign artifacts
-- **Context-boundary safe** — re-read from disk at each stage transition, with no dependency on LLM memory (NFR-2)
-
-The directive allows the operator to adjust campaign-wide policy without editing the state file or relying on LLM memory.
-
-## File Format
-
-- **Encoding:** UTF-8 markdown
-- **Frontmatter:** not required (plain content is sufficient)
-- **Location:** the path specified by `campaign.directive_path` in the campaign state file
-- **Default filename:** `_campaign-directive.md` (configured in `manifest.yaml` as `config.directive_file`)
+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 sections are optional. The directive may contain any combination of these, or none at all.
-
-### `## Quality Overrides`
-
-Operator adjustments to quality gates for specific skills or the entire campaign.
-
-Example:
-```markdown
-## Quality Overrides
-
-- Accept 85% for library-x due to incomplete upstream docs
-- Lower soft gate to 70% for experimental-sdk (early-stage repo)
-```
-
-### `## Skip List`
-
-Skills to skip during processing, with rationale.
-
-Example:
-```markdown
-## Skip List
-
-- Skip library-y — upstream repo is in maintenance mode
-- Skip legacy-tool — will be removed in next sprint
-```
-
-### `## Pipeline Flags`
+All optional — the directive may hold any combination of these, or none:
 
-Per-skill or campaign-wide pipeline modifiers.
+- **`## 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.
 
-Example:
-```markdown
-## Pipeline Flags
-
-- Use `--pin main` for all unpinned skills
-- Force forge-auto mode for large-repo-z
-```
-
-### `## Notes`
-
-Free-form operator context for the LLM agent processing the campaign.
-
-Example:
-```markdown
-## Notes
-
-Focus on documentation quality this run — the team is preparing for an external audit.
-Prioritize skills that feed into the public API layer.
-```
-
-## Unrecognized Sections
-
-Any section heading not listed above is treated as general guidance. The LLM agent reads and applies judgment based on the content. This allows operators to add ad-hoc context without modifying the specification.
-
-## Read Contract
-
-The directive is read from the path stored in `campaign.directive_path` (in the campaign state file) at stage entry. Every step that loads state and performs actionable processing checks for and applies the directive.
-
-Steps that read the directive:
-- **step-02-strategy** — applies directive contents as campaign-wide context for strategy processing (e.g. `## Notes` visible while reviewing the computed order; the order itself is computed deterministically by `campaign-deps.py`)
-- **step-05-skill-loop** — directive populates `{{directive_content}}` in kickoff template and provides campaign-wide context for all skill processing
-- **step-06-batch** — operator may want skip/quality overrides for Tier B batch processing
-- **step-08-verify** — operator may want to influence verification focus areas
-- **step-09-refine** — operator may want to guide refinement priorities
-- **step-10-export** — operator may want to exclude specific skills from export
-
-Steps that do NOT read the directive:
-- **step-01-setup** — creates the state file; `directive_path` is collected as input, not read
-- **step-03-pins** — pin validation is deterministic (Python script); directive cannot influence gh API calls
-- **step-04-provenance** — repo access verification is deterministic; directive cannot influence commit SHA recording
-- **step-07-capstone** — SS compose-mode is mechanical aggregation; no operator policy applies
-- **step-11-maintenance** — report generation is templated; health check is autonomous
-- **step-resume** — routing step, not a processing step
+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
-
-## Modification Contract
-
-The operator may edit the directive file at any time between stages. The next stage that reads the directive will pick up the updated version. There is no caching — the directive is always read fresh from disk at stage entry.
-
-## Lifecycle
-
-1. **Created:** before or during Stage 0 (setup) — the operator provides the file path, or it defaults to `_campaign-directive.md`
-2. **Read:** at each stage entry by applicable steps (see Read Contract above)
-3. **Modified:** at any time between stages by the operator
-4. **Consumed:** by the LLM agent as campaign-wide context influencing processing decisions

package/src/skf-campaign/references/step-01-setup.md

@@ -16,7 +16,7 @@ manifestScript: 'scripts/campaign-parse-manifest.py'
 
 Collect campaign inputs from the operator, create the initial `_campaign-state.yaml`, and generate `campaign-brief.yaml` so the campaign has a persistent starting point that survives context death.
 
-This is the only step that creates the state file (it does not yet exist). All subsequent steps use **read-backup-modify-write** per the State Contract in SKILL.md.
+This is the only step that creates the state file (it does not yet exist). All subsequent steps use **read-backup-modify-write** per the State Contract in `references/campaign-contracts.md`.
 
 ## RULES
 
@@ -40,9 +40,9 @@ Accept from the operator (or, in headless mode, from the `--brief`/`--manifest`
 - `directive_path` (optional) — path to a `_campaign-directive.md` file with operator directives (contract: `references/campaign-directive-spec.md`)
 - `architecture_doc_path` (optional) — path to the architecture document the verify (Stage 7) and refine (Stage 8) stages consume. If omitted here, those stages discover it at runtime (`docs/architecture.md`, then `_bmad-output/planning-artifacts/architecture.md`). Capturing it now persists the choice across resume and avoids re-prompting.
 
-When seeding from `--manifest`, parse it deterministically: `uv run {manifestScript} <manifest-file>`. If the result's `errors[]` is non-empty (exit 1), HALT listing the offending line numbers — never run a partial target set. When seeding from `--brief`, read the existing `campaign-brief.yaml` directly.
+When seeding from `--manifest`, parse it deterministically: `uv run {manifestScript} <manifest-file>`. If the result's `errors[]` is non-empty (script exit 1), HALT (exit code 2, `invalid-input`) listing the offending line numbers — never run a partial target set. When seeding from `--brief`, read the existing `campaign-brief.yaml` directly.
 
-If no targets can be collected (empty interactive input or empty `--brief`/`--manifest`), HALT with guidance — a campaign needs at least one target.
+If no targets can be collected (empty interactive input or empty `--brief`/`--manifest`), HALT (exit code 2, `invalid-input`) with guidance — a campaign needs at least one target.
 
 ### §2 — Health Queue Preference
 
@@ -108,7 +108,7 @@ Populate `{templateFile}` with collected inputs and write to `{briefFile}`. Fill
 - `architecture_doc_path` — from collected input, or empty string if not provided
 - `notes` — operator-provided context, or empty string
 
-The brief is a machine-readable snapshot enabling fresh-context resume (FR-35).
+The brief is a machine-readable snapshot enabling fresh-context resume.
 
 ## OUTPUT
 
@@ -116,7 +116,6 @@ Confirm state file creation and brief generation. Display summary:
 
 - Campaign name
 - Number of targets
-- Tier distribution (count of A vs B)
 - Health queue setting
 
 Chain to `{nextStepFile}`.

package/src/skf-campaign/references/step-02-strategy.md

@@ -46,11 +46,14 @@ Run the deterministic topological sort — do not hand-compute it:
 uv run {depsScript} --compute --state-file {stateFile}
 ```
 
-Parse the JSON output: `execution_order` (the ordered skill names — Kahn's sort with Tier A placed before Tier B within a dependency level), `circular_deps_detected` (bool), and `cycle_participants` (the unplaced skills when a cycle exists, else null). Exit code 1 from the script signals a cycle or a dangling dependency reference; exit code 2 signals a state/parse error — surface either and HALT.
+Parse the JSON output: `execution_order` (the ordered skill names — Kahn's sort with Tier A placed before Tier B within a dependency level), `circular_deps_detected` (bool), `cycle_participants` (the unplaced skills when a cycle exists, else null), and `tier_counts` (`{"A": n, "B": m}`, for the §7 strategy view). Script exit 1 signals an unorderable graph — a cycle or a dangling `depends_on` reference — handled at §5. Script exit 2 signals the helper could not read/parse the state file; HALT (exit code 2, `invalid-input`) surfacing its error.
 
-### §5 — Handle Circular Dependencies
+### §5 — Handle Unorderable Graph
 
-If `circular_deps_detected` is `true`, HALT (exit code 4, `circular-deps`) with a clear error listing `cycle_participants` and their mutual `depends_on` edges. Do NOT proceed — circular dependencies make execution order impossible.
+If the graph cannot be ordered (script exit 1), HALT (exit code 4, `circular-deps`) — the execution order is impossible, so do not proceed. Two cases:
+
+- **Cycle** (`circular_deps_detected: true`): list `cycle_participants` and their mutual `depends_on` edges.
+- **Dangling reference** (a `DANGLING_DEPENDENCY` error with no `execution_order`): name the skill and the unknown dependency it references.
 
 ### §6 — Write State
 
@@ -83,6 +86,8 @@ TIER DISTRIBUTION:
   Tier B (QS batch): {count}
 ```
 
+Fill the TIER DISTRIBUTION counts from `tier_counts` in the §4 script output — do not re-tally `skills[]` by hand.
+
 ### §8 — Plan Confirmation Gate
 
 The strategy view is the last review surface before a potentially long, mostly-unattended run begins. Present a confirmation gate:

package/src/skf-campaign/references/step-03-pins.md

@@ -41,7 +41,7 @@ Copy `{stateFile}` to `{backupFile}` before any modification.
 
 ### §4 — Validate Pins
 
-Run `uv run {pinScript} --state-file {stateFile} --brief-file {briefFile}`. Parse the JSON output. For each result: if `status` is `"valid"` or `"resolved"`, the pin is good; if `"invalid"`, collect the failure with suggestions.
+Run `uv run {pinScript} --state-file {stateFile} --brief-file {briefFile}`. If the script exits 2 (a required tool such as `gh` is unavailable, or a file is unreadable), HALT (exit code 2, `invalid-input`) surfacing its error — pins cannot be validated without `gh`. Otherwise parse the JSON output. For each result: if `status` is `"valid"` or `"resolved"`, the pin is good; if `"invalid"`, collect the failure with suggestions.
 
 ### §5 — Handle Invalid Pins
 

package/src/skf-campaign/references/step-04-provenance.md

@@ -48,7 +48,7 @@ Run the deterministic provenance check — do not parse repo URLs or shell out t
 uv run {provenanceScript} --state-file {stateFile} --brief-file {briefFile}
 ```
 
-The script resolves `{owner}/{repo}` from each `repo_url` (tolerating `.git`/trailing slashes/SSH form), picks the ref (the skill's `pin`, else the repo default branch), runs `gh repo view` + `gh api commits`, and emits `results[]` with `commit_sha` and `status` per skill, plus `all_accessible`, `inaccessible_count`, and `systemic_hint`. Exit 0 = all accessible, 1 = one or more inaccessible, 2 = error (missing files, bad YAML, `gh` not installed).
+The script resolves `{owner}/{repo}` from each `repo_url` (tolerating `.git`/trailing slashes/SSH form), picks the ref (the skill's `pin`, else the repo default branch), runs `gh repo view` + `gh api commits`, and emits `results[]` with `commit_sha` and `status` per skill, plus `all_accessible`, `inaccessible_count`, and `systemic_hint`. Exit 0 = all accessible, 1 = one or more inaccessible, 2 = error (missing files, bad YAML, `gh` not installed). On script exit 2, HALT (exit code 2, `invalid-input`) surfacing the error — repo access cannot be verified without `gh`.
 
 ### §5 — Handle Inaccessible Repos
 

package/src/skf-campaign/references/step-05-skill-loop.md

@@ -25,7 +25,7 @@ Iterate skills in `dependency_graph.execution_order`, processing each Tier A ski
 - Update `campaign.current_stage` to `4`.
 - Update `campaign.last_updated` to current ISO-8601 with timezone on every write.
 - Write state after EACH skill completes (not just at end) — context death between skills must be survivable.
-- The per-skill pipeline body (§5.2) runs inline, not in a delegated subagent: AN→BS→CS→TS are nested skill activations, and a subagent cannot spawn further subagents. This is a deliberate constraint, not an oversight — inline keeps the full pipeline reachable and preserves NFR-2 (every skill's state is written before the next begins).
+- The per-skill pipeline body (§5.2) runs inline, not in a delegated subagent: AN→BS→CS→TS are nested skill activations, and a subagent cannot spawn further subagents — running inline keeps the full pipeline reachable and writes each skill's state before the next begins.
 - If `{headless_mode}` is true, auto-proceed through confirmation gates. Dependency gate blocks default to HALT (safest — never silently skip dependencies).
 
 ## TASKS

package/src/skf-campaign/references/step-06-batch.md

@@ -5,6 +5,7 @@ stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
 backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
 briefFile: '{campaignWorkspacePath}/campaign-brief.yaml'
 batchFile: '{campaignWorkspacePath}/_batch-input.txt'
+batchScript: 'scripts/campaign-render-batch.py'
 validateScript: 'scripts/campaign-validate-state.py'
 ---
 
@@ -42,15 +43,15 @@ If no Tier B skills need processing, skip to §7 (Stage Completion) — the batc
 
 ### §4 — Generate Batch File
 
-Load `{briefFile}` to look up `repo_url` for each Tier B skill (repo URLs are in the brief's `targets[]`, not in the state schema). HALT (exit code 8, `missing-brief`) if the brief is missing or unreadable.
+Generate the QS `--batch` input file deterministically:
 
-Write a batch input file listing Tier B skills for QS `--batch` consumption. For each pending Tier B skill, include:
+```
+uv run {batchScript} --state-file {stateFile} --brief-file {briefFile} -o {batchFile}
+```
 
-- Skill name (from `skills[].name`)
-- Repository URL (from brief's `targets[].repo_url`, matched by name)
-- Pin (from `skills[].pin`, or omit if null for latest)
+The script filters `skills[]` for `tier == "B" && status == "pending"`, looks up each skill's `repo_url` from the brief's `targets[]` (repo URLs live in the brief, not the state schema), and writes one line per skill at `{batchFile}` in the exact single-target shape QS parses (see `src/skf-quick-skill/references/batch-mode.md`) — the line format is owned once by the script, not re-derived here. It emits a JSON summary (`written`, `count`, `skipped_non_tierB`, `skipped_non_pending`) on stderr.
 
-Place the batch file at `{batchFile}`.
+HALT on non-zero exit: exit code 8 (`missing-brief`) when the brief is missing/unreadable **or** a pending Tier B skill has no matching brief target; exit code 2 (`invalid-input`) on a state file/parse error.
 
 ### §5 — Execute QS Batch
 

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

@@ -60,7 +60,7 @@ When `{headless_mode}` is true, emit the campaign result envelope on stdout, cop
 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")
+- `status`: "success" if the campaign completed normally (HARD HALTs emit the error variant per the "Result Contract on HARD HALT" in `references/campaign-contracts.md`)
 - `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
@@ -73,7 +73,7 @@ Set `campaign.current_stage` to `10`. Update `campaign.last_updated` to current
 
 ### §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.
+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). Surface the active setting here.
 
 Display: "**Campaign complete.** Report at `{reportFile}`. Findings routing: {campaign.health_findings_queue}. Chaining to health check..."
 

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

@@ -3,6 +3,7 @@ stateSchemaFile: 'assets/campaign-state-schema.json'
 stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
 backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
 validateScript: 'scripts/campaign-validate-state.py'
+statusScript: 'scripts/campaign-status.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -24,7 +25,7 @@ Validate campaign state integrity, determine the resume point, and chain to the
 
 ### §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."
+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."
 
 Run `uv run {validateScript} --state-file {stateFile}`. If it succeeds (exit 0), proceed to §2.
 
@@ -43,7 +44,7 @@ Check if `{backupFile}` exists.
 **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:
+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).
 
@@ -56,10 +57,10 @@ 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}."
+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: "All remaining skills are complete. Run `campaign` to start a new campaign."
+   - `[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.
 
    In headless mode, default to `[N]ext` and log the auto-decision. Log the chosen action to the decision log.
@@ -94,20 +95,20 @@ Map the resolved stage number to its step file. Both §3 branches feed this tabl
 | 9 | step-10-export.md |
 | 10 | step-11-maintenance.md |
 
-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")
-  Skills completed: {completed_count} / {total_count}
-  Skills remaining: {pending_count} pending, {active_count} active, {failed_count} failed, {skipped_count} skipped
+  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: "Campaign has reached its final stage. All skills have been processed."
+HALT (exit code 0, campaign already complete): "Campaign has reached its final stage. All skills have been processed."
 
 ## OUTPUT