bmad-module-skill-forge 1.8.0 → 1.9.0

package/src/shared/scripts/skf-validate-pins.py

@@ -0,0 +1,368 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""SKF Validate Pins — resolve and validate version pins for a GitHub repository.
+
+Shared pin validation script consumed by skf-analyze-source (AN auto-scope,
+deepwiki --pin) and campaign workflows.  Validates that a user-supplied --pin
+resolves to an existing tag or branch, or auto-resolves the latest release tag
+when no --pin is provided.
+
+Tag matching priority mirrors source-resolution-protocols.md:
+
+  1. Exact match:   {pin}
+  2. v-prefixed:    v{pin}
+  3. Package scope: {name}@{pin}, @{scope}/{name}@{pin}
+  4. Crate prefix:  {name}/v{pin}, {name}/{pin}, {name}-v{pin}
+
+CLI:
+  uv run python src/shared/scripts/skf-validate-pins.py \\
+      --repo-url <url> [--pin <version>] [--format tag|branch|any]
+
+Input:
+  --repo-url   GitHub repository URL (required)
+  --pin        Version pin to validate (optional — resolves latest release when absent)
+  --format     Restrict matching to tag, branch, or any (optional, default: any)
+
+Output (JSON on stdout):
+  {
+    "status":       "valid" | "invalid" | "resolved",
+    "pin":          "<input_pin_or_null>",
+    "resolved_ref": "<matched_tag_or_branch>",
+    "ref_type":     "tag" | "branch",
+    "version":      "<semver_or_null>",
+    "suggestions":  ["<nearest_tags_on_invalid>"]
+  }
+
+Exit codes:
+  0  valid/resolved (pin matches a tag or branch, or latest release resolved)
+  1  invalid (no match found for the supplied pin, or no releases for auto-resolve)
+  2  error (invalid args, gh not found, network error, etc.)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+_GITHUB_URL_RE = re.compile(
+    r"https?://(?:www\.)?github\.com/([^/\s]+)/([^/\s.]+?)(?:\.git)?/?$",
+    re.IGNORECASE,
+)
+
+_SEMVER_RE = re.compile(
+    r"^v?(\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?(?:\+[a-zA-Z0-9.]+)?)$"
+)
+
+
+# ---------------------------------------------------------------------------
+# gh CLI helpers
+# ---------------------------------------------------------------------------
+
+def _run_gh(args: List[str]) -> Optional[str]:
+    try:
+        result = subprocess.run(
+            ["gh"] + args,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+        return None
+    except FileNotFoundError:
+        return None
+
+
+def _check_gh_available() -> bool:
+    try:
+        subprocess.run(
+            ["gh", "--version"],
+            capture_output=True,
+            text=True,
+        )
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def _run_git(args: List[str]) -> Optional[str]:
+    try:
+        result = subprocess.run(
+            ["git"] + args,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+        return None
+    except FileNotFoundError:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Version extraction
+# ---------------------------------------------------------------------------
+
+def extract_version(tag: str) -> Optional[str]:
+    m = _SEMVER_RE.match(tag)
+    if m:
+        return m.group(1)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Tag listing
+# ---------------------------------------------------------------------------
+
+def list_tags(owner: str, repo: str, repo_url: str) -> List[str]:
+    raw = _run_gh([
+        "api", f"repos/{owner}/{repo}/tags",
+        "--paginate", "--jq", ".[].name",
+    ])
+    if raw:
+        return [t for t in raw.splitlines() if t.strip()]
+
+    raw = _run_git(["ls-remote", "--tags", repo_url])
+    if raw:
+        tags = []
+        for line in raw.splitlines():
+            parts = line.split("refs/tags/")
+            if len(parts) == 2:
+                tag = parts[1].strip()
+                if not tag.endswith("^{}"):
+                    tags.append(tag)
+        return tags
+
+    return []
+
+
+# ---------------------------------------------------------------------------
+# Branch verification
+# ---------------------------------------------------------------------------
+
+def check_branch_exists(repo_url: str, branch: str) -> bool:
+    raw = _run_git(["ls-remote", "--heads", repo_url, branch])
+    if raw and branch in raw:
+        return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Tag matching (mirrors source-resolution-protocols.md)
+# ---------------------------------------------------------------------------
+
+def _derive_name_from_url(owner: str, repo: str) -> str:
+    return repo.lower()
+
+
+def match_tag(pin: str, tags: List[str], owner: str, repo: str) -> Optional[str]:
+    name = _derive_name_from_url(owner, repo)
+
+    candidates = [
+        pin,
+        f"v{pin}",
+        f"{name}@{pin}",
+        f"{name}/v{pin}",
+        f"{name}/{pin}",
+        f"{name}-v{pin}",
+    ]
+
+    for candidate in candidates:
+        if candidate in tags:
+            return candidate
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Suggestion generation
+# ---------------------------------------------------------------------------
+
+def _semver_sort_key(tag: str) -> Tuple:
+    v = extract_version(tag)
+    if v is None:
+        return (0, 0, 0, tag)
+    parts = v.split("-")[0].split(".")
+    try:
+        return tuple(int(p) for p in parts[:3])
+    except ValueError:
+        return (0, 0, 0, tag)
+
+
+def generate_suggestions(pin: str, tags: List[str], max_count: int = 5) -> List[str]:
+    if not tags:
+        return []
+
+    prefixes_to_try = []
+    if "." in pin:
+        prefixes_to_try.append(pin.rsplit(".", 1)[0] + ".")
+        prefixes_to_try.append(pin.split(".")[0])
+    prefixes_to_try.append(pin)
+
+    for prefix in prefixes_to_try:
+        prefix_matches = [t for t in tags if t.startswith(prefix)]
+        if prefix_matches:
+            sorted_matches = sorted(prefix_matches, key=_semver_sort_key, reverse=True)
+            return sorted_matches[:max_count]
+
+    sorted_tags = sorted(tags, key=_semver_sort_key, reverse=True)
+    return sorted_tags[:max_count]
+
+
+# ---------------------------------------------------------------------------
+# Latest release resolution
+# ---------------------------------------------------------------------------
+
+def resolve_latest_release(owner: str, repo: str) -> Optional[str]:
+    raw = _run_gh([
+        "api", f"repos/{owner}/{repo}/releases/latest",
+        "--jq", ".tag_name",
+    ])
+    if raw and raw != "null":
+        return raw.strip()
+
+    raw = _run_gh([
+        "api", f"repos/{owner}/{repo}/tags",
+        "--jq", ".[0].name",
+    ])
+    if raw and raw != "null":
+        return raw.strip()
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Core validation logic
+# ---------------------------------------------------------------------------
+
+def validate_pin(
+    repo_url: str,
+    pin: Optional[str] = None,
+    format_filter: str = "any",
+) -> Dict[str, Any]:
+    m = _GITHUB_URL_RE.match(repo_url.strip())
+    if not m:
+        return {
+            "status": "invalid",
+            "pin": pin,
+            "resolved_ref": None,
+            "ref_type": None,
+            "version": None,
+            "suggestions": [],
+        }
+
+    owner, repo = m.group(1), m.group(2)
+
+    if pin is None:
+        tag = resolve_latest_release(owner, repo)
+        if tag is None:
+            return {
+                "status": "invalid",
+                "pin": None,
+                "resolved_ref": None,
+                "ref_type": None,
+                "version": None,
+                "suggestions": [],
+            }
+        return {
+            "status": "resolved",
+            "pin": None,
+            "resolved_ref": tag,
+            "ref_type": "tag",
+            "version": extract_version(tag),
+            "suggestions": [],
+        }
+
+    tags: List[str] = []
+    if format_filter in ("tag", "any"):
+        tags = list_tags(owner, repo, repo_url)
+        matched = match_tag(pin, tags, owner, repo)
+        if matched:
+            return {
+                "status": "valid",
+                "pin": pin,
+                "resolved_ref": matched,
+                "ref_type": "tag",
+                "version": extract_version(matched),
+                "suggestions": [],
+            }
+
+    if format_filter in ("branch", "any"):
+        if check_branch_exists(repo_url, pin):
+            return {
+                "status": "valid",
+                "pin": pin,
+                "resolved_ref": pin,
+                "ref_type": "branch",
+                "version": None,
+                "suggestions": [],
+            }
+
+    if not tags:
+        tags = list_tags(owner, repo, repo_url)
+    suggestions = generate_suggestions(pin, tags)
+
+    return {
+        "status": "invalid",
+        "pin": pin,
+        "resolved_ref": None,
+        "ref_type": None,
+        "version": None,
+        "suggestions": suggestions,
+    }
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate and resolve version pins for a GitHub repository.",
+    )
+    parser.add_argument("--repo-url", required=True, help="GitHub repository URL")
+    parser.add_argument("--pin", default=None, help="Version pin to validate")
+    parser.add_argument(
+        "--format",
+        choices=["tag", "branch", "any"],
+        default="any",
+        help="Restrict matching to tag, branch, or any (default: any)",
+    )
+    args = parser.parse_args()
+
+    if not _check_gh_available():
+        json.dump({"error": "gh CLI not found", "code": "GH_NOT_FOUND"}, sys.stderr)
+        sys.stderr.write("\n")
+        return 2
+
+    m = _GITHUB_URL_RE.match(args.repo_url.strip())
+    if not m:
+        json.dump(
+            {"error": f"Not a GitHub URL: {args.repo_url}", "code": "INVALID_URL"},
+            sys.stderr,
+        )
+        sys.stderr.write("\n")
+        return 2
+
+    try:
+        result = validate_pin(args.repo_url, args.pin, args.format)
+    except Exception as exc:
+        json.dump({"error": str(exc), "code": "VALIDATION_ERROR"}, sys.stderr)
+        sys.stderr.write("\n")
+        return 2
+
+    json.dump(result, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+
+    if result["status"] == "invalid":
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-analyze-source/SKILL.md

@@ -31,26 +31,32 @@ These rules apply to every step in this workflow:
 
 ## Stages
 
-| # | Step | File | Auto-proceed |
-|---|------|------|--------------|
-| 1 | Initialize | references/init.md | Yes |
-| 1b | Continue (session resume) | references/continue.md | Yes |
-| 2 | Scan Project | references/scan-project.md | No (confirm) |
-| 3 | Identify Units | references/identify-units.md | No (confirm) |
-| 4 | Map & Detect | references/map-and-detect.md | Yes |
-| 5 | Recommend | references/recommend.md | No (confirm) |
-| 6 | Generate Briefs | references/generate-briefs.md | Yes |
-| 7 | Workflow Health Check | references/health-check.md | Yes |
+| # | Step | File | Auto-proceed | Condition |
+|---|------|------|--------------|-----------|
+| 1 | Initialize | references/init.md | Yes | Always |
+| 1a | Auto-Scope | references/step-auto-scope.md | Yes | `[auto]` mode only. Includes §0b pin resolution — validates and resolves version pin before scoping. Includes §0c coexistence detection — checks for existing skills before proceeding. Includes §0 docs-only URL detection — doc URLs short-circuit auto-scope entirely |
+| 1b | Continue (session resume) | references/continue.md | Yes | Always |
+| 2 | Scan Project | references/scan-project.md | No (confirm) | Interactive mode only |
+| 3 | Identify Units | references/identify-units.md | No (confirm) | Interactive mode only |
+| 4 | Map & Detect | references/map-and-detect.md | Yes | Interactive mode only |
+| 5 | Recommend | references/recommend.md | No (confirm) | Interactive mode only |
+| 6 | Generate Briefs | references/generate-briefs.md | Yes | Interactive mode only |
+| 7 | Workflow Health Check | references/health-check.md | Yes | Always |
+
+**Auto mode path:** When `[auto]` flag is present, init (step 1) routes directly to step 1a, which performs manifest scan → shape detection → scope generation → brief write → health check, bypassing steps 2–6. After URL type detection (§0), pin resolution (§0b) validates the `--pin` argument (or resolves the latest release tag) and stores the resolved ref for downstream brief writes. Coexistence detection (§0c) then checks for existing skills matching the target. If found, the user chooses alongside/merge/skip. Headless mode auto-selects alongside. Auto-scope may produce N > 1 confirmed units when decomposition thresholds are met (`export_count > 500` `[PENDING VALIDATION]` or `package_count > 3` `[PENDING VALIDATION]`), resulting in N briefs and N `brief_paths` in the envelope. When the target is a documentation URL (not a GitHub repo or local path), auto-scope detects the docs-only input at §0, validates URL reachability, writes a docs-only brief, and emits the envelope without performing source analysis.
+
+**Shape detection reference:** `references/step-shape-detect.md` — loaded by step 1a as a reference doc (not a chained step).
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | project_path [required], scope_hint [optional] |
-| **Headless inputs** | `--project-path <path>` (skip Step 1 project-path prompt), `--scope-hint <text>` (skip Step 1 scope-hint prompt), `--intent-hint <text>` (pre-supply analysis intent; drives recommendation ranking in Step 5) |
+| **Inputs** | project_path [required], scope_hint [optional]. `project_path` can be a GitHub repo URL, a local filesystem path, or a documentation URL for docs-only mode. The URL type heuristic at §0 determines the mode. |
+| **Headless inputs** | `--project-path <path>` (skip Step 1 project-path prompt; accepts documentation URLs for docs-only mode), `--scope-hint <text>` (skip Step 1 scope-hint prompt), `--intent-hint <text>` (pre-supply analysis intent; drives recommendation ranking in Step 5), `--pin <version>` (pin to a specific version tag or branch; accepts semver tags, git tags, and branch names; when absent, resolves to the latest release tag) |
 | **Headless flag** | `--headless` / `-H` flips every confirm gate to auto-proceed |
-| **Gates** | step 2: Confirm Gate [C] | step 3: Confirm Gate [C] | step 5: Confirm Gate [C] |
-| **Outputs** | analysis-report.md, skill-brief.yaml files (one per recommended unit); final `SKF_ANALYZE_RESULT_JSON` line on stdout when `{headless_mode}` is true |
+| **Auto flag** | `[auto]` bracket modifier — activates auto-scope mode (step 1a). Pipelines pass this as `AN[auto]`. When active, init routes to `step-auto-scope.md` which performs shape detection → scope generation → brief write, bypassing interactive steps 2–6. Requires `--project-path`. |
+| **Gates** | step 2: Confirm Gate [C] | step 3: Confirm Gate [C] | step 5: Confirm Gate [C] (all skipped in auto mode) |
+| **Outputs** | analysis-report.md, skill-brief.yaml files (one per recommended unit); final `SKF_ANALYZE_RESULT_JSON` line on stdout when `{headless_mode}` is true. In auto mode, the envelope includes `"mode":"auto"`. |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
 | **Exit codes** | See "Exit Codes" below |
 
@@ -60,21 +66,21 @@ Every HARD HALT in this workflow exits with a stable code so headless automators
 
 | Code | Meaning              | Raised by                                                                                  |
 | ---- | -------------------- | ------------------------------------------------------------------------------------------ |
-| 0    | success              | step 7 (terminal — health check completion)                                               |
-| 2    | input-missing        | step 1 §2-3 — required config absent (config.yaml not loadable, project path empty/invalid in headless mode) |
-| 3    | resolution-failure   | step 1 §2 (`forge-tier.yaml` missing at `{sidecar_path}/forge-tier.yaml`); step 1 §3 (project path does not exist or remote URL inaccessible) |
+| 0    | success / skipped / redirect | step 7 (terminal — health check completion); also covers coexistence `"skipped"` and `"redirect"` statuses from §0c |
+| 2    | input-missing        | step 1 §2-3 — required config absent (config.yaml not loadable, project path empty/invalid in headless mode); step 1 §2b — auto mode without `--project-path` |
+| 3    | resolution-failure   | step 1 §2 (`forge-tier.yaml` missing at `{sidecar_path}/forge-tier.yaml`); step 1 §3 (project path does not exist or remote URL inaccessible); step 1a §0a (docs-only URL unreachable); step 1a §0b (pin validation failure — `halt_reason: "pin-invalid"` when the supplied `--pin` does not match any tag or branch); step 1a §3 (shape detection script error, exit code 2) |
 | 4    | write-failure        | step 1 §6 (analysis report write failed); step 6 §5 (skill-brief.yaml write failed); step 6 §9 (result contract write failed) |
 | 6    | user-cancelled       | any interactive menu in steps 2/3/5/6 (user selected `[X]` Cancel and exit)               |
 
 ## Result Contract (Headless)
 
-When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+When `{headless_mode}` is true, step 6 (interactive) or step 1a (auto) emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
 
 ```
-SKF_ANALYZE_RESULT_JSON: {"status":"success|error","report_path":"…|null","brief_paths":["…"],"unit_counts":{"confirmed":N,"skipped":N,"maybe":N},"exit_code":0,"halt_reason":null}
+SKF_ANALYZE_RESULT_JSON: {"status":"success|error","report_path":"…|null","brief_paths":["…"],"unit_counts":{"confirmed":N,"skipped":N,"maybe":N},"exit_code":0,"halt_reason":null,"mode":"interactive|auto"}
 ```
 
-`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"forge-tier-missing"`, `"path-invalid"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above. `brief_paths` is an array of absolute paths to every generated `skill-brief.yaml` (empty array if none were generated). `unit_counts` reports confirmed/skipped/maybe counts from step 5's user decisions.
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT, `"redirect"` when coexistence detection routes to US (merge), or `"skipped"` when the user skips a conflicting target. `halt_reason` is one of: `null` (success), `"input-missing"`, `"forge-tier-missing"`, `"path-invalid"`, `"pin-invalid"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above. `brief_paths` is an array of absolute paths to every generated `skill-brief.yaml` (empty array if none were generated). `unit_counts` reports confirmed/skipped/maybe counts from step 5's user decisions. `mode` is `"auto"` when the `[auto]` flag was active, `"interactive"` otherwise (omitting `mode` is equivalent to `"interactive"` for backward compatibility). The `coexistence` field (present when §0c triggers) is `"alongside"`, `"merge"`, or `"skip"`, indicating the user's coexistence decision. The `pinned_ref` and `pinned_version` fields (present when §0b resolves a pin) record the resolved git ref and extracted semver version for provenance tracking.
 
 ## On Activation
 

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

@@ -46,6 +46,36 @@ Look for {outputFile}.
 
 "**Forge tier detected:** {tier} — analysis depth will be calibrated accordingly."
 
+### 2b. Auto Mode Check
+
+**Check for `[auto]` flag:** If `[auto]` was passed as a bracket modifier in the pipeline context (e.g., `AN[auto]`), set `{auto_mode}` = true.
+
+**IF `{auto_mode}` is true:**
+
+1. **Resolve project path:** If `project_paths[]` is already populated (from §1 continuation detection or `--project-path` arg), use it. Otherwise, if `--project-path <path>` was passed at invocation, set `project_paths[]` from it (comma-split if multiple). If neither is available, HARD HALT with exit code 2 (`input-missing`): "**Auto mode requires `--project-path` — no project path available.**"
+2. **Validate the path(s):** For each provided path/URL, check that it exists (local) or is accessible (remote). If any invalid: HARD HALT with exit code 3 (`resolution-failure`): "**Path `{path}` doesn't appear to be valid.**"
+3. **Create the analysis report** from {templateFile}. Populate frontmatter:
+   ```yaml
+   stepsCompleted: ['init']
+   lastStep: 'init'
+   lastContinued: ''
+   date: '{current_date}'
+   user_name: '{user_name}'
+   project_name: '{project_name}'
+   project_paths: ['{provided_project_path}']
+   forge_tier: '{detected_tier}'
+   existing_skills: []
+   confirmed_units: []
+   stack_skill_candidates: []
+   nextWorkflow: ''
+   mode: 'auto'
+   ```
+4. "**Auto mode activated — bypassing interactive analysis.**"
+5. **Route to auto-scope:** Load, read fully, then execute `references/step-auto-scope.md`. **STOP HERE** — do not continue to §3 or any subsequent section.
+
+**IF `{auto_mode}` is NOT true:**
+Continue to §3 as normal — the entire interactive flow below is unchanged.
+
 ### 3. Collect Project Path
 
 **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.