bmad-module-skill-forge 7.0.0 → 8.1.0

package/src/skf-analyze-source/SKILL.md

@@ -87,7 +87,7 @@ These rules apply to every step in this workflow:
    uv run {resolveCustomizationHelper} --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-analyze-source.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran) for step 5 to record in the run sink.
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-analyze-source.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `SKF helper skf-resolve-customization.py not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran) for step 5 to record in the run sink.
 
    Then bind, so stage files use the variable with no conditional at the usage site:
 

package/src/skf-audit-skill/SKILL.md

@@ -79,7 +79,7 @@ Stage 1b returns to init.md at §5b's **Record for report**, then §6. Step 1 §
    uv run {resolveCustomizationHelper} --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-audit-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. Then keep the reason as `{customization_resolver_unavailable}`, which step 6 hands to the emitter as a warning.
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-audit-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `SKF helper skf-resolve-customization.py not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. Then keep the reason as `{customization_resolver_unavailable}`, which step 6 hands to the emitter as a warning.
 
    Bind the two scalars the stages read, each to its bundled default when the merged value is empty or absent:
 

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-brief-skill/SKILL.md

@@ -65,7 +65,7 @@ Give the halt's own `halt_reason`: the helper derives `exit_code` from it. `skil
    uv run {resolveCustomizationHelper} --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-brief-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case add `customization_resolver_unavailable: <reason>` to `workflow_warnings[]` as the run's first warning.
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-brief-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `SKF helper skf-resolve-customization.py not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case add `customization_resolver_unavailable: <reason>` to `workflow_warnings[]` as the run's first warning.
 
    Bind the values the stage files use, taking the bundled default when the merged value is empty or absent:
 

package/src/skf-campaign/SKILL.md

@@ -37,7 +37,7 @@ Run these steps once, in order, before dispatching to Mode Routing.
    uv run {resolveCustomizationHelper} --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-campaign.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case, unless the invocation is `campaign status` (which writes nothing), log `customization_resolver_unavailable: <reason>` as an `event` in the decision log once `{campaignWorkspacePath}` is bound below (`references/campaign-contracts.md`, Decision Log).
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-campaign.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `SKF helper skf-resolve-customization.py not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case, unless the invocation is `campaign status` (which writes nothing), log `customization_resolver_unavailable: <reason>` as an `event` in the decision log once `{campaignWorkspacePath}` is bound below (`references/campaign-contracts.md`, Decision Log).
 
    Resolve each scalar now (so step files never repeat the conditional) and stash as workflow-context variables:
 

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); null for a stage skipped on purpose (`--no-<field>`) or a sub-skill that printed no line (`--no-result <field>`, a `not_recorded` row with halt reason `no-result`) |
+| `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

@@ -69,7 +69,7 @@ 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, 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.
+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).
 

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

@@ -67,7 +67,7 @@ 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 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.
+**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
 

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

@@ -75,7 +75,7 @@ SKF_RESULT
 - `campaign.refinement.issue_count`: from the envelope
 - `campaign.refinement.improvement_count`: from the envelope
 
-**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.
+**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
 

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"],

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

@@ -81,12 +81,21 @@ Operations:
                     (a file or `-`; the line's SKF_*_RESULT_JSON: prefix is
                     optional). A success envelope is recorded; an error
                     envelope, or --no-capstone and the like (a stage
-                    skipped on purpose), records null. --no-result <field>
-                    (repeatable) records a sub-skill that printed no result
-                    line: null, with halt reason no-result in its
-                    not_recorded row; it does not go with that field's
-                    --<field> or --no-<field>. A recorded verification also
-                    sets capstone.verified.
+                    skipped on purpose), records null. A line that does
+                    not parse, is not a JSON object, or has no string
+                    `status` or integer `exit_code` records null with halt
+                    reason result-unreadable in its not_recorded row (an
+                    empty line, or a file it cannot read or decode, is
+                    still exit 2). --no-result <field> (repeatable) records
+                    a sub-skill that printed no result line: null, with
+                    halt reason no-result in its not_recorded row; it does
+                    not go with that field's --<field> or --no-<field>.
+                    Each field it writes also sets
+                    campaign.stage_outcomes.<field>: `completed` with the
+                    envelope's exit_code, `skipped` for --no-<field>, or
+                    `failed` with the not_recorded row's halt_reason and
+                    exit_code. A recorded verification also sets
+                    capstone.verified.
   recover           Copy a .bak that validates over the primary (step-resume).
   archive           Move the state, its .bak and the brief, each one that
                     exists, into archive/<campaign name>-<UTC stamp>/ beside
@@ -150,7 +159,9 @@ Output (one JSON object on stdout):
              "last_updated", "current_stage", "changed": [...]} plus the
              operation's own keys (init: "quality_gate", "brief_file", null
              without --brief-out; apply-batch: "activated", "skipped",
-             "completed", "failed"; set-campaign: "recorded", "not_recorded")
+             "completed", "failed"; set-campaign: "recorded", and
+             "not_recorded", one {"field", "status", "halt_reason",
+             "exit_code"} row for each field it set to null)
   recover:  {"op", "state_file", "backup_file", "recovered", "last_updated",
              "current_stage"}
   archive:  {"op", "archive_dir", "moved": [...]}
@@ -423,8 +434,16 @@ def read_json(source: str, label: str) -> dict:
     return data
 
 
-def read_envelope(source: str, label: str) -> dict:
-    """A sub-skill's result envelope: the last SKF_*_RESULT_JSON line, or bare JSON."""
+def read_envelope(source: str, label: str) -> dict | None:
+    """A sub-skill's result envelope: the last SKF_*_RESULT_JSON line, or bare JSON.
+
+    None when that payload does not parse or is not a JSON object, which
+    set-campaign records as result-unreadable. json.loads raises ValueError
+    on a payload it cannot parse (JSONDecodeError is one, an integer of more
+    than 4,300 digits another) and RecursionError on nesting too deep for
+    it; both read as a payload that does not parse. An empty payload, or
+    input it cannot read or decode, is still exit 2.
+    """
     text = read_text(source, label)
     lines = [line for line in text.splitlines() if "_RESULT_JSON:" in line and "SKF_" in line]
     payload = lines[-1].split("_RESULT_JSON:", 1)[1].strip() if lines else text.strip()
@@ -432,11 +451,9 @@ def read_envelope(source: str, label: str) -> dict:
         raise StateError(EXIT_INPUT, "input-unreadable", f"{label} holds no result envelope")
     try:
         data = json.loads(payload)
-    except json.JSONDecodeError as exc:
-        raise StateError(EXIT_INPUT, "input-unreadable", f"{label} is not a result envelope: {exc}") from exc
-    if not isinstance(data, dict):
-        raise StateError(EXIT_INPUT, "input-unreadable", f"{label} is not a JSON object")
-    return data
+    except (ValueError, RecursionError):
+        return None
+    return data if isinstance(data, dict) else None
 
 
 def _skills_by_name(state: dict) -> dict[str, dict]:
@@ -792,6 +809,25 @@ def _refinement(envelope: dict, stamp: str) -> dict | None:
 SUMMARIES = (("capstone", _capstone), ("verification", _verification), ("refinement", _refinement))
 
 
+def _readable(envelope: dict | None) -> bool:
+    """An envelope set-campaign can read: an object with a string `status` and an integer `exit_code`.
+
+    The SS, VS and RA envelope schemas all require both, so a line missing
+    either is recorded result-unreadable, as step-10 records an Export line.
+    """
+    if not isinstance(envelope, dict):
+        return False
+    exit_code = envelope.get("exit_code")
+    return isinstance(envelope.get("status"), str) and isinstance(exit_code, int) and not isinstance(exit_code, bool)
+
+
+def _failed_outcome(row: dict) -> dict:
+    """The stage outcome of a field set-campaign did not record, from its not_recorded row."""
+    reason = row["halt_reason"]
+    return {"outcome": "failed", "halt_reason": reason if isinstance(reason, str) else None,
+            "exit_code": row["exit_code"]}
+
+
 def op_set_campaign(args: argparse.Namespace) -> dict:
     no_result = set(args.no_result or ())
     for field, _build in SUMMARIES:
@@ -811,24 +847,36 @@ def op_set_campaign(args: argparse.Namespace) -> dict:
             campaign["architecture_doc_path"] = args.architecture_doc_path
             changed.append("campaign.architecture_doc_path")
         for field, build in SUMMARIES:
-            if field in envelopes:
+            # Each branch decides the stage outcome; a failed one takes its row's halt_reason and exit_code.
+            if field in envelopes and not _readable(envelopes[field]):
+                value = None
+                row = {"field": field, "status": None, "halt_reason": "result-unreadable", "exit_code": None}
+                not_recorded.append(row)
+                outcome = _failed_outcome(row)
+            elif field in envelopes:
                 envelope = envelopes[field]
                 value = build(envelope, stamp)
                 if value is None:
-                    not_recorded.append({"field": field, "status": envelope.get("status"),
-                                         "halt_reason": envelope.get("halt_reason"),
-                                         "exit_code": envelope.get("exit_code")})
+                    row = {"field": field, "status": envelope.get("status"),
+                           "halt_reason": envelope.get("halt_reason"), "exit_code": envelope.get("exit_code")}
+                    not_recorded.append(row)
+                    outcome = _failed_outcome(row)
                 else:
                     recorded.append(field)
+                    outcome = {"outcome": "completed", "halt_reason": None, "exit_code": envelope["exit_code"]}
             elif getattr(args, f"no_{field}"):
                 value = None
                 not_recorded.append({"field": field, "status": None, "halt_reason": None, "exit_code": None})
+                outcome = {"outcome": "skipped", "halt_reason": None, "exit_code": None}
             elif field in no_result:
                 value = None
-                not_recorded.append({"field": field, "status": None, "halt_reason": "no-result", "exit_code": None})
+                row = {"field": field, "status": None, "halt_reason": "no-result", "exit_code": None}
+                not_recorded.append(row)
+                outcome = _failed_outcome(row)
             else:
                 continue
             campaign[field] = value
+            campaign.setdefault("stage_outcomes", {})[field] = outcome
             changed.append(f"campaign.{field}")
             if field == "verification" and isinstance(campaign.get("capstone"), dict):
                 verdict = (value or {}).get("overall_verdict")

package/src/skf-campaign/templates/campaign-report-template.md

@@ -21,6 +21,10 @@
 |------|------|--------|---------------|-----|-------------|
 {{skills_table}}
 
+## Stages
+
+{{stages_section}}
+
 ## Export Gate
 
 {{export_gate_section}}

package/src/skf-create-skill/SKILL.md

@@ -82,7 +82,7 @@ These rules apply to every step in this workflow:
    uv run {resolveCustomizationHelper} --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-create-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran) for step 1 §0 to record in each brief's run folder.
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-create-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `SKF helper skf-resolve-customization.py not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran) for step 1 §0 to record in each brief's run folder.
 
    Apply the resolved values so the surface is not a silent no-op: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (entries prefixed `file:` are paths or globs whose contents load as facts), except a `!` entry and the entry it names (`!file:{project-root}/**/project-context.md` drops the bundled project-context default); and stash `{onCompleteCommand}` ← `workflow.on_complete` (empty string = no-op) for step 8 to invoke once each brief's result contract is written. After activation completes, execute each entry in `workflow.activation_steps_append` in order.