bmad-module-skill-forge 2.2.0 → 3.0.0

package/docs/campaign.md

@@ -3,54 +3,91 @@ title: Campaign Orchestration
 description: Multi-library skill production with dependency tracking, file-based state, and resume
 ---
 
-Campaign orchestration drives the production of 15+ coordinated skills through the full SKF pipeline (brief, generate, compile, test, export) in dependency order. It sits at the top of the pipeline ladder — it does not produce skill artifacts directly but sequences the workflows that do.
+Campaign orchestration builds many related skills as one coordinated campaign, in dependency order. It is meant for projects with many libraries (15 or more), but one library is enough to start. Each Tier A library goes through the full SKF pipeline: brief, compile and test. Tier B libraries take a faster batch path. The finished skills are exported together at the end (see [Tier A vs Tier B](#tier-a-vs-tier-b)). The `skf-campaign` skill does not write skills itself. It runs the SKF workflows that do, in the right order.
 
-When your architecture declares many dependencies, running individual pipelines one at a time is tedious and error-prone. Campaign automates the entire loop: it reads the dependency graph, sorts skills topologically, drives each one through the pipeline, enforces quality gates, and tracks state to disk so you can resume after a context death or session break.
+When your project depends on many libraries, building one skill at a time is slow and easy to get wrong. Campaign runs the whole loop for you. You list the libraries and what each one depends on, and Campaign orders them so every skill is built after the skills it depends on. It then drives each one through the pipeline, applies the quality gates, and saves its progress to disk as it goes. If the AI session runs out of context or you close it, you can resume where you left off.
+
+---
+
+## Before You Start
+
+- Run `skf-setup` first, so SKF knows your tools and folders.
+- Install the GitHub CLI (`gh`) and sign in. Pin Validation and Provenance use it to check every repository, and without it the campaign stops before any skill is built. Each library's repository must be on GitHub.
+- An architecture document is optional. Only the Verification and Refinement stages use it (see [Stages](#stages)).
 
 ---
 
 ## Invocation
 
+Ask Ferris to run `campaign`, or call the `skf-campaign` skill directly.
+
 ```
-@Ferris campaign                           — start a new campaign
-@Ferris campaign resume                    — resume from the last active skill
-@Ferris campaign resume --from=<skill>     — resume from a specific skill
-@Ferris campaign status                    — read-only progress summary
+@Ferris campaign                          # start a new campaign
+@Ferris campaign resume                   # resume from the last active skill
+@Ferris campaign resume --from=<skill>    # resume from a specific skill
+@Ferris campaign status                   # read-only progress summary
 ```
 
-- **`campaign`** starts a new campaign from stage 0 (Setup). If a `_campaign-state.yaml` already exists, Ferris offers a choice: resume the existing campaign or overwrite with a new one.
-- **`campaign resume`** picks up where the last session left off. State is validated on load — if the state file is corrupted, the `.bak` file is used as a fallback.
-- **`campaign status`** loads and validates the current state, prints the resume-detection summary plus the tail of the decision log, then stops — no backup, no mutation, no chaining. Use it to check on a long-running campaign without advancing it.
-- **`--from=<skill>`** overrides the resume point to the named skill, useful when you want to re-process a specific skill without restarting the entire campaign.
+- **`campaign`** starts a new campaign from stage 0 (Setup). If a `_campaign-state.yaml` or its backup already exists, Ferris offers a choice: resume the existing campaign or overwrite with a new one.
+- **`campaign resume`** picks up where the last session left off. Ferris checks the state file first. If it is damaged, Ferris restores the `.bak` backup copy and continues from that.
+- **`campaign status`** checks the state file and shows the campaign name, the current stage, how many skills are done out of the total, and how many skills have each status. After that come the last lines of the decision log. Then it stops. It makes no backup, changes nothing and starts no stage, so you can check on a long campaign without moving it forward.
+- **`--from=<skill>`** moves the resume point to the named skill. To rebuild a skill that already finished, choose `[R]e-run` when Ferris asks.
 
 ### Override flags
 
 | Flag | Effect |
 |------|--------|
-| `--headless` / `-H` | Auto-proceed every gate with its default action and emit structured output (see [Headless / Automation](#headless--automation)). |
-| `--brief <file>` | Seed targets from a `campaign-brief.yaml` instead of interactive prompts. Implies `--headless`. |
-| `--manifest <file>` | Seed targets from a plain-text `name,repo_url,tier,pin` manifest (one per line; trailing `;dep1,dep2` for `depends_on`). Implies `--headless`. |
+| `--headless` / `-H` | Answer every question with its default and print machine-readable progress and results (see [Headless / Automation](#headless--automation)). |
+| `--brief <file>` | Seed targets from a `campaign-brief.yaml` instead of interactive prompts. Implies `--headless`: a seeded run is an unattended (CI) run that takes every default. To review the plan and the export, give the same file at the Setup question instead, which stays interactive. |
+| `--manifest <file>` | Seed targets from a plain-text `name,repo_url,tier,pin` manifest (one per line; trailing `;dep1,dep2` for `depends_on`). Implies `--headless`, as `--brief` does, for the same reason. |
 | `--from=<skill>` | Resume override (see above). |
 
+### What Setup Asks For
+
+An interactive Setup opens with one question: give the targets in whatever form you have them, such as a manifest or `campaign-brief.yaml` path, a pasted list or repository URLs. Add a campaign name, and the path to a `_campaign-directive.md` file or to your architecture document, if you have them.
+
+Setup then drafts the campaign and shows it once for you to correct: the campaign name (your project name unless you gave one), the directive and architecture paths, and one table of the targets with these columns:
+
+- `name`: the skill name
+- `repo_url`: the GitHub repository, as a URL, an SSH URL or `owner/repo`. Setup writes it as `https://github.com/<owner>/<repo>` and rejects another host or a path inside a repository
+- `tier`: `A` (full pipeline) or `B` (quick batch), see [Tier A vs Tier B](#tier-a-vs-tier-b). `A` unless you say otherwise
+- `pin`: empty for the latest release (the default). A Tier A pin must be a full `X.Y.Z` version (a `v` prefix is allowed), because brief-skill builds a Tier A skill from a release version only; a Tier B pin may also be a branch
+- `depends_on`: the other skills in this campaign that it depends on, none by default
+
+After your corrections, Setup asks only about what is still missing or ambiguous, such as a target with no repository URL or a dependency that names no target, all in one question.
+
+To skip these questions, pass the list as a manifest file with `--manifest`:
+
+```
+# name,repo_url,tier,pin;depends_on
+core-lib,https://github.com/acme/core-lib,A,
+web-sdk,https://github.com/acme/web-sdk,A,2.1.0;core-lib
+cli-helpers,https://github.com/acme/cli-helpers,B
+```
+
+Setup checks every target the same way, whether it comes from a manifest, a `--brief` file or a pasted list. It rejects a malformed line or target, a `repo_url` that is not a GitHub repository, a name that is not a skill name (lower-case letters, digits and hyphens, at most 64 characters), a Tier A pin that is not an `X.Y.Z` version, and a duplicate name. A headless run then stops with exit code 2 and lists each bad line or target with what is wrong with it, and an interactive Setup shows them and asks you to correct those targets. It never runs with only part of the list.
+
 ---
 
 ## Stages
 
-Campaign runs through 11 stages (0–10). All stages auto-proceed except Export, which requires explicit approval before writing skills to disk.
-
-| Stage | Name | Description | Auto-proceed |
-|-------|------|-------------|--------------|
-| 0 | Setup | Initialize campaign state, detect existing skills, and configure output paths | Yes |
-| 1 | Strategy | Generate the campaign brief from architecture and dependency analysis | Yes |
-| 2 | Pin Validation | Validate version pins for all declared dependencies | Yes |
-| 3 | Provenance | Establish provenance records for each target library | Yes |
-| 4 | Skill Loop | Drive each Tier A skill through its forge pipeline (AN → BS → CS → TS) in dependency order — export is deferred to the gated Export stage | Yes |
-| 5 | Tier B Batch | Process Tier B skills (lower-priority or transitive dependencies) in batch mode | Yes |
-| 6 | Capstone | Generate stack skill(s) that integrate individual skills into a cohesive project context | Yes |
-| 7 | Verification | Run verification passes across all produced skills for cross-skill consistency | Yes |
-| 8 | Refinement | Address gaps found during verification — re-run pipelines for skills that need improvement | Yes |
-| 9 | Export | Write all verified skills to disk and update context files — **requires user approval** | No |
-| 10 | Maintenance | Generate the campaign report and clean up temporary state | Yes |
+Campaign runs through 11 stages, numbered 0 to 10. Most run on their own. Setup asks for your campaign details, unless you pass `--brief` or `--manifest`. Two stages always stop for your answer: Strategy shows you the plan before any skill is built, and Export asks before it writes anything. The Skill Loop, Verification and Refinement ask only when they need a decision. In headless mode, every question takes its default answer.
+
+| Stage | Name | What happens | Waits for you? |
+|-------|------|--------------|----------------|
+| 0 | Setup | Asks for the campaign name and the libraries to skill, writes `_campaign-state.yaml`, and generates `campaign-brief.yaml` | Yes, for its questions (not with `--brief` or `--manifest`) |
+| 1 | Strategy | Works out the build order so each skill comes after the skills it depends on, stops on a circular or unknown dependency, and shows you the plan | Yes: `[P]roceed` or `[C]ancel` |
+| 2 | Pin Validation | Checks every version pin against the repository's real releases and branches, and fills an empty pin with the latest release | No |
+| 3 | Provenance | Checks that every repository is reachable and records the exact commit each skill is built from | No |
+| 4 | Skill Loop | Builds each Tier A skill in order through brief (BS), compile (CS) and test (TS). Export waits for stage 9 | Only when a skill's dependencies have not completed |
+| 5 | Tier B Batch | Builds every Tier B skill in one Quick Skill batch run (`skf-quick-skill --batch`) | No |
+| 6 | Capstone | Composes one stack skill from the completed skills that clear the quality gate, using `skf-create-stack-skill` in compose mode | No |
+| 7 | Verification | Runs `skf-verify-stack` against your architecture document and records the overall verdict and coverage it reports | Only to ask for a missing architecture document |
+| 8 | Refinement | Runs `skf-refine-architecture`, which writes a refined copy of your architecture document based on the skills | Only to ask for a missing architecture document |
+| 9 | Export | Lists each completed skill with its quality-gate verdict, names the ones the gate leaves out and, once you approve, runs `skf-export-skill` on each `pass` and `fallback` skill to package it and update your context files | Yes: `[E]xport all` or `[C]ancel` |
+| 10 | Maintenance | Writes `campaign-report.md`, runs your `on_complete` hook if you set one, then runs the end-of-workflow health check | No |
+
+Verification and Refinement use the architecture document path you gave at Setup. Without one, they look for `docs/architecture.md` and then `_bmad-output/planning-artifacts/architecture.md`. A headless run with no architecture document skips both stages. If either stage fails, the failure is logged and the campaign carries on.
 
 ---
 
@@ -58,35 +95,49 @@ Campaign runs through 11 stages (0–10). All stages auto-proceed except Export,
 
 ### campaign-brief.yaml
 
-A machine-generated brief that captures the full scope of the campaign: which libraries to skill, their version pins, dependency relationships, and quality targets. Created during the Strategy stage from your architecture document and dependency declarations.
+A machine-readable summary of the campaign, written during Setup by the same helper call that writes `_campaign-state.yaml`, from the targets Setup checked (what you enter, or `--brief` or `--manifest`). It holds the campaign name; each library's repository URL, tier, version pin and dependencies, and any language or scope hint its source gave; the quality gate; the architecture document path; and your notes. Later stages read the repository URLs from it, and a fresh session uses it to pick the campaign back up.
 
 ### _campaign-state.yaml
 
-The single source of truth for campaign progress. Every state mutation follows a read-backup-modify-write pattern — the current state is backed up before each write, so a crash during write never loses more than one operation. All progress tracking lives here, not in conversation context.
+The single source of truth for campaign progress. Every write goes through one helper, `campaign-state.py`, which validates the state before and after the change, copies the valid state it read to `_campaign-state.yaml.bak` (never an invalid one), and writes the new state atomically, through a temporary file renamed over the old one, so a crash leaves the old state or the new one, never half of one. It takes every timestamp from the clock, in UTC. All progress lives in this file, not in the conversation.
 
 ### _campaign-directive.md
 
-A standing directive document that carries cross-cutting instructions for the campaign. See the [campaign directive spec](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-campaign/references/campaign-directive-spec.md) for the full specification and usage patterns.
+An optional Markdown file of standing instructions for the whole campaign. You give its path at Setup. Each stage that uses it re-reads it when the stage starts, so edits you make between stages take effect. It can hold `## Quality Overrides`, `## Skip List`, `## Pipeline Flags` and `## Notes` sections, and any other heading is read as general guidance. See the [campaign directive spec](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-campaign/references/campaign-directive-spec.md) for the full format.
+
+### Where Campaign Files Live
+
+Everything the campaign writes about itself sits in one folder: `forge-data/_campaign/` by default (`{forge_data_folder}/_campaign`). It holds `_campaign-state.yaml` and its `.bak` backup, `campaign-brief.yaml`, the decision log, the Tier B batch input, the `archive/` folder and `campaign-report.md`. To move it, set `campaign_workspace_path` (see [Customization](#customization)).
+
+### _campaign-decision-log.md
+
+This log only grows. It records every decision in the campaign, whether you made it or a headless run took the default: skip or force at a dependency gate, overwrite, export or cancel at the Export gate, recovery from the backup, a cancel at any other question, and why a skill failed. Each entry is one timestamped line with its type: `decision` (your choice at a question), `auto` (the default a headless run took) or `event` (what happened without a choice, such as a failed skill). `campaign status` shows its last lines.
 
 ### Dependency Tracking
 
-Campaign sorts skills topologically by their dependency graph. If skill B depends on skill A, skill A is produced first. This ensures downstream skills can reference upstream APIs during compilation.
+Campaign orders skills by their `depends_on` lists, so if skill B depends on skill A, skill A is built first. A dependency counts as met only when that skill has completed. If it has not, the Skill Loop stops at the waiting skill and asks you to `[S]kip` it, `[F]orce` it anyway, or `[H]alt`, which stops the campaign with exit code 13 (`dependency-blocked`) and leaves it ready to resume. A headless run never forces: it skips the waiting skill when every unmet dependency failed or was skipped, so the skills that do not depend on it still run, and halts with exit code 13 only while a dependency is still pending or active. A circular or unknown dependency stops the campaign at Strategy with exit code 4.
 
 ### Tier A vs Tier B
 
-- **Tier A** — primary dependencies declared in the architecture. Each gets a full individual pipeline run (AN → BS → CS → TS) during the Skill Loop stage; the tested skills are exported collectively at the gated Export stage.
-- **Tier B** — secondary or transitive dependencies. Processed in batch during the Tier B Batch stage with lighter-touch quality requirements.
+You choose a tier for each library at Setup.
+
+- **Tier A** gets the full pipeline during the Skill Loop: brief (BS), compile (CS) and test (TS). The tested skills that clear the quality gate are exported together at the Export stage.
+- **Tier B** is built in one batch by Quick Skill (`skf-quick-skill --batch`) during the Tier B Batch stage. It is faster and gives best-effort skills, with no separate test step.
+
+Do not make a Tier A library depend on a Tier B library. A dependency counts as met only once that skill has completed, and Tier B skills are built after the Skill Loop, so the Tier A skill could never pass the dependency gate. Strategy rejects such a plan with exit code 4 and names each Tier A skill and the Tier B skill it depends on (`tier_inversions`): make the dependency Tier A, or drop it.
 
 ### Customization
 
-Campaign ships a `customize.toml` workflow surface you can tune without forking the skill. The resolver merges three layers (scalars override, arrays append): the bundled `customize.toml`, then a committed team override at `_bmad/custom/<skill-name>.toml`, then a personal (gitignored) override at `_bmad/custom/<skill-name>.user.toml` — both under {project-root}. What you can set:
+Campaign ships a `customize.toml` file that you can tune without forking the skill. When the campaign starts, it merges three layers: the bundled `customize.toml`, then a team override committed at `_bmad/custom/skf-campaign.toml`, then a personal override at `_bmad/custom/skf-campaign.user.toml` that git ignores. Both overrides sit under your project root. A single value in a later layer replaces the earlier one, and list entries add up. You can set:
 
-- **Quality-gate scalars** — `quality_gate_hard`, `quality_gate_soft_target`, `quality_gate_soft_fallback` (the thresholds above).
-- **`campaign_workspace_path`** — relocate the entire campaign workspace (state, backup, brief, archive, decision log) to a shared volume without editing any step file; empty means the default `{forge_data_folder}/_campaign`.
-- **`persistent_facts`** — literal sentences or `file:` references (globs supported) injected into every per-skill kickoff, so house style and guardrails reach the whole campaign.
-- **Template overrides** — `report_template_path`, `kickoff_template_path`, `brief_template_path` for house-style copies.
-- **`on_complete`** — a post-completion hook invoked with `--report-path=<…>` after the report finalizes; hook failures are logged but never fail the campaign.
-- **`activation_steps_prepend` / `activation_steps_append`** — org-wide pre-flight or context-load steps around activation.
+- **Quality-gate values**: `quality_gate_hard`, `quality_gate_soft_target` and `quality_gate_soft_fallback` (see [Quality Gates](#quality-gates) below).
+- **`campaign_workspace_path`**: moves the whole campaign folder (state, backup, brief, batch input, archive, report and decision log), for example to a shared volume. Empty means the default, `{forge_data_folder}/_campaign`.
+- **`persistent_facts`**: plain sentences or `file:` references (globs allowed) added to every skill's kickoff message, so house style and guardrails reach the whole campaign. By default it loads every `project-context.md` in your project. A `file:` path with no glob character that names no file stops the campaign at its first Tier A kickoff with exit code 2, while a glob that matches nothing adds nothing. To drop the default, add `persistent_facts = ["!file:{project-root}/**/project-context.md"]` to a team or personal override: an entry that starts with `!` adds nothing and removes every earlier entry it names, so those files stay out of every Tier A kickoff.
+- **Template overrides**: `report_template_path`, `kickoff_template_path` and `brief_template_path` point to your own copies of the templates.
+- **`on_complete`**: a command run at the end of the campaign, after its final state write. It gets `--report-path=<path>` only when the report was written. If it fails, the failure is logged and the campaign still succeeds.
+- **`activation_steps_prepend` / `activation_steps_append`**: extra steps run before or after activation, for org-wide checks or loading context.
+
+These overrides need BMAD Method's customization script, which the BMAD Method installer adds. In a project with SKF alone, the campaign ignores `_bmad/custom/` and uses the bundled values, prints `[activation/warn] customization_resolver_unavailable: not found` and, except for `campaign status`, logs that event in its decision log. See [Workflows: Customizing a Workflow](/docs/workflows.md#customizing-a-workflow) for the settings every workflow shares.
 
 See the skill's [SKILL.md](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-campaign/SKILL.md) for the full merge contract.
 
@@ -94,79 +145,80 @@ See the skill's [SKILL.md](https://github.com/armelhbobdad/bmad-module-skill-for
 
 ## Quality Gates
 
-Campaign enforces two types of quality gates:
-
-The bar is **campaign-wide** — one set of thresholds applied to every skill, not a per-pipeline split:
+One quality bar applies to every skill in the campaign. It has three parts:
 
-- **Hard gate** (`zero-critical-high`) — zero critical or high-severity issues allowed. Any skill that fails the hard gate is flagged for manual intervention and blocks the campaign from proceeding past that skill.
-- **Soft target** (default 90%) — the score a skill should reach.
-- **Soft fallback** (default 80%) — the floor. A skill scoring at or above the fallback but below the target still proceeds; only a skill below the fallback is treated as a soft-gate miss.
+- **Hard gate** (`zero-critical-high`): a skill may have no critical or high-severity findings, such as a wrong or fabricated signature or a broken reference. The test step (`skf-test-skill`) fails a skill that has any. The campaign marks that skill failed and writes the reason to the decision log. Skills that depend on it wait at the dependency gate, and the other skills carry on. A missing export does not trip this gate: Test Skill rates it Medium, so it lowers the skill's score instead (see [Gap severities](/docs/verifying-a-skill.md#gap-severities)).
+- **Soft target** (default 90%): the score a skill should reach.
+- **Soft fallback** (default 80%): the floor. A skill that scores at or above the fallback but below the target still clears the gate, as `fallback`. A skill below the fallback is not exported.
 
-All three are tunable via [customization](#customization); the per-campaign brief and any directive `## Quality Overrides` still take precedence at runtime.
+You can change all three through [customization](#customization). The campaign brief and a directive's `## Quality Overrides` section take precedence when the campaign runs. A Tier A skill completes only on a Test Skill PASS, with `--threshold` set to its effective soft target. Export then enforces the gate: a skill that scores at or above the soft target is `pass`, one at or above the soft fallback is `fallback`, and anything else is not exported. A Tier B skill is classified by its skill-check score, and one without a score is not exported.
 
 ---
 
 ## Resume
 
-Campaign is designed around the assumption that context will die. File-based state (`_campaign-state.yaml`) survives context death, session timeouts, and machine restarts.
+Campaign expects the AI session to end before the campaign does, for example when it runs out of context. Its progress lives on disk in `_campaign-state.yaml`, so it survives a lost session, a timeout or a machine restart.
 
 When you resume:
 
-1. Ferris validates the state file against the campaign schema
+1. Ferris validates the state file against the campaign schema. When it fails, `campaign-state.py recover` copies the backup over it, but only when the backup validates
 2. Completed skills are skipped automatically
-3. The campaign picks up from the next incomplete skill in dependency order
+3. If a skill was in progress, the campaign returns to it (the Skill Loop for Tier A, the Tier B Batch for Tier B). Otherwise it starts the stage after the last stage that finished
 4. All cross-skill context (dependency graph, quality scores, provenance records) is restored from disk
 
-Use `--from=<skill>` to override the resume point if you need to re-process a specific skill.
+A campaign that already finished has nothing to resume: Ferris says so, and a headless resume prints the campaign's success line again. A Setup that stopped after writing the state but before the brief halts the resume with exit code 8 (`missing-brief`): run `campaign` and choose overwrite to start again.
+
+Use `--from=<skill>` to resume at a specific skill. If that skill already finished (completed, failed or skipped), Ferris asks whether to `[R]e-run` it, jump to the `[N]ext` unfinished skill, or `[H]alt`. Headless runs take `[N]ext`, so they never re-run a finished skill. An unknown skill name stops the campaign with exit code 2.
 
 ### Re-invocation and recovery
 
-- **`campaign` over an existing state** prompts resume-vs-overwrite. Choosing overwrite first archives the existing `_campaign-state.yaml` and `campaign-brief.yaml` to `archive/{name}-{timestamp}/` and logs it to the decision log, so a new campaign never silently clobbers an old one. In headless mode the default is **resume** — archive-and-overwrite happens only when `--brief`/`--manifest` explicitly seeds a new campaign.
-- **Corrupt primary, valid `.bak`** — resume auto-recovers by restoring the backup over the primary and logging the recovery; if the backup is also unusable it HALTs (exit 9, `corrupt-state`) reporting both errors.
-- **Primary behind the backup** — if the primary looks older than the `.bak` (a possible crash during the last write), Ferris offers `[R]ecover` from the backup or `[K]eep` the primary (the default; headless keeps the primary).
+- **Running `campaign` when a state file or its backup already exists** asks whether to resume or overwrite. Overwrite first runs `campaign-state.py archive`, which moves `_campaign-state.yaml`, its `.bak` and `campaign-brief.yaml` into `archive/<name>-<UTC timestamp>/`, and records this in the decision log, so a new campaign never silently replaces an old one. Setup itself refuses to overwrite a state file or a backup. Headless runs resume by default; they archive and overwrite only when `--brief` or `--manifest` seeds a new campaign.
+- **Damaged state file, good backup**: resume runs `campaign-state.py recover`, which copies the `.bak` over the state file only when the backup validates, and logs the recovery. If the backup is also unusable, the campaign stops with exit code 9 (`corrupt-state`) and reports both errors. Every write keeps a valid state in the backup and replaces the state file in one step, so a crash during a write never leaves a state file older than its backup.
 
 ---
 
 ## Expected Output
 
-A successful campaign produces:
+A finished campaign leaves:
 
-- **Individual skill packages** — one per dependency, each tested and exported
-- **Stack skill(s)** — capstone skills that integrate individual skills into a cohesive project context
-- **Campaign report** (`campaign-report.md`) — a post-campaign summary with per-skill quality scores, dependency graph visualization, and overall campaign metrics
-- **Headless envelope** (`SKF_CAMPAIGN_RESULT_JSON`) — a structured JSON result for automation consumers
+- **Individual skills**: one for each library that completed. The Export stage exports the ones that clear the quality gate; the others stay on disk and in the report.
+- **One capstone stack skill**: composed from the completed skills that clear the quality gate. The Export stage exports only the individual skills, so run `skf-export-skill` on the stack skill yourself when you want it packaged.
+- **Verification report and refined architecture**: from Verification and Refinement, when an architecture document was found.
+- **Campaign report** (`campaign-report.md`): the quality gate; a table of every skill with its tier, status, score, pin and workarounds; an Export Gate section with each completed skill's verdict, whether Export exported it or why its export failed, and the skills the gate kept from export; the lowest, highest and average scores; time per skill; and a section on failed or skipped skills.
+- **Decision log** (`_campaign-decision-log.md`): every decision made during the campaign.
+- **Headless result line** (`SKF_CAMPAIGN_RESULT_JSON`): printed in headless mode for scripts to read, as the run's last line. Besides the counts and the score of each skill, it carries `export_verdicts` (each completed skill's verdict at Export), `skills_excluded` (the completed skills the gate kept from export), `skills_exported` (the skills Export exported) and `export_failures` (each skill whose export failed, with its `halt_reason` and `exit_code`). The last two are null when the Export stage did not run. A failed export does not fail the campaign, which still ends with `status` `success`, so a CI job that needs every skill exported checks `export_failures`.
 
-The Export stage (stage 9) is the only non-auto-proceed stage. Ferris presents a summary of all skills to be written and waits for explicit approval before modifying any context files. In headless mode, the write-gate auto-resolves.
+The Export stage (stage 9) asks before it writes anything. It lists each completed skill with its verdict, names the skills it leaves out because they fall below the soft fallback or have no score, and waits for `[E]xport all` or `[C]ancel`. `[E]xport all` exports only the `pass` and `fallback` skills, each under the skill folder its build wrote: a Tier B skill under the name Quick Skill gave it, the library's name, even when you named the target differently. In headless mode it exports them without asking.
 
 ---
 
 ## Headless / Automation
 
-Campaign is a first-class headless front door for unattended, multi-session production. Add `--headless` / `-H` (or set `headless_mode: true` in preferences); `--brief`/`--manifest` imply it and seed targets non-interactively. In headless mode every confirmation gate auto-proceeds with its default action, each step emits a single-line JSON progress event to **stderr** on entry and exit (`{"stage":N,"name":"<slug>","status":"start|done"}`), and the terminal step emits the `SKF_CAMPAIGN_RESULT_JSON` envelope on stdout.
+Campaign can run unattended across several sessions. Add `--headless` / `-H`, or set `headless_mode: true` in `_bmad/_memory/forger-sidecar/preferences.yaml`. `--brief` and `--manifest` turn headless mode on for you and supply the targets: a seeded run is meant for CI, so it takes every default. To review the plan and the export, give the same file at the Setup question of an interactive run instead. In headless mode every question takes its default answer. Each step prints a one-line JSON progress event to **stderr** when it starts and when it ends (`{"stage":N,"name":"<slug>","status":"start|done"}`), or `{"stage":N,"name":"<slug>","status":"halt","exit":<code>}` when it stops on an error. At the end, the health check displays the `SKF_CAMPAIGN_RESULT_JSON` line as the run's last line. The line follows [`skf-campaign-result-envelope.v1.json`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/shared/scripts/schemas/skf-campaign-result-envelope.v1.json), and its success form carries `exit_code` 0 and a null `halt_reason`.
 
-- **Cancel affordance** — at any interactive gate the operator can type `cancel`, `exit`, or `:q` to leave cleanly; the campaign HALTs with exit code 12 (`user-cancelled`), logs the cancellation, and leaves state intact and resumable. The Export gate is the exception: its own `[C]ancel` exits 11 (`export-cancelled`).
-- **Exit codes** — every HARD HALT exits with a stable, documented code so automators branch on the failure class without grepping message text: `0` success, `3` invalid-state, `4` circular-deps, `5` invalid-pin, `6` inaccessible-repo, `7` dependency-deadlock, `8` missing-brief, `9` corrupt-state, `10` report-failure (degraded — the campaign still completes), `11` export-cancelled, `12` user-cancelled.
-- **Error envelope** — on any HARD HALT the `SKF_CAMPAIGN_RESULT_JSON` envelope is emitted on stderr in its error variant, carrying `status: "error"`, `exit_code`, the `phase` (step slug), and an `error` object with `code` and `message`.
+- **Cancel**: at any question between Setup and the Export gate, type `cancel`, `exit` or `:q` to stop cleanly. The campaign stops with exit code 12 (`user-cancelled`), logs the cancel, and leaves its state ready to resume. The Export gate is the exception: its own `[C]ancel` exits with code 11 (`export-cancelled`).
+- **Exit codes**: every stop on an error exits with a fixed code, so scripts can branch on the kind of failure without reading the message: `0` success, `2` invalid-input (for example no targets, a target Setup rejects, `gh` not available, or an unknown `--from` skill), `3` invalid-state, `4` circular-deps (a dependency cycle, an unknown dependency, or a Tier A skill that depends on a Tier B skill), `5` invalid-pin, `6` inaccessible-repo, `7` dependency-deadlock, `8` missing-brief, `9` corrupt-state, `10` report-failure (the campaign still completes; only the report is missing), `11` export-cancelled, `12` user-cancelled, `13` dependency-blocked (a `[H]alt` at a skill whose dependency has not completed; the campaign can resume).
+- **Error line**: when the campaign stops on an error, it prints the `SKF_CAMPAIGN_RESULT_JSON` line on stderr in its error form. The line carries every field the schema requires, with `status: "error"`, `exit_code` and `halt_reason`, the counts so far and the other fields empty or null, plus `phase` (the step where it stopped) and an `error` object holding `code` and `message`, which only a halt carries.
 
-The full exit-code table and envelope schema live in the skill's [SKILL.md](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-campaign/SKILL.md) under "Exit Codes" and "Result Contract on HARD HALT".
+The full exit-code table and result-line formats are in the skill's [campaign contracts](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-campaign/references/campaign-contracts.md), under "Exit Codes" and "Result Contract on HARD HALT".
 
 ---
 
 ## Timing
 
-Campaign duration scales with the number of declared dependencies — each Tier A skill runs a full `AN → BS → CS → TS` pipeline, and Tier B skills run in batch. A campaign is explicitly designed to **span multiple sessions**: file-based state means you can stop after any skill and resume later without losing progress. Factors that affect total time:
+Campaign time grows with the number of libraries. Each Tier A skill runs the full brief, compile and test chain, and Tier B skills run in one batch. A campaign is meant to **span several sessions**: its state is on disk, so you can stop after any skill and resume later without losing progress. What affects total time:
 
-- **Skill count and tier mix** — Tier A skills (a full pipeline each) dominate; Tier B batch processing is lighter per skill.
-- **Dependency depth** — deep graphs serialize more work (downstream skills wait on upstream APIs); wide, shallow graphs spread more naturally across sessions.
-- **Capstone breadth** — stack-skill composition (stage 6) grows with the number of constituent skills.
-- **Forge tier** — Deep-tier projects (with QMD and CCC) spend more time per skill on enrichment.
+- **Skill count and tier mix**: Tier A skills, each with a full pipeline, take most of the time. Tier B batch processing is lighter per skill.
+- **Dependency depth**: in a deep chain of dependencies, each skill waits for the ones before it. A wide, shallow graph splits more easily across sessions.
+- **Capstone breadth**: composing the stack skill (stage 6) takes longer the more skills it combines.
+- **Forge tier**: at Deep tier (ast-grep, GitHub CLI and QMD), each skill spends more time on QMD knowledge search.
 
-Plan a campaign as multi-session work rather than a single sitting — the resume design above exists precisely so that context death between skills is a non-event.
+Plan a campaign as work over several sessions, not one sitting. The campaign saves its state to disk as it goes, so losing the session between skills costs you nothing.
 
 ---
 
 ## Related
 
-- [Workflows](/docs/workflows.md) — pipeline mode mechanics, headless mode, circuit breakers
-- [forge-auto](/docs/forge-auto.md) — zero-ceremony single-skill creation (campaign orchestrates many of these)
-- [BMAD Synergy](/docs/bmad-synergy.md) — how campaign fits into BMAD Phase 3 as an orchestration layer
+- [Workflows](/docs/workflows.md): pipeline mode, headless mode and circuit breakers
+- [forge-auto](/docs/forge-auto.md): one command that builds and exports a single skill. A campaign runs a similar chain for each Tier A library and exports them together at the end
+- [BMAD Synergy](/docs/bmad-synergy.md): where campaign fits in BMAD Phase 3 (Solutioning)

package/docs/concepts.md

@@ -1,10 +1,12 @@
 ---
 title: Concepts
-description: Seven load-bearing terms for using and understanding Skill Forge — agent skills, provenance, confidence tiers, capability tiers, drift, version pinning, and the BMAD module.
+description: "Seven core terms for using and understanding Skill Forge: agent skills, provenance, confidence tiers, capability tiers, drift, version pinning, and the BMAD module."
 ---
 
 These are the seven terms you'll meet in every other page of this site. Each one names something SKF does differently from generic docs tooling. For the full mechanism behind them, see [Architecture](/docs/architecture.md) and [Skill Model](/docs/skill-model.md).
 
+Commands on this page look like `@Ferris AS`. Ferris is the SKF agent you talk to, and the two letters are the menu code of the workflow you want (`AS` is Audit Skill). See [Agents](/docs/agents.md) for the full menu.
+
 ---
 
 ## Agent Skills
@@ -13,21 +15,21 @@ An agent skill is an instruction file that tells an AI agent how to use your cod
 
 Skills follow the [agentskills.io](https://agentskills.io) open standard, so they work across Claude, Cursor, Copilot, and other AI tools.
 
-**Example:** A skill for [cognee](https://github.com/topoteretes/cognee) tells your agent: "The function is `cognee.search()`, its first parameters are `query_text`, `query_type`, `user`, `datasets`, and `dataset_ids`, and it's defined at `cognee/api/v1/search/search.py:L26` (v1.0.0, commit `3c048aa4`)." Every parameter and location is AST-verified from the actual source code.
+**Example:** A skill for [cognee](https://github.com/topoteretes/cognee) tells your agent: "The function is `cognee.search()`, its first parameters are `query_text`, `query_type`, `user`, `datasets`, and `dataset_ids`, and it's defined at `cognee/api/v1/search/search.py:L27` (v1.0.0, commit `3c048aa4`)." With ast-grep installed, SKF reads such a signature from the structure of the actual source code (its abstract syntax tree, or AST) and labels it T1; a signature it reads by eye instead is labeled T1-low (see [Confidence Tiers](#confidence-tiers-t1t1-lowt2t3)).
 
 ---
 
 ## Provenance
 
-Provenance means every instruction in a skill traces back to where it came from. For code, that's a file and line number. For documentation, it's a URL. For developer discourse, it's an issue or PR reference. **If SKF can't point to a source, it doesn't include the instruction.**
+Provenance means every instruction in a skill traces back to where it came from. For code, that's a file and line number. For documentation, it's a URL. For developer discourse such as issues, pull requests, and changelogs, it's the indexed document the instruction came from. **If SKF can't point to a source, it doesn't include the instruction.**
 
-**Examples** (from a [real generated skill](https://github.com/armelhbobdad/oh-my-skills)):
-- `[AST:cognee/api/v1/search/search.py:L26]` — extracted from source code via AST parsing (T1)
-- `[SRC:cognee/api/v1/session/__init__.py:L7]` — read from source code without AST verification (T1-low)
-- `[QMD:cognee-temporal:issues.md]` — surfaced from indexed developer discourse (T2)
-- `[EXT:docs.cognee.ai/getting-started/quickstart]` — sourced from external documentation (T3)
+**Examples** (the citation forms, with paths from the oms-cognee skill in [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills)):
+- `[AST:cognee/api/v1/search/search.py:L27]`: an ast-grep rule matched the definition in the source code (T1)
+- `[SRC:cognee/api/v1/add/add.py:L166]`: read from source code by eye, without an ast-grep match (T1-low)
+- `[QMD:oms-cognee-temporal:releases.md]`: found in indexed release notes and other developer discourse (T2)
+- `[EXT:https://docs.cognee.ai/getting-started/quickstart]`: taken from external documentation (T3)
 
-This is the opposite of how most AI tools work. They generate plausible-sounding content from training data; SKF only includes what it can cite. Quick-tier skills rely on best-effort source reading rather than AST verification — but even Quick skills cite their sources, and nothing ships without a citation.
+This is the opposite of how most AI tools work. They generate plausible-sounding content from training data; SKF only includes what it can cite. Skills compiled at the Quick tier rely on best-effort source reading rather than AST verification, but they still cite their sources, as `[SRC:file:Lnn]` (T1-low). Inside a compiled skill, the only content without a citation is clearly marked: sections you write yourself between `[MANUAL]` markers, and integrations labeled `[inferred from shared domain]` in a stack skill assembled from existing skills. Quick Skill (`@Ferris QS`) is the exception: it writes a fast, best-effort draft from the source and README, with no citation on each instruction and no provenance map.
 
 ---
 
@@ -35,27 +37,29 @@ This is the opposite of how most AI tools work. They generate plausible-sounding
 
 Each piece of information in a skill carries a confidence level based on where it came from:
 
-- **T1 — AST extraction:** Pulled directly from source code via AST parsing. The function signature exists in the code at the pinned commit. Cited as `[AST:file:Lnn]`.
-- **T1-low — Source reading:** Found by reading source files directly without AST parsing. The location is correct but the type signature may be inferred. Produced by Quick tier and by Forge/Forge+/Deep when ast-grep cannot parse a specific file. Cited as `[SRC:file:Lnn]`.
-- **T2 — Evidence (Deep tier only):** Surfaced by QMD knowledge search from issues, PRs, changelogs, or documentation within the repository. Available only when QMD is installed (Deep tier). Reliable context, but less definitive than source code itself. Cited as `[QMD:collection:document]`. T2 has two temporal subtypes:
-  - **T2-past** — Historical context (closed issues, merged PRs, changelogs) explaining API design decisions. Surfaces in the skill's `references/` directory.
-  - **T2-future** — Forward-looking context (open PRs, deprecation warnings, RFCs) about upcoming changes. Surfaces in SKILL.md Section 4b (Migration & Deprecation Warnings) and `references/`.
-- **T3 — External:** Pulled from external documentation or websites. Treated with caution and clearly marked. Cited as `[EXT:url]`.
+- **T1 (AST extraction):** An ast-grep rule matched the export in the source code, so its signature comes from the code's structure at the pinned commit. Cited as `[AST:file:Lnn]`.
+- **T1-low (source reading):** Found by reading source files directly without an ast-grep match. The location is correct but the type signature may be inferred. Produced by Quick tier, and by Forge, Forge+, or Deep when ast-grep cannot parse a specific file or when an export is read directly while ast-grep works. Cited as `[SRC:file:Lnn]`.
+- **T2 (evidence, Deep tier only):** Found by QMD, a local search engine that SKF uses to index the project's issues, pull requests, changelogs, and fetched documentation. Reliable context, but less definitive than source code itself. Cited as `[QMD:collection:document]`. T2 has two temporal subtypes:
+  - **T2-past:** Historical context (closed issues, merged PRs, changelogs) explaining API design decisions. Surfaces in the skill's `references/` directory.
+  - **T2-future:** Forward-looking context (open PRs, deprecation warnings, RFCs) about upcoming changes. Surfaces in the Migration & Deprecation Warnings section of SKILL.md, which appears only when there is such context, and in `references/`.
+- **T3 (external):** Pulled from external documentation or websites. Treated with caution and clearly marked. Cited as `[EXT:url]`.
+
+**The label follows the tool, not the tier.** SKF labels each export by the tool that actually read it: an ast-grep match is T1 at any tier, and an export read by eye is T1-low, even in a Deep-tier skill. Before SKF 3.0.0 the label followed the forge tier, so a skill built at Forge or above could claim T1 for an export nothing parsed. A skill you build or update now can therefore show fewer T1 claims and more T1-low ones than the same skill built by an earlier version, with nothing less extracted. Audit Skill lists such label changes in their own table, "Provenance label differences (not drift)", and does not count them as drift.
 
-Forge+ semantic discovery (via cocoindex-code) does not introduce a new confidence tier — it influences *which* files are extracted, not *how* they're cited. Discovered files are verified by ast-grep (T1) or source reading (T1-low).
+Forge+ semantic discovery (via cocoindex-code) does not introduce a new confidence tier. It changes the order in which a step reads files one at a time, not *how* they're cited. Every export is still labeled by the tool that read it: ast-grep (T1) or source reading (T1-low).
 
 ---
 
 ## Capability Tiers (Quick/Forge/Forge+/Deep)
 
-Your capability tier depends on which tools you have installed. Each tier builds on the previous one:
+Your capability tier depends on which tools are installed and working on your machine. Forge, Forge+, and Deep all need ast-grep, and Forge+ and Deep each add different tools on top of it. Deep does not need cocoindex-code, so it does not build on Forge+:
 
-- **Quick** — No tools required. SKF reads source files and builds best-effort skills. Works in under a minute. GitHub CLI used when available.
-- **Forge** — Adds [ast-grep](https://ast-grep.github.io). SKF uses AST parsing to verify instructions against the actual code structure.
-- **Forge+** — Adds [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code). SKF uses semantic code search to discover relevant source regions before AST extraction, improving coverage on large codebases.
-- **Deep** — Full pipeline: requires [ast-grep](https://ast-grep.github.io) + [GitHub CLI](https://cli.github.com) + [QMD](https://github.com/tobi/qmd) (all three). SKF indexes knowledge for semantic search and performs GitHub repository exploration. Skills get enriched with historical context, deprecation warnings, and cross-reference intelligence. CCC (cocoindex-code) enhances Deep tier when installed — ast-grep + gh + qmd + ccc gives maximum capability.
+- **Quick:** No extra tools required. SKF reads source files and builds best-effort skills. Works in under a minute. GitHub CLI used when available.
+- **Forge:** Adds [ast-grep](https://ast-grep.github.io). SKF uses AST parsing to verify instructions against the actual code structure: each export an ast-grep rule matches is T1, and one it cannot match is read by eye and stays T1-low.
+- **Forge+:** Adds [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code). SKF searches the code by meaning and ranks the files, so a step that reads files one at a time reads the most relevant first, which helps most on large codebases. The ast-grep recipe runner reads every file in scope either way.
+- **Deep:** The full pipeline. Needs [ast-grep](https://ast-grep.github.io), the [GitHub CLI](https://cli.github.com), and [QMD](https://github.com/tobi/qmd), all three, with QMD running. SKF indexes the project's issues, pull requests, changelogs, and docs so it can search them, and it explores the GitHub repository. Skills gain historical context and deprecation warnings. cocoindex-code is optional here; adding it to Deep also brings its semantic code search, which gives the most capability.
 
-You don't need all tools to start. SKF detects what you have and sets your tier automatically. See [Skill Model → Progressive Capability Model](/docs/skill-model.md#progressive-capability-model) for the full technical treatment.
+You don't need all tools to start. When you run Setup Forge (`@Ferris SF`), SKF checks which tools work and sets your tier from that. If you install a tool later, run `@Ferris SF` again to update your tier. See [Skill Model → Progressive Capability Model](/docs/skill-model.md#progressive-capability-model) for the full technical treatment.
 
 ---
 
@@ -63,9 +67,11 @@ You don't need all tools to start. SKF detects what you have and sets your tier
 
 Drift happens when the source code changes but the skill instructions haven't been updated to match. A skill might still reference a function that was renamed, removed, or had its signature changed upstream.
 
-SKF detects drift by comparing the skill's recorded provenance against the current code. The `audit-skill` workflow (`@Ferris AS`) scans for these mismatches — for both individual skills and stack skills. Stack skills track per-library provenance and, in compose-mode, constituent freshness via metadata hash comparison.
+SKF detects drift by comparing the skill's recorded provenance against the current code. The Audit Skill workflow (`@Ferris AS`) scans for these mismatches in both single-library skills and stack skills (one skill that covers several libraries a project uses together). A stack built from source code is checked library by library. A stack assembled from skills you already have is checked for member skills that changed after it was assembled.
+
+Audit Skill also checks the documentation pages a skill tracked when it was built, and reports which of them changed upstream since then. This check is informational and does not change the drift score. Neither does a provenance label that changed only because a different tool read the export (T1 to T1-low, or back): Audit Skill lists it under "Provenance label differences (not drift)".
 
-**Example:** Your skill says `createUser(name: string)` but the function was renamed to `registerUser(name: string, email: string)` in the last release. That's drift. For stack skills, constituent drift occurs when an individual skill is updated but the stack hasn't been re-composed to reflect the changes.
+**Example:** Your skill says `createUser(name: string)` but the function was renamed to `registerUser(name: string, email: string)` in the last release. That's drift. For a stack assembled from existing skills, constituent drift means one of its member skills was updated after the stack was assembled, and the stack hasn't been rebuilt to pick up the change.
 
 ---
 
@@ -73,14 +79,14 @@ SKF detects drift by comparing the skill's recorded provenance against the curre
 
 Every skill records the exact version (or commit) of the source code it was built from. This means you always know which version of the library the instructions apply to.
 
-By default, the version is auto-detected from the source (package.json, pyproject.toml, etc.). You can also target a specific version — either by specifying it during `@Ferris BS` (brief-skill) or by appending `@version` to a quick skill command (`@Ferris QS cognee@1.0.0`). This is especially useful for docs-only skills where no source code is available for auto-detection. When targeting a specific version on a remote repository, SKF resolves the matching git tag and clones from it — so the extracted API signatures actually reflect the target version's code, not just the label applied to whatever happens to be on the default branch.
+By default, the version is auto-detected from the source (package.json, pyproject.toml, etc.). You can also target a specific version, either by giving it during `@Ferris BS` (Brief Skill) or by adding `@version` to a Quick Skill command (`@Ferris QS cognee@1.0.0`). This is especially useful for docs-only skills, where there is no source code to detect a version from. When you target a version on a remote repository, SKF finds the matching git tag and clones from it. That way the extracted API signatures come from that version's code, not from whatever is on the default branch with a label added. If no tag matches, Quick Skill stops and lists the tags it found, while Create Skill warns you and falls back to the default branch.
 
-When the source updates, you can re-run `@Ferris US` (update-skill) to regenerate the skill for the new version while preserving any manual additions you've made.
+When the source updates, re-run `@Ferris US` (Update Skill) to regenerate the skill. SKF writes the result as a new version and leaves the old one in place. Anything you wrote between `<!-- [MANUAL:name] -->` and `<!-- [/MANUAL:name] -->` markers is carried over; edits made anywhere else are not protected and can be overwritten. Update Skill follows the ref the skill was built from, so a skill built from a branch picks up that branch's new commits. To move a skill built from a release tag to a newer release, run `@Ferris US <name> --target-ref <tag>`.
 
 ---
 
 ## BMAD Module
 
-SKF is a plugin (called a "module") for [BMAD Method](https://docs.bmad-method.org/), a framework for running structured AI workflows. You don't need to know BMAD to use SKF — the standalone installer sets everything up.
+SKF is a plugin (called a "module") for [BMAD Method](https://docs.bmad-method.org/), a framework for running structured AI workflows. You don't need to know BMAD to use SKF. The standalone installer (`npx bmad-module-skill-forge install`) sets everything up.
 
-If you already use BMAD, see [BMAD Synergy](/docs/bmad-synergy.md) for how SKF workflows pair with BMM phases and optional modules like TEA, BMB, and GDS.
+If you already use BMAD, see [BMAD Synergy](/docs/bmad-synergy.md) for how SKF workflows fit into BMAD's main four-phase workflow (BMM) and optional modules such as TEA (Test Architect), BMB (BMAD Builder), and GDS (Game Dev Studio).