bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/{workflows/create-skill/data → skf-create-skill/references}/extraction-patterns.md

@@ -30,11 +30,11 @@ Structural extraction via ast-grep — verified exports with line-level citation
 
 > **Note:** `ast_bridge.*`, `qmd_bridge.*`, and `ccc_bridge.*` references below are **conceptual interfaces**, not callable functions. Resolve them as follows:
 > - `ast_bridge.*` → ast-grep MCP tools (`mcp__ast-grep__find_code`, `mcp__ast-grep__find_code_by_rule`) or `ast-grep` CLI
-> - `qmd_bridge.*` → QMD MCP tools (`mcp__plugin_qmd-plugin_qmd__search`, `vector_search`) or `qmd` CLI
+> - `qmd_bridge.*` → QMD MCP `query` tool (`mcp__plugin_qmd-plugin_qmd__query`) taking `searches=[{type:'lex'|'vec'|'hyde', query, intent}]`, or `qmd` CLI (`qmd search` / `qmd vector-search`). The legacy `vector_search` MCP tool has been removed; if a client surfaces a tool-not-found error, degrade gracefully per the QMD step-04 tool-probe note — do not retry the stale name.
 > - `ccc_bridge.*` → `/ccc` skill (Claude Code), ccc MCP server (Cursor), or `ccc` CLI
 > - `gh_bridge.*` → `gh api` commands or direct file I/O for local sources
 >
-> See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) for the complete resolution table. Also see the AST Extraction Protocol section below and the TOOL/SUBPROCESS FALLBACK rule for dispatch details.
+> See `knowledge/tool-resolution.md` for the complete resolution table. Also see the AST Extraction Protocol section below and the TOOL/SUBPROCESS FALLBACK rule for dispatch details.
 
 ### Strategy
 
@@ -235,7 +235,8 @@ constraints:
 id: python-public-classes
 language: python
 rule:
-  pattern: 'class $NAME($$$BASES)'
+  pattern: 'class $NAME'
+  kind: class_definition
   inside:
     kind: module
     stopBy: end
@@ -244,6 +245,8 @@ constraints:
     regex: '^[^_]'
 ```
 
+> **Pattern note:** The minimal `class $NAME` pattern (with `kind: class_definition` to disambiguate the AST node) works on ast-grep 0.42.x via both MCP `find_code_by_rule` and CLI `--json=stream`. The previously documented `class $NAME($$$BASES)` and `class $NAME($$$BASES):` variants are known-broken on 0.42.x — see Known Limitations #7 below. For simple CLI extraction without a YAML rule, use `ast-grep run -p 'class $NAME' -l python --json=stream {path}` and post-filter names via the `^[^_]` regex in the Python processing step of the CLI streaming template.
+
 **JavaScript/TypeScript — exported functions:**
 
 > **Language selection:** Use `language: typescript` for `.ts` files and `language: tsx` for `.tsx` files. Patterns that work with `typescript` may return zero results with `tsx` and vice versa — they use different tree-sitter parsers. For mixed codebases, run each pattern twice (once per language) and merge results. Note: `export function` patterns may fail with `tsx` on ast-grep 0.41.x (see Known Limitations #5) — use source reading as fallback for those.
@@ -395,6 +398,8 @@ When using ast-grep for extraction, be aware of these documented limitations:
 
 6. **CLI `--json=stream` may produce no output:** On ast-grep 0.41.x, `--json=stream` may produce empty output for certain patterns. The `--json=stream` flag requires the explicit `run` subcommand: use `ast-grep run -p '{pattern}' --json=stream` (not `ast-grep -p '{pattern}' --json=stream`). If streaming still produces no output, fall back to the MCP tool or source reading.
 
+7. **Python class patterns with bases/colon return zero (ast-grep 0.42.x):** The patterns `class $NAME($$$BASES)` and `class $NAME($$$BASES):` return zero matches on real Python sources with ast-grep 0.42.0, even on files containing dozens of subclassed public classes. `find_code_by_rule` also rejects the bare inline rule without `kind` as `Rule must specify a set of AST kinds to match. Try adding \`kind\` rule.` **Workaround:** Use the minimal `class $NAME` pattern with `kind: class_definition` (YAML) or `ast-grep run -p 'class $NAME' -l python --json=stream` (CLI), then post-filter names via the `^[^_]` regex. The `^[^_]` constraint enforces the "public" filter since ast-grep's base-match rule is what's broken, not the name-match rule. See the Python — public classes recipe above.
+
 ### Component Library Demo/Example Auto-Exclusion
 
 When `scope.type: "component-library"`, auto-detect and propose demo/example exclusions before extraction begins. **User confirmation is required before applying** — some `examples/` directories contain API-level code.

package/src/skf-create-skill/references/source-resolution-protocols.md

@@ -0,0 +1,239 @@
+# Source Resolution Protocols
+
+## Shell Path Quoting
+
+Every shell snippet in this document uses `{...}` placeholders for paths. **Always wrap path interpolations in double quotes** when emitting the actual command — `git -C "{workspace_repo_path}"`, `rm -rf "{temp_path}"`, `cd "{project-root}"`. SKF's supported platforms are Linux and macOS; user home directories on macOS frequently contain spaces, which break unquoted shell. WSL2 users see the same. Native Windows is untested but the quoting convention is also required there.
+
+## Tag Resolution
+
+Tag resolution maps a declared version in the brief onto a concrete git ref before cloning, so the skill is built from code matching its declared version. Two paths trigger tag resolution: an **explicit** `brief.target_version` (deliberate user intent) or an **implicit** `brief.version` (auto-populated hint from `brief-skill`). Both apply only when `source_repo` is a remote URL.
+
+**When neither `brief.target_version` nor `brief.version` is set:** skip tag resolution entirely. Set `source_ref` to `HEAD` (default branch).
+
+### Explicit Tag Resolution (when target_version is set)
+
+When `brief.target_version` is present AND `source_repo` is a remote URL, resolve the target version to a git tag before cloning:
+
+1. **List available tags:**
+   - `gh api repos/{owner}/{repo}/tags --paginate --jq '.[].name'`
+   - Fallback: `git ls-remote --tags "{source_repo}" | sed 's|.*refs/tags/||'`
+
+2. **Match `target_version` against tags** in priority order:
+   - **Exact match:** `{target_version}` (e.g., `0.5.0`)
+   - **With `v` prefix:** `v{target_version}` (e.g., `v0.5.0`)
+   - **With package scope (monorepos):** `{brief.name}@{target_version}` or `@{scope}/{brief.name}@{target_version}`
+
+3. **Resolution outcomes:**
+   - **Single match:** Store the matched tag as `source_ref`. Use it as `{branch}` in all subsequent clone/API commands.
+   - **Multiple matches:** Present the matching tags to the user — "Multiple tags match version {target_version}: {list}. Which one should I use?" Wait for selection.
+   - **Zero matches:** ⚠️ Warn: "No git tag found matching version {target_version}. Closest available tags: {list 5 nearest by semver sort}. Falling back to default branch — **extracted code may not match target version.**" Set `source_ref` to `HEAD` and proceed with default branch.
+
+4. **Store `source_ref`** in context. This value is written to metadata.json and provenance-map.json for downstream workflows (update-skill, audit-skill) to re-clone from the same ref.
+
+### Implicit Tag Resolution (when only brief.version is set)
+
+When `brief.target_version` is absent but `brief.version` is present AND `source_repo` is a remote URL, treat `brief.version` as an **implicit** target version and attempt tag resolution before cloning. This matches `brief-skill`'s behavior, which auto-populates `brief.version` from the latest non-prerelease release tag — so a tag matching `brief.version` is the common case, and silently cloning HEAD would produce a skill labeled with `brief.version` but built from an unrelated default-branch commit.
+
+1. **List available tags** exactly as in Explicit Tag Resolution above.
+
+2. **Match `brief.version` against tags** in this reduced priority order. Package-scoped monorepo variants are **not** tried — those require deliberate user intent via `target_version`, since implicit matching against a monorepo tag like `{brief.name}@{version}` could silently select a sibling package's ref:
+   - **Exact match:** `{brief.version}` (e.g., `0.3.37`)
+   - **With `v` prefix:** `v{brief.version}` (e.g., `v0.3.37`)
+
+3. **Resolution outcomes:**
+   - **Single match:** Store the matched tag as `source_ref`. Use it as `{branch}` in all subsequent clone/API commands. Do not warn — this is the expected path.
+   - **Multiple matches:** Present the matching tags to the user — "Multiple tags match `brief.version` ({brief.version}): {list}. Which one should I use, or fall back to HEAD?" Wait for selection.
+   - **Zero matches:** ⚠️ Warn: "No git tag found matching `brief.version` ({brief.version}). Falling back to default branch — **extracted code may not match the declared version.** If you intended to pin a specific version, set `target_version` explicitly in the brief." Set `source_ref` to `HEAD` and proceed with default branch. Append `tag_resolution: {status: "fallback-head", requested: "{brief.version}", reason: "no-matching-tag"}` to the in-context evidence-report payload so step-05 §7 surfaces the fallback in the evidence report. This turns the warning into a persistent audit trail a reviewer can grep later, not just a one-shot stderr line.
+
+4. **Do not halt on zero matches.** Unlike the explicit path, implicit resolution never blocks compilation — `brief.version` is an auto-populated hint, and some repositories simply do not tag releases. The warning is sufficient notice; the evidence report in step-08 will surface the HEAD fallback for reviewers.
+
+5. **Store `source_ref`** in context exactly as in the explicit path. It flows through to metadata.json and provenance-map.json so downstream workflows (update-skill, audit-skill) can re-clone from the same ref.
+
+**Interaction with Version Reconciliation (below):** When implicit tag resolution succeeds, the clone's source files should carry the same version as `brief.version` — so the Version Reconciliation section's source-vs-brief mismatch warning will not fire. When implicit resolution falls back to HEAD, Version Reconciliation runs normally against the default branch's version file and may produce its own mismatch warning.
+
+### Local Source Warning
+
+When `brief.target_version` is set AND `source_repo` is a local path:
+
+⚠️ "**Local source may not match target version {target_version}.** Ensure you've checked out the correct version locally, or use a remote GitHub URL so SKF can clone from the git tag automatically."
+
+Proceed with local files as-is. Set `source_ref` to `"local"`.
+
+Implicit resolution via `brief.version` is **not applied to local sources** — local paths reflect whatever the user has checked out, and rewriting them from a tag would be out of scope for a local-source workflow.
+
+---
+
+## Remote Source Resolution
+
+**Note:** Quick-tier remote sources do not use the workspace/clone protocol described below. Quick tier accesses remote files via the `gh_bridge.read_file` path described in step-03 section 4.
+
+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, 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. **Compute workspace path:** Derive a persistent local path from the remote URL:
+
+   - **Parse the URL** to extract `{host}`, `{owner}`, `{repo}`:
+     - `https://github.com/facebook/react` or `https://github.com/facebook/react.git` → `github.com/facebook/react`
+     - `git@github.com:facebook/react.git` → `github.com/facebook/react`
+     - `facebook/react` (owner/repo shorthand) → `github.com/facebook/react`
+   - **Resolve workspace root:** Use environment variable `SKF_WORKSPACE` if set, otherwise `~/.skf/workspace/` (where `~` is the user's home directory on all platforms)
+   - **Workspace repo path:** `{workspace_root}/repos/{host}/{owner}/{repo}/`
+
+3. **Workspace check — resolve the source locally:**
+
+   **Concurrency guard:** all of the operations below (fetch, checkout, rev-parse, and the extraction read that follows in step-03) must be wrapped in an exclusive `flock` on `{workspace_repo_path}/.skf-workspace.lock`. Acquire the lock before the workspace-hit check, hold it across fetch + checkout + rev-parse, AND keep holding it through the extraction-time read of the working tree. Two concurrent batch runs that target the same workspace clone but different `source_ref` values would otherwise race — one would `checkout` while the other was reading files mid-extraction, corrupting the inventory. The lock makes the per-workspace-repo unit of work serial. Use `flock -x {lockfile} -c "..."` or `fcntl.flock(LOCK_EX)`. If `flock` is unavailable, log a warning ("Concurrency guard unavailable — concurrent forges against the same workspace repo may produce inconsistent extraction inventories") and proceed.
+
+   **If `{workspace_repo_path}/.git/` exists (workspace hit):**
+
+   The repo was previously cloned into the workspace. Fetch updates and checkout the requested ref.
+
+   **Detect tag vs branch for `source_ref`** (skipped when `source_ref` is `HEAD` — in that case fetch default branch without a ref argument):
+
+   ```
+   # Ask the remote whether source_ref exists as a tag
+   git -C "{workspace_repo_path}" ls-remote --tags origin {source_ref} | grep -q "refs/tags/{source_ref}$" && ref_kind=tag || ref_kind=branch
+   ```
+
+   Fetch using the ref-kind-appropriate invocation so tag refs are written into `refs/tags/*` rather than being dropped by a branch-only fetch:
+
+   ```
+   if ref_kind == tag:
+     git -C "{workspace_repo_path}" fetch origin tag {source_ref}
+   else:
+     git -C "{workspace_repo_path}" fetch origin {source_ref}
+   ```
+
+   Check if checkout is needed — skip if the requested ref is already checked out:
+
+   ```
+   current_head = git -C "{workspace_repo_path}" rev-parse HEAD
+   fetched_head = git -C "{workspace_repo_path}" rev-parse FETCH_HEAD
+   ```
+
+   If `current_head != fetched_head`:
+   ```
+   git -C "{workspace_repo_path}" -c advice.detachedHead=false checkout FETCH_HEAD
+   ```
+
+   If fetch or checkout fails, proceed to the **ephemeral fallback** (step 5).
+
+   **If `{workspace_repo_path}/.git/` does NOT exist (workspace miss):**
+
+   Clone the repository into the workspace for persistent reuse. Create the parent directory first (`{workspace_root}/repos/{host}/{owner}/`):
+
+   ```
+   mkdir -p "{workspace_root}/repos/{host}/{owner}/"
+   ```
+
+   Clone with the appropriate branch flag — `--branch` is only valid for real branch/tag names, not for `HEAD`. **Do NOT pass `--single-branch`** here: workspace clones are persistent and re-used for future forges with different `source_ref` values (a later run may target a different tag or branch). A single-branch workspace clone would force every re-forge with a new ref to fall through to ephemeral cloning, defeating the workspace cache:
+
+   ```
+   # If source_ref is a real branch or tag (not HEAD/null):
+   git clone --depth 1 --branch {source_ref} "{source_repo}" "{workspace_repo_path}"
+
+   # If source_ref is HEAD or not set (default branch):
+   git clone --depth 1 "{source_repo}" "{workspace_repo_path}"
+   ```
+
+   **Note:** No `--filter=blob:none` — blobs for the current tree are needed for indexing and the cost is amortized across all future forges. No sparse-checkout — a full checkout serves all consumers (different briefs with different include/exclude patterns) without configuration conflicts. `--single-branch` is reserved for ephemeral clones (step 5); workspace clones keep all branches available so re-forges against different refs can fetch + checkout without re-cloning.
+
+   If this is the **first repo** in the workspace (workspace root was just created), print an informational message:
+
+   "Caching source at `{workspace_repo_path}` (saves time on re-forges). Override location with `SKF_WORKSPACE` env var."
+
+   If clone fails, proceed to the **ephemeral fallback** (step 5).
+
+4. **If workspace resolution succeeds:** Set `source_root = {workspace_repo_path}` — this updates the working source path for all subsequent operations (AST extraction, CCC indexing, artifact generation). Capture the source commit: `git -C "{workspace_repo_path}" rev-parse HEAD` — store as `source_commit` in context. Proceed with the **Forge/Deep Tier** extraction strategy below. Set context:
+   - `source_root = {workspace_repo_path}`
+   - `remote_clone_path = {workspace_repo_path}`
+   - `remote_clone_type = "workspace"`
+
+   **Scope filtering:** Since the workspace uses a full checkout (no sparse-checkout), apply `include_patterns` and `exclude_patterns` from the brief as **file-level filters** when building the extraction file list. Always-included root files (`pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `setup.py`, `setup.cfg`, `VERSION`) are exempt from pattern filtering.
+
+5. **Ephemeral fallback (on any workspace failure):**
+
+   If workspace clone or fetch fails for any reason (network error, auth failure, disk full, timeout), fall back to ephemeral cloning — the pre-workspace behavior that always works:
+
+   ```
+   temp_path = {system_temp}/skf-ephemeral-{skill-name}-{timestamp}/
+
+   # If source_ref is a real branch or tag (not HEAD/null):
+   git clone --depth 1 --branch {source_ref} --single-branch --filter=blob:none "{source_repo}" "{temp_path}"
+
+   # If source_ref is HEAD or not set (default branch):
+   git clone --depth 1 --single-branch --filter=blob:none "{source_repo}" "{temp_path}"
+   ```
+
+   If ephemeral clone succeeds: Set `source_root = {temp_path}`. Capture `source_commit`. Set context:
+   - `source_root = {temp_path}`
+   - `remote_clone_path = {temp_path}`
+   - `remote_clone_type = "ephemeral"`
+
+   Apply `include_patterns` and `exclude_patterns` from the brief as file-level filters when building the extraction file list.
+
+6. **If all cloning fails (workspace AND ephemeral):**
+
+   ⚠️ **Warn the user explicitly:**
+
+   "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.
+
+**Remote 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 `remote_clone_type == "ephemeral"`:** Cleanup is required.
+  1. **Reset working directory first:** Run `cd "{project-root}"` using the **absolute path** captured at workflow start.
+  2. **Delete the clone:** `rm -rf "{temp_path}"`
+  3. **Log:** "Ephemeral source clone cleaned up."
+
+  This ensures cleanup runs even if some extractions failed. If any error halts the step before Gate 2, cleanup must still occur.
+
+- **If `remote_clone_type == "workspace"`:** No cleanup. The workspace checkout persists for future forges.
+
+---
+
+## Source Commit Capture (all tiers, source mode only)
+
+**If `source_type: "docs-only"`:** skip — set `source_commit: null`.
+
+After the source path is accessible, capture the current commit hash for provenance tracking:
+
+- **Local path:** `git -C "{source_root}" rev-parse HEAD` — if the path is a git repo
+- **Ephemeral clone (Forge/Deep):** already captured during clone (step 3 above)
+- **Quick tier (remote, no clone):** `gh api repos/{owner}/{repo}/commits/{source_ref} --jq '.sha'`
+
+Store the result as `source_commit` in context. If capture fails (not a git repo, API unavailable), set `source_commit: null` — this is not an error.
+
+Also store `source_ref` in context (from tag resolution above, or `HEAD` if no tag was resolved, or `"local"` for local sources). This value is persisted to metadata.json and provenance-map.json so downstream workflows (update-skill, audit-skill) can re-access the same source ref.
+
+---
+
+## Version Reconciliation (all tiers, source mode only)
+
+**Target version override:** If `brief.target_version` is present, use it as the authoritative version for the skill. Do NOT warn about a brief-vs-source version mismatch — the user intentionally specified this version. Set the working version to `brief.target_version` and skip the rest of this reconciliation section. The `target_version` field indicates deliberate user intent (e.g., targeting an older version, or providing the version for a docs-only skill).
+
+**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 workspace/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"`). **Monorepo resolution:** When multiple `package.json` files exist (workspace root + packages), resolve version using this priority:
+  1. Package whose `name` field matches `brief.name` (e.g., the skill's target library name)
+  2. Package with a `bin` field (CLI entry point — represents the published version)
+  3. Root workspace `package.json` version (if present)
+  4. Fall back to `brief.version` if no version found. For monorepos using workspace protocols (pnpm, yarn, npm workspaces), the root `package.json` often has no `version` field — this is expected, not an error.
+- 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}")` — resolved as `gh api repos/{owner}/{repo}/contents/{version_file}` or direct file read if local (see `knowledge/tool-resolution.md`) — for the primary version file of the detected language. If the read fails, keep `brief.version`.

package/src/{workflows/create-skill/data → skf-create-skill/references}/tier-degradation-rules.md

@@ -6,21 +6,22 @@ When `source_repo` is a remote URL (GitHub URL or owner/repo format) and the tie
 
 - **ast-grep requires local files** — it cannot operate on remote URLs
 
-**Ephemeral clone strategy (preferred):**
+**Workspace-first 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.
+2. If `git` is available: check for an existing workspace checkout at `{workspace_root}/repos/{host}/{owner}/{repo}/`. If found, `git fetch` to update. If not found, clone into the workspace path with `--depth 1 --single-branch`. See `source-resolution-protocols.md` for the full workspace resolution algorithm.
+3. The workspace uses a full checkout (no sparse-checkout). Brief `include_patterns` and `exclude_patterns` are applied as file-level filters at extraction time, not at the git level. This allows a single workspace checkout to serve multiple briefs with different scope filters.
+4. For update-skill: `changed_files_from_manifest` scoping is applied as file-level filters at extraction time on the full workspace checkout.
+5. If workspace clone/fetch succeeds: use the workspace path for AST extraction. All results are T1 with `[AST:...]` citations.
+6. If workspace fails: fall back to ephemeral clone (`{system_temp}/skf-ephemeral-{skill-name}-{timestamp}/`). If ephemeral succeeds, use it. Ephemeral clone is deleted after extraction.
+7. Workspace checkouts persist across forges — CCC indexes, tool outputs, and the checkout itself are reused.
 
 **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 — resolved as `gh api` commands or direct file I/O; see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md))
+- Extraction proceeds using Quick tier strategy (source reading via gh_bridge — resolved as `gh api` commands or direct file I/O; see `knowledge/tool-resolution.md`)
 - All results labeled T1-low with `[SRC:...]` citations
 - The degradation reason is recorded in the evidence report
 

package/src/{workflows/create-skill → skf-create-skill}/steps-c/step-01-load-brief.md

@@ -1,6 +1,4 @@
 ---
-name: 'step-01-load-brief'
-description: 'Load skill-brief.yaml, validate structure, resolve source code location, load forge tier'
 nextStepFile: './step-02-ecosystem-check.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 preferencesFile: '{sidecar_path}/preferences.yaml'
@@ -12,41 +10,10 @@ preferencesFile: '{sidecar_path}/preferences.yaml'
 
 To load and validate the skill-brief.yaml compilation config, resolve the source code location, and load the forge tier from sidecar to determine available capabilities for the compilation pipeline.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+## Rules
 
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🎯 ALWAYS follow the exact instructions in the step file
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a skill compilation engine performing initialization
-- ✅ This is an autonomous init step — no user interaction needed
-- ✅ Load data, validate structure, resolve paths, determine capabilities
-
-### Step-Specific Rules:
-
-- 🎯 Focus ONLY on loading brief, resolving source, and determining tier
-- 🚫 FORBIDDEN to begin extraction or compilation — that's steps 03-05
-- 🚫 FORBIDDEN to write any output files — this step only loads and validates
-- 💬 Report initialization status clearly
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow MANDATORY SEQUENCE exactly
-- 💾 All loaded data remains in context for subsequent steps
-- 📖 Validate brief structure before proceeding
-- 🚫 Halt with actionable error if prerequisites are missing
-
-## CONTEXT BOUNDARIES:
-
-- Available: User's skill name or brief path from Ferris menu invocation
-- Focus: Loading inputs and determining capabilities
-- Limits: Do NOT begin any extraction or compilation work
-- Dependencies: forge-tier.yaml must exist (from setup-forge workflow)
+- Focus only on loading brief, resolving source, and determining tier — do not begin extraction or compilation
+- Do not write any output files — this step only loads and validates
 
 ## MANDATORY SEQUENCE
 
@@ -65,7 +32,14 @@ Extract and report:
 - `tools`: which tools are available (gh, ast-grep, ccc, qmd)
 - `ccc_index`: ccc index state (status, indexed_path, last_indexed) — needed by step-02b
 
-**Apply tier override:** Read `{preferencesFile}`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
+**Apply tier override:** Read `{preferencesFile}`. If `tier_override` is set and is one of the exact valid tier values (`Quick`, `Forge`, `Forge+`, `Deep`), use it instead of the detected tier. **If `tier_override` is set but is NOT one of those four values:** log a warning — "Unknown tier_override `{value}` in preferences.yaml; falling back to detected tier `{detected_tier}`. Valid values: Quick, Forge, Forge+, Deep." — and use the detected tier. Never silently apply an unknown override value, and never map it heuristically to a tier.
+
+**Record the decision:** append an entry to the in-context `headless_decisions[]` buffer (initialize to `[]` at the start of this step if absent) whenever a non-interactive choice is made automatically — both the valid-override path AND the rejected-override path:
+
+- Valid override applied: `{step: "step-01-load-brief", gate: "tier-override", decision: "apply", value: "{tier_override}", rationale: "explicit preferences.yaml tier_override", timestamp: {ISO}}`
+- Invalid override rejected: `{step: "step-01-load-brief", gate: "tier-override", decision: "reject-invalid", value: "{tier_override}", fallback: "{detected_tier}", rationale: "tier_override not in {Quick,Forge,Forge+,Deep}", timestamp: {ISO}}`
+
+Step-05 §7 reads `headless_decisions[]` and emits an "Auto-Decisions" section into `evidence-report.md` so reviewers can audit every silent choice the workflow made.
 
 ### 2. Discover Skill Brief
 
@@ -76,7 +50,10 @@ Extract and report:
 
 **If user invoked with --batch flag:**
 - Check `{sidecar_path}/batch-state.yaml` for an active batch checkpoint:
-  - If `batch_active: true` and `current_index` is valid: load the brief at `brief_list[current_index]` (resuming a batch loop from step-08)
+  - If `batch_active: true`: validate the checkpoint before trusting it. Both conditions below MUST hold:
+    1. `0 <= current_index < len(brief_list)` — the index points inside the recorded list.
+    2. `os.path.exists(brief_list[current_index])` — the brief file is still on disk.
+    If both hold, load the brief at `brief_list[current_index]` (resuming a batch loop from step-08). If **either** check fails, the checkpoint is stale (briefs renamed, moved, or deleted between runs; index off the end after a partial failure). Log a warning — "Stale batch checkpoint — current_index={i}, brief_list length={n}, brief_exists={bool}. Resetting and re-discovering." — then set `batch_active: false` in `batch-state.yaml` and fall through to the no-checkpoint branch below.
   - If no checkpoint exists or `batch_active` is false: search specified directory for all `skill-brief.yaml` files, list discovered briefs with skill names, store list for batch loop processing, and load the FIRST brief
 
 **If no brief found:**
@@ -91,13 +68,14 @@ Check that the loaded skill-brief.yaml contains required fields:
 - `version` — source version to compile against
 - `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)
+- `scope` — what to extract. Accepts either a string (simple scope description, e.g., "all public exports") or an object with sub-fields: `type` (e.g., `"component-library"`), `include`, `exclude`, `notes`, and optionally `demo_patterns`, `registry_path`, `ui_variants` for component libraries
 
 **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; forced to `community` for docs-only)
+- `target_version` — specific version to compile against (triggers **explicit** tag resolution for remote repos; see source-resolution-protocols.md). When absent, the workflow falls back to **implicit** tag resolution from `brief.version` for remote sources — see below.
 - `include_patterns` — file glob patterns to include
 - `exclude_patterns` — file glob patterns to exclude
 - `description` — human description of the skill
@@ -109,14 +87,19 @@ Check that the loaded skill-brief.yaml contains required fields:
 **If required fields missing:**
 Halt with specific error: "Brief validation failed: missing required field `{field}`. Update your skill-brief.yaml and re-run."
 
+**Name format check (run after required-field check, before any path creation):** validate `brief.name` against the regex `^[a-z0-9][a-z0-9-]{0,63}$` — 1-64 characters, lowercase alphanumeric plus hyphens, must start with a letter or digit, no leading hyphen, no uppercase, no underscores, no slashes. This matches the agentskills.io skill-name rule and the directory-name constraint that `skill-check`'s `frontmatter.name_matches_directory` rule will later enforce. If validation fails, halt BEFORE any directory is created or any path is resolved: "Brief validation failed: `name` field `{value}` does not match required pattern `^[a-z0-9][a-z0-9-]{0,63}$`. Skill names must be 1-64 chars, lowercase alphanumeric plus hyphens, no leading hyphen, no underscores, no slashes. Update your skill-brief.yaml and re-run."
+
+**Version non-empty check:** reject `brief.version` if absent, empty, or whitespace-only (`version.strip() == ""`). Halt: "Brief validation failed: `version` field is required and must be non-empty. Update your skill-brief.yaml and re-run." This guards downstream directory resolution — an empty version would later create paths like `{skills_output_folder}/{name}//` with a stray double-slash, which is a nightmare to clean up.
+
 ### 4. Resolve Source Code Location
 
 **If `source_type: "docs-only"`:** Skip source resolution. Set `source_root: null` in context. Proceed directly to section 5 (Report Initialization) — docs-only skills have no source to resolve.
 
 **If source_repo is a GitHub URL or owner/repo format:**
-- Verify repository exists via `gh_bridge.list_tree(owner, repo, branch)` — **Tool resolution:** `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1` or direct file listing if local; see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
+- Verify repository exists via `gh_bridge.list_tree(owner, repo, branch)` — **Tool resolution:** `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1` or direct file listing if local; see `knowledge/tool-resolution.md`
 - If branch not specified, detect default branch
-- Store resolved: owner, repo, branch, file tree — note: `source_root` for remote repos is set to the ephemeral clone path during extraction (step-03)
+- Store resolved: owner, repo, branch, file tree — note: `source_root` for remote repos is initially set to the remote URL (for detection and API access purposes) and then updated to the local workspace/clone path during step-03 source resolution
+- **Version-to-tag pinning intent:** If `brief.target_version` is absent but `brief.version` is present, record the intent to apply **implicit tag resolution** from `brief.version` when step-03 resolves the source. Do not resolve the tag here — tag resolution runs in step-03 alongside the clone. This step only notes the pinning intent so step-03 knows to attempt it. See `references/source-resolution-protocols.md` → "Implicit Tag Resolution".
 
 **If source_repo is a local path:**
 - Verify path exists and contains source files
@@ -150,7 +133,7 @@ Where tier_description follows positive capability framing:
 
 **Auto-proceed step — no user interaction.**
 
-After initialization is complete and all data is loaded, immediately load, read entire file, then execute `{nextStepFile}`.
+After initialization is complete and all data is loaded (including `target_version` if present in the brief), immediately load, read entire file, then execute `{nextStepFile}`.
 
 #### EXECUTION RULES:
 
@@ -162,24 +145,3 @@ After initialization is complete and all data is loaded, immediately load, read
 
 ONLY WHEN forge-tier.yaml is loaded, skill-brief.yaml is validated, and source code location is resolved will you proceed to load `{nextStepFile}` for ecosystem check.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Forge tier loaded from sidecar with tool availability
-- Skill brief loaded and all required fields validated
-- Source code location resolved and accessible (or `source_root: null` confirmed for docs-only skills)
-- Initialization summary displayed with tier and capabilities
-- Auto-proceeded to step-02
-
-### ❌ SYSTEM FAILURE:
-
-- Proceeding without forge-tier.yaml (missing prerequisite)
-- Proceeding with invalid or incomplete brief
-- Not resolving source code location before proceeding
-- Beginning extraction or compilation work in this step
-- Not displaying initialization summary
-
-**Master Rule:** This step ONLY loads and validates. It does NOT extract, compile, or write files.

package/src/{workflows/create-skill → skf-create-skill}/steps-c/step-02-ecosystem-check.md

@@ -1,7 +1,5 @@
 ---
-name: 'step-02-ecosystem-check'
-description: 'Check agentskills.io ecosystem for existing official skill before compilation'
-nextStepFile: './step-02b-ccc-discover.md'
+nextStepFile: './sub/step-02b-ccc-discover.md'
 ---
 
 # Step 2: Ecosystem Check
@@ -10,42 +8,11 @@ nextStepFile: './step-02b-ccc-discover.md'
 
 To search the agentskills.io ecosystem for an existing official skill matching the brief, advise the user if one is found, and allow them to decide whether to proceed with compilation or install the existing skill.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+## Rules
 
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🎯 ALWAYS follow the exact instructions in the step file
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a skill compilation engine performing ecosystem discovery
-- ✅ This step is advisory — ecosystem check results never block compilation
-- ✅ Tool unavailability is never an error — it's a graceful skip condition
-
-### Step-Specific Rules:
-
-- 🎯 Focus ONLY on ecosystem search and presenting findings
-- 🚫 FORBIDDEN to begin any extraction or compilation work
-- 🚫 FORBIDDEN to halt the workflow if the ecosystem check fails or times out
-- 💬 If a match is found, present it factually — let the user decide
-- ⏱️ Enforce 5-second timeout on ecosystem queries
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow MANDATORY SEQUENCE exactly
-- 💾 All loaded data remains in context for subsequent steps
-- 📖 Ecosystem check is advisory — never blocking
-- 🚫 Do not modify any files — this step only queries and reports
-
-## CONTEXT BOUNDARIES:
-
-- Available: brief_data (name, version, source_repo, language, scope) and tier from step-01
-- Focus: Searching for existing skills in the ecosystem
-- Limits: Do NOT begin extraction, compilation, or file writing
-- Dependencies: skill-brief.yaml must be loaded and validated from step-01
+- Focus only on ecosystem search and presenting findings — do not begin extraction
+- Do not halt the workflow if the ecosystem check fails or times out (5-second timeout)
+- If a match is found, present it factually — let the user decide
 
 ## MANDATORY SEQUENCE
 
@@ -59,8 +26,8 @@ To search the agentskills.io ecosystem for an existing official skill matching t
 
 Query the ecosystem using the skill name from the brief:
 - Call the registry API with brief.name — check if an official skill already exists
-- Enforce 5-second timeout — if the query does not return within 5 seconds, treat as no match
-- Cache results for 24 hours (if re-running same skill)
+- Enforce 5-second timeout — if the query does not return within 5 seconds, treat as no match. Rationale: ecosystem check is an opportunistic advisory; a slow or degraded registry must not stall the compilation pipeline, and 5s is well beyond any healthy registry's p99 latency.
+- Cache results for 24 hours (if re-running same skill). Rationale: the agentskills.io registry publishes new official skills in daily batches; a 24-hour TTL balances freshness against redundant network calls during iterative brief refinement.
 
 **If registry API is NOT available (current default):**
 
@@ -103,6 +70,7 @@ Display: "**Ecosystem match found — Select an Option:** [P] Proceed with compi
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
+- **GATE [default: P]** — If `{headless_mode}` and match found: auto-proceed with [P] Proceed, log: "headless: ecosystem match found, auto-proceeding", AND append an entry to the in-context `headless_decisions[]` list: `{step: "step-02-ecosystem-check", gate: "ecosystem-match", decision: "P", rationale: "headless mode — match found, auto-proceed with user's own compilation", timestamp: {ISO}}`. Step-05 §7 (evidence-report assembly) reads `headless_decisions[]` and emits an "Auto-Decisions" section into evidence-report.md.
 - This menu ONLY appears when an ecosystem match is found
 - If no match, timeout, or tool unavailable — auto-proceed with no menu
 
@@ -120,27 +88,3 @@ ONLY WHEN the ecosystem check is complete (match evaluated, user decision made i
 
 If no match is found, this step auto-proceeds with no user interaction.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Ecosystem check attempted via registry API (or gracefully skipped if API unavailable)
-- 5-second timeout enforced on ecosystem queries
-- Match presented factually with clear options if found
-- No-match case auto-proceeds silently
-- User decision respected (Proceed/Install/Abort)
-- Auto-proceeded to step-02b (when no match or user chose Proceed)
-
-### ❌ SYSTEM FAILURE:
-
-- Halting the workflow because ecosystem check failed or timed out
-- Treating API unavailability as an error
-- Confusing `npx skill-check check` (local validation) with ecosystem lookup
-- Displaying "no match found" messages (absence should be silent)
-- Beginning extraction or compilation work in this step
-- Proceeding without user decision when a match IS found
-- Not enforcing the 5-second timeout
-
-**Master Rule:** This step is advisory. API unavailability and timeouts are silent skips, not errors. Only a confirmed match requires user interaction.