bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/skf-brief-skill/references/write-brief.md

@@ -5,9 +5,6 @@ nextStepFile: 'health-check.md'
 writeSkillBriefProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-write-skill-brief.py'
   - '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
-emitBriefEnvelopeProbeOrder:
-  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
-  - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
 forgeTierRwProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-forge-tier-rw.py'
   - '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
@@ -32,7 +29,7 @@ forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 
 **Resolve `{writeSkillBriefHelper}`** from `{writeSkillBriefProbeOrder}`; first existing path wins. HALT if no candidate exists.
 
-`{briefSchemaPath}` and `{versionResolutionFile}` document the brief contract for human readers. The deterministic enforcement of that contract lives in `{writeSkillBriefHelper}` and its JSON Schema artifact at `src/shared/scripts/schemas/skill-brief.v1.json`. Load `{briefSchemaPath}` only if you need to explain a specific field to the user during inline adjustments — otherwise skip the read; the script is the source of truth.
+`assets/skill-brief-schema.md` and `{versionResolutionFile}` document the brief contract for human readers. The deterministic enforcement of that contract lives in `{writeSkillBriefHelper}` and its JSON Schema artifact at `src/shared/scripts/schemas/skill-brief.v1.json`. Load `assets/skill-brief-schema.md` only if you need to explain a specific field to the user during inline adjustments; otherwise skip the read: the script is the source of truth.
 
 ### 2. Resolve Output Path
 
@@ -46,11 +43,19 @@ The script's atomic-write helper creates parent directories as needed (`mkdir -p
 
 Before writing, check whether the resolved target path already exists.
 
-**Ratify path (`ratify_mode: true` in workflow context):**
+**Ratify path (`ratify_mode: true` in workflow context):** step 1 (`references/gather-intent-ratify.md`) authorized overwriting only the brief it read, `ratify_source_path`: interactively by `[R] Ratify`, then reviewed and approved at step 4, or headlessly by a `from_brief` argument. Check whether the target is that file (the same file through any path or link), each path written as it is on its line between the markers:
 
-The overwrite was already authorized when ratify mode was entered — interactively at step 1 §3.1a (`[R] Ratify` against the same file, then reviewed and approved at step 4), or headlessly at the step 1 §8 GATE `from_brief` route (the operator pointed the run at a brief to ratify). Either way, skip the interactive prompt below; log a single-line `brief-skill: ratify-mode auto-overwriting existing brief at {path}` and proceed to §3. **This ratify branch takes precedence over both the interactive and headless branches below** — when `ratify_mode` is set, neither of those runs. In particular, a headless ratify (`from_brief`) auto-overwrites the brief in place without requiring `force`; `force` governs only the derive route, where overwriting a pre-existing brief is a genuine clobber the operator must opt into.
+```bash
+uv run python -c 'import os, sys; a, b = sys.stdin.read().splitlines()[:2]; print("same" if os.path.exists(a) and os.path.exists(b) and os.path.samefile(a, b) else "different")' <<'SKF_PATHS'
+{resolved-target-path}
+{ratify_source_path}
+SKF_PATHS
+```
+
+- **`same`:** skip both gates below, with no `force` needed: log a single-line `brief-skill: ratify-mode auto-overwriting existing brief at {path}` and proceed to §3.
+- **`different`** (the brief lives outside `{forge_data_folder}/<name>/`, or step 4 renamed it): an existing file at the target is another brief, so the gates below apply as on the derive route.
 
-**Interactive (`{headless_mode}` is false, `ratify_mode` not set):**
+**Interactive (`{headless_mode}` is false), unless the ratify check printed `same`:**
 
 If the file exists, present:
 
@@ -60,18 +65,18 @@ Overwrite it with the brief you just approved? [Y/N]"
 - **[Y]** Overwrite — proceed to §3.
 - **[N]** Cancel — emit a single-line stderr log `brief-skill: overwrite-cancelled at {path}` and HALT with exit code 5 (do not chain to step 6; the run produced no new artifact).
 
-**Headless (`{headless_mode}` is true):**
+**GATE [default: HALT unless `force` was supplied]**: headless (`{headless_mode}` is true), unless the ratify check printed `same`:
 
 If the file exists:
 
 - If `force` was supplied as a headless argument: log `"headless: force-overwriting existing brief at {path}"` and proceed to §3.
-- Otherwise: emit the error envelope per §4b with `halt_reason: "overwrite-cancelled"`, then HALT with exit code 5.
+- Otherwise: emit the halt envelope first, `uv run {emitBriefEnvelopeHelper} emit --target stderr` with `halt_reason: "overwrite-cancelled"` (SKILL.md Halt Contract), then HALT with exit code 5.
 
 If the file does not exist, proceed normally.
 
 ### 3. Write the Brief
 
-Assemble the brief context as a **flat** JSON object — every approved value is a top-level key, scope is split across four `scope_*` keys instead of nested, and every optional field is passed as `null` when not set rather than conditionally omitted. This eliminates the "decide what to omit" cognitive load that previously made this the most expensive HALT-typo site in the workflow:
+**Derive run** (any run but a ratify run): assemble the brief context as a **flat** JSON object: every approved value is a top-level key, scope is split across the `scope_*` keys instead of nested, and every optional field is passed as `null` when not set rather than conditionally omitted:
 
 ```json
 {
@@ -90,28 +95,41 @@ Assemble the brief context as a **flat** JSON object — every approved value is
   "scope_exclude":    ["{approved exclude patterns}"],
   "scope_notes":      "{approved scope notes or empty string}",
   "scope_rationale":  null | {"recommended":"...","chosen":"...","accepted_recommendation":true|false,"heuristic":"...","reason":"...","recorded":"YYYY-MM-DD"},
-  "scope_tier_a_include": null | ["{tier-A authoring-surface patterns — from step 03 §3c capture, or hydrated on a ratify run}"],
-  "scope_amendments":     null | [{"path":"...","action":"...","reason":"...","date":"YYYY-MM-DD","workflow":"..."}],
+  "scope_tier_a_include": null | ["{tier-A authoring-surface patterns, from step 3 §3c}"],
+  "scope_registry_path":  null | "{a component library's registry file; this key and the next two from step 3's component-library flow or its headless default}",
+  "scope_ui_variants":    null | [{"name": "...", "package": "..."}],
+  "scope_demo_patterns":  null | ["{demo globs}"],
   "doc_urls":         null | [{"url": "...", "label": "...", "source": "{optional: language-registry|readme-detection|homepage|pages-api|docs-folder}"}],
   "scripts_intent":   null | "{detect|none|free-text}",
   "assets_intent":    null | "{detect|none|free-text}",
   "source_authority": null | "{official|community|internal}",
-  "target_ref":       null | "{explicit git ref — ratify only}",
-  "source_ref":       null | "{resolved git ref — ratify only}"
+  "target_ref":       null | "{the explicit git ref of step 1's /tree/<ref>/ URL}"
 }
 ```
 
-**Ratify mode (`ratify_mode: true`):** this path never ran step 2, so the version was not re-derived — it was hydrated from the upstream brief at step 1 §3.1a (interactive) or the §8 GATE `from_brief` route (headless). Add a `version_resolved` key set to that hydrated `version`; the writer's precedence checks `version_resolved` first, so this pins the output to the brief's authored version. **Without it**, `target_version` and `detected_version` are both null on a ratify run and the writer falls through to the `1.0.0` default, silently discarding the upstream version. Keep `target_version` set to the brief's `target_version` (null if it had none) so the writer's `target_version == version` invariant still holds. Likewise carry `target_ref`/`source_ref` and `scope_tier_a_include`/`scope_amendments` from the hydrated brief (all null on a derive run) so the writer round-trips the monorepo git ref, the stratified tier-A surface, and the amendment audit log instead of dropping them.
-
-Pipe it into the writer script with the `--from-flat` flag:
+Stage it in the run folder, then run the writer on the file with the `--from-flat` flag:
 
 ```bash
-echo '<context-json>' | uv run {writeSkillBriefHelper} write --target {resolved-target-path} --from-flat
+cat > "{run_dir}/brief-context.json" <<'SKF_JSON'
+<the brief context above, as one JSON object>
+SKF_JSON
+uv run {writeSkillBriefHelper} write --target {resolved-target-path} --from-flat < "{run_dir}/brief-context.json"
 ```
 
 The script translates flat → nested internally, drops the null optional fields, and runs the same schema validation and atomic write as before — pass every key always, the writer decides what reaches the YAML.
 
-The script:
+**Ratify run (`ratify_mode: true`):** write from the brief step 1 ratified, `{ratify_source_path}`, so nothing it holds is retyped. The writer keeps every field of that brief that it renders and the patch below does not name, such as its version, which step 2 never re-derives on a ratify run (an [R] pass analyzes the brief's ref but keeps the hydrated version), its git refs and its `scope.amendments` log. The patch holds the fields step 4 or a step 3 `[R]` pass can change: write each `<field>` as its current value in JSON, `null` when it is unset, which removes the key (an `[R]` pass that moved `scope.type` off `component-library` unsets the three component-library fields). Add any other field the user changed at step 4 under its brief key; a changed `version` sets `target_version` too when the brief holds one, because the writer keeps the two equal:
+
+```bash
+cat > "{run_dir}/ratify-patch.json" <<'SKF_JSON'
+{"name": <name>, "description": <description>, "language": <language>,
+ "scope": {"type": <scope.type>, "include": <scope.include>, "exclude": <scope.exclude>, "notes": <scope.notes>, "rationale": <scope.rationale>, "tier_a_include": <scope.tier_a_include>, "registry_path": <scope.registry_path>, "ui_variants": <scope.ui_variants>, "demo_patterns": <scope.demo_patterns>},
+ "scripts_intent": <scripts_intent>, "assets_intent": <assets_intent>, "doc_urls": <doc_urls>}
+SKF_JSON
+uv run {writeSkillBriefHelper} write --target {resolved-target-path} --base-brief "{ratify_source_path}" --patch-file "{run_dir}/ratify-patch.json"
+```
+
+Either way, the script:
 - Validates the context against `src/shared/scripts/schemas/skill-brief.v1.json`
 - Applies the version-precedence rule from `{versionResolutionFile}`
 - Enforces the `target_version == version` invariant (refuses to write a brief that violates it)
@@ -122,55 +140,41 @@ The script:
 **On script failure (non-zero exit):**
 - Exit 1 (validation/invariant): The error JSON on stderr names the offending field. This indicates a context-assembly bug, not a user error — surface the message to the user, log it, then HALT.
   - Interactive: **HALT** — display the error JSON's `message` field.
-  - Headless: emit the error envelope per §4b with `halt_reason: "input-invalid"`, then `exit 2`.
-- Exit 2 (I/O failure): The atomic write failed (target unwritable, disk full, etc.).
+  - Headless: emit the halt envelope first, `uv run {emitBriefEnvelopeHelper} emit --target stderr` with `halt_reason: "input-invalid"` (SKILL.md Halt Contract), then HALT (exit code 2).
+- Exit 2 (I/O failure): The atomic write failed (target unwritable, disk full, etc.). On a ratify run it can also mean the brief at `{ratify_source_path}` could not be read: show the error JSON's `message` field.
   - Interactive: **HALT** — "**Error:** Failed to write skill-brief.yaml. Check that the directory is writable and try again."
-  - Headless: emit the error envelope per §4b with `halt_reason: "write-failed"`, then `exit 4`.
-
-**On success:** capture `brief_path` and `version` from the response envelope — both are needed for §4b and §6.
+  - Headless: emit the halt envelope first, `uv run {emitBriefEnvelopeHelper} emit --target stderr` with `halt_reason: "write-failed"` (SKILL.md Halt Contract), then HALT (exit code 4).
 
-**Draft cleanup.** After a successful write, remove `{forge_data_folder}/{skill-name}/.brief-draft.json` if it exists (`rm -f` — silent on absent). The draft was a step 1 §7 checkpoint covering the in-flight workflow window; once the brief is written it is no longer meaningful. In headless mode this rm is a no-op (drafts are only written interactively).
+**On success:** capture `brief_path` and `version` from the response envelope (§4b, §6 and §6b need them), and add each entry of its `warnings[]` to `workflow_warnings[]`.
 
-### 4b. Headless Result Envelope (Canonical)
+**Draft cleanup.** After a successful write, remove `{forge_data_folder}/{skill-name}/.brief-draft.json` if it exists (`rm -f`, silent on absent). The draft was the checkpoint step 1 §8 and step 3 §5c wrote for the in-flight workflow window; once the brief is written it is no longer meaningful. In headless mode this rm is a no-op (drafts are only written interactively).
 
-**Resolve `{emitBriefEnvelopeHelper}`** from `{emitBriefEnvelopeProbeOrder}`; first existing path wins. HALT if no candidate exists.
+### 3b. QMD Collection Registration (Deep Tier Only)
 
-This section is the canonical envelope-emission reference for the workflow. Every headless emission — the success terminal here and every HARD HALT in step 1/02/05 — uses this contract. Remote sites point here instead of restating it.
+**IF forge tier is Deep AND QMD tool is available:** resolve `{forgeTierRwHelper}` from `{forgeTierRwProbeOrder}` (first existing path wins), then load `{qmdRegistrationFile}` and follow the procedure there to index the brief into a QMD collection and update the forge-tier registry. If neither path exists, do not HALT: the brief is already written, and a QMD problem never fails the run. Index the brief all the same, skip the procedure's registry update, and add `QMD registry not updated: skf-forge-tier-rw.py not found` to `workflow_warnings[]`. A warning the procedure logs goes on `workflow_warnings[]` too, which is why this runs before §4b builds the envelope.
 
-**Success (this call site only — emitted from §3 directly):**
+**IF forge tier is NOT Deep OR QMD is not available:** skip this section silently: do not load `{qmdRegistrationFile}`. No messaging.
 
-```bash
-echo '{"status":"success","brief_path":"<from §3 response>","skill_name":"<name>","version":"<from §3 response>","language":"<language>","scope_type":"<scope.type>","halt_reason":null}' | \
-  uv run {emitBriefEnvelopeHelper} emit
-```
+### 4b. Result Envelope (Headless)
 
-**Error (used by every HARD HALT site):**
+When `{headless_mode}` is true, build the run's `SKF_BRIEF_RESULT_JSON` line now, after the write (§3) and the QMD registration (§3b), so `workflow_warnings[]` holds every warning the run raised. `{emitBriefEnvelopeHelper}` was resolved at SKILL.md On Activation step 4, and `references/invocation-contract.md` defines each field. Bind `{result_envelope_line}` to the line it prints, and do not display it here: the shared health check displays it verbatim as the run's last line, the final message a `claude -p` caller reads:
 
 ```bash
-echo '{"status":"error","skill_name":"<name>","halt_reason":"<reason>"}' | \
-  uv run {emitBriefEnvelopeHelper} emit --target stderr
+uv run {emitBriefEnvelopeHelper} emit <<'SKF_BRIEF_RESULT'
+{"status":"success","brief_path":"<brief_path from §3>","skill_name":"<name>","version":"<version from §3>","language":"<language>","scope_type":"<scope.type>","halt_reason":null,"mode":null,"warnings":[<workflow_warnings[] as JSON strings>]}
+SKF_BRIEF_RESULT
 ```
 
-When the HALT fires before `skill_name` has been resolved (step 1 §1 pre-flight write probe, step 1 §8 input-missing on a malformed args bundle), pass the partially-gathered value or the literal `"unknown"` — the script accepts any non-empty string at this position.
+The helper derives `exit_code`, checks the line against the envelope schema and prints it on stdout. If `{emitBriefEnvelopeHelper}` has no path, or the helper exits non-zero or prints no line, leave `{result_envelope_line}` empty and display its error: the brief is already written, so the run goes on.
 
-The script derives `exit_code` deterministically from `halt_reason` (null→0, input-missing/input-invalid→2, forge-tier-missing/target-inaccessible/gh-auth-failed→3, write-failed→4, overwrite-cancelled→5, user-cancelled→6 [interactive-only — headless never raises this]), validates against `src/shared/scripts/schemas/skf-brief-result-envelope.v1.json`, and prints the prefixed `SKF_BRIEF_RESULT_JSON: {…}` line.
+A HALT in this step, or in steps 1 and 2, does not use this section: it emits the error envelope through the SKILL.md Halt Contract, which also gives the `unknown` placeholder for a halt before the skill name is resolved.
 
-The script enforces the success/error halt_reason invariant (success requires null halt_reason; error requires non-null). The `user-cancelled` halt_reason is accepted for completeness (interactive `[X]` Cancel sites in step 1/03/04) but never appears on the headless code path.
-
-Invocation sites (each pointed at this block, not duplicated): step 1 §1 (write-failed pre-resolution; forge-tier-missing), step 1 §8 (input-missing/input-invalid GATE), step 2 §1 (target-inaccessible/gh-auth-failed), step 5 §2b (overwrite-cancelled), step 5 §3 (input-invalid/write-failed from script). The step 1 §1 forge-tier-missing and step 2 §1 target-inaccessible/gh-auth-failed sites emit through this block too, so every headless HALT class surfaces a `SKF_BRIEF_RESULT_JSON` envelope — there are no envelope-silent failure classes.
-
-When `{headless_mode}` is false, skip this section silently — no envelope is emitted.
-
-### 5. QMD Collection Registration (Deep Tier Only)
-
-**Resolve `{forgeTierRwHelper}`** from `{forgeTierRwProbeOrder}`; first existing path wins. HALT if no candidate exists.
-
-**IF forge tier is Deep AND QMD tool is available:** load `{qmdRegistrationFile}` and follow the procedure there to index the brief into a QMD collection and update the forge-tier registry.
-
-**IF forge tier is NOT Deep OR QMD is not available:** skip this section silently — do not load `{qmdRegistrationFile}`. No messaging.
+When `{headless_mode}` is false, skip this section silently: no envelope is emitted.
 
 ### 6. Display Success Summary
 
+When `{headless_mode}` is true, skip this section: the envelope §4b bound is the run's result.
+
 "**Skill brief written successfully.**
 
 ---
@@ -199,7 +203,7 @@ After compilation, you can:
 
 ### 6b. On-Complete Hook (pipeline integration)
 
-If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it now — after the brief has been written (§3) and the result contract finalized (§4b) — as:
+If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it now, after the brief has been written (§3) and, in a headless run, the result envelope built and bound to `{result_envelope_line}` (§4b):
 
 ```bash
 {onCompleteCommand} --result-path={brief_path}
@@ -207,12 +211,17 @@ If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 fr
 
 where `{brief_path}` is the absolute path captured from the §3 response envelope (the freshly written `skill-brief.yaml`, the stable artifact a downstream consumer chains from).
 
-- On success: log to `workflow_warnings[]` as informational only if the hook emitted stderr (`on_complete hook stderr: …`); otherwise no entry.
-- On non-zero exit / process error: log to `workflow_warnings[]` (`on_complete hook failed (exit {code}): {stderr_snippet}`).
-- **Never fail the workflow on hook errors** — the hook is for pipeline integration (chaining into create-skill, Slack, dashboards, CI), not for gating brief production.
+- **Never fail the workflow on hook errors:** the hook is for pipeline integration (chaining into create-skill, Slack, dashboards, CI), not for gating brief production. On a non-zero exit or a process error, display one line, `on_complete hook failed (exit {code}): {first line of its stderr}`, and continue. A headless run bound its envelope at §4b, so the envelope does not carry this line.
+- On success, add nothing: the hook's own output is its report.
 
-When `{onCompleteCommand}` is empty (bundled default), skip this section entirely — no hook is invoked.
+When `{onCompleteCommand}` is empty (bundled default), skip this section entirely: no hook is invoked. An `[auto]` run runs only §3b of this file: step-auto-validate.md §3 runs the same hook right after its envelope.
 
 ### 7. Chain to Health Check
 
-Once the brief file has been written and the success summary displayed, load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.
+Once the brief file has been written (and, outside headless mode, the success summary displayed), remove the run folder step 1 §1 created, with what the run staged in it (the guard keeps the command to that folder):
+
+```bash
+case "{run_dir}" in "{project-root}/_bmad-output/.skf-run/skf-brief-skill-"*) rm -rf "{run_dir}" ;; esac
+```
+
+Then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step: do not stop here even though the summary reads as final.

package/src/skf-campaign/SKILL.md

@@ -7,7 +7,7 @@ description: Campaign orchestration — multi-library skill production with depe
 
 ## Overview
 
-Orchestrates the production of 15+ skills across multiple sessions by driving them through the full SKF pipeline (brief, generate, compile, test, export) in dependency order. Campaign sits atop the pipeline ladder: it sequences the workflows that produce skills rather than producing artifacts itself. File-based state (`_campaign-state.yaml`) survives context death, enabling resume from any point.
+Orchestrates the production of 15+ skills across multiple sessions by driving them through the full SKF pipeline (brief, generate, compile, test, export) in dependency order. File-based state (`_campaign-state.yaml`) survives context death, enabling resume from any point.
 
 ## Conventions
 
@@ -16,41 +16,40 @@ Orchestrates the production of 15+ skills across multiple sessions by driving th
 - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
 - `{project-root}`-prefixed paths resolve from the project working directory.
 - `{skill-name}` resolves to the skill directory's basename.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root; e.g. `shared/health-check.md` and the envelope schemas under `shared/scripts/schemas/`.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one.
 
 ## Role
 
-You are a campaign orchestrator operating in Ferris's Management mode. You sequence workflows, track per-skill state, enforce quality gates, and ensure every skill reaches its target tier — while the individual pipeline workflows handle the actual artifact production.
+You are a campaign orchestrator operating in Ferris's Management mode. You sequence workflows, track per-skill state, enforce quality gates, and ensure every skill reaches its target tier, while the individual pipeline workflows handle the actual artifact production.
 
 ## On Activation
 
 Run these steps once, in order, before dispatching to Mode Routing.
 
-1. **Load config.** Read `{project-root}/_bmad/skf/config.yaml` and `{sidecar_path}/preferences.yaml` in one batched message (independent files). From config resolve `project_name`, `user_name`, `communication_language`, `document_output_language`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`. From preferences resolve `headless_mode` (default false). If the config file is missing, fall back to `forge_data_folder = forge-data`.
+1. **Load config.** Read `{project-root}/_bmad/skf/config.yaml` and `{sidecar_path}/preferences.yaml` in one batched message (independent files). From config resolve `project_name`, `user_name`, `communication_language`, `document_output_language`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`. If the config file is missing, fall back to `forge_data_folder = forge-data`.
 
-2. **Resolve `{headless_mode}`** — true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `preferences.yaml`. Default: false.
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
 
 3. **Resolve workflow customization.** Run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   The script merges three layers (scalars override, arrays append):
+   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).
 
-   - `{skill-root}/customize.toml` — bundled defaults
-   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
-   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
-
-   If it fails or is missing, fall back to `{skill-root}/customize.toml` directly. Resolve each scalar now (so step files never repeat the conditional) and stash as workflow-context variables:
+   Resolve each scalar now (so step files never repeat the conditional) and stash as workflow-context variables:
 
    - `{campaignWorkspacePath}` ← `workflow.campaign_workspace_path` if non-empty, else `{forge_data_folder}/_campaign`
-   - `{qualityGateHard}` / `{qualityGateSoftTarget}` / `{qualityGateSoftFallback}` ← the `quality_gate_*` scalars (defaults `zero-critical-high` / `90` / `80`)
+   - `{qualityGateHard}` / `{qualityGateSoftTarget}` / `{qualityGateSoftFallback}` ← the `quality_gate_*` scalars (defaults `zero-critical-high` / `90` / `80`): the base gate, which step-01 §2 and `scripts/campaign-quality-gate.py` adjust with the brief and the directive
    - `{reportTemplatePath}` ← `workflow.report_template_path` if non-empty, else `templates/campaign-report-template.md`
    - `{kickoffTemplatePath}` ← `workflow.kickoff_template_path` if non-empty, else `templates/kickoff-template.md`
    - `{briefTemplatePath}` ← `workflow.brief_template_path` if non-empty, else `templates/campaign-brief-template.yaml`
    - `{onComplete}` ← `workflow.on_complete` (empty = no-op)
+   - `{emitEnvelopeHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py`, else `{project-root}/src/shared/scripts/skf-emit-result-envelope.py` (the first that exists)
 
-   Load `workflow.persistent_facts` (literal sentences and `file:` references, globs expanded) and keep them in mind for the whole campaign — they are injected into every per-skill kickoff. Run any `activation_steps_prepend` before step 1 and any `activation_steps_append` after this step.
+   Load `workflow.persistent_facts` (literal sentences and `file:` references, globs expanded: the bundled default loads every `project-context.md` under `{project-root}`; an entry prefixed `!` drops each earlier entry it names and loads nothing itself, so an override's `"!file:{project-root}/**/project-context.md"` turns that default off) and keep them in mind for the whole campaign: they are injected into every per-skill kickoff, whose loader drops a `!` entry the same way. Run any `activation_steps_prepend` now, right after the resolve: the config and preferences of steps 1 and 2 are already loaded, so a prepend step can read them but cannot run before them. `activation_steps_append` runs at step 5, once the CLI overrides are parsed.
 
 4. **Parse CLI overrides** into the workflow context:
 
@@ -61,36 +60,34 @@ Run these steps once, in order, before dispatching to Mode Routing.
    | `--manifest <file>` | Seed step-01 targets from a plain-text `name,repo_url,tier,pin` manifest. Implies `--headless`. |
    | `--from <skill>` | Resume override — see Mode Routing. |
 
-   If `--brief` or `--manifest` is set, force `{headless_mode} = true` (log "headless: coerced by --brief/--manifest" if it was false).
-
-   **`--manifest` format:** one `name,repo_url,tier,pin` target per line (empty `pin` = latest); a trailing `;dep1,dep2` segment sets `depends_on`; blank and `#` lines are skipped. A malformed line HALTs step-01 with the offending line numbers — never a partial target set.
+   If `--brief` or `--manifest` is set, force `{headless_mode} = true` (log "headless: coerced by --brief/--manifest" if it was false). This is deliberate: a seeded run is an unattended run (CI), so it takes the default at every gate. To review the plan and the export, give the same file at the Setup question instead, which stays interactive. step-01 §1 documents the manifest format and validates every target.
 
-5. **Dispatch** per Mode Routing below.
+5. Run any `activation_steps_append`, then **dispatch** per Mode Routing below.
 
 ## Workflow Rules
 
 These rules apply to every step in this workflow:
 
-- State-first — write state to disk before chaining to the next step or workflow
-- Read-backup-modify-write for all state mutations (State Contract in `references/campaign-contracts.md`)
-- Validate `_campaign-state.yaml` on every load by running `uv run scripts/campaign-validate-state.py --state-file {stateFile}` and HALT (exit code 3, `invalid-state`) on non-zero — never hand-validate the schema
-- Zero memory dependency — campaign state is 100% recoverable from disk; never rely on conversation context for progress tracking
-- Treat a missing or unparseable `SKF_*_RESULT_JSON` envelope from any sub-skill as a sub-skill failure; never write partial state from an unparsed envelope
-- Append a one-line entry to the campaign decision log (`{campaignWorkspacePath}/_campaign-decision-log.md`, append-only) at every operator or auto-decision (skip/force, overwrite, export cancel/proceed, `.bak` recovery, user-cancel) so rationale survives compaction and resume
-- **Universal cancel affordance** — at any interactive gate between Setup and the Export gate, `cancel`/`exit`/`:q` triggers a HARD HALT with **exit code 12 (`user-cancelled`)**: log it and leave state intact and resumable. Exception: the Export gate's own `[C]ancel` stays exit code 11 (`export-cancelled`) — never also emit 12 there, so an automator's exit-code branch stays deterministic. These keywords count only as a response *to a prompt*; a skill or campaign named `cancel`/`exit` supplied as data is never treated as a cancel.
+- State-first: write state to disk before chaining to the next step or workflow
+- Every state write goes through `scripts/campaign-state.py` (State Contract in `references/campaign-contracts.md`); never edit the state or its `.bak` by hand
+- Validate `_campaign-state.yaml` on every load by running `uv run scripts/campaign-validate-state.py --state-file {stateFile}` and HALT (exit code 3, `invalid-state`) on non-zero; never hand-validate the schema
+- Zero memory dependency: campaign state is 100% recoverable from disk; never rely on conversation context for progress tracking
+- A sub-skill's result is what the step that runs it reads (an `SKF_*_RESULT_JSON` envelope or a verdict): a missing, unparseable or error result is a sub-skill failure, and never write partial state from an unparsed envelope
+- Log every operator decision, headless default and event (skip/force, overwrite, export cancel/proceed, `.bak` recovery, user-cancel, a failed skill) as one typed entry in the append-only `{campaignWorkspacePath}/_campaign-decision-log.md` through `campaign-state.py log` (`references/campaign-contracts.md`), so rationale survives compaction and resume
+- **Universal cancel affordance:** at any interactive gate between Setup and the Export gate, `cancel`/`exit`/`:q` triggers a HARD HALT with **exit code 12 (`user-cancelled`)**: log it and leave state intact and resumable. Exception: the Export gate's own `[C]ancel` stays exit code 11 (`export-cancelled`); never also emit 12 there, so an automator's exit-code branch stays deterministic.
 - Always communicate in `{communication_language}`
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
-- If `{headless_mode}` is true, emit a single-line JSON progress event to **stderr** at each step's entry, exit, and HARD HALT so schedulers stream live progress — event format in `references/campaign-contracts.md` (Headless Progress Events)
+- If `{headless_mode}` is true, emit a single-line JSON progress event to **stderr** at each step's entry, exit, and HARD HALT, and at every HARD HALT the error envelope (`references/campaign-contracts.md`: Headless Progress Events, Result Contract on HARD HALT)
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
 | 0 | Setup | references/step-01-setup.md | Yes |
-| 1 | Strategy | references/step-02-strategy.md | Yes |
+| 1 | Strategy | references/step-02-strategy.md | No (plan confirmation; headless takes [P]) |
 | 2 | Pin Validation | references/step-03-pins.md | Yes |
 | 3 | Provenance | references/step-04-provenance.md | Yes |
-| 4 | Skill Loop | references/step-05-skill-loop.md | Yes |
+| 4 | Skill Loop | references/step-05-skill-loop.md | Conditional (a blocked dependency) |
 | 5 | Tier B Batch | references/step-06-batch.md | Yes |
 | 6 | Capstone | references/step-07-capstone.md | Yes |
 | 7 | Verification | references/step-08-verify.md | Yes |
@@ -98,24 +95,24 @@ These rules apply to every step in this workflow:
 | 9 | Export | references/step-10-export.md | No (write-gate HALT) |
 | 10 | Maintenance | references/step-11-maintenance.md | Yes |
 
-**Stage numbering:** step files are 1-indexed (`step-01` … `step-11`); `campaign.current_stage` in state is 0-indexed, so step-`NN` runs stage `NN − 1` (step-01 = stage 0, step-11 = stage 10). `references/step-resume.md` §3–§4 own how a resolved stage maps back to its step file on resume (including the `current_stage + 1` advance when no skill is active).
+**Stage numbering:** `campaign.current_stage` is 0-indexed, so step-`NN` runs stage `NN - 1`; `campaign-state.py resume` maps a resumed campaign to its step file.
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
 | **Inputs** | `campaign` to start a new campaign; `campaign resume [--from=<skill>]` to resume from last active or specified skill; `campaign status` for a read-only progress summary |
-| **Outputs** | `_campaign-state.yaml` (state), `campaign-brief.yaml` (machine-generated brief), `campaign-report.md` (post-campaign summary), `_campaign-decision-log.md` (append-only rationale), `SKF_CAMPAIGN_RESULT_JSON` (headless envelope) — all under `{campaignWorkspacePath}` |
+| **Outputs** | `_campaign-state.yaml` (state), `campaign-brief.yaml` (machine-generated brief), `campaign-report.md` (post-campaign summary), `_campaign-decision-log.md` (append-only rationale), all under `{campaignWorkspacePath}`; `SKF_CAMPAIGN_RESULT_JSON` (headless envelope) |
 
 ## Contracts
 
-Exit codes, the HARD-HALT error envelope, the read-backup-modify-write **State Contract**, the headless success envelope, and per-step progress events live in `references/campaign-contracts.md` — consult it when you HALT, mutate state, or emit headless output.
+Exit codes, the HARD-HALT error envelope, the **State Contract** (`scripts/campaign-state.py`), the decision log and per-step progress events live in `references/campaign-contracts.md`: consult it when you HALT, write state, or log. The envelope's one definition is `shared/scripts/schemas/skf-campaign-result-envelope.v1.json`; step-11 emits its success line.
 
 ## Mode Routing
 
 On invocation:
 
-1. **`campaign resume [--from=<skill>]`** — load `references/step-resume.md` (validates state, recovers from backup, chains to the right stage). `--from=<skill>` overrides the resume point to the named skill.
-2. **`campaign`** (new, no existing state) — run from stage 0 (Setup).
-3. **`campaign`** (state exists) — detect existing `{campaignWorkspacePath}/_campaign-state.yaml` and prompt **resume** (via `references/step-resume.md`) or **overwrite**. On overwrite, first archive the existing `_campaign-state.yaml` and `campaign-brief.yaml` to `{campaignWorkspacePath}/archive/{name}-{timestamp}/` and log it before chaining to step-01. In headless mode, default to **resume** (never silently clobber); archive-and-overwrite only when `--brief`/`--manifest` explicitly seeds a new campaign.
-4. **`campaign status`** (read-only) — load `{campaignWorkspacePath}/_campaign-state.yaml`, validate it via `campaign-validate-state.py`, then run `uv run scripts/campaign-status.py --state-file {campaignWorkspacePath}/_campaign-state.yaml` and display its summary (campaign name, current stage, completed-vs-total, per-status counts) followed by the last ~15 lines of `{campaignWorkspacePath}/_campaign-decision-log.md` for the recent decision trail, then stop. No backup, no mutation, no chaining. Exit 0 (or 9 if the state is unrecoverable).
+1. **`campaign resume [--from=<skill>]`**: load `references/step-resume.md` (validates state, recovers from backup, chains to the stage `campaign-state.py resume` computes). `--from=<skill>` overrides the resume point to the named skill.
+2. **`campaign`** (new, no existing state) to run from stage 0 (Setup).
+3. **`campaign`** (state exists): when `{campaignWorkspacePath}/_campaign-state.yaml` or its `.bak` exists, prompt **resume** (via `references/step-resume.md`) or **overwrite**. On overwrite, first run `uv run scripts/campaign-state.py archive --state-file {campaignWorkspacePath}/_campaign-state.yaml --brief-file {campaignWorkspacePath}/campaign-brief.yaml`, which moves the state, its `.bak` and the brief into a new folder under `{campaignWorkspacePath}/archive/`, and log the `archive_dir` it returns (type `decision`) before chaining to step-01 (its `init` refuses to overwrite a state or backup). A `--brief` that named the workspace's `campaign-brief.yaml` is then read from `archive_dir`. **GATE [default: resume]**: in headless mode, default to **resume** (never silently clobber); archive-and-overwrite only when `--brief`/`--manifest` explicitly seeds a new campaign.
+4. **`campaign status`** (read-only): load `{campaignWorkspacePath}/_campaign-state.yaml`, validate it via `campaign-validate-state.py`, then run `uv run scripts/campaign-status.py --state-file {campaignWorkspacePath}/_campaign-state.yaml` and display its summary (campaign name, current stage, completed-vs-total, per-status counts) followed by the last ~15 lines of `{campaignWorkspacePath}/_campaign-decision-log.md` for the recent decision trail, then stop. No backup, no mutation, no chaining. Exit 0 (or 9 if the state is unrecoverable).

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

@@ -8,7 +8,7 @@
   "properties": {
     "campaign": {
       "type": "object",
-      "required": ["name", "started_at", "last_updated", "current_stage", "quality_gate", "health_findings_queue"],
+      "required": ["name", "started_at", "last_updated", "current_stage", "quality_gate"],
       "additionalProperties": false,
       "properties": {
         "name": {
@@ -48,7 +48,8 @@
         },
         "health_findings_queue": {
           "type": "string",
-          "enum": ["local", "improvement"]
+          "enum": ["local", "improvement"],
+          "description": "Ignored. Setup asked for it before v3.0.0; the end-of-run health check now decides where findings go. Kept optional so state files that hold it still validate."
         },
         "architecture_doc_path": {
           "type": ["string", "null"],
@@ -80,11 +81,13 @@
           "description": "Stage 7 verify-stack summary. Detailed findings live in the external report at report_path.",
           "properties": {
             "report_path": {
-              "type": ["string", "null"]
+              "type": ["string", "null"],
+              "description": "report_path of the skf-verify-stack result envelope: the timestamped report, which no later run rewrites (not the -latest copy)."
             },
             "overall_verdict": {
               "type": ["string", "null"],
-              "enum": ["Verified", "Plausible", "Risky", "Blocked", null]
+              "enum": ["FEASIBLE", "CONDITIONALLY_FEASIBLE", "NOT_FEASIBLE", null],
+              "description": "overall_verdict of the skf-verify-stack result envelope."
             },
             "coverage_percentage": {
               "type": ["number", "null"]
@@ -167,6 +170,24 @@
           },
           "commit_sha": {
             "type": ["string", "null"]
+          },
+          "export": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "required": ["status"],
+            "description": "The Export stage's outcome for this skill, recorded by campaign-state.py set-skill --export after its skf-export-skill call: exported, or failed with that call's halt_reason and exit code (null when it gave none). Absent until Export runs the skill; a reset to pending removes it.",
+            "properties": {
+              "status": {
+                "type": "string",
+                "enum": ["exported", "failed"]
+              },
+              "halt_reason": {
+                "type": ["string", "null"]
+              },
+              "exit_code": {
+                "type": ["integer", "null"]
+              }
+            }
           }
         }
       }

package/src/skf-campaign/customize.toml

@@ -1,8 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-campaign.
-# Team overrides:     _bmad/custom/skf-campaign.toml (under {project-root})
-# Personal overrides: _bmad/custom/skf-campaign.user.toml (under {project-root})
+# Team overrides:     {project-root}/_bmad/custom/skf-campaign.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-campaign.user.toml
 
 [workflow]
 
@@ -10,15 +10,18 @@
 #   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
 #   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
 
-# Steps to run before the standard activation (config load, customization
-# resolve). Overrides append. Use for org-wide pre-flight checks (auth,
-# network, compliance) that must precede any orchestration work.
+# Steps to run right after the customization resolve (On Activation step 3).
+# Config and preferences are already loaded by then, so a step here can read
+# them but cannot run before them. Overrides append. Use for org-wide
+# pre-flight checks (auth, network, compliance) that must precede any
+# orchestration work.
 
 activation_steps_prepend = []
 
-# Steps to run after activation but before the first stage executes.
-# Overrides append. Use for context loads or banner customization that
-# should run once activation completes successfully.
+# Steps to run once activation is complete, the CLI overrides included (so
+# headless mode already reflects --brief and --manifest), just before the
+# first stage executes. Overrides append. Use for context loads or banner
+# customization.
 
 activation_steps_append = []
 
@@ -27,11 +30,21 @@ activation_steps_append = []
 # into every per-skill kickoff, so project-scoped house facts propagate to
 # the whole campaign. Overrides append.
 #
-# Each entry is either:
+# Each entry is one of:
 #   - a literal sentence, e.g. "All skills must cite their upstream source."
 #   - a file reference prefixed with `file:`, e.g.
 #     "file:{project-root}/docs/skill-style.md" (globs supported; file
 #     contents are loaded and treated as facts).
+#   - an entry prefixed with `!`, which loads nothing and drops each earlier
+#     entry it names.
+#
+# The kickoff script expands each `file:` entry when it renders a Tier A
+# kickoff (a `**` glob recursively, so the default below takes every
+# project-context.md under {project-root}) and inlines each matching file in
+# full into every kickoff. Overrides append, and the script drops a `!`
+# entry and each earlier entry it names, so to keep those files out of every
+# Tier A kickoff, set in {project-root}/_bmad/custom/skf-campaign.toml:
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
@@ -49,10 +62,25 @@ campaign_workspace_path = ""
 
 # --- Quality gate ---
 #
-# Campaign-wide quality bar applied to every skill. Scalars override the
-# bundled defaults; the per-campaign brief and any directive `## Quality
-# Overrides` still take precedence at runtime. Override here to change the
-# org-wide default without forking the skill.
+# Campaign-wide quality bar, enforced on every skill. Precedence, highest
+# first: the directive's `## Quality Overrides` (while the campaign runs),
+# then the `quality_gate` of the campaign-brief.yaml Setup reads (from
+# --brief or its opening question, field by field), then these values.
+# Override here to change the org-wide default without forking the skill.
+#
+# quality_gate_hard: `zero-critical-high` is the only accepted value (Setup
+# halts on any other). It passes a skill only when its test-skill run finds
+# no Critical or High gap. A missing export is a Medium gap: it lowers the
+# coverage score and no longer counts against this gate.
+#
+# quality_gate_soft_target: every Tier A test run gets it as `--threshold`,
+# and a completed skill scoring at or above it exports as `pass`.
+# quality_gate_soft_fallback: a completed skill scoring below the target but
+# at or above this exports as `fallback`; one below it, or with no score, is
+# listed at Export and not exported. test-skill fails a Tier A skill below
+# its threshold unless it scores at least 80 (its threshold fallback), so a
+# soft_fallback below 80 only matters for Tier B skills, checked by their
+# quick-skill (skill-check) score, or for a soft_target below 80.
 
 quality_gate_hard = "zero-critical-high"
 quality_gate_soft_target = 90
@@ -68,8 +96,11 @@ report_template_path = ""
 kickoff_template_path = ""
 brief_template_path = ""
 
-# Optional post-completion hook. When non-empty, the workflow invokes:
+# Optional post-completion hook. When non-empty, step-11 invokes it once
+# the campaign is finished: after the report and the final state write
+# (current_stage 10), before the headless result envelope:
 #   <on_complete> --report-path=<path-to-campaign-report.md>
-# after the campaign report is finalized (step-11). Failures are logged to
-# the decision log but never fail the campaign. Empty = no-op.
+# --report-path is passed only when the report was written; a report that
+# could not be generated leaves the hook called without it. Failures are
+# logged to the decision log but never fail the campaign. Empty = no-op.
 on_complete = ""