bmad-module-skill-forge 0.2.0 → 0.4.0

package/src/workflows/create-skill/data/extraction-patterns.md

@@ -26,13 +26,16 @@ Source reading via gh_bridge — infer exports from file structure and content.
 
 ## Forge Tier (AST Available)
 
-Structural extraction via ast_bridge — verified exports with line-level citations.
+Structural extraction via ast-grep — verified exports with line-level citations.
+
+> **Note:** `ast_bridge.*` and `qmd_bridge.*` references below are **conceptual interfaces**, not callable functions. They describe the operation to perform. Use ast-grep (MCP tool or CLI) for `ast_bridge.*` operations and QMD (MCP tool or CLI) for `qmd_bridge.*` operations. See the AST Extraction Protocol section below and the TOOL/SUBPROCESS FALLBACK rule for dispatch details.
 
 ### Strategy
+
 1. Detect language from brief or file extensions
-2. `ast_bridge.scan_definitions(path, language)` — extract all exports
+2. Use ast-grep to extract all exports from `path` for the given `language` (scan definitions)
 3. For each export: function name, full signature, parameter types, return type, line number
-4. `ast_bridge.detect_co_imports(path, libraries[])` — find integration points
+4. Use ast-grep to detect co-imported symbols in `path` for the given `libraries[]`
 5. Build extraction rules YAML for reproducibility
 
 ### Confidence
@@ -61,3 +64,213 @@ Same extraction as Forge tier. Deep tier adds enrichment in step-04, not extract
 ### Confidence
 - Extraction: same as Forge (T1)
 - Enrichment annotations added in step-04: T2
+
+---
+
+## AST Extraction Protocol
+
+When AST tools are available (Forge/Deep tier), follow this deterministic protocol to prevent output overflow on large codebases.
+
+**"Files in scope"** = files remaining after applying `include_patterns` and `exclude_patterns` from the brief, filtered by the target language extension. This is NOT the total repository file count from step-01's tree listing. Use the filtered count from step-03 section 2 as the decision tree input.
+
+### Decision Tree
+
+Apply the first matching condition:
+
+```
+Files in scope ≤ 100
+  → Use ast-grep MCP tool: find_code(pattern, max_results=100, output_format="text")
+  → Parse compact text output directly into extraction inventory
+
+Files in scope 101–500
+  → Use ast-grep MCP tool: find_code_by_rule(yaml, max_results=150, output_format="text")
+  → Use scoped YAML rules (see recipes below) to filter at the AST level
+  → Parse compact text output into extraction inventory
+
+Files in scope > 500
+  → CLI streaming fallback: ast-grep --json=stream + line-by-line Python processing
+  → Process in directory batches, cap per-batch output
+  → Merge batch results into extraction inventory
+```
+
+### Safety Valve
+
+If any ast-grep operation (MCP or CLI) visibly causes a timeout, returns an error related to output size, or produces unexpectedly large output: immediately switch to the CLI streaming fallback with `--json=stream`. Do not retry the same approach. When falling back to the CLI streaming template, inject the brief's `scope.exclude` patterns into the `EXCLUDES` list (use `[]` if absent) — this applies regardless of which path triggered the fallback. Note: `max_results` in the MCP tool and `| head -N` in the CLI path provide hard caps, but this safety valve covers cases where the upstream tool itself fails before returning results (e.g., OOM during JSON serialization).
+
+### MCP Tool Usage (Preferred)
+
+**Simple pattern search:**
+
+```
+find_code(
+  project_folder="{source_path}",
+  pattern="async def $NAME($$$PARAMS)",
+  language="python",
+  max_results=100,
+  output_format="text"
+)
+```
+
+**Scoped YAML rule search (for larger repos):**
+
+```
+find_code_by_rule(
+  project_folder="{source_path}",
+  yaml="id: public-api\nlanguage: python\nrule:\n  pattern: 'def $NAME($$$PARAMS)'\n  inside:\n    kind: module\n    stopBy: end\nconstraints:\n  NAME:\n    regex: '^[^_]'",
+  max_results=150,
+  output_format="text"
+)
+```
+
+### CLI Streaming Fallback
+
+When MCP tools are unavailable or the repo exceeds 500 files in scope, use `--json=stream` (NEVER `--json` or `--json=pretty`) with line-by-line Python processing:
+
+```bash
+# Note: use $$$ for variadic params in ast-grep patterns (e.g., 'def $NAME($$$PARAMS)')
+# {exclude_patterns} = Python list from brief's scope.exclude, e.g. ['tests/**', '**/test_*']
+# If scope.exclude is absent or empty in the brief, inject [] as the default.
+# Patterns are matched against the full file path as emitted by ast-grep.
+# Ensure paths are relative to the same root as the patterns (strip ./ prefix if needed).
+ast-grep -p '{pattern}' -l {language} --json=stream {path} | python3 -c "
+import sys, json, fnmatch, signal
+signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+
+EXCLUDES = {exclude_patterns}
+
+for line in sys.stdin:
+    try:
+        m = json.loads(line)
+        f = m.get('file','')
+        if EXCLUDES and any(fnmatch.fnmatch(f, pat) for pat in EXCLUDES):
+            continue
+        v = m.get('metaVariables',{})
+        name = v.get('single',{}).get('NAME',{}).get('text','')
+        if name and not name.startswith('_'):
+            ln = m.get('range',{}).get('start',{}).get('line',0)+1
+            sig = m.get('text','').split(chr(10))[0].strip()
+            print(f'[AST:{f}:L{ln}] {sig}')
+    except: pass
+" | head -200
+```
+
+**Critical constraints:**
+
+- ALWAYS use `--json=stream` — never `--json` (loads entire array into memory)
+- ALWAYS process line-by-line (`for line in sys.stdin`) — never `json.load(sys.stdin)`
+- ALWAYS cap output with `| head -N` as a safety valve
+- For repos > 500 files, process in directory batches of 20-50 files each
+
+### YAML Rule Recipes by Language
+
+**Python — public functions:**
+
+```yaml
+id: python-public-functions
+language: python
+rule:
+  pattern: 'def $NAME($$$PARAMS)'
+  inside:
+    kind: module
+    stopBy: end
+constraints:
+  NAME:
+    regex: '^[^_]'
+```
+
+**Python — public classes:**
+
+```yaml
+id: python-public-classes
+language: python
+rule:
+  pattern: 'class $NAME($$$BASES)'
+  inside:
+    kind: module
+    stopBy: end
+constraints:
+  NAME:
+    regex: '^[^_]'
+```
+
+**JavaScript/TypeScript — exported functions:**
+
+```yaml
+id: js-exported-functions
+language: typescript
+rule:
+  pattern: 'export function $NAME($$$PARAMS)'
+```
+
+**JavaScript/TypeScript — exported constants:**
+
+```yaml
+id: js-exported-constants
+language: typescript
+rule:
+  pattern: 'export const $NAME = $VALUE'
+```
+
+**Rust — public functions:**
+
+```yaml
+id: rust-public-functions
+language: rust
+rule:
+  any:
+    - pattern: 'pub fn $NAME($$$PARAMS) -> $RET'
+    - pattern: 'pub fn $NAME($$$PARAMS)'
+```
+
+**Go — exported functions (capitalized):**
+
+```yaml
+id: go-exported-functions
+language: go
+rule:
+  pattern: 'func $NAME($$$PARAMS) $RET'
+constraints:
+  NAME:
+    regex: '^[A-Z]'
+```
+
+### Re-Export Tracing
+
+After initial AST extraction, some top-level exports may resolve to **module imports** rather than direct function definitions. This is common in Python libraries that use `__init__.py` re-exports for a clean public API.
+
+**Detection heuristic:** For each top-level export from `__init__.py` (or equivalent entry point), check if the import path resolves to a directory (contains `__init__.py`) rather than a `.py` file with a matching `def` or `class`. If the initial AST scan found no function/class definition for a known public export, it is likely a module re-export.
+
+**Tracing protocol:**
+
+1. Read the entry point file (e.g., `{package}/__init__.py`) and extract all `from .X import Y` statements
+2. For each import where Y was NOT found by the initial AST scan:
+   - Check if the import path resolves to a directory (e.g., `{package}/api/v1/delete/` exists with `__init__.py`)
+   - If directory: read its `__init__.py` to find the actual re-exported symbol
+   - **Handle aliases:** Check for `from .module import A as B` patterns in the intermediate `__init__.py`. If the parent imports `B`, trace through to `A` in `.module`. If the parent imports `A` but the `__init__.py` only exports it as `B` (via `from .module import A as B`), match by original name `A` and note the alias
+   - Trace the symbol to its definition file and run AST extraction on that file
+3. Cite the actual definition location: `[AST:{definition_file}:L{line}]`
+
+**Examples:**
+
+```python
+# Module re-export — follow required
+from .api.v1.delete import delete    # delete/ is a directory → read delete/__init__.py
+
+# Direct function import — no follow needed
+from .api.v1.add.add import add      # add.py exists with def add()
+
+# Aliased re-export — follow through alias
+# In cognee/api/v1/visualize/__init__.py:
+#   from .start_visualization_server import visualization_server
+# In cognee/__init__.py:
+#   from .api.v1.visualize import start_visualization_server
+# → Match start_visualization_server against both definition names AND alias names
+#   in the intermediate __init__.py to resolve the chain
+```
+
+**Unresolvable imports:** If the import statement is a star-import (`from .X import *`) or a conditional import (`try`/`except`), the symbol cannot be reliably traced via this protocol. Record it with `[SRC:{package}/__init__.py:L{line}]` (T1-low) and a note: "star/conditional import — manual trace required."
+
+**Scope limit:** Only trace re-exports for symbols listed in the top-level entry point's public API. Do not recursively trace beyond one level of `__init__.py` indirection. If a re-export cannot be resolved after one level, record it with a `[SRC:{package}/__init__.py:L{line}]` citation (T1-low) from the import statement itself.
+
+**Other languages:** JS/TS barrel files (`index.ts` with `export { X } from './module'`) follow the same principle — trace the re-export to the definition file. Rust `pub use` and Go package-level re-exports are less common but follow the same heuristic when encountered.
+

package/src/workflows/create-skill/data/skill-sections.md

@@ -2,30 +2,60 @@
 
 ## agentskills.io Compliant Format
 
-### Frontmatter (Required)
+### Frontmatter (Required — agentskills.io Compliance)
 
 ```yaml
 ---
 name: {skill-name}
-version: {source-version}
-description: {skill-name} — {export-count} verified functions
-author: {source-author}
+description: >
+  {Trigger-optimized description of what the skill does and when to use it.
+  Include specific keywords for agent discovery.
+  Mention what NOT to use it for if applicable.
+  1-1024 characters.}
 ---
 ```
 
-### Section Order
+**Frontmatter rules (agentskills.io specification):**
 
-1. **Overview** — What this skill provides, source repo, version, tier used
-2. **Quick Start** — Most common 3-5 functions with minimal examples
-3. **API Reference** — Grouped by module/file, each function with:
-   - Signature with types
-   - Parameters table
-   - Return type
-   - Usage example (from source tests/docs if available)
-   - Provenance citation: `[AST:{file}:L{line}]` or `[SRC:{file}:L{line}]`
-4. **Type Definitions** — Exported types, interfaces, enums
-5. **Integration Patterns** — Co-import patterns detected by ast_bridge (Forge/Deep only)
-6. **Manual Sections** — Seeded with `<!-- [MANUAL] -->` markers for update-skill
+- `name`: 1-64 characters, lowercase alphanumeric + hyphens only, must match parent directory name
+- `description`: 1-1024 characters, trigger-optimized for agent matching
+- Only 6 fields permitted: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`
+- `version` and `author` belong in metadata.json, NOT in frontmatter
+
+### Two-Tier Section Structure
+
+SKILL.md uses a two-tier structure to ensure actionable content survives `split-body` extraction.
+
+#### Tier 1 — Always Inline (survives split-body, target <300 lines)
+
+| # | Section | Budget | Purpose |
+|---|---------|--------|---------|
+| 1 | **Overview** | ~10 lines | What the library does, source repo, version, tier, export count |
+| 2 | **Quick Start** | ~30 lines | 3-5 core functions with one runnable end-to-end example |
+| 3 | **Common Workflows** | ~30 lines | 4-5 typical function call sequences for common tasks |
+| 4 | **Key API Summary** | ~20 lines | Table of top 10-15 functions (name, purpose, key params) |
+| 4b | **Migration & Deprecation Warnings** | ~10 lines | T2-future warnings inline (Deep tier only, skip if none) |
+| 5 | **Key Types** | ~20 lines | Most important enum/type values inline |
+| 6 | **Architecture at a Glance** | ~10 lines | Bullet list of subsystem categories |
+| 7 | **CLI** | ~10 lines | Basic CLI commands (skip if no CLI) |
+| 8 | **Manual Sections** | ~5 lines | `<!-- [MANUAL] -->` markers for update-skill |
+
+#### Tier 2 — Reference-Eligible (extracted by split-body into references/)
+
+| # | Section | Purpose |
+|---|---------|---------|
+| 9 | **Full API Reference** | Complete signatures, parameter tables, return types, examples, citations |
+| 10 | **Full Type Definitions** | All types, interfaces, enums with full field details |
+| 11 | **Full Integration Patterns** | Co-import patterns, adapter details, pipeline internals (Forge/Deep only) |
+
+#### Assembly Rules
+
+- Tier 1 sections are assembled first — they form the standalone body
+- Tier 2 sections are assembled after — they are progressive disclosure detail
+- Tier 1 sections are kept short enough that `split-body` targets the larger Tier 2 sections (`## Full` headings) into `references/`
+- After split-body, SKILL.md retains all Tier 1 content — actionable without loading references
+- An agent loading only SKILL.md (no references) must get enough to act
+- **Section 4b (Migration & Deprecation Warnings)** is conditional: only emitted for Deep tier when T2-future annotations exist. Quick/Forge tiers and Deep tiers without T2-future annotations omit it entirely (no empty section). Parsers and validators must treat this section as optional.
 
 ### Provenance Citation Format
 
@@ -50,15 +80,31 @@ Place after Quick Start and after API Reference sections.
 
 ---
 
-## context-snippet.md Format
+## context-snippet.md Format (Vercel-aligned indexed format)
 
-Compressed 2-line-per-skill format for CLAUDE.md managed section:
+Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per skill). Aligned with Vercel's research finding that retrieval instructions + indexed file maps + inline gotchas dramatically improve agent performance.
 
 ```markdown
-{skill-name} -> skills/{skill-name}/
-  exports: {comma-separated top 10 function names}
+[{skill-name} v{version}]|root: skills/{skill-name}/
+|IMPORTANT: {skill-name} v{version} — read SKILL.md before writing {skill-name} code. Do NOT rely on training data.
+|quick-start:{SKILL.md#quick-start}
+|api: {top exports with () for functions, comma-separated}
+|key-types:{SKILL.md#key-types} — {inline summary of most important type values}
+|gotchas: {2-3 most critical pitfalls or breaking changes, inline}
 ```
 
+### Format rules
+
+- **Line 1:** Skill name + version + root path — version signals training data staleness
+- **Line 2 (IMPORTANT):** Retrieval instruction — always present, tells agent to read SKILL.md before acting
+- **Lines 3+:** Pipe-delimited index mapping topics to SKILL.md sections (with `#anchor` pointers)
+- **Inline content:** Each index line includes a brief inline summary (~10 words) so the agent can decide whether to read the full section
+- **gotchas line:** 2-3 most critical pitfalls inline — prevents mistakes without requiring a file read
+- **Token budget:** ~80-120 tokens per skill (justified by Vercel's finding that indexed format maintains performance at 80% compression)
+- **T1-now content only** — no T2 annotations in the snippet
+- **Section anchors** (`#quick-start`, `#key-types`) must match actual SKILL.md heading slugs
+- **Version** comes from source detection (per issue #32), not brief default
+
 ---
 
 ## metadata.json Structure
@@ -67,22 +113,27 @@ Compressed 2-line-per-skill format for CLAUDE.md managed section:
 {
   "name": "{skill-name}",
   "version": "{source-version}",
-  "skill_type": "individual",
+  "skill_type": "single",
   "source_authority": "{official|community|internal}",
   "source_repo": "{github-url}",
+  "source_root": "{resolved-source-path}",
   "source_commit": "{commit-hash}",
-  "forge_tier": "{quick|forge|deep}",
+  "confidence_tier": "{Quick|Forge|Deep}",
   "spec_version": "1.3",
-  "generated_at": "{ISO-8601}",
+  "generation_date": "{ISO-8601}",
+  "exports": [],
   "tool_versions": {
     "ast_grep": "{version-or-null}",
     "qmd": "{version-or-null}",
-    "skf": "1.0.0"
+    "skf": "{skf_version}"
   },
   "stats": {
     "exports_documented": 0,
+    "exports_public_api": 0,
+    "exports_internal": 0,
     "exports_total": 0,
-    "coverage": 0.0,
+    "public_api_coverage": 0.0,
+    "total_coverage": 0.0,
     "confidence_t1": 0,
     "confidence_t2": 0,
     "confidence_t3": 0
@@ -125,7 +176,10 @@ Each reference file includes:
   "generated_at": "{ISO-8601}",
   "entries": [
     {
-      "claim": "getToken accepts userId and optional TokenOptions",
+      "export_name": "getToken",
+      "export_type": "function",
+      "params": ["userId: string", "options?: TokenOptions"],
+      "return_type": "Token",
       "source_file": "src/auth/index.ts",
       "source_line": 42,
       "confidence": "T1",
@@ -150,7 +204,7 @@ Each reference file includes:
 ## Tool Versions
 - ast-grep: {version}
 - QMD: {version}
-- SKF: 1.0.0
+- SKF: {skf_version}
 
 ## Extraction Summary
 - Files scanned: {count}

package/src/workflows/create-skill/data/source-resolution-protocols.md

@@ -0,0 +1,138 @@
+# Source Resolution Protocols
+
+## Remote Source Resolution (Forge/Deep only)
+
+If `source_repo` is a local path: proceed with the tier-appropriate strategy as normal.
+
+If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is Forge or Deep:
+
+1. **Check `git` availability:** Verify `git` is functional (`git --version`). If `git` is not available, skip to the fallback warning below.
+
+2. **Ephemeral shallow clone:** Clone the repository to a system temp path for AST access:
+
+   ```
+   temp_path = {system_temp}/skf-ephemeral-{skill-name}-{timestamp}/
+   git clone --depth 1 --branch {branch} --single-branch --filter=blob:none {source_repo} {temp_path}
+   ```
+
+   **If `include_patterns` are NOT specified:**
+
+   ```
+   git clone --depth 1 --branch {branch} --single-branch --filter=blob:none {source_repo} {temp_path}
+   ```
+
+   **If `include_patterns` ARE specified**, use sparse-checkout to limit the clone scope:
+
+   ```
+   git clone --depth 1 --branch {branch} --single-branch --filter=blob:none --sparse {source_repo} {temp_path}
+   ```
+
+   **Mode selection:** Choose sparse-checkout mode based on whether `exclude_patterns` exist:
+
+   - **No `exclude_patterns`:** Use default **cone mode** (faster). Convert `include_patterns` to directory roots.
+   - **`exclude_patterns` present:** Use **`--no-cone` mode** which supports gitignore-style negation patterns (`!` prefix). This applies both include and exclude at the git level, avoiding unnecessary blob downloads.
+
+   **Cone mode (no exclude patterns):**
+
+   **IMPORTANT:** `git sparse-checkout set` expects **directories**, not glob patterns. Convert `include_patterns` before passing them:
+
+   **Classification rule:** A pattern is an **individual file** if it contains no glob characters (`*`, `?`, `[`) AND does not end with `/`. Everything else is a glob — strip it to its directory root (the path prefix before the first glob character or wildcard segment).
+
+   - Strip glob suffixes to directory roots (e.g., `src/core/**/*.py` → `src/core`, `src/api/*.ts` → `src/api`)
+   - Deduplicate the resulting directory list
+   - Individual files (e.g., `pyproject.toml`, `src/utils/helpers.py`) are kept as-is
+
+   **If only directory roots (no individual files):**
+
+   ```
+   git -C {temp_path} sparse-checkout set {converted_directory_roots}
+   ```
+
+   **If any individual files are present (or mixed):**
+
+   ```
+   git -C {temp_path} sparse-checkout set --skip-checks {converted_directory_roots} {individual_files}
+   ```
+
+   Example transformation:
+   ```
+   Brief include_patterns:        sparse-checkout args:
+   src/core/**/*.py          →    src/core          (directory root)
+   src/api/*.ts              →    src/api           (directory root)
+   examples/**/*.py          →    examples          (directory root)
+   pyproject.toml            →    pyproject.toml    (individual file, needs --skip-checks)
+   src/utils/helpers.py      →    src/utils/helpers.py (individual file, needs --skip-checks)
+   ```
+
+   **No-cone mode (exclude patterns present):**
+
+   When `exclude_patterns` exist, use `--no-cone` mode to pass both include and exclude patterns directly as gitignore-style rules:
+
+   1. Convert `include_patterns` to gitignore-style patterns. If a pattern contains no glob characters (`*`, `?`, `[`) and does not end with `/`, append `/**` to match directory contents recursively (e.g., `cognee` → `cognee/**`; `cognee/**` → kept as-is).
+   2. Convert `exclude_patterns` to negation patterns by prepending `!`. Apply the same anchoring rule (e.g., `cognee/tests` → `!cognee/tests/**`; `cognee/tests/**` → `!cognee/tests/**`; `**/test_*` → `!**/test_*`).
+   3. **CRITICAL:** List all include patterns BEFORE negated exclude patterns — git processes patterns in order and a negation can only suppress a prior inclusion.
+   4. Pass to sparse-checkout — include patterns first, then negated exclude patterns:
+
+   ```
+   git -C {temp_path} sparse-checkout set --no-cone {include_gitignore_patterns} {negated_exclude_patterns}
+   ```
+
+   Example transformation:
+   ```
+   Brief include_patterns:        Brief exclude_patterns:
+   cognee/**                      cognee/tests/**
+                                  cognee/alembic/**
+                                  **/test_*
+
+   sparse-checkout args (--no-cone):
+   'cognee/**' '!cognee/tests/**' '!cognee/alembic/**' '!**/test_*'
+   ```
+
+   **Note:** `--no-cone` mode is slower than cone mode for very large repositories but eliminates downloading excluded blobs entirely.
+
+   **Always-included root files:**
+
+   Regardless of `include_patterns`, always add these root-level version/manifest files to the sparse-checkout pattern list. These are needed for version reconciliation and must not require a fallback to `gh api`:
+
+   `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `setup.py`, `setup.cfg`, `VERSION`
+
+   In cone mode, always use the `--skip-checks` command form when adding these files — even if `include_patterns` resolved to only directory roots (which would normally use the form without `--skip-checks`). The command becomes: `git -C {temp_path} sparse-checkout set --skip-checks {directory_roots} pyproject.toml package.json Cargo.toml go.mod setup.py setup.cfg VERSION`. In no-cone mode, list them as explicit include patterns before any negation patterns. Do not flag them as extraneous inclusions during post-checkout filtering.
+
+   **Post-checkout filtering:**
+
+   After checkout, apply the original glob `include_patterns` as file-level filters when building the extraction file list — sparse-checkout gets the right directories, glob filtering narrows to the exact files. When `--no-cone` mode was used, most exclude filtering is already done at the git level, but apply `exclude_patterns` as a final pass to catch any edge cases where gitignore pattern matching diverges from the brief's glob semantics. Always-included root files (see above) are exempt from post-checkout filtering.
+
+3. **If clone succeeds:** Update the working source path to `{temp_path}` for all subsequent AST operations in this step. Proceed with the **Forge/Deep Tier** extraction strategy below. Mark `ephemeral_clone_active = true` for cleanup.
+
+4. **If clone fails (network error, auth failure, timeout):**
+
+   ⚠️ **Warn the user explicitly:**
+
+   "Ephemeral clone of `{source_repo}` failed: {error}. Degrading to source reading (T1-low) for this run. For T1 (AST-verified) confidence, clone the repository locally and update `source_repo` in your brief to the local path."
+
+   Proceed with Quick tier extraction strategy below. Note the degradation reason in context for the evidence report.
+
+**Ephemeral clone cleanup:** After extraction is complete for all files in scope (whether successful or partially failed), before presenting the Gate 2 summary (Section 6), if `ephemeral_clone_active`, delete the `{temp_path}` directory. Log: "Ephemeral source clone cleaned up." This ensures cleanup runs even if some extractions failed, as long as the step itself is still executing.
+
+---
+
+## Version Reconciliation (all tiers, source mode only)
+
+**If `source_type: "docs-only"`:** skip this section — no source files exist to reconcile.
+
+After the source path is accessible (local path from step-01, or ephemeral clone from above), check whether the source contains a version identifier and reconcile it with `brief.version`. Look for the first matching version file in the resolved source path:
+
+- Python: `pyproject.toml` (`[project] version`), `setup.py` (`version=`), `__version__` in `__init__.py`
+- JavaScript/TypeScript: `package.json` (`"version"`)
+- Rust: `Cargo.toml` (`[package] version`)
+- Go: `go.mod` (module version if tagged)
+
+**If a source version is found AND it differs from `brief.version`:**
+
+⚠️ Warn the user: "Brief version ({brief.version}) differs from source version ({source_version}). Using source version ({source_version})."
+
+Update the working version in context to the source version. Record the mismatch in context for the evidence report (step-08).
+
+**If no version file is found or version cannot be extracted:** keep `brief.version` as-is. No warning needed.
+
+**If source is remote and accessed via Quick tier (gh_bridge, no local files):** attempt to read the version file via `gh_bridge.read_file(owner, repo, "{version_file}")` for the primary version file of the detected language. If the read fails, keep `brief.version`.

package/src/workflows/create-skill/data/tier-degradation-rules.md

@@ -0,0 +1,46 @@
+# Tier Degradation Rules
+
+## Remote Source at Forge/Deep Tier
+
+When `source_repo` is a remote URL (GitHub URL or owner/repo format) and the tier is Forge or Deep:
+
+- **ast-grep requires local files** — it cannot operate on remote URLs
+
+**Ephemeral clone strategy (preferred):**
+
+1. Check `git` availability (`git --version`). `git` is effectively guaranteed at Deep tier (via `gh` dependency) but NOT guaranteed at Forge tier.
+2. If `git` is available: perform an ephemeral shallow clone to a system temp path (`{system_temp}/skf-ephemeral-{skill-name}-{timestamp}/`).
+3. For create-skill: use `--depth 1 --single-branch --filter=blob:none`; if `include_patterns` are specified, apply mode selection: if `exclude_patterns` are absent, use cone mode (convert include_patterns to directory roots; use `--skip-checks` for individual file paths); if `exclude_patterns` are present, use `--no-cone` mode (pass gitignore-style patterns with `!`-prefixed excludes — includes first, then negations). See source-resolution-protocols.md for the full conversion rules.
+4. For update-skill: use sparse-checkout with `--skip-checks` scoped to the changed files from the change manifest only (file paths require `--skip-checks`). No `--branch` flag — uses the remote default branch (must match the branch used during original create-skill run).
+5. If clone succeeds: use the local clone path for AST extraction. All results are T1 with `[AST:...]` citations.
+6. Cleanup: delete the temp directory after extraction inventory is built and all data is in context. The clone never persists beyond the extraction step.
+
+**Fallback (clone fails or `git` unavailable):**
+
+- The extraction step MUST warn the user explicitly before degrading
+- **create-skill:** Warning must include actionable guidance — clone locally and update `source_repo` in the brief to the local path
+- **update-skill:** Warning must include actionable guidance — clone locally, re-run [CS] Create Skill with the local path to regenerate provenance data, then re-run the update
+- Extraction proceeds using Quick tier strategy (source reading via gh_bridge)
+- All results labeled T1-low with `[SRC:...]` citations
+- The degradation reason is recorded in the evidence report
+
+Silent degradation is **forbidden**. The user must always know when AST extraction was skipped and why.
+
+## AST Tool Unavailable at Forge/Deep Tier
+
+When the tier is Forge or Deep but ast-grep is not functional:
+
+- The extraction step MUST warn the user explicitly before degrading
+- Warning must include actionable guidance: run [SF] Setup Forge to detect tools
+- Extraction proceeds using Quick tier strategy
+- All results labeled T1-low
+- The degradation reason is recorded in the evidence report
+
+## Per-File AST Failure
+
+When ast-grep fails on an individual file (parse error, unsupported syntax):
+
+- Fall back to source reading for **that file only**
+- Other files continue with AST extraction
+- The affected file's results are labeled T1-low; unaffected files retain T1
+- Log a warning noting which file degraded and why

package/src/workflows/create-skill/steps-c/step-01-load-brief.md

@@ -63,9 +63,8 @@ Halt with: "Forge halted: No forge configuration found. Run [SF] Setup Forge fir
 Extract and report:
 - `tier`: Quick, Forge, or Deep
 - `tools`: which tools are available (gh, ast-grep, qmd)
-- `tier_override`: if set, use override tier instead of detected
 
-Check for `tier_override` in `{preferencesFile}`. If `tier_override` is set and differs from detected tier, use the override value.
+**Apply tier override:** Read `{preferencesFile}`. If `tier_override` is set and is a valid tier value (Quick, Forge, or Deep), use it instead of the detected tier.
 
 ### 2. Discover Skill Brief
 
@@ -89,17 +88,21 @@ Check that the loaded skill-brief.yaml contains required fields:
 **Required fields:**
 - `name` — skill identifier (kebab-case)
 - `version` — source version to compile against
-- `source_repo` — GitHub owner/repo or local path
+- `source_repo` — GitHub owner/repo or local path (**optional when `source_type: "docs-only"`**)
 - `language` — primary source language
 - `scope` — what to extract (e.g., "all public exports", specific modules)
 
 **Optional fields:**
+- `source_type` — `"source"` (default) or `"docs-only"` (external documentation only)
+- `doc_urls` — array of `{url, label}` documentation URLs (required when `source_type: "docs-only"`)
 - `source_branch` — branch to use (default: main/master)
-- `source_authority` — official/community/internal (default: community)
+- `source_authority` — official/community/internal (default: community; forced to `community` for docs-only)
 - `include_patterns` — file glob patterns to include
 - `exclude_patterns` — file glob patterns to exclude
 - `description` — human description of the skill
 
+**Docs-only validation:** When `source_type: "docs-only"`, `source_repo` is not required but `doc_urls` must have at least one entry. `source_authority` is forced to `community`.
+
 **If required fields missing:**
 Halt with specific error: "Brief validation failed: missing required field `{field}`. Update your skill-brief.yaml and re-run."