bmad-module-skill-forge 1.5.0 → 1.6.0

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.6.0",
       "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.6.0"
 
 # 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.6.0",
   "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-description-guard.py

@@ -160,17 +160,45 @@ def is_diverged(diff_kind: str) -> bool:
 def restore_description(skill_md: Path, captured: str) -> None:
     """Atomically rewrite SKILL.md so its frontmatter `description` equals captured.
 
-    Preserves frontmatter key order and surrounding whitespace by doing a
-    line-level rewrite of just the `description:` value, not a full YAML
-    re-dump (which would re-order keys, change quoting style, and likely
-    fail roundtrip tests downstream).
+    Parses the entire frontmatter via PyYAML, replaces the top-level
+    `description` value, and re-emits the frontmatter via `yaml.safe_dump`.
+    This guarantees valid YAML output regardless of the source representation
+    (inline, double-quoted, single-quoted, folded `>`, literal `|`), and
+    avoids the line-level pitfalls a previous implementation had with folded
+    block scalars and nested `description:` keys in sibling mappings.
+
+    Key order is preserved (PyYAML's `safe_dump` honours dict insertion order;
+    this module's `requires-python = ">=3.10"` guarantees ordered dicts).
+    Quoting style of *other* fields may change to whatever `safe_dump`
+    chooses for each scalar — downstream readers parse YAML, so any valid
+    YAML emission is acceptable.
     """
     text = skill_md.read_text(encoding="utf-8")
     leading, fm_yaml, body = _split_frontmatter(text)
     if not fm_yaml:
         raise ValueError(f"cannot restore: no frontmatter in {skill_md}")
 
-    new_fm = _rewrite_description_line(fm_yaml, captured)
+    try:
+        fm = yaml.safe_load(fm_yaml)
+    except yaml.YAMLError as exc:
+        raise ValueError(f"frontmatter in {skill_md} is not valid YAML: {exc}") from exc
+    if not isinstance(fm, dict):
+        raise ValueError(f"frontmatter in {skill_md} is not a mapping")
+    if "description" not in fm:
+        raise ValueError(f"frontmatter in {skill_md} has no `description` field")
+
+    fm["description"] = captured
+
+    # `width=10**9` keeps the description on one line regardless of length;
+    # PyYAML otherwise inserts line breaks at ~80 chars which would re-introduce
+    # folded-scalar continuation lines — the exact failure mode this rewrite fixes.
+    new_fm = yaml.safe_dump(
+        fm,
+        sort_keys=False,
+        default_flow_style=False,
+        allow_unicode=True,
+        width=10**9,
+    ).rstrip("\n")
     new_text = f"{leading}{new_fm}\n---\n{body}"
 
     # atomic: write to a sibling temp file, fsync, rename
@@ -191,81 +219,6 @@ def restore_description(skill_md: Path, captured: str) -> None:
         raise
 
 
-def _rewrite_description_line(fm_yaml: str, new_description: str) -> str:
-    """Replace the `description:` value in a YAML frontmatter block.
-
-    Preserves other keys verbatim. Handles three common shapes:
-      description: single-line value
-      description: "double-quoted value"
-      description: |     # block scalar (folded variant: >)
-        multi-line
-        value here
-    """
-    lines = fm_yaml.split("\n")
-    out: list[str] = []
-    i = 0
-    quoted = _yaml_quote_inline(new_description)
-    replaced = False
-    while i < len(lines):
-        line = lines[i]
-        if not replaced and _is_description_key_line(line):
-            stripped = line.lstrip()
-            indent = line[: len(line) - len(stripped)]
-            # detect block-scalar indicator (| or >)
-            after_key = stripped[len("description:") :].lstrip()
-            if after_key.startswith("|") or after_key.startswith(">"):
-                # skip block-scalar continuation lines (deeper indent than the key line)
-                key_indent = len(indent)
-                i += 1
-                while i < len(lines):
-                    nxt = lines[i]
-                    if nxt.strip() == "":
-                        # blank lines belong to the block scalar
-                        i += 1
-                        continue
-                    nxt_indent = len(nxt) - len(nxt.lstrip())
-                    if nxt_indent <= key_indent:
-                        break
-                    i += 1
-                out.append(f"{indent}description: {quoted}")
-                replaced = True
-                continue
-            out.append(f"{indent}description: {quoted}")
-            replaced = True
-            i += 1
-            continue
-        out.append(line)
-        i += 1
-    if not replaced:
-        raise ValueError("description key not found while rewriting frontmatter")
-    return "\n".join(out)
-
-
-def _is_description_key_line(line: str) -> bool:
-    stripped = line.lstrip()
-    return stripped.startswith("description:") and (
-        len(stripped) == len("description:") or stripped[len("description:")] in (" ", "\t", "")
-    )
-
-
-def _yaml_quote_inline(value: str) -> str:
-    """Emit a YAML scalar suitable as the inline value of `description: `.
-
-    Uses double-quoted form so control characters and embedded quotes are
-    safe. Block scalars (| / >) are not used — the description field is a
-    single semantic string and downstream readers (skill-check, agentskills)
-    expect inline form.
-    """
-    escaped = (
-        value.replace("\\", "\\\\")
-        .replace("\"", "\\\"")
-        .replace("\n", "\\n")
-        .replace("\r", "\\r")
-        .replace("\t", "\\t")
-    )
-    return f'"{escaped}"'
-
-
 # --------------------------------------------------------------------------
 # CLI
 # --------------------------------------------------------------------------

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/continue.md

@@ -6,6 +6,7 @@ nextStepOptions:
   step 4: 'map-and-detect.md'
   step 5: 'recommend.md'
   step 6: 'generate-briefs.md'
+  step 7: 'health-check.md'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -61,8 +62,9 @@ Map the last completed step to the next step file:
 | identify-units | map-and-detect |
 | map-and-detect | recommend |
 | recommend | generate-briefs |
+| generate-briefs | health-check |
 
-**IF all steps completed:**
+**IF `health-check` is in `stepsCompleted`:**
 "**This analysis appears to be complete.** All steps have been finished. Would you like to start a new analysis?"
 
 ### 5. Update and Route

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

@@ -13,6 +13,8 @@ A good skill brief sets a tight, cohesive boundary: one capability with 3-8 prim
 
 Brief-skill is split from create-skill so the scoping conversation runs *once*, on cheap signals (manifests, top-level exports, intent), without paying for AST extraction. Compilation is expensive; scoping decisions are cheap to revise. Keeping them in separate workflows lets a user iterate on the brief, share it for review, and re-run create-skill against the same brief whenever the upstream version moves.
 
+**Ratify path (interactive only).** When the user already has a `skill-brief.yaml` produced by another workflow — typically `skf-analyze-source`'s `generate-briefs` step, where one analyze pass emits several recommended briefs — invoking `/skf-brief-skill` with a path to that brief at the first prompt routes to a fast-path review: gather-intent §3.1a loads the YAML, hydrates the brief context, and jumps straight to step 4 (confirm-brief) where the standard review/edit cycle still applies before step 5 writes. This skips re-deriving fields the upstream draft already supplies and saves the 5-10 minutes a full re-run of intent + analyze + scope would cost.
+
 ## Conventions
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
@@ -30,7 +32,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).