bmad-module-skill-forge 1.9.0 → 2.0.1

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

@@ -0,0 +1,121 @@
+---
+nextStepFile: 'step-02-strategy.md'
+stateSchemaFile: 'assets/campaign-state-schema.json'
+stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
+briefFile: '{campaignWorkspacePath}/campaign-brief.yaml'
+templateFile: '{briefTemplatePath}'
+validateScript: 'scripts/campaign-validate-state.py'
+manifestScript: 'scripts/campaign-parse-manifest.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Setup
+
+## STEP GOAL:
+
+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 `references/campaign-contracts.md`.
+
+## RULES
+
+- This step creates the state file — there is no existing state to read or back up.
+- Validate the written state with `uv run {validateScript} --state-file {stateFile}` before generating the brief. HALT (exit code 3, `invalid-state`) on non-zero, surfacing the script's `errors[]`.
+- If `{headless_mode}` is true, draw inputs from `--brief`/`--manifest` (On Activation step 4) and auto-proceed through confirmation gates with the default action, logging each auto-decision to the decision log.
+
+## TASKS
+
+### §1 — Collect Inputs
+
+Accept from the operator (or, in headless mode, from the `--brief`/`--manifest` source parsed in On Activation):
+
+- `campaign_name` — string identifier for this campaign run
+- Target libraries — each entry requires:
+  - `name` — skill name
+  - `repo_url` — source repository URL
+  - `tier` — `"A"` (full pipeline) or `"B"` (batch)
+  - `pin` — version pin (string) or `null` for latest
+  - `depends_on` — array of skill names this target depends on (may be empty)
+- `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 (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 (exit code 2, `invalid-input`) with guidance — a campaign needs at least one target.
+
+### §2 — Health Queue Preference
+
+Default to `"local"` (project-local findings queue). Present the opt-in prompt:
+
+> Send anonymized quality findings to the shared improvement queue? [y/N]
+
+- **y** — set `health_findings_queue` to `"improvement"`
+- **N** (default) — keep `health_findings_queue` as `"local"`
+
+In headless mode: auto-select `"local"` (N) and log the auto-decision.
+
+### §3 — Build State Object
+
+Construct `_campaign-state.yaml` in memory from collected inputs. Use the campaign-wide quality gate resolved in On Activation: `{qualityGateHard}` / `{qualityGateSoftTarget}` / `{qualityGateSoftFallback}`. Note: `repo_url` (collected in §1) is NOT part of the state schema — it belongs in the brief only (§5). The state schema enforces `additionalProperties: false`, so including it would fail validation.
+
+```yaml
+campaign:
+  name: "{campaign_name}"
+  started_at: "{current_iso8601_with_tz}"
+  last_updated: "{current_iso8601_with_tz}"
+  current_stage: 0
+  directive_path: "{directive_path or omit if not provided}"
+  architecture_doc_path: "{architecture_doc_path or omit if not provided}"
+  quality_gate:
+    hard: "{qualityGateHard}"
+    soft_target: {qualityGateSoftTarget}
+    soft_fallback: {qualityGateSoftFallback}
+  health_findings_queue: "{local or improvement}"
+skills:
+  # One entry per target:
+  - name: "{target.name}"
+    status: "pending"
+    depends_on: []            # from target.depends_on
+    tier: "{target.tier}"
+    pin: null                 # from target.pin
+    brief_path: null          # populated in step-05 once BS produces the skill's brief
+    skill_path: null
+    quality_score: null
+    workarounds_applied: []
+    started_at: null
+    completed_at: null
+dependency_graph:
+  execution_order: []         # populated by step-02-strategy
+  circular_deps_detected: false
+```
+
+### §4 — Write + Validate State
+
+1. Ensure the directory `{campaignWorkspacePath}/` exists (create if missing).
+2. Write the constructed state to `{stateFile}`. This is the initial creation — no `.bak` is needed for the first write; all subsequent steps use read-backup-modify-write.
+3. Run `uv run {validateScript} --state-file {stateFile}`. On non-zero (invalid), **HALT** (exit 3) with the script's `errors[]` — do not proceed to brief generation with an invalid state file.
+
+### §5 — Generate Brief
+
+Populate `{templateFile}` with collected inputs and write to `{briefFile}`. Fill in:
+
+- `campaign_name` — from collected input
+- `created_at` — current ISO-8601 timestamp with timezone
+- `targets` — array of target entries with `name`, `repo_url`, `tier`, `pin`, `depends_on`
+- `quality_gate` — `{qualityGateHard}` / `{qualityGateSoftTarget}` / `{qualityGateSoftFallback}`
+- `health_findings_queue` — from the §2 preference decision
+- `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.
+
+## OUTPUT
+
+Confirm state file creation and brief generation. Display summary:
+
+- Campaign name
+- Number of targets
+- Health queue setting
+
+Chain to `{nextStepFile}`.

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

@@ -0,0 +1,102 @@
+---
+nextStepFile: 'step-03-pins.md'
+stateSchemaFile: 'assets/campaign-state-schema.json'
+stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
+backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+depsScript: 'scripts/campaign-deps.py'
+validateScript: 'scripts/campaign-validate-state.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Strategy
+
+## STEP GOAL:
+
+Compute the execution order from dependency edges, detect circular dependencies, and present a human-readable strategy view to the operator so the campaign plan is visible before execution begins.
+
+## RULES
+
+- This step uses the **read-backup-modify-write** pattern (state file exists from step-01).
+- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
+- Write `execution_order` and `circular_deps_detected` to `dependency_graph`.
+- Update `campaign.current_stage` to `1`.
+- Update `campaign.last_updated` to current ISO-8601 with timezone on every write.
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with the default action and log each auto-decision.
+
+## TASKS
+
+### §1 — Read + Validate State
+
+Load `{stateFile}`. Run `uv run {validateScript} --state-file {stateFile}`; on non-zero, HALT (exit 3) with the script's `errors[]`.
+
+### §2 — Backup State
+
+Copy `{stateFile}` to `{backupFile}` before any modification.
+
+### §3 — Read Directive
+
+If `campaign.directive_path` is set in state, load the file at that path and apply its contents as campaign-wide context for this stage's processing, per the directive contract in `references/campaign-directive-spec.md`. If the file is not found, continue without error (directive is optional).
+
+### §4 — Compute Execution Order
+
+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), `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 Unorderable Graph
+
+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
+
+Set `dependency_graph.execution_order` to the computed order. Set `dependency_graph.circular_deps_detected` to the detection result. Set `campaign.current_stage` to `1`. Set `campaign.last_updated` to current ISO-8601 with timezone. Write to `{stateFile}`.
+
+### §7 — Present Strategy View
+
+Display a human-readable strategy summary to the operator (not written to a file — display only):
+
+```
+CAMPAIGN STRATEGY: {campaign_name}
+
+EXECUTION ORDER:
+  1. {skill_name} [Tier {tier}] {pin or "latest"}
+  2. {skill_name} [Tier {tier}] {pin or "latest"} ← depends on: {dep1, dep2}
+  ...
+
+DEPENDENCY MAP:
+  {skill_a} → {skill_b}, {skill_c}
+  {skill_d} → (no dependencies)
+  ...
+
+QUALITY GATE:
+  Hard gate: {quality_gate.hard}
+  Soft target: {quality_gate.soft_target}%
+  Soft fallback: {quality_gate.soft_fallback}%
+
+TIER DISTRIBUTION:
+  Tier A (full pipeline): {count}
+  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:
+
+- `[P]roceed` — begin execution (chain to `{nextStepFile}`).
+- `[C]ancel` — stop now with exit code 12 (`user-cancelled`); state is intact and resumable. To change targets, edit the campaign brief (`{campaignWorkspacePath}/campaign-brief.yaml`) or re-run `campaign` (overwrite), then start again.
+
+**HALT and wait for operator input.** In headless mode, auto-proceed with `[P]` and log "headless: auto-proceed past plan-confirmation gate" to the decision log.
+
+## OUTPUT
+
+Confirm strategy computed, display the strategy view, and resolve the §8 gate. Chain to `{nextStepFile}`.

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

@@ -0,0 +1,56 @@
+---
+nextStepFile: 'step-04-provenance.md'
+stateSchemaFile: 'assets/campaign-state-schema.json'
+stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
+backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+briefFile: '{campaignWorkspacePath}/campaign-brief.yaml'
+pinScript: 'scripts/campaign-validate-pins.py'
+validateScript: 'scripts/campaign-validate-state.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Pins
+
+## STEP GOAL:
+
+Validate all version pins against real releases/branches before the campaign proceeds, catching invalid pins early with actionable suggestions.
+
+## RULES
+
+- This step uses the **read-backup-modify-write** pattern (state file exists from step-01).
+- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
+- Update `campaign.current_stage` to `2`.
+- Update `campaign.last_updated` to current ISO-8601 with timezone on every write.
+- HALT (exit code 5, `invalid-pin`) on any invalid pin — invalid pins are errors, not gates.
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with the default action and log each auto-decision.
+
+## TASKS
+
+### §1 — Read + Validate State
+
+Load `{stateFile}`. Run `uv run {validateScript} --state-file {stateFile}`; on non-zero, HALT (exit 3) with the script's `errors[]`.
+
+### §2 — Read Brief
+
+Load `{briefFile}`. Build a lookup map from `targets[].name` to `targets[].repo_url`. HALT (exit code 8, `missing-brief`) if the brief is missing or unreadable.
+
+### §3 — Backup State
+
+Copy `{stateFile}` to `{backupFile}` before any modification.
+
+### §4 — Validate Pins
+
+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
+
+If ANY pins are invalid, collect ALL failures first (all-or-nothing pattern), then HALT (exit code 5, `invalid-pin`) with a clear error listing each invalid pin, the skill name, the attempted pin value, and suggested corrections. Do NOT partially proceed.
+
+### §6 — Update State
+
+For each skill where validation returned `status: "resolved"` (pin was null, latest release found), update `skill.pin` to the `resolved_ref` value. For `status: "valid"` where the input pin differs from `resolved_ref` (e.g., user said `2.0.0` but the actual tag is `v2.0.0`), update `skill.pin` to the `resolved_ref` so downstream steps use the exact ref name. Set `campaign.current_stage` to `2`. Set `campaign.last_updated`. Write to `{stateFile}`.
+
+## OUTPUT
+
+Display pin validation summary — for each skill: name, pin, resolved ref, ref type. Chain to `{nextStepFile}`.

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

@@ -0,0 +1,63 @@
+---
+nextStepFile: 'step-05-skill-loop.md'
+stateSchemaFile: 'assets/campaign-state-schema.json'
+stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
+backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+briefFile: '{campaignWorkspacePath}/campaign-brief.yaml'
+provenanceScript: 'scripts/campaign-provenance.py'
+validateScript: 'scripts/campaign-validate-state.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Provenance
+
+## STEP GOAL:
+
+Verify that all target repositories are accessible and record the exact commit SHA for each target, establishing the provenance baseline for the campaign.
+
+## RULES
+
+- This step uses the **read-backup-modify-write** pattern.
+- Reads the brief for `repo_url` (not in state — `repo_url` is NOT part of the state schema).
+- Any inaccessible repo halts the campaign — all targets must be reachable before skill processing begins.
+- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
+- Update `campaign.current_stage` to `3`.
+- Update `campaign.last_updated` to current ISO-8601 with timezone on every write.
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with the default action and log each auto-decision.
+
+## TASKS
+
+### §1 — Read + Validate State
+
+Load `{stateFile}`. Run `uv run {validateScript} --state-file {stateFile}`; on non-zero, HALT (exit 3) with the script's `errors[]`.
+
+### §2 — Read Brief
+
+Load `{briefFile}` only to confirm it parses (the provenance script reads it directly). HALT (exit code 8, `missing-brief`) if the brief is missing or unreadable.
+
+### §3 — Backup State
+
+Copy `{stateFile}` to `{backupFile}` before any modification.
+
+### §4 — Verify Repo Access + Record Commit SHAs
+
+Run the deterministic provenance check — do not parse repo URLs or shell out to `gh` by hand:
+
+```
+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). On script exit 2, HALT (exit code 2, `invalid-input`) surfacing the error — repo access cannot be verified without `gh`.
+
+### §5 — Handle Inaccessible Repos
+
+If `all_accessible` is `false` (script exit 1), HALT (exit code 6, `inaccessible-repo`). When the script returns a non-null `systemic_hint` (every target failed the same way — e.g. unauthenticated `gh`, no network, rate limit), present that single root-cause line instead of a wall of near-identical per-repo errors. Otherwise list each inaccessible repo, its URL, and its error. Do NOT partially proceed — all repos must be verified before writing state.
+
+### §6 — Write State
+
+Set each skill's `commit_sha` from the script's `results[]`. Set `campaign.current_stage` to `3`. Set `campaign.last_updated` to current ISO-8601 with timezone. Write to `{stateFile}`.
+
+## OUTPUT
+
+Display provenance summary — for each target, show name, repo URL, and recorded commit SHA. Chain to `{nextStepFile}`.

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

@@ -0,0 +1,103 @@
+---
+nextStepFile: 'step-06-batch.md'
+stateSchemaFile: 'assets/campaign-state-schema.json'
+stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
+backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+briefFile: '{campaignWorkspacePath}/campaign-brief.yaml'
+depsScript: 'scripts/campaign-deps.py'
+kickoffTemplate: '{kickoffTemplatePath}'
+kickoffScript: 'scripts/campaign-render-kickoff.py'
+validateScript: 'scripts/campaign-validate-state.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Skill Loop
+
+## STEP GOAL:
+
+Iterate skills in `dependency_graph.execution_order`, processing each Tier A skill through the full pipeline while enforcing dependency gates. Write state after each skill completes to survive context death between skills.
+
+## RULES
+
+- This step uses the **read-backup-modify-write** pattern.
+- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
+- Update `campaign.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 — 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
+
+### §1 — Read + Validate State
+
+Load `{stateFile}`. Run `uv run {validateScript} --state-file {stateFile}`; on non-zero, HALT (exit 3) with the script's `errors[]`.
+
+### §2 — Read Brief
+
+Load `{briefFile}`. Build a lookup map from `targets[].name` to `targets[].repo_url`. HALT (exit code 8, `missing-brief`) if the brief is missing or unreadable.
+
+### §3 — Read Directive
+
+If `campaign.directive_path` is set in state, load the file at that path and apply its contents as campaign-wide context for all skill processing, per the directive contract in `references/campaign-directive-spec.md`. If the file is not found, continue without error (directive is optional).
+
+### §4 — Dependency Gate Check
+
+For each skill in `dependency_graph.execution_order`, before processing:
+
+1. Skip Tier B skills — they are processed in step-06 via batch mode.
+2. Skip skills whose status is already `"completed"`, `"failed"`, or `"skipped"` (resume support).
+3. Run `uv run {depsScript} --check --state-file {stateFile} --skill {skill_name}`.
+4. If `ready: true` — proceed to §5 for this skill.
+5. If `ready: false` — present the blocked skill and its unmet dependencies:
+   - `[S]kip` — mark skill as `"skipped"`, backup and write state, continue to next skill.
+   - `[F]orce` — re-run with `--force`, proceed to §5 despite unmet deps.
+   - `[H]alt` — stop the campaign loop. (Default in headless mode.)
+6. **Deadlock detection:** after iterating through all remaining skills and finding none ready, present the same recovery menu as §4.5, scoped to the mutually-blocked set (this is the strictly harder situation, so it must not get worse UX than a single blocked skill):
+   - List the blocked skills and their unmet dependencies.
+   - `[F]orce one` — choose a skill to re-run with `--force` and resume the loop from it.
+   - `[S]kip one` — choose a skill to mark `"skipped"`, backup and write state, then re-evaluate readiness.
+   - `[H]alt` — stop the campaign loop with exit code 7 (`dependency-deadlock`). **Default in headless mode** (never silently force or skip a dependency). Log the chosen action to the decision log.
+
+### §5 — Per-Skill Processing
+
+For each ready Tier A skill:
+
+1. **Activate** — set `status` to `"active"`, set `started_at` to current ISO-8601 with timezone. Backup and write state.
+2. **Execute pipeline:**
+   - **Pre-apply** — apply known workarounds before generation by running the shared pre-apply helper against the skill's working directory:
+     ```
+     uv run {project-root}/_bmad/skf/shared/scripts/skf-preapply.py --target-dir <skill-working-dir> --log-dir {campaignWorkspacePath}
+     ```
+     (During development the helper lives at `src/shared/scripts/skf-preapply.py`.) Parse `applied[]` from the JSON output and capture the list of applied workarounds. Pre-apply is best-effort: if the helper is missing or exits non-zero, log a warning and proceed — it is not a gate.
+   - **Kickoff emit** — render the mechanical placeholders deterministically, then fill the three judgment slots. Run:
+     ```
+     uv run {kickoffScript} --state-file {stateFile} --brief-file {briefFile} --skill {skill_name} --template {kickoffTemplate} --workarounds '<JSON list of applied workarounds from pre-apply>'
+     ```
+     The script fills `{{campaign_name}}`, `{{current_stage}}`, `{{quality_gate_summary}}`, `{{skill_name}}`, `{{skill_tier}}`, `{{pin}}`, `{{commit_sha}}`, `{{repo_url}}`, `{{workarounds_list}}`, and `{{dependency_status_table}}` from state + brief. Then fill the three judgment slots that remain in the rendered output:
+     - `{{brief_summary}}` — a concise summary of this target's brief entry (name, repo_url, tier, pin, depends_on). The per-skill brief does NOT exist yet at kickoff — BS produces it during this pipeline run (see below), so do not read `brief_path`; summarize the campaign brief's target entry instead.
+     - `{{persistent_facts}}` — the campaign-wide persistent facts resolved in On Activation (literal sentences and loaded `file:` contents), as a bullet list, or "None" if empty. This is how house style/guardrails reach every skill's pipeline.
+     - `{{directive_content}}` — raw content of the file at `campaign.directive_path`, or "No directive configured" if unset/missing.
+     Present the completed kickoff message as the context for the skill's pipeline run.
+   - **AN → BS → CS → TS** — standard forge pipeline for this skill. When BS (Brief Synthesis) produces the skill's brief, set `skills[current].brief_path` to the brief path from the BS result envelope so the field the schema declares is populated and available for resume and reporting.
+   - **Doc-rot check** — grep feeder artifacts for corrections emitted during the pipeline run. Append any doc-rot findings to the skill's `workarounds_applied` array (prefixed with `[doc-rot]`) so they survive state write and are available for §6 propagation.
+3. **Record results:**
+   - On success: set `status` to `"completed"`, set `completed_at` to current ISO-8601 with timezone, record `quality_score`. Backup and write state.
+   - On failure: set `status` to `"failed"`. Log the failure reason (the sub-skill's `halt_reason`/exit code, or "unparseable result envelope") to the decision log so `campaign status` and the report surface *why* a skill failed without the operator opening sub-skill logs. Backup and write state. Downstream skills whose `depends_on` does NOT include the failed skill continue processing normally; those that DO depend on it are blocked at §4's dependency gate.
+
+### §6 — Propagate Findings
+
+After each completed skill, propagate quality findings and doc-rot corrections to campaign-level tracking (`workarounds_applied`, `quality_score`).
+
+### §7 — Loop Completion
+
+When all Tier A skills in `execution_order` are processed (completed, failed, or skipped):
+
+1. Set `campaign.current_stage` to `4`.
+2. Set `campaign.last_updated` to current ISO-8601 with timezone.
+3. Backup and write state.
+
+## OUTPUT
+
+Display per-skill summary: name, status, quality_score (if completed). Chain to `{nextStepFile}`.

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

@@ -0,0 +1,88 @@
+---
+nextStepFile: 'step-07-capstone.md'
+stateSchemaFile: 'assets/campaign-state-schema.json'
+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'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Tier B Batch
+
+## STEP GOAL:
+
+Batch all Tier B skills through QS `--batch` mode, recording per-skill results in campaign state. Tier B skills use a faster, simpler path than the full Tier A pipeline — QS handles each target end-to-end in a single invocation.
+
+## RULES
+
+- This step uses the **read-backup-modify-write** pattern.
+- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
+- Update `campaign.last_updated` to current ISO-8601 with timezone on every write.
+- Update `campaign.current_stage` to `5`.
+- If `{headless_mode}` is true, auto-proceed through confirmation gates. QS `--batch` implies headless.
+
+## TASKS
+
+### §1 — Read + Validate State
+
+Load `{stateFile}`. Run `uv run {validateScript} --state-file {stateFile}`; on non-zero, HALT (exit 3) with the script's `errors[]`.
+
+### §2 — Read Directive
+
+If `campaign.directive_path` is set in state, load the file at that path and apply its contents as campaign-wide context for this stage's processing, per the directive contract in `references/campaign-directive-spec.md`. If the file is not found, continue without error (directive is optional).
+
+### §3 — Identify Tier B Skills
+
+Filter `skills[]` for entries where `tier == "B"` and `status == "pending"`. Skip skills with status `"completed"`, `"failed"`, or `"skipped"` (resume support — a previous run may have partially completed the batch).
+
+If no Tier B skills need processing, skip to §7 (Stage Completion) — the batch stage completes immediately when all Tier B skills are already handled.
+
+### §4 — Generate Batch File
+
+Generate the QS `--batch` input file deterministically:
+
+```
+uv run {batchScript} --state-file {stateFile} --brief-file {briefFile} -o {batchFile}
+```
+
+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.
+
+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
+
+Set each pending Tier B skill to `status: "active"` and `started_at` to current ISO-8601 with timezone. Backup `{stateFile}` to `{backupFile}`, then write the updated state.
+
+Invoke QS in `--batch` mode with the generated batch file:
+
+```
+skf-quick-skill --batch {batchFile}
+```
+
+QS `--batch` implies `--headless`. Capture per-skill results from the QS batch output — each target reports success/failure, skill path, and quality score.
+
+### §6 — Record Results
+
+For each Tier B skill in the batch:
+
+1. If QS reports success:
+   - Set `status` to `"completed"`
+   - Set `completed_at` to current ISO-8601 with timezone
+   - Record `quality_score` from QS output
+   - Record `skill_path` from QS output
+2. If QS reports failure:
+   - Set `status` to `"failed"`
+
+After all updates: backup `{stateFile}` to `{backupFile}`, then write the updated state.
+
+### §7 — Stage Completion
+
+Set `campaign.current_stage` to `5`. Update `campaign.last_updated` to current ISO-8601 with timezone. Backup `{stateFile}` to `{backupFile}`, then write the updated state.
+
+## OUTPUT
+
+Display per-skill batch summary: name, status, quality_score (if completed). Chain to `{nextStepFile}`.

package/src/skf-campaign/references/step-07-capstone.md

@@ -0,0 +1,63 @@
+---
+nextStepFile: 'step-08-verify.md'
+stateSchemaFile: 'assets/campaign-state-schema.json'
+stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
+backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+validateScript: 'scripts/campaign-validate-state.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Capstone
+
+## STEP GOAL:
+
+Compose a capstone stack skill from all completed individual skills using SS compose-mode. The capstone represents the final integrated view of all campaign skills — a single stack skill that documents how the constituent libraries connect.
+
+## RULES
+
+- This step uses the **read-backup-modify-write** pattern.
+- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
+- Update `campaign.last_updated` to current ISO-8601 with timezone on every write.
+- Update `campaign.current_stage` to `6`.
+- If `{headless_mode}` is true, auto-proceed through confirmation gates. SS compose-mode supports headless.
+
+## TASKS
+
+### §1 — Read + Validate State
+
+Load `{stateFile}`. Run `uv run {validateScript} --state-file {stateFile}`; on non-zero, HALT (exit 3) with the script's `errors[]`.
+
+### §2 — Collect Completed Skills
+
+Gather all skills from `skills[]` with `status == "completed"` — this includes both Tier A skills (processed in step-05) and Tier B skills (processed in step-06). Extract their `skill_path` values.
+
+If no completed skills exist, do NOT HALT — a campaign where everything failed is exactly when the operator most needs the downstream diagnostic report. Set `campaign.capstone` to `null`, warn ("No completed skills — skipping capstone composition; verification and the campaign report will still run so failures are explained"), log the skip to the decision log, and skip directly to §5 (Stage Completion) so the chain continues to verify → … → the report. step-10 (export) and step-11 (report) already handle the zero-completed case.
+
+### §3 — Invoke SS Compose-Mode
+
+Invoke `skf-create-stack-skill` in compose-mode with:
+
+- The collected `skill_path` values as input skills
+- `campaign.name` as the stack identifier
+
+Capture the result: stack skill path and quality score from the SS result output (`SKF_STACK_RESULT_JSON`).
+
+### §4 — Record Capstone Results
+
+Persist the capstone outcome to `campaign.capstone` in the state (campaign-level summary; the composed skill itself lives at `skill_path`):
+
+- `campaign.capstone.skill_path` — stack skill path (from SS result)
+- `campaign.capstone.quality_score` — quality score (from SS result)
+- `campaign.capstone.verified` — `null` for now; set by the verify stage (step-08) once the stack is checked
+- `campaign.capstone.completed_at` — current ISO-8601 with timezone
+
+The capstone is a derived artifact — it is **not** tracked as a skill entry in the `skills[]` array. Its campaign-level summary lives in `campaign.capstone`; the constituent skill list and any verbose detail are reported in the step output and are available to downstream steps (verify, refine).
+
+### §5 — Stage Completion
+
+Set `campaign.current_stage` to `6`. Update `campaign.last_updated` to current ISO-8601 with timezone. Backup `{stateFile}` to `{backupFile}`, then write the updated state (including `campaign.capstone` from §4).
+
+## OUTPUT
+
+Display capstone summary: stack skill name, path, quality score, and the list of constituent skills. Chain to `{nextStepFile}`.