bmad-module-skill-forge 2.2.0 → 3.0.0

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

@@ -2,7 +2,8 @@
 nextStepFile: 'step-09-refine.md'
 stateSchemaFile: 'assets/campaign-state-schema.json'
 stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
-backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+decisionLogFile: '{campaignWorkspacePath}/_campaign-decision-log.md'
+stateScript: 'scripts/campaign-state.py'
 validateScript: 'scripts/campaign-validate-state.py'
 ---
 
@@ -16,59 +17,57 @@ Invoke VS (skf-verify-stack) in headless mode against all completed campaign ski
 
 ## 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`.
+- Write `campaign.current_stage` = 7 only in this stage's final state write (§5), after the verification is recorded: step-resume resumes at `current_stage + 1`, so an early write skips unfinished work.
+- Write state and decision-log entries only through `{stateScript}`, and on a non-zero exit HALT with the same code (State Contract in `references/campaign-contracts.md`). A log entry is `uv run {stateScript} log --log-file {decisionLogFile} --type <decision|auto|event> --text '<entry>'`.
+- If `{headless_mode}` is true, emit this stage's progress events, and at any HARD HALT the error envelope, per `references/campaign-contracts.md`. VS runs headless with `--headless`.
 
 ## TASKS
 
-### §1 — Read + Validate State
+### §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
+### §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
+### §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).
+2. Otherwise discover it: check `{project-root}/docs/architecture.md` (SKF convention), then `{project-root}/_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.
+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 (type `event`) and go to §5 with no verification.
 
-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.
+Once resolved (steps 2 and 3), persist the path at once, so the refine stage and any resume reuse it without prompting again: `uv run {stateScript} set-campaign --state-file {stateFile} --architecture-doc-path <path>`. Then proceed to §4 with the resolved path.
 
-### §4 — Invoke VS
+### §4: Invoke VS
 
-Invoke `skf-verify-stack` with `--headless --architecture-doc <path>`, where `<path>` is the architecture doc discovered in §3.
+Invoke `skf-verify-stack` with `--headless --architecture-doc <path>`, where `<path>` is the architecture doc §3 resolved.
 
-VS discovers skills from its own configured `{skills_output_folder}` — the campaign does NOT pass individual skill paths. Capture the result envelope from stdout:
+VS discovers skills from its own configured `{skills_output_folder}`; the campaign does NOT pass individual skill paths. Keep the `SKF_VERIFY_STACK_RESULT_JSON` line it prints on stdout for §5. Its fields are defined once, by `shared/scripts/schemas/skf-verify-stack-result-envelope.v1.json` (in the SKF module: `{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during development); §5 reads `report_path`, `overall_verdict`, `coverage_percentage` and `recommendation_count` from it.
 
-```
-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
+### §5: Record the VS Outcome and Complete the Stage
 
-**On success** (exit code 0): persist the summary to `campaign.verification` (detailed findings stay in the external report):
+Record the outcome and the stage in one write, passing the §4 envelope line to the helper, which reads it (never copy its fields by hand):
 
-- `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
+```
+uv run {stateScript} set-campaign --state-file {stateFile} --verification - --stage 7 <<'SKF_RESULT'
+<the SKF_VERIFY_STACK_RESULT_JSON line VS printed>
+SKF_RESULT
+```
 
-Also set `campaign.capstone.verified` to `true` when `overall_verdict == "Verified"`, otherwise `false` (only if a `campaign.capstone` entry exists from step-07).
+**On success** (`status` `success`, exit code 0), the helper persists the summary to `campaign.verification` (detailed findings stay in the external report):
 
-**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.
+- `campaign.verification.report_path`: `report_path` from the envelope, the timestamped report no later Verify Stack run rewrites (step-09 hands it to RA)
+- `campaign.verification.overall_verdict`: `overall_verdict` from the envelope, one of `FEASIBLE`, `CONDITIONALLY_FEASIBLE` or `NOT_FEASIBLE`
+- `campaign.verification.coverage_percentage`: from the envelope
+- `campaign.verification.recommendation_count`: from the envelope
 
-### §6 — Stage Completion
+It also sets `campaign.capstone.verified` to `true` when `overall_verdict` is `FEASIBLE`, otherwise `false` (only if a `campaign.capstone` entry exists from step-07).
 
-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).
+**On VS failure** (a non-zero exit, an `error` envelope): the helper sets `campaign.verification` to `null` and names it in `not_recorded`; log the exit code and `halt_reason` (from the envelope or stderr, type `event`). Verification failure does NOT block the campaign: it produces diagnostic information for operator review. When VS printed no envelope, or §3 skipped it, record no verification instead: `uv run {stateScript} set-campaign --state-file {stateFile} --no-verification --stage 7`.
 
 ## OUTPUT
 

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

@@ -2,7 +2,8 @@
 nextStepFile: 'step-10-export.md'
 stateSchemaFile: 'assets/campaign-state-schema.json'
 stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
-backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+decisionLogFile: '{campaignWorkspacePath}/_campaign-decision-log.md'
+stateScript: 'scripts/campaign-state.py'
 validateScript: 'scripts/campaign-validate-state.py'
 ---
 
@@ -16,67 +17,65 @@ Invoke RA (skf-refine-architecture) in headless mode with the project's architec
 
 ## 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`.
+- Write `campaign.current_stage` = 8 only in this stage's final state write (§5), after the refinement is recorded: step-resume resumes at `current_stage + 1`, so an early write skips unfinished work.
+- Write state and decision-log entries only through `{stateScript}`, and on a non-zero exit HALT with the same code (State Contract in `references/campaign-contracts.md`). A log entry is `uv run {stateScript} log --log-file {decisionLogFile} --type <decision|auto|event> --text '<entry>'`.
+- If `{headless_mode}` is true, emit this stage's progress events, and at any HARD HALT the error envelope, per `references/campaign-contracts.md`. RA runs headless with `--headless`.
 
 ## TASKS
 
-### §1 — Read + Validate State
+### §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
+### §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
+### §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`.
+2. Otherwise check `{project-root}/docs/architecture.md`, then `{project-root}/_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.
+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 (type `event`) and go to §5 with no refinement.
 
-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.
+Once resolved (steps 2 and 3), persist the path if state does not hold it yet: `uv run {stateScript} set-campaign --state-file {stateFile} --architecture-doc-path <path>`. 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.
+**VS feasibility report:** read `campaign.verification.report_path` from state, where step-08 saved the report VS wrote, so a chained run and a resumed one pass the same report. When it is null, or `campaign.verification` is unset (VS failed or step-08 skipped it), RA runs without a report: never look for one by file name.
 
-### §4 — Invoke RA
+### §4: Invoke RA
 
 Invoke `skf-refine-architecture` with:
 
 ```
-skf-refine-architecture --headless --architecture-doc <arch_path> [--vs-report-path <report_path>] [--scope-skills <names>]
+skf-refine-architecture --headless --architecture-doc <arch_path> --vs-report-path <report_path|none> [--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).
+- `--vs-report-path`: `campaign.verification.report_path` from §3, or `none` when state holds no report path.
 - `--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:
+Keep the `SKF_REFINE_ARCHITECTURE_RESULT_JSON` line it prints on stdout for §5. Its fields are defined once, by `shared/scripts/schemas/skf-refine-architecture-result-envelope.v1.json` (in the SKF module: `{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during development); §5 reads `status`, `refined_path`, `gap_count`, `issue_count` and `improvement_count` from it.
 
-```
-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
+### §5: Record the RA Outcome and Complete the Stage
 
-**On success** (exit code 0): persist the summary to `campaign.refinement` (the refined document itself lives at `refined_path`):
+Record the outcome and the stage in one write, passing the §4 envelope line to the helper, which reads it (never copy its fields by hand):
 
-- `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
+```
+uv run {stateScript} set-campaign --state-file {stateFile} --refinement - --stage 8 <<'SKF_RESULT'
+<the SKF_REFINE_ARCHITECTURE_RESULT_JSON line RA printed>
+SKF_RESULT
+```
 
-**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.
+**On success** (`status` `success`, exit code 0), the helper persists the summary to `campaign.refinement` (the refined document itself lives at `refined_path`):
 
-### §6 — Stage Completion
+- `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
 
-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).
+**On RA failure** (a non-zero exit, an `error` envelope): the helper sets `campaign.refinement` to `null` and names it in `not_recorded`; log the exit code and `halt_reason` (from the envelope or stderr, type `event`). Refinement failure does NOT block the campaign: the campaign continues to export with whatever state exists. When RA printed no envelope, or §3 skipped it, record no refinement instead: `uv run {stateScript} set-campaign --state-file {stateFile} --no-refinement --stage 8`.
 
 ## OUTPUT
 

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

@@ -2,7 +2,9 @@
 nextStepFile: 'step-11-maintenance.md'
 stateSchemaFile: 'assets/campaign-state-schema.json'
 stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
-backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+decisionLogFile: '{campaignWorkspacePath}/_campaign-decision-log.md'
+gateScript: 'scripts/campaign-quality-gate.py'
+stateScript: 'scripts/campaign-state.py'
 validateScript: 'scripts/campaign-validate-state.py'
 ---
 
@@ -12,94 +14,104 @@ validateScript: 'scripts/campaign-validate-state.py'
 
 ## 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.
+Classify every completed skill against the quality gate, present the verdicts for operator review, and gate the export of the skills that clear it behind explicit confirmation. This is the only campaign stage whose gate holds back a file write: nothing is exported 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".
+- Write `campaign.current_stage` = 9 only in this stage's final state write (§6), after the export gate: step-resume resumes at `current_stage + 1`, so an early write skips unfinished work, and a campaign cancelled at the gate shows the gate again when it resumes.
+- Write state and decision-log entries only through `{stateScript}`, and on a non-zero exit HALT with the same code (State Contract in `references/campaign-contracts.md`). A log entry is `uv run {stateScript} log --log-file {decisionLogFile} --type <decision|auto|event> --text '<entry>'`.
+- If `{headless_mode}` is true, auto-proceed past the write-gate with `[E]` and log "headless: auto-proceed past export write-gate" (type `auto`); emit this stage's progress events, and at any HARD HALT the error envelope, per `references/campaign-contracts.md`.
 
 ## TASKS
 
-### §1 — Read + Validate State
+### §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
+### §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).
+If `campaign.directive_path` is set in state, the gate script applies its `## Quality Overrides` itself (§3), so do not adjust the gate by hand. Read any other section as campaign-wide context, 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
+### §3: Collect Export Candidates
 
-Gather all skills from `skills[]` with `status == "completed"`. These are the export candidates.
+Classify every completed skill against its quality gate, passing `--directive-file` when state sets `campaign.directive_path`; never compare scores by hand:
 
-If no completed skills exist, display a warning and proceed directly to §6 (stage completion) — there is nothing to export.
+```
+uv run {gateScript} classify --state-file {stateFile} [--directive-file <campaign.directive_path>]
+```
+
+Each completed skill gets a `verdict`: `pass` (score at or above its `soft_target`), `fallback` (at or above its `soft_fallback`) or `fail` (below the fallback, or no score). Only `pass` and `fallback` skills are export candidates (`export[]`); `excluded[]` lists the others with their `reason`, and they stay on disk and in the report. Each row's `export_name` is the skill folder its build wrote, the name `skf-export-skill` resolves: for a Tier B skill quick-skill names it after the library, not the campaign target. A Tier B score is the skill-check score QS records, not a test-skill score. Log each `excluded[]` skill and each `unparsed` or `warnings` entry to the decision log. On exit 2 (an override that breaks the gate, or a directive that cannot be read), HALT (exit code 2, `invalid-input`) with its `error`.
+
+If `export[]` is empty (no completed skill, or none clears the gate), display a warning naming any `excluded[]` skills and proceed directly to §6 (stage completion): there is nothing to export.
+
+Present the verdicts, one row per entry of its `skills[]`:
 
-Present a summary table of export candidates:
+| # | Name | Tier | Quality Score | Gate | Export Name | Skill Path |
+|---|------|------|---------------|------|-------------|------------|
+| 1 | {name} | {tier} | {quality_score} | {verdict} | {export_name} | {skill_path} |
+| ... | ... | ... | ... | ... | ... | ... |
 
-| # | Name | Tier | Quality Score | Skill Path |
-|---|------|------|---------------|------------|
-| 1 | {name} | {tier} | {quality_score} | {skill_path} |
-| ... | ... | ... | ... | ... |
+When `excluded[]` is not empty, list it under the table: "**Not exported (below the quality gate):** {name} ({quality_score}: {reason}), ..."
 
-Display: "**{N} skill(s) ready for export.**"
+Display: "**{N} skill(s) ready for export.**" ({N} is the number of `export[]` skills.)
 
-### §4 — Write-Gate HALT
+### §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`:
+{N} skill(s) that clear the quality gate will be exported via `skf-export-skill`:
 
-{summary table from §3}
+{summary table and exclusions from §3}
 
-- **[E]xport all** — invoke `skf-export-skill` for each completed skill
-- **[C]ancel** — halt the campaign gracefully (no files written, resume later)
+- **[E]xport all**: invoke `skf-export-skill` for each skill in `export[]`
+- **[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".
+**GATE [default: E]**: in headless mode, auto-proceed with `[E]` (the RULES log line). `[E]` exports only the `export[]` skills; the excluded ones are logged at §3.
 
 #### 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.
+Log the cancellation (type `decision`), then HALT with exit code 11 (`export-cancelled`). Do NOT mark the campaign as failed: this is a graceful, resumable halt, and nothing of this stage is written, so the operator may resume later at this gate.
 
 #### On `[E]xport`:
 
-Log the export decision to the decision log, then proceed to §5.
+Log the export decision (type `decision`), then proceed to §5.
 
-### §5 — Invoke EX
+### §5: Invoke EX
 
-For each completed skill (from §3), invoke `skf-export-skill` in headless mode:
+For each `skills[]` row of §3 whose `name` is in `export[]`, invoke `skf-export-skill` in headless mode under the row's `export_name`:
 
 ```
-skf-export-skill {skill_name} --headless
+skf-export-skill {export_name} --headless
 ```
 
-Capture the result envelope `SKF_EXPORT_RESULT_JSON` per skill.
+Capture its result envelope `SKF_EXPORT_RESULT_JSON`, then record the outcome under the campaign `name`, so step-11's report and result envelope read it from state:
 
-**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.
+- **Exit code 0:** `uv run {stateScript} set-skill --state-file {stateFile} --skill {name} --export exported`, and log the result (type `event`).
+- **Non-zero exit:** `uv run {stateScript} set-skill --state-file {stateFile} --skill {name} --export failed --export-exit-code <exit_code> [--export-halt-reason <halt_reason>]`, with the envelope's `halt_reason` when it printed one, and log the error (type `event`: exit code, envelope or stderr). Continue with the remaining skills: one failure does not block the other exports.
 
 After all exports complete, display a summary:
 
 "**Export Results:**
 - Exported: {success_count} skill(s)
 - Failed: {fail_count} skill(s)
+- Not exported, below the quality gate: {excluded_count} skill(s)
 {list of failed skills if any}"
 
-### §6 — Stage Completion
+### §6: Stage Completion
+
+Write the stage:
 
-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.
+```
+uv run {stateScript} set-stage --state-file {stateFile} --stage 9
+```
 
 ## OUTPUT
 

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

@@ -2,10 +2,12 @@
 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'
+resultContextFile: '{campaignWorkspacePath}/_result-context.json'
+decisionLogFile: '{campaignWorkspacePath}/_campaign-decision-log.md'
 reportScript: 'scripts/campaign-report.py'
 reportTemplate: '{reportTemplatePath}'
+stateScript: 'scripts/campaign-state.py'
 validateScript: 'scripts/campaign-validate-state.py'
 ---
 
@@ -15,23 +17,21 @@ validateScript: 'scripts/campaign-validate-state.py'
 
 ## 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.
+Generate the campaign report from the accumulated state, record the campaign as finished, run the `on_complete` hook, build the headless result envelope, and chain to the health check, 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.
+- Write `campaign.current_stage` = 10 only in this stage's final state write (§3), after the report: step-resume resumes at `current_stage + 1`, capped at 10, so a report step cut short before §3 runs again. After §3 a resume reports the campaign complete and, in headless mode, prints its envelope again from `{resultContextFile}`; it does not run the §4 hook.
+- Write state and decision-log entries only through `{stateScript}`, and on a non-zero exit HALT with the same code (State Contract in `references/campaign-contracts.md`). A log entry is `uv run {stateScript} log --log-file {decisionLogFile} --type <decision|auto|event> --text '<entry>'`.
+- If `{headless_mode}` is true, emit this stage's progress events, and at any HARD HALT the error envelope, per `references/campaign-contracts.md`. The success envelope is built in §5 and displayed by the health check as the run's last line, never here.
 
 ## TASKS
 
-### §1 — Read + Validate State
+### §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
+### §2: Generate Campaign Report
 
 Invoke the campaign report script:
 
@@ -39,46 +39,43 @@ Invoke the campaign report script:
 uv run {reportScript} \
     --state-file {stateFile} \
     --template-file {reportTemplate} \
-    --output-file {reportFile}
+    --output-file {reportFile} \
+    --context-file {resultContextFile} \
+    --decision-log {decisionLogFile}
 ```
 
-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.
+Its JSON result on stdout carries `skills_completed`, `skills_failed`, `quality_scores`, `export_verdicts` (each completed skill's quality-gate verdict at Export), `skills_excluded` (the completed skills the gate kept from export), `skills_exported` and `export_failures` (what step-10 recorded: the skills `skf-export-skill` exported, and each skill whose export failed, with its `halt_reason` and `exit_code`; both null when Export did not run) and `duration`, already computed: §6 displays them, and §5 builds the envelope from `{resultContextFile}`, the payload the script also writes, on success and on failure alike.
 
-**On success** (exit code 0): log the report path and summary stats from the result JSON.
+**On success** (exit code 0): log the report path and the summary stats from the result JSON (type `event`).
 
-**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.
+**On failure** (exit code 2): the campaign itself has already completed, so do NOT discard it over a missing summary artifact. Display the error from stderr and log "report generation failed (degraded): {error}" (type `event`), then CONTINUE to §3. The payload the script wrote in its place is the degraded finish (`status` `error`, `halt_reason` `report-failure`, exit code 10, no report path), a signal in the envelope and never 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):
+### §3: Record the Finished Campaign
 
 ```
-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":"..."}
+uv run {stateScript} set-stage --state-file {stateFile} --stage 10
 ```
 
-- `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
+On exit 3, HALT (exit code 3, `invalid-state`) with its `errors[]`.
 
-When not in headless mode, skip this section silently.
+### §4: Post-Completion Hook
 
-### §4 — Stage Completion
+Skip this section when `{onComplete}` (resolved in On Activation) is empty. Otherwise run it now, after the final state write, so a hook that archives or commits the workspace captures the finished campaign. When §2 wrote the report, run `{onComplete} --report-path={reportFile}`; when §2 degraded, run `{onComplete}` without `--report-path`, since there is no report to read. Log the outcome (type `event`): a hook failure is recorded but never fails the campaign.
 
-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: Result Envelope
 
-### §5 — Chain to Health Check
+When `{headless_mode}` is true, build the campaign's result envelope from the payload §2 wrote:
+
+```
+uv run {emitEnvelopeHelper} emit --workflow skf-campaign < {resultContextFile}
+```
 
-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.
+`{emitEnvelopeHelper}` is the shared emitter (its path is in the Result Contract of `references/campaign-contracts.md`). It checks the line against `shared/scripts/schemas/skf-campaign-result-envelope.v1.json` (in the SKF module: `{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during development), the one definition of the envelope: the success line, or the degraded one when §2 failed. Bind `{result_envelope_line}` to the `SKF_CAMPAIGN_RESULT_JSON:` line it prints, and do not display it here: the health check displays it verbatim as the run's last line, the final message a `claude -p` caller reads. If `{resultContextFile}` is missing (the report script could not write it), give the same command `{"status": "error", "halt_reason": "report-failure", "decision_log": "{decisionLogFile}"}` on stdin instead. If the emitter exits non-zero, log its error (type `event`) and leave `{result_envelope_line}` empty.
 
-Display: "**Campaign complete.** Report at `{reportFile}`. Findings routing: {campaign.health_findings_queue}. Chaining to health check..."
+When not in headless mode, skip this section.
 
-Chain to `{nextStepFile}` (shared/health-check.md).
+### §6: Chain to Health Check
 
-## OUTPUT
+When `{headless_mode}` is false, display, from the §2 result: "**Campaign complete.** {skills_completed} completed, {skills_failed} failed in {duration}. Report at `{reportFile}`." When §2 degraded, display "**Campaign finished, but the report could not be generated** (see the decision log); state is intact." instead. In headless mode display nothing: the envelope is the run's last line.
 
-Display campaign completion summary: skills completed, skills failed, report path, total duration. Chain to `{nextStepFile}`.
+Chain to `{nextStepFile}`: the health-check step is the true terminal step, so do not stop here even though the summary reads as final.