bmad-module-skill-forge 2.2.0 → 3.0.0

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

@@ -2,7 +2,7 @@
 
 # Campaign Contracts
 
-The self-contained contracts consulted at a specific moment — when a step HALTs, mutates state, or emits the final headless envelope. Each stands alone so it survives context compaction.
+The self-contained contracts consulted at a specific moment: when a step HALTs, writes state or the decision log, or emits a headless progress event. Each stands alone so it survives context compaction.
 
 ## Exit Codes
 
@@ -10,51 +10,61 @@ Every HARD HALT exits with a stable, documented code so headless automators can
 
 | Code | Meaning              | Raised by                                                   |
 | ---- | -------------------- | ----------------------------------------------------------- |
-| 0    | success              | step-11 (terminal); step-resume §3–§4 (campaign already complete — nothing to resume) |
-| 2    | invalid-input        | step-01 §1 (no targets, or a malformed `--manifest` line); steps 02/03/04/06 §4 (a helper reports unreadable input or a required tool such as `gh` unavailable); step-resume §1/§3 (resume targets a missing campaign or unknown skill) |
-| 3    | invalid-state        | any step §1 (`campaign-validate-state.py` non-zero on load) |
-| 4    | circular-deps        | step-02 §5 (a dependency cycle, or a dangling `depends_on` reference — either way the graph cannot be ordered) |
-| 5    | invalid-pin          | step-03 §5                                                  |
-| 6    | inaccessible-repo    | step-04 §5                                                  |
-| 7    | dependency-deadlock  | step-05 §4 (no skill ready and no recovery chosen)          |
-| 8    | missing-brief        | step-03/04/05 §2 and step-06 §4 (brief missing/unreadable, or a Tier B target has no matching brief entry) |
+| 0    | success              | step-11 (terminal: the success line, which the health check displays last); step-resume §3 (campaign already complete: nothing to resume, and in headless mode the success line again). Never an error halt: no `emit-halt` |
+| 2    | invalid-input        | step-01 §1 (no targets, or a target the parse script rejects: a malformed manifest line or brief target, a `repo_url` that is no GitHub repository, a name that is no skill name, a Tier A pin that is no X.Y.Z version, a duplicate name) and §2 (a quality gate the gate script rejects, a brief it cannot read, or a state file or backup that already exists); steps 02/03/04 §3 and step-06 §3 (a helper reports unreadable input or a required tool such as `gh` unavailable); step-05 §4 and §5, step-07 §2 and step-10 §3 (a directive override that breaks the quality gate, or a directive the gate script cannot read); step-05 §5 (the kickoff script cannot read its template, state, directive or a facts file, or a `file:` fact path names no file); step-resume §1/§3 (resume targets a missing campaign or unknown skill) |
+| 3    | invalid-state        | any step §1 (`campaign-validate-state.py` non-zero on load), and any `campaign-state.py` write that exits 3 (the state, or the change, fails validation) |
+| 4    | circular-deps        | step-02 §4 (a dependency cycle, a dangling `depends_on` reference, or a Tier A skill that depends on a Tier B skill: either way the plan cannot be followed) and §7 (`apply-plan` refuses the plan) |
+| 5    | invalid-pin          | step-03 §4 and §5 (`apply-pins` refuses an invalid pin)      |
+| 6    | inaccessible-repo    | step-04 §4 and §5 (`apply-provenance` refuses an inaccessible repo) |
+| 7    | dependency-deadlock  | step-05 §4 (no skill ready and no recovery chosen; defensive, since Strategy rejects every order the loop cannot follow) |
+| 8    | missing-brief        | step-03/04/05 §2, step-05 §4 and §5, step-06 §3 (brief missing/unreadable, or a skill has no matching brief target), and step-resume §3 (Setup stopped before it wrote the brief) |
 | 9    | corrupt-state        | step-resume §1 (primary unrecoverable, `.bak` also invalid) |
 | 10   | report-failure       | step-11 §2 — **degraded only**: the report could not be generated; the campaign still completes and state stays intact (never a hard halt that discards a finished campaign) |
 | 11   | export-cancelled     | step-10 §4 (operator chose `[C]ancel` — graceful, resumable) |
 | 12   | user-cancelled       | any interactive gate (operator typed `cancel` / `exit` / `:q` at a prompt between Setup and the Export gate — graceful, resumable) |
+| 13   | dependency-blocked   | step-05 §4 (`[H]alt` at a skill whose dependency has not completed: the operator's choice, or the headless default while a dependency is still pending or active; graceful, resumable) |
 
 ## Result Contract on HARD HALT
 
-In addition to the success-variant envelope (see Campaign Headless Envelope below), every HARD HALT emits an **error variant** so automators don't silently break. Emit one line on **stderr**:
+`shared/scripts/schemas/skf-campaign-result-envelope.v1.json` (in the SKF module: `{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during development) is the one definition of the `SKF_CAMPAIGN_RESULT_JSON` envelope, and the shared emitter, `{emitEnvelopeHelper}`, is the only thing that prints it. That helper is `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py` when installed, `{project-root}/src/shared/scripts/skf-emit-result-envelope.py` during development. Exit code 0 is never an error halt: step-11 builds the success line, and step-resume prints it again for a campaign already complete. Every HARD HALT in headless mode emits the error variant, so automators don't silently break:
 
-```
-SKF_CAMPAIGN_RESULT_JSON: {"status":"error","exit_code":<N>,"phase":"<slug>","error":{"code":"<class>","message":"<short>"},"skills_completed":N,"skills_failed":N,"campaign_report_path":null,"decision_log":"<path-or-null>"}
+```bash
+uv run scripts/campaign-state.py halt-payload --state-file {campaignWorkspacePath}/_campaign-state.yaml --phase <step slug> --halt-reason <class> <<'SKF_CAMPAIGN_HALT' | uv run {emitEnvelopeHelper} emit-halt --workflow skf-campaign --target stderr
+<the halt message>
+SKF_CAMPAIGN_HALT
 ```
 
-`<class>` is the Exit Codes meaning (e.g. `circular-deps`, `inaccessible-repo`); `<slug>` is the step where the HALT occurred. One line, no pretty-print.
+`<class>` is the Exit Codes meaning (e.g. `circular-deps`, `inaccessible-repo`), from which the emitter derives `exit_code`; `<step slug>` is the kebab portion of the step file where the HALT occurred. `halt-payload` adds the `completed` and `failed` counts of the state (0 before Setup wrote it) and the decision log (null before the campaign workspace exists). The emitter prints one line on stderr, with `status` `error`, `exit_code`, `halt_reason`, `phase` and an `error` object holding `code` and `message`. If either command exits non-zero, display the halt message alone.
 
 ## State Contract
 
-All state mutations follow the read-backup-modify-write pattern:
-
-1. **Read** `_campaign-state.yaml`
-2. **Validate** via `uv run scripts/campaign-validate-state.py --state-file {stateFile}` (halt on invalid)
-3. **Backup** — copy current `_campaign-state.yaml` to `_campaign-state.yaml.bak`
-4. **Modify** in memory
-5. **Update** `campaign.last_updated` to current ISO-8601 timestamp
-6. **Write** modified state back to `_campaign-state.yaml`
+Every write to `_campaign-state.yaml` goes through `scripts/campaign-state.py`. Each write reads the state and validates it (an invalid state is never rotated into `.bak`, and nothing is written), applies the operation, stamps `campaign.last_updated` (and any `started_at` or `completed_at` the operation sets) from the clock in UTC, validates the result (a change that would make the state invalid is refused), copies the valid primary it read to `_campaign-state.yaml.bak`, and writes the new state to a temporary file renamed over the old one. A crash therefore leaves the old file or the new one, never half of one, and `.bak` always holds the last valid state. `--stage N` on a write also sets `campaign.current_stage`: each stage writes its number only in its final write, after every gate, because resume starts at `current_stage + 1`.
 
-The `.bak` file is one-deep (overwritten on every write). If the primary file is corrupted (crash during write), the `.bak` file contains the last valid state — step-resume §1 recovers from it automatically rather than dead-halting.
+| Operation | Step | What it writes |
+| --- | --- | --- |
+| `init` | step-01 | the state, from `campaign-parse-manifest.py`'s targets and the gate `campaign-quality-gate.py check` settles, then `campaign-brief.yaml` from the same targets (`--brief-out`); refuses a state or backup that exists |
+| `apply-plan` | step-02 | `dependency_graph` from `campaign-deps.py --compute` |
+| `apply-pins` | step-03 | each resolved pin, from `campaign-validate-pins.py`'s output |
+| `apply-provenance` | step-04 | each `commit_sha`, from `campaign-provenance.py`'s output |
+| `set-skill` | step-05, step-10, step-resume | a skill's `status`, `quality_score`, `skill_path`, `brief_path` or `export` outcome (`--export`); `active` stamps `started_at` once, `completed` stamps `completed_at`, `pending` clears both and the `export` outcome |
+| `append-workarounds` | step-05 | entries of a skill's `workarounds_applied`, each once |
+| `apply-batch` | step-06 | the Tier B batch from its line-to-skill map: `--start`, `--results-file` or `--no-results` |
+| `set-campaign` | steps 07 to 09 | `architecture_doc_path`, and the capstone, verification or refinement summary read from the sub-skill's envelope line (`capstone.verified` with the verification) |
+| `set-stage` | steps 05, 10, 11 | `current_stage` alone |
+| `recover` | step-resume | `.bak` over the primary, when `.bak` validates (exit 9 otherwise) |
+| `archive` | SKILL.md (overwrite) | nothing: it moves the state, its `.bak` and the brief into a new folder under `archive/` and returns it |
+| `resume` | step-resume | nothing: it returns the stage and step file to resume |
+| `halt-payload` | any HARD HALT | nothing: it prints the error envelope's payload (Result Contract above) |
 
-## Campaign Headless Envelope
+Its exit codes are the campaign's: 2 for invalid input (an unknown skill, an input file it cannot read, a script output that holds an error), 3 for an invalid state or change, 4 for a plan `apply-plan` refuses, 5 for a pin `apply-pins` refuses, 6 for a repository `apply-provenance` refuses, 9 for a `recover` with no valid backup. HALT with the same code.
 
-When `{headless_mode}` is true, the final step emits a single-line JSON envelope on stdout:
+## Decision Log
 
-```
-SKF_CAMPAIGN_RESULT_JSON: {"status":"success|error","skills_completed":0,"skills_failed":0,"quality_scores":{},"campaign_report_path":"","decision_log":"","duration":""}
-```
+`_campaign-decision-log.md` is append-only, one typed and timestamped line per entry, written with `uv run scripts/campaign-state.py log --log-file {campaignWorkspacePath}/_campaign-decision-log.md --type <decision|auto|event> --text '<entry>'` (single-quote the entry, so the shell expands no `$` or backtick in it, and write an apostrophe inside it as `'\''`). Its types:
 
-`status` is `"success"` when the campaign completes normally, `"error"` on any unrecoverable halt (with `exit_code` per the Exit Codes table — see Result Contract on HARD HALT above). `skills_completed` and `skills_failed` count per-skill outcomes. `quality_scores` maps skill names to their test-skill scores. `campaign_report_path` points to the generated `campaign-report.md`. `decision_log` points to `_campaign-decision-log.md`. `duration` is the wall-clock time of the campaign run. Populate the counts, `quality_scores`, and `duration` directly from the `campaign-report.py` result JSON (step-11 §2) — do not recompute them by hand.
+- `decision`: the operator's choice at a gate (skip or force, overwrite, export or cancel, re-run or next, a cancel)
+- `auto`: the default a headless run took at a gate
+- `event`: what happened without a choice: a failed skill and why, a skip the directive or a dependency forced, a recovery from the backup, a report or hook failure
 
 ## Headless Progress Events
 
@@ -64,4 +74,4 @@ When `{headless_mode}` is true, emit a single-line JSON progress event to **stde
 - exit (just before chaining): `{"stage":N,"name":"<slug>","status":"done"}`
 - on HARD HALT: `{"stage":N,"name":"<slug>","status":"halt","exit":<code>}` instead of `"done"`
 
-`N` is the 0-indexed stage number (0–10) and `<slug>` is the kebab portion of the step filename. For the non-numbered routing/terminal steps (`resume`, `health-check`) emit `"stage":null` with the slug. One line per event; do not pretty-print.
+`N` is the 0-indexed stage number (0 to 10) and `<slug>` is the kebab portion of the step filename. For the non-numbered routing/terminal steps (`resume`, `health-check`) emit `"stage":null` with the slug. One line per event; do not pretty-print.

package/src/skf-campaign/references/campaign-directive-spec.md

@@ -16,11 +16,13 @@ required; default filename `_campaign-directive.md`.
 
 All optional — the directive may hold any combination of these, or none:
 
-- **`## Quality Overrides`** — operator adjustments to quality gates for specific skills or the whole campaign.
-- **`## Skip List`** — skills to skip during processing, with rationale.
+- **`## Quality Overrides`**: operator adjustments to the quality gate, one list item each. `- soft_target: 85` and `- soft_fallback: 75` set the campaign-wide values, and `- <skill>: soft_target 80, soft_fallback 70` sets one skill's (either key alone is fine). A skill's line beats a campaign-wide line, and both beat the campaign brief and customize.toml. The hard gate cannot be overridden. They apply to each skill's test threshold (skill loop) and to the export classification (Capstone and Export).
+- **`## Skip List`**: skills to skip during processing, one list item each: `- <skill>: <reason>`, the reason optional. The skill loop and the Tier B batch mark a listed skill `skipped` before it runs and log the reason.
 - **`## Pipeline Flags`** — per-skill or campaign-wide pipeline modifiers.
 - **`## Notes`** — free-form operator context for the agent processing the campaign.
 
+`scripts/campaign-quality-gate.py` reads the Quality Overrides and Skip List sections (a section runs to the next `#` or `##` heading; backticks around a name are dropped), so their effect never depends on how a step reads the prose. A list item in them it cannot read is reported and logged, never applied, and a name that is no skill in the campaign is logged as a warning.
+
 Any heading not listed above is treated as general guidance: read it and apply
 judgment based on the content. This lets operators add ad-hoc context without
 modifying this specification.

package/src/skf-campaign/references/health-check.md

@@ -3,7 +3,6 @@
 # ({project-root}/_bmad/skf/ when installed, {project-root}/src/ during
 # development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
-stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -12,24 +11,16 @@ stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
 
 ## STEP GOAL:
 
-Apply the operator's findings-routing consent, then chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of skf-campaign — after the shared health check completes, the workflow is fully done.
+Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of skf-campaign: after the shared health check completes, the workflow is fully done.
+
+In headless mode step 11 bound `{result_envelope_line}` to the campaign's `SKF_CAMPAIGN_RESULT_JSON` line without displaying it: the shared health check displays that line verbatim as the run's last line wherever it stops, so a `claude -p` caller reads the envelope as the final message.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step 11.
-- The ONLY processing permitted here is reading the routing preference (below) and carrying it into `{nextStepFile}`; otherwise delegate directly with no additional commentary.
+- No user-facing reports, file writes, or result contracts in this step: those belong in step 11
+- Delegate directly to `{nextStepFile}` with no additional commentary
+- Do not attempt any other action between loading this step and executing `{nextStepFile}`
 
 ## MANDATORY SEQUENCE
 
-### 1. Apply findings-routing consent
-
-Read `campaign.health_findings_queue` from `{stateFile}` and carry it into the shared health check as the operator's **already-decided** routing consent (so the shared step does not re-prompt, satisfying its "explicit opt-in" requirement for non-bug findings):
-
-- `"improvement"` — the operator opted in at setup: route this campaign's friction/gap findings to the shared improvement queue (the shared step's opt-in is pre-satisfied; do not re-prompt).
-- `"local"` (default) — keep findings in the local queue only; do not submit to the shared queue.
-
-If the state file is unreadable, default to `"local"` (never submit without consent).
-
-### 2. Delegate
-
-Load `{nextStepFile}`, read it fully, then execute it — applying the routing consent from step 1.
+Load `{nextStepFile}`, read it fully, then execute it.

package/src/skf-campaign/references/step-01-setup.md

@@ -3,8 +3,9 @@ nextStepFile: 'step-02-strategy.md'
 stateSchemaFile: 'assets/campaign-state-schema.json'
 stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
 briefFile: '{campaignWorkspacePath}/campaign-brief.yaml'
+decisionLogFile: '{campaignWorkspacePath}/_campaign-decision-log.md'
 templateFile: '{briefTemplatePath}'
-validateScript: 'scripts/campaign-validate-state.py'
+stateScript: 'scripts/campaign-state.py'
 manifestScript: 'scripts/campaign-parse-manifest.py'
 ---
 
@@ -16,99 +17,61 @@ manifestScript: 'scripts/campaign-parse-manifest.py'
 
 Collect campaign inputs from the operator, create the initial `_campaign-state.yaml`, and generate `campaign-brief.yaml` so the campaign has a persistent starting point that survives context death.
 
-This is the only step that creates the state file (it does not yet exist). All subsequent steps use **read-backup-modify-write** per the State Contract in `references/campaign-contracts.md`.
-
 ## RULES
 
-- This step creates the state file — there is no existing state to read or back up.
-- Validate the written state with `uv run {validateScript} --state-file {stateFile}` before generating the brief. HALT (exit code 3, `invalid-state`) on non-zero, surfacing the script's `errors[]`.
-- If `{headless_mode}` is true, draw inputs from `--brief`/`--manifest` (On Activation step 4) and auto-proceed through confirmation gates with the default action, logging each auto-decision to the decision log.
+- This is the only step that creates the state file, with the helper's `init` operation (`{stateScript}`); every later write goes through `{stateScript}` too (State Contract in `references/campaign-contracts.md`), so no target, timestamp or gate value is ever typed into the state or the brief by hand.
+- If `{headless_mode}` is true, draw inputs from `--brief`/`--manifest` (On Activation step 4) and auto-proceed through confirmation gates with the default action, logging each auto-decision with `uv run {stateScript} log --log-file {decisionLogFile} --type auto --text '<entry>'`; emit this stage's progress events, and at any HARD HALT the error envelope, per `references/campaign-contracts.md`.
 
 ## TASKS
 
-### §1 — Collect Inputs
-
-Accept from the operator (or, in headless mode, from the `--brief`/`--manifest` source parsed in On Activation):
-
-- `campaign_name` — string identifier for this campaign run
-- Target libraries — each entry requires:
-  - `name` — skill name
-  - `repo_url` — source repository URL
-  - `tier` — `"A"` (full pipeline) or `"B"` (batch)
-  - `pin` — version pin (string) or `null` for latest
-  - `depends_on` — array of skill names this target depends on (may be empty)
-- `directive_path` (optional) — path to a `_campaign-directive.md` file with operator directives (contract: `references/campaign-directive-spec.md`)
-- `architecture_doc_path` (optional) — path to the architecture document the verify (Stage 7) and refine (Stage 8) stages consume. If omitted here, those stages discover it at runtime (`docs/architecture.md`, then `_bmad-output/planning-artifacts/architecture.md`). Capturing it now persists the choice across resume and avoids re-prompting.
-
-When seeding from `--manifest`, parse it deterministically: `uv run {manifestScript} <manifest-file>`. If the result's `errors[]` is non-empty (script exit 1), HALT (exit code 2, `invalid-input`) listing the offending line numbers — never run a partial target set. When seeding from `--brief`, read the existing `campaign-brief.yaml` directly.
-
-If no targets can be collected (empty interactive input or empty `--brief`/`--manifest`), HALT (exit code 2, `invalid-input`) with guidance — a campaign needs at least one target.
-
-### §2 — Health Queue Preference
-
-Default to `"local"` (project-local findings queue). Present the opt-in prompt:
-
-> Send anonymized quality findings to the shared improvement queue? [y/N]
-
-- **y** — set `health_findings_queue` to `"improvement"`
-- **N** (default) — keep `health_findings_queue` as `"local"`
-
-In headless mode: auto-select `"local"` (N) and log the auto-decision.
-
-### §3 — Build State Object
-
-Construct `_campaign-state.yaml` in memory from collected inputs. Use the campaign-wide quality gate resolved in On Activation: `{qualityGateHard}` / `{qualityGateSoftTarget}` / `{qualityGateSoftFallback}`. Note: `repo_url` (collected in §1) is NOT part of the state schema — it belongs in the brief only (§5). The state schema enforces `additionalProperties: false`, so including it would fail validation.
-
-```yaml
-campaign:
-  name: "{campaign_name}"
-  started_at: "{current_iso8601_with_tz}"
-  last_updated: "{current_iso8601_with_tz}"
-  current_stage: 0
-  directive_path: "{directive_path or omit if not provided}"
-  architecture_doc_path: "{architecture_doc_path or omit if not provided}"
-  quality_gate:
-    hard: "{qualityGateHard}"
-    soft_target: {qualityGateSoftTarget}
-    soft_fallback: {qualityGateSoftFallback}
-  health_findings_queue: "{local or improvement}"
-skills:
-  # One entry per target:
-  - name: "{target.name}"
-    status: "pending"
-    depends_on: []            # from target.depends_on
-    tier: "{target.tier}"
-    pin: null                 # from target.pin
-    brief_path: null          # populated in step-05 once BS produces the skill's brief
-    skill_path: null
-    quality_score: null
-    workarounds_applied: []
-    started_at: null
-    completed_at: null
-dependency_graph:
-  execution_order: []         # populated by step-02-strategy
-  circular_deps_detected: false
-```
+### §1: Collect Inputs
+
+A campaign needs a `campaign_name` and its target libraries. Each target has:
+
+- `name`: skill name
+- `repo_url`: source repository URL
+- `tier`: `"A"` (full pipeline) or `"B"` (batch)
+- `pin`: version pin (string), or `null` for latest
+- `depends_on`: array of skill names this target depends on (may be empty)
+
+Two paths are optional:
+
+- `directive_path`: a `_campaign-directive.md` file with operator directives (contract: `references/campaign-directive-spec.md`)
+- `architecture_doc_path`: the architecture document the verify (Stage 7) and refine (Stage 8) stages consume. If omitted here, those stages discover it at runtime (`{project-root}/docs/architecture.md`, then `{project-root}/_bmad-output/planning-artifacts/architecture.md`). Capturing it now persists the choice across resume and avoids re-prompting.
+
+A field no source gives takes its default: `tier` `"A"`, `pin` `null`, `depends_on` empty, and `campaign_name` the brief's `campaign_name`, else `{project_name}`. A Tier A target may not depend on a Tier B target: Tier B skills are built after the skill loop, so Strategy rejects that plan.
+
+Every target goes through `{manifestScript}`, whatever its source, so no target reaches state unchecked. It rejects a malformed target, a `repo_url` that is no GitHub repository (it reads a URL, an SSH URL or `owner/repo`, and writes each as `https://github.com/<owner>/<repo>`), a name that is no skill name (lower-case letters, digits and hyphens, at most 64 characters), a Tier A pin that is no X.Y.Z version (the only pin brief-skill builds from) and a duplicate name. It fills an empty name from the repository (`filled_names`), and lists each `depends_on` name that is no target (`dangling_depends_on`) and each Tier A target that depends on a Tier B target (`tier_inversions`), each entry naming its `skill` and `depends_on`. The state and the brief take their targets from the script's `targets[]`, never from the raw source.
+
+**Manifest format** (a `--manifest` file, and a pasted list rewritten for the script): one `name,repo_url,tier,pin` target per line, where an empty `name` takes the repository's name and an empty `pin` means the latest release; a trailing `;dep1,dep2` segment sets `depends_on`; blank and `#` lines are skipped.
 
-### §4 — Write + Validate State
+**Headless** (`--brief` and `--manifest` imply it): take the inputs from the source On Activation parsed. Parse a `--manifest` file with `uv run {manifestScript} <manifest-file>` and a `--brief` file with `uv run {manifestScript} --brief <brief-file>`, which also returns the brief's `campaign_name`, `quality_gate`, `architecture_doc_path` and `notes` under `brief`. Headless asks nothing about `dangling_depends_on` or `tier_inversions`: Strategy halts on them (exit code 4).
 
-1. Ensure the directory `{campaignWorkspacePath}/` exists (create if missing).
-2. Write the constructed state to `{stateFile}`. This is the initial creation — no `.bak` is needed for the first write; all subsequent steps use read-backup-modify-write.
-3. Run `uv run {validateScript} --state-file {stateFile}`. On non-zero (invalid), **HALT** (exit 3) with the script's `errors[]` — do not proceed to brief generation with an invalid state file.
+**Interactive:** open with this one question, and ask nothing before it:
+
+> Share the targets for this campaign in whatever form you have them: a manifest or `campaign-brief.yaml` path, a pasted list, or repository URLs. Add a campaign name and a directive or architecture document path if you have them.
+
+Turn the answer into targets: a manifest path goes through `uv run {manifestScript} <manifest-file>`, and a brief path through `uv run {manifestScript} --brief <brief-file>`. A pasted list or bare repository URLs are first rewritten as manifest lines in the manifest format above (leave the name empty when none is given: the script takes it from the repository), then piped to `uv run {manifestScript} -`. Show the drafted campaign once for correction: the campaign name, the directive and architecture paths (or none), and one table of the targets with `name`, `repo_url`, `tier`, `pin` and `depends_on`. After the operator's corrections, ask only about what is still missing or ambiguous, all in one question, read from the script's output rather than by matching names yourself: each `dangling_depends_on` entry (a `depends_on` name that is no target), each `tier_inversions` entry (make the dependency Tier A, or drop it) and each `filled_names` entry (confirm the name). Run a corrected set through the script again before §2.
+
+A target the script rejects (`errors[]` non-empty, exit 1: a malformed manifest line or brief target, a `repo_url` that is no GitHub repository, a name that is no skill name, a Tier A pin that is no X.Y.Z version, a duplicate name, a brief `pin` that is not a string) never yields a partial target set: in headless, HALT (exit code 2, `invalid-input`) listing each error's line or target number and message; interactively, show them and ask for those targets corrected. An exit 2 (a file that is missing, unreadable or not a YAML mapping) HALTs (exit code 2, `invalid-input`) with its `error`.
+
+If no targets can be collected (an empty answer, or an empty `--brief` or `--manifest`), HALT (exit code 2, `invalid-input`) with guidance: a campaign needs at least one target.
+
+### §2: Create State
+
+Settle the campaign name (the brief's `campaign_name`, else the operator's, else `{project_name}`), then create the state in one call. Pipe in the parse of the settled targets: the last §1 parse run again (the manifest file, `--brief <brief-file>`, or the corrected manifest lines on stdin), so the state takes its targets from the script's `targets[]`, never from the raw source:
+
+```
+uv run {manifestScript} <the settled source> | uv run {stateScript} init --state-file {stateFile} --targets-file - --name "<campaign_name>" --hard "{qualityGateHard}" --soft-target {qualityGateSoftTarget} --soft-fallback {qualityGateSoftFallback} [--brief-file <brief-file>] [--directive-path <directive_path>] [--architecture-doc-path <architecture_doc_path>] --brief-out {briefFile} --brief-template {templateFile} [--notes '<operator notes>']
+```
 
-### §5 — Generate Brief
+Pass `--brief-file` when the targets came from a campaign brief: each value its `quality_gate` gives wins over the customize.toml one. The directive's `## Quality Overrides` apply later, while the campaign runs, and are never written here. The helper settles and checks the gate with `campaign-quality-gate.py check`, creates `{campaignWorkspacePath}/`, writes every target as a `pending` skill, stamps `started_at` and `last_updated` from the clock, and validates the state before it writes it. There is no earlier state, so no `.bak` is written. It then writes `{briefFile}` from `{templateFile}`: the campaign name, `created_at` (the state's `started_at`), the same `targets[]`, one entry per target with `name`, `repo_url`, `tier`, `pin` and `depends_on`, plus every other field its source gave it (a language or scope hint, for example), the settled `quality_gate`, `architecture_doc_path` and `notes`. `repo_url` lives only in the brief: the state schema has no place for it. Pass `--notes` only with notes the operator gave, single-quoted as a decision-log entry is (`references/campaign-contracts.md`); without it a brief's own `notes` carry over.
 
-Populate `{templateFile}` with collected inputs and write to `{briefFile}`. Fill in:
+On exit 2, HALT (exit code 2, `invalid-input`) with its `error` and `errors[]`; nothing is written: a gate the gate script rejects (a hard gate other than `zero-critical-high`, a soft value outside 0 to 100, a fallback above the target, or a brief it cannot read), targets that hold errors, a brief template that is no YAML mapping, or a state file or backup that already exists. On exit 3, HALT (exit code 3, `invalid-state`) with its `errors[]`.
 
-- `campaign_name` — from collected input
-- `created_at` — current ISO-8601 timestamp with timezone
-- `targets` — array of target entries with `name`, `repo_url`, `tier`, `pin`, `depends_on`
-- `quality_gate` — `{qualityGateHard}` / `{qualityGateSoftTarget}` / `{qualityGateSoftFallback}`
-- `health_findings_queue` — from the §2 preference decision
-- `architecture_doc_path` — from collected input, or empty string if not provided
-- `notes` — operator-provided context, or empty string
+### §3: The Brief
 
-The brief is a machine-readable snapshot enabling fresh-context resume.
+`init` (§2) wrote `{briefFile}` from the same `targets[]`, so write nothing by hand: it is the machine-readable snapshot a fresh session resumes from.
 
 ## OUTPUT
 
@@ -116,6 +79,5 @@ Confirm state file creation and brief generation. Display summary:
 
 - Campaign name
 - Number of targets
-- Health queue setting
 
 Chain to `{nextStepFile}`.

package/src/skf-campaign/references/step-02-strategy.md

@@ -2,8 +2,9 @@
 nextStepFile: 'step-03-pins.md'
 stateSchemaFile: 'assets/campaign-state-schema.json'
 stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
-backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
+decisionLogFile: '{campaignWorkspacePath}/_campaign-decision-log.md'
 depsScript: 'scripts/campaign-deps.py'
+stateScript: 'scripts/campaign-state.py'
 validateScript: 'scripts/campaign-validate-state.py'
 ---
 
@@ -17,51 +18,41 @@ Compute the execution order from dependency edges, detect circular dependencies,
 
 ## RULES
 
-- This step uses the **read-backup-modify-write** pattern (state file exists from step-01).
-- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
-- Write `execution_order` and `circular_deps_detected` to `dependency_graph`.
-- Update `campaign.current_stage` to `1`.
-- 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` = 1 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. Here that write follows the §6 plan gate, so a campaign cancelled at the plan shows the plan again when it resumes.
+- Write state and decision-log entries only through `{stateScript}`, and on a non-zero exit HALT with the same code (State Contract in `references/campaign-contracts.md`). A log entry is `uv run {stateScript} log --log-file {decisionLogFile} --type <decision|auto|event> --text '<entry>'`.
+- If `{headless_mode}` is true, auto-proceed through the plan gate with its default action and log the auto-decision; 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 — Backup State
-
-Copy `{stateFile}` to `{backupFile}` before any modification.
-
-### §3 — 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).
 
-### §4 — Compute Execution Order
+### §3: Compute Execution Order
 
-Run the deterministic topological sort — do not hand-compute it:
+Run the deterministic topological sort; do not hand-compute it:
 
 ```
 uv run {depsScript} --compute --state-file {stateFile}
 ```
 
-Parse the JSON output: `execution_order` (the ordered skill names — Kahn's sort with Tier A placed before Tier B within a dependency level), `circular_deps_detected` (bool), `cycle_participants` (the unplaced skills when a cycle exists, else null), and `tier_counts` (`{"A": n, "B": m}`, for the §7 strategy view). Script exit 1 signals an unorderable graph — a cycle or a dangling `depends_on` reference — handled at §5. Script exit 2 signals the helper could not read/parse the state file; HALT (exit code 2, `invalid-input`) surfacing its error.
+Parse the JSON output: `execution_order` (the ordered skill names: Kahn's sort with Tier A placed before Tier B within a dependency level), `circular_deps_detected` (bool), `cycle_participants` (the unplaced skills when a cycle exists, else null), `tier_counts` (`{"A": n, "B": m}`, for the §5 strategy view) and `tier_inversions` (each Tier A `skill` that `depends_on` a Tier B skill). Script exit 1 signals a plan the stages cannot follow (a cycle, a dangling `depends_on` reference or a tier inversion), handled at §4 before the §5 view shows any order. Script exit 2 signals the helper could not read/parse the state file; HALT (exit code 2, `invalid-input`) surfacing its error.
 
-### §5 — Handle Unorderable Graph
+### §4: Handle Unorderable Graph
 
-If the graph cannot be ordered (script exit 1), HALT (exit code 4, `circular-deps`) — the execution order is impossible, so do not proceed. Two cases:
+If the graph cannot be followed (script exit 1), HALT (exit code 4, `circular-deps`): the execution order is impossible, so do not proceed. Three cases:
 
 - **Cycle** (`circular_deps_detected: true`): list `cycle_participants` and their mutual `depends_on` edges.
 - **Dangling reference** (a `DANGLING_DEPENDENCY` error with no `execution_order`): name the skill and the unknown dependency it references.
+- **Tier A on Tier B** (`tier_inversions` non-empty, a `TIER_INVERSION` error): name each `skill` and the Tier B skill it `depends_on`. Tier B skills are built in the batch stage, after the skill loop, so the Tier A skill could never pass its dependency gate. Guidance: make the dependency Tier A, or drop the dependency, then re-run `campaign` and choose overwrite.
 
-### §6 — Write State
-
-Set `dependency_graph.execution_order` to the computed order. Set `dependency_graph.circular_deps_detected` to the detection result. Set `campaign.current_stage` to `1`. Set `campaign.last_updated` to current ISO-8601 with timezone. Write to `{stateFile}`.
+### §5: Present Strategy View
 
-### §7 — Present Strategy View
-
-Display a human-readable strategy summary to the operator (not written to a file — display only):
+Display a human-readable strategy summary to the operator (display only: it is not written to a file):
 
 ```
 CAMPAIGN STRATEGY: {campaign_name}
@@ -86,17 +77,27 @@ TIER DISTRIBUTION:
   Tier B (QS batch): {count}
 ```
 
-Fill the TIER DISTRIBUTION counts from `tier_counts` in the §4 script output — do not re-tally `skills[]` by hand.
+Fill the TIER DISTRIBUTION counts from `tier_counts` in the §3 script output; do not re-tally `skills[]` by hand.
 
-### §8 — Plan Confirmation Gate
+### §6: Plan Confirmation Gate
 
 The strategy view is the last review surface before a potentially long, mostly-unattended run begins. Present a confirmation gate:
 
-- `[P]roceed` — begin execution (chain to `{nextStepFile}`).
-- `[C]ancel` — stop now with exit code 12 (`user-cancelled`); state is intact and resumable. To change targets, edit the campaign brief (`{campaignWorkspacePath}/campaign-brief.yaml`) or re-run `campaign` (overwrite), then start again.
+- `[P]roceed`: write the plan (§7), then chain to `{nextStepFile}`.
+- `[C]ancel`: log the cancel, then stop with exit code 12 (`user-cancelled`). Nothing of this stage is written, so the state is intact and a resume shows this plan again. To change targets, tiers, pins or dependencies, re-run `campaign` and choose overwrite: they live in the state that Setup wrote, and editing `campaign-brief.yaml` does not reach them.
+
+**HALT and wait for operator input.** **GATE [default: P]**: in headless mode, auto-proceed with `[P]` and log "headless: auto-proceed past plan-confirmation gate" (type `auto`).
+
+### §7: Write State
+
+On `[P]roceed`, write the plan and the stage in one write:
+
+```
+uv run {stateScript} apply-plan --state-file {stateFile} --stage 1
+```
 
-**HALT and wait for operator input.** In headless mode, auto-proceed with `[P]` and log "headless: auto-proceed past plan-confirmation gate" to the decision log.
+It sets `dependency_graph.execution_order` and `circular_deps_detected` from the same `campaign-deps.py --compute` the §3 view came from, so the order on disk is the order shown. On exit 4 (the graph can no longer be followed: the state changed since §3), HALT (exit code 4, `circular-deps`) with its `errors[]`; on exit 3, HALT (exit code 3, `invalid-state`).
 
 ## OUTPUT
 
-Confirm strategy computed, display the strategy view, and resolve the §8 gate. Chain to `{nextStepFile}`.
+Confirm strategy computed, display the strategy view, resolve the §6 gate and write the §7 plan. Chain to `{nextStepFile}`.

package/src/skf-campaign/references/step-03-pins.md

@@ -2,9 +2,11 @@
 nextStepFile: 'step-04-provenance.md'
 stateSchemaFile: 'assets/campaign-state-schema.json'
 stateFile: '{campaignWorkspacePath}/_campaign-state.yaml'
-backupFile: '{campaignWorkspacePath}/_campaign-state.yaml.bak'
 briefFile: '{campaignWorkspacePath}/campaign-brief.yaml'
+pinResultsFile: '{campaignWorkspacePath}/_pin-results.json'
+decisionLogFile: '{campaignWorkspacePath}/_campaign-decision-log.md'
 pinScript: 'scripts/campaign-validate-pins.py'
+stateScript: 'scripts/campaign-state.py'
 validateScript: 'scripts/campaign-validate-state.py'
 ---
 
@@ -18,39 +20,45 @@ Validate all version pins against real releases/branches before the campaign pro
 
 ## RULES
 
-- This step uses the **read-backup-modify-write** pattern (state file exists from step-01).
-- Validate state on load via `uv run {validateScript} --state-file {stateFile}`; HALT (exit 3) on non-zero.
-- Update `campaign.current_stage` to `2`.
-- Update `campaign.last_updated` to current ISO-8601 with timezone on every write.
-- HALT (exit code 5, `invalid-pin`) on any invalid pin — invalid pins are errors, not gates.
-- If `{headless_mode}` is true, auto-proceed through confirmation gates with the default action and log each auto-decision.
+- Write `campaign.current_stage` = 2 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>'`.
+- HALT (exit code 5, `invalid-pin`) on any invalid pin: invalid pins are errors, not gates.
+- 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}`. 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 pin script reads it directly). HALT (exit code 8, `missing-brief`) if the brief is missing or unreadable.
 
-### §3 — Backup State
+### §3: Validate Pins
 
-Copy `{stateFile}` to `{backupFile}` before any modification.
+Run the pin script, keeping its JSON output in `{pinResultsFile}` for §5:
 
-### §4 — Validate Pins
+```
+uv run {pinScript} --state-file {stateFile} --brief-file {briefFile} > {pinResultsFile}
+```
 
-Run `uv run {pinScript} --state-file {stateFile} --brief-file {briefFile}`. If the script exits 2 (a required tool such as `gh` is unavailable, or a file is unreadable), HALT (exit code 2, `invalid-input`) surfacing its error — pins cannot be validated without `gh`. Otherwise parse the JSON output. For each result: if `status` is `"valid"` or `"resolved"`, the pin is good; if `"invalid"`, collect the failure with suggestions.
+If the script exits 2 (a required tool such as `gh` is unavailable, a file is unreadable, or `INVALID_BRIEF`: a brief that is no mapping or holds a target with no `name` or no `repo_url`), HALT (exit code 2, `invalid-input`) surfacing its error; only when `gh` is what is missing, add that pins cannot be validated without it. Otherwise read `{pinResultsFile}`. For each result: if `status` is `"valid"` or `"resolved"`, the pin is good; if `"invalid"`, collect the failure with suggestions.
 
-### §5 — Handle Invalid Pins
+### §4: Handle Invalid Pins
 
 If ANY pins are invalid, collect ALL failures first (all-or-nothing pattern), then HALT (exit code 5, `invalid-pin`) with a clear error listing each invalid pin, the skill name, the attempted pin value, and suggested corrections. Do NOT partially proceed.
 
-### §6 — Update State
+### §5: Write State
 
-For each skill where validation returned `status: "resolved"` (pin was null, latest release found), update `skill.pin` to the `resolved_ref` value. For `status: "valid"` where the input pin differs from `resolved_ref` (e.g., user said `2.0.0` but the actual tag is `v2.0.0`), update `skill.pin` to the `resolved_ref` so downstream steps use the exact ref name. Set `campaign.current_stage` to `2`. Set `campaign.last_updated`. Write to `{stateFile}`.
+Write every resolved pin and the stage in one write:
+
+```
+uv run {stateScript} apply-pins --state-file {stateFile} --results-file {pinResultsFile} --stage 2
+```
+
+It sets each skill's `pin` to the script's `resolved_ref` wherever the two differ: a null pin that resolved to the latest release, or a pin written without its tag's form (`2.0.0` for the tag `v2.0.0`), so downstream steps use the exact ref name. It refuses results that hold an invalid pin (exit 5, nothing written: HALT as in §4); on exit 3, HALT (exit code 3, `invalid-state`).
 
 ## OUTPUT
 
-Display pin validation summary — for each skill: name, pin, resolved ref, ref type. Chain to `{nextStepFile}`.
+Display pin validation summary: for each skill, name, pin, resolved ref, ref type. Chain to `{nextStepFile}`.