bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/skf-campaign/references/step-04-provenance.md

@@ -2,9 +2,11 @@
 nextStepFile: 'step-05-skill-loop.md'
 stateSchemaFile: 'assets/campaign-state-schema.json'
 stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
-backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
 briefFile: '{campaignWorkspacePath}/campaign-brief.yaml'
+provenanceResultsFile: '{campaignWorkspacePath}/_provenance-results.json'
+decisionLogFile: '{campaignWorkspacePath}/_campaign-decision-log.md'
 provenanceScript: 'scripts/campaign-provenance.py'
+stateScript: 'scripts/campaign-state.py'
 validateScript: 'scripts/campaign-validate-state.py'
 ---
 
@@ -18,46 +20,45 @@ Verify that all target repositories are accessible and record the exact commit S
 
 ## RULES
 
-- This step uses the **read-backup-modify-write** pattern.
-- Reads the brief for `repo_url` (not in state — `repo_url` is NOT part of the state schema).
-- Any inaccessible repo halts the campaign — all targets must be reachable before skill processing begins.
-- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
-- Update `campaign.current_stage` to `3`.
-- Update `campaign.last_updated` to current ISO-8601 with timezone on every write.
-- If `{headless_mode}` is true, auto-proceed through confirmation gates with the default action and log each auto-decision.
+- Write `campaign.current_stage` = 3 only in this stage's final state write, after every gate: step-resume resumes at `current_stage + 1`, so an early write skips unfinished work.
+- Write state and decision-log entries only through `{stateScript}`, and on a non-zero exit HALT with the same code (State Contract in `references/campaign-contracts.md`). A log entry is `uv run {stateScript} log --log-file {decisionLogFile} --type <decision|auto|event> --text '<entry>'`.
+- Any inaccessible repo halts the campaign: all targets must be reachable before skill processing begins. The brief holds each `repo_url` (the state schema has no place for it).
+- If `{headless_mode}` is true, emit this stage's progress events, and at any HARD HALT the error envelope, per `references/campaign-contracts.md`.
 
 ## TASKS
 
-### §1 — Read + Validate State
+### §1: Read + Validate State
 
 Load `{stateFile}`. Run `uv run {validateScript} --state-file {stateFile}`; on non-zero, HALT (exit 3) with the script's `errors[]`.
 
-### §2 — Read Brief
+### §2: Read Brief
 
 Load `{briefFile}` only to confirm it parses (the provenance script reads it directly). HALT (exit code 8, `missing-brief`) if the brief is missing or unreadable.
 
-### §3 — Backup State
+### §3: Verify Repo Access + Record Commit SHAs
 
-Copy `{stateFile}` to `{backupFile}` before any modification.
-
-### §4 — Verify Repo Access + Record Commit SHAs
-
-Run the deterministic provenance check — do not parse repo URLs or shell out to `gh` by hand:
+Run the deterministic provenance check, keeping its JSON output in `{provenanceResultsFile}` for §5; do not parse repo URLs or call `gh` by hand:
 
 ```
-uv run {provenanceScript} --state-file {stateFile} --brief-file {briefFile}
+uv run {provenanceScript} --state-file {stateFile} --brief-file {briefFile} > {provenanceResultsFile}
 ```
 
-The script resolves `{owner}/{repo}` from each `repo_url` (tolerating `.git`/trailing slashes/SSH form), picks the ref (the skill's `pin`, else the repo default branch), runs `gh repo view` + `gh api commits`, and emits `results[]` with `commit_sha` and `status` per skill, plus `all_accessible`, `inaccessible_count`, and `systemic_hint`. Exit 0 = all accessible, 1 = one or more inaccessible, 2 = error (missing files, bad YAML, `gh` not installed). On script exit 2, HALT (exit code 2, `invalid-input`) surfacing the error — repo access cannot be verified without `gh`.
+It writes `results[]`, one per skill with its `commit_sha` (of the skill's `pin`, else the default branch), `status`, `error` and `error_class` (`unauthenticated`, `not-found`, `rate-limited`, `forbidden`, `network`, or `other` for a target it could not look up), plus `all_accessible`, `inaccessible_count` and `systemic_hint`. Exit 0 = all accessible, 1 = one or more inaccessible, 2 = error (missing files, bad YAML, `gh` not installed, or `INVALID_BRIEF`: a brief that is no mapping or holds a target with no `name` or no `repo_url`). On script exit 2, HALT (exit code 2, `invalid-input`) surfacing the error; only when `gh` is what is missing, add that repo access cannot be verified without it.
+
+### §4: Handle Inaccessible Repos
 
-### §5 — Handle Inaccessible Repos
+If `all_accessible` is `false` (script exit 1), HALT (exit code 6, `inaccessible-repo`) and list each inaccessible repo with its URL, its `error_class` and its `error`. When the script returns a non-null `systemic_hint` (every target failed the same way: unauthenticated `gh`, no network, a rate limit, an organization's SSO policy), show that root-cause line first, above the per-repo errors, never in their place. Do NOT partially proceed: all repos must be verified before writing state.
 
-If `all_accessible` is `false` (script exit 1), HALT (exit code 6, `inaccessible-repo`). When the script returns a non-null `systemic_hint` (every target failed the same way — e.g. unauthenticated `gh`, no network, rate limit), present that single root-cause line instead of a wall of near-identical per-repo errors. Otherwise list each inaccessible repo, its URL, and its error. Do NOT partially proceed — all repos must be verified before writing state.
+### §5: Write State
 
-### §6 — Write State
+Write every commit SHA and the stage in one write:
+
+```
+uv run {stateScript} apply-provenance --state-file {stateFile} --results-file {provenanceResultsFile} --stage 3
+```
 
-Set each skill's `commit_sha` from the script's `results[]`. Set `campaign.current_stage` to `3`. Set `campaign.last_updated` to current ISO-8601 with timezone. Write to `{stateFile}`.
+It sets each skill's `commit_sha` from `results[]` and refuses results that hold an inaccessible repo (exit 6, nothing written: HALT as in §4); on exit 3, HALT (exit code 3, `invalid-state`).
 
 ## OUTPUT
 
-Display provenance summary — for each target, show name, repo URL, and recorded commit SHA. Chain to `{nextStepFile}`.
+Display provenance summary: for each target, show name, repo URL, and recorded commit SHA. Chain to `{nextStepFile}`.

package/src/skf-campaign/references/step-05-skill-loop.md

@@ -2,11 +2,15 @@
 nextStepFile: 'step-06-batch.md'
 stateSchemaFile: 'assets/campaign-state-schema.json'
 stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
-backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
 briefFile: '{campaignWorkspacePath}/campaign-brief.yaml'
+decisionLogFile: '{campaignWorkspacePath}/_campaign-decision-log.md'
+preapplyLogFile: '{campaignWorkspacePath}/preapply-log.json'
+factsFile: '{campaignWorkspacePath}/_facts.json'
 depsScript: 'scripts/campaign-deps.py'
 kickoffTemplate: '{kickoffTemplatePath}'
 kickoffScript: 'scripts/campaign-render-kickoff.py'
+gateScript: 'scripts/campaign-quality-gate.py'
+stateScript: 'scripts/campaign-state.py'
 validateScript: 'scripts/campaign-validate-state.py'
 ---
 
@@ -20,85 +24,100 @@ Iterate skills in `dependency_graph.execution_order`, processing each Tier A ski
 
 ## RULES
 
-- This step uses the **read-backup-modify-write** pattern.
-- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
-- Update `campaign.current_stage` to `4`.
-- Update `campaign.last_updated` to current ISO-8601 with timezone on every write.
-- Write state after EACH skill completes (not just at end) — context death between skills must be survivable.
-- The per-skill pipeline body (§5.2) runs inline, not in a delegated subagent: AN→BS→CS→TS are nested skill activations, and a subagent cannot spawn further subagents — running inline keeps the full pipeline reachable and writes each skill's state before the next begins.
-- If `{headless_mode}` is true, auto-proceed through confirmation gates. Dependency gate blocks default to HALT (safest — never silently skip dependencies).
+- Write `campaign.current_stage` = 4 only in this stage's final state write (§6), after every skill: step-resume resumes at `current_stage + 1`, so an early write skips unfinished work. An interrupted skill needs no stage write: it stays `active`, and resume sends an active Tier A skill back to this stage.
+- Write state and decision-log entries only through `{stateScript}`, and on a non-zero exit HALT with the same code (State Contract in `references/campaign-contracts.md`). A log entry is `uv run {stateScript} log --log-file {decisionLogFile} --type <decision|auto|event> --text '<entry>'`.
+- Write state after EACH skill completes (not just at end): context death between skills must be survivable.
+- The per-skill pipeline body (§5.2) runs inline, not in a delegated subagent: BS→CS→TS are nested skill activations, and a subagent cannot spawn further subagents, so running inline keeps the full pipeline reachable and writes each skill's state before the next begins.
+- If `{headless_mode}` is true, auto-proceed through confirmation gates; at a blocked skill, headless takes §4.6's `default_action` and never forces a dependency. Emit this stage's progress events, and at any HARD HALT the error envelope, per `references/campaign-contracts.md`.
 
 ## TASKS
 
-### §1 — Read + Validate State
+### §1: Read + Validate State
 
 Load `{stateFile}`. Run `uv run {validateScript} --state-file {stateFile}`; on non-zero, HALT (exit 3) with the script's `errors[]`.
 
-### §2 — Read Brief
+### §2: Read Brief
 
-Load `{briefFile}`. Build a lookup map from `targets[].name` to `targets[].repo_url`. HALT (exit code 8, `missing-brief`) if the brief is missing or unreadable.
+Load `{briefFile}` only to confirm it parses (the kickoff script reads it directly). HALT (exit code 8, `missing-brief`) if the brief is missing or unreadable.
 
-### §3 — Read Directive
+### §3: Read Directive
 
-If `campaign.directive_path` is set in state, load the file at that path and apply its contents as campaign-wide context for all skill processing, per the directive contract in `references/campaign-directive-spec.md`. If the file is not found, continue without error (directive is optional).
+If `campaign.directive_path` is set in state, the directive steers this stage through two scripts, so apply none of it by hand: the gate script's resolve calls read its `## Skip List` and `## Quality Overrides` for each skill (§4 and §5, re-reading the file, so an edit between skills takes effect), and the kickoff script inlines the whole file into each kickoff (§5), where its other sections are the campaign-wide context the directive contract in `references/campaign-directive-spec.md` describes. If the file is not found, continue without error (directive is optional).
 
-### §4 — Dependency Gate Check
+### §4: Dependency Gate Check
 
 For each skill in `dependency_graph.execution_order`, before processing:
 
-1. Skip Tier B skills — they are processed in step-06 via batch mode.
+1. Skip Tier B skills: they are processed in step-06 via batch mode.
 2. Skip skills whose status is already `"completed"`, `"failed"`, or `"skipped"` (resume support).
-3. Run `uv run {depsScript} --check --state-file {stateFile} --skill {skill_name}`.
-4. If `ready: true` — proceed to §5 for this skill.
-5. If `ready: false` — present the blocked skill and its unmet dependencies:
-   - `[S]kip` — mark skill as `"skipped"`, backup and write state, continue to next skill.
-   - `[F]orce` — re-run with `--force`, proceed to §5 despite unmet deps.
-   - `[H]alt` — stop the campaign loop. (Default in headless mode.)
-6. **Deadlock detection:** after iterating through all remaining skills and finding none ready, present the same recovery menu as §4.5, scoped to the mutually-blocked set (this is the strictly harder situation, so it must not get worse UX than a single blocked skill):
+3. Resolve the skill's run, passing `--directive-file` when state sets `campaign.directive_path`:
+
+   ```
+   uv run {gateScript} resolve --state-file {stateFile} --skill {skill_name} --brief-file {briefFile} [--directive-file <campaign.directive_path>]
+   ```
+
+   When `skip` is true, the directive's Skip List names the skill: mark it skipped (`uv run {stateScript} set-skill --state-file {stateFile} --skill {skill_name} --status skipped`), log "directive Skip List: {skill_name} ({skip_reason})" (type `event`), and continue to the next skill. Otherwise keep its `brief_skill`, the brief-skill inputs §5.2 copies. Its `unparsed` entries and `warnings` lines describe the directive, not the skill: log them to the decision log once per stage, from the first resolve call, and again only when a later call reports different ones. On exit 2, HALT with its `error`: exit code 8 (`missing-brief`) when its `code` is `BRIEF_NOT_FOUND`, `BRIEF_UNREADABLE` or `TARGET_NOT_FOUND` (the brief has no target for the skill), else exit code 2 (`invalid-input`): an override that breaks the gate, or a directive that cannot be read.
+4. Run `uv run {depsScript} --check --state-file {stateFile} --skill {skill_name}`.
+5. If `ready: true`, proceed to §5 for this skill.
+6. If `ready: false`, present the blocked skill and each unmet dependency with its status (`unmet_status`):
+   - `[S]kip`: mark the skill skipped with the `set-skill --status skipped` call above, log it, continue to the next skill.
+   - `[F]orce`: re-run with `--force`, proceed to §5 despite unmet deps.
+   - `[H]alt`: stop the campaign with exit code 13 (`dependency-blocked`); state is intact and resumable.
+
+   **GATE [default: `default_action`]**: headless, take `default_action`. `skip` (every unmet dependency failed or was skipped, so none can complete in this run) runs `[S]kip` and logs "headless: skipped {skill_name}: {dependency} is {status}" for each unmet dependency, so the independent skills after it still run. `halt` (a dependency is still pending or active, an order the loop cannot follow) runs `[H]alt`. In execution order every dependency comes first, so `halt` is defensive: only a `--from` resume or a hand-edited state leaves a dependency pending.
+7. **Deadlock detection** (defensive: Strategy rejects every order the loop cannot follow and §4.6 settles each blocked skill as the loop reaches it, so only a hand-edited state gets here): after iterating through all remaining skills and finding none ready, present the same recovery menu as §4.6, scoped to the mutually-blocked set (this is the strictly harder situation, so it must not get worse UX than a single blocked skill):
    - List the blocked skills and their unmet dependencies.
-   - `[F]orce one` — choose a skill to re-run with `--force` and resume the loop from it.
-   - `[S]kip one` — choose a skill to mark `"skipped"`, backup and write state, then re-evaluate readiness.
-   - `[H]alt` — stop the campaign loop with exit code 7 (`dependency-deadlock`). **Default in headless mode** (never silently force or skip a dependency). Log the chosen action to the decision log.
+   - `[F]orce one`: choose a skill to re-run with `--force` and resume the loop from it.
+   - `[S]kip one`: choose a skill to mark skipped (`set-skill --status skipped`), then re-evaluate readiness.
+   - `[H]alt`: stop the campaign loop with exit code 7 (`dependency-deadlock`).
 
-### §5 — Per-Skill Processing
+   **GATE [default: HALT]**: headless takes `[H]alt` (exit code 7, `dependency-deadlock`) and never forces a dependency. Log the chosen action to the decision log.
+
+### §5: Per-Skill Processing
 
 For each ready Tier A skill:
 
-1. **Activate** — set `status` to `"active"`, set `started_at` to current ISO-8601 with timezone. Backup and write state.
+1. **Activate:** `uv run {stateScript} set-skill --state-file {stateFile} --skill {skill_name} --status active`. It stamps `started_at` from the clock, or keeps the start of a run an interruption left `active`.
 2. **Execute pipeline:**
-   - **Pre-apply** — apply known workarounds before generation by running the shared pre-apply helper against the skill's working directory:
+   - **Pre-apply:** apply known workarounds before generation by running the shared pre-apply helper against the skill's working directory:
      ```
      uv run {project-root}/_bmad/skf/shared/scripts/skf-preapply.py --target-dir <skill-working-dir> --log-dir {campaignWorkspacePath}
      ```
-     (During development the helper lives at `src/shared/scripts/skf-preapply.py`.) Parse `applied[]` from the JSON output and capture the list of applied workarounds. Pre-apply is best-effort: if the helper is missing or exits non-zero, log a warning and proceed — it is not a gate.
-   - **Kickoff emit** — render the mechanical placeholders deterministically, then fill the three judgment slots. Run:
+     (During development, with no `{project-root}/_bmad/skf/shared/scripts/skf-preapply.py` installed, the helper lives at `{project-root}/src/shared/scripts/skf-preapply.py`.) It writes its `applied[]` workarounds to `{preapplyLogFile}`, which the kickoff script reads. Pre-apply is best-effort: if the helper is missing or exits non-zero, log a warning and proceed (it is not a gate), and leave `--workarounds-file` out of the kickoff call below, so an earlier skill's log is never listed for this one.
+   - **Kickoff emit:** render the whole kickoff message with the kickoff script, which fills every placeholder of the template. The customization resolver pipes the persistent facts into it:
      ```
-     uv run {kickoffScript} --state-file {stateFile} --brief-file {briefFile} --skill {skill_name} --template {kickoffTemplate} --workarounds '<JSON list of applied workarounds from pre-apply>'
+     uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow.persistent_facts | uv run {kickoffScript} --state-file {stateFile} --brief-file {briefFile} --skill {skill_name} --template {kickoffTemplate} [--workarounds-file {preapplyLogFile}] --facts-json - --project-root {project-root} [--directive-file <campaign.directive_path>]
      ```
-     The script fills `{{campaign_name}}`, `{{current_stage}}`, `{{quality_gate_summary}}`, `{{skill_name}}`, `{{skill_tier}}`, `{{pin}}`, `{{commit_sha}}`, `{{repo_url}}`, `{{workarounds_list}}`, and `{{dependency_status_table}}` from state + brief. Then fill the three judgment slots that remain in the rendered output:
-     - `{{brief_summary}}` — a concise summary of this target's brief entry (name, repo_url, tier, pin, depends_on). The per-skill brief does NOT exist yet at kickoff — BS produces it during this pipeline run (see below), so do not read `brief_path`; summarize the campaign brief's target entry instead.
-     - `{{persistent_facts}}` — the campaign-wide persistent facts resolved in On Activation (literal sentences and loaded `file:` contents), as a bullet list, or "None" if empty. This is how house style/guardrails reach every skill's pipeline.
-     - `{{directive_content}}` — raw content of the file at `campaign.directive_path`, or "No directive configured" if unset/missing.
-     Present the completed kickoff message as the context for the skill's pipeline run.
-   - **AN → BS → CS → TS** — standard forge pipeline for this skill. When BS (Brief Synthesis) produces the skill's brief, set `skills[current].brief_path` to the brief path from the BS result envelope so the field the schema declares is populated and available for resume and reporting.
-   - **Doc-rot check** — **record** what CS step 5c already produced; do not re-derive it. Because the pipeline body runs inline (see the §5 note above), that step's context is directly readable here: `corrections_added`, `correction_matches` (the enriched match records — `source`, `pattern`, `category`, `context_line`, `affected`), `corrections_deduped` and `corrections_capped`. Append one `[doc-rot]`-prefixed entry per `correction_matches` record to the skill's `workarounds_applied` array so they survive state write and are available for §6 propagation. When step 5c took its skip branch (`doc_rot_triggered: false`, `corrections_added: 0`), there is nothing to record — append nothing and move on.
+     - `--facts-json -` takes `workflow.persistent_facts` from the resolver unchanged. When the resolver is missing or fails, write the `persistent_facts` list of `{skill-root}/customize.toml`, as written, to `{factsFile}` as a JSON list with your file-writing tool, and replace the pipe with `< {factsFile}`: no fact or workaround ever passes through shell quoting.
+     - `--workarounds-file` is passed when pre-apply exited 0 for this skill; the script lists each workaround it applied (the file, the fingerprint and its fix, the severity).
+     - `--directive-file` is passed when state sets `campaign.directive_path`.
+
+     Present the script's output unchanged as the context for the skill's pipeline run, and fill nothing in by hand. An exit 2 with no JSON on stderr is a usage error from a mangled call, not invalid input: fix the call and run it again. An exit 2 with JSON names its `code`: on `BAD_WORKAROUNDS` or `BAD_FACTS` this call's input is wrong, so correct it and run the call again; on `BRIEF_NOT_FOUND` or `BRIEF_UNREADABLE`, HALT (exit code 8, `missing-brief`); on any other code, HALT (exit code 2, `invalid-input`) with its `error`. Correct a call once only: when the corrected call fails too, HALT (exit code 2, `invalid-input`).
+   - **BS → CS → TS**: the forge pipeline for a named skill, the chain the forger's `forge` alias runs. Run each sub-skill with `--headless`, so no nested gate waits and each prints its result envelope. A sub-skill that fails ends the pipeline, and the skill fails (§5.3) with its `halt_reason`. Campaign runs no analyze-source pass: brief-skill scopes the named skill itself, while analyze-source names its briefs from the repository, so brief-skill would overwrite or never read them.
+     - **BS** (`skf-brief-skill`): `--headless --force` with each non-null field of §4's `brief_skill` as the input of that name (`target_repo`, `skill_name`, `target_version`, `language_hint`, `scope_hint`); copy them, never read them out of the kickoff. `target_version` is the skill's pin: Setup accepts only an X.Y.Z version as a Tier A pin, and brief-skill refuses any other shape with `input-invalid`, so a pin never silently drops out of the build. `--force` replaces a brief an earlier attempt wrote under this name. Record the `brief_path` of its SKF_BRIEF_RESULT_JSON at once, so resume and the report have it: `uv run {stateScript} set-skill --state-file {stateFile} --skill {skill_name} --brief-path <brief_path>`. An envelope with `status` `error`, or none, fails the skill.
+     - **CS** (`skf-create-skill`): `--headless` with that `brief_path`. CS prints an SKF_CREATE_SKILL_RESULT_JSON line (on stderr) only when it halts; that line fails the skill with its `summary.halt_reason`. On success, keep the `{skill_package}` its report names (the compiled skill's folder): §5.3 records it.
+     - **TS** (`skf-test-skill`): first resolve the gate again, right before the test, so a directive edit made during this skill counts and the threshold never has to survive the nested runs in conversation context: `uv run {gateScript} resolve --state-file {stateFile} --skill {skill_name} [--directive-file <campaign.directive_path>]` (exit 2 HALTs as at §4). Then run `{skill_name} --headless --threshold={threshold}` with that call's `threshold`, and `pipeline_alias` set to `campaign` in its data context (the explicit threshold wins over test-skill's per-pipeline default). TS settles its verdict, caps and 80% floor fallback itself; §5.3 reads the result.
+   - **Doc-rot check:** **record** what CS step 5c already produced; do not re-derive it. Because the pipeline body runs inline (see the RULES note on inline execution), that step's context is directly readable here. Its `correction_matches` holds only the corrections step 5c's judgment pass kept and wrote as `## CORRECTION` blocks, each with `source`, `pattern`, `candidate_category`, `context_line` and `affected`; the candidates the pass rejected are not corrections, so they are never recorded. Append one entry per `correction_matches` record to the skill's `workarounds_applied` array, written as `[doc-rot] {affected}: {candidate_category}`, so they survive in state: `uv run {stateScript} append-workarounds --state-file {stateFile} --skill {skill_name} --entry '<entry>'`, one single-quoted `--entry` per record (an entry the skill already holds is not added twice, so a resumed skill records each correction once). When step 5c took its skip branch (`doc_rot_triggered: false`, `corrections_added: 0`), there is nothing to record: append nothing and move on.
 
      **Do not hand-grep the feeder artifacts here, and do not re-run the scan.** `skf-create-skill/references/step-doc-rot.md` §2 requires the scan to run in its helper precisely so identical feeders yield identical matches; a second pass in this loop is free to disagree with the corrections CS actually wrote. It would also be self-contaminating: step 5c has already written `## CORRECTION` blocks into the compiled SKILL.md, and the helper's exclusion windows cover only that file's frontmatter and its Migration & Deprecation Warnings section — so re-scanning it would re-match the blocks 5c itself authored and record them as fresh findings.
-3. **Record results:**
-   - On success: set `status` to `"completed"`, set `completed_at` to current ISO-8601 with timezone, record `quality_score`. Backup and write state.
-   - On failure: set `status` to `"failed"`. Log the failure reason (the sub-skill's `halt_reason`/exit code, or "unparseable result envelope") to the decision log so `campaign status` and the report surface *why* a skill failed without the operator opening sub-skill logs. Backup and write state. Downstream skills whose `depends_on` does NOT include the failed skill continue processing normally; those that DO depend on it are blocked at §4's dependency gate.
+3. **Record results:** settle the skill from its test verdict, never from an envelope's `status` (TS reports `success` for a scored FAIL too). Pipe the SKF_TEST_RESULT_JSON line TS printed (on stdout for a scored run, on stderr when it halted) to the gate script, and nothing when it printed none:
 
-### §6 — Propagate Findings
+   ```
+   uv run {gateScript} record --skill {skill_name} <<'SKF_RESULT'
+   <the SKF_TEST_RESULT_JSON line TS printed>
+   SKF_RESULT
+   ```
 
-After each completed skill, propagate quality findings and doc-rot corrections to campaign-level tracking (`workarounds_applied`, `quality_score`).
+   - `status` `completed` (verdict PASS, a threshold-fallback PASS included): `uv run {stateScript} set-skill --state-file {stateFile} --skill {skill_name} --status completed --quality-score <quality_score> --skill-path <skill_package>`, with its `quality_score` and the `{skill_package}` CS named; the helper stamps `completed_at`. Whether the skill exports is decided at Export (step-10), against its gate.
+   - `status` `failed` (FAIL, INCONCLUSIVE, pass-with-drift, an error envelope or no readable result), or an earlier sub-skill failed: `uv run {stateScript} set-skill --state-file {stateFile} --skill {skill_name} --status failed [--quality-score <quality_score>]`, with `--quality-score` when it has one. Log the failure reason as an `event` (the record's `reason`, the failing sub-skill's `halt_reason`/exit code, or "unparseable result envelope") to the decision log so `campaign status` and the report surface *why* a skill failed without the operator opening sub-skill logs. Downstream skills whose `depends_on` does NOT include the failed skill continue processing normally; those that DO depend on it are blocked at §4's dependency gate, where headless skips them.
 
-### §7 — Loop Completion
+### §6: Loop Completion
 
-When all Tier A skills in `execution_order` are processed (completed, failed, or skipped):
+When all Tier A skills in `execution_order` are processed (completed, failed, or skipped), write the stage:
 
-1. Set `campaign.current_stage` to `4`.
-2. Set `campaign.last_updated` to current ISO-8601 with timezone.
-3. Backup and write state.
+```
+uv run {stateScript} set-stage --state-file {stateFile} --stage 4
+```
 
 ## OUTPUT
 

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

@@ -2,10 +2,13 @@
 nextStepFile: 'step-07-capstone.md'
 stateSchemaFile: 'assets/campaign-state-schema.json'
 stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
-backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
 briefFile: '{campaignWorkspacePath}/campaign-brief.yaml'
 batchFile: '{campaignWorkspacePath}/_batch-input.txt'
+batchMapFile: '{campaignWorkspacePath}/_batch-map.json'
+batchResultsFile: '{campaignWorkspacePath}/_batch-results.json'
+decisionLogFile: '{campaignWorkspacePath}/_campaign-decision-log.md'
 batchScript: 'scripts/campaign-render-batch.py'
+stateScript: 'scripts/campaign-state.py'
 validateScript: 'scripts/campaign-validate-state.py'
 ---
 
@@ -19,43 +22,43 @@ Batch all Tier B skills through QS `--batch` mode, recording per-skill results i
 
 ## RULES
 
-- This step uses the **read-backup-modify-write** pattern.
-- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
-- Update `campaign.last_updated` to current ISO-8601 with timezone on every write.
-- Update `campaign.current_stage` to `5`.
-- If `{headless_mode}` is true, auto-proceed through confirmation gates. QS `--batch` implies headless.
+- Write `campaign.current_stage` = 5 only in this stage's final state write, after every result is recorded: step-resume resumes at `current_stage + 1`, so an early write skips unfinished work. An interrupted batch needs no stage write: its skills stay `active`, and resume sends an active Tier B skill back to this stage.
+- Write state and decision-log entries only through `{stateScript}`, and on a non-zero exit HALT with the same code (State Contract in `references/campaign-contracts.md`). A log entry is `uv run {stateScript} log --log-file {decisionLogFile} --type <decision|auto|event> --text '<entry>'`.
+- If `{headless_mode}` is true, emit this stage's progress events, and at any HARD HALT the error envelope, per `references/campaign-contracts.md`. QS `--batch` implies headless.
 
 ## TASKS
 
-### §1 — Read + Validate State
+### §1: Read + Validate State
 
 Load `{stateFile}`. Run `uv run {validateScript} --state-file {stateFile}`; on non-zero, HALT (exit 3) with the script's `errors[]`.
 
-### §2 — Read Directive
+### §2: Read Directive
 
-If `campaign.directive_path` is set in state, load the file at that path and apply its contents as campaign-wide context for this stage's processing, per the directive contract in `references/campaign-directive-spec.md`. If the file is not found, continue without error (directive is optional).
+If `campaign.directive_path` is set in state, the batch script applies its `## Skip List` itself (§3), so do not filter skills by hand. Read any other section as campaign-wide context, per the directive contract in `references/campaign-directive-spec.md`. If the file is not found, continue without error (directive is optional).
 
-### §3 — Identify Tier B Skills
+### §3: Select Tier B Skills and Write the Batch File
 
-Filter `skills[]` for entries where `tier == "B"` and `status == "pending"`. Skip skills with status `"completed"`, `"failed"`, or `"skipped"` (resume support — a previous run may have partially completed the batch).
+The batch script selects the Tier B skills (pending ones, and active ones an interrupted batch left behind), leaves out the ones the directive's Skip List names, and writes the batch file and its line-to-skill map: select and format nothing by hand. Pass `--directive-file` when state sets `campaign.directive_path`:
 
-If no Tier B skills need processing, skip to §7 (Stage Completion) — the batch stage completes immediately when all Tier B skills are already handled.
+```
+uv run {batchScript} --state-file {stateFile} --brief-file {briefFile} -o {batchFile} --map {batchMapFile} [--directive-file <campaign.directive_path>]
+```
 
-### §4 — Generate Batch File
+Its JSON summary on stderr gives `count`, the skill of each line in order (`skills`), the skills the Skip List left out (`skipped_by_directive`, each with its `reason`) and the hints left off a line (`dropped_hints`: a language or scope hint quick-skill could not read as one word).
 
-Generate the QS `--batch` input file deterministically:
+HALT on non-zero exit: exit code 8 (`missing-brief`) when the brief is missing/unreadable **or** a selected Tier B skill has no matching brief target; exit code 2 (`invalid-input`) on a state file/parse error or a directive that cannot be read.
 
-```
-uv run {batchScript} --state-file {stateFile} --brief-file {briefFile} -o {batchFile}
-```
+Log each `skipped_by_directive` entry as "directive Skip List: {name} ({reason})" and each `dropped_hints` entry as "batch: {skill} built without its {hint} `{value}` (quick-skill reads a hint as one word)", both type `event`.
 
-The script filters `skills[]` for `tier == "B" && status == "pending"`, looks up each skill's `repo_url` from the brief's `targets[]` (repo URLs live in the brief, not the state schema), and writes one line per skill at `{batchFile}` in the exact single-target shape QS parses (see `src/skf-quick-skill/references/batch-mode.md`) — the line format is owned once by the script, not re-derived here. It emits a JSON summary (`written`, `count`, `skipped_non_tierB`, `skipped_non_pending`) on stderr.
+### §4: Execute QS Batch
 
-HALT on non-zero exit: exit code 8 (`missing-brief`) when the brief is missing/unreadable **or** a pending Tier B skill has no matching brief target; exit code 2 (`invalid-input`) on a state file/parse error.
+Record the batch's start from the map, so no skill is marked by hand:
 
-### §5 — Execute QS Batch
+```
+uv run {stateScript} apply-batch --state-file {stateFile} --map-file {batchMapFile} --start
+```
 
-Set each pending Tier B skill to `status: "active"` and `started_at` to current ISO-8601 with timezone. Backup `{stateFile}` to `{backupFile}`, then write the updated state.
+It marks each `skipped_by_directive` skill `skipped` and each batched skill `active`, stamping `started_at` from the clock unless an interrupted batch already set it. If the §3 `count` is 0, add `--stage 5` to this call and chain to `{nextStepFile}`: the batch stage completes at once when every Tier B skill is already handled.
 
 Invoke QS in `--batch` mode with the generated batch file:
 
@@ -63,25 +66,29 @@ Invoke QS in `--batch` mode with the generated batch file:
 skf-quick-skill --batch {batchFile}
 ```
 
-QS `--batch` implies `--headless`. Capture per-skill results from the QS batch output — each target reports success/failure, skill path, and quality score.
+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.
+
+### §5: Record Results
 
-### §6 — Record Results
+Join the batch summary to the skills by line number, never by matching QS output to skills by hand:
 
-For each Tier B skill in the batch:
+```
+uv run {batchScript} --record <summary_path> --map {batchMapFile} > {batchResultsFile}
+```
 
-1. If QS reports success:
-   - Set `status` to `"completed"`
-   - Set `completed_at` to current ISO-8601 with timezone
-   - Record `quality_score` from QS output
-   - Record `skill_path` from QS output
-2. If QS reports failure:
-   - Set `status` to `"failed"`
+When that call exits 0, record the results and the stage in one write:
 
-After all updates: backup `{stateFile}` to `{backupFile}`, then write the updated state.
+```
+uv run {stateScript} apply-batch --state-file {stateFile} --map-file {batchMapFile} --results-file {batchResultsFile} --stage 5
+```
 
-### §7 — Stage Completion
+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`.
 
-Set `campaign.current_stage` to `5`. Update `campaign.last_updated` to current ISO-8601 with timezone. Backup `{stateFile}` to `{backupFile}`, then write the updated state.
+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.
+
+```
+uv run {stateScript} apply-batch --state-file {stateFile} --map-file {batchMapFile} --no-results --stage 5
+```
 
 ## OUTPUT
 

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

@@ -2,7 +2,10 @@
 nextStepFile: 'step-08-verify.md'
 stateSchemaFile: 'assets/campaign-state-schema.json'
 stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
-backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+decisionLogFile: '{campaignWorkspacePath}/_campaign-decision-log.md'
+gateScript: 'scripts/campaign-quality-gate.py'
+manifestScript: 'scripts/campaign-parse-manifest.py'
+stateScript: 'scripts/campaign-state.py'
 validateScript: 'scripts/campaign-validate-state.py'
 ---
 
@@ -12,51 +15,63 @@ validateScript: 'scripts/campaign-validate-state.py'
 
 ## STEP GOAL:
 
-Compose a capstone stack skill from all completed individual skills using SS compose-mode. The capstone represents the final integrated view of all campaign skills — a single stack skill that documents how the constituent libraries connect.
+Compose a capstone stack skill from the completed individual skills that clear the quality gate, using SS compose-mode. The capstone represents the final integrated view of the campaign's exported skills: a single stack skill that documents how the constituent libraries connect.
 
 ## RULES
 
-- This step uses the **read-backup-modify-write** pattern.
-- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
-- Update `campaign.last_updated` to current ISO-8601 with timezone on every write.
-- Update `campaign.current_stage` to `6`.
-- If `{headless_mode}` is true, auto-proceed through confirmation gates. SS compose-mode supports headless.
+- Write `campaign.current_stage` = 6 only in this stage's final state write (§4), after the capstone is recorded: step-resume resumes at `current_stage + 1`, so an early write skips unfinished work.
+- Write state and decision-log entries only through `{stateScript}`, and on a non-zero exit HALT with the same code (State Contract in `references/campaign-contracts.md`). A log entry is `uv run {stateScript} log --log-file {decisionLogFile} --type <decision|auto|event> --text '<entry>'`.
+- If `{headless_mode}` is true, emit this stage's progress events, and at any HARD HALT the error envelope, per `references/campaign-contracts.md`. SS compose-mode runs headless.
 
 ## TASKS
 
-### §1 — Read + Validate State
+### §1: Read + Validate State
 
 Load `{stateFile}`. Run `uv run {validateScript} --state-file {stateFile}`; on non-zero, HALT (exit 3) with the script's `errors[]`.
 
-### §2 — Collect Completed Skills
+### §2: Collect Completed Skills
 
-Gather all skills from `skills[]` with `status == "completed"` — this includes both Tier A skills (processed in step-05) and Tier B skills (processed in step-06). Extract their `skill_path` values.
+Classify the completed skills (Tier A from step-05, Tier B from step-06) against the quality gate as Export will, passing `--directive-file` when state sets `campaign.directive_path`; never compare scores by hand:
 
-If no completed skills exist, do NOT HALT — a campaign where everything failed is exactly when the operator most needs the downstream diagnostic report. Set `campaign.capstone` to `null`, warn ("No completed skills — skipping capstone composition; verification and the campaign report will still run so failures are explained"), log the skip to the decision log, and skip directly to §5 (Stage Completion) so the chain continues to verify → … → the report. step-10 (export) and step-11 (report) already handle the zero-completed case.
+```
+uv run {gateScript} classify --state-file {stateFile} [--directive-file <campaign.directive_path>]
+```
 
-### §3 — Invoke SS Compose-Mode
+The capstone composes the skills in its `export[]` (the `pass` and `fallback` verdicts), so it never describes a skill the gate keeps from export: log each `excluded[]` skill as "capstone: {name} left out, below the quality gate ({reason})". Name each composed skill by the `export_name` of its row in `skills[]` (the skill folder its build wrote), as Export does. On exit 2 (an override that breaks the gate, or a directive that cannot be read), HALT (exit code 2, `invalid-input`) with its `error`.
 
-Invoke `skf-create-stack-skill` in compose-mode with:
+If `export[]` is empty (no completed skill, or none clears the gate), do NOT HALT: a campaign where everything failed is exactly when the operator most needs the downstream diagnostic report. Warn ("No skill clears the quality gate: skipping capstone composition; verification and the campaign report will still run so failures are explained"), log the skip (type `event`), and go to §4 with no capstone, so the chain continues to verify, refine, export and the report. step-10 (export) and step-11 (report) already handle the zero-completed case.
 
-- The collected `skill_path` values as input skills
-- `campaign.name` as the stack identifier
+### §3: Invoke SS Compose-Mode
 
-Capture the result: stack skill path and quality score from the SS result output (`SKF_STACK_RESULT_JSON`).
+Invoke `skf-create-stack-skill` with `--headless` and these inputs, so it asks nothing and prints its result envelope:
 
-### §4 — Record Capstone Results
+- `mode`: `compose`
+- `skills`: the §2 `export_name` values, comma-separated (compose mode takes them as its constituent skill folders)
+- `stack_name`: the `stack_name` that `uv run {manifestScript} --stack-name {stateFile}` prints, the campaign name as a skill name cut to leave room for the `-stack` SS appends; when it prints null, leave the input out and SS names the stack `{project_name}-stack`
+- `architecture_doc_path`: `campaign.architecture_doc_path`, only when state sets it
 
-Persist the capstone outcome to `campaign.capstone` in the state (campaign-level summary; the composed skill itself lives at `skill_path`):
+Keep the `SKF_STACK_RESULT_JSON` line it prints for §4, which records it. On `status` `error`, or no envelope, log its `halt_reason` (or "no result envelope", type `event`): verification and the campaign report still run.
 
-- `campaign.capstone.skill_path` — stack skill path (from SS result)
-- `campaign.capstone.quality_score` — quality score (from SS result)
-- `campaign.capstone.verified` — `null` for now; set by the verify stage (step-08) once the stack is checked
-- `campaign.capstone.completed_at` — current ISO-8601 with timezone
+### §4: Record the Capstone and Complete the Stage
 
-The capstone is a derived artifact — it is **not** tracked as a skill entry in the `skills[]` array. Its campaign-level summary lives in `campaign.capstone`; the constituent skill list and any verbose detail are reported in the step output and are available to downstream steps (verify, refine).
+Record the capstone outcome and the stage in one write, passing the §3 envelope line to the helper, which reads it (never copy its fields by hand):
 
-### §5 — Stage Completion
+```
+uv run {stateScript} set-campaign --state-file {stateFile} --capstone - --stage 6 <<'SKF_RESULT'
+<the SKF_STACK_RESULT_JSON line SS printed>
+SKF_RESULT
+```
 
-Set `campaign.current_stage` to `6`. Update `campaign.last_updated` to current ISO-8601 with timezone. Backup `{stateFile}` to `{backupFile}`, then write the updated state (including `campaign.capstone` from §4).
+From a `success` envelope it sets `campaign.capstone`, the campaign-level summary (the composed skill itself lives at `skill_path`):
+
+- `campaign.capstone.skill_path`: `skill_package` from the SS envelope
+- `campaign.capstone.quality_score`: `quality_score` from the SS envelope (the skill-check score SS records, null when skill-check did not run; it is not a test-skill score)
+- `campaign.capstone.verified`: `null` for now; set by the verify stage (step-08) once the stack is checked
+- `campaign.capstone.completed_at`: the time of the write, from the clock
+
+An `error` envelope sets `campaign.capstone` to `null` (the helper names it in `not_recorded`). When §2 found no skill to compose, or SS printed no envelope, record no capstone instead: `uv run {stateScript} set-campaign --state-file {stateFile} --no-capstone --stage 6`.
+
+The capstone is a derived artifact: it is **not** tracked as a skill entry in the `skills[]` array. The constituent skill list and any verbose detail are reported in the step output and are available to downstream steps (verify, refine).
 
 ## OUTPUT