bmad-module-skill-forge 1.9.0 → 2.0.0

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. 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).
+- 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,87 @@
+---
+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'
+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
+
+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.
+
+Write a batch input file listing Tier B skills for QS `--batch` consumption. For each pending Tier B skill, include:
+
+- 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)
+
+Place the batch file at `{batchFile}`.
+
+### §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}`.

package/src/skf-campaign/references/step-08-verify.md

@@ -0,0 +1,75 @@
+---
+nextStepFile: 'step-09-refine.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}. -->
+
+# Verify
+
+## STEP GOAL:
+
+Invoke VS (skf-verify-stack) in headless mode against all completed campaign skills to produce a feasibility report. The report cross-references generated skills against the project's architecture document, providing coverage analysis and integration verdicts for operator review.
+
+## 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 `7`.
+- If `{headless_mode}` is true, auto-proceed through confirmation gates. VS supports headless via `--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 — Locate Architecture Doc
+
+Resolve the architecture document path, preferring the value persisted in state:
+
+1. If `campaign.architecture_doc_path` is set in state and the file exists, use it directly.
+2. Otherwise discover it: check `docs/architecture.md` at `{project-root}` (SKF convention), then `_bmad-output/planning-artifacts/architecture.md` (BMM convention).
+3. If still not found and `{headless_mode}` is false: prompt the operator to provide the architecture doc path.
+4. If still not found and `{headless_mode}` is true: skip VS invocation with a warning — do not HALT. Log that verification was skipped due to missing architecture doc (to the decision log) and proceed to §6.
+
+Once resolved (steps 2–3), persist the path to `campaign.architecture_doc_path` so the refine stage and any resume reuse it without re-prompting. Then proceed to §4 with the resolved path.
+
+### §4 — Invoke VS
+
+Invoke `skf-verify-stack` with `--headless --architecture-doc <path>`, where `<path>` is the architecture doc discovered in §3.
+
+VS discovers skills from its own configured `{skills_output_folder}` — the campaign does NOT pass individual skill paths. Capture the result envelope from stdout:
+
+```
+SKF_VERIFY_STACK_RESULT_JSON: {"status":"…","report_path":"…","report_latest_path":"…","overall_verdict":"…","coverage_percentage":0,"recommendation_count":0,"exit_code":0,"halt_reason":null}
+```
+
+### §5 — Handle VS Outcome
+
+**On success** (exit code 0): persist the summary to `campaign.verification` (detailed findings stay in the external report):
+
+- `campaign.verification.report_path` — `report_latest_path` from the envelope
+- `campaign.verification.overall_verdict` — one of `Verified`, `Plausible`, `Risky`, `Blocked`
+- `campaign.verification.coverage_percentage` — from the envelope
+- `campaign.verification.recommendation_count` — from the envelope
+
+Also set `campaign.capstone.verified` to `true` when `overall_verdict == "Verified"`, otherwise `false` (only if a `campaign.capstone` entry exists from step-07).
+
+**On VS failure** (non-zero exit): log the error (exit code and halt_reason from the envelope or stderr). Verification failure does NOT block the campaign — it produces diagnostic information for operator review. Leave `campaign.verification` unset (or null). Continue to §6 regardless of outcome.
+
+### §6 — Stage Completion
+
+Set `campaign.current_stage` to `7`. Update `campaign.last_updated` to current ISO-8601 with timezone. Backup `{stateFile}` to `{backupFile}`, then write the updated state (including `campaign.architecture_doc_path` from §3 and `campaign.verification` from §5).
+
+## OUTPUT
+
+Display verification summary: overall verdict (or "skipped" if architecture doc was not found), report path (if produced), and coverage percentage. Chain to `{nextStepFile}`.

package/src/skf-campaign/references/step-09-refine.md

@@ -0,0 +1,83 @@
+---
+nextStepFile: 'step-10-export.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}. -->
+
+# Refine
+
+## STEP GOAL:
+
+Invoke RA (skf-refine-architecture) in headless mode with the project's architecture document and VS feasibility report to produce a refined architecture. RA identifies gaps, issues, and improvements based on the generated skills and applies them to the architecture document.
+
+## 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 `8`.
+- If `{headless_mode}` is true, auto-proceed through confirmation gates. RA supports headless via `--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 — Locate Inputs
+
+**Architecture doc:** Use the same resolution strategy as step-08:
+
+1. If `campaign.architecture_doc_path` is set in state and the file exists, use it directly (step-08 normally persists it).
+2. Otherwise check `docs/architecture.md` at `{project-root}`, then `_bmad-output/planning-artifacts/architecture.md`.
+3. If still not found and `{headless_mode}` is false: prompt the operator.
+4. If still not found and `{headless_mode}` is true: skip RA invocation with a warning — do not HALT. Log that refinement was skipped due to missing architecture doc (to the decision log) and proceed to §6.
+
+Once resolved (steps 2–3), persist the path to `campaign.architecture_doc_path` if not already set, then proceed to §4 with the resolved path.
+
+**VS feasibility report:** If chaining from step-08, the report path is available from the VS result envelope (`report_latest_path`). On resume, look for `feasibility-report-*-latest.md` in `{forge_data_folder}/`. If no report exists (VS may have failed or been skipped in step-08), proceed without it — RA's VS report input is optional.
+
+### §4 — Invoke RA
+
+Invoke `skf-refine-architecture` with:
+
+```
+skf-refine-architecture --headless --architecture-doc <arch_path> [--vs-report-path <report_path>] [--scope-skills <names>]
+```
+
+- `--architecture-doc`: the architecture doc discovered in §3 (required).
+- `--vs-report-path`: the VS feasibility report path from §3 (omit if not found).
+- `--scope-skills`: comma-separated names of completed campaign skills (from `skills[]` where `status == "completed"`). Optional but improves focus by limiting refinement scope to campaign-relevant skills.
+
+Capture the result envelope from stdout:
+
+```
+SKF_REFINE_ARCHITECTURE_RESULT_JSON: {"status":"…","refined_path":"…","gap_count":0,"issue_count":0,"improvement_count":0,"exit_code":0,"halt_reason":null}
+```
+
+### §5 — Handle RA Outcome
+
+**On success** (exit code 0): persist the summary to `campaign.refinement` (the refined document itself lives at `refined_path`):
+
+- `campaign.refinement.refined_path` — from the envelope
+- `campaign.refinement.gap_count` — from the envelope
+- `campaign.refinement.issue_count` — from the envelope
+- `campaign.refinement.improvement_count` — from the envelope
+
+**On RA failure** (non-zero exit): log the error (exit code and halt_reason from the envelope or stderr). Refinement failure does NOT block the campaign — the campaign continues to export with whatever state exists. Leave `campaign.refinement` unset (or null). Continue to §6 regardless of outcome.
+
+### §6 — Stage Completion
+
+Set `campaign.current_stage` to `8`. Update `campaign.last_updated` to current ISO-8601 with timezone. Backup `{stateFile}` to `{backupFile}`, then write the updated state (including `campaign.refinement` from §5).
+
+## OUTPUT
+
+Display refinement summary: refined architecture path (or "skipped" if architecture doc was not found), gap count, issue count, and improvement count. Chain to `{nextStepFile}`.

package/src/skf-campaign/references/step-10-export.md

@@ -0,0 +1,106 @@
+---
+nextStepFile: 'step-11-maintenance.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}. -->
+
+# Export
+
+## STEP GOAL:
+
+Present all completed skills for operator review and gate the export behind explicit confirmation. This is the only campaign step that requires manual approval before proceeding — no files are written until the operator confirms.
+
+## 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 `9`.
+- If `{headless_mode}` is true, auto-proceed past the write-gate with `[E]` and log: "headless: auto-proceed past export write-gate".
+
+## 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 — Collect Export Candidates
+
+Gather all skills from `skills[]` with `status == "completed"`. These are the export candidates.
+
+If no completed skills exist, display a warning and proceed directly to §6 (stage completion) — there is nothing to export.
+
+Present a summary table of export candidates:
+
+| # | Name | Tier | Quality Score | Skill Path |
+|---|------|------|---------------|------------|
+| 1 | {name} | {tier} | {quality_score} | {skill_path} |
+| ... | ... | ... | ... | ... |
+
+Display: "**{N} skill(s) ready for export.**"
+
+### §4 — Write-Gate HALT
+
+Present the export confirmation gate:
+
+"**Export Gate — Confirm before writing files**
+
+{N} completed skill(s) will be exported via `skf-export-skill`:
+
+{summary table from §3}
+
+- **[E]xport all** — invoke `skf-export-skill` for each completed skill
+- **[C]ancel** — halt the campaign gracefully (no files written, resume later)
+
+Choose [E] or [C]:"
+
+**HALT and wait for operator input.**
+
+**Headless mode:** auto-proceed with `[E]` and log: "headless: auto-proceed past export write-gate".
+
+#### On `[C]ancel`:
+
+Display: "Export cancelled by operator. Campaign halted gracefully — no files written. Resume later to retry export."
+
+Log the cancellation to the decision log, then HALT with exit code 11 (`export-cancelled`). Do NOT mark the campaign as failed — this is a graceful, resumable halt; the operator may resume later.
+
+#### On `[E]xport`:
+
+Log the export decision to the decision log, then proceed to §5.
+
+### §5 — Invoke EX
+
+For each completed skill (from §3), invoke `skf-export-skill` in headless mode:
+
+```
+skf-export-skill {skill_name} --headless
+```
+
+Capture the result envelope `SKF_EXPORT_RESULT_JSON` per skill.
+
+**On per-skill EX success** (exit code 0): log the result and continue.
+
+**On per-skill EX failure** (non-zero exit): log the error (exit code, envelope if available, or stderr). Continue with remaining skills — per-skill failure does not block remaining exports.
+
+After all exports complete, display a summary:
+
+"**Export Results:**
+- Exported: {success_count} skill(s)
+- Failed: {fail_count} skill(s)
+{list of failed skills if any}"
+
+### §6 — Stage Completion
+
+Set `campaign.current_stage` to `9`. Update `campaign.last_updated` to current ISO-8601 with timezone. Backup `{stateFile}` to `{backupFile}`, then write the updated state.
+
+## OUTPUT
+
+Display export summary: skills exported count, failures count (if any), and per-skill results. Chain to `{nextStepFile}`.

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

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