bmad-module-skill-forge 1.7.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/assets/skill-brief-schema.md

@@ -27,7 +27,8 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | `scripts_intent`   | string | `detect` / `none` / free-text                    | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
 | `assets_intent`    | string | `detect` / `none` / free-text                    | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/").        |
 | `target_version`   | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | User-specified target version. When present, overrides auto-detection and becomes the skill's version. Recommended for docs-only skills where auto-detection is unavailable.                                                   |
-| `target_ref`       | string | Git ref (tag or branch)                          | Optional. Explicit git ref used verbatim as the resolved `source_ref`, bypassing version-to-tag matching. Escape hatch for monorepo crate tags whose prefix differs from the skill name (e.g. tag `livekit/v0.7.42` for skill `livekit-rust`). Remote sources only. |
+| `target_ref`       | string | Git ref (tag or branch)                          | Optional. Explicit git ref used verbatim as the resolved `source_ref`, bypassing version-to-tag matching. Escape hatch for monorepo crate tags whose prefix differs from the skill name (e.g. tag `livekit/v0.7.42` for skill `livekit-rust`). Remote sources only. Mutually exclusive with `constituent_refs`. |
+| `constituent_refs` | object | map of path→ref strings                          | Optional. Per-constituent git ref overrides for composite (multi-repo or multi-ref) sources. Keys must match entries in the analyze-source `project_paths` array. When absent, a single `target_ref` (or auto-detected ref) applies to all paths. Mutually exclusive with `target_ref`. |
 | `source_authority` | string | `official` / `community` / `internal`            | Default `community`. Set to `official` only when the skill creator is the library maintainer. Forced to `community` when `source_type: "docs-only"`.                                                                           |
 | `source_ref`       | string | Git ref (tag/branch/HEAD)                        | Resolved git ref used for source access. Set automatically during tag resolution — do not set manually.                                                                                                                        |
 

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

@@ -48,6 +48,7 @@ For EACH detected boundary from the scan:
 - Package Boundary — workspace member or independently versioned
 - Module Boundary — logical grouping within a package
 - Library Boundary — third-party with significant project-specific usage
+- Composite Boundary — ≥2 boundaries that only deliver value together (detected in §3b below; not assigned during initial per-boundary classification)
 
 **Step C — Assign scope type:**
 - `full-library` — entire codebase of the unit
@@ -105,9 +106,28 @@ For disqualified candidates, note reason:
 |------|--------|
 | {path} | {disqualification reason} |
 
+### 3b. Detect Composite Unit Merges
+
+After building the classification table, apply the Composite Boundary detection heuristic from {heuristicsFile} against the qualifying units:
+
+1. **Scan for merge candidates:** Among the qualifying units (from `kept[]`), find groups of ≥2 Package or Module boundaries that meet EITHER trigger:
+   - **Mutual hard dependency:** Every constituent imports from at least one other constituent in the group, AND no constituent's public API is self-contained
+   - **Shared integration surface:** Constituents share types/traits defined in one constituent but consumed by all others, AND the consuming constituents have no independent barrel
+
+2. **If candidate groups are found**, propose each merge:
+   - Derive a composite name from the common namespace prefix or repo name
+   - List the constituents (boundary names and paths being merged)
+   - State the triggering heuristic and evidence
+
+3. **If no candidate groups are found**, skip to §4.
+
+**Merge does NOT fire for:** Units already flagged as Stack Skill Candidates in step 4 (map-and-detect §5) — those are multi-unit groupings that deliver value *separately* but are *also* useful together. Composite merges are for units that are *only* useful together (the key distinction). If a group of units is independently useful but commonly combined, it remains as separate units and is flagged as a stack skill candidate later.
+
+**This step is a recommendation — not automatic.** Merges are presented to the user in §5 for confirmation (see "Composite Merge Proposals" below). If the user rejects a merge, the constituents remain as separate units in the classification table.
+
 ### 4. Detect Primary Language Per Unit
 
-For each qualifying unit, determine the primary programming language based on:
+For each qualifying unit (including any approved composites from §3b), determine the primary programming language based on:
 - File extensions in the unit directory
 - Manifest file type (package.json → JS/TS, Cargo.toml → Rust, go.mod → Go, etc.)
 - Entry point file extension
@@ -126,20 +146,34 @@ For each qualifying unit, determine the primary programming language based on:
 **Already-Skilled Units:** {count from existing_skills match}
 {List with recommendation to run update-skill if source has changed}
 
+{IF composite merge proposals exist from §3b:}
+
+**Composite Merge Proposals:** {count}
+
+| # | Composite Name | Constituents | Heuristic | Evidence |
+|---|----------------|--------------|-----------|----------|
+| 1 | {name} | {list of constituent unit names} | {mutual hard dependency / shared integration surface} | {brief evidence} |
+
+If approved, each composite replaces its constituents in the classification table as a single Composite Boundary unit. The constituents are recorded in the composite's metadata for downstream workflows (create-skill reads constituents to scope extraction across all member paths).
+
+{END IF}
+
 **Notes:**
 - {Any observations about project structure patterns}
 - {Any ambiguous boundaries that need user clarification}
 
-Do these classifications look correct? Should any units be added, removed, or reclassified?"
+Do these classifications look correct? Should any units be added, removed, or reclassified?
+{IF composites proposed:} Are the composite merge proposals correct? (Accept/reject each individually.)"
 
-Wait for user feedback. Adjust classifications based on user input.
+Wait for user feedback. Adjust classifications based on user input. For approved composites: remove the constituent rows from the qualifying units table and add a single composite row with `Boundary Type: Composite`, scope type inherited from the dominant constituent, and confidence reflecting the merge heuristic strength.
 
 ### 6. Append to Report
 
 Append the complete "## Identified Units" section to {outputFile}:
 
 Replace the placeholder `[Appended by identify-units]` with:
-- Classification table (qualifying units)
+- Classification table (qualifying units, including approved composites)
+- Composite merge details (if any): composite name, constituents list, heuristic, evidence
 - Disqualification table
 - Already-skilled units list
 - Language detection results
@@ -149,8 +183,11 @@ Update {outputFile} frontmatter:
 ```yaml
 stepsCompleted: [append 'identify-units' to existing array]
 lastStep: 'identify-units'
+confirmed_composites: [{list of approved composite merge objects: {name, constituents[], heuristic}}]
 ```
 
+(`confirmed_composites` is an empty array when no composites were proposed or all were rejected.)
+
 ### 7. Present MENU OPTIONS
 
 Display: "**Select:** [C] Continue to Export Mapping and Integration Detection | [X] Cancel and exit"

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

@@ -46,10 +46,42 @@ 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.
 
+**Per-path ref overrides (`--target-refs`):** If `--target-refs <mapping>` was passed at invocation, parse it as a comma-separated list of `path:ref` pairs (e.g., `owner/repo:v1.0.0,owner/repo2:main`). Build a `constituent_refs` map from the pairs. Each key must match an entry in `project_paths[]` (validated after path collection). When `--target-refs` is absent but multiple `project_paths` exist, set `constituent_refs` to `{}` (empty — all paths use default ref resolution). When only a single path exists, omit `constituent_refs` entirely (use `target_ref` if set on the brief). `constituent_refs` and `target_ref` are mutually exclusive — if both are supplied, HALT with: "`--target-refs` and `--target-ref` are mutually exclusive. Use `--target-refs` for multi-path analysis, or `--target-ref` for single-path."
+
 "**Welcome to Analyze Source — the SKF decomposition engine.**
 
 I'll analyze your project to identify discrete skillable units and produce skill-brief.yaml files for each recommended unit.
@@ -71,6 +103,7 @@ Wait for user input.
 - For each provided path/URL: check that it exists (local) or is accessible (remote)
 - **IF any invalid:** "Path `{path}` doesn't appear to be valid. Please correct it."
 - Store as `project_paths[]` array in report frontmatter (single path stored as 1-element array for consistency)
+- **IF `constituent_refs` was built from `--target-refs`:** Validate that every key in the map matches an entry in `project_paths[]`. If any key has no matching path, HALT: "constituent_refs key `{key}` does not match any entry in project_paths."
 
 **Collect intent hint** (drives recommendation ranking in Step 5):
 
@@ -127,6 +160,7 @@ date: '{current_date}'
 user_name: '{user_name}'
 project_name: '{project_name}'
 project_paths: ['{provided_project_path}']
+constituent_refs: {map from --target-refs, or omit if single path}
 forge_tier: '{detected_tier}'
 existing_skills: [{list of existing skill names}]
 intent_hint: '{intent_hint or empty string}'
@@ -136,6 +170,8 @@ stack_skill_candidates: []
 nextWorkflow: ''
 ```
 
+**`constituent_refs` presence rules:** Include the field only when `project_paths` has more than one entry. When present, keys are path strings matching `project_paths[]` entries, values are explicit git refs (tag/branch/commit). Paths with no explicit ref have no entry in the map (default ref resolution applies). Downstream steps (scan-project, brief generation) read this map to resolve per-constituent refs when cloning or reading off-HEAD constituents.
+
 "**Initialization complete.**
 
 **Project:** {project_path}

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

@@ -28,6 +28,7 @@ To map the complete project structure by scanning directory trees, detecting ser
 
 Read {outputFile} frontmatter to obtain:
 - `project_paths[]` — the root(s) to scan (one or more paths/URLs)
+- `constituent_refs` — optional per-path git ref overrides (present only when `project_paths` has multiple entries and explicit refs were supplied via `--target-refs`)
 - `forge_tier` — determines scanning depth
 - Scope hints (if any were provided in step 01)
 
@@ -37,14 +38,16 @@ Load {heuristicsFile} for reference on detection signals.
 
 **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):
+**For each path in `project_paths[]`**, resolve the constituent ref (if any) and launch a subprocess that scans the project directory structure (aggregate results across all repos with clear repo-level grouping):
+
+**Per-path ref resolution:** If `constituent_refs` is present and contains an entry for the current path, use that ref. For remote paths, this means cloning or fetching at the specified ref (`git clone --branch {ref} --depth 1` or `git show {ref}:<subpath>` for off-HEAD access). For local paths with a non-HEAD ref, check out or read from the specified ref using `git show {ref}:<path>`. When no `constituent_refs` entry exists for a path, use default ref resolution (HEAD for local, latest tag or HEAD for remote).
 
 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 {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
+6. Return structured findings — file paths and types only, not contents. When `constituent_refs` was used, include the resolved ref in each repo-level result group: `{path, ref, manifests[], monorepo, warnings?}`
 
 **If subprocess unavailable:** Perform directory scanning in main thread using file I/O tools.