bmad-module-skill-forge 0.8.0 → 0.8.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",

package/src/knowledge/tool-resolution.md

@@ -13,6 +13,7 @@ Bridge names (`ast_bridge`, `ccc_bridge`, `qmd_bridge`, `gh_bridge`) and subproc
 | `ccc_bridge` | `status()`                       | `/ccc` skill status                                              | ccc MCP server | `ccc --help` + `ccc doctor`                        | Unavailable = `tools.ccc: false` |
 | `qmd_bridge` | `search(query)`                  | `mcp__plugin_qmd-plugin_qmd__search`                             | qmd MCP server | `qmd search "{query}"`                             | Skip enrichment                  |
 | `qmd_bridge` | `vector_search(query)`           | `mcp__plugin_qmd-plugin_qmd__vector_search`                      | qmd MCP server | `qmd vector_search "{query}"`                      | Use BM25 search only             |
+| `qmd_bridge` | `version()`                      | `qmd --version` → parse `"qmd X.Y.Z"` → `"X.Y.Z"`              | qmd MCP server | `qmd --version`                                    | `"unknown"`                      |
 | `gh_bridge`  | `list_tree(owner, repo, branch)` | `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1`     | gh CLI         | `gh api ...`                                       | Direct file listing if local     |
 | `gh_bridge`  | `read_file(owner, repo, path)`   | `gh api repos/{owner}/{repo}/contents/{path}`                    | gh CLI         | `gh api ...`                                       | Direct file read if local        |
 

package/src/workflows/create-skill/steps-c/step-05-compile.md

@@ -122,10 +122,10 @@ Following the structure from the skill-sections data file:
   2. `mcp__ast-grep__find_code` tool metadata (if version is exposed by the MCP server)
   3. `"unknown"` (final fallback — add a warning to the evidence report)
 - Resolve `{qmd_version}` using this resolution chain (try each in order, use the first that succeeds):
-  1. `mcp__plugin_qmd-plugin_qmd__status` → parse version from status output
-  2. `pip show qmd-plugin` → read `Version:` field from pip metadata
+  1. `qmd --version` → parse version string from output (e.g., `qmd 2.0.1` → `"2.0.1"`)
+  2. `mcp__plugin_qmd-plugin_qmd__status` → parse version if exposed in status output
   3. `"unknown"` (final fallback — add a warning to the evidence report)
-  Note: `qmd --version` and `qmd -V` return usage text instead of a version string — do not use them for version detection.
+  Note: QMD is a Bun/Node package (`@tobilu/qmd`). Install via `bun install -g @tobilu/qmd`.
 - Store `commit_short` = first 8 characters of `source_commit` (or `"unknown"` if unavailable) for use in step-08 report.
 - If `scripts_inventory` is non-empty, populate `scripts[]` array and set `stats.scripts_count`. If `assets_inventory` is non-empty, populate `assets[]` array and set `stats.assets_count`. Omit these fields entirely when inventories are empty.
 

package/src/workflows/test-skill/data/scoring-rules.md

@@ -54,6 +54,18 @@ When `docs_only_mode: true` is set by step-03 (indicating a Quick tier skill whe
 
 This is functionally identical to Quick tier weight redistribution but with a different coverage denominator (self-consistency instead of source comparison).
 
+### State 2 Source Access (Any Tier, Provenance-Map Only)
+
+When source is not locally available and analysis resolves to State 2 (provenance-map baseline per source-access-protocol.md):
+
+- **Signature Accuracy:** N/A — provenance-map stores parameters as flat string arrays; verification is string comparison only, not semantic AST verification. Type aliases (`str` vs `String`, `list` vs `List[Any]`) cannot be resolved without live source.
+- **Type Coverage:** N/A — cannot verify type completeness without local source access for AST re-parsing.
+- **Weight redistribution:** Same as Quick tier — Signature Accuracy (22%) and Type Coverage (14%) weights redistributed proportionally to remaining active categories (Export Coverage, Coherence, External Validation).
+- **Applies regardless of detected tier** (including Forge, Forge+, Deep) whenever `analysis_confidence` is `provenance-map` and local source is unavailable.
+- **Export Coverage denominator:** Uses the union of provenance-map entry names and metadata.json `exports[]` names (per source-access-protocol.md State 2 rules).
+
+Note: When provenance-map entries are predominantly T1 (AST-verified at compilation time), the coverage and name-matching data is already at highest confidence. The N/A categories reflect the inability to re-verify at test time, not low-quality extraction data.
+
 ### Forge Tier (ast-grep)
 - Export Coverage: AST-backed export comparison
 - Signature Accuracy: AST-verified signature matching

package/src/workflows/test-skill/steps-c/step-04b-external-validators.md

@@ -60,13 +60,20 @@ Read {outputFile} frontmatter to get the skill directory path (`skillDir`).
 
 Before running external validators, check if `{forge_data_folder}/{skill_name}/evidence-report.md` contains validation results (a `## Validation Results` section with quality scores).
 
-**Staleness check:** Determine whether SKILL.md has changed since the evidence report was generated.
+**Staleness check:** Determine whether SKILL.md has changed since the evidence report was generated. Walk through these checks in order:
 
-**Primary (git-tracked):** Run `git log -1 --format=%cI -- {skillDir}/SKILL.md` to get the last commit date of SKILL.md. Compare against the evidence report's generation date (from its frontmatter or the `## Validation Results` timestamp). If SKILL.md's last commit is newer, results are stale.
+**Pre-check (untracked or staged-only file):** Run `git ls-files --error-unmatch {skillDir}/SKILL.md 2>/dev/null`.
+- If the command fails (exit code non-zero) or git is not available, the file is either **untracked** (new, never committed) or we're in a **non-git environment**:
+  - Check if `{skillDir}/metadata.json` exists and has a `generation_date` field
+  - Compare `metadata.json` `generation_date` against the evidence report's generation date (from its frontmatter or `## Validation Results` timestamp)
+  - If timestamps match within the same minute (same workflow session): auto-reuse is safe — the evidence report was generated from the same SKILL.md content
+  - If timestamps differ or metadata.json is missing: treat as stale, proceed to section 2 for a fresh run
+  - Note: "Staleness check: SKILL.md is untracked/non-git — using metadata.json timestamp comparison."
+- If the command succeeds (file is tracked by git), continue to Primary check below.
 
-**Secondary (uncommitted changes):** Run `git diff --name-only -- {skillDir}/SKILL.md`. If output is non-empty, SKILL.md has uncommitted changes — treat results as stale regardless of commit dates.
+**Primary (git-tracked):** Run `git log -1 --format=%cI -- {skillDir}/SKILL.md` to get the last commit date of SKILL.md. Compare against the evidence report's generation date (from its frontmatter or the `## Validation Results` timestamp). If SKILL.md's last commit is newer, results are stale.
 
-**Fallback (non-git environments):** If git commands fail (not a git repository), fall back to `metadata.json` `generation_date` comparison with a warning: "Staleness check using metadata.json — may be identical to evidence report timestamp. Consider a git-tracked directory for reliable staleness detection."
+**Secondary (uncommitted changes):** Run `git diff --name-only -- {skillDir}/SKILL.md`. If output is non-empty, SKILL.md has uncommitted changes — treat results as stale regardless of commit dates. Also check `git diff --cached --name-only -- {skillDir}/SKILL.md` for staged-but-uncommitted changes — if non-empty, SKILL.md has been staged since last commit, treat results as stale.
 
 If SKILL.md was modified after the evidence report was generated (e.g., after update-skill), the cached results are stale — skip auto-reuse and proceed to section 2 for a fresh run.
 

package/src/workflows/update-skill/steps-c/step-03-re-extract.md

@@ -76,9 +76,25 @@ Perform tier-aware extraction on only the changed files identified in step 02, p
 
 **Remote Source Resolution (Forge/Deep only):**
 
-**MCP source access check (before ephemeral clone):** If MCP source-reading tools are available (zread, deepwiki, gh API, or similar) and `source_repo` is set in metadata.json, use MCP tools to fetch only the changed files from the change manifest. This avoids ephemeral clone overhead entirely. MCP provides full source file content equivalent to a local read. If the fetched content is written to a temp file and analyzed with ast-grep, label confidence as T1. If AST is unavailable (the common case for MCP-fetched content), use pattern-based extraction and label confidence as T1-low.
+**MCP source access (ordered fallback):** When `source_repo` is set in metadata.json, try each MCP tool in order to fetch only the changed files from the change manifest. This avoids ephemeral clone overhead entirely. Tools are ordered by data freshness — gh API returns live GitHub content and is preferred for update-skill where current file versions are required. zread and deepwiki depend on manual indexing and may return stale data if indexes haven't been refreshed since the changes being extracted.
 
-**If MCP unavailable:** Load and follow `{remoteSourceResolutionData}` for ephemeral clone setup, version reconciliation, and AST tool unavailability handling.
+1. **gh API** — `gh api repos/{owner}/{repo}/contents/{path}` for raw file content
+   - If accessible: fetch file content (base64-decoded), always current
+   - If rate-limited, 404, or inaccessible: log tool and reason, continue to next tool
+2. **zread** — `get_repo_structure` + `read_file` for targeted file access
+   - If repo found: fetch changed files, proceed with extraction
+   - If "repo not found" or error: log tool and reason, continue to next tool
+   - Caveat: indexed data — may be stale if index wasn't refreshed after the target changes
+3. **deepwiki** — `ask_question` for targeted export/signature queries
+   - If repo indexed and returns usable source data: extract from response
+   - If no results or repo not indexed: log tool and reason, continue to next tool
+   - Caveat: returns synthesized content, not raw source — extraction quality varies; index may be stale
+
+**Confidence labeling:** MCP-fetched content written to a temp file and analyzed with ast-grep → T1. MCP-fetched content analyzed with pattern matching (AST unavailable) → T1-low.
+
+**If all MCP tools fail for this repo:** Fall back to ephemeral clone — load and follow `{remoteSourceResolutionData}` for clone setup, version reconciliation, and AST tool unavailability handling.
+
+**If all approaches fail (MCP + ephemeral clone):** Degrade to provenance-map-only analysis (State 2, T1 confidence from compilation-time data). Warn user: "Source access failed for {source_repo}. Analysis limited to provenance-map baseline."
 
 **Quick tier (text pattern matching):**
 - Extract function/class/type names via regex patterns