bmad-module-skill-forge 1.9.0 → 2.0.0

package/src/skf-brief-skill/assets/skill-brief-schema.md

@@ -19,7 +19,7 @@
 | Field              | Type   | Constraint                                       | Description                                                                                                                                                                                                                    |
 |--------------------|--------|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | source_type        | string | `source` or `docs-only`                          | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required                                                                                                                                                |
-| doc_urls           | array  | `{url, label}` objects                           | Documentation URLs for T3 content. Required when `source_type: "docs-only"`                                                                                                                                                    |
+| doc_urls           | array  | `{url, label, source?}` objects                  | Documentation URLs for T3 content. Required when `source_type: "docs-only"`. Optional `source` provenance enum: `language-registry` (registry-guaranteed corpus) \| `readme-detection` \| `homepage` \| `pages-api` \| `docs-folder` |
 | `scripts_intent`   | string | `detect` / `none` / free-text                    | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
 | `assets_intent`    | string | `detect` / `none` / free-text                    | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/").        |
 | `target_version`   | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | User-specified target version. When present, overrides auto-detection and becomes the skill's version. Recommended for docs-only skills where auto-detection is unavailable.                                                   |

package/src/skf-brief-skill/references/analyze-target.md

@@ -10,6 +10,9 @@ detectWorkspacesProbeOrder:
 detectLanguageProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-language.py'
   - '{project-root}/src/shared/scripts/skf-detect-language.py'
+emitBriefEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -56,10 +59,10 @@ To analyze the target repository by resolving its location, reading its structur
 
 **On API failure (non-200 from `gh api`):**
 
-Distinguish the failure class before reporting:
-- Auto-run `gh auth status` and capture its output. If it reports an unauthenticated state or expired token: HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** GitHub CLI is not authenticated. `gh auth status` says: `{captured output}`. Run `gh auth login` and retry."
-- If `gh auth status` reports authenticated but the call still failed (404/403): HALT (exit code 3, `halt_reason: "target-inaccessible"`) — "**Error:** Cannot access repository at `{url}`. The CLI is authenticated but the API returned `{status}`. Check the URL and that the account has access to private repositories if applicable."
-- If `gh auth status` itself fails to run (binary missing): HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** `gh` CLI not found on PATH. Install it from <https://cli.github.com> and re-run."
+Distinguish the failure class before reporting. In headless mode, every branch below emits the error envelope per **step 5 §4b** with its stated `halt_reason` before the HALT (pass the resolved `{skill_name}`, or the `"unknown"` placeholder documented in §4b if it is not yet set):
+- Auto-run `gh auth status` and capture its output. If it reports an unauthenticated state or expired token: emit the error envelope per **step 5 §4b** with `halt_reason: "gh-auth-failed"`, then HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** GitHub CLI is not authenticated. `gh auth status` says: `{captured output}`. Run `gh auth login` and retry."
+- If `gh auth status` reports authenticated but the call still failed (404/403): emit the error envelope per **step 5 §4b** with `halt_reason: "target-inaccessible"`, then HALT (exit code 3, `halt_reason: "target-inaccessible"`) — "**Error:** Cannot access repository at `{url}`. The CLI is authenticated but the API returned `{status}`. Check the URL and that the account has access to private repositories if applicable."
+- If `gh auth status` itself fails to run (binary missing): emit the error envelope per **step 5 §4b** with `halt_reason: "gh-auth-failed"`, then HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** `gh` CLI not found on PATH. Install it from <https://cli.github.com> and re-run."
 
 **For local paths:**
 - Verify the directory exists

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

@@ -1,7 +1,6 @@
 ---
 nextStepFile: 'write-brief.md'
 reviseStepFile: 'scope-definition.md'
-briefSchemaFile: 'assets/skill-brief-schema.md'
 advancedElicitationSkill: '/bmad-advanced-elicitation'
 partyModeSkill: '/bmad-party-mode'
 ---

package/src/skf-brief-skill/references/gather-intent.md

@@ -2,7 +2,6 @@
 nextStepFile: 'analyze-target.md'
 ratifyTargetFile: 'confirm-brief.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
-descriptionVoiceExamplesFile: 'assets/description-voice-examples.md'
 headlessArgsFile: 'references/headless-args.md'
 headlessSourceAuthorityDetectionFile: 'references/headless-source-authority-detection.md'
 portfolioSimilarityCheckFile: 'references/portfolio-similarity-check.md'
@@ -61,6 +60,7 @@ Attempt to load `{forgeTierFile}`:
 
 **If not found:**
 - "**Cannot proceed.** forge-tier.yaml not found at `{forgeTierFile}`. Run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
+- In headless mode, emit the error envelope per **step 5 §4b** with `halt_reason: "forge-tier-missing"` (`skill_name` is not yet resolved here — use the `"unknown"` placeholder convention documented in §4b).
 - HALT (exit code 3, `halt_reason: "forge-tier-missing"`) — do not proceed.
 
 ### 1b. Auto Mode Check
@@ -106,8 +106,12 @@ This section has four sub-flows. Execute exactly one branch — 3.1a *or* 3.2 *o
 
 #### 3.1 Collect target
 
+**Open-floor opening.** Lead with an open invitation so an expert can state everything in one breath rather than being walked through seven discrete prompts — costs almost nothing token-wise and sharply improves the conversational feel of this, the most question-heavy mode. A first-timer who pastes only a bare URL still gets the full guided sequence below, unchanged.
+
 "**What repository or documentation do you want to create a skill for?**
 
+Tell me everything you have — the repo or docs, what you want to skill and why, any scope or version thoughts. Or just paste a URL and we'll go from there.
+
 Provide one of:
 - A **GitHub URL** (e.g., `https://github.com/org/repo`)
 - A **local path** (e.g., `/path/to/project`)
@@ -118,7 +122,7 @@ Or type `cancel` / `exit` / `[X]` to leave without writing anything.
 
 **Target:**"
 
-Wait for user response. Branch on the response:
+Wait for user response. **Parse the response for any of the fields the later sections collect** — `target_version` (§3b), intent (§4), scope hints (§5), source authority (§3.3), a proposed name (§6) — and pre-fill every field the user covered, holding them in workflow context. Sections §3b/§4/§5/§6/§7b then **acknowledge a pre-filled field instead of re-asking** ("I noted you're targeting v4.0.0"), and prompt only for the gaps. An expert who stated it all collapses to the §3.1 target branch plus the §7b description confirmation; a bare URL falls through to the full sequence. Then branch on the response for the target itself:
 
 - Empty input, `cancel`, `exit`, `[X]`, `q`, or `:q` → Display `"Cancelled — no brief was written."` and HALT (exit code 6, `halt_reason: "user-cancelled"`). Cancellation here is non-destructive — no files have been written yet by step 1. Headless mode never reaches this branch (the GATE in §8 short-circuits the interactive sub-flows).
 - Path that resolves to an existing `skill-brief.yaml` (file path ending in `skill-brief.yaml` that exists, OR a directory containing a `skill-brief.yaml`) → §3.1a
@@ -267,6 +271,8 @@ Take your time — the more context you share, the better the brief."
 
 Wait for user response. Ask follow-up questions if intent is unclear.
 
+**Capture, don't interrupt.** If the user volunteers an out-of-scope aside while answering — "the v3 API is totally different", "we're deprecating the auth module next quarter" — do not redirect the conversation to chase it. Silently note it as a candidate `scope.notes` line (carried forward into the brief's `scope.notes` at step 3) and continue the current prompt. These unprompted asides are often the most useful scoping signal; the cost of losing them when the conversation moves on is higher than the cost of one stored line.
+
 ### 5. Capture Scope Hints
 
 If the user mentioned scope preferences in their intent response, acknowledge them:

package/src/skf-brief-skill/references/scope-definition.md

@@ -1,6 +1,5 @@
 ---
 nextStepFile: 'confirm-brief.md'
-scopeTemplatesFile: 'assets/scope-templates.md'
 recommendScopeTypeProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-recommend-scope-type.py'
   - '{project-root}/src/shared/scripts/skf-recommend-scope-type.py'
@@ -120,6 +119,8 @@ How broadly should this skill cover the library?
 
 Press Enter to accept the recommendation, or pick a different letter."
 
+**First-timer reassurance (interactive only, never-briefed user — the §4 first-timer rail fired in step 01).** Append one line so the harder scope-type call doesn't stall a first-timer: "The recommended type is almost always right — accept it and re-scope from step 4 if the analysis surprises you." Repeat users and headless skip this line.
+
 Wait for user selection. Empty input or just Enter accepts the recommendation; any of the five letters overrides.
 
 ### 3. Define Boundaries Based on Selection

package/src/skf-brief-skill/references/step-auto-brief.md

@@ -9,7 +9,12 @@ writeSkillBriefProbeOrder:
 emitBriefEnvelopeProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
   - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
-detectDocsScript: 'src/shared/scripts/skf-detect-docs.py'
+mergeDocUrlsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-merge-doc-urls.py'
+  - '{project-root}/src/shared/scripts/skf-merge-doc-urls.py'
+detectDocsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-docs.py'
+  - '{project-root}/src/shared/scripts/skf-detect-docs.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -69,10 +74,12 @@ Extract from the parsed brief:
 
 ### 2. Run Doc Detection
 
+**Resolve `{detectDocsHelper}`** from `{detectDocsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 Invoke doc detection to discover documentation URLs for the source repo:
 
 ```bash
-uv run python {project-root}/{detectDocsScript} --repo-url {source_repo}
+uv run {detectDocsHelper} --repo-url {source_repo}
 ```
 
 `--repo-url` is always required (the script uses it for GitHub API calls). If a local clone is also available at `{local_clone_path}`, add `--local-path {local_clone_path}` to enable docs-folder scanning in addition to API-based detection.
@@ -97,8 +104,18 @@ For each detected doc entry, create a brief `doc_urls` entry:
     - `"readme_link"` → `"README Link"`
     - `"pages_api"` → `"GitHub Pages"`
     - `"docs_folder"` → `"Docs Folder"`
+- `source` ← coarse provenance derived from `detected_via` (per the `skill-brief.v1.json` `doc_urls[].source` enum): `homepageUrl` → `homepage`, `readme_link` → `readme-detection`, `pages_api` → `pages-api`, `docs_folder` → `docs-folder`. This marks the entry as opportunistically detected, distinct from a registry-guaranteed corpus.
+
+**Merge via the canonical helper.** Resolve `{mergeDocUrlsHelper}` from `{mergeDocUrlsProbeOrder}` (first existing path wins; HALT if neither exists). Pass the upstream brief's `doc_urls` as `existing` and the entries just mapped above as `detected`:
+
+```bash
+echo '{"scope_type": "{scope_type}", "existing": {upstream brief doc_urls JSON, [] if none}, "detected": {mapped detected entries JSON}}' \
+  | uv run {mergeDocUrlsHelper}
+```
+
+The helper returns `{"doc_urls": [...], "suppressed": [...]}`. It deduplicates by **normalized** URL (lowercase host, strip a trailing `/index.html` and any trailing `/`), so a seeded `…/book/` and a README's `…/book/index.html` collapse to one entry; existing/corpora-seeded entries always win and keep their `source: language-registry`, so the registry-vs-detected distinction survives the merge. For a **whole-language reference** (`scope_type == "full-library"` AND ≥1 `existing` entry has `source: language-registry`) it additionally suppresses README noise on a corpus host: non-corpus path segments (`/whatsnew/`, `/contribute`, `/wiki/`) and non-primary-locale duplicates of a kept page (`/ja/master/` when `/en/master/` is kept). Ordinary skills (any other `scope_type`, or no registry corpora) pass through with dedup only — no suppression. Use the returned `doc_urls` as the brief's merged list.
 
-If the upstream brief already has `doc_urls`, merge the detected docs with the existing entries (deduplicate by URL — existing entries take precedence).
+**Log suppressed entries.** When `suppressed` is non-empty, log one line per entry — `"info: suppressed {url} ({reason})"` — so the operator can see what the whole-language noise filter dropped (never drop silently). The N==0 DEGRADED case (a whole-language repo whose registry returned no corpora) carries no `language-registry` entry, so suppression stays inactive and its README docs are kept — this is intentional (there is no canonical corpus host to filter against).
 
 ### 4. Validate Enriched Brief
 
@@ -123,7 +140,7 @@ Assemble the enriched brief context as a flat JSON object following the write-br
   "scope_rationale":  null,
   "scope_tier_a_include": null,
   "scope_amendments":     null,
-  "doc_urls":         [{"url": "...", "label": "..."}],
+  "doc_urls":         [{"url": "...", "label": "...", "source": "..."}],
   "scripts_intent":   "{scripts_intent or null}",
   "assets_intent":    "{assets_intent or null}",
   "source_authority": "{source_authority or null}",

package/src/skf-brief-skill/references/step-auto-validate.md

@@ -75,11 +75,11 @@ Scope:        {scope_type} ({N} include, {M} exclude patterns)
 Docs:         {doc_urls count} sources detected | "None detected"
 Version:      {version}
 Forge Tier:   {forge_tier}
-Quality:      90% target (deepwiki pipeline)
+Pipeline:     forge-auto ({forge_tier} tier)
 Description:  "{description}"
 ```
 
-Where `{N}` is the count of `scope_include` patterns and `{M}` is the count of `scope_exclude` patterns. If `doc_urls` is null or empty, display "None detected".
+Where `{N}` is the count of `scope_include` patterns and `{M}` is the count of `scope_exclude` patterns. If `doc_urls` is null or empty, display "None detected". The `Pipeline` line names the auto pipeline and the resolved `{forge_tier}` — it carries no numeric quality target, which would be an unverified guarantee an automator might parse as fact.
 
 ### 3. Validation Gate
 

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

@@ -1,5 +1,4 @@
 ---
-briefSchemaFile: 'assets/skill-brief-schema.md'
 versionResolutionFile: 'references/version-resolution.md'
 qmdRegistrationFile: 'references/qmd-collection-registration.md'
 nextStepFile: 'health-check.md'
@@ -98,7 +97,7 @@ Assemble the brief context as a **flat** JSON object — every approved value is
   "scope_rationale":  null | {"recommended":"...","chosen":"...","accepted_recommendation":true|false,"heuristic":"...","reason":"...","recorded":"YYYY-MM-DD"},
   "scope_tier_a_include": null | ["{tier-A authoring-surface patterns — from step 03 §3c capture, or hydrated on a ratify run}"],
   "scope_amendments":     null | [{"path":"...","action":"...","reason":"...","date":"YYYY-MM-DD","workflow":"..."}],
-  "doc_urls":         null | [{"url": "...", "label": "..."}],
+  "doc_urls":         null | [{"url": "...", "label": "...", "source": "{optional: language-registry|readme-detection|homepage|pages-api|docs-folder}"}],
   "scripts_intent":   null | "{detect|none|free-text}",
   "assets_intent":    null | "{detect|none|free-text}",
   "source_authority": null | "{official|community|internal}",
@@ -163,7 +162,7 @@ The script derives `exit_code` deterministically from `halt_reason` (null→0, i
 
 The script enforces the success/error halt_reason invariant (success requires null halt_reason; error requires non-null). The `user-cancelled` halt_reason is accepted for completeness (interactive `[X]` Cancel sites in step 1/03/04) but never appears on the headless code path.
 
-Invocation sites (each pointed at this block, not duplicated): step 1 §1 (write-failed pre-resolution), step 1 §8 (input-missing/input-invalid GATE), step 5 §2b (overwrite-cancelled), step 5 §3 (input-invalid/write-failed from script). Step-01 §1 forge-tier-missing and step 2 §1 (target-inaccessible/gh-auth-failed) currently HALT without emitting an envelope — pre-existing gaps tracked separately, not addressed by this canonicalization.
+Invocation sites (each pointed at this block, not duplicated): step 1 §1 (write-failed pre-resolution; forge-tier-missing), step 1 §8 (input-missing/input-invalid GATE), step 2 §1 (target-inaccessible/gh-auth-failed), step 5 §2b (overwrite-cancelled), step 5 §3 (input-invalid/write-failed from script). The step 1 §1 forge-tier-missing and step 2 §1 target-inaccessible/gh-auth-failed sites emit through this block too, so every headless HALT class surfaces a `SKF_BRIEF_RESULT_JSON` envelope — there are no envelope-silent failure classes.
 
 When `{headless_mode}` is false, skip this section silently — no envelope is emitted.
 

package/src/skf-campaign/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: skf-campaign
+description: Campaign orchestration — multi-library skill production with dependency tracking, file-based state, and resume. Use when the user asks to "run a campaign" or "orchestrate skills."
+---
+
+# Campaign
+
+## Overview
+
+Orchestrates the production of 15+ skills across multiple sessions by driving them through the full SKF pipeline (brief, generate, compile, test, export) in dependency order. Campaign sits at the top of the pipeline ladder — it does not produce skill artifacts directly but sequences the workflows that do. File-based state (`_campaign-state.yaml`) survives context death, enabling resume from any point.
+
+## Conventions
+
+- Bare paths (e.g. `references/step-01-setup.md`) resolve from the skill root.
+- `references/` holds step files chained by stage number, plus the directive contract at `references/campaign-directive-spec.md` (the canonical spec for `_campaign-directive.md`); `templates/` holds workflow-loaded templates; `scripts/` and `assets/` hold deterministic helpers and the state schema.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## Role
+
+You are a campaign orchestrator operating in Ferris's Management mode. You sequence workflows, track per-skill state, enforce quality gates, and ensure every skill reaches its target tier — while the individual pipeline workflows handle the actual artifact production.
+
+## On Activation
+
+Run these steps once, in order, before dispatching to Mode Routing.
+
+1. **Load config.** Read `{project-root}/_bmad/skf/config.yaml` and `{sidecar_path}/preferences.yaml` in one batched message (independent files). From config resolve `project_name`, `user_name`, `communication_language`, `document_output_language`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`. From preferences resolve `headless_mode` (default false). If the config file is missing, fall back to `forge_data_folder = forge-data`.
+
+2. **Resolve `{headless_mode}`** — true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `preferences.yaml`. Default: false.
+
+3. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow
+   ```
+
+   The script merges three layers (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If it fails or is missing, fall back to `{skill-root}/customize.toml` directly. Apply the fallback for each scalar now so step files never repeat the conditional, and stash as workflow-context variables:
+
+   - `{campaignWorkspacePath}` ← `workflow.campaign_workspace_path` if non-empty, else `{forge_data_folder}/_campaign`
+   - `{qualityGateHard}` / `{qualityGateSoftTarget}` / `{qualityGateSoftFallback}` ← the `quality_gate_*` scalars (defaults `zero-critical-high` / `90` / `80`)
+   - `{reportTemplatePath}` ← `workflow.report_template_path` if non-empty, else `templates/campaign-report-template.md`
+   - `{kickoffTemplatePath}` ← `workflow.kickoff_template_path` if non-empty, else `templates/kickoff-template.md`
+   - `{briefTemplatePath}` ← `workflow.brief_template_path` if non-empty, else `templates/campaign-brief-template.yaml`
+   - `{onComplete}` ← `workflow.on_complete` (empty = no-op)
+
+   Load `workflow.persistent_facts` (literal sentences and `file:` references, globs expanded) and keep them in mind for the whole campaign — they are injected into every per-skill kickoff. Run any `activation_steps_prepend` before step 1 and any `activation_steps_append` after this step.
+
+   Every step file resolves its frontmatter path vars (`stateFile`, `backupFile`, …) under `{campaignWorkspacePath}` — overriding `campaign_workspace_path` relocates the whole campaign workspace without editing a single step.
+
+4. **Parse CLI overrides** into the workflow context:
+
+   | Flag | Effect |
+   | --- | --- |
+   | `--headless` / `-H` | Force `{headless_mode} = true` (see step 2). |
+   | `--brief <file>` | Seed step-01 targets from a `campaign-brief.yaml` instead of interactive prompts. Implies `--headless`. |
+   | `--manifest <file>` | Seed step-01 targets from a plain-text `name,repo_url,tier,pin` manifest. Implies `--headless`. |
+   | `--from <skill>` | Resume override — see Mode Routing. |
+
+   If `--brief` or `--manifest` is set, force `{headless_mode} = true` (log "headless: coerced by --brief/--manifest" if it was false).
+
+   **`--manifest` format:** one target per line, comma-separated `name,repo_url,tier,pin` (omit `pin` or leave it empty for latest); add a trailing `;dep1,dep2` segment for `depends_on`. Blank lines and `#` comments are skipped. If any line fails to parse, HALT in step-01 listing the offending line numbers rather than silently dropping targets — a partial target set is never run.
+
+5. **Dispatch** per Mode Routing below.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- State-first — write state to disk before chaining to the next step or workflow
+- Read-backup-modify-write for all state mutations (see State Contract below)
+- Validate `_campaign-state.yaml` on every load by running `uv run scripts/campaign-validate-state.py --state-file {stateFile}` and HALT (exit code 3, `invalid-state`) on non-zero — never hand-validate the schema
+- Zero memory dependency (NFR-2) — campaign state is 100% recoverable from disk; never rely on conversation context for progress tracking
+- Treat a missing or unparseable `SKF_*_RESULT_JSON` envelope from any sub-skill as a sub-skill failure; never write partial state from an unparsed envelope
+- Append a one-line entry to the campaign decision log (`{campaignWorkspacePath}/_campaign-decision-log.md`, append-only) at every operator decision or auto-decision (skip/force, architecture-doc skip, export cancel/proceed, campaign overwrite, `.bak` recovery, user-cancel) so rationale survives compaction and resume
+- **Universal cancel affordance** — at any interactive gate the operator may type `cancel`, `exit`, or `:q` to leave cleanly. HARD HALT with **exit code 12 (`user-cancelled`)**, log the cancellation to the decision log, and leave state intact and resumable. This gives the operator a documented way out at every prompt between Setup and the Export gate. **The Export gate is the one exception:** it has its own `[C]ancel` with exit code 11 (`export-cancelled`), which remains canonical there — do not also emit 12 at the export gate, so an automator's exit-code branch stays deterministic. These keywords are recognized only as a response *to an interactive prompt*; a skill or campaign named `cancel`/`exit` supplied as data is never treated as a cancel.
+- Always communicate in `{communication_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- If `{headless_mode}` is true, emit a single-line JSON progress event to **stderr** at each step's entry and exit so schedulers stream live progress instead of post-mortem-parsing the final envelope:
+  - entry: `{"stage":N,"name":"<slug>","status":"start"}`
+  - 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 stage number (0–10, per the Stages table) 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.
+
+## Stages
+
+| # | Step | File | Auto-proceed |
+|---|------|------|--------------|
+| 0 | Setup | references/step-01-setup.md | Yes |
+| 1 | Strategy | references/step-02-strategy.md | Yes |
+| 2 | Pin Validation | references/step-03-pins.md | Yes |
+| 3 | Provenance | references/step-04-provenance.md | Yes |
+| 4 | Skill Loop | references/step-05-skill-loop.md | Yes |
+| 5 | Tier B Batch | references/step-06-batch.md | Yes |
+| 6 | Capstone | references/step-07-capstone.md | Yes |
+| 7 | Verification | references/step-08-verify.md | Yes |
+| 8 | Refinement | references/step-09-refine.md | Yes |
+| 9 | Export | references/step-10-export.md | No (write-gate HALT) |
+| 10 | Maintenance | references/step-11-maintenance.md | Yes |
+
+**Stage numbering:** step files are 1-indexed (`step-01` … `step-11`); `campaign.current_stage` in state is 0-indexed, so step-`NN` runs stage `NN − 1` (e.g. step-01 = stage 0, step-11 = stage 10). The Resume Routing table in `references/step-resume.md` maps a resolved stage number to its step file; because `current_stage` records the highest *completed* stage, resume without an active skill advances to `current_stage + 1` (the stage that still needs to run) before consulting the table.
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | `campaign` to start a new campaign; `campaign resume [--from=<skill>]` to resume from last active or specified skill; `campaign status` for a read-only progress summary |
+| **Overrides** | `--headless` / `-H`, `--brief <file>`, `--manifest <file>`, `--from <skill>` — see On Activation step 4 |
+| **Gates** | Step 9 (Export): write-gate HALT — requires explicit user approval before writing exported skills to disk |
+| **Outputs** | `_campaign-state.yaml` (state), `campaign-brief.yaml` (machine-generated brief), `campaign-report.md` (post-campaign summary), `_campaign-decision-log.md` (append-only rationale), `SKF_CAMPAIGN_RESULT_JSON` (headless envelope) — all under `{campaignWorkspacePath}` |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every HARD HALT exits with a stable, documented code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning              | Raised by                                                   |
+| ---- | -------------------- | ----------------------------------------------------------- |
+| 0    | success              | step-11 (terminal)                                          |
+| 3    | invalid-state        | any step §1 (`campaign-validate-state.py` non-zero on load) |
+| 4    | circular-deps        | step-02 §5                                                  |
+| 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 (brief missing or unreadable)              |
+| 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` — graceful, resumable; see Workflow Rules) |
+
+## Result Contract on HARD HALT
+
+In addition to the success-variant envelope (see Campaign Headless Envelope), every HARD HALT emits an **error variant** so automators don't silently break. Emit one line on **stderr**:
+
+```
+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>"}
+```
+
+`<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.
+
+## Mode Routing
+
+On invocation:
+
+1. **`campaign resume [--from=<skill>]`** — load `references/step-resume.md`. Validates state integrity, checks backup consistency, and chains to the appropriate stage step file. If `--from=<skill>` is provided, override the resume point to the named skill.
+2. **`campaign`** (new, no existing state) — run from stage 0 (Setup).
+3. **`campaign`** (state exists) — detect existing `{campaignWorkspacePath}/_campaign-state.yaml` and prompt: **resume** via `references/step-resume.md`, or **overwrite** with a new campaign. On overwrite, first archive the existing `_campaign-state.yaml` and `campaign-brief.yaml` to `{campaignWorkspacePath}/archive/{name}-{timestamp}/`, log the archive to the decision log, and show a one-line summary of what is being set aside before chaining to step-01. In headless mode, default to **resume** (never silently clobber); archive-and-overwrite only when `--brief`/`--manifest` explicitly seeds a new campaign.
+4. **`campaign status`** (read-only) — load `{campaignWorkspacePath}/_campaign-state.yaml`, validate it via `campaign-validate-state.py`, display the Resume Detection summary block followed by the last ~15 lines of `{campaignWorkspacePath}/_campaign-decision-log.md` (so the operator sees the recent decision trail without flooding the terminal on a long campaign), then stop. No backup, no mutation, no chaining. Exit 0 (or 9 if the state is unrecoverable).
+
+## Resume Detection
+
+When resuming:
+
+1. Read `_campaign-state.yaml`
+2. Validate via `campaign-validate-state.py` (halt on invalid; attempt `.bak` recovery per step-resume)
+3. Find last active or completed stage from `campaign.current_stage` (the highest completed stage); when no skill is active, resume continues from the stage *after* it (`current_stage + 1`, terminal-capped)
+4. Skip completed skills (status = `completed` or `skipped`)
+5. If `--from=<skill>` is provided, find the named skill and resume from its stage
+6. Continue from the next incomplete skill in `dependency_graph.execution_order`
+
+## 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`
+
+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.
+
+## Campaign Headless Envelope
+
+When `{headless_mode}` is true, the final step emits a single-line JSON envelope on stdout:
+
+```
+SKF_CAMPAIGN_RESULT_JSON: {"status":"success|error","skills_completed":0,"skills_failed":0,"quality_scores":{},"campaign_report_path":"","decision_log":"","duration":""}
+```
+
+`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). `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.

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

@@ -0,0 +1,191 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "campaign-state",
+  "description": "Schema for _campaign-state.yaml — single source of truth for campaign orchestration state",
+  "type": "object",
+  "required": ["campaign", "skills", "dependency_graph"],
+  "additionalProperties": false,
+  "properties": {
+    "campaign": {
+      "type": "object",
+      "required": ["name", "started_at", "last_updated", "current_stage", "quality_gate", "health_findings_queue"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "started_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "last_updated": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "current_stage": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10
+        },
+        "directive_path": {
+          "type": "string"
+        },
+        "quality_gate": {
+          "type": "object",
+          "required": ["hard", "soft_target", "soft_fallback"],
+          "additionalProperties": false,
+          "properties": {
+            "hard": {
+              "type": "string"
+            },
+            "soft_target": {
+              "type": "number"
+            },
+            "soft_fallback": {
+              "type": "number"
+            }
+          }
+        },
+        "health_findings_queue": {
+          "type": "string",
+          "enum": ["local", "improvement"]
+        },
+        "architecture_doc_path": {
+          "type": ["string", "null"],
+          "description": "Path to the architecture document consumed by the verify (Stage 7) and refine (Stage 8) stages. Sourced at setup; null when the campaign runs no verification."
+        },
+        "capstone": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "description": "Capstone (stack) outcome composed from all completed campaign skills (Tier A and Tier B). Campaign-level summary; the composed skill itself lives at skill_path.",
+          "properties": {
+            "skill_path": {
+              "type": ["string", "null"]
+            },
+            "quality_score": {
+              "type": ["number", "null"]
+            },
+            "verified": {
+              "type": ["boolean", "null"]
+            },
+            "completed_at": {
+              "type": ["string", "null"],
+              "format": "date-time"
+            }
+          }
+        },
+        "verification": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "description": "Stage 7 verify-stack summary. Detailed findings live in the external report at report_path.",
+          "properties": {
+            "report_path": {
+              "type": ["string", "null"]
+            },
+            "overall_verdict": {
+              "type": ["string", "null"],
+              "enum": ["Verified", "Plausible", "Risky", "Blocked", null]
+            },
+            "coverage_percentage": {
+              "type": ["number", "null"]
+            },
+            "recommendation_count": {
+              "type": ["integer", "null"]
+            }
+          }
+        },
+        "refinement": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "description": "Stage 8 refine-architecture summary. The refined document lives at refined_path.",
+          "properties": {
+            "refined_path": {
+              "type": ["string", "null"]
+            },
+            "gap_count": {
+              "type": ["integer", "null"]
+            },
+            "issue_count": {
+              "type": ["integer", "null"]
+            },
+            "improvement_count": {
+              "type": ["integer", "null"]
+            }
+          }
+        }
+      }
+    },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "status", "tier"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pending", "active", "completed", "failed", "skipped"]
+          },
+          "depends_on": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "tier": {
+            "type": "string",
+            "enum": ["A", "B"]
+          },
+          "pin": {
+            "type": ["string", "null"]
+          },
+          "brief_path": {
+            "type": ["string", "null"]
+          },
+          "skill_path": {
+            "type": ["string", "null"]
+          },
+          "quality_score": {
+            "type": ["number", "null"]
+          },
+          "workarounds_applied": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "started_at": {
+            "type": ["string", "null"],
+            "format": "date-time"
+          },
+          "completed_at": {
+            "type": ["string", "null"],
+            "format": "date-time"
+          },
+          "commit_sha": {
+            "type": ["string", "null"]
+          }
+        }
+      }
+    },
+    "dependency_graph": {
+      "type": "object",
+      "required": ["execution_order", "circular_deps_detected"],
+      "additionalProperties": false,
+      "properties": {
+        "execution_order": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "circular_deps_detected": {
+          "type": "boolean"
+        }
+      }
+    }
+  }
+}