bmad-module-skill-forge 0.2.0 → 0.4.0

package/docs/concepts.md

@@ -0,0 +1,96 @@
+---
+title: Concepts
+description: Plain-English definitions of key Skill Forge terms — agent skills, provenance, confidence tiers, drift, and more
+---
+
+# Concepts
+
+This page defines the key terms you'll encounter in Skill Forge. Each one is explained in plain English with a concrete example.
+
+---
+
+## Agent Skills
+
+An agent skill is an instruction file that tells an AI agent how to use your code. Instead of the agent guessing your API from its training data, it reads the skill and gets real function names, real parameter types, and real usage patterns.
+
+Skills follow the [agentskills.io](https://agentskills.io) open standard, so they work across Claude, Cursor, Copilot, and other AI tools.
+
+**Example:** A skill for `better-auth` tells your agent: "The function is `authClient.signIn.email()`, it takes `{ email: string, password: string }`, and it returns a `Promise<Session>`. Here's the source: `src/client.ts:L47`."
+
+---
+
+## Provenance
+
+Provenance means every instruction in a skill traces back to where it came from. For code, that's a file and line number. For documentation, it's a URL. For developer discourse, it's an issue or PR reference. If SKF can't point to a source, it doesn't include the instruction.
+
+**Examples** (from a [real generated skill](https://github.com/armelhbobdad/oh-my-skills)):
+- `[AST:cognee/api/v1/search/search.py:L26]` — extracted from source code via AST parsing
+- `[SRC:cognee/api/v1/session/__init__.py:L8]` — read from source code without AST verification
+- `[EXT:docs.cognee.ai/getting-started/quickstart]` — sourced from external documentation
+- `[QMD:cognee-temporal:issues.md]` — surfaced from indexed developer discourse
+
+---
+
+## Confidence Tiers (T1/T2/T3)
+
+Each piece of information in a skill carries a confidence level based on where it came from:
+
+- **T1 — AST extraction:** Pulled directly from source code via AST parsing. This is structural truth — the function signature actually exists in the code right now.
+- **T2 — Evidence:** Found in issues, PRs, changelogs, or documentation within the repository. Reliable context, but not as definitive as code.
+- **T3 — External:** Pulled from external documentation or websites. Treated with caution and clearly marked.
+
+**Example:** A function signature is T1. A deprecation warning from a closed GitHub issue is T2. A usage example from a blog post is T3.
+
+---
+
+## Capability Tiers (Quick/Forge/Deep)
+
+Your capability tier depends on which tools you have installed. Each tier builds on the previous one:
+
+- **Quick** — GitHub CLI only. SKF reads source files and builds best-effort skills. Works in under a minute.
+- **Forge** — Adds [ast-grep](https://ast-grep.github.io). SKF uses AST parsing for structural truth. Instructions are verified against the actual code structure.
+- **Deep** — Adds [QMD](https://github.com/tobi/qmd). SKF indexes knowledge for semantic search. Skills get enriched with historical context, deprecation warnings, and cross-reference intelligence.
+
+You don't need all tools to start. SKF detects what you have and sets your tier automatically. See [How It Works](../architecture.md) for the full technical treatment.
+
+---
+
+## Drift
+
+Drift happens when the source code changes but the skill instructions haven't been updated to match. A skill might still reference a function that was renamed, removed, or had its signature changed.
+
+SKF detects drift by comparing the skill's recorded provenance against the current code. The `audit-skill` workflow (`@Ferris AS`) scans for these mismatches.
+
+**Example:** Your skill says `createUser(name: string)` but the function was renamed to `registerUser(name: string, email: string)` in the last release. That's drift.
+
+---
+
+## Version Pinning
+
+Every skill records the exact version (or commit) of the source code it was built from. This means you always know which version of the library the instructions apply to.
+
+When the source updates, you can re-run `@Ferris US` (update-skill) to regenerate the skill for the new version while preserving any manual additions you've made.
+
+---
+
+## BMAD Module
+
+SKF is a plugin (called a "module") for the [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD), a framework for running structured AI workflows. BMad provides the workflow engine — step-by-step execution, shared knowledge bases, and consistent outputs. SKF plugs into that engine and focuses specifically on skill compilation.
+
+You don't need to know BMad to use SKF. The standalone installer sets everything up.
+
+---
+
+## Ferris
+
+Ferris is the AI agent persona that runs all SKF workflows. When you type `@Ferris CS`, you're telling Ferris to run the create-skill workflow.
+
+Ferris switches between four modes depending on which workflow is active: Architect (exploring and building), Surgeon (precise updates), Audit (quality checks), and Delivery (packaging for distribution).
+
+---
+
+## Zero Hallucination
+
+SKF's core principle: if an instruction can't be traced back to actual source code, it doesn't get included in the skill. This is the opposite of how most AI tools work — they generate plausible-sounding content from training data. SKF only includes what it can verify.
+
+This doesn't mean skills are perfect. Quick-tier skills read source files without AST verification, so they rely on best-effort extraction. But even Quick skills cite their sources, and no tier includes invented information.

package/docs/examples.md

@@ -9,6 +9,45 @@ This section provides practical examples for using SKF: Skill Forge.
 
 ---
 
+## What the Output Looks Like
+
+When SKF generates a skill, you get a `SKILL.md` file with machine-readable frontmatter and provenance-backed instructions. Here's a trimmed example from a real skill generated for [cognee](https://github.com/topoteretes/cognee) (browse the full output at [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills)):
+
+**Frontmatter (tells AI agents when to load this skill):**
+
+```yaml
+name: cognee
+description: Use when cognee is a Python AI memory engine that transforms
+  documents into knowledge graphs with vector and graph storage for semantic
+  search and reasoning. Use this skill when writing code that calls cognee's
+  Python API (add, cognify, search, memify, config, datasets, prune, session).
+```
+
+**Body (what your AI agent reads):**
+
+```
+## Key API Summary
+
+| Function | Purpose | Key Params | Source |
+|----------|---------|------------|--------|
+| add() | Ingest text, files, binary data | data, dataset_name | [AST:cognee/api/v1/add/add.py:L22] |
+| cognify() | Build knowledge graph | datasets, graph_model | [AST:cognee/api/v1/cognify/cognify.py:L47] |
+| search() | Query knowledge graph | query_text, query_type | [AST:cognee/api/v1/search/search.py:L26] |
+| memify() | Enrich graph with custom tasks | extraction_tasks, data | [AST:cognee/modules/memify/memify.py:L27] |
+| session.* | Session history and feedback | get_session(), add_feedback() | [SRC:cognee/api/v1/session/__init__.py:L8] |
+| DataPoint | Base class for custom graph nodes | inherit and add fields | [EXT:docs.cognee.ai/guides/custom-data-models] |
+```
+
+Provenance tags trace each instruction to its source:
+- `[AST:file:line]` — extracted from code via AST parsing (highest confidence)
+- `[SRC:file:line]` — read from source code without AST verification
+- `[EXT:url]` — sourced from external documentation
+- `[QMD:collection:doc]` — surfaced from indexed developer discourse (issues, PRs, changelogs)
+
+See [How It Works](../architecture.md) for the full output structure.
+
+---
+
 ## Example Workflows
 
 ### Quick Skill — 47 Seconds
@@ -93,7 +132,17 @@ Checks ecosystem first. If no official skill exists: generates from source. `sou
 
 No source code available — only documentation.
 
-Generate from docs + QMD-indexed content. T2/T3 confidence only. `source_authority: community`.
+```
+@Ferris BS
+# When asked for target, provide documentation URLs:
+# https://docs.cognee.ai/
+# Ferris sets source_type: "docs-only" and collects doc_urls
+@Ferris CS
+# step-03 skips (no source), step-03c fetches docs via doc_fetcher
+# All content is T3 [EXT:url] confidence. source_authority: community
+```
+
+The brief's `doc_urls` field drives the doc_fetcher step. The agent uses whatever web fetching tool is available in its environment (Firecrawl, WebFetch, curl, etc.) to retrieve documentation as markdown and extract API information with T3 citations.
 
 ---
 
@@ -139,6 +188,7 @@ Quick mode reads source without AST analysis. Install ast-grep to upgrade to For
 
 - Run `/bmad-help` — analyzes your current state and suggests what to do next
   (e.g. `/bmad-help my batch creation failed halfway, how do I resume?`)
+  *Provided by the [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD) — not available in standalone SKF installations.*
 - Run `@Ferris SF` to check your current tier and tool availability
-- Review `forge-config.yaml` for runtime configuration
+- Review `forge-tier.yaml` in your forger sidecar for runtime configuration
 - Check module configuration in your BMAD settings

package/docs/getting-started.md

@@ -11,7 +11,7 @@ Welcome to Skill Forge! This guide will help you get up and running.
 
 ## What This Module Does
 
-Skill Forge is an automated skill compiler for the AI agent ecosystem. It transforms code repositories, documentation websites, and developer discourse into agentskills.io-compliant, version-pinned, provenance-backed agent skills. Every instruction traces to actual code — zero hallucination tolerance.
+Skill Forge analyzes code repositories, documentation websites, and developer discourse to build verified instruction files ("skills") for AI agents. Instead of your agent guessing API calls from training data, it follows instructions where every function, type, and pattern traces back to its source — a file and line for code, a URL for documentation, an issue or PR for discourse. Skills comply with the [agentskills.io](https://agentskills.io) open standard and work across Claude, Cursor, Copilot, and other AI tools. See the [Concepts](../concepts.md) page for definitions of key terms.
 
 ---
 
@@ -22,11 +22,9 @@ There are three ways to install SKF, depending on your setup.
 ### Standalone (recommended for trying SKF)
 
 ```bash
-npx skill-forge install
+npx bmad-module-skill-forge install
 ```
 
-Or equivalently: `npx bmad-module-skill-forge install`
-
 Installs SKF on its own. You'll be prompted for project name, output folders, and which IDEs to configure. The installer generates IDE-specific command files (e.g. `.claude/commands/`, `.cursor/commands/`) so workflows appear in your IDE's command palette.
 
 ### As a custom module during BMad Method installation
@@ -48,7 +46,7 @@ This installs BMad core + SKF together with full IDE integration, manifests, and
 If you already have BMad installed, you can add SKF afterward by running the standalone installer in the same directory:
 
 ```bash
-npx skill-forge install
+npx bmad-module-skill-forge install
 ```
 
 The installer detects the existing `_bmad/` directory and installs SKF alongside your current modules.
@@ -57,13 +55,30 @@ The installer detects the existing `_bmad/` directory and installs SKF alongside
 
 ## Prerequisites
 
-| Tool                                                                   | Required For       | Install                     |
-|------------------------------------------------------------------------|--------------------|-----------------------------|
-| `gh` (GitHub CLI)                                                      | All modes          | <https://cli.github.com>      |
-| `ast-grep`  (CLI tool for code structural search, lint, and rewriting) | Forge + Deep modes | <https://ast-grep.github.io>  |
-| `qmd` (local hybrid search engine for markdown)                        | Deep mode          | <https://github.com/tobi/qmd> |
+| Tool                                                                   | Required For               | Install                                                |
+|------------------------------------------------------------------------|----------------------------|--------------------------------------------------------|
+| [Node.js](https://nodejs.org/) >= 22                                   | Installation, npx commands | <https://nodejs.org>                                   |
+| `gh` (GitHub CLI)                                                      | All modes                  | <https://cli.github.com>                               |
+| `ast-grep`  (CLI tool for code structural search, lint, and rewriting) | Forge + Deep modes         | <https://ast-grep.github.io>                           |
+| `ast-grep` MCP server (recommended alongside CLI)                      | Forge + Deep modes         | <https://github.com/ast-grep/ast-grep-mcp>             |
+| `qmd` (local hybrid search engine for project files)                   | Deep mode                  | <https://github.com/tobi/qmd>                          |
+| `SNYK_TOKEN` (Snyk API token — **Enterprise plan required**)           | Optional security scan     | <https://docs.snyk.io/snyk-api/authentication-for-api> |
+
+Don't worry if you don't have all tools — SKF detects what's available and sets your tier automatically. Security scanning via Snyk is optional and requires an Enterprise plan; it does not affect your tier level.
+
+---
+
+## Configuration
+
+SKF has two install-time variables (defined in `src/module.yaml`) and one runtime preference:
+
+| Variable               | Purpose                                                                                              | Default                     |
+|------------------------|------------------------------------------------------------------------------------------------------|-----------------------------|
+| `skills_output_folder` | Where generated skills are saved                                                                     | `{project-root}/skills`     |
+| `forge_data_folder`    | Where workspace artifacts are stored                                                                 | `{project-root}/forge-data` |
+| `tier_override`        | Force a specific tier for comparison or testing (in `_bmad/_memory/forger-sidecar/preferences.yaml`) | `~` (auto-detect)           |
 
-Don't worry if you don't have all tools — SKF detects what's available and sets your tier automatically.
+Runtime configuration (tool detection, tier, parallel settings) is managed by the `setup-forge` workflow in `forge-tier.yaml`.
 
 ---
 
@@ -148,13 +163,13 @@ Analyze Source scans the project, identifies skillable units, maps exports, and
 
 ### I want the highest accuracy possible
 
-Quick mode reads source files. Forge mode adds AST parsing for structural truth. Deep mode goes further — QMD indexes your project's markdown (docs, changelogs, issues, migration guides) into searchable collections, then uses BM25 keyword search, vector semantic search, and LLM-powered re-ranking to surface context no other tool can find.
+Quick mode reads source files. Forge mode adds AST parsing for structural truth. Deep mode goes further — as skills are compiled, SKF indexes curated extraction artifacts and skill briefs into QMD collections, then uses BM25 keyword search, vector semantic search, and LLM-powered re-ranking to surface context no other tool can find.
 
 ```
 @Ferris SF    # Setup detects your tools and sets tier automatically
 ```
 
-If `ast-grep` and `qmd` are available, Ferris activates Deep mode. Every skill gets AST-verified signatures (T1) enriched with deep knowledge search (T2) — deprecation warnings, breaking change history, common pitfalls surfaced by hybrid search across your indexed documentation.
+If `ast-grep` and `qmd` are available, Ferris activates Deep mode. Every skill gets AST-verified signatures (T1) enriched with deep knowledge search (T2) — deprecation warnings, breaking change history, common pitfalls surfaced by searching across your indexed skill artifacts.
 
 ### I maintain an OSS library and want official skills
 
@@ -194,5 +209,6 @@ Your existing skill is now out of date. Audit detects the drift, Update regenera
 If you run into issues:
 1. Run `/bmad-help` — analyzes your current state and suggests what to do next
    (e.g. `/bmad-help my quick skill has low confidence scores, how do I improve them?`)
+   *Provided by the [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD) — not available in standalone SKF installations.*
 2. Run `@Ferris SF` to check your tool availability and tier
-3. Check `forge-config.yaml` for your current configuration
+3. Check `forge-tier.yaml` in your forger sidecar for your current configuration

package/docs/index.md

@@ -1,10 +1,10 @@
 ---
 title: Skill Forge (SKF)
-description: AST-verified, provenance-backed agent skills from code repositories, documentation, and developer discourse
+description: Turn code and docs into instructions AI agents can actually follow
 template: splash
 hero:
   title: Skill Forge (SKF)
-  tagline: AST-verified, provenance-backed agent skills from code repositories, documentation, and developer discourse
+  tagline: Turn code and docs into instructions AI agents can actually follow.
   actions:
     - text: Getting Started
       link: ./getting-started/
@@ -15,60 +15,35 @@ hero:
       icon: external
 ---
 
-## What is Skill Forge?
+## What does Skill Forge do?
 
-Skill Forge is an automated skill compiler for the AI agent ecosystem. It transforms code repositories, documentation, and developer discourse into [agentskills.io](https://agentskills.io)-compliant, version-pinned, provenance-backed agent skills. Every instruction traces to verifiable sources — zero hallucination tolerance.
-
-- **AST-Verified**: Structural truth via ast-grep — no guessing, no hallucination.
-- **Provenance-Backed**: Every claim traces to source code with file and line references.
-- **Progressive Tiers**: Quick (no setup) → Forge (ast-grep) → Deep (QMD knowledge).
-- **Ecosystem-First**: Checks for official skills before generating community ones.
+AI agents hallucinate API calls. They invent function names, guess parameter types, and produce code that doesn't compile. Skill Forge fixes this by analyzing code repositories, documentation, and developer discourse — extracting real signatures and patterns and compiling them into verified instruction files that any AI agent can follow. Every instruction traces back to where it came from.
 
 ## Quick Install
 
-**Standalone:**
+Requires [Node.js](https://nodejs.org/) >= 22.
 
 ```bash
-npx skill-forge install
+npx bmad-module-skill-forge install
 ```
 
-**Or as a custom module with BMad Method** (for the full development workflow):
+Then set up your environment and generate your first skill:
 
-```bash
-npx bmad-method install    # select "Add custom modules" and point to src/
 ```
-
-Then interact with the forge agent:
-
+@Ferris SF              # Set up your forge
+@Ferris QS <package>    # Generate a skill in under a minute
 ```
-@Ferris SF    # Setup your forge environment
-@Ferris QS    # Quick Skill — generate in under a minute
-```
-
-See the [Getting Started](./getting-started.md) guide for all installation methods.
-
-## Core Workflows
 
-| Workflow | Trigger | Purpose |
-|----------|---------|---------|
-| [Setup Forge](/workflows/#setup-forge-sf) | SF | Initialize forge, detect tools, set tier |
-| [Brief Skill](/workflows/#brief-skill-bs) | BS | Scope and design a skill |
-| [Create Skill](/workflows/#create-skill-cs) | CS | Compile a skill from a brief |
-| [Quick Skill](/workflows/#quick-skill-qs) | QS | Fast skill, no brief needed |
-| [Stack Skill](/workflows/#stack-skill-ss) | SS | Consolidated project stack skill |
-| [Update Skill](/workflows/#update-skill-us) | US | Regenerate after source changes |
-| [Audit Skill](/workflows/#audit-skill-as) | AS | Drift detection |
-| [Test Skill](/workflows/#test-skill-ts) | TS | Verify completeness |
-| [Export Skill](/workflows/#export-skill-ex) | EX | Package for distribution |
-| [Analyze Source](/workflows/#analyze-source-an) | AN | Discover what to skill |
+See the [Getting Started](./getting-started/) guide for full installation and usage instructions.
 
 ## Documentation
 
-- **[Getting Started](./getting-started.md)** — Installation, prerequisites, first steps
-- **[Architecture](./architecture.md)** — Output format, confidence model, tiers, tool ecosystem
-- **[Agents](./agents.md)** — Ferris agent: modes, capabilities, communication style
-- **[Workflows](./workflows.md)** — All 10 workflows with commands and connection diagram
-- **[Examples](./examples.md)** — Real-world scenarios, tips, and troubleshooting
+- **[Getting Started](./getting-started/)** — Installation, prerequisites, and your first skill
+- **[Concepts](./concepts/)** — Plain-English definitions of key terms (provenance, tiers, drift, and more)
+- **[How It Works](./architecture/)** — Architecture, capability model, output format, and design decisions
+- **[Workflows](./workflows/)** — All 10 workflows with commands and connection diagrams
+- **[Agents](./agents/)** — Ferris: the AI agent that runs all SKF workflows
+- **[Examples](./examples/)** — Real-world scenarios, tips, and troubleshooting
 
 ## Support
 

package/docs/workflows.md

@@ -5,7 +5,7 @@ description: All 10 SKF workflows with commands, steps, and connection diagram
 
 # Workflows Reference
 
-SKF includes 10 workflows organized by purpose:
+SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.md), the AI agent that runs everything. Each workflow handles a specific part of the skill lifecycle — from analyzing source code to packaging for distribution. If any terms are unfamiliar, see the [Concepts](../concepts.md) page for plain-English definitions.
 
 ---
 
@@ -15,11 +15,11 @@ SKF includes 10 workflows organized by purpose:
 
 **Command:** `@Ferris SF`
 
-**Purpose:** Initialize forge environment, detect tools, set capability tier, auto-index project.
+**Purpose:** Initialize forge environment, detect tools, set capability tier, verify QMD collection health.
 
 **When to Use:** First time using SKF in a project. Run once per project.
 
-**Key Steps:** Detect tools → Determine tier → Create forge-config.yaml → Auto-index (Deep)
+**Key Steps:** Detect tools → Determine tier → Write forge-tier.yaml → QMD hygiene (Deep)
 
 **Agent:** Ferris (Architect mode)
 

package/package.json

@@ -1,14 +1,17 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.2.0",
-  "description": "BMAD module — AST-verified, provenance-backed agent skills compiler with progressive capability tiers (Quick/Forge/Deep)",
+  "version": "0.4.0",
+  "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Deep).",
   "keywords": [
     "bmad",
+    "bmad-method",
+    "bmad-module",
     "agent-skills",
     "agentskills",
     "skill-forge",
     "ast-grep",
+    "qmd",
     "provenance",
     "code-analysis"
   ],
@@ -20,8 +23,7 @@
   "author": "armelhbobdad",
   "main": "tools/cli/skf-cli.js",
   "bin": {
-    "bmad-module-skill-forge": "tools/skf-npx-wrapper.js",
-    "skill-forge": "tools/skf-npx-wrapper.js"
+    "bmad-module-skill-forge": "tools/skf-npx-wrapper.js"
   },
   "scripts": {
     "docs:build": "node tools/build-docs.js",

package/src/forger/forge-tier.yaml

@@ -8,6 +8,6 @@ tools:
   qmd: ~
 
 # Capability tier (derived from tool availability)
-# Quick = no tools | Forge = ast-grep | Deep = ast-grep + gh + qmd
+# Quick = no tools required | Forge = + ast-grep | Deep = + ast-grep + gh + QMD
 tier: ~
 tier_detected_at: ~

package/src/forger/preferences.yaml

@@ -1,5 +1,12 @@
 # Ferris Sidecar: User Preferences
-# Written by setup-forge workflow on first run
+# Created by setup-forge workflow on first run
+# Edit this file to customize Ferris behavior
+
+# Override detected tier (set to Quick, Forge, or Deep to force a tier)
+tier_override: ~
+
+# Passive context injection (set to false to skip snippet generation and CLAUDE.md updates during export)
+passive_context: true
 
 # Language defaults
 output_language: ~

package/src/knowledge/doc-fetcher.md

@@ -0,0 +1,55 @@
+# Doc Fetcher
+
+## Purpose
+
+T3 external documentation fetching retrieves content from URLs specified in the extraction brief. It serves as the primary extraction source in Scenario D (docs-only, SaaS, closed-source) where no source code is available, and as a supplemental source when a brief includes `doc_urls` alongside a source repository.
+
+## Tool-Agnostic Principle
+
+`doc_fetcher` is not a wrapper around any specific CLI tool. The LLM agent uses whatever web fetching capability is available in its environment — Firecrawl MCP, WebFetch, curl, browser automation tools, or any other URL retrieval mechanism. The extraction workflow never assumes a particular fetching tool exists; it discovers available capabilities at runtime and uses the best option present.
+
+## T3 Quarantine Rules
+
+All content obtained through doc fetching is classified as **external, untrusted** and subject to quarantine constraints:
+
+1. **Citation format** — every doc-fetched claim uses `[EXT:{url}]` citation format
+2. **Conflict resolution priority** — T3 has the lowest priority: `T1 > T2 > source reading > T3`
+3. **Source authority cap** — T3 content forces `source_authority: community` in metadata; it never qualifies as `official`
+4. **No structural claims** — T3 cannot assert verified signatures or line-level precision
+
+## When to Use
+
+| Scenario | Role | Example |
+| --- | --- | --- |
+| Scenario D — docs-only / SaaS / closed-source | **Primary source** | Stripe API, Twilio SDK docs |
+| Brief includes `doc_urls` alongside source repo | **Supplemental enrichment** | README links, hosted API reference |
+
+When used as supplemental enrichment, T3 content adds context but never overrides T1 or T1-low claims extracted from the actual source code.
+
+## Security Considerations
+
+- URLs specified in the brief are transmitted to external services for content extraction — the agent must inform the user which URLs will be fetched before initiating retrieval
+- Fetched content should not be trusted as authoritative; it may be outdated, modified, or incorrect
+- The agent should not follow redirects to unexpected domains without user confirmation
+
+## Interaction with Other Tiers
+
+- **T3 never replaces T1 (AST) or T2 (QMD)** content for the same export — quarantine rules enforce this
+- **Deep tier**: T3 content can be enriched by QMD (T2 annotations layered onto a T3 base), producing richer output while preserving the T3 confidence label on the base claim
+- **Forge tier**: T3 content exists alongside T1 AST content; T1 takes precedence for any overlapping claims
+- **Quick tier**: T3 may be the only external enrichment available, but T1-low source-read claims still outrank it
+
+## Anti-Patterns
+
+- Citing doc-fetched content with `[AST:...]` or `[SRC:...]` format — always use `[EXT:{url}]`
+- Promoting T3 claims to `source_authority: official` regardless of the documentation source
+- Fetching URLs without informing the user which external services will be contacted
+- Using T3 content to override a contradicting T1 or T1-low extraction
+
+## Related Fragments
+
+- [confidence-tiers.md](confidence-tiers.md) — tier definitions, citation formats, and precedence rules
+- [progressive-capability.md](progressive-capability.md) — how capability tiers determine available extraction methods
+- [zero-hallucination.md](zero-hallucination.md) — the foundational principle that T3 quarantine enforces
+
+_Source: consolidated from extraction brief schema, create-skill Scenario D handling, and confidence tier conflict resolution rules_

package/src/knowledge/overview.md

@@ -20,15 +20,16 @@ With knowledge files:
 
 ## Knowledge Map
 
-| File | Purpose | Key Workflows |
-| --- | --- | --- |
-| [zero-hallucination.md](zero-hallucination.md) | Every claim traces to source; uncitable content excluded | AN, BS, CS, QS, SS, US, AS, TS |
-| [confidence-tiers.md](confidence-tiers.md) | T1/T1-low/T2/T3 trust model and citation formats | AN, BS, CS, QS, SS, US, AS, TS, EX |
-| [progressive-capability.md](progressive-capability.md) | Quick/Forge/Deep tier philosophy and behavior adaptation | All 10 |
-| [agentskills-spec.md](agentskills-spec.md) | agentskills.io output format principles and compliance | CS, QS, SS, US, TS, EX |
-| [skill-lifecycle.md](skill-lifecycle.md) | End-to-end pipeline, artifact flow, workflow selection | All 10 |
-| [provenance-tracking.md](provenance-tracking.md) | Provenance-map.json, evidence reports, claim traceability | CS, QS, SS, US, AS, TS |
-| [manual-section-integrity.md](manual-section-integrity.md) | \[MANUAL\] marker preservation and merge algorithm | CS, US, AS, TS, EX |
+| File                                                       | Purpose                                                           | Key Workflows                      |
+|------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------|
+| [zero-hallucination.md](zero-hallucination.md)             | Every claim traces to source; uncitable content excluded          | AN, BS, CS, QS, SS, US, AS, TS     |
+| [confidence-tiers.md](confidence-tiers.md)                 | T1/T1-low/T2/T3 trust model and citation formats                  | AN, BS, CS, QS, SS, US, AS, TS, EX |
+| [progressive-capability.md](progressive-capability.md)     | Quick/Forge/Deep tier philosophy and behavior adaptation          | All 10                             |
+| [agentskills-spec.md](agentskills-spec.md)                 | agentskills.io output format principles and compliance            | CS, QS, SS, US, TS, EX             |
+| [skill-lifecycle.md](skill-lifecycle.md)                   | End-to-end pipeline, artifact flow, workflow selection            | All 10                             |
+| [provenance-tracking.md](provenance-tracking.md)           | Provenance-map.json, evidence reports, claim traceability         | CS, QS, SS, US, AS, TS             |
+| [manual-section-integrity.md](manual-section-integrity.md) | \[MANUAL\] marker preservation and merge algorithm                | CS, US, AS, TS, EX                 |
+| [qmd-registry.md](qmd-registry.md)                         | Progressive QMD collection registry and collection gate principle | SF, BS, CS, US, AS                 |
 
 ## JiT Loading Protocol
 
@@ -39,13 +40,13 @@ With knowledge files:
 
 ## Knowledge vs. Data
 
-| Aspect | Knowledge Files (`knowledge/`) | Data Files (`data/`) |
-| --- | --- | --- |
-| Scope | Cross-cutting, multi-workflow | Single workflow, single step |
-| Content | Principles, patterns, judgment rules | Schemas, templates, scoring formulas |
-| Loading | JiT via index lookup | JiT via step instruction |
-| Examples | Zero hallucination, confidence tiers | skill-brief-schema.md, scoring-rules.md |
-| Stability | Rarely changes | Changes with workflow evolution |
+| Aspect    | Knowledge Files (`knowledge/`)       | Data Files (`data/`)                    |
+|-----------|--------------------------------------|-----------------------------------------|
+| Scope     | Cross-cutting, multi-workflow        | Single workflow, single step            |
+| Content   | Principles, patterns, judgment rules | Schemas, templates, scoring formulas    |
+| Loading   | JiT via index lookup                 | JiT via step instruction                |
+| Examples  | Zero hallucination, confidence tiers | skill-brief-schema.md, scoring-rules.md |
+| Stability | Rarely changes                       | Changes with workflow evolution         |
 
 ## Related Fragments
 

package/src/knowledge/progressive-capability.md

@@ -87,7 +87,7 @@ Deep:   "Full intelligence pipeline — AST verification plus GitHub exploration
 **Context:** The test-skill workflow adjusts scoring weights based on the forge tier.
 
 **Implementation:**
-- **Quick (Naive mode):** Export Coverage 50%, Signature Accuracy 30%, Type Coverage 20%. No coherence check — AST verification unavailable.
+- **Quick (Naive mode):** Export Coverage 45%, Signature Accuracy 25%, Type Coverage 20%, External Validation 10%. No coherence check — AST verification unavailable. When external validation tools (skill-check, tessl) are unavailable, their 10% is redistributed proportionally across the remaining categories.
 - **Forge (Contextual mode):** Export Coverage 40%, Signature Accuracy 25%, Type Coverage 15%, Coherence 20%. Full AST-backed verification.
 - **Deep (Contextual mode):** Same weights as Forge, plus cross-repo verification and QMD coherence checks feed into the coherence score.
 
@@ -104,12 +104,20 @@ When a tool becomes unavailable mid-session (e.g., ast-grep uninstalled between
 3. New extractions use the current tier's capabilities
 4. The tier change is logged in the sidecar for audit trail
 
+When source is remote (GitHub URL) and tier is Forge or Deep:
+1. AST extraction requires local files — ast-grep cannot operate on remote URLs
+2. The extraction step attempts an **ephemeral shallow clone** to a system temp path (if `git` is available)
+3. If the clone succeeds: AST extraction proceeds on the local clone, then the temp directory is cleaned up
+4. If the clone fails (or `git` is unavailable): the step warns the user explicitly and degrades to source reading (T1-low) with actionable guidance
+5. Silent degradation is forbidden — the user must always know when AST extraction was skipped and why
+
 ## Anti-Patterns
 
 - Describing Quick tier as "basic" or "limited" — it is fast and legitimate
 - Requiring ast-grep for workflows that work fine without it (setup-forge, brief-skill)
 - Mixing tier capabilities in a single extraction (e.g., T1 citations when only source reading was used)
 - Failing a workflow because the tier is "too low" — adapt behavior instead
+- Silent degradation when source is remote at Forge/Deep tier — always warn with actionable guidance
 
 ## Related Fragments