bmad-module-skill-forge 1.8.0 → 2.0.0

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

@@ -0,0 +1,188 @@
+---
+nextStepFile: 'step-auto-validate.md'
+validateBriefSchemaProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
+  - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
+writeSkillBriefProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-write-skill-brief.py'
+  - '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
+emitBriefEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
+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}. -->
+
+# Step 1a: Auto-Brief Generation
+
+## STEP GOAL:
+
+To enrich an upstream skill brief (produced by AN auto-scope) with documentation URLs discovered via `skf-detect-docs.py`, validate the enriched brief, and write it through the canonical writer. Envelope emission is deferred to step-auto-validate.md, which presents the brief for user approval before continuing. This step replaces the interactive gather-intent → analyze-target → scope-definition → confirm-brief → write-brief chain when `[auto]` mode is active.
+
+## Rules
+
+- Auto-proceed step — no user interaction required
+- This step is conditional — only loaded when `[auto]` flag is present in the pipeline context
+- Must produce the same output artifact as the interactive chain: a validated `skill-brief.yaml`
+- Doc detection is best-effort — failures do not halt the pipeline
+- Do NOT re-derive scope fields from the upstream brief — AN already set them correctly
+- Do NOT render YAML or JSON envelopes in the LLM — delegate to deterministic scripts
+
+## MANDATORY SEQUENCE
+
+### 1. Load Upstream Brief
+
+Read the upstream brief path from `{brief_path}` (passed by the forger from AN's `SKF_ANALYZE_RESULT_JSON` `brief_paths[]`).
+
+**IF `{brief_path}` is not set or the file does not exist:**
+- HARD HALT with exit code 2 (`input-missing`): "**Auto-brief requires an upstream brief — `brief_path` is missing or the file does not exist at `{brief_path}`.**"
+- Emit error envelope per §6 with `halt_reason: "input-missing"`.
+
+**Resolve `{validateBriefSchemaHelper}`** from `{validateBriefSchemaProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Validate the upstream brief against the schema:
+
+```bash
+uv run {validateBriefSchemaHelper} {brief_path}
+```
+
+The script returns JSON `{valid, errors[], warnings[], halt_reason, brief}`.
+
+- **`valid: false`** — the upstream brief is malformed. HARD HALT with exit code 2 (`input-invalid`): "**Upstream brief at `{brief_path}` is invalid: {first error message}.**" Emit error envelope per §6 with `halt_reason: "input-invalid"`.
+- **`valid: true`** — proceed with the parsed `brief` payload. Surface any non-empty `warnings[]` to the log.
+
+Extract from the parsed brief:
+- `skill_name` ← `brief.name`
+- `version` ← `brief.version`
+- `source_repo` ← `brief.source_repo`
+- `language` ← `brief.language`
+- `scope_type` ← `brief.scope.type`
+- `forge_tier` ← `brief.forge_tier`
+- `description` ← `brief.description`
+- `created` ← `brief.created`
+- `created_by` ← `brief.created_by`
+- All scope fields: `scope.include`, `scope.exclude`, `scope.notes`, `scope.rationale`, `scope.amendments`, `scope.tier_a_include`
+- Optional fields: `source_type`, `source_authority`, `doc_urls`, `target_version`, `target_ref`, `source_ref`, `scripts_intent`, `assets_intent`
+
+**Docs-only check:** If `source_type` is `docs-only` in the parsed brief, skip §2 (Run Doc Detection) and §3 (Enrich Brief with Detected Docs) — the doc URL is already in the brief's `doc_urls`. Log: "Docs-only brief — skipping repo-based doc detection. Doc URLs provided by upstream." Proceed directly to §4 (Validate Enriched Brief). All brief fields (`source_type`, `source_authority`, `doc_urls`, `scope_type`) must pass through unmodified.
+
+### 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 {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.
+
+**Handle exit codes:**
+
+- **Exit 0 (found docs):** Parse the JSON output array. Each entry has `{url, detected_via, content_hash, content_type}`. Proceed to §3 with the detected docs.
+- **Exit 1 (none found):** Log: "No external documentation found — brief generated from source analysis only." Proceed to §4 with no doc enrichment.
+- **Exit 2 (error):** Log warning: "Doc detection failed — proceeding without doc enrichment." Do NOT halt — doc enrichment is best-effort. Proceed to §4 with no doc enrichment.
+
+### 3. Enrich Brief with Detected Docs
+
+For each detected doc entry, create a brief `doc_urls` entry:
+
+- `url` ← `url` (direct copy)
+- `label` ← derive from `content_type` if available:
+  - `"api-docs"` → `"API Documentation"`
+  - `"guide"` → `"Guide"`
+  - `"reference"` → `"Reference"`
+  - Otherwise derive from `detected_via`:
+    - `"homepageUrl"` → `"Homepage"`
+    - `"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.
+
+**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
+
+Assemble the enriched brief context as a flat JSON object following the write-brief §3 contract:
+
+```json
+{
+  "name":             "{skill_name}",
+  "target_version":   "{target_version or null}",
+  "detected_version": null,
+  "source_type":      "{source_type or 'source'}",
+  "source_repo":      "{source_repo}",
+  "language":         "{language}",
+  "description":      "{description}",
+  "forge_tier":       "{forge_tier}",
+  "created":          "{created}",
+  "created_by":       "{created_by}",
+  "scope_type":       "{scope_type}",
+  "scope_include":    ["{scope.include patterns}"],
+  "scope_exclude":    ["{scope.exclude patterns}"],
+  "scope_notes":      "{scope.notes or ''}",
+  "scope_rationale":  null,
+  "scope_tier_a_include": null,
+  "scope_amendments":     null,
+  "doc_urls":         [{"url": "...", "label": "...", "source": "..."}],
+  "scripts_intent":   "{scripts_intent or null}",
+  "assets_intent":    "{assets_intent or null}",
+  "source_authority": "{source_authority or null}",
+  "target_ref":       "{target_ref or null}",
+  "source_ref":       "{source_ref or null}",
+  "version_resolved": "{version}"
+}
+```
+
+The `version_resolved` key pins the output to the upstream brief's version — without it, the writer's precedence logic falls through to `1.0.0` since `target_version` and `detected_version` are both null on the auto path.
+
+### 5. Write Enriched Brief
+
+**Resolve `{writeSkillBriefHelper}`** from `{writeSkillBriefProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Write the enriched brief through the canonical writer:
+
+```bash
+echo '<context-json>' | uv run {writeSkillBriefHelper} write --target {forge_data_folder}/{skill_name}/skill-brief.yaml --from-flat
+```
+
+**On script failure (non-zero exit):**
+- Exit 1 (validation/invariant): Emit error envelope per §6 with `halt_reason: "input-invalid"`, then HARD HALT.
+- Exit 2 (I/O failure): Emit error envelope per §6 with `halt_reason: "write-failed"`, then HARD HALT.
+
+**On success:** Capture `brief_path` and `version` from the response envelope for step-auto-validate's envelope emission.
+
+### 6. Error Envelope (Canonical)
+
+Every HARD HALT in this step emits the error envelope on stderr:
+
+**Resolve `{emitBriefEnvelopeHelper}`** from `{emitBriefEnvelopeProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+```bash
+echo '{"status":"error","skill_name":"{skill_name or unknown}","halt_reason":"{reason}","mode":"auto"}' | \
+  uv run {emitBriefEnvelopeHelper} emit --target stderr
+```
+
+### 7. Chain to Auto-Validate
+
+Load, read fully, then execute {nextStepFile} to present the auto-brief validation gate, where the user can approve, edit, or reject the brief before the pipeline continues.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the enriched brief has been written and validated will you load and read fully {nextStepFile} to begin the auto-brief validation gate.

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

@@ -0,0 +1,209 @@
+---
+nextStepFile: 'health-check.md'
+rejectTargetFile: 'confirm-brief.md'
+validateBriefSchemaProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
+  - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
+writeSkillBriefProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-write-skill-brief.py'
+  - '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
+emitBriefEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 1b: Auto-Brief Validation
+
+## STEP GOAL:
+
+To present the user with a concise summary of the auto-generated brief and offer three actions — approve, edit, or reject — before the pipeline continues. On approve or edit, the result envelope is emitted and the pipeline chains to the health check. On reject, the pipeline falls back to the interactive brief review cycle with pre-populated fields.
+
+## Rules
+
+- This step is conditional — only loaded from step-auto-brief.md when `[auto]` mode is active
+- The brief MUST already exist on disk (written by step-auto-brief §5) before this step runs
+- Do NOT render YAML or JSON envelopes in the LLM — delegate to deterministic scripts
+- Do NOT modify confirm-brief.md or write-brief.md — the [R]eject path reuses them as-is
+- The 10-line summary is always displayed, even in headless mode, for logging transparency
+
+## MANDATORY SEQUENCE
+
+### 1. Load Auto-Brief
+
+Read the brief from `{forge_data_folder}/{skill_name}/skill-brief.yaml` (written by step-auto-brief §5).
+
+**Resolve `{validateBriefSchemaHelper}`** from `{validateBriefSchemaProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Validate the brief against the schema:
+
+```bash
+uv run {validateBriefSchemaHelper} {forge_data_folder}/{skill_name}/skill-brief.yaml
+```
+
+The script returns JSON `{valid, errors[], warnings[], halt_reason, brief}`.
+
+- **`valid: false`** — HARD HALT with exit code 2 (`input-invalid`): "**Auto-brief at `{forge_data_folder}/{skill_name}/skill-brief.yaml` is invalid: {first error message}.**" Emit error envelope per §7 with `halt_reason: "input-invalid"`.
+- **`valid: true`** — proceed with the parsed `brief` payload. Surface any non-empty `warnings[]` to the log.
+
+**IF the file does not exist:**
+- HARD HALT with exit code 2 (`input-missing`): "**Auto-brief not found at `{forge_data_folder}/{skill_name}/skill-brief.yaml` — step-auto-brief must write the brief before this step runs.**" Emit error envelope per §7 with `halt_reason: "input-missing"`.
+
+Extract from the parsed brief:
+- `skill_name` ← `brief.name`
+- `version` ← `brief.version`
+- `source_repo` ← `brief.source_repo`
+- `language` ← `brief.language`
+- `scope_type` ← `brief.scope.type`
+- `scope_include` ← `brief.scope.include`
+- `scope_exclude` ← `brief.scope.exclude`
+- `forge_tier` ← `brief.forge_tier`
+- `description` ← `brief.description`
+- `doc_urls` ← `brief.doc_urls`
+
+### 2. Present 10-Line Summary
+
+Render a concise summary from the brief fields for rapid scanning:
+
+```
+Auto-Brief Summary: {skill_name}
+─────────────────────────────────
+Source:       {source_repo}
+Language:     {language}
+Scope:        {scope_type} ({N} include, {M} exclude patterns)
+Docs:         {doc_urls count} sources detected | "None detected"
+Version:      {version}
+Forge Tier:   {forge_tier}
+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". 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
+
+**GATE: [A]pprove** — Present `[A]pprove` / `[E]dit` / `[R]eject` to user.
+
+"**Review the auto-generated brief above.**
+
+Select an action:
+  [A] Approve — accept the brief as-is and continue the pipeline
+  [E] Edit — modify specific fields before continuing
+  [R] Reject — fall back to interactive brief review with pre-populated fields"
+
+If `{headless_mode}`: auto-proceed with `[A]pprove`, log: "headless: auto-approve auto-brief".
+
+Wait for user response. Branch on the response:
+
+- `[A]` or `approve` → §4 ([A]pprove path)
+- `[E]` or `edit` → §5 ([E]dit path)
+- `[R]` or `reject` → §6 ([R]eject path)
+- Any other input → answer briefly, re-display the menu
+
+### 4. [A]pprove Path
+
+**Resolve `{emitBriefEnvelopeHelper}`** from `{emitBriefEnvelopeProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Emit the `SKF_BRIEF_RESULT_JSON` envelope with `mode: "auto"`:
+
+```bash
+echo '{"status":"success","brief_path":"{brief_path}","skill_name":"{skill_name}","version":"{version}","language":"{language}","scope_type":"{scope_type}","halt_reason":null,"mode":"auto"}' | \
+  uv run {emitBriefEnvelopeHelper} emit
+```
+
+Where `{brief_path}` is `{forge_data_folder}/{skill_name}/skill-brief.yaml`.
+
+Chain to {nextStepFile} (health-check.md) — load, read fully, then execute.
+
+### 5. [E]dit Path
+
+Present each brief field with its current value and accept natural language modification requests.
+
+"**Editable fields:**
+
+1. **Name:** {skill_name}
+2. **Source:** {source_repo}
+3. **Language:** {language}
+4. **Scope type:** {scope_type}
+5. **Include patterns:** {scope_include}
+6. **Exclude patterns:** {scope_exclude}
+7. **Description:** {description}
+8. **Doc URLs:** {doc_urls or "None"}
+9. **Version:** {version}
+10. **Forge tier:** {forge_tier}
+
+Tell me what to change (e.g. 'change scope type to public-api', 'add doc URL https://...')."
+
+Wait for user response. Apply changes to the brief context.
+
+**Re-write the modified brief** through the canonical writer:
+
+**Resolve `{writeSkillBriefHelper}`** from `{writeSkillBriefProbeOrder}`; first existing path wins.
+
+Assemble the modified brief context as a flat JSON object (same format as step-auto-brief §4):
+
+```bash
+echo '<modified-flat-json>' | uv run {writeSkillBriefHelper} write --target {forge_data_folder}/{skill_name}/skill-brief.yaml --from-flat
+```
+
+The canonical writer validates the brief internally — on non-zero exit, surface the error and re-prompt for corrections. The edit loop allows multiple modifications — each write re-validates before accepting.
+
+**Re-validate the written brief** against the schema to confirm correctness:
+
+**Resolve `{validateBriefSchemaHelper}`** from `{validateBriefSchemaProbeOrder}`; first existing path wins.
+
+```bash
+uv run {validateBriefSchemaHelper} {forge_data_folder}/{skill_name}/skill-brief.yaml
+```
+
+If validation fails (the writer missed a constraint), surface the error and re-prompt for corrections.
+
+Re-present the 10-line summary (§2 format) with updated values so the user can verify the change.
+
+"Updated brief written. **Select:** [A] Approve and continue · [E] Edit more · [R] Reject"
+
+- `[A]` → emit envelope per §4, chain to {nextStepFile}
+- `[E]` → repeat §5 edit loop
+- `[R]` → §6 ([R]eject path)
+
+### 6. [R]eject Path
+
+"**Falling back to interactive brief — fields pre-populated from auto-detection.**"
+
+Hydrate brief context variables from the auto-brief on disk, using the same field mapping as the ratify path in gather-intent §3.1a:
+
+- `name` ← `brief.name`; `version` ← `brief.version`; `target_version` ← `brief.target_version`
+- `target_ref` ← `brief.target_ref`; `source_ref` ← `brief.source_ref` (optional git refs; preserve when present)
+- `source_repo` ← `brief.source_repo`; `source_type` ← `brief.source_type`; `source_authority` ← `brief.source_authority`; `doc_urls` ← `brief.doc_urls`
+- `language` ← `brief.language`; `description` ← `brief.description`; `forge_tier` ← `brief.forge_tier`
+- `created` ← `brief.created`; `created_by` ← `brief.created_by`
+- `scope.type` / `scope.include` / `scope.exclude` / `scope.tier_a_include` / `scope.notes` / `scope.rationale` / `scope.amendments` ← `brief.scope.*` (preserve `tier_a_include` and the `amendments` log verbatim — do not re-derive or drop them)
+- `scripts_intent` ← `brief.scripts_intent`; `assets_intent` ← `brief.assets_intent`
+
+Set `ratify_mode: true` and `ratify_source_path: {forge_data_folder}/{skill_name}/skill-brief.yaml` in workflow context.
+
+Chain to {rejectTargetFile} (confirm-brief.md) — load, read fully, then execute. The user gets the full interactive review experience: view, adjust fields inline, revise scope via [R], or approve via [C] → write-brief.md → health-check.md.
+
+The interactive chain's write-brief.md handles its own envelope emission with `mode: null` (interactive), which is correct since the user explicitly chose to leave auto mode.
+
+### 7. Error Envelope (Canonical)
+
+Every HARD HALT in this step emits the error envelope on stderr:
+
+**Resolve `{emitBriefEnvelopeHelper}`** from `{emitBriefEnvelopeProbeOrder}`; first existing path wins.
+
+```bash
+echo '{"status":"error","skill_name":"{skill_name or unknown}","halt_reason":"{reason}","mode":"auto"}' | \
+  uv run {emitBriefEnvelopeHelper} emit --target stderr
+```
+
+### 8. Chain
+
+Load, read fully, then execute the appropriate next step file based on the user's choice:
+- [A]pprove or [E]dit (after final approve): {nextStepFile} (health-check.md)
+- [R]eject: {rejectTargetFile} (confirm-brief.md)
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the user has made their choice (approve, edit-then-approve, or reject) and the appropriate action has been taken (envelope emitted or context hydrated) will you load and read fully the next step file.

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.