bmad-module-skill-forge 1.1.0 → 1.3.0

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "1.1.0",
+      "version": "1.3.0",
       "author": {
         "name": "Armel"
       },

package/README.md

@@ -16,7 +16,7 @@
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
 [![GitHub stars](https://img.shields.io/github/stars/armelhbobdad/bmad-module-skill-forge?style=social)](https://github.com/armelhbobdad/bmad-module-skill-forge/stargazers)
 
-_Skill Forge analyzes your code repositories, documentation, and developer discourse to build verified instruction files for AI agents. Every instruction links back to a specific file and line in the source it was compiled from._
+_Skill Forge analyzes your code repositories, documentation, and developer discourse to build verified instruction files for AI agents. Every instruction links back to its upstream — a specific `file:line` at a pinned commit when source is available, or a documentation URL when it isn't._
 
 **If SKF fixes your agent's API guesses, give it a ⭐ — it helps others find this tool.**
 **If it saved you an afternoon, [grab me a coffee ☕](https://buymeacoffee.com/armelhbobdad) — it helps me keep forging.**
@@ -94,7 +94,7 @@ A skeptical reader is probably already considering one of these alternatives:
 
 |                            | **Skill Forge**                           | MCP doc servers   | Hand-edited `.cursorrules` | awesome-\* lists |
 | -------------------------- | ----------------------------------------- | ----------------- | -------------------------- | ---------------- |
-| Reproducible from source   | AST extraction + pinned commit            | varies; opaque    | whatever you wrote         | none             |
+| Reproducible from upstream | AST + pinned commit (or pinned doc URL)   | varies; opaque    | whatever you wrote         | none             |
 | Version-pinned & immutable | yes — per-version directories             | runtime-dependent | rots silently              | no               |
 | Audit trail                | `provenance-map.json` + test + evidence   | depends on server | none                       | none             |
 | Runtime cost               | zero (markdown + JSON)                    | a running process | zero                       | zero             |
@@ -115,13 +115,15 @@ SKF extracts real function signatures, types, and patterns from code, docs, and
 
 ## Verifying a Skill
 
-You can falsify any AST citation in an SKF-compiled skill in under a minute:
+You can falsify any citation in an SKF-compiled skill in under a minute:
 
 1. **Open the skill's `provenance-map.json`** — find your symbol; read its `source_file` and `source_line`.
 2. **Open the skill's `metadata.json`** — read `source_commit` and `source_repo`.
 3. **Jump to the upstream repo at that commit**, open that file, find that line. The signature in `SKILL.md` should match the one you're reading.
 
-If it doesn't, that's a bug — open an issue and SKF will republish with a new commit SHA and a new provenance map. Falsifiability isn't a feature; it's the whole deal.
+For docs-only skills, the audit shape is the same — `provenance-map.json` still lists every symbol — but entries cite `[EXT:{url}]` instead of `file:line@SHA`, and step 3 becomes "open the doc URL and confirm the signature matches."
+
+If it doesn't, that's a bug — open an issue and SKF will republish the skill with a fresh provenance map (a new commit SHA for source skills, a fresh fetch for docs-only). Falsifiability isn't a feature; it's the whole deal.
 
 **Reference output: [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills)** — four Deep-tier skills compiled by SKF (cocoindex, cognee, Storybook v10, uitripled), each shipping its full audit trail in-repo. Scores range from 99.0% to 99.49%. Every claim walks to an upstream line in under 60 seconds. Serves as both the worked example for this section and ongoing proof that the pipeline does what it says.
 

package/docs/_data/pinned.yaml

@@ -26,7 +26,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "1.1.0"
+skf_version: "1.3.0"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/docs/bmad-synergy.md

@@ -9,7 +9,7 @@ This page builds on BMAD concepts (BMM phases, TEA, modules). New to BMAD? Start
 
 ## Launcher Skills vs Content Skills
 
-A BMAD project that also uses SKF ends up with two different kinds of `SKILL.md` files living in the same IDE skills directory. SKF supports 23 IDEs — Claude Code (`.claude/skills/`), Cursor (`.cursor/skills/`), GitHub Copilot (`.github/skills/`), Windsurf (`.windsurf/skills/`), Cline (`.cline/skills/`), Roo Code (`.roo/skills/`), Gemini CLI (`.gemini/skills/`), and 16 others — each with its own skill directory. See the [complete IDE → Context File mapping](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-export-skill/assets/managed-section-format.md) for the full list. They look similar. They are not the same thing. This is the single most durable point of confusion, so get it straight up front.
+A BMAD project that also uses SKF ends up with two different kinds of `SKILL.md` files living in the same IDE skills directory. SKF supports 24 IDEs — Claude Code (`.claude/skills/`), Cursor (`.cursor/skills/`), GitHub Copilot (`.github/skills/`), Windsurf (`.windsurf/skills/`), Cline (`.cline/skills/`), Roo Code (`.roo/skills/`), Gemini CLI (`.gemini/skills/`), and 17 others — each with its own skill directory. See the [complete IDE → Context File mapping](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-export-skill/assets/managed-section-format.md) for the full list. They look similar. They are not the same thing. This is the single most durable point of confusion, so get it straight up front.
 
 | | BMAD launcher skill | SKF content skill |
 |---|---|---|
@@ -166,7 +166,7 @@ Beyond briefing, CIS and SKF don't overlap — CIS covers ideation, storytelling
 
 ## Delivery and Lifecycle in a BMAD Project
 
-`@Ferris EX` is the **only workflow that introduces new skill context** into the three context files that serve all 23 IDEs: `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), and `AGENTS.md` (the remaining 21 IDEs — GitHub Copilot, Windsurf, Cline, Roo Code, Gemini CLI, and others). Each IDE also has its own skill root directory where skill files are installed (e.g., `.windsurf/skills/`, `.roo/skills/`, `.gemini/skills/`). Create-skill and update-skill produce draft artifacts that never touch those files directly — nothing reaches an agent's passive context until it has been through the EX gate. See [Skill Model → Dual-Output Strategy](../skill-model/#dual-output-strategy) for the architectural rationale.
+`@Ferris EX` is the **only workflow that introduces new skill context** into the three context files that serve all 24 IDEs: `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), and `AGENTS.md` (the remaining 22 IDEs — GitHub Copilot, Windsurf, Cline, Roo Code, Gemini CLI, and others). Each IDE also has its own skill root directory where skill files are installed (e.g., `.windsurf/skills/`, `.roo/skills/`, `.gemini/skills/`). Create-skill and update-skill produce draft artifacts that never touch those files directly — nothing reaches an agent's passive context until it has been through the EX gate. See [Skill Model → Dual-Output Strategy](../skill-model/#dual-output-strategy) for the architectural rationale.
 
 This matters specifically in a BMAD project: you may have multiple BMAD modules, each with its own launcher skills, plus SKF content skills, all trying to contribute context. The write-guard means only verified, tested SKF skills ever reach an agent's passive context — nothing half-baked sneaks in. `@Ferris EX` injects managed sections that coexist cleanly with whatever BMAD's installer wrote in the same files.
 

package/docs/getting-started.md

@@ -135,7 +135,7 @@ Analyzes your project's dependencies and generates a consolidated stack skill wi
 
 ## Common use cases
 
-> **Looking for end-to-end examples?** See [Examples](../examples/) for eleven real-world scenarios with full command transcripts — from Quick Skill under a minute, to brownfield onboarding, stack verification, release-prep drift remediation, and SaaS docs-only skills.
+> **Looking for end-to-end examples?** See [Examples](../examples/) for thirteen real-world scenarios with full command transcripts — from Quick Skill under a minute, to brownfield onboarding, stack verification, release-prep drift remediation, and SaaS docs-only skills.
 
 ---
 

package/docs/skill-model.md

@@ -25,51 +25,45 @@ Setup detects your installed tools and sets your tier automatically:
 ```
 
 ```
-┌─────────────────────────────┐
-│ FORGE STATUS                │
-└─────────────────────────────┘
+═══════════════════════════════════════
+  FORGE STATUS
+═══════════════════════════════════════
 
   Tier:  Deep
-
-  Deep tier active. Full capability unlocked — AST-backed code
-  analysis, GitHub repository exploration, and QMD knowledge search
-  with cross-repository synthesis. Maximum provenance and intelligence.
+  Deep tier active. Full capability unlocked — AST-backed code analysis,
+  GitHub repository exploration, and QMD knowledge search with
+  cross-repository synthesis. Maximum provenance and intelligence.
 
   Tools Detected:
-    ast-grep  — 0.42.0
-    gh        — 2.89.0
-    qmd       — operational (104 docs indexed globally)
-    ccc       — 0.2.10 (daemon healthy)
+  - ast-grep 0.42.0
+  - gh 2.91.0 (2026-04-22)
+  - qmd 2.0.1
+  - ccc (daemon healthy)
 
   QMD Registry:
-    0 collection(s) healthy
-    39 orphaned collection(s) removed
-    (empty — collections are created automatically when you run [CS] Create Skill)
+  0 collection(s) healthy
+  23 orphaned collection(s) kept
 
   CCC Index:
-    indexed this run — semantic discovery ready (2 files, 14 chunks)
-    SKF infrastructure excluded: _bmad, _bmad-output, .claude,
-    _skf-learn, skills, forge-data
-
-┌────────────────────────────────┐
-│ Forge ready. Deep tier active. │
-└────────────────────────────────┘
-
-Health Check: Clean run. No workflow issues to report.
+  indexed this run — semantic discovery ready (1 file)
 
-Workflow complete.
+  Files written this run:
+  - forge-tier.yaml — {project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml
+  - .cocoindex_code/settings.yml — {project-root}/.cocoindex_code/settings.yml (6 SKF exclusion patterns merged)
+  - .cocoindex_code/ ccc index — 1 file indexed
 
----
-Forge is live at Deep tier, armel. All four core tools are available, the CCC semantic index is built, and the QMD registry is clean.
+═══════════════════════════════════════
+  Forge ready. Deep tier active.
+═══════════════════════════════════════
 
-What would you like to forge next? Common starting points:
+  Next: try [BS] Brief Skill to scope your first compilation target,
+  or [QS] Quick Skill for a fast template-driven path.
+  Already have a skill? [AS] Audit Skill drift-checks an existing skill
+  against current sources.
 
-- QS — fast skill from a GitHub URL or package name
-- BS → CS — brief, then compile a skill from source
-- AN — analyze a large repo to discover what's worth skilling
-- WS — show current lifecycle status
+Health Check: Clean run. No workflow issues to report.
 
-Or chain them: forge (BS CS TS EX), forge-quick (QS TS EX), onboard (AN CS TS EX).
+Workflow complete.
 ```
 
 Don't have ast-grep, cocoindex-code, or QMD yet? No problem — Quick mode works with no additional tools. Optional GitHub CLI improves source access. Install tools later; your tier upgrades automatically.

package/docs/troubleshooting.md

@@ -9,11 +9,23 @@ If something isn't working, start here. For general setup help see [Getting Star
 
 ## Common errors
 
+### "Setup cannot proceed: `uv` is not installed"
+
+Surfaced by `/skf-setup` On Activation when `uv --version` is missing on `$PATH`. SKF helpers depend on `uv` to auto-resolve their Python dependencies via PEP 723 inline metadata; bare `python3` ignores that metadata and would fail later with `ModuleNotFoundError: No module named 'yaml'`. The probe halts the workflow up-front with one cohesive diagnostic instead of letting five steps each fail individually.
+
+**Fix:** install `uv` from <https://docs.astral.sh/uv/getting-started/installation/> and re-run `/skf-setup`. `uv` is documented as a runtime prerequisite in [Getting Started → Prerequisites](../getting-started/#prerequisites-full-reference).
+
+### "Setup cannot proceed: `_bmad/skf/config.yaml` was not found"
+
+Surfaced by `/skf-setup` On Activation when the SKF install config is missing — typically because you invoked `/skf-setup` from a directory that is not an SKF-initialised project. The check runs before any file mutation so nothing is written.
+
+**Fix:** from the project root, run `npx bmad-module-skill-forge install` (or `npx bmad-method install` and add SKF as a custom module — see [Getting Started → Install](../getting-started/#install)), then re-run `/skf-setup`. If you ARE in the right project but the file was deleted, restore it from version control or re-run the SKF installer. A separate "config.yaml is not valid YAML" diagnostic surfaces the parser error inline if the file exists but is malformed — open the file at the named path and repair the YAML.
+
 ### Forge reports ast-grep is unavailable
 
 If setup reports that ast-grep was not detected, install it to unlock the Forge tier: <https://ast-grep.github.io>. Re-run `@Ferris SF` afterward — your tier upgrades automatically.
 
-### "No brief found"
+### "No skill brief found"
 
 Run `@Ferris BS` first to create a skill brief, or use `@Ferris QS` for brief-less generation. `CS` requires either a brief or a direct invocation with scope arguments.
 

package/docs/why-skf.md

@@ -3,7 +3,7 @@ title: Why Skill Forge?
 description: The strategic case for SKF — the problem it solves, how it compares to alternatives, who it's for, and who it isn't.
 ---
 
-Skill Forge is the only AI-skills toolchain where every claim your agent reads cites a file, a line, and a commit SHA. Not "sourced from training data." Not "retrieved from context." **Cited.** You can open the upstream repo at the pinned commit and see the function exists — in under a minute. That's the wedge. This page explains why it matters, how SKF compares to alternatives, and who it's for.
+Skill Forge is the only AI-skills toolchain where every claim your agent reads points back to a real upstream location — a `file:line` at a pinned commit when source is available, or a documentation URL when it isn't. Not "sourced from training data." Not "retrieved from context." **Cited.** You can open the upstream repo (or the doc page) and see the function exists — in under a minute. That's the wedge. This page explains why it matters, how SKF compares to alternatives, and who it's for.
 
 ---
 
@@ -26,7 +26,7 @@ SKF treats this as a citation problem, not a model problem. If a skill claims `c
 | RAG / context stuffing | Retrieves relevant code snippets | Returns fragments without synthesis — no coherent skill output |
 | Manual authoring | High initial accuracy | Drifts as the source code changes, doesn't scale across dependencies |
 | IDE built-in context (Copilot, Cursor) | Convenient, zero setup | Uses generic training data, not your project's specific integration patterns |
-| **Skill Forge** | **Every instruction cites upstream `file:line` at a pinned commit. Falsifiable in 60 seconds.** | **Coverage depends on which tools you've installed (Quick / Forge / Forge+ / Deep tiers).** |
+| **Skill Forge** | **Every instruction cites upstream — `file:line@SHA` for source skills, doc URL for docs-only skills. Falsifiable in 60 seconds.** | **Coverage depends on which tools you've installed (Quick / Forge / Forge+ / Deep tiers).** |
 
 </div>
 
@@ -40,6 +40,8 @@ Pick any symbol in any SKF-compiled skill. Three clicks:
 2. Open the skill's `provenance-map.json` — find your symbol; it lists the file and line.
 3. Visit the upstream repo at that commit and that line. The signature in the skill should match.
 
+For docs-only skills, the audit shape is the same — `provenance-map.json` still lists every symbol — but entries cite `[EXT:{url}]` instead of `file:line@SHA`, and step 3 becomes "open the doc URL and confirm the signature matches."
+
 If it doesn't, **that's a bug.** [Open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) and SKF republishes the skill with a new commit SHA and a new provenance map. No other AI-skills tool treats disagreement between claim and source as a defect. SKF does.
 
 See the [Verifying a Skill](../verifying-a-skill/) page for the full three-step audit on real skills, the test reports that log *exactly* where coverage falls short, and the scoring formula behind the 80% pass threshold.
@@ -78,9 +80,8 @@ You're considering running SKF across a brownfield platform. You need to know ab
 ## Not for you if…
 
 - You want docs that hand-hold through every happy path with screenshots and emojis. SKF is a citation machine, not a tutorial series.
-- You need perfect coverage of every private implementation detail. SKF extracts public APIs; if you want internals, read the code directly.
 - You don't have Node.js ≥ 22 and Python ≥ 3.10 installed. SKF is a Node/Python toolchain at its core.
-- You're looking for something that generates skills from natural-language descriptions alone. SKF compiles from source code and documentation — not prompts.
+- You have neither source code nor published documentation for the target. SKF compiles from one or both — a source repo (citations as `file:line@SHA`) or doc URLs (citations as `[EXT:{url}]`). A vague description with no upstream artifact to cite isn't enough.
 
 Everything else is downstream of one question: *are the instructions your AI reads provably true?* If yes, SKF isn't adding value. If you can't be sure, SKF is the tool.
 

package/docs/workflows.md

@@ -21,6 +21,11 @@ Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../
 
 **Key Steps:** Detect tools + Determine tier → CCC index check (Forge+) → Write forge-tier.yaml → QMD + CCC registry hygiene (Deep/Forge+) → Status report
 
+**Flags:**
+
+- `--require-tier=<Quick|Forge|Forge+|Deep>` — fail-fast for CI: if the calculated tier does not satisfy the requested tier (tool-prerequisite check, not a name comparison — Deep does NOT subsume Forge+ because Deep does not require ccc), the workflow halts with a "REQUIRED TIER NOT MET" block and exits without chaining to the health check. Pipelines branch on the JSON envelope's `require_tier_satisfied` field.
+- `--headless` / `-H` — see [Headless Mode](#headless-mode) below. For `/skf-setup` specifically, headless mode emits a single-line `SKF_SETUP_RESULT_JSON: {…}` envelope to stdout (schema-locked, includes `tier`, `previous_tier`, `tier_changed`, `tools`, `tools_added`/`removed`, `files_written`, `warnings`, `error`) and SUPPRESSES the human-readable banner — the entire payload pipelines need is on one parseable line.
+
 **Agent:** Ferris (Architect mode)
 
 ---
@@ -79,6 +84,19 @@ Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../
 
 **Key Steps:** Resolve target → Ecosystem check → Quick extract → Compile → Validate → Write
 
+**Headless / batch flags:**
+
+- `--headless` / `-H` — auto-proceed all confirmation gates with documented defaults; emits structured stderr progress events and exit codes (see [Headless Mode](#headless-mode))
+- `--batch <file>` — process N targets from a text file in sequence (one target per line, `#` comments and `language=<lang>` / `scope=<path>` per-line modifiers supported); implies `--headless`
+- `--fail-fast` — only with `--batch`; abort the whole batch on the first per-target failure instead of recording it and proceeding
+
+**Per-target overrides** (apply to a single-target run, or globally to every target in `--batch`):
+
+- `--description "<string>"` — override the LLM-derived description used in `SKILL.md` frontmatter and `metadata.json`
+- `--exports "name1,name2,..."` — override the extracted export list (comma-separated)
+- `--skip-snippet` — skip `context-snippet.md` generation and write
+- `--no-active-pointer` — skip the active-pointer flip in finalize (deliverables still land in `{skill_package}`)
+
 **Agent:** Ferris (Architect mode)
 
 ---
@@ -337,6 +355,41 @@ Add `--headless` or `-H` to any workflow command to skip all confirmation gates.
 
 You can also set `headless_mode: true` in your forge preferences (`_bmad/_memory/forger-sidecar/preferences.yaml`) to make headless the default for all workflows.
 
+**Exception — `/skf-setup` headless emits a single-line JSON envelope.** Unlike other workflows, headless `/skf-setup` SUPPRESSES the human-readable status banner entirely and emits exactly one prefixed line on stdout:
+
+```
+SKF_SETUP_RESULT_JSON: {"skf_setup":{"tier":"Deep","previous_tier":"Forge","tier_changed":true,"tools":{...},"tools_added":[...],"tools_removed":[],"config_path":"...","ccc_index":{...},"files_written":[...],"tier_override_active":false,"tier_override_invalid":false,"require_tier_satisfied":null,"warnings":[],"error":null}}
+```
+
+Parent skills and CI pipelines `grep` one line out of the workflow log to learn the outcome — no ASCII-art parsing, no race against the [`forge-tier.yaml`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-setup/steps-c/step-02-write-config.md) writer. The envelope schema is versioned at [`src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json) and asserted against on every emit.
+
+**Exception — `/skf-quick-skill` headless emits structured progress + result envelopes.** Headless `/skf-quick-skill` runs are first-class building blocks for batch automators. Three operational contracts beyond per-gate auto-proceed:
+
+1. **Per-step JSON progress events to `stderr`** at each step's entry / exit / HARD HALT — one line per event, no pretty-print:
+
+   ```
+   {"step":3,"name":"quick-extract","status":"start"}
+   {"step":3,"name":"quick-extract","status":"done"}
+   {"step":1,"name":"resolve-target","status":"halt","exit":3}
+   ```
+
+   `<name>` is the kebab portion of the step filename: `resolve-target`, `ecosystem-check`, `quick-extract`, `compile`, `write-and-validate`, `finalize`, `health-check`.
+
+2. **Structured exit-code map.** Every HARD HALT exits with a stable code so pipelines branch on the failure class without grepping message text:
+
+   | Code | Meaning             |
+   | ---- | ------------------- |
+   | 0    | success             |
+   | 3    | resolution-failure  |
+   | 4    | write-failure       |
+   | 5    | overwrite-cancelled |
+   | 6    | compile-cancelled   |
+   | 7    | finalize-blocked    |
+
+3. **Error-variant result contract on every HARD HALT.** A `SKF_QUICK_SKILL_RESULT_JSON: {…}` envelope is emitted on `stderr` (always) and copied to `{skill_package}/quick-skill-result-latest.json` when the skill package is known (HALTs at step-05 §1 onward). The schema and full population rules live in [`src/skf-quick-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-quick-skill/SKILL.md) § "Result Contract on HARD HALT".
+
+**Batch mode (`--batch <file>`).** Drives N targets through the full pipeline (steps 1–7 each) in sequence. Input format: one target per line, `#` comments and blank lines ignored, optional per-line modifiers `language=<lang>` and `scope=<path>`. Per-target output lands in `{skill_package}/` as today; an aggregated summary writes to `{skills_output_folder}/_batch/quick-skill-batch-{ts}.json` (with `quick-skill-batch-latest.json` copy). Per-target boundary events (`{"batch":N,"target":"…","status":"start|done|fail",…}`) and a final `{"batch_summary":true,…}` event extend the per-step event stream above. Full input grammar, summary schema, and exit-code semantics in [`src/skf-quick-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-quick-skill/SKILL.md) § "Batch Mode".
+
 ---
 
 ## Terminal Step: Health Check

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
@@ -53,7 +53,7 @@
     "test:cli": "node test/test-cli-integration.js",
     "test:install": "node test/test-installation-components.js",
     "test:knowledge": "node test/test-knowledge-base.js",
-    "test:python": "uv run --with pytest --with pyyaml pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py -v",
+    "test:python": "uv run --with pytest --with pyyaml pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py -v",
     "test:schemas": "node test/test-agent-schema.js",
     "test:workflow": "node test/test-workflow-state.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",

package/src/knowledge/ccc-bridge.md

@@ -48,7 +48,7 @@ Returns: list of `{file, score, snippet}` entries ranked by semantic relevance t
 ### `ccc_bridge.status()`
 
 **Resolves to:** Two-step verification:
-1. `ccc --help` — confirms binary exists (exit 0)
+1. `ccc --help` — confirms binary exists (exit 0) AND output contains the `CocoIndex Code` identity marker (rejects unrelated `ccc`-named binaries shadowing PATH)
 2. `ccc doctor` — confirms daemon is running, extracts version string, validates embedding model
 
 **Usage context:** Called exclusively by setup step-01 during tool detection. Downstream workflows read the result from forge-tier.yaml — they do not re-verify.

package/src/shared/references/output-contract-schema.md

@@ -33,3 +33,13 @@ Each run writes **two files** to `{output_dir}`:
 Write the per-run record first, then copy it to the `-latest.json` path. If the copy fails, the per-run record still exists — the run is not lost.
 
 **Consumers (forger, CI, chained workflows):** read from `{skill-name}-result-latest.json`. Do not enumerate timestamped files unless inspecting prior-run history.
+
+## Available Helpers
+
+There is no generic helper that writes the schema above; each skill assembles the JSON in its terminal step today. One specialised helper exists:
+
+- **`src/shared/scripts/skf-emit-result-envelope.py`** — `skf-setup`-specific. Writes a different envelope (`SKF_SETUP_RESULT_JSON: {…}`) following the JSON schema at `src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`. Carries setup-specific fields (`tier`, `previous_tier`, `tools`, `ccc_index`, `tier_override_*`, `qmd_status`, etc.) that have no analogue in other workflows. **Do not reuse for non-skf-setup skills.**
+
+A generalised emitter (matching this document's schema) is a reasonable future helper when a second consumer materialises with the same shape. For now, skills that write this contract assemble the JSON in their terminal step — the work is small (5–8 fields) and skill-specific summary content benefits from being expressed inline alongside the rest of the step's logic.
+
+skf-quick-skill writes both the success-variant contract (`step-06-finalize.md` §3) and the error-variant contract on every HARD HALT (per `SKILL.md` § "Result Contract on HARD HALT") in this hand-assembled style.

package/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json",
+  "title": "SKF_SETUP_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document emitted by skf-setup step-04 §4 when {headless_mode} is true, prefixed with the literal 'SKF_SETUP_RESULT_JSON: '. Pipelines grep one line out of the workflow log without parsing ASCII-art and without racing the forge-tier.yaml writer. Schema added in PR #247, extended in PR #248 (header / outputs / failure modes), extended again in this PR with previous_tier / tier_changed / tools_added / tools_removed / error.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["skf_setup"],
+  "properties": {
+    "skf_setup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "tier",
+        "previous_tier",
+        "tier_changed",
+        "tools",
+        "tools_added",
+        "tools_removed",
+        "config_path",
+        "ccc_index",
+        "files_written",
+        "tier_override_active",
+        "tier_override_invalid",
+        "require_tier_satisfied",
+        "warnings",
+        "error"
+      ],
+      "properties": {
+        "tier": {
+          "type": "string",
+          "enum": ["Quick", "Forge", "Forge+", "Deep"],
+          "description": "Active capability tier this run."
+        },
+        "previous_tier": {
+          "type": ["string", "null"],
+          "enum": ["Quick", "Forge", "Forge+", "Deep", null],
+          "description": "Tier read from the existing forge-tier.yaml at workflow start. Null on first runs."
+        },
+        "tier_changed": {
+          "type": "boolean",
+          "description": "True when previous_tier is non-null AND differs from tier. False on first runs and same-tier re-runs. Lets pipelines react to upgrades without re-reading forge-tier.yaml."
+        },
+        "tools": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["ast_grep", "gh_cli", "qmd", "ccc"],
+          "properties": {
+            "ast_grep": { "type": "boolean" },
+            "gh_cli": { "type": "boolean" },
+            "qmd": { "type": "boolean" },
+            "ccc": { "type": "boolean" }
+          }
+        },
+        "tools_added": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["ast_grep", "gh_cli", "qmd", "ccc"] },
+          "uniqueItems": true,
+          "description": "Tool keys with available=true that were NOT available in previous_tools. On first runs, equals the currently-detected tools."
+        },
+        "tools_removed": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["ast_grep", "gh_cli", "qmd", "ccc"] },
+          "uniqueItems": true,
+          "description": "Tool keys that were available in previous_tools but are NOT available now."
+        },
+        "config_path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Absolute path to the forge-tier.yaml that this run wrote (or attempted to write — see error)."
+        },
+        "ccc_index": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status", "indexed_path", "file_count"],
+          "properties": {
+            "status": {
+              "type": "string",
+              "enum": ["fresh", "created", "failed", "none"]
+            },
+            "indexed_path": { "type": ["string", "null"] },
+            "file_count": { "type": ["integer", "null"], "minimum": 0 }
+          }
+        },
+        "files_written": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["forge-tier.yaml", "preferences.yaml", "settings.yml", "ccc_index"]
+          },
+          "uniqueItems": true,
+          "description": "Files actually written this run. Empty array when a write failure halted the run before any file was written."
+        },
+        "tier_override_active": {
+          "type": "boolean",
+          "description": "True when a valid tier_override from preferences.yaml was applied."
+        },
+        "tier_override_invalid": {
+          "type": "boolean",
+          "description": "True when tier_override was set but did not match Quick|Forge|Forge+|Deep (case-sensitive). Detected tier was used as fallback."
+        },
+        "require_tier_satisfied": {
+          "type": ["boolean", "null"],
+          "description": "Null when --require-tier was not set. Otherwise true if the tool prerequisites of the requested tier are met (Deep does NOT subsume Forge+)."
+        },
+        "warnings": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Non-fatal anomalies surfaced during the run. May include tier_override_invalid, tier_override_unsafe, ccc_exclusion_warnings entries, ccc_registry_stale_removed entries, qmd_daemon_stopped, ccc_indexing_failed, etc. Empty when none."
+        },
+        "error": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["phase", "path", "reason"],
+              "properties": {
+                "phase": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Step or operation that failed (e.g. 'step-02-write-config:forge-tier.yaml')."
+                },
+                "path": { "type": "string", "minLength": 1, "description": "Absolute path of the file the failed operation targeted." },
+                "reason": { "type": "string", "minLength": 1, "description": "Human-readable error message." }
+              }
+            }
+          ],
+          "description": "Null on success. Object describing the failure when forge-tier.yaml or preferences.yaml could not be written. Pipelines branch on error !== null for 'exit code 2' semantics."
+        }
+      }
+    }
+  }
+}