bmad-module-skill-forge 1.5.0 → 1.5.1

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "1.5.0",
+      "version": "1.5.1",
       "author": {
         "name": "Armel"
       },

package/docs/_data/pinned.yaml

@@ -26,7 +26,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "1.5.0"
+skf_version: "1.5.1"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "1.5.0",
+  "version": "1.5.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/shared/scripts/skf-detect-tools.py

@@ -88,13 +88,26 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import shutil
 import subprocess
 import sys
+import tempfile
 from concurrent.futures import ThreadPoolExecutor
 
 
 VALID_TIERS = ("Quick", "Forge", "Forge+", "Deep")
 PROBE_TIMEOUT_SEC = 8  # per-tool subprocess.run timeout
+# Prefer the OS `timeout(1)` utility to bound each probe. A daemon-backed
+# tool (e.g. `qmd status`) can block in an uninterruptible syscall against
+# its daemon; `subprocess.run`'s own post-timeout `process.wait()` is
+# unbounded and never returns in that case, hanging the whole detector.
+# `timeout --kill-after` reaps the child (and its session) at the OS level,
+# so Python's wait always returns. POSIX-only: Windows' `timeout.exe` is an
+# unrelated builtin (waits for input; cannot run a command), and the
+# uninterruptible-wait hang is itself POSIX-specific (Windows uses a
+# forcible TerminateProcess), so on Windows we fall back to subprocess.run's
+# own timeout. None when unavailable.
+_TIMEOUT_BIN = shutil.which("timeout") if os.name == "posix" else None
 CCC_IDENTITY_MARKER = "cocoindex code"  # case-insensitive substring
 
 
@@ -115,16 +128,45 @@ def _run(cmd: list[str], timeout: int = PROBE_TIMEOUT_SEC) -> tuple[int, str, st
     Treats every failure mode (FileNotFoundError, TimeoutExpired, OSError,
     CalledProcessError) as a failed probe — returns rc=127 and an empty
     stdout/stderr. Tool detection should never crash the workflow.
+
+    The child is wrapped in the OS `timeout(1)` utility (when available) so a
+    daemon-backed probe blocked in an uninterruptible syscall (e.g.
+    `qmd status` waiting on its daemon socket) is reaped at the OS level —
+    `subprocess.run`'s own post-timeout `process.wait()` is unbounded and
+    would otherwise never return, hanging the whole detector. Child
+    stdout/stderr are redirected to temp files (no pipe to drain), and
+    `start_new_session=True` isolates the child's process group; the
+    Python-level timeout is a secondary net set slightly above the OS one.
     """
+    if _TIMEOUT_BIN:
+        run_cmd = [_TIMEOUT_BIN, "--kill-after=2", str(timeout), *cmd]
+        py_timeout = timeout + 5
+    else:
+        run_cmd = cmd
+        py_timeout = timeout
     try:
-        result = subprocess.run(
-            cmd,
-            capture_output=True,
-            text=True,
-            timeout=timeout,
-            check=False,
-        )
-        return result.returncode, result.stdout or "", result.stderr or ""
+        with tempfile.TemporaryFile() as out_f, tempfile.TemporaryFile() as err_f:
+            result = subprocess.run(
+                run_cmd,
+                stdin=subprocess.DEVNULL,
+                stdout=out_f,
+                stderr=err_f,
+                timeout=py_timeout,
+                check=False,
+                start_new_session=True,
+            )
+            # Mocked unit tests patch `subprocess.run` to return a fake with
+            # `.stdout`/`.stderr` strings set; real runs redirect to the temp
+            # files (so `result.stdout` is None — read the files instead).
+            stdout = result.stdout
+            if stdout is None:
+                out_f.seek(0)
+                stdout = out_f.read().decode("utf-8", "replace")
+            stderr = result.stderr
+            if stderr is None:
+                err_f.seek(0)
+                stderr = err_f.read().decode("utf-8", "replace")
+            return result.returncode, stdout or "", stderr or ""
     except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
         return 127, "", ""
 

package/src/shared/scripts/skf-manifest-ops.py

@@ -12,7 +12,10 @@ CLI: python3 skf-manifest-ops.py <skills-folder> <command> [args]
 Commands:
   read                          — Read entire manifest
   get <skill-name>              — Get a single skill entry
-  set <skill-name> <version>    — Add/update skill with active version
+  set <skill-name> <version> [--ides a,b]
+                                — Add/update skill with active version;
+                                  --ides unions a comma-separated IDE list
+                                  into the version entry (deduped, sorted)
   remove <skill-name>           — Remove skill from manifest
   deprecate <skill-name> [ver]  — Mark skill or version as deprecated
   rename <old-name> <new-name>  — Rename a skill entry
@@ -124,7 +127,7 @@ def cmd_get(manifest_path, skill_name):
     return {"status": "ok", "skill": skill_name, "entry": exports[skill_name]}
 
 
-def cmd_set(manifest_path, skill_name, version):
+def cmd_set(manifest_path, skill_name, version, ides=None):
     data, err = read_manifest(manifest_path)
     if err:
         return {"status": "error", "error": err}
@@ -140,10 +143,18 @@ def cmd_set(manifest_path, skill_name, version):
     if old_active and old_active in versions and old_active != version:
         versions[old_active]["status"] = "archived"
 
-    # Add or update the new active version
+    # Add or update the new active version. Absent --ides preserves the
+    # existing ides/platforms list verbatim (backward-compatible). When
+    # --ides is supplied, union it in (dedupe, keep sorted).
     existing_version = versions.get(version, {})
+    merged_ides = list(existing_version.get("ides", existing_version.get("platforms", [])))
+    if ides:
+        for ide in ides:
+            if ide not in merged_ides:
+                merged_ides.append(ide)
+        merged_ides = sorted(merged_ides)
     versions[version] = {
-        "ides": existing_version.get("ides", existing_version.get("platforms", [])),
+        "ides": merged_ides,
         "last_exported": today,
         "status": "active",
     }
@@ -205,7 +216,7 @@ def cmd_rename(manifest_path, old_name, new_name):
 def main():
     if len(sys.argv) < 3:
         print("Usage: python3 skf-manifest-ops.py <skills-folder> <command> [args]", file=sys.stderr)
-        print("Commands: read, get <name>, set <name> <version>, remove <name>, deprecate <name> [version], rename <old> <new>", file=sys.stderr)
+        print("Commands: read, get <name>, set <name> <version> [--ides a,b], remove <name>, deprecate <name> [version], rename <old> <new>", file=sys.stderr)
         sys.exit(1)
 
     skills_folder = Path(sys.argv[1])
@@ -217,7 +228,12 @@ def main():
     elif command == "get" and len(sys.argv) >= 4:
         result = cmd_get(manifest_path, sys.argv[3])
     elif command == "set" and len(sys.argv) >= 5:
-        result = cmd_set(manifest_path, sys.argv[3], sys.argv[4])
+        ides_arg = None
+        if "--ides" in sys.argv:
+            idx = sys.argv.index("--ides")
+            if idx + 1 < len(sys.argv):
+                ides_arg = [s for s in sys.argv[idx + 1].split(",") if s]
+        result = cmd_set(manifest_path, sys.argv[3], sys.argv[4], ides_arg)
     elif command == "remove" and len(sys.argv) >= 4:
         result = cmd_remove(manifest_path, sys.argv[3])
     elif command == "deprecate" and len(sys.argv) >= 4:

package/src/skf-analyze-source/references/identify-units.md

@@ -2,7 +2,9 @@
 nextStepFile: 'map-and-detect.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 heuristicsFile: 'references/unit-detection-heuristics.md'
-disqualifyCandidatesScript: '{project-root}/src/shared/scripts/skf-disqualify-candidates.py'
+disqualifyCandidatesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-disqualify-candidates.py'
+  - '{project-root}/src/shared/scripts/skf-disqualify-candidates.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -32,6 +34,8 @@ Load {heuristicsFile} for classification rules.
 
 ### 2. Apply Detection Heuristics
 
+**Resolve `{disqualifyCandidatesHelper}`** from `{disqualifyCandidatesProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 For EACH detected boundary from the scan:
 
 **Step A — Count detection signals:**
@@ -58,16 +62,16 @@ Run the shared disqualification helper to apply the deterministic subset of the
    ```json
    [
      {"name": "<unit-name>",
-      "path": "<rel-from-project-root>",
+      "path": "<rel-from-analyzed-source-root (project_paths[0])>",
       "files": ["<rel-path>", ...]},
      ...
    ]
    ```
 2. **Invoke the script** via stdin:
    ```bash
-   uv run {disqualifyCandidatesScript} filter --boundaries - --source-root {project-root}
+   uv run {disqualifyCandidatesHelper} filter --boundaries - --source-root {project_paths[0]}
    ```
-   piping the boundaries JSON on stdin. The script emits:
+   piping the boundaries JSON on stdin. `--source-root` is the analyzed-source root (`project_paths[0]`) — the directory the boundaries/manifest scan ran against — not `{project-root}` (the forge workspace), which differs whenever the analyzed target lives outside the forge workspace. The script emits:
    ```json
    {
      "kept":    [{"name": "...", "path": "...", "files_count": N, "loc_total": L}, ...],

package/src/skf-analyze-source/references/init.md

@@ -26,9 +26,11 @@ To initialize the analyze-source workflow by loading configuration, detecting co
 Look for {outputFile}.
 
 **IF the file exists AND has `stepsCompleted` with entries:**
-- "**Found an existing analysis report. Resuming previous session...**"
-- Load, read entirely, then execute {continueFile}
-- **STOP HERE** — do not continue this sequence
+- The report filename is keyed to `{project_name}` (the forge workspace), not the analyzed target — so a report from a *different* target can collide here. Before resuming, establish the requested target and compare it to the existing report:
+  - Determine the requested target now: if `--project-path <path>` was passed at invocation, set `project_paths[]` from it (comma-split if multiple); otherwise collect the path(s) using the section-3 "Collect Project Path" prompt and store as `project_paths[]`. (Section 3 must NOT re-prompt when `project_paths[]` is already populated here.)
+  - Read the existing report's frontmatter `project_paths`.
+  - **IF the existing report's `project_paths` matches the requested target:** "**Found an existing analysis report. Resuming previous session...**" — Load, read entirely, then execute {continueFile}. **STOP HERE** — do not continue this sequence.
+  - **ELSE (different target — stale collision):** the existing report belongs to another analysis. Archive it by renaming to `{forge_data_folder}/analyze-source-report-{project_name}-<UTC-timestamp>.md`, announce "**Existing report belongs to a different target — archived as <name>; starting a fresh analysis.**", then continue to section 2 (skip re-collecting the path in section 3 — it is already set).
 
 **IF the file does not exist OR stepsCompleted is empty:**
 - Continue to section 2
@@ -46,7 +48,7 @@ Look for {outputFile}.
 
 ### 3. Collect Project Path
 
-**Headless flag consumption:** If `--project-path <path>` was passed at invocation, set `project_paths[]` directly from the flag value (comma-split if multiple paths were supplied), skip the prompt below, and proceed to validation. Otherwise prompt as today.
+**Headless flag consumption:** If `project_paths[]` is already populated (e.g. collected by the section-1 stale-collision guard) OR `--project-path <path>` was passed at invocation, set/keep `project_paths[]` (comma-split the flag value if multiple paths were supplied), skip the prompt below, and proceed to validation. Otherwise prompt as today.
 
 "**Welcome to Analyze Source — the SKF decomposition engine.**
 

package/src/skf-analyze-source/references/scan-project.md

@@ -2,7 +2,9 @@
 nextStepFile: 'identify-units.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 heuristicsFile: 'references/unit-detection-heuristics.md'
-scanManifestsScript: '{project-root}/src/shared/scripts/skf-scan-manifests.py'
+scanManifestsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-scan-manifests.py'
+  - '{project-root}/src/shared/scripts/skf-scan-manifests.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -33,11 +35,13 @@ Load {heuristicsFile} for reference on detection signals.
 
 ### 2. Scan Directory Structure
 
+**Resolve `{scanManifestsHelper}`** from `{scanManifestsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 **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.)
-3. Enumerate package manifests deterministically — invoke `uv run {scanManifestsScript} scan {path}` and parse the JSON envelope. The script returns `{manifests[], total_unique, monorepo, warnings?}` covering npm/python/rust/go/maven/gradle/ruby/composer/swift; record each `{path, ecosystem}` for the manifests catalog in §4 and capture `monorepo` for the boundary-signal pass in §3
+3. Enumerate package manifests deterministically — invoke `uv run {scanManifestsHelper} scan {path}` and parse the JSON envelope. The script returns `{manifests[], total_unique, monorepo, warnings?}` covering npm/python/rust/go/maven/gradle/ruby/composer/swift; record each `{path, ecosystem}` for the manifests catalog in §4 and capture `monorepo` for the boundary-signal pass in §3
 4. Locate entry point files (index.ts, main.ts, app.ts, main.go, main.rs, __init__.py, etc.)
 5. Detect service configuration (Dockerfile, docker-compose.yml, kubernetes manifests, serverless.yml) — keep this step LLM-driven; file glob + presence check is sufficient, no parsing required
 6. Return structured findings — file paths and types only, not contents

package/src/skf-audit-skill/references/init.md

@@ -2,8 +2,12 @@
 nextStepFile: 're-index.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
 templateFile: 'assets/drift-report-template.md'
-loadProvenanceScript: '{project-root}/src/shared/scripts/skf-load-provenance.py'
-compareFileHashesScript: '{project-root}/src/shared/scripts/skf-compare-file-hashes.py'
+loadProvenanceProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-load-provenance.py'
+  - '{project-root}/src/shared/scripts/skf-load-provenance.py'
+compareFileHashesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-compare-file-hashes.py'
+  - '{project-root}/src/shared/scripts/skf-compare-file-hashes.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -98,12 +102,14 @@ Load the following from the skill directory:
 
 Search for provenance map at `{forge_data_folder}/{skill_name}/{active_version}/provenance-map.json` (i.e., `{forge_version}/provenance-map.json`). If not found at the versioned path, fall back to `{forge_data_folder}/{skill_name}/provenance-map.json`:
 
+**Resolve `{loadProvenanceHelper}`** from `{loadProvenanceProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 **If found:**
 - Record provenance map age (days since last extraction) from file mtime
 - Normalize the map's deterministic projections in one subprocess call:
 
   ```bash
-  uv run {loadProvenanceScript} normalize {provenanceMap}
+  uv run {loadProvenanceHelper} normalize {provenanceMap}
   ```
 
   Parse the emitted JSON and stash these fields in workflow context (downstream steps read them directly — no re-walk):

package/src/skf-audit-skill/references/structural-diff.md

@@ -1,8 +1,12 @@
 ---
 nextStepFile: 'semantic-diff.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
-loadProvenanceScript: '{project-root}/src/shared/scripts/skf-load-provenance.py'
-compareFileHashesScript: '{project-root}/src/shared/scripts/skf-compare-file-hashes.py'
+loadProvenanceProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-load-provenance.py'
+  - '{project-root}/src/shared/scripts/skf-load-provenance.py'
+compareFileHashesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-compare-file-hashes.py'
+  - '{project-root}/src/shared/scripts/skf-compare-file-hashes.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -89,10 +93,12 @@ For each changed export, record:
 
 **Only execute if provenance-map.json contains `file_entries`.**
 
+**Resolve `{compareFileHashesHelper}`** from `{compareFileHashesProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 Run one deterministic comparison subprocess — it walks tracked file_entries[] AND the inverse direction (source-tree → candidate set in standard script/asset/doc directories) so the LLM does not orchestrate per-file hashing:
 
 ```bash
-uv run {compareFileHashesScript} compare {provenanceMap} {sourceRoot}
+uv run {compareFileHashesHelper} compare {provenanceMap} {sourceRoot}
 ```
 
 Parse the emitted JSON:

package/src/skf-brief-skill/SKILL.md

@@ -30,7 +30,7 @@ You are a skill scoping architect collaborating with a developer who wants to cr
 These rules apply to every step in this workflow:
 
 - Only load one step file at a time — never preload future steps
-- **Lazy-load references and assets:** `references/*.md` and `assets/*.md` files are loaded inside the section that needs them, not at step entry. If a section is skipped (e.g. `version-resolution.md` when `{extractPublicApiScript}` already returned a version, `scope-templates.md` for the `docs-only` branch that bypasses §2c), do not load that file. Each unnecessary load costs context (~5-10 KB per reference) and biases the LLM toward consulting material the current path does not need.
+- **Lazy-load references and assets:** `references/*.md` and `assets/*.md` files are loaded inside the section that needs them, not at step entry. If a section is skipped (e.g. `version-resolution.md` when `{extractPublicApiHelper}` already returned a version, `scope-templates.md` for the `docs-only` branch that bypasses §2c), do not load that file. Each unnecessary load costs context (~5-10 KB per reference) and biases the LLM toward consulting material the current path does not need.
 - Always communicate in `{communication_language}` (the language for user-facing prose). Written artifact text — the `description`, `notes`, and other free-form fields persisted into `skill-brief.yaml` — is in `{document_output_language}`; per-step rules call this out where it applies (see step 5). The two values may be the same.
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
 

package/src/skf-brief-skill/references/analyze-target.md

@@ -1,9 +1,15 @@
 ---
 nextStepFile: 'scope-definition.md'
 versionResolutionFile: 'references/version-resolution.md'
-extractPublicApiScript: '{project-root}/src/shared/scripts/skf-extract-public-api.py'
-detectWorkspacesScript: '{project-root}/src/shared/scripts/skf-detect-workspaces.py'
-detectLanguageScript: '{project-root}/src/shared/scripts/skf-detect-language.py'
+extractPublicApiProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-extract-public-api.py'
+  - '{project-root}/src/shared/scripts/skf-extract-public-api.py'
+detectWorkspacesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-workspaces.py'
+  - '{project-root}/src/shared/scripts/skf-detect-workspaces.py'
+detectLanguageProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-language.py'
+  - '{project-root}/src/shared/scripts/skf-detect-language.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -58,11 +64,13 @@ Display: "**Resolving target...**"
 
 ### 1b. Detect Monorepo / Workspace Layout
 
-Delegate workspace detection to `{detectWorkspacesScript}` instead of reasoning through manifest rules in prose. Build a payload from the tree fetched in §1 plus the small set of root manifests the detector needs, then invoke the script:
+**Resolve `{detectWorkspacesHelper}`** from `{detectWorkspacesProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Delegate workspace detection to `{detectWorkspacesHelper}` instead of reasoning through manifest rules in prose. Build a payload from the tree fetched in §1 plus the small set of root manifests the detector needs, then invoke the script:
 
 ```bash
 echo '{"tree": [<flat list of repo-relative file paths>], "manifests": {"package.json": "<raw text>", "Cargo.toml": "<raw text>", "pnpm-workspace.yaml": "<raw text>", "lerna.json": "<raw text>"}}' | \
-  uv run {detectWorkspacesScript}
+  uv run {detectWorkspacesHelper}
 ```
 
 - **`tree`** — pass the flat list of repo-relative file paths already fetched in §1 (for GitHub: the `path` values from the `gh api .../git/trees/HEAD?recursive=1` response; for local: the equivalent listing).
@@ -104,10 +112,12 @@ List the top-level directory structure:
 
 ### 3. Detect Primary Language
 
-Delegate the rule walk to `{detectLanguageScript}` instead of evaluating manifest presence and extension frequency in prose:
+**Resolve `{detectLanguageHelper}`** from `{detectLanguageProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Delegate the rule walk to `{detectLanguageHelper}` instead of evaluating manifest presence and extension frequency in prose:
 
 ```bash
-echo '{"tree": [<flat list of repo-relative file paths from §1>]}' | uv run {detectLanguageScript}
+echo '{"tree": [<flat list of repo-relative file paths from §1>]}' | uv run {detectLanguageHelper}
 ```
 
 The script returns `{language, confidence, detection_source, fallback_to_extension_frequency}` after walking the documented rule table (manifest presence first — package.json with tsconfig.json disambiguation, Cargo.toml, pyproject.toml/setup.py/setup.cfg, go.mod, pom.xml, build.gradle.kts, build.gradle Groovy with Java/Kotlin disambiguation, *.csproj/*.sln, Gemfile — then extension-frequency fallback over recognized source extensions). Use the returned values directly:
@@ -120,7 +130,9 @@ If `confidence` is `low` (or `unknown` is returned for `language`): flag for use
 
 ### 4. List Top-Level Modules and Exports
 
-Identify the public API surface. **Delegate the parsing to `{extractPublicApiScript}` whenever the detected language is supported** — the script is the single source of truth for manifest parsing, export discovery, and version detection across the whole SKF pipeline. Hand-rolling these in prose creates drift seams the LLM cannot fully close.
+**Resolve `{extractPublicApiHelper}`** from `{extractPublicApiProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Identify the public API surface. **Delegate the parsing to `{extractPublicApiHelper}` whenever the detected language is supported** — the script is the single source of truth for manifest parsing, export discovery, and version detection across the whole SKF pipeline. Hand-rolling these in prose creates drift seams the LLM cannot fully close.
 
 **Script-supported languages** (use the script): `js`, `ts`, `javascript`, `typescript`, `python`, `rust`, `go`, `java`, `kotlin`.
 
@@ -153,7 +165,7 @@ This section runs exactly one of §4.1 (script path) or §4.2 (fallback path) ba
 3. Invoke the script and parse its JSON stdout:
 
    ```bash
-   echo '<payload-json>' | uv run {extractPublicApiScript} --language <lang> --mode quick
+   echo '<payload-json>' | uv run {extractPublicApiHelper} --mode quick
    ```
 
    On a non-zero exit (codes 1 or 2 per the script's docstring), capture stderr, log it, and fall through to §4.2 (the prose-fallback path) — never HALT just because the script choked on an unusual manifest.
@@ -200,7 +212,7 @@ If CCC is unavailable or returns no results: skip this subsection silently.
 
 ### 4b. Detect Source Version
 
-**When the language was script-supported (§4 took the script path):** the `version` field returned by `{extractPublicApiScript}` IS the detected version — do not re-derive it and do not load `{versionResolutionFile}`. The script already implements the language-specific lookups documented in that reference, so loading the reference here only burns context.
+**When the language was script-supported (§4 took the script path):** the `version` field returned by `{extractPublicApiHelper}` IS the detected version — do not re-derive it and do not load `{versionResolutionFile}`. The script already implements the language-specific lookups documented in that reference, so loading the reference here only burns context.
 
 **When the language was not script-supported:** load `{versionResolutionFile}` and follow the prose Detection Algorithm directly (Ruby / C# / Swift / etc. fall outside the script's coverage).
 

package/src/skf-brief-skill/references/gather-intent.md

@@ -6,8 +6,12 @@ headlessArgsFile: 'references/headless-args.md'
 headlessSourceAuthorityDetectionFile: 'references/headless-source-authority-detection.md'
 portfolioSimilarityCheckFile: 'references/portfolio-similarity-check.md'
 draftCheckpointFile: 'references/draft-checkpoint.md'
-validateBriefInputsScript: '{project-root}/src/shared/scripts/skf-validate-brief-inputs.py'
-emitBriefEnvelopeScript: '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
+validateBriefInputsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-inputs.py'
+  - '{project-root}/src/shared/scripts/skf-validate-brief-inputs.py'
+emitBriefEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -302,14 +306,16 @@ Display: "**Select:** [C] Continue to Target Analysis · [X] Cancel and exit"
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
-- **GATE [default: use args]** — If `{headless_mode}`, consume pre-supplied arguments and auto-proceed. The full argument set (required/optional, defaults, halt codes, enum values) is documented in `{headlessArgsFile}` — load it now if you need to look up a specific argument. Validation is delegated to `{validateBriefInputsScript}`; the table is the canonical operator-facing documentation, the script enforces it.
+- **Resolve `{validateBriefInputsHelper}`** from `{validateBriefInputsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+- **GATE [default: use args]** — If `{headless_mode}`, consume pre-supplied arguments and auto-proceed. The full argument set (required/optional, defaults, halt codes, enum values) is documented in `{headlessArgsFile}` — load it now if you need to look up a specific argument. Validation is delegated to `{validateBriefInputsHelper}`; the table is the canonical operator-facing documentation, the script enforces it.
 
   **Preset merge (before validation).** If the headless args include a `preset` field, load `{sidecar_path}/brief-presets/{preset}.yaml` and merge its contents as defaults — explicit args override preset values, key by key. The preset file is YAML; if it does not exist, log `"warn: preset '{name}' not found at {path} — proceeding without preset"` and continue (do not HALT). If it parses but contains unknown fields, log per-field warnings and pass through unchanged (the validator's KNOWN_FIELDS check will catch any that survive). Drop the `preset` key itself from the merged dict before passing to the validator (it is consumed at this level and is not a brief field).
 
-  **Delegate validation to `{validateBriefInputsScript}`** instead of reasoning through the table rules in prose:
+  **Delegate validation to `{validateBriefInputsHelper}`** instead of reasoning through the table rules in prose:
 
   ```bash
-  echo '<headless-args-as-json>' | uv run {validateBriefInputsScript}
+  echo '<headless-args-as-json>' | uv run {validateBriefInputsHelper}
   ```
 
   The script returns a JSON envelope: `{valid, errors[], warnings[], normalized, halt_reason}`. Apply the result deterministically:

package/src/skf-brief-skill/references/headless-args.md

@@ -1,6 +1,6 @@
 # Headless Argument Table
 
-Loaded by step 1 §8 only when `{headless_mode}` is true. Canonical operator-facing documentation for the argument set consumed at step 1's GATE; the `{validateBriefInputsScript}` enforces these rules deterministically (its `KNOWN_FIELDS` set must stay in sync with this table).
+Loaded by step 1 §8 only when `{headless_mode}` is true. Canonical operator-facing documentation for the argument set consumed at step 1's GATE; the `{validateBriefInputsHelper}` enforces these rules deterministically (its `KNOWN_FIELDS` set must stay in sync with this table).
 
 | Argument | Required | Default | Notes |
 |----------|----------|---------|-------|

package/src/skf-brief-skill/references/qmd-collection-registration.md

@@ -41,7 +41,7 @@ echo '{
   "skill_name": "{skill-name}",
   "created_at": "{current ISO date}"
   // include "status": "pending" only when embed verification failed
-}' | uv run {forgeTierRwScript} register-qmd-collection --target {forgeTierFile}
+}' | uv run {forgeTierRwHelper} register-qmd-collection --target {forgeTierFile}
 ```
 
 The script handles the upsert deterministically (replace existing entry with same `name`, else append) and preserves all other forge-tier state (tools, tier, ccc_index, ccc_index_registry, other qmd_collections entries) — no need to reason about YAML re-rendering or section comments.

package/src/skf-brief-skill/references/scope-definition.md

@@ -1,7 +1,9 @@
 ---
 nextStepFile: 'confirm-brief.md'
 scopeTemplatesFile: 'assets/scope-templates.md'
-recommendScopeTypeScript: '{project-root}/src/shared/scripts/skf-recommend-scope-type.py'
+recommendScopeTypeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-recommend-scope-type.py'
+  - '{project-root}/src/shared/scripts/skf-recommend-scope-type.py'
 advancedElicitationSkill: '/bmad-advanced-elicitation'
 partyModeSkill: '/bmad-party-mode'
 ---
@@ -82,7 +84,9 @@ Load `{scopeTemplatesPath}` for the scope type options ([F], [M], [P], [C], [R])
 
 **Recommend a scope type — don't present the five options as equal weight.** SKILL.md states this workflow "steers toward the smaller, sharper version when scope is unclear" — surface that opinion at decision time. Use the analysis from step 2 and the user's intent from step 1 to pick the best-fit recommendation, then present the menu with that option marked as the suggested default.
 
-**Delegate the recommendation to `{recommendScopeTypeScript}`** instead of walking the heuristic ladder in prose. The script is the single source of truth for the five-rule ladder (component-registry → reference-app keywords → specific-modules naming/count → narrow-public-api → default full-library) plus the docs-only short-circuit. Both the interactive recommendation and the §6 headless GATE invoke the same script — same inputs, same outputs, no drift.
+**Resolve `{recommendScopeTypeHelper}`** from `{recommendScopeTypeProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+**Delegate the recommendation to `{recommendScopeTypeHelper}`** instead of walking the heuristic ladder in prose. The script is the single source of truth for the five-rule ladder (component-registry → reference-app keywords → specific-modules naming/count → narrow-public-api → default full-library) plus the docs-only short-circuit. Both the interactive recommendation and the §6 headless GATE invoke the same script — same inputs, same outputs, no drift.
 
 **Fetch registry-file contents before building the payload.** Step-02 §4.1 fetches `package.json` plus the entry-point files but does not fetch `registry.ts` / `components.ts` — the deep-match branch of the component-registry rule needs those contents. Scan the tree for any of `registry.ts` / `registry.tsx` / `components.ts` / `components.tsx` (any depth). For each match, fetch its contents in **one message with N parallel Bash calls** (`gh api repos/{owner}/{repo}/contents/{path}` for GitHub, file reads for local), then base64-decode the responses together. Skip the fetch if the tree contains no registry files.
 
@@ -97,7 +101,7 @@ echo '{
   "entry_files": [{"path": "<registry path>", "content": "<contents>"}, ...],
   "source_type": "source",
   "mode": "interactive"
-}' | uv run {recommendScopeTypeScript}
+}' | uv run {recommendScopeTypeHelper}
 ```
 
 `entry_files` carries the registry contents fetched above; omit when no registry files exist in the tree. `mode: "interactive"` activates the content-inspection branch of the component-registry rule (10+ entries or `Component[]` annotation); the headless GATE in §6 uses `mode: "headless"` which falls back to presence-only matching. `source_type: "docs-only"` short-circuits to `docs-only` regardless of the other signals.
@@ -182,7 +186,7 @@ Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Conti
 - ALWAYS halt and wait for user input after presenting menu
 - **GATE [default: C]** — If `{headless_mode}`: consume the headless inputs from step 1 in priority order:
   - If `scope_type` was supplied, use it (must match one of the six valid types) and skip the §2c template menu.
-  - Otherwise auto-select via `{recommendScopeTypeScript}` — invoke the script with the **same payload shape** documented in §2c but with `mode: "headless"` (presence-only matching for the component-registry rule, since `entry_files` may not be available without an interactive context). Use the returned `scope_type` and log `"headless: scope_type={value} from heuristic={matched_heuristic}"`. The script's docs-only short-circuit handles `source_type=docs-only` automatically.
+  - Otherwise auto-select via `{recommendScopeTypeHelper}` — invoke the script with the **same payload shape** documented in §2c but with `mode: "headless"` (presence-only matching for the component-registry rule, since `entry_files` may not be available without an interactive context). Use the returned `scope_type` and log `"headless: scope_type={value} from heuristic={matched_heuristic}"`. The script's docs-only short-circuit handles `source_type=docs-only` automatically.
   - If `include`/`exclude` were supplied, use them verbatim (split on comma) instead of running the boundary prompts in §3.
   - If `scripts_intent`/`assets_intent` were supplied, record them and skip §5b; otherwise default to `detect`.
   - Set `scope.rationale`: `recommended`/`heuristic` from the script (or `recommended = scope_type` arg, `heuristic = "user-supplied-arg"` when `scope_type` was passed); `chosen = <resolved type>`; `accepted_recommendation = (no scope_type arg)`; `reason = "<script rationale>"` (auto path) or `"headless: scope_type supplied as argument"` (arg path); `recorded = {date}`. No prompt — headless never asks "why".

package/src/skf-brief-skill/references/write-brief.md

@@ -3,9 +3,15 @@ briefSchemaFile: 'assets/skill-brief-schema.md'
 versionResolutionFile: 'references/version-resolution.md'
 qmdRegistrationFile: 'references/qmd-collection-registration.md'
 nextStepFile: 'health-check.md'
-writeSkillBriefScript: '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
-emitBriefEnvelopeScript: '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
-forgeTierRwScript: '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
+writeSkillBriefProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-write-skill-brief.py'
+  - '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
+emitBriefEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
+forgeTierRwProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-forge-tier-rw.py'
+  - '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 ---
 
@@ -30,7 +36,9 @@ To generate the complete skill-brief.yaml from the approved brief data and write
 
 ### 1. Reference the Schema (LLM context only)
 
-`{briefSchemaPath}` and `{versionResolutionFile}` document the brief contract for human readers. The deterministic enforcement of that contract lives in `{writeSkillBriefScript}` and its JSON Schema artifact at `src/shared/scripts/schemas/skill-brief.v1.json`. Load `{briefSchemaPath}` only if you need to explain a specific field to the user during inline adjustments — otherwise skip the read; the script is the source of truth.
+**Resolve `{writeSkillBriefHelper}`** from `{writeSkillBriefProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+`{briefSchemaPath}` and `{versionResolutionFile}` document the brief contract for human readers. The deterministic enforcement of that contract lives in `{writeSkillBriefHelper}` and its JSON Schema artifact at `src/shared/scripts/schemas/skill-brief.v1.json`. Load `{briefSchemaPath}` only if you need to explain a specific field to the user during inline adjustments — otherwise skip the read; the script is the source of truth.
 
 ### 2. Resolve Output Path
 
@@ -94,7 +102,7 @@ Assemble the brief context as a **flat** JSON object — every approved value is
 Pipe it into the writer script with the `--from-flat` flag:
 
 ```bash
-echo '<context-json>' | uv run {writeSkillBriefScript} write --target {resolved-target-path} --from-flat
+echo '<context-json>' | uv run {writeSkillBriefHelper} write --target {resolved-target-path} --from-flat
 ```
 
 The script translates flat → nested internally, drops the null optional fields, and runs the same schema validation and atomic write as before — pass every key always, the writer decides what reaches the YAML.
@@ -121,20 +129,22 @@ The script:
 
 ### 4b. Headless Result Envelope (Canonical)
 
+**Resolve `{emitBriefEnvelopeHelper}`** from `{emitBriefEnvelopeProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 This section is the canonical envelope-emission reference for the workflow. Every headless emission — the success terminal here and every HARD HALT in step 1/02/05 — uses this contract. Remote sites point here instead of restating it.
 
 **Success (this call site only — emitted from §3 directly):**
 
 ```bash
 echo '{"status":"success","brief_path":"<from §3 response>","skill_name":"<name>","version":"<from §3 response>","language":"<language>","scope_type":"<scope.type>","halt_reason":null}' | \
-  uv run {emitBriefEnvelopeScript} emit
+  uv run {emitBriefEnvelopeHelper} emit
 ```
 
 **Error (used by every HARD HALT site):**
 
 ```bash
 echo '{"status":"error","skill_name":"<name>","halt_reason":"<reason>"}' | \
-  uv run {emitBriefEnvelopeScript} emit --target stderr
+  uv run {emitBriefEnvelopeHelper} emit --target stderr
 ```
 
 When the HALT fires before `skill_name` has been resolved (step 1 §1 pre-flight write probe, step 1 §8 input-missing on a malformed args bundle), pass the partially-gathered value or the literal `"unknown"` — the script accepts any non-empty string at this position.
@@ -149,6 +159,8 @@ When `{headless_mode}` is false, skip this section silently — no envelope is e
 
 ### 5. QMD Collection Registration (Deep Tier Only)
 
+**Resolve `{forgeTierRwHelper}`** from `{forgeTierRwProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 **IF forge tier is Deep AND QMD tool is available:** load `{qmdRegistrationFile}` and follow the procedure there to index the brief into a QMD collection and update the forge-tier registry.
 
 **IF forge tier is NOT Deep OR QMD is not available:** skip this section silently — do not load `{qmdRegistrationFile}`. No messaging.

package/src/skf-create-skill/references/extraction-patterns.md

@@ -400,6 +400,8 @@ When using ast-grep for extraction, be aware of these documented limitations:
 
 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.
 
+8. **Rust `pub fn` any-pattern returns zero; bare `pub fn $NAME` over-captures (ast-grep 0.42.x):** The `rust-public-functions` recipe's `any:` of `pub fn $NAME($$$PARAMS) -> $RET` / `pub fn $NAME($$$PARAMS)` returns "No matches found" on real Rust sources with ast-grep 0.42.2, even on crates containing 200+ public functions. Dropping to the bare `pub fn $NAME` pattern matches, but over-captures restricted-visibility functions such as `pub(crate) fn` / `pub(super) fn`, which are **not** public API. **Workaround:** Prefer a visibility-constrained source grep — `rg '^\s*pub fn ' <src>` filtered to exclude lines beginning `pub(` — cross-checked against the AN-verified public surface, at T1-low confidence. Never silently accept zero results for Rust public functions, and never treat a bare `pub fn $NAME` match set as the public API without stripping `pub(...)`-restricted items. See the Rust — public functions 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/validate.md

@@ -61,11 +61,11 @@ Run the external skill-check tool against the compiled skill staging directory.
 **Flag probe (run once, cache the result for §4 and §5 re-invocations):**
 
 ```bash
-npx skill-check --help 2>/dev/null | grep -- --no-security-scan
+npx skill-check check --help 2>/dev/null | grep -- --no-security-scan
 ```
 
 - If the probe matches `--no-security-scan`: set `{security_scan_flag} = "--no-security-scan"`.
-- Else run a second probe — `npx skill-check --help 2>/dev/null | grep -- --skip-security` — and if it matches, set `{security_scan_flag} = "--skip-security"`.
+- Else run a second probe — `npx skill-check check --help 2>/dev/null | grep -- --skip-security` — and if it matches, set `{security_scan_flag} = "--skip-security"`.
 - If neither flag exists: set `{security_scan_flag} = ""` (empty) AND set `{skill_check_flag_fallback} = true`. Skip §2 and §4 automated flows entirely — fall through to §3 manual frontmatter validation. Record in evidence-report: `skill_check_flag_probe: neither --no-security-scan nor --skip-security supported by installed skill-check; validation performed manually`.
 
 **If a security-scan-disable flag was resolved (probe succeeded):**

package/src/skf-create-stack-skill/references/detect-integrations.md

@@ -2,7 +2,9 @@
 nextStepFile: 'compile-stack.md'
 integrationPatterns: 'references/integration-patterns.md'
 composeModeRules: 'references/compose-mode-rules.md'
-pairIntersectScript: '{project-root}/src/shared/scripts/skf-pair-intersect.py'
+pairIntersectProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-pair-intersect.py'
+  - '{project-root}/src/shared/scripts/skf-pair-intersect.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -35,8 +37,11 @@ From `confirmed_dependencies`, conceptually you have N*(N-1)/2 unordered pairs.
    ]
    ```
 2. **Invoke the script** via stdin (or a temp file under `{forge_data_folder}/` if stdin piping is unavailable):
+
+   **Resolve `{pairIntersectHelper}`** from `{pairIntersectProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
    ```bash
-   uv run {pairIntersectScript} intersect --libraries -
+   uv run {pairIntersectHelper} intersect --libraries -
    ```
    piping the libraries JSON on stdin. The script emits:
    ```json

package/src/skf-create-stack-skill/references/detect-manifests.md

@@ -1,7 +1,9 @@
 ---
 nextStepFile: 'rank-and-confirm.md'
 manifestPatterns: 'references/manifest-patterns.md'
-scanManifestsScript: '{project-root}/src/shared/scripts/skf-scan-manifests.py'
+scanManifestsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-scan-manifests.py'
+  - '{project-root}/src/shared/scripts/skf-scan-manifests.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -90,8 +92,10 @@ Store the explicit list as `raw_dependencies` and skip to [Display Detection Sum
 
 Invoke the deterministic manifest scanner — it walks the project root, parses every recognised manifest, dedupes the production dep set, and flags monorepo layout:
 
+**Resolve `{scanManifestsHelper}`** from `{scanManifestsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 ```bash
-uv run {scanManifestsScript} scan {scan_root}
+uv run {scanManifestsHelper} scan {scan_root}
 ```
 
 Where `{scan_root}` is the project root path. Load `{manifestPatterns}` for the ecosystem reference table that documents supported filenames, dependency keys, and normalisation rules; the script implements exactly that table (npm/pnpm/yarn, python pip/poetry/pdm, rust cargo, go modules, java/kotlin maven + gradle, ruby bundler, composer, swift package manager). Exclusion patterns (`node_modules/`, `.venv/`, `vendor/`, `dist/`, `build/`, `target/`, `.git/`, hidden dirs) are applied internally.

package/src/skf-create-stack-skill/references/parallel-extract.md

@@ -1,6 +1,8 @@
 ---
 nextStepFile: 'detect-integrations.md'
-enumerateStackSkillsScript: '{project-root}/src/shared/scripts/skf-enumerate-stack-skills.py'
+enumerateStackSkillsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-enumerate-stack-skills.py'
+  - '{project-root}/src/shared/scripts/skf-enumerate-stack-skills.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -33,8 +35,10 @@ Use `skill_package_path` (stored in step 2 and optionally refreshed above) direc
 
 **Exports resolution order (H1) — script-driven:** Do NOT walk per-skill `metadata.json` → `references/` → SKILL.md by hand. Invoke the helper once at step entry to compute the full inventory for every confirmed skill in one deterministic call:
 
+**Resolve `{enumerateStackSkillsHelper}`** from `{enumerateStackSkillsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 ```bash
-uv run {enumerateStackSkillsScript} enumerate {skills_output_folder}
+uv run {enumerateStackSkillsHelper} enumerate {skills_output_folder}
 ```
 
 The script emits JSON of the form:

package/src/skf-export-skill/references/preflight-snippet-root-probe.md

@@ -48,8 +48,9 @@ Emit a single warning (once, not per snippet) and present resolution options bef
 > - **(a) Set override** — add `snippet_skill_root_override: {observed_prefix}` to `config.yaml`. Snippets keep their on-disk prefix; the managed section references the real location.
 > - **(b) Proceed with IDE mapping** — step 4 will rewrite every snippet's root path to the IDE's skill_root. Use this only if the IDE's skill directory actually contains the skill files.
 > - **(c) Cancel** — abort export and investigate.
+> - **(d) Use observed prefix for this run only** — set the effective snippet root to the single observed on-disk prefix for this export run, without writing to `config.yaml`. The managed section references the real on-disk location. (Only offered when exactly one prefix was observed.)
 >
-> If multiple distinct prefixes were observed, the snippets disagree with each other — investigate before choosing (a).
+> If multiple distinct prefixes were observed, the snippets disagree with each other — investigate before choosing (a) or (d).
 
 Wait for user choice.
 
@@ -69,6 +70,10 @@ Continue to §2. Step 4's root-rewrite algorithm will rewrite every snippet's pr
 
 HALT. Exit code 6, `halt_reason: "user-cancelled"`. No files written.
 
+### (d) Use observed prefix for this run only
+
+**Only available when `observed_prefixes` contains exactly one value.** Set the effective snippet root for this run to that single observed prefix — do NOT mutate `config.yaml`. Step 4's root-rewrite algorithm uses this value as the reference instead of `target_context_files[0].skill_root`, so snippets keep their on-disk prefix and the managed section resolves to the real location. Print a one-line hint: "Persist `snippet_skill_root_override: {observed_prefix}` in config.yaml to skip this prompt on future exports." Continue to §2.
+
 ## No-mismatch fast path
 
 **If all observed prefixes match the reference `skill_root` (or no existing snippets were found):** no warning, no gate. Return control to §1b and proceed silently to §2.

package/src/skf-export-skill/references/summary.md

@@ -89,18 +89,18 @@ Your skill is generated from an external dependency for local use.
 
 ### 3. Use It In This Project
 
-Always show this section (regardless of `source_authority`) so the author can install the skill they just forged into the current project and try it immediately:
+Always show this section (regardless of `source_authority`) so the author can install the skill they just forged into the current project and try it immediately.
+
+**Rendering rule for the command below — must be obeyed:** substitute `{resolved_skill_package}` with the actual resolved path before printing (do not leave the placeholder for the user to replace). The substituted path must be either absolute (starts with `/`) or `./`-prefixed. A bare relative path like `skills/foo/1.0.0/foo` is parsed by the `skills` CLI as `https://github.com/skills/foo.git` (org/repo GitHub lookup) and will fail with an authentication error. If `{resolved_skill_package}` resolves to a relative path, prefix it with `./` before emitting.
 
 "### Use It In This Project
 
-To install this skill into the current project right now:
+To install this skill into the current project right now, run:
 
 ```
 npx skills add {resolved_skill_package}
 ```
 
-Replace `{resolved_skill_package}` with the absolute path to the package folder shown above (from step 2), e.g. `{skills_output_folder}/{skill-name}/{version}/{skill-name}/`.
-
 For other source formats (registry name, git URL, tarball, etc.), see the **Installation → Source Formats** section at <https://www.npmjs.com/package/skills>.
 
 If the installed skill's commands are not available in the same IDE session, reload plugins (e.g. for Claude Code users, run `/reload-plugins`) or restart your AI editor. Next time you will see the command `/{skill-name}` (e.g. `/{skill-name}`)."

package/src/skf-export-skill/references/update-context.md

@@ -335,10 +335,10 @@ On success per file, report: "**{target-file} updated successfully.** Verified b
 5. Write the updated manifest atomically via `{manifestOpsHelper}` after all skills in the batch have been applied. For each skill / version pair, invoke:
 
    ```bash
-   python3 {manifestOpsHelper} {skills_output_folder} set {skill-name} {version}
+   python3 {manifestOpsHelper} {skills_output_folder} set {skill-name} {version} --ides {ides_written}
    ```
 
-   The helper handles v2-schema validation, v1→v2 migration, and `platforms`→`ides` rename internally — no in-prompt JSON manipulation needed. Each `set` invocation merges the per-version `ides` and `last_exported` fields into the existing entry. After all skills have been set, re-read the manifest via `{manifestOpsHelper} {skills_output_folder} read` to confirm the final state matches expectations.
+   `{ides_written}` is the comma-joined sorted IDE set computed in step 3. The helper handles v2-schema validation, v1→v2 migration, and `platforms`→`ides` rename internally — no in-prompt JSON manipulation needed. Each `set` invocation unions the supplied `--ides` into the version entry's existing `ides` (deduplicated, sorted) server-side and refreshes `last_exported`. After all skills have been set, re-read the manifest via `{manifestOpsHelper} {skills_output_folder} read` to confirm the final state matches expectations.
 
 **Dry-run mode:** Do NOT update the manifest. Display: "**[DRY RUN] Export manifest would be updated for {skill-name-list} — ides: {ides_written}.**" (list every skill in `skill_batch`)
 

package/src/skf-test-skill/references/coherence-check.md

@@ -4,7 +4,9 @@ outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
 outputFormatsFile: 'assets/output-section-formats.md'
 scoringRulesFile: 'references/scoring-rules.md'
 migrationSectionRules: 'references/migration-section-rules.md'
-scanSkillMdStructureScript: '{project-root}/src/shared/scripts/skf-scan-skill-md-structure.py'
+scanSkillMdStructureProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-scan-skill-md-structure.py'
+  - '{project-root}/src/shared/scripts/skf-scan-skill-md-structure.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -26,11 +28,13 @@ Read `testMode` from `{outputFile}` frontmatter.
 
 Perform the following explicit checks (no hand-waving — most use a single deterministic script; severity assignments are binding; do not relax them).
 
-**2.0 Run the structural scan.** Invoke `{scanSkillMdStructureScript}` twice and parse the JSON outputs. These results back §§2.1, 2.2, 2.3, and 2.6 — do not re-implement those checks with grep/sed/awk loops.
+**Resolve `{scanSkillMdStructureHelper}`** from `{scanSkillMdStructureProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+**2.0 Run the structural scan.** Invoke `{scanSkillMdStructureHelper}` twice and parse the JSON outputs. These results back §§2.1, 2.2, 2.3, and 2.6 — do not re-implement those checks with grep/sed/awk loops.
 
 ```bash
-uv run {scanSkillMdStructureScript} scan {skill-md} --required-sections
-uv run {scanSkillMdStructureScript} scan {skill-md}
+uv run {scanSkillMdStructureHelper} scan {skill-md} --required-sections
+uv run {scanSkillMdStructureHelper} scan {skill-md}
 ```
 
 The first call returns `{ description: {satisfied, matched_synonym, tried[]}, usage: {...}, api_surface: {...} }`. The second returns `{ unbalanced_fences, fence_count, bare_opening_fences[{line,text}], table_drift[{line,section,expected_cols,actual_cols,row}] }`. Hold both JSON blobs for the checks below.
@@ -47,9 +51,12 @@ The script matches case-insensitively and tolerates `##`/`###` heading levels. S
 
 **2.3 Language tags on opening fences.** Read `bare_opening_fences[]` from the second JSON blob. The script already runs the stateful open/close scan — closing fences are never reported. For each entry, emit a **Medium severity** finding: `naive-coherence — opening code fence at line {entry.line} missing language tag`.
 
-**2.4 Exports cross-used in Usage section.** For each function name reported in the step 3 subagent inventory (`exports[].name` where `kind == "function"` or `kind == "method"`):
-- `grep -c "{export.name}" SKILL.md` restricted to the Usage section (find the `## Usage` anchor from §2.1 and the next `^## ` anchor; count within that span).
-- **Zero occurrences → High severity** finding: `naive-coherence — exported {kind} \`{name}\` is not referenced in the Usage section`. This catches the "documented but unused" failure mode that trivially fails discovery testing.
+**2.4 Exports cross-used in a usage-family section.** For each function name reported in the step 3 subagent inventory (`exports[].name` where `kind == "function"` or `kind == "method"`):
+- Determine the usage-family search scope:
+  - **Single-body skill** (no `references/` directory, or `## Full*` sections carry real content): the span from §2.1's `matched_synonym` anchor to the next `^## ` anchor.
+  - **Split-body skill** (a `references/` directory exists alongside SKILL.md AND the SKILL.md `## Full*` sections are stubs/pointers): the union of EVERY usage-family heading present in SKILL.md (`Usage`/`Examples`/`How to use`/`Quickstart`/`Quick Start`/`Getting Started`/`Common Workflows`/`Key API Summary`), each from its anchor to the next `^## ` anchor, PLUS the full text of every file under `references/`.
+- `grep -c "{export.name}"` across that scope and sum the counts.
+- **Zero occurrences across the entire scope → High severity** finding: `naive-coherence — exported {kind} \`{name}\` is not referenced in any usage-family section or reference file`. This catches the "documented but unused" failure mode that trivially fails discovery testing. A method referenced in any usage-family section OR any `references/` file satisfies the check.
 
 **2.5 Async/sync consistency.** For every export with `async` in its description prose (grep for `\basync\b` in the description segment), check the corresponding code example segment for `await` / `async` keywords:
 - Description says async + example shows no `await` → **High severity** finding: `naive-coherence — \`{name}\` described as async but example lacks \`await\``

package/src/skf-verify-stack/references/coverage.md

@@ -2,7 +2,9 @@
 nextStepFile: 'integrations.md'
 coveragePatternsData: '{coveragePatternsPath}'
 feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
-atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 outputFile: '{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md'
 outputFileLatest: '{outputFolderPath}/feasibility-report-{project_slug}-latest.md'
 ---
@@ -107,13 +109,15 @@ Extra and Orphan skills are informational only. They do not affect the coverage
 
 ### 6. Append to Report
 
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 Write the **Coverage Analysis** section to `{outputFile}` (see `{feasibilitySchemaRef}` — section headings are fixed and ordered: `## Executive Summary`, `## Coverage Analysis`, `## Integration Verdicts`, `## Recommendations`, `## Evidence Sources`):
 - Include the full coverage table
 - Include coverage percentage
 - Include missing skill recommendations
 - Include the Extra (unreferenced) and Orphan (source_repo unresolvable) subdivisions from section 4
 - Update frontmatter: append `'coverage'` to `stepsCompleted`; set `coveragePercentage` (integer 0..100)
-- Pipe the updated full content through `python3 {atomicWriteScript} write --target {outputFile}` and again with `--target {outputFileLatest}`
+- Pipe the updated full content through `python3 {atomicWriteHelper} write --target {outputFile}` and again with `--target {outputFileLatest}`
 
 ### 7. Auto-Proceed to Next Step
 

package/src/skf-verify-stack/references/init.md

@@ -1,7 +1,9 @@
 ---
 nextStepFile: 'coverage.md'
 feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
-atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 # {outputFile} and {outputFileLatest} resolve from the activation-stored
 # {project_slug}, {timestamp}, and {outputFolderPath} variables (set in
 # SKILL.md On Activation §2 + §4). The activation-stored values are
@@ -109,6 +111,8 @@ Each helper-emitted entry includes: `skill_name`, `version`, `language`, `confid
 
 ### 4. Create Feasibility Report
 
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 This skill is the PRODUCER of the feasibility report schema defined in `{feasibilitySchemaRef}`. All outputs MUST conform to that schema — in particular: `schemaVersion: "1.0"`, the defined verdict token set (`Verified|Plausible|Risky|Blocked`; overall `FEASIBLE|CONDITIONALLY_FEASIBLE|NOT_FEASIBLE`), the filename pattern, and the section-heading order.
 
 **Filename variables** (already computed at activation — do not re-derive):
@@ -137,7 +141,7 @@ This skill is the PRODUCER of the feasibility report schema defined in `{feasibi
 - `skillsAnalyzed: {count}`
 - `stepsCompleted: ['init']`
 
-**Atomic write:** Pipe the staged content through `python3 {atomicWriteScript} write --target {outputFile}` and then again with `--target {outputFileLatest}`. Both writes use the same staged content. Do NOT use `rm`+rewrite; do NOT create a symlink for the `-latest` copy.
+**Atomic write:** Pipe the staged content through `python3 {atomicWriteHelper} write --target {outputFile}` and then again with `--target {outputFileLatest}`. Both writes use the same staged content. Do NOT use `rm`+rewrite; do NOT create a symlink for the `-latest` copy.
 
 On any non-zero exit from either write: HALT (exit code 4, `halt_reason: "write-failed"`) and emit the error envelope per SKILL.md "Result Contract (Headless)" with `report_path: null`, `report_latest_path: null`, `overall_verdict: null`.
 

package/src/skf-verify-stack/references/integrations.md

@@ -3,7 +3,9 @@ nextStepFile: 'requirements.md'
 integrationRulesData: '{integrationRulesPath}'
 coveragePatternsData: '{coveragePatternsPath}'
 feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
-atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 outputFile: '{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md'
 outputFileLatest: '{outputFolderPath}/feasibility-report-{project_slug}-latest.md'
 ---
@@ -160,12 +162,14 @@ For each integration pair `{library_a, library_b}`, apply the verification proto
 
 ### 6. Append to Report
 
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 Write the **Integration Verdicts** section to `{outputFile}` (heading is fixed — consumers grep for `## Integration Verdicts`; the table header MUST be the canonical `| lib_a | lib_b | verdict | rationale |` per `{feasibilitySchemaRef}`; the skill-local display table with the extra Context/Source/Evidence columns can be rendered beneath it for human readers):
 - Emit the canonical `| lib_a | lib_b | verdict | rationale |` table first (verdict tokens MUST be one of `Verified`, `Plausible`, `Risky`, `Blocked` — case-sensitive)
 - Include the extended table with Context, Source, and Evidence columns below it
 - Include recommendations for Risky and Blocked pairs (Blocked recommendations MUST cite a named candidate per step 5 H6, or the explicit no-candidate notice)
 - Update frontmatter: append `'integrations'` to `stepsCompleted`; set `pairsVerified`, `pairsPlausible`, `pairsRisky`, `pairsBlocked` counts
-- Pipe the updated full content through `python3 {atomicWriteScript} write --target {outputFile}` and again with `--target {outputFileLatest}`
+- Pipe the updated full content through `python3 {atomicWriteHelper} write --target {outputFile}` and again with `--target {outputFileLatest}`
 
 ### 7. Auto-Proceed to Next Step
 

package/src/skf-verify-stack/references/report.md

@@ -6,7 +6,9 @@
 outputFile: '{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md'
 outputFileLatest: '{outputFolderPath}/feasibility-report-{project_slug}-latest.md'
 feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
-atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 nextStepFile: 'health-check.md'
 ---
 
@@ -98,9 +100,11 @@ Based on the overall verdict, present the appropriate recommendation:
 
 ### 4b. Result Contract
 
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{forge_data_folder}/verify-stack-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_data_folder}/verify-stack-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include the feasibility report path (both `{outputFile}` and `{outputFileLatest}`) in `outputs`; include `overallVerdict` (`FEASIBLE` / `CONDITIONALLY_FEASIBLE` / `NOT_FEASIBLE`), `coveragePercentage`, and `recommendationCount` in `summary` — use the case-sensitive schema tokens.
 
-Write both JSON files through `python3 {atomicWriteScript} write --target ...` to avoid partial-write corruption. On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`) and emit the error envelope.
+Write both JSON files through `python3 {atomicWriteHelper} write --target ...` to avoid partial-write corruption. On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`) and emit the error envelope.
 
 When `{headless_mode}` is true, also emit the single-line envelope on **stdout** before chaining to step 7 (matches the SKILL.md "Result Contract (Headless)" shape):
 

package/src/skf-verify-stack/references/requirements.md

@@ -1,7 +1,9 @@
 ---
 nextStepFile: 'synthesize.md'
 feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
-atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 outputFile: '{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md'
 outputFileLatest: '{outputFolderPath}/feasibility-report-{project_slug}-latest.md'
 ---
@@ -24,6 +26,8 @@ If a PRD or vision document was provided in Step 01, verify that the combined ca
 
 ### 1. Check PRD Availability
 
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 **Read `prdAvailable` from `{outputFile}` frontmatter (set in Step 01). If `prdAvailable` is false (no PRD/vision document was provided):**
 
 "**Pass 3: Requirements Coverage — Skipped**
@@ -34,7 +38,7 @@ To include this pass, re-run **[VS]** with a PRD or vision document path.
 
 **Proceeding to synthesis...**"
 
-Update `{outputFile}` frontmatter: append `'requirements'` to `stepsCompleted`; set `requirementsPass: "skipped"`. Pipe the updated content through `python3 {atomicWriteScript} write --target {outputFile}` and again with `--target {outputFileLatest}`.
+Update `{outputFile}` frontmatter: append `'requirements'` to `stepsCompleted`; set `requirementsPass: "skipped"`. Pipe the updated content through `python3 {atomicWriteHelper} write --target {outputFile}` and again with `--target {outputFileLatest}`.
 
 Load, read the full file and then execute `{nextStepFile}`. **STOP HERE — do not execute sections 2-6.**
 
@@ -105,7 +109,7 @@ Write the Requirements Coverage content under the `## Recommendations` section (
 - Update frontmatter: append `'requirements'` to `stepsCompleted`
 - Set `requirementsPass: "completed"`
 - Set `requirementsFulfilled`, `requirementsPartial`, `requirementsNotAddressed` counts
-- Pipe the updated full content through `python3 {atomicWriteScript} write --target {outputFile}` and again with `--target {outputFileLatest}`
+- Pipe the updated full content through `python3 {atomicWriteHelper} write --target {outputFile}` and again with `--target {outputFileLatest}`
 
 ### 6. Auto-Proceed to Next Step
 

package/src/skf-verify-stack/references/synthesize.md

@@ -1,7 +1,9 @@
 ---
 nextStepFile: 'report.md'
 feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
-atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 outputFile: '{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md'
 outputFileLatest: '{outputFolderPath}/feasibility-report-{project_slug}-latest.md'
 ---
@@ -121,6 +123,8 @@ Assemble the following for the report:
 
 ### 5. Append to Report
 
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 Write the **Recommendations** and **Evidence Sources** sections to `{outputFile}` (per the fixed heading order in `{feasibilitySchemaRef}`):
 - Include overall verdict with rationale in the `## Executive Summary` section (replace the placeholder text from the template)
 - Include prioritized recommendation list under `## Recommendations`
@@ -137,7 +141,7 @@ Write the **Recommendations** and **Evidence Sources** sections to `{outputFile}
   - If any pair has Check 4 missing/weak AND was capped at `Plausible`, that alone does NOT force `NOT_FEASIBLE`, but `FEASIBLE` requires zero such pairs
   - `FEASIBLE` requires 100% coverage AND zero Blocked pairs AND zero Check-4-missing pairs — otherwise downgrade to `CONDITIONALLY_FEASIBLE`
   - `coveragePercentage == 0` forces `NOT_FEASIBLE` (per section 1 short-circuit)
-- Pipe the updated full content through `python3 {atomicWriteScript} write --target {outputFile}` and again with `--target {outputFileLatest}`
+- Pipe the updated full content through `python3 {atomicWriteHelper} write --target {outputFile}` and again with `--target {outputFileLatest}`
 
 ### 6. Auto-Proceed to Next Step