bmad-module-skill-forge 0.2.0 → 0.4.0

package/src/knowledge/provenance-tracking.md

@@ -22,7 +22,7 @@ With provenance tracking:
 
 | Artifact | Format | Purpose | Generated By |
 | --- | --- | --- | --- |
-| `provenance-map.json` | JSON | Machine-readable claim-to-source mapping | CS, QS, SS |
+| `provenance-map.json` | JSON | Machine-readable export-to-source mapping | CS, QS, SS |
 | `evidence-report.md` | Markdown | Human-readable extraction summary | CS, QS, SS |
 | Inline citations | `[TAG:path:Lnn]` | Per-claim source reference in SKILL.md | CS, QS, SS, US |
 | `drift-report.md` | Markdown | Findings from source comparison | AS |
@@ -36,35 +36,43 @@ With provenance tracking:
 **Implementation:**
 ```json
 {
-  "version": "1.0",
+  "skill_name": "express-skill",
+  "source_repo": "https://github.com/expressjs/express",
+  "source_commit": "abc1234",
   "generated_at": "2025-01-15T10:30:00Z",
-  "extraction_tier": "forge",
-  "claims": {
-    "createServer": {
+  "entries": [
+    {
+      "export_name": "createServer",
+      "export_type": "function",
+      "params": ["options: ServerOptions"],
+      "return_type": "Server",
       "source_file": "src/server.ts",
-      "line": 23,
-      "confidence": "t1",
+      "source_line": 23,
+      "confidence": "T1",
       "extraction_method": "ast-grep",
-      "ast_node_type": "export_statement > function_declaration",
-      "signature": "createServer(options: ServerOptions): Server"
+      "ast_node_type": "export_statement > function_declaration"
     },
-    "parseConfig": {
+    {
+      "export_name": "parseConfig",
+      "export_type": "function",
+      "params": ["input"],
+      "return_type": null,
       "source_file": "src/config.ts",
-      "line": 45,
-      "confidence": "t1_low",
+      "source_line": 45,
+      "confidence": "T1-low",
       "extraction_method": "source-read",
-      "ast_node_type": null,
-      "signature": "parseConfig(input)"
+      "ast_node_type": null
     }
-  }
+  ]
 }
 ```
 
 **Key Points:**
-- Each claim is keyed by export name for direct lookup
+- Each entry uses structured fields (`export_name`, `params[]`, `return_type`) for incremental updates
 - `ast_node_type` is null for non-AST extractions — never fabricated
-- `extraction_method` distinguishes how the claim was obtained
-- Confidence tier is recorded per-claim, not per-file
+- `extraction_method` distinguishes how the entry was obtained
+- Confidence tier is recorded per-entry, not per-file
+- `params` is an array of typed strings (e.g., `"userId: string"`) — enables param-by-param diffing
 
 ### Example 2: Evidence Report
 
@@ -106,7 +114,7 @@ With provenance tracking:
 **Implementation:** The audit process:
 1. Load the existing `provenance-map.json`
 2. Re-index current source to build a fresh reference (same extraction method)
-3. For each claim in the provenance map, compare against fresh reference:
+3. For each entry in the provenance map, compare against fresh reference:
    - **Signature changed** → CRITICAL or HIGH severity
    - **Export removed** → CRITICAL severity
    - **New export undocumented** → HIGH (if > 3) or MEDIUM (if 1-3)
@@ -128,15 +136,15 @@ With provenance tracking:
 2. Identify claims that need re-extraction (from audit drift report or source change detection)
 3. Re-extract only affected claims using current tier tools
 4. Merge fresh provenance entries into the existing map:
-   - Changed claims: replace with new provenance
-   - Unchanged claims: preserve existing provenance (timestamp unchanged)
+   - Changed entries: replace with new provenance
+   - Unchanged entries: preserve existing provenance (timestamp unchanged)
    - Removed exports: remove from provenance map
    - New exports: add with fresh provenance
 5. Regenerate evidence report reflecting the update
 
 **Key Points:**
-- Selective re-extraction — only changed claims are re-processed
-- Provenance timestamps show when each claim was last verified
+- Selective re-extraction — only changed entries are re-processed
+- Provenance timestamps show when each entry was last verified
 - The merge preserves \[MANUAL\] section provenance (author: "manual", no source location)
 
 ## Inline Citation Rules

package/src/knowledge/qmd-registry.md

@@ -0,0 +1,132 @@
+# QMD Collection Registry
+
+## Principle
+
+QMD collections in the Skill Forge follow a **progressive registry architecture**: workflow steps that produce artifacts index them into QMD collections and register them in `forge-tier.yaml`. Downstream workflow steps discover and query collections through the registry — never by convention or assumption. Collections are created by producers, consumed by searchers, and maintained by a janitor.
+
+## Rationale
+
+Early SKF versions used a blind auto-index strategy: setup-forge would scan all project directories and index them into QMD collections. This created three problems:
+
+- On fresh workspaces, auto-indexing found nothing — wasted work
+- Raw source code indexing produced low signal-to-noise search results
+- No connection between what was indexed and what workflows actually queried
+
+The progressive registry solves all three by indexing **curated workflow artifacts** (extraction snapshots, skill briefs) instead of raw source files, and only when a workflow produces them.
+
+## Architecture
+
+### Roles
+
+| Role | Workflow | Responsibility |
+| --- | --- | --- |
+| **Producer** | brief-skill, create-skill | Creates QMD collections from workflow artifacts and registers them in forge-tier.yaml |
+| **Consumer** | audit-skill, update-skill | Reads the registry, discovers collections by skill name and type, queries via qmd_bridge |
+| **Janitor** | setup-forge | Cross-references live QMD collections against the registry, cleans orphans and stale entries |
+
+### Registry Schema
+
+The `qmd_collections` array lives in `forge-tier.yaml` alongside tool availability and tier:
+
+```yaml
+qmd_collections:
+  - name: "my-lib-extraction"
+    type: "extraction"
+    source_workflow: "create-skill"
+    skill_name: "my-lib"
+    created_at: "2026-03-14"
+  - name: "my-lib-brief"
+    type: "brief"
+    source_workflow: "brief-skill"
+    skill_name: "my-lib"
+    created_at: "2026-03-14"
+```
+
+### Collection Types
+
+| Type | Producer | Content | Primary Consumers |
+| --- | --- | --- | --- |
+| `extraction` | create-skill step-07 | Compiled SKILL.md, references, context-snippet — structured, confidence-rated exports | audit-skill (drift detection), update-skill (T2 enrichment) |
+| `brief` | brief-skill step-05 | skill-brief.yaml — intent, scope, target repository metadata | Portfolio-level search (cross-skill deduplication) |
+| `docs` | create-skill step-03c | Fetched external documentation — API references, guides, usage examples (T3 confidence) | step-04 enrichment (cross-reference doc context with source-extracted functions) |
+
+### Lifecycle
+
+```
+brief-skill writes brief → indexes {name}-brief → registers in forge-tier.yaml
+    ↓
+create-skill fetches docs → indexes {name}-docs → registers in forge-tier.yaml (Deep only)
+    ↓
+create-skill compiles skill → indexes {name}-extraction → registers in forge-tier.yaml
+    ↓
+audit-skill reads registry → queries {name}-extraction for temporal context
+update-skill reads registry → queries {name}-extraction for T2 enrichment
+    ↓
+setup-forge reads registry + QMD state → cleans orphans, removes stale entries
+```
+
+## Collection Gate
+
+A new QMD collection type is justified ONLY when:
+
+1. A specific **workflow step** performs a **programmatic search** against it
+2. The data is not already accessible through existing artifacts (provenance map, file I/O)
+3. QMD search adds value beyond what direct file reading provides
+
+Human readability alone is not sufficient justification — the file is already on disk.
+
+## Rejected Candidates
+
+### Source Clone Indexing
+
+**Proposal:** Clone the target repository and index all source files into QMD.
+
+**Rejection reason:** Freshness problem. A cloned repo is a snapshot pretending to be current. No clear owner for refresh lifecycle. The provenance map already records `file:line` for every export, and ast-grep provides structural queries against local source. QMD indexing of raw source adds noise, not signal.
+
+### Source-Map Indexing
+
+**Proposal:** Index the GitHub API tree response (directory structure + file metadata) as a lightweight `{name}-source-map` collection.
+
+**Rejection reason:** No workflow consumer. Audit-skill already has file paths from provenance-map.json. The source-map would only serve ad-hoc developer queries, which don't justify the collection overhead.
+
+### Analysis Report Indexing
+
+**Proposal:** Index the analyze-source decomposition report as a `{name}-analysis` collection.
+
+**Rejection reason:** Decision artifact, not a compilation input. The analyze-source report tells users which skills to create, but create-stack-skill works from individual skill artifacts, not the analysis report. The only consumer would be a human reading the file — which they can do directly.
+
+## Pattern Examples
+
+### Example 1: Producer Registration (create-skill)
+
+**Context:** After writing all skill artifacts to disk, create-skill registers them with QMD.
+
+**Implementation:** Deep tier only. Atomic replace if collection exists:
+
+```
+qmd collection remove {name}-extraction   (if exists)
+qmd collection add skills/{name} --name {name}-extraction --mask "**/*"
+qmd embed
+```
+
+Then append/replace the registry entry in forge-tier.yaml. Failures never block the workflow. The `qmd embed` call generates vector embeddings required for `vector_search` and `deep_search`.
+
+### Example 2: Consumer Discovery (audit-skill)
+
+**Context:** Audit-skill needs temporal context for drift detection.
+
+**Implementation:** Read `qmd_collections` from forge-tier.yaml. Find entry where `skill_name` matches AND `type` is `"extraction"`. If found, query via qmd_bridge. If not found, log and continue without T2 enrichment — not an error.
+
+### Example 3: Janitor Hygiene (setup-forge)
+
+**Context:** Setup-forge verifies QMD health on every run.
+
+**Implementation:** Cross-reference live QMD collections against registry. Classify as healthy (in both), orphaned (in QMD only), or stale (in registry only). Prompt user before removing orphans. Silently clean stale registry entries.
+
+## Related Fragments
+
+- [progressive-capability.md](progressive-capability.md) — tier model that gates QMD availability to Deep tier
+- [skill-lifecycle.md](skill-lifecycle.md) — end-to-end pipeline showing where producers and consumers sit
+- [provenance-tracking.md](provenance-tracking.md) — provenance map that provides file:line context without QMD
+
+_Source: progressive QMD registry architecture implemented across setup-forge, brief-skill, create-skill, audit-skill, and update-skill workflows_

package/src/knowledge/skf-knowledge-index.csv

@@ -7,3 +7,5 @@ agentskills-spec,agentskills.io Specification,"Format principles — frontmatter
 skill-lifecycle,Skill Lifecycle,"End-to-end pipeline — workflow connections, artifact flow, decision rules for workflow selection","lifecycle,pipeline,workflows,artifacts",core,knowledge/skill-lifecycle.md
 provenance-tracking,Provenance Tracking,"Provenance mechanism — provenance-map.json, evidence reports, claim traceability","provenance,evidence,traceability,citations",core,knowledge/provenance-tracking.md
 manual-section-integrity,Manual Section Integrity,"[MANUAL] preservation — marker format, merge algorithm, orphan detection","manual,preservation,merge,markers",core,knowledge/manual-section-integrity.md
+qmd-registry,QMD Collection Registry,"Progressive registry architecture — producer/consumer/janitor roles, collection gate principle, forge-tier.yaml registry schema","qmd,registry,collections,deep,indexing",core,knowledge/qmd-registry.md
+doc-fetcher,Doc Fetcher,"T3 external documentation — tool-agnostic URL fetching, quarantine rules, conflict resolution","doc-fetcher,t3,external,documentation,quarantine",extended,knowledge/doc-fetcher.md

package/src/module.yaml

@@ -1,7 +1,7 @@
 code: skf
 name: "SKF: Skill Forge — Evidence-Based Agent Skills Compiler"
-header: "Automated skill compiler — AST-verified, provenance-backed agent skills from code repositories, documentation, and developer discourse"
-subheader: "Zero hallucination tolerance. Every instruction traces to code."
+header: "Turn code and docs into instructions AI agents can actually follow"
+subheader: "Every instruction traces to source. Zero hallucination tolerance."
 description: "Skill Forge transforms code repositories, documentation, and developer discourse into agentskills.io-compliant, version-pinned, provenance-backed agent skills. Uses ast-grep for structural truth, QMD for knowledge intelligence, and a progressive capability model (Quick/Forge/Deep). Standalone module — no other modules required. Recommended alongside BMM for full development workflow integration."
 default_selected: false
 

package/src/workflows/analyze-source/data/skill-brief-schema.md

@@ -9,8 +9,8 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | Field | Type | Constraint | Description |
 |-------|------|------------|-------------|
 | name | string | kebab-case `[a-z0-9-]+` | Unique skill identifier |
-| version | string | Semantic `X.Y.Z` | Defaults to `1.0.0` |
-| source_repo | string | GitHub URL or local path | Repository or project root |
+| version | string | Semantic `X.Y.Z` | Auto-detect from source (see Version Detection below), fall back to `1.0.0` |
+| source_repo | string | GitHub URL or local path | Repository or project root (optional when `source_type: "docs-only"`) |
 | language | string | Recognized language | Primary programming language |
 | scope | object | See Scope Object below | Boundary definition |
 | description | string | 1-3 sentences | What the skill covers |
@@ -18,11 +18,29 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | created | string | ISO date `YYYY-MM-DD` | Generation date |
 | created_by | string | user_name from config | Who generated the brief |
 
+## Optional Fields
+
+| Field | Type | Constraint | Description |
+|-------|------|------------|-------------|
+| source_type | string | `source` or `docs-only` | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required |
+| doc_urls | array | `{url, label}` objects | Documentation URLs for T3 content. Required when `source_type: "docs-only"` |
+
+## Version Detection
+
+During brief generation, attempt to auto-detect the source version before defaulting to `"1.0.0"`. Check the first matching file in the source:
+
+- **Python:** `pyproject.toml` `[project] version` (static) → if `dynamic = ["version"]`, check `__init__.py` for `__version__` → `_version.py` if exists → `setup.py` `version=` → `git describe --tags --abbrev=0`
+- **JavaScript/TypeScript:** `package.json` (`"version"`)
+- **Rust:** `Cargo.toml` `[package] version` (static) → if `version = { workspace = true }`, resolve from workspace root `Cargo.toml` → `git describe --tags --abbrev=0`
+- **Go:** version tag from `go.mod` or `git describe --tags --abbrev=0`
+
+If detection succeeds, use the detected version. If it fails or returns a non-semver value, fall back to `"1.0.0"`.
+
 ## Scope Object
 
 ```yaml
 scope:
-  type: full-library | specific-modules | public-api
+  type: full-library | specific-modules | public-api | docs-only
   include:
     - 'src/**/*.ts'          # At least one required
   exclude:
@@ -42,7 +60,8 @@ scope:
 
 ```yaml
 name: '{unit-name}'
-version: '1.0.0'
+version: '{detected-version or 1.0.0}'
+source_type: 'source'
 source_repo: '{project_path}'
 language: '{detected_language}'
 scope:
@@ -66,6 +85,7 @@ created_by: '{user_name}'
 4. **Scope type valid**: Must match one of the three defined types
 5. **Include patterns**: At least one include glob pattern required
 6. **Forge tier match**: Must match value in forge-tier.yaml
+7. **Docs-only mode**: When `source_type: "docs-only"`, `doc_urls` required (>= 1), `source_repo` optional
 
 ## Output Location
 

package/src/workflows/analyze-source/steps-c/step-01-init.md

@@ -72,10 +72,12 @@ Look for {outputFile}.
 ### 2. Verify Prerequisites
 
 **Check forge-tier.yaml:**
-- Look for `{forge_data_folder}/forge-tier.yaml`
-- **IF missing:** HARD HALT — "**Cannot proceed.** forge-tier.yaml not found at `{forge_data_folder}/forge-tier.yaml`. Please run the setup-forge workflow first to configure your forge tier (Quick/Forge/Deep)."
+- Look for `{sidecar_path}/forge-tier.yaml`
+- **IF missing:** HARD HALT — "**Cannot proceed.** forge-tier.yaml not found at `{sidecar_path}/forge-tier.yaml`. Please run the setup-forge workflow first to configure your forge tier (Quick/Forge/Deep)."
 - **IF found:** Read and note the forge tier value
 
+**Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, or Deep), use it instead of the detected tier.
+
 "**Forge tier detected:** {tier} — analysis depth will be calibrated accordingly."
 
 ### 3. Collect Project Path
@@ -84,15 +86,23 @@ Look for {outputFile}.
 
 I'll analyze your project to identify discrete skillable units and produce skill-brief.yaml files for each recommended unit.
 
-**Please provide the project root path to analyze:**
+**Please provide the project root path(s) to analyze:**
+
+This can be:
+- A single root directory of a repo or multi-service project
+- Multiple paths or URLs (comma-separated) for multi-repo analysis (e.g., integration/stack skills)
 
-This should be the root directory of the repo or multi-service project you want to decompose."
+Examples:
+- `/path/to/project`
+- `owner/repo, owner/repo2`
+- `/path/to/project, https://github.com/owner/repo2`"
 
 Wait for user input.
 
-**Validate the path:**
-- Check that the path exists and contains source files
-- **IF invalid:** "That path doesn't appear to be a valid project directory. Please provide the correct path."
+**Validate the path(s):**
+- For each provided path/URL: check that it exists (local) or is accessible (remote)
+- **IF any invalid:** "Path `{path}` doesn't appear to be valid. Please correct it."
+- Store as `project_paths[]` array in report frontmatter (single path stored as 1-element array for consistency)
 
 ### 4. Collect Optional Scope Hints
 
@@ -131,7 +141,7 @@ lastContinued: ''
 date: '{current_date}'
 user_name: '{user_name}'
 project_name: '{project_name}'
-project_path: '{provided_project_path}'
+project_paths: ['{provided_project_path}']
 forge_tier: '{detected_tier}'
 existing_skills: [{list of existing skill names}]
 confirmed_units: []
@@ -163,7 +173,7 @@ Display: "**Proceeding to project scan...**"
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN the output report has been created with populated frontmatter (project_path, forge_tier, existing_skills) will you load and read fully {nextStepFile} to execute and begin the project scan.
+ONLY WHEN the output report has been created with populated frontmatter (project_paths, forge_tier, existing_skills) will you load and read fully {nextStepFile} to execute and begin the project scan.
 
 ---
 

package/src/workflows/analyze-source/steps-c/step-01b-continue.md

@@ -66,7 +66,7 @@ To resume the analyze-source workflow from where it was left off in a previous s
 
 Load {outputFile} and read frontmatter:
 - `stepsCompleted` array
-- `project_path`
+- `project_paths`
 - `project_name`
 - `forge_tier`
 - `existing_skills`
@@ -76,7 +76,7 @@ Load {outputFile} and read frontmatter:
 
 "**Analysis Progress for {project_name}:**
 
-**Project:** {project_path}
+**Project:** {project_paths}
 **Forge Tier:** {forge_tier}
 **Steps Completed:** {list stepsCompleted}
 **Last Step:** {last entry in stepsCompleted}

package/src/workflows/analyze-source/steps-c/step-02-scan-project.md

@@ -38,6 +38,8 @@ To map the complete project structure by scanning directory trees, detecting ser
 - 💬 Use subprocess optimization (Pattern 1) for scanning across many files
 - 📋 Tier-aware scanning depth: Quick (file structure only), Forge (+ manifest parsing), Deep (+ config analysis)
 
+**AST Degradation Fallback:** If the AST tool (ast-grep) is unavailable at Forge or Deep tier, degrade to Quick-tier behavior for this step and emit a warning: "AST tool unavailable — falling back to file-structure scanning for this step."
+
 ## EXECUTION PROTOCOLS:
 
 - 🎯 Follow the MANDATORY SEQUENCE exactly
@@ -59,7 +61,7 @@ To map the complete project structure by scanning directory trees, detecting ser
 ### 1. Load Context
 
 Read {outputFile} frontmatter to obtain:
-- `project_path` — the root to scan
+- `project_paths[]` — the root(s) to scan (one or more paths/URLs)
 - `forge_tier` — determines scanning depth
 - Scope hints (if any were provided in step 01)
 
@@ -67,7 +69,7 @@ Load {heuristicsFile} for reference on detection signals.
 
 ### 2. Scan Directory Structure
 
-Launch a subprocess that scans the project directory structure:
+**For each path in `project_paths[]`**, launch a subprocess that scans the project directory structure (aggregate results across all repos with clear repo-level grouping):
 
 1. Map the top-level directory tree (2-3 levels deep)
 2. Identify workspace configuration files (pnpm-workspace.yaml, lerna.json, Cargo.toml [workspace], go.work, etc.)
@@ -82,6 +84,12 @@ Launch a subprocess that scans the project directory structure:
 - If specific directories were given, scan only those
 - If exclusion patterns were given, skip matching directories
 
+**Deep tier additional scanning (IF Deep tier):**
+- Use ast-grep to detect structural patterns across the codebase: `ast-grep -p 'class $NAME' --lang python` (or equivalent per language) to build a class/type inventory
+- Use ast-grep to identify exported function patterns: `ast-grep -p 'def $FUNC($$$PARAMS)' --lang python` at entry points
+- If QMD is available, query for temporal context on the project: recent changes, active development areas, refactoring patterns
+- Record Deep-tier findings separately — they supplement (not replace) the Quick/Forge scan results
+
 ### 3. Detect Service Boundaries
 
 Based on scan results, identify potential service boundaries:

package/src/workflows/analyze-source/steps-c/step-04-map-and-detect.md

@@ -38,6 +38,8 @@ To analyze each qualifying unit's export surface and import graph, detect cross-
 - 🚫 FORBIDDEN to make recommendations in this step (that's step 05)
 - 📋 Tier-aware depth: Quick (file-level exports), Forge (AST export analysis), Deep (AST + semantic relationships)
 
+**AST Degradation Fallback:** If the AST tool (ast-grep) is unavailable at Forge or Deep tier, degrade to Quick-tier behavior for this step and emit a warning: "AST tool unavailable — falling back to file-level export mapping for this step."
+
 ## EXECUTION PROTOCOLS:
 
 - 🎯 Follow the MANDATORY SEQUENCE exactly
@@ -68,16 +70,28 @@ Load {heuristicsFile} for stack skill candidate detection rules.
 
 DO NOT BE LAZY — For EACH qualifying unit, launch a subprocess (or analyze in main thread) that:
 
+**Size-aware strategy selection:**
+- **< 50 files:** Full export scan — analyze every file for exports
+- **50-200 files:** Targeted scan — entry points (`__init__.py`, `index.ts`, `lib.rs`) + public modules + barrel exports only
+- **200+ files:** Entry-point strategy — analyze top-level entry point for public API surface, list submodule entry points, analyze each submodule entry point only. Report coverage confidence based on percentage of files analyzed.
+
+**Per-unit analysis (scaled by strategy above):**
+
 1. Scans the unit's directory for export/public interface files
 2. Counts and categorizes exports based on forge tier:
    - **Quick tier:** Count files by type, identify index/barrel files, list directory structure
    - **Forge tier:** Parse export statements, identify public API surface, count exported functions/classes/types
-   - **Deep tier:** All Forge analysis plus semantic relationship mapping between exports
+   - **Deep tier:** All Forge analysis plus:
+     - ast-grep structural export extraction: `ast-grep -p 'export $$$' --lang typescript` or equivalent per language to build a verified export inventory
+     - ast-grep type/interface mapping: `ast-grep -p 'interface $NAME' --lang typescript` or `ast-grep -p 'class $NAME($$$)' --lang python`
+     - If QMD available: query for temporal evolution of identified exports (deprecation signals, recent additions, refactoring patterns)
+     - Record semantic relationships between exports (which exports reference/depend on each other)
 3. Returns structured findings to parent:
    - Export count (files, functions, types, classes)
    - Primary export patterns (barrel exports, direct exports, re-exports)
    - Public API surface size estimate
    - Key entry points
+   - Analysis strategy used and coverage confidence
 
 **Per-unit export summary:**
 
@@ -180,11 +194,12 @@ stack_skill_candidates: [{list flagged candidate groupings}]
 
 ### 8. Present MENU OPTIONS
 
-Display: "**Select:** [C] Continue to Recommendations"
+Display: "**Select:** [C] Continue to Recommendations | [D] Discover Additional Source"
 
 #### Menu Handling Logic:
 
 - IF C: Save findings to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
+- IF D: Accept a new repo path/URL from the user. Run a lightweight scan (directory structure + manifest detection from step 02) and classify (unit identification from step 03) for the new source only. Merge results into the existing report — append new units to the unit list, update `project_paths[]` in frontmatter. Then redisplay this step's export mapping for the new units before returning to the menu.
 - IF Any other: help user, then [Redisplay Menu Options](#8-present-menu-options)
 
 #### EXECUTION RULES:

package/src/workflows/analyze-source/steps-c/step-05-recommend.md

@@ -189,12 +189,13 @@ stack_skill_candidates: [{updated list with user decisions}]
 
 ### 8. Present MENU OPTIONS
 
-Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Brief Generation"
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [D] Discover Additional Source [C] Continue to Brief Generation"
 
 #### Menu Handling Logic:
 
 - IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
 - IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
+- IF D: Accept a new repo path/URL from the user. Run a lightweight scan + classify (subset of steps 02-03) for the new source only. Merge new units into the existing report and update `project_paths[]` in frontmatter. Run export mapping for the new units (same logic as step 04 section 2). Generate recommendation cards for the new units and present them for confirmation. Then redisplay this menu.
 - IF C: Save recommendations to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
 - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options)
 

package/src/workflows/analyze-source/steps-c/step-06-generate-briefs.md

@@ -59,7 +59,7 @@ To generate a valid skill-brief.yaml file for each confirmed unit using the sche
 
 Read {outputFile} completely to obtain:
 - `confirmed_units` from frontmatter (names of units approved in step 05)
-- `project_path`, `forge_tier`, `user_name`, `forge_data_folder` from frontmatter
+- `project_paths`, `forge_tier`, `user_name`, `forge_data_folder` from frontmatter
 - Recommendation cards from "## Recommendations" section (proposed brief fields per unit)
 - Export map and integration data from prior sections
 
@@ -78,8 +78,8 @@ For EACH unit in `confirmed_units`, construct a skill-brief.yaml using:
 | Field | Source |
 |-------|--------|
 | name | Confirmed name from step 05 recommendation card |
-| version | `1.0.0` (default for new briefs) |
-| source_repo | `{project_path}` from frontmatter |
+| version | Auto-detect from source (see schema Version Detection), fall back to `1.0.0` |
+| source_repo | `{project_paths[0]}` from frontmatter (or per-unit path if multi-repo) |
 | language | Primary language detected in step 03 |
 | scope.type | Scope type from step 05 recommendation card |
 | scope.include | Include patterns from step 05 recommendation card |

package/src/workflows/analyze-source/templates/analysis-report-template.md

@@ -6,7 +6,7 @@ lastContinued: ''
 date: ''
 user_name: ''
 project_name: ''
-project_path: ''
+project_paths: []
 forge_tier: ''
 existing_skills: []
 confirmed_units: []

package/src/workflows/analyze-source/validation-report.md

@@ -339,7 +339,7 @@ Data files in `data/` support the workflow's inline validation:
 
 | File | Style | Appropriate | Key Language | Status |
 |------|-------|-------------|--------------|--------|
-| step-01-init | Prescriptive | ✅ | "Check forge-tier.yaml", "HARD HALT", "Validate the path" | PASS |
+| step-01-init | Prescriptive | ✅ | "Check forge-tier.yaml", "HARD HALT", "Validate the path", checks `preferences.yaml` for `tier_override` | PASS |
 | step-01b-continue | Prescriptive | ✅ | "Read frontmatter", "Map last completed step to next step" | PASS |
 | step-02-scan-project | Prescriptive | ✅ | "Map top-level directory tree", "Identify workspace configs", "Detect service boundaries" | PASS |
 | step-03-identify-units | Prescriptive | ✅ | "Count detection signals", "Classify boundary type", "Check disqualification rules" | PASS |

package/src/workflows/analyze-source/workflow-plan-analyze-source.md

@@ -207,7 +207,7 @@ Decomposition engine — discover what to skill, recommend stack skill. Analyzes
 ## Tools Configuration
 
 **Core BMAD Tools:**
-- **Party Mode:** excluded — no creative exploration phase in evidence-based analysis
+- **Party Mode:** available at step-05 (recommend) — included as optional [P] menu for creative exploration during collaborative unit review
 - **Advanced Elicitation:** included as optional [A] menu at Step 05 only — quality gate for challenging unit boundary decisions
 - **Brainstorming:** excluded — no ideation needed in code analysis
 

package/src/workflows/analyze-source/workflow.md

@@ -54,7 +54,7 @@ installed_path: '{project-root}/_bmad/skf/workflows/analyze-source'
 
 Load and read full config from {project-root}/_bmad/skf/config.yaml and resolve:
 
-- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `forge_data_folder`, `skills_output_folder`
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `forge_data_folder`, `skills_output_folder`, `sidecar_path`
 
 ### 2. First Step Execution
 

package/src/workflows/audit-skill/steps-c/step-01-init.md

@@ -50,7 +50,8 @@ Load the existing skill artifacts, provenance map, and forge tier configuration
 - Available: User-provided skill path, SKF module config variables
 - Focus: Loading and validating all inputs needed for drift analysis
 - Limits: Do not analyze or compare — only load and baseline
-- Dependencies: setup-forge must be completed (forge-tier.yaml exists), skill must have been created by create-skill (provenance-map.json exists)
+- Dependencies: setup-forge must be completed (forge-tier.yaml exists), skill must have been created by create-skill (provenance-map.json exists for source-based skills)
+- Docs-only limitation: If `metadata.json` indicates `source_type: "docs-only"` or `confidence_tier: "Quick"` with all T3 citations, inform user: "**This is a docs-only skill.** Drift detection compares against upstream documentation, not source code. Re-run `@Ferris US` to re-fetch documentation URLs and detect content changes." Audit-skill's structural diff is not applicable to docs-only skills — recommend update-skill instead.
 
 ## MANDATORY SEQUENCE
 
@@ -84,6 +85,8 @@ Load `{sidecar_path}/forge-tier.yaml` to detect available tools.
 - Extract tier level: Quick / Forge / Deep
 - Extract available tools: gh_bridge, ast_bridge, qmd_bridge
 
+**Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, or Deep), use it instead of the detected tier.
+
 ### 3. Load Skill Artifacts
 
 Load the following from the skill directory:
@@ -93,8 +96,8 @@ Load the following from the skill directory:
 - `metadata.json` — Skill metadata (version, created date, export count)
 
 **Extract from metadata.json:**
-- `skill_name`, `version`, `created` date, `forge_tier` used during creation
-- `source_root` — Original source code path
+- `name`, `version`, `generation_date`, `confidence_tier` used during creation
+- `source_root` — Resolved source code path used during extraction
 
 ### 4. Load Provenance Map
 
@@ -137,7 +140,7 @@ Create `{outputFile}` from `{templateFile}`:
 | Field | Value |
 |-------|-------|
 | **Skill** | {skill_name} v{version} |
-| **Created** | {created_date} |
+| **Created** | {generation_date} |
 | **Source** | {source_path} |
 | **Forge Tier** | {current_tier} (created at {original_tier}) |
 | **Provenance Age** | {days} days since last extraction |
@@ -176,7 +179,7 @@ ONLY WHEN C is selected and the drift report has been created with baseline data
 ### ✅ SUCCESS:
 
 - Skill artifacts loaded (SKILL.md, metadata.json)
-- Forge tier detected from sidecar
+- Forge tier detected from sidecar (and override applied if set in preferences.yaml)
 - Provenance map loaded (or degraded mode confirmed)
 - Source path resolved and validated
 - Drift report created from template with populated frontmatter

package/src/workflows/audit-skill/steps-c/step-02-re-index.md

@@ -97,7 +97,7 @@ Identify all source files in the source directory that contain public exports.
 ```
 {
   "extraction_date": "{timestamp}",
-  "forge_tier": "{tier}",
+  "confidence_tier": "{tier}",
   "source_root": "{source_path}",
   "files_scanned": {count},
   "exports": [
@@ -117,13 +117,23 @@ Identify all source files in the source directory that contain public exports.
 
 **IF forge tier is Deep:**
 
-Query qmd_bridge for temporal context on each extracted export:
+Read the `qmd_collections` registry from `{sidecar_path}/forge-tier.yaml`.
+
+Find the collection entry matching the current skill: look for an entry where `skill_name` matches the current skill being audited AND `type` is `"extraction"`.
+
+**If a matching extraction collection is found:**
+Query qmd_bridge against the `{skill_name}-extraction` collection for temporal context on each extracted export:
 - When was this export first added?
 - Has it been modified recently?
 - What is its usage frequency across the codebase?
+- How does the current extraction compare to the previously compiled skill content?
 
 Append temporal metadata to each export in the snapshot.
 
+**If no matching collection found in registry:**
+Log: "No QMD extraction collection found for {skill_name}. Temporal enrichment skipped. Re-run [CS] Create Skill to generate the collection."
+Continue without T2 enrichment — this is not an error.
+
 **IF forge tier is Quick or Forge:**
 Skip this section. Temporal context requires Deep tier.