bmad-module-skill-forge 6.0.0 → 8.0.0

package/src/skf-analyze-source/customize.toml

@@ -59,8 +59,9 @@ analysis_report_template_path = "templates/analysis-report-template.md"
 # written the result files, at the end of every run that writes them
 # (generate-briefs.md, step-auto-scope.md and auto-docs-only.md), as:
 #   <on_complete> --result-path=<forge_data_folder>/analyze-source-result-latest.json
-# A run whose result file could not be written (result_path null in the
-# envelope) and a HALT call no hook. Useful for Slack notifications,
+# A HALT calls no hook, nor does a run whose result file or its -latest
+# copy could not be written (result_path null, or a result_file_write_failed
+# warning naming the copy, in the envelope). Useful for Slack notifications,
 # dashboard ingest, CI hooks, or chaining into a brief linter. A hook
 # failure is displayed and never fails the run.
 #

package/src/skf-analyze-source/references/auto-docs-only.md

@@ -145,9 +145,9 @@ Add `"coexistence": "alongside"` when `{coexistence_suffix}` is non-empty ([A]lo
 uv run {emitEnvelopeHelper} emit --workflow skf-analyze-source --run-dir "{run_dir}" --result-dir "{forge_data_folder}" < "{run_dir}/result-context.json"
 ```
 
-The emitter stamps the UTC time and the run id into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout. When `{headless_mode}` is true, display the line verbatim. A result file that could not be written leaves the line's `result_path` null and a `result_file_write_failed` warning in it, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `auto-docs-only:5`, path `{forge_data_folder}`): "The result contract could not be written: {its message}."
+The emitter stamps the UTC time and the run id into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout. When `{headless_mode}` is true, display the line verbatim. A per-run record that could not be written leaves `result_path` null, and a `-latest` copy that could not be written leaves it set; either adds a `result_file_write_failed` warning to the line, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `auto-docs-only:5`, path `{forge_data_folder}`): "The result contract could not be written: {its message}."
 
-If `{onCompleteCommand}` is non-empty and the line's `result_path` is not null, invoke it now: `{onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json`. Display a hook failure; it never fails the run.
+If `{onCompleteCommand}` is non-empty, the line's `result_path` is not null and its `warnings` hold no `result_file_write_failed` entry naming `analyze-source-result-latest.json`, invoke it now: `{onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json`. Display a hook failure; it never fails the run. When `{onCompleteCommand}` is non-empty but `result_path` is null or a `result_file_write_failed` warning names `analyze-source-result-latest.json` (the copy alone failed), skip the hook and say so: "on_complete skipped: `analyze-source-result-latest.json` was not written."
 
 ### 6. Chain to health check
 

package/src/skf-analyze-source/references/generate-briefs.md

@@ -287,11 +287,11 @@ The shared emitter writes the result files and prints the envelope; this section
 uv run {emitEnvelopeHelper} emit --workflow skf-analyze-source --run-dir "{run_dir}" --result-dir "{forge_data_folder}" < "{run_dir}/result-context.json"
 ```
 
-The emitter stamps the UTC time and the run id into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy (the record of the last run whose emitter wrote this copy, at a stable path; a caller reads its own run's `SKF_ANALYZE_RESULT_JSON` line), and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout (field rules in `references/headless-contract.md`). When `{headless_mode}` is true, display the line verbatim: it is the success signal of a headless run. A result file that could not be written leaves the line's `result_path` null and a `result_file_write_failed` warning in it, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `generate-briefs:9`, path `{forge_data_folder}`, with `brief_paths` and `unit_counts` from the payload): "The result contract could not be written: {its message}."
+The emitter stamps the UTC time and the run id into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy (the record of the last run whose emitter wrote this copy, at a stable path; a caller reads its own run's `SKF_ANALYZE_RESULT_JSON` line), and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout (field rules in `references/headless-contract.md`). When `{headless_mode}` is true, display the line verbatim: it is the success signal of a headless run. A per-run record that could not be written leaves `result_path` null, and a `-latest` copy that could not be written leaves it set; either adds a `result_file_write_failed` warning to the line, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `generate-briefs:9`, path `{forge_data_folder}`, with `brief_paths` and `unit_counts` from the payload): "The result contract could not be written: {its message}."
 
 ### 9b. On-Complete Hook (pipeline integration)
 
-If `{onCompleteCommand}` is non-empty and the §9 line's `result_path` is not null, invoke it now, after the emitter wrote the timestamped result JSON and its `analyze-source-result-latest.json` copy:
+If `{onCompleteCommand}` is non-empty, the §9 line's `result_path` is not null and its `warnings` hold no `result_file_write_failed` entry naming `analyze-source-result-latest.json` (the emitter wrote the timestamped result JSON and its `analyze-source-result-latest.json` copy), invoke it now:
 
 ```
 {onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json
@@ -303,8 +303,10 @@ The stable `-latest` path is preferred over the timestamped copy so downstream c
 - On non-zero exit / process error: display the hook failure (`on_complete hook failed (exit {code}): {stderr_snippet}`); it never fails the run.
 - **Never fail the workflow on hook errors** — the hook is for pipeline integration (Slack, dashboards, CI), not for gating skill-brief production.
 
+When `{onCompleteCommand}` is non-empty but `result_path` is null or a `result_file_write_failed` warning names `analyze-source-result-latest.json` (the copy alone failed), skip the hook and say so: "on_complete skipped: `analyze-source-result-latest.json` was not written." The hook never gets a `-latest` copy this run failed to write.
+
 If `{onCompleteCommand}` is empty, skip this section entirely (default behavior — no hook configured).
 
 ### 10. Chain to Health Check
 
-After the briefs are written (or skipped, or none was confirmed), the report updated, the summary presented, the run ended in §9 and the on-complete hook invoked (or skipped per empty `{onCompleteCommand}`), delete the run folder, whose payloads the emitter has read: `rm -rf "{run_dir}"`. Then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step: continue past the summary even though it reads as final.
+After the briefs are written (or skipped, or none was confirmed), the report updated, the summary presented, the run ended in §9 and the on-complete hook invoked (or skipped as §9b says), delete the run folder, whose payloads the emitter has read: `rm -rf "{run_dir}"`. Then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step: continue past the summary even though it reads as final.

package/src/skf-analyze-source/references/headless-contract.md

@@ -17,7 +17,7 @@ SKF_ANALYZE_RESULT_JSON: {"status":"success|error|redirect|skipped","report_path
 - `brief_paths`: absolute path of every `skill-brief.yaml` the run wrote (empty array if none). A brief is written only after it passed the brief writer and, outside the docs-only branch, the schema gate.
 - `unit_counts` — `confirmed` (units approved for briefs) and `skipped` (rejected in step 5, or the skipped target in coexistence §0c) counts; auto mode reports `confirmed:N, skipped:0`. `maybe` is a reserved slot, currently always `0`.
 - `mode`: `"auto"` when the invocation carries `[auto]`, from activation through step 1a and the docs-only branch; `"interactive"` otherwise, also in the step-by-step chain an `[auto]` run falls back to (step 1a §3, exit 1).
-- `result_path`: the per-run result file the emitter wrote, stamped by it; `null` for a HALT, which writes no result file, and when the write failed (a `result_file_write_failed` warning then says why).
+- `result_path`: the per-run result file the emitter wrote, stamped by it; `null` for a HALT, which writes no result file, when `--result-dir` names no folder (with no warning), and when the per-run record could not be written (a `result_file_write_failed` warning then says why); a `-latest` copy that could not be written leaves it set, and a `result_file_write_failed` warning names the copy.
 - `error`: on a HALT only, `{"phase", "reason"}` plus `path` when the halt names one.
 - `headless_decisions`: present when the run recorded an auto-decision: step 1a's §3b merge-or-split decision (gate `auto-scope.cohesion`), its §4 choices of shape for a repository on a framework or a parser library (gate `auto-scope.shape`) and its §5 choice of the documented language (gate `auto-scope.language`), and each gate default a headless run of the step-by-step chain took: `scan-project.scan`, `identify-units.classifications`, `map-and-detect.findings` (with the composite merges it accepted), `recommend.recommendations` and `generate-briefs.write`.
 - `warnings`: present when the run recorded at least one.
@@ -32,7 +32,7 @@ The step that ends the run stages `{run_dir}/result-context.json` with the envel
 uv run {emitEnvelopeHelper} emit --workflow skf-analyze-source --run-dir "{run_dir}" --result-dir "{forge_data_folder}" < "{run_dir}/result-context.json"
 ```
 
-The emitter stamps the UTC time, the run id, the decisions and warnings the run recorded into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the line. A result file that could not be written leaves `result_path` null and a `result_file_write_failed` warning in the line, and the run still finishes. If the emitter exits non-zero, the step corrects the payload from the message on its stderr and runs it once more; if it fails again, it HARD HALTs with exit code 4 (`write-failed`). Then `{onCompleteCommand}` runs, when it is set and `result_path` is not null, with `--result-path={forge_data_folder}/analyze-source-result-latest.json`; a hook failure is displayed and never fails the run. Last, the step deletes `{run_dir}` and chains to step 7.
+The emitter stamps the UTC time, the run id, the decisions and warnings the run recorded into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the line. A per-run record that could not be written leaves `result_path` null, and a `-latest` copy that could not be written leaves it set; either adds a `result_file_write_failed` warning to the line, and the run still finishes. If the emitter exits non-zero, the step corrects the payload from the message on its stderr and runs it once more; if it fails again, it HARD HALTs with exit code 4 (`write-failed`). Then `{onCompleteCommand}` runs, when it is set, `result_path` is not null and no `result_file_write_failed` warning names `analyze-source-result-latest.json`, with `--result-path={forge_data_folder}/analyze-source-result-latest.json`, and a hook failure is displayed and never fails the run; otherwise a set hook is skipped with "on_complete skipped: `analyze-source-result-latest.json` was not written." Last, the step deletes `{run_dir}` and chains to step 7.
 
 ## Halt Envelope
 

package/src/skf-analyze-source/references/step-auto-scope.md

@@ -447,8 +447,8 @@ Add `"coexistence": "alongside"` when `{coexistence_suffix}` is non-empty ([A]lo
 uv run {emitEnvelopeHelper} emit --workflow skf-analyze-source --run-dir "{run_dir}" --result-dir "{forge_data_folder}" < "{run_dir}/result-context.json"
 ```
 
-The emitter stamps the UTC time, the run id and the decisions and warnings the run recorded into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout (field rules in `references/headless-contract.md`). When `{headless_mode}` is true, display the line verbatim. A result file that could not be written leaves the line's `result_path` null and a `result_file_write_failed` warning in it, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `step-auto-scope:9`, path `{forge_data_folder}`): "The result contract could not be written: {its message}."
+The emitter stamps the UTC time, the run id and the decisions and warnings the run recorded into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout (field rules in `references/headless-contract.md`). When `{headless_mode}` is true, display the line verbatim. A per-run record that could not be written leaves `result_path` null, and a `-latest` copy that could not be written leaves it set; either adds a `result_file_write_failed` warning to the line, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `step-auto-scope:9`, path `{forge_data_folder}`): "The result contract could not be written: {its message}."
 
-If `{onCompleteCommand}` is non-empty and the line's `result_path` is not null, invoke it now: `{onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json`. Display a hook failure; it never fails the run.
+If `{onCompleteCommand}` is non-empty, the line's `result_path` is not null and its `warnings` hold no `result_file_write_failed` entry naming `analyze-source-result-latest.json`, invoke it now: `{onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json`. Display a hook failure; it never fails the run. When `{onCompleteCommand}` is non-empty but `result_path` is null or a `result_file_write_failed` warning names `analyze-source-result-latest.json` (the copy alone failed), skip the hook and say so: "on_complete skipped: `analyze-source-result-latest.json` was not written."
 
 Then delete the run folder, whose payloads the emitter has read: `rm -rf "{run_dir}"`. Load, read fully, then execute {nextStepFile} to run the shared workflow health check.

package/src/skf-audit-skill/customize.toml

@@ -62,10 +62,11 @@ drift_report_template_path = "assets/drift-report-template.md"
 
 # Optional post-audit hook: a shell command run from {project-root}, not an
 # agent instruction. Step 6 (references/report.md) runs it on a finished
-# audit, after the emitter wrote the result files, as:
+# audit, after the emitter wrote the per-run record (`result_path` not null),
+# as:
 #   <on_complete> --result-path=<{forge_version}/audit-skill-result-<YYYYMMDD-HHmmss>.json>
-# It never runs on a halt, nor when the result file could not be written. A
-# failure is shown to the user and never fails the audit.
+# It never runs on a halt, nor when the per-run record could not be written.
+# A failure is shown to the user and never fails the audit.
 #
 # Empty string = no-op (default).
 

package/src/skf-audit-skill/references/report.md

@@ -196,7 +196,7 @@ When On Activation step 3 fell back to the bundled `customize.toml`, add `"custo
 uv run {emitEnvelopeHelper} emit --workflow skf-audit-skill --run-dir "{run_dir}" --result-dir "{forge_version}" < "{run_dir}/result-context.json"
 ```
 
-It writes `{forge_version}/audit-skill-result-{YYYYMMDD-HHmmss}.json` (UTC; it picks the name) and its `audit-skill-result-latest.json` copy (the record of the last run whose emitter wrote this copy, at a stable path: a copy, not a symlink; a caller reads its own run's `SKF_AUDIT_RESULT_JSON` line), stamps the timestamp, `run_id`, `headless_decisions` and `warnings` into both, and prints the `SKF_AUDIT_RESULT_JSON:` line on stdout. When `{headless_mode}` is true, bind `{result_envelope_line}` ← the line and do not display it here: the shared health check displays it verbatim as the run's last line, so a `claude -p` caller reads `drift_score`, `report_path`, `next_workflow`, `upstream_moved` and `upstream_ref` from the final message. A result file that could not be written leaves `result_path` null and a `result_file_write_failed` warning in the line, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HALT with **exit 4**, `halt_reason: "write-failed"`, phase `report:result-contract`: the run's result contract could not be written.
+It writes `{forge_version}/audit-skill-result-{YYYYMMDD-HHmmss}.json` (UTC; it picks the name) and its `audit-skill-result-latest.json` copy (the record of the last run whose emitter wrote this copy, at a stable path: a copy, not a symlink; a caller reads its own run's `SKF_AUDIT_RESULT_JSON` line), stamps the timestamp, `run_id`, `headless_decisions` and `warnings` into both, and prints the `SKF_AUDIT_RESULT_JSON:` line on stdout. When `{headless_mode}` is true, bind `{result_envelope_line}` ← the line and do not display it here: the shared health check displays it verbatim as the run's last line, so a `claude -p` caller reads `drift_score`, `report_path`, `next_workflow`, `upstream_moved` and `upstream_ref` from the final message. A per-run record that could not be written leaves `result_path` null, and a `-latest` copy that could not be written leaves it set; either adds a `result_file_write_failed` warning to the line, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HALT with **exit 4**, `halt_reason: "write-failed"`, phase `report:result-contract`: the run's result contract could not be written.
 
 **Hard-halt envelope (headless only).** Every hard halt prints its envelope through the emitter on **stderr** with `status: "error"` and the `exit_code` / `halt_reason` for its failure class, as each step's **Halt envelope** paragraph shows: it is the only failure signal a wrapping pipeline receives. `drift_score` carries its last known value (`null` if classification never ran); `report_path` is `null` when the report write failed.
 

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

@@ -115,6 +115,64 @@
               "type": ["integer", "null"]
             }
           }
+        },
+        "stage_outcomes": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "What the capstone (Stage 6), verification (Stage 7) and refinement (Stage 8) stages did, written by campaign-state.py set-campaign beside each summary: completed, skipped (a stage skipped on purpose, --no-<field>) or failed, with the failure's halt_reason (no-result when the sub-skill printed no line, result-unreadable when its line could not be read) and exit_code (null when it gave none). Optional: a stage is absent until set-campaign records it, so older states still validate.",
+          "properties": {
+            "capstone": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["outcome"],
+              "properties": {
+                "outcome": {
+                  "type": "string",
+                  "enum": ["completed", "skipped", "failed"]
+                },
+                "halt_reason": {
+                  "type": ["string", "null"]
+                },
+                "exit_code": {
+                  "type": ["integer", "null"]
+                }
+              }
+            },
+            "verification": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["outcome"],
+              "properties": {
+                "outcome": {
+                  "type": "string",
+                  "enum": ["completed", "skipped", "failed"]
+                },
+                "halt_reason": {
+                  "type": ["string", "null"]
+                },
+                "exit_code": {
+                  "type": ["integer", "null"]
+                }
+              }
+            },
+            "refinement": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["outcome"],
+              "properties": {
+                "outcome": {
+                  "type": "string",
+                  "enum": ["completed", "skipped", "failed"]
+                },
+                "halt_reason": {
+                  "type": ["string", "null"]
+                },
+                "exit_code": {
+                  "type": ["integer", "null"]
+                }
+              }
+            }
+          }
         }
       }
     },

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

@@ -51,7 +51,7 @@ Every write to `_campaign-state.yaml` goes through `scripts/campaign-state.py`.
 | `set-skill` | step-05, step-10, step-resume | a skill's `status`, `quality_score`, `skill_path`, `brief_path` or `export` outcome (`--export`); `active` stamps `started_at` once, `completed` stamps `completed_at`, `pending` clears both and the `export` outcome |
 | `append-workarounds` | step-05 | entries of a skill's `workarounds_applied`, each once |
 | `apply-batch` | step-06 | the Tier B batch from its line-to-skill map: `--start`, `--results-file` or `--no-results` |
-| `set-campaign` | steps 07 to 09 | `architecture_doc_path`, and the capstone, verification or refinement summary read from the sub-skill's envelope line (`capstone.verified` with the verification) |
+| `set-campaign` | steps 07 to 09 | `architecture_doc_path`, and the capstone, verification or refinement summary read from the sub-skill's envelope line (`capstone.verified` with the verification); null for a stage skipped on purpose (`--no-<field>`), a sub-skill that printed no line (`--no-result <field>`, a `not_recorded` row with halt reason `no-result`) or a line it cannot read (one that does not parse, or has no `status` or `exit_code`: a `not_recorded` row with halt reason `result-unreadable`, exit 0); and `stage_outcomes`, each stage `completed`, `skipped` or `failed` with its halt reason and exit code |
 | `set-stage` | steps 05, 10, 11 | `current_stage` alone |
 | `recover` | step-resume | `.bak` over the primary, when `.bak` validates (exit 9 otherwise) |
 | `archive` | SKILL.md (overwrite) | nothing: it moves the state, its `.bak` and the brief into a new folder under `archive/` and returns it |

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

@@ -66,7 +66,7 @@ Invoke QS in `--batch` mode with the generated batch file:
 skf-quick-skill --batch {batchFile}
 ```
 
-QS `--batch` implies `--headless`. When the batch ends it prints a `batch_summary` event on stderr: keep its `summary_path`, the batch summary file that holds each target's result.
+QS `--batch` implies `--headless`. When the batch ends it prints a `batch_summary` event on stderr: keep its `summary_path`, the batch summary file that holds each target's result. When its `summary_path` is null, QS could not write that file: keep the event's `batch_file` (QS's `batch.jsonl`, which holds each target's result) as `<summary_path>` instead, and log the event's `summary_write_failed` warning, type `event`.
 
 ### §5: Record Results
 
@@ -84,7 +84,7 @@ uv run {stateScript} apply-batch --state-file {stateFile} --map-file {batchMapFi
 
 A `completed` result sets the skill `completed`, with `completed_at` from the clock, its `quality_score` (the skill-check score QS records, not a test-skill score) and its `skill_path`; a `failed` one sets it `failed`. Log each entry of the helper's `failed[]` with its `error_code` (`no-batch-result` when the summary holds no result for its line), type `event`.
 
-When QS printed no `batch_summary` event (run no record call), or the record call exits 2 (a missing summary or map, or a summary that belongs to another batch file), fail every skill the map lists instead, and log why: never guess which target built which skill.
+When QS printed no `batch_summary` event (run no record call), or the record call exits 2 (a missing or unreadable summary, batch file or map, or results that belong to another batch file), fail every skill the map lists instead, and log why: never guess which target built which skill.
 
 ```
 uv run {stateScript} apply-batch --state-file {stateFile} --map-file {batchMapFile} --no-results --stage 5

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

@@ -50,7 +50,7 @@ Invoke `skf-create-stack-skill` with `--headless` and these inputs, so it asks n
 - `stack_name`: the `stack_name` that `uv run {manifestScript} --stack-name {stateFile}` prints, the campaign name as a skill name cut to leave room for the `-stack` SS appends; when it prints null, leave the input out and SS names the stack `{project_name}-stack`
 - `architecture_doc_path`: `campaign.architecture_doc_path`, only when state sets it
 
-Keep the `SKF_STACK_RESULT_JSON` line it prints for §4, which records it. On `status` `error`, or no envelope, log its `halt_reason` (or "no result envelope", type `event`): verification and the campaign report still run.
+Keep the `SKF_STACK_RESULT_JSON` line it prints for §4, which records it: on stdout, or on stderr when SS halts. On `status` `error`, log its `halt_reason` (type `event`); a run with that line on neither stream is recorded in §4. Verification and the campaign report still run either way.
 
 ### §4: Record the Capstone and Complete the Stage
 
@@ -69,10 +69,10 @@ From a `success` envelope it sets `campaign.capstone`, the campaign-level summar
 - `campaign.capstone.verified`: `null` for now; set by the verify stage (step-08) once the stack is checked
 - `campaign.capstone.completed_at`: the time of the write, from the clock
 
-An `error` envelope sets `campaign.capstone` to `null` (the helper names it in `not_recorded`). When §2 found no skill to compose, or SS printed no envelope, record no capstone instead: `uv run {stateScript} set-campaign --state-file {stateFile} --no-capstone --stage 6`.
+An `error` envelope sets `campaign.capstone` to `null` (the helper names it in `not_recorded`). When §2 found no skill to compose, record no capstone instead: `uv run {stateScript} set-campaign --state-file {stateFile} --no-capstone --stage 6`. When SS printed no `SKF_STACK_RESULT_JSON` line on stdout or stderr, there is no result to read, whatever its exit code: record it with `uv run {stateScript} set-campaign --state-file {stateFile} --no-result capstone --stage 6`, log "no SKF_STACK_RESULT_JSON line (exit <code>)" with SS's exit code (type `event`), and go on. When the helper's `not_recorded` row gives the halt reason `result-unreadable` (SS printed a line that does not parse, or one with no `status` or `exit_code`), log "unparseable SKF_STACK_RESULT_JSON line" (type `event`) and go on.
 
 The capstone is a derived artifact: it is **not** tracked as a skill entry in the `skills[]` array. The constituent skill list and any verbose detail are reported in the step output and are available to downstream steps (verify, refine).
 
 ## OUTPUT
 
-Display capstone summary: stack skill name, path, quality score, and the list of constituent skills. Chain to `{nextStepFile}`.
+Display capstone summary: stack skill name, path, quality score, and the list of constituent skills, or "skipped" when §2 found no skill to compose, or "failed (<halt_reason>)" from the helper's `not_recorded` row. That row's `halt_reason` fills it (`failed (no-result)` when SS printed no line); when that is null, show `failed (exit <exit_code>)`, or `failed (no exit code)` when the exit code is null too. Chain to `{nextStepFile}`.

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

@@ -46,7 +46,7 @@ Once resolved (steps 2 and 3), persist the path at once, so the refine stage and
 
 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. 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.
+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 for §5: on stdout, or on stderr when VS halts. 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.
 
 ### §5: Record the VS Outcome and Complete the Stage
 
@@ -67,8 +67,8 @@ SKF_RESULT
 
 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).
 
-**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`.
+**On VS failure** (a line whose `status` is `error` or whose `exit_code` is non-zero): the helper sets `campaign.verification` to `null` and names it in `not_recorded`; log that line's `exit_code` and `halt_reason` (type `event`). Verification failure does NOT block the campaign: it produces diagnostic information for operator review. When §3 skipped VS, record no verification instead: `uv run {stateScript} set-campaign --state-file {stateFile} --no-verification --stage 7`. When VS printed no `SKF_VERIFY_STACK_RESULT_JSON` line on stdout or stderr, there is no result to read, whatever its exit code: record it with `uv run {stateScript} set-campaign --state-file {stateFile} --no-result verification --stage 7`, log "no SKF_VERIFY_STACK_RESULT_JSON line (exit <code>)" with VS's exit code (type `event`), and go on. When the helper's `not_recorded` row gives the halt reason `result-unreadable` (VS printed a line that does not parse, or one with no `status` or `exit_code`), log "unparseable SKF_VERIFY_STACK_RESULT_JSON line" (type `event`) and go on.
 
 ## OUTPUT
 
-Display verification summary: overall verdict (or "skipped" if architecture doc was not found), report path (if produced), and coverage percentage. Chain to `{nextStepFile}`.
+Display verification summary: overall verdict (or "skipped" if architecture doc was not found, or "failed (<halt_reason>)" from the helper's `not_recorded` row), report path (if produced), and coverage percentage. That row's `halt_reason` fills it (`failed (no-result)` when VS printed no line); when that is null, show `failed (exit <exit_code>)`, or `failed (no exit code)` when the exit code is null too. Chain to `{nextStepFile}`.

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

@@ -56,7 +56,7 @@ skf-refine-architecture --headless --architecture-doc <arch_path> --vs-report-pa
 - `--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.
 
-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.
+Keep the `SKF_REFINE_ARCHITECTURE_RESULT_JSON` line it prints for §5: on stdout, or on stderr when RA halts. 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.
 
 ### §5: Record the RA Outcome and Complete the Stage
 
@@ -75,8 +75,8 @@ SKF_RESULT
 - `campaign.refinement.issue_count`: from the envelope
 - `campaign.refinement.improvement_count`: from the envelope
 
-**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`.
+**On RA failure** (a line whose `status` is `error` or whose `exit_code` is non-zero): the helper sets `campaign.refinement` to `null` and names it in `not_recorded`; log that line's `exit_code` and `halt_reason` (type `event`). Refinement failure does NOT block the campaign: the campaign continues to export with whatever state exists. When §3 skipped RA, record no refinement instead: `uv run {stateScript} set-campaign --state-file {stateFile} --no-refinement --stage 8`. When RA printed no `SKF_REFINE_ARCHITECTURE_RESULT_JSON` line on stdout or stderr, there is no result to read, whatever its exit code: record it with `uv run {stateScript} set-campaign --state-file {stateFile} --no-result refinement --stage 8`, log "no SKF_REFINE_ARCHITECTURE_RESULT_JSON line (exit <code>)" with RA's exit code (type `event`), and go on. When the helper's `not_recorded` row gives the halt reason `result-unreadable` (RA printed a line that does not parse, or one with no `status` or `exit_code`), log "unparseable SKF_REFINE_ARCHITECTURE_RESULT_JSON line" (type `event`) and go on.
 
 ## 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}`.
+Display refinement summary: refined architecture path (or "skipped" if architecture doc was not found, or "failed (<halt_reason>)" from the helper's `not_recorded` row), gap count, issue count, and improvement count. That row's `halt_reason` fills it (`failed (no-result)` when RA printed no line); when that is null, show `failed (exit <exit_code>)`, or `failed (no exit code)` when the exit code is null too. Chain to `{nextStepFile}`.

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

@@ -44,7 +44,7 @@ uv run {reportScript} \
     --decision-log {decisionLogFile}
 ```
 
-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.
+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), `stage_outcomes` (whether the capstone, verification and refinement stages completed, were skipped or failed, with a failure's `halt_reason` and `exit_code`; null before the capstone stage ran) 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 the summary stats from the result JSON (type `event`).
 

package/src/skf-campaign/scripts/campaign-render-batch.py

@@ -47,12 +47,17 @@ Record mode (--record): joins the QS batch summary (`summary_path` of the
 `quality_score`) or `failed` (with QS's `error_code`, or `no-batch-result`
 when the summary holds no result for its line). A result whose target is not
 the mapped line's target means the summary belongs to another batch file, and
-nothing is joined.
+nothing is joined. When QS could not write the summary (`summary_path` null),
+the event's `batch_file` names the batch run folder's `batch.jsonl`, and
+--record takes that file instead: a path named `batch.jsonl` is read through
+the shared skf-quick-batch.py's `load` (a later result line for a batch
+number wins, a spoiled line is skipped), and its results are joined as a
+summary's are.
 
 CLI:
   uv run campaign-render-batch.py --state-file <p> --brief-file <p> \
       [-o <batchFile>] [--map <mapFile>] [--directive-file <p>]
-  uv run campaign-render-batch.py --record <summary_path> --map <mapFile>
+  uv run campaign-render-batch.py --record <summary_path|batch_file> --map <mapFile>
 
 Output:
   render: batch text (one target per line) to {batchFile} via -o, else to
@@ -68,8 +73,8 @@ Output:
 Exit codes:
   0  batch file written (0+ targets), or results joined
   2  state file missing / unreadable / bad YAML, a directive that cannot be
-     read, a missing or unreadable map or summary, or a summary that does not
-     match the map (SUMMARY_MISMATCH)
+     read, a missing or unreadable map, summary or batch.jsonl, or a summary
+     or batch.jsonl that does not match the map (SUMMARY_MISMATCH)
   8  brief missing / unreadable (missing-brief HALT), or a selected Tier B skill
      has no matching brief target with a repo_url (unmatched-target)
 """
@@ -87,18 +92,25 @@ import yaml
 
 GATE_SCRIPT = Path(__file__).resolve().with_name("campaign-quality-gate.py")
 RESOLVE_PACKAGE_SCRIPT = Path(__file__).resolve().parent.parent.parent / "shared" / "scripts" / "skf-resolve-package.py"
+SHARED_SCRIPTS = RESOLVE_PACKAGE_SCRIPT.parent
 SELECTED_STATUSES = ("pending", "active")
 
 
-def _version_re() -> Any:
-    """skf-resolve-package.py's _VERSION_RE: the pins parse-target reads after `@`."""
-    spec = importlib.util.spec_from_file_location("skf_resolve_package", RESOLVE_PACKAGE_SCRIPT)
+def _shared(file_name: str) -> Any:
+    spec = importlib.util.spec_from_file_location(file_name[:-3].replace("-", "_"), SHARED_SCRIPTS / file_name)
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
-    return module._VERSION_RE
+    return module
+
+
+def _version_re() -> Any:
+    """skf-resolve-package.py's _VERSION_RE: the pins parse-target reads after `@`."""
+    return _shared(RESOLVE_PACKAGE_SCRIPT.name)._VERSION_RE
 
 
 VERSION_RE = _version_re()
+# QS's batch helper: --record reads a batch's batch.jsonl through its own load.
+qb = _shared("skf-quick-batch.py")
 
 
 def _err(message: str, code: str, exit_code: int, **extra: Any) -> int:
@@ -365,11 +377,30 @@ def _load_json(path: str, label: str) -> Tuple[Optional[Dict[str, Any]], int]:
     return data, 0
 
 
+def _load_batch_file(path: str) -> Tuple[Optional[Dict[str, Any]], int]:
+    """A QS batch run folder's batch.jsonl, read as a summary: its results, by batch number.
+
+    Read through skf-quick-batch.py's own load, so a later result line for a
+    batch number replaces an earlier one and a spoiled line is skipped.
+    """
+    if not Path(path).is_file():
+        return None, _err(f"Batch result file not found: {path}", "SUMMARY_NOT_FOUND", 2)
+    try:
+        state = qb.load(Path(path).parent)
+    except qb.BatchError as exc:
+        return None, _err(f"Batch result file unreadable: {exc}", "SUMMARY_PARSE_ERROR", 2)
+    return {"results": [state["results"][n] for n in sorted(state["results"])]}, 0
+
+
 def record(summary_file: str, map_file: str) -> int:
     batch_map, rc = _load_json(map_file, "map")
     if batch_map is None:
         return rc
-    batch_summary, rc = _load_json(summary_file, "summary")
+    if Path(summary_file).name == qb.BATCH_FILE:
+        # the event's batch_file: QS could not write the summary, so batch.jsonl holds the results
+        batch_summary, rc = _load_batch_file(summary_file)
+    else:
+        batch_summary, rc = _load_json(summary_file, "summary")
     if batch_summary is None:
         return rc
     try:
@@ -392,7 +423,9 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("-o", "--output", dest="output", help="batch file path (default: stdout)")
     parser.add_argument("--map", dest="map_file", help="line-to-skill map path (written, or read by --record)")
     parser.add_argument("--directive-file", help="campaign directive whose Skip List is applied")
-    parser.add_argument("--record", dest="summary_file", help="QS batch summary to join to --map")
+    parser.add_argument("--record", dest="summary_file",
+                        help="QS batch summary to join to --map, or the batch's batch.jsonl when summary_path "
+                        "is null")
     args = parser.parse_args(argv)
     if args.summary_file:
         if not args.map_file:

package/src/skf-campaign/scripts/campaign-report.py

@@ -14,7 +14,8 @@ Output (JSON on stdout):
    "quality_scores":{"skill":score,...},"duration":"...",
    "export_verdicts":{"skill":"pass|fallback|fail",...},"skills_excluded":["skill",...],
    "skills_exported":["skill",...],
-   "export_failures":[{"skill","halt_reason","exit_code"},...]}
+   "export_failures":[{"skill","halt_reason","exit_code"},...],
+   "stage_outcomes":{"capstone|verification|refinement":{"outcome","halt_reason","exit_code"}}}
 
 `export_verdicts` holds each completed skill's quality-gate verdict at Export
 and `skills_excluded` the completed skills the gate kept from export, both
@@ -30,6 +31,14 @@ halt_reason and exit code. Both are null when the Export stage did not run
 (`campaign.current_stage` below 9). The report's Export Gate table shows the
 same outcome per skill in its Export column.
 
+`stage_outcomes` is what the capstone, verification and refinement stages
+did: the `campaign.stage_outcomes` entry campaign-state.py set-campaign
+recorded for each one, as {"outcome", "halt_reason", "exit_code"} with
+`outcome` completed, skipped or failed (null for a stage it holds no
+outcome for). It is null when the capstone stage did not run
+(`campaign.current_stage` below 6). The report's Stages section shows the
+same outcome per stage, a failure with its halt_reason, else its exit code.
+
 --context-file also writes the payload skf-emit-result-envelope.py turns into
 the campaign's SKF_CAMPAIGN_RESULT_JSON line (schemas/
 skf-campaign-result-envelope.v1.json): the result above, with the report as
@@ -116,14 +125,19 @@ def _export_record(skill: Any) -> Optional[Dict[str, Any]]:
     return record if isinstance(record, dict) and record.get("status") in ("exported", "failed") else None
 
 
+def _failed_cell(record: Dict[str, Any]) -> str:
+    """A failure as the report shows it: its halt_reason, else its exit code, else none."""
+    why = record.get("halt_reason") or (
+        f"exit {record['exit_code']}" if record.get("exit_code") is not None else "no exit code")
+    return f"failed ({why})"
+
+
 def _export_cell(record: Optional[Dict[str, Any]], verdict: str) -> str:
     if record is None:
         return "not exported" if verdict == "fail" else "N/A"
     if record["status"] == "exported":
         return "exported"
-    why = record.get("halt_reason") or (
-        f"exit {record['exit_code']}" if record.get("exit_code") is not None else "no exit code")
-    return f"failed ({why})"
+    return _failed_cell(record)
 
 
 def _export_outcomes(state: Any) -> Dict[str, Any]:
@@ -146,6 +160,44 @@ def _export_outcomes(state: Any) -> Dict[str, Any]:
     return {"skills_exported": exported, "export_failures": failures}
 
 
+STAGES = (("capstone", "Capstone"), ("verification", "Verification"), ("refinement", "Refinement"))
+STAGE_OUTCOMES = ("completed", "skipped", "failed")
+
+
+def _stage_record(entry: Any) -> Optional[Dict[str, Any]]:
+    """A stage outcome campaign-state.py recorded, with its three keys, or None."""
+    if not isinstance(entry, dict) or entry.get("outcome") not in STAGE_OUTCOMES:
+        return None
+    return {"outcome": entry["outcome"], "halt_reason": entry.get("halt_reason"), "exit_code": entry.get("exit_code")}
+
+
+def _stage_outcomes(state: Any) -> Optional[Dict[str, Any]]:
+    """What the capstone, verification and refinement stages did; null before stage 6 ran."""
+    campaign = state.get("campaign") if isinstance(state, dict) else None
+    stage = campaign.get("current_stage") if isinstance(campaign, dict) else None
+    if not isinstance(stage, int) or isinstance(stage, bool) or stage < 6:
+        return None
+    held = campaign.get("stage_outcomes")
+    held = held if isinstance(held, dict) else {}
+    return {field: _stage_record(held.get(field)) for field, _label in STAGES}
+
+
+def _stages_section(outcomes: Optional[Dict[str, Any]]) -> str:
+    if outcomes is None:
+        return "The capstone, verification and refinement stages have not run."
+    lines = ["| Stage | Outcome |", "|-------|---------|"]
+    for field, label in STAGES:
+        record = outcomes[field]
+        if record is None:
+            cell = "not recorded"
+        elif record["outcome"] == "failed":
+            cell = _failed_cell(record)
+        else:
+            cell = record["outcome"]
+        lines.append(f"| {label} | {cell} |")
+    return "\n".join(lines)
+
+
 def _export_gate_section(
     classification: Optional[Dict[str, Any]], state: Optional[Dict[str, Any]] = None
 ) -> str:
@@ -273,6 +325,7 @@ def _compute_aggregates(
         "duration_table": "\n".join(duration_table_rows),
         "failed_skipped_section": "\n".join(failed_skipped_lines),
         "export_gate_section": _export_gate_section(classification, state),
+        "stages_section": _stages_section(_stage_outcomes(state)),
     }
 
 
@@ -324,6 +377,7 @@ def run(
             "halt_reason": "report-failure",
             **_counts(state),
             **_export_outcomes(state),
+            "stage_outcomes": _stage_outcomes(state),
             "campaign_report_path": None,
             "decision_log": decision_log,
         })
@@ -377,6 +431,7 @@ def run(
             None if classification is None else [e["name"] for e in classification["excluded"]]
         ),
         **_export_outcomes(state),
+        "stage_outcomes": _stage_outcomes(state),
     }
     _write_context(context_file, {
         "status": "success",
@@ -387,6 +442,7 @@ def run(
         "skills_excluded": result["skills_excluded"],
         "skills_exported": result["skills_exported"],
         "export_failures": result["export_failures"],
+        "stage_outcomes": result["stage_outcomes"],
         "campaign_report_path": result["report_path"],
         "decision_log": decision_log,
         "duration": result["duration"],