bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/skf-create-skill/references/source-resolution-protocols.md

@@ -2,57 +2,67 @@
 
 ## Shell Path Quoting
 
-Every shell snippet in this document uses `{...}` placeholders for paths. **Always wrap path interpolations in double quotes** when emitting the actual command — `git -C "{workspace_repo_path}"`, `rm -rf "{temp_path}"`, `cd "{project-root}"`. SKF's supported platforms are Linux and macOS; user home directories on macOS frequently contain spaces, which break unquoted shell. WSL2 users see the same. Native Windows is untested but the quoting convention is also required there.
+Every shell snippet in this document and in step 3 §2b uses `{...}` placeholders for paths. **Always wrap path interpolations in double quotes** when emitting the actual command: `uv run {sourceTreeHelper} resolve --source-repo "{source_repo}"`, `cd "{remote_clone_path}"`, `cd "{project-root}"`. Home folders on macOS often contain spaces, which break unquoted shell, and WSL2 and Windows paths do too, so the quoting convention applies on every platform.
 
 ## Tag Resolution
 
-Tag resolution maps a declared version in the brief onto a concrete git ref before cloning, so the skill is built from code matching its declared version. Three signals can drive it, in priority order: an explicit `brief.target_ref` (a ref the user states verbatim — highest priority), an **explicit** `brief.target_version` (deliberate user intent), or an **implicit** `brief.version` (auto-populated hint from `brief-skill`). All apply only when `source_repo` is a remote URL.
+Tag resolution maps a declared version in the brief onto a concrete git ref, so the skill is built from code matching its declared version. Three signals can drive it, in priority order: an explicit `brief.target_ref` (a ref the user states verbatim, highest priority), an **explicit** `brief.target_version` (deliberate user intent), or an **implicit** `brief.version` (auto-populated hint from `brief-skill`). They apply only to a remote source read at Forge tier or above: step 3 §2b hands them to the `resolve` subcommand of `{sourceTreeHelper}` as flags (its command shows which), and resolve lists the remote's tags and does the matching. A Quick-tier remote source reads `HEAD`.
 
-**Explicit ref override (when `target_ref` is set):** When `brief.target_ref` is present AND `source_repo` is a remote URL, use its value verbatim as `source_ref` and skip all version-to-tag matching below. This is the escape hatch for ref conventions the matching heuristics don't cover — notably monorepo crate tags whose prefix differs from the skill name (e.g. skill `livekit-rust` built from tag `livekit/v0.7.42`). Confirm it resolves first: `git ls-remote "{source_repo}" "{target_ref}"` (matches a tag or branch) — if it returns nothing, ⚠️ warn "`target_ref` ({target_ref}) does not resolve in {source_repo}; falling back to version matching" and continue with the version-based matching below.
+| The brief sets | What resolve reads |
+|---|---|
+| `target_ref` (it takes priority) | that ref as given: a tag (a tag wins over a branch of the same name), a branch, `HEAD` or a full commit |
+| `target_version` | the first of seven tag forms that exists (Explicit Tag Resolution) |
+| only `version` | the first of two tag forms that exists (Implicit Tag Resolution) |
+| none of them | `HEAD`, the default branch |
 
-**When none of `brief.target_ref`, `brief.target_version`, or `brief.version` is set:** skip tag resolution entirely. Set `source_ref` to `HEAD` (default branch).
+`target_ref` is the escape hatch for ref conventions the tag forms do not cover, notably monorepo crate tags whose prefix differs from the skill name (skill `livekit-rust` built from tag `livekit/v0.7.42`). When the brief sets it and a version too, resolve gets both: a `target_ref` the remote does not have adds the warning "target_ref ({target_ref}) does not resolve in {source_repo}; falling back to version matching", and resolve matches the version instead.
 
 ### Explicit Tag Resolution (when target_version is set)
 
-When `brief.target_version` is present AND `source_repo` is a remote URL, resolve the target version to a git tag before cloning:
+resolve tries these forms of `{target_version}` against the remote's tags, in priority order (every form but the first drops a leading `v` of the version):
 
-1. **List available tags:**
-   - `gh api repos/{owner}/{repo}/tags --paginate --jq '.[].name'`
-   - Fallback: `git ls-remote --tags "{source_repo}" | sed 's|.*refs/tags/||'`
+- **Exact match:** `{target_version}` (e.g., `0.5.0`)
+- **With `v` prefix:** `v{target_version}` (e.g., `v0.5.0`)
+- **With package scope (monorepos):** `{brief.name}@{target_version}` or `@{scope}/{brief.name}@{target_version}`
+- **With crate/package-directory prefix (monorepos):** `{brief.name}/v{target_version}`, `{brief.name}/{target_version}`, or `{brief.name}-v{target_version}` (e.g. `tokio/v1.0.0`). These cover monorepos whose tags are prefixed by the crate or package directory **when that directory equals the skill name**. When it differs (crate `livekit` for skill `livekit-rust`, tag `livekit/v0.7.42`), no form can infer it: set `target_ref` instead.
 
-2. **Match `target_version` against tags** in priority order:
-   - **Exact match:** `{target_version}` (e.g., `0.5.0`)
-   - **With `v` prefix:** `v{target_version}` (e.g., `v0.5.0`)
-   - **With package scope (monorepos):** `{brief.name}@{target_version}` or `@{scope}/{brief.name}@{target_version}`
-   - **With crate/package-directory prefix (monorepos):** `{brief.name}/v{target_version}`, `{brief.name}/{target_version}`, or `{brief.name}-v{target_version}` (e.g. `tokio/v1.0.0`). Covers monorepos whose tags are prefixed by the crate/package directory **when that directory equals the skill name**. When the directory differs from the skill name (e.g. crate `livekit` for skill `livekit-rust`, tag `livekit/v0.7.42`), this heuristic can't infer it — set `target_ref` explicitly instead.
+Outcomes, from `tag_resolution.status`:
 
-3. **Resolution outcomes:**
-   - **Single match:** Store the matched tag as `source_ref`. Use it as `{branch}` in all subsequent clone/API commands.
-   - **Multiple matches:** Present the matching tags to the user — "Multiple tags match version {target_version}: {list}. Which one should I use?" Wait for selection.
-   - **Zero matches:** ⚠️ Warn: "No git tag found matching version {target_version}. Closest available tags: {list 5 nearest by semver sort}. Falling back to default branch — **extracted code may not match target version.**" Set `source_ref` to `HEAD` and proceed with default branch.
+- **`matched`:** one form matched. resolve read that tag, and it is `source_ref`.
+- **`ambiguous`:** several tags matched, and nothing was read yet: see Several Matching Tags below.
+- **`fallback-head`:** no tag matched, and resolve read `HEAD`; the warning it printed names the nearest tags. ⚠️ Add: "**Extracted code may not match target version {target_version}.**"
 
-4. **Store `source_ref`** in context. This value is written to metadata.json and provenance-map.json for downstream workflows (update-skill, audit-skill) to re-clone from the same ref.
+`source_ref` is written to metadata.json and provenance-map.json for downstream workflows (update-skill, audit-skill) to read the same ref again.
 
 ### Implicit Tag Resolution (when only brief.version is set)
 
-When `brief.target_version` is absent but `brief.version` is present AND `source_repo` is a remote URL, treat `brief.version` as an **implicit** target version and attempt tag resolution before cloning. This matches `brief-skill`'s behavior, which auto-populates `brief.version` from the latest non-prerelease release tag — so a tag matching `brief.version` is the common case, and silently cloning HEAD would produce a skill labeled with `brief.version` but built from an unrelated default-branch commit.
+When `brief.target_version` is absent but `brief.version` is present, `brief.version` is an **implicit** target version. This matches `brief-skill`'s behavior, which auto-populates `brief.version` from the latest non-prerelease release tag, so a tag matching `brief.version` is the common case, and silently reading HEAD would produce a skill labeled with `brief.version` but built from an unrelated default-branch commit.
 
-1. **List available tags** exactly as in Explicit Tag Resolution above.
+With `--implicit`, resolve tries only two forms, in this order:
 
-2. **Match `brief.version` against tags** in this reduced priority order. Package-scoped monorepo variants are **not** tried — those require deliberate user intent via `target_version`, since implicit matching against a monorepo tag like `{brief.name}@{version}` could silently select a sibling package's ref:
-   - **Exact match:** `{brief.version}` (e.g., `0.3.37`)
-   - **With `v` prefix:** `v{brief.version}` (e.g., `v0.3.37`)
+- **Exact match:** `{brief.version}` (e.g., `0.3.37`)
+- **With `v` prefix:** `v{brief.version}` (e.g., `v0.3.37`)
 
-3. **Resolution outcomes:**
-   - **Single match:** Store the matched tag as `source_ref`. Use it as `{branch}` in all subsequent clone/API commands. Do not warn — this is the expected path.
-   - **Multiple matches:** Present the matching tags to the user — "Multiple tags match `brief.version` ({brief.version}): {list}. Which one should I use, or fall back to HEAD?" Wait for selection.
-   - **Zero matches:** ⚠️ Warn: "No git tag found matching `brief.version` ({brief.version}). Falling back to default branch — **extracted code may not match the declared version.** If you intended to pin a specific version, set `target_version` explicitly in the brief." Set `source_ref` to `HEAD` and proceed with default branch. Append `tag_resolution: {status: "fallback-head", requested: "{brief.version}", reason: "no-matching-tag"}` to the in-context evidence-report payload so step 5 §7 surfaces the fallback in the evidence report. This turns the warning into a persistent audit trail a reviewer can grep later, not just a one-shot stderr line.
+Package-scoped monorepo forms are **not** tried: they need deliberate user intent through `target_version`, since implicit matching against a monorepo tag like `{brief.name}@{version}` could silently select a sibling package's ref.
 
-4. **Do not halt on zero matches.** Unlike the explicit path, implicit resolution never blocks compilation — `brief.version` is an auto-populated hint, and some repositories simply do not tag releases. The warning is sufficient notice; the evidence report in step 8 will surface the HEAD fallback for reviewers.
+Outcomes, from `tag_resolution.status`:
 
-5. **Store `source_ref`** in context exactly as in the explicit path. It flows through to metadata.json and provenance-map.json so downstream workflows (update-skill, audit-skill) can re-clone from the same ref.
+- **`matched`:** no warning; this is the expected path.
+- **`ambiguous`:** see Several Matching Tags below, where `HEAD` is one of the choices.
+- **`fallback-head`:** no tag matched, and resolve read `HEAD`; the warning it printed names the nearest tags. ⚠️ Add: "**Extracted code may not match the declared version {brief.version}.** If you intended to pin a specific version, set `target_version` explicitly in the brief." Keep the `tag_resolution` record resolve printed (`status: "fallback-head"`, `requested`, `reason: "no-matching-tag"`) in the in-context evidence-report payload so step 5 §7 surfaces the fallback in the evidence report: a persistent audit trail a reviewer can grep later, not just a one-shot warning.
 
-**Interaction with Version Reconciliation (below):** When implicit tag resolution succeeds, the clone's source files should carry the same version as `brief.version` — so the Version Reconciliation section's source-vs-brief mismatch warning will not fire. When implicit resolution falls back to HEAD, Version Reconciliation runs normally against the default branch's version file and may produce its own mismatch warning.
+**Do not halt on zero matches.** Implicit resolution never blocks compilation: `brief.version` is an auto-populated hint, and some repositories simply do not tag releases. The warning is sufficient notice; the evidence report in step 8 will surface the HEAD fallback for reviewers.
+
+**Interaction with Version Reconciliation (below):** When implicit tag resolution matches a tag, the tree's source files should carry the same version as `brief.version`, so the Version Reconciliation section's source-vs-brief mismatch warning will not fire. When implicit resolution falls back to HEAD, Version Reconciliation runs normally against the default branch's version file and may produce its own mismatch warning.
+
+### Several Matching Tags
+
+When resolve prints `ambiguous`, it read nothing, and `tag_resolution.candidates` lists the matching tags in the priority order above. This is the one choice tag resolution leaves to you:
+
+- Ask: "Multiple tags match version {tag_resolution.requested}: {candidates}. Which one should I use?", adding "or should I fall back to HEAD?" for an implicit version, and "Setting `target_ref` in the brief skips this question next time." Wait for the selection.
+- **GATE [default: first candidate]**: under `{headless_mode}`, take the first candidate, log "headless: tag {tag} chosen from {candidates} for version {tag_resolution.requested}", and record the auto-decision per the Workflow Rules (step `extract`, gate `tag-choice`, decision `{tag}`): stage `{"step": "extract", "gate": "tag-choice", "decision": "{tag}", "rationale": "headless mode: first matching tag in priority order", "timestamp": "{ISO}"}` as `{run_dir}/decision.json` and run `uv run {emitEnvelopeHelper} record --workflow skf-create-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"`.
+
+Step 3 §2b then runs resolve again with the chosen tag (or `HEAD`) as `--target-ref`.
 
 ### Local Source Warning
 
@@ -68,133 +78,15 @@ Implicit resolution via `brief.version` is **not applied to local sources** —
 
 ## Remote Source Resolution
 
-**Note:** Quick-tier remote sources do not use the workspace/clone protocol described below. Quick tier accesses remote files via the `gh_bridge.read_file` path described in step 3 section 4.
-
-If `source_repo` is a local path: proceed with the tier-appropriate strategy as normal.
-
-If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is Forge, Forge+, or Deep:
-
-1. **Check `git` availability:** Verify `git` is functional (`git --version`). If `git` is not available, skip to the fallback warning below.
-
-2. **Compute workspace path:** Derive a persistent local path from the remote URL:
-
-   - **Parse the URL** to extract `{host}`, `{owner}`, `{repo}`:
-     - `https://github.com/facebook/react` or `https://github.com/facebook/react.git` → `github.com/facebook/react`
-     - `git@github.com:facebook/react.git` → `github.com/facebook/react`
-     - `facebook/react` (owner/repo shorthand) → `github.com/facebook/react`
-   - **Resolve workspace root:** Use environment variable `SKF_WORKSPACE` if set, otherwise `~/.skf/workspace/` (where `~` is the user's home directory on all platforms)
-   - **Workspace repo path:** `{workspace_root}/repos/{host}/{owner}/{repo}/`
-
-3. **Workspace check — resolve the source locally:**
-
-   **Concurrency guard:** all of the operations below (fetch, checkout, rev-parse, and the extraction read that follows in step 3) must be wrapped in an exclusive `flock` on `{workspace_repo_path}/.skf-workspace.lock`. Acquire the lock before the workspace-hit check, hold it across fetch + checkout + rev-parse, AND keep holding it through the extraction-time read of the working tree. Two concurrent batch runs that target the same workspace clone but different `source_ref` values would otherwise race — one would `checkout` while the other was reading files mid-extraction, corrupting the inventory. The lock makes the per-workspace-repo unit of work serial. Use `flock -x {lockfile} -c "..."` or `fcntl.flock(LOCK_EX)`. If `flock` is unavailable, log a warning ("Concurrency guard unavailable — concurrent forges against the same workspace repo may produce inconsistent extraction inventories") and proceed.
-
-   **If `{workspace_repo_path}/.git/` exists (workspace hit):**
-
-   The repo was previously cloned into the workspace. Fetch updates and checkout the requested ref.
-
-   **Detect tag vs branch for `source_ref`** (skipped when `source_ref` is `HEAD` — in that case fetch default branch without a ref argument):
-
-   ```
-   # Ask the remote whether source_ref exists as a tag
-   git -C "{workspace_repo_path}" ls-remote --tags origin {source_ref} | grep -q "refs/tags/{source_ref}$" && ref_kind=tag || ref_kind=branch
-   ```
-
-   Fetch using the ref-kind-appropriate invocation so tag refs are written into `refs/tags/*` rather than being dropped by a branch-only fetch:
-
-   ```
-   if ref_kind == tag:
-     git -C "{workspace_repo_path}" fetch origin tag {source_ref}
-   else:
-     git -C "{workspace_repo_path}" fetch origin {source_ref}
-   ```
-
-   Check if checkout is needed — skip if the requested ref is already checked out:
-
-   ```
-   current_head = git -C "{workspace_repo_path}" rev-parse HEAD
-   fetched_head = git -C "{workspace_repo_path}" rev-parse FETCH_HEAD
-   ```
-
-   If `current_head != fetched_head`:
-   ```
-   git -C "{workspace_repo_path}" -c advice.detachedHead=false checkout FETCH_HEAD
-   ```
-
-   If fetch or checkout fails, proceed to the **ephemeral fallback** (step 5).
-
-   **If `{workspace_repo_path}/.git/` does not exist (workspace miss):**
+**Note:** Quick-tier remote sources are never read into a tree. Quick tier accesses remote files via the `gh_bridge.read_file` path described in step 3 section 4.
 
-   Clone the repository into the workspace for persistent reuse. Create the parent directory first (`{workspace_root}/repos/{host}/{owner}/`):
+A remote source (a GitHub URL, an `owner/repo` shorthand or another git URL) read at Forge, Forge+ or Deep tier goes through one `resolve` call of `{sourceTreeHelper}` (step 3 §2b). It reads the commit Tag Resolution picks into a private tree of this run's own, which no other run can move, and with `--update-clone` moves SKF's workspace clone to the same commit in the same call, under the clone's `.skf-workspace.lock` and after running `{cccGitHygieneHelper}` there, never forcing a checkout (the `resolve` section of `skf-source-tree.py` has the details). The tree is removed with the helper's `close` subcommand at the end of step 7, or before any HALT after step 3 §2b.
 
-   ```
-   mkdir -p "{workspace_root}/repos/{host}/{owner}/"
-   ```
+**Compute workspace path:** SKF's workspace clone of a repository is `{workspace_root}/repos/{host}/{owner}/{repo}/`, where `{workspace_root}` is the environment variable `SKF_WORKSPACE` when set, otherwise `~/.skf/workspace/` (where `~` is the user's home directory on all platforms). resolve prints it as `workspace_path`.
 
-   Clone with the appropriate branch flag — `--branch` is only valid for real branch/tag names, not for `HEAD`. **Do not pass `--single-branch`** here: workspace clones are persistent and re-used for future forges with different `source_ref` values (a later run may target a different tag or branch). A single-branch workspace clone would force every re-forge with a new ref to fall through to ephemeral cloning, defeating the workspace cache:
+**Scope filtering:** the tree is a full checkout (no sparse-checkout), so apply `include_patterns` and `exclude_patterns` from the brief as **file-level filters** when building the extraction file list. Always-included root files (`pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `build.gradle.kts`, `Package.swift`, `setup.py`, `setup.cfg`, `VERSION`) are exempt from pattern filtering.
 
-   ```
-   # If source_ref is a real branch or tag (not HEAD/null):
-   git clone --depth 1 --branch {source_ref} "{source_repo}" "{workspace_repo_path}"
-
-   # If source_ref is HEAD or not set (default branch):
-   git clone --depth 1 "{source_repo}" "{workspace_repo_path}"
-   ```
-
-   **Note:** No `--filter=blob:none` — blobs for the current tree are needed for indexing and the cost is amortized across all future forges. No sparse-checkout — a full checkout serves all consumers (different briefs with different include/exclude patterns) without configuration conflicts. `--single-branch` is reserved for ephemeral clones (step 5); workspace clones keep all branches available so re-forges against different refs can fetch + checkout without re-cloning.
-
-   If this is the **first repo** in the workspace (workspace root was just created), print an informational message:
-
-   "Caching source at `{workspace_repo_path}` (saves time on re-forges). Override location with `SKF_WORKSPACE` env var."
-
-   If clone fails, proceed to the **ephemeral fallback** (step 5).
-
-4. **If workspace resolution succeeds:** Set `source_root = {workspace_repo_path}` — this updates the working source path for all subsequent operations (AST extraction, CCC indexing, artifact generation). Capture the source commit: `git -C "{workspace_repo_path}" rev-parse HEAD` — store as `source_commit` in context. Proceed with the **Forge/Deep Tier** extraction strategy below. Set context:
-   - `source_root = {workspace_repo_path}`
-   - `remote_clone_path = {workspace_repo_path}`
-   - `remote_clone_type = "workspace"`
-
-   **Scope filtering:** Since the workspace uses a full checkout (no sparse-checkout), apply `include_patterns` and `exclude_patterns` from the brief as **file-level filters** when building the extraction file list. Always-included root files (`pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `build.gradle.kts`, `Package.swift`, `setup.py`, `setup.cfg`, `VERSION`) are exempt from pattern filtering.
-
-5. **Ephemeral fallback (on any workspace failure):**
-
-   If workspace clone or fetch fails for any reason (network error, auth failure, disk full, timeout), fall back to ephemeral cloning — the pre-workspace behavior that always works:
-
-   ```
-   temp_path = {system_temp}/skf-ephemeral-{skill-name}-{timestamp}/
-
-   # If source_ref is a real branch or tag (not HEAD/null):
-   git clone --depth 1 --branch {source_ref} --single-branch --filter=blob:none "{source_repo}" "{temp_path}"
-
-   # If source_ref is HEAD or not set (default branch):
-   git clone --depth 1 --single-branch --filter=blob:none "{source_repo}" "{temp_path}"
-   ```
-
-   If ephemeral clone succeeds: Set `source_root = {temp_path}`. Capture `source_commit`. Set context:
-   - `source_root = {temp_path}`
-   - `remote_clone_path = {temp_path}`
-   - `remote_clone_type = "ephemeral"`
-
-   Apply `include_patterns` and `exclude_patterns` from the brief as file-level filters when building the extraction file list.
-
-6. **If all cloning fails (workspace AND ephemeral):**
-
-   ⚠️ **Warn the user explicitly:**
-
-   "Clone of `{source_repo}` failed: {error}. Degrading to source reading (T1-low) for this run. For T1 (AST-verified) confidence, clone the repository locally and update `source_repo` in your brief to the local path."
-
-   Proceed with Quick tier extraction strategy below. Note the degradation reason in context for the evidence report.
-
-**Remote clone cleanup:** After extraction is complete for all files in scope (whether successful or partially failed), before presenting the Gate 2 summary (Section 6):
-
-- **If `remote_clone_type == "ephemeral"`:** Cleanup is required.
-  1. **Reset working directory first:** Run `cd "{project-root}"` using the **absolute path** captured at workflow start.
-  2. **Delete the clone:** `rm -rf "{temp_path}"`
-  3. **Log:** "Ephemeral source clone cleaned up."
-
-  This ensures cleanup runs even if some extractions failed. If any error halts the step before Gate 2, cleanup must still occur.
-
-- **If `remote_clone_type == "workspace"`:** No cleanup. The workspace checkout persists for future forges.
+**When no tree can be read** (resolve prints `unavailable`, or does not finish), step 3 §2b warns the user and degrades this run to source reading (T1-low), with the Quick tier extraction strategy.
 
 ---
 
@@ -205,13 +97,15 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 After the source path is accessible, capture the current commit hash for provenance tracking:
 
 - **Local path:** `git -C "{source_root}" rev-parse HEAD` — if the path is a git repo
-- **Ephemeral clone (Forge/Deep):** already captured during clone (step 3 above)
+- **Remote source at Forge tier or above:** the `source_commit` resolve printed in step 3 §2b, the commit the tree holds
 - **Quick tier (remote, no clone):** `gh api repos/{owner}/{repo}/commits/{source_ref} --jq '.sha'`
 
 Store the result as `source_commit` in context. If capture fails (not a git repo, API unavailable), set `source_commit: null` — this is not an error.
 
 Also store `source_ref` in context (from tag resolution above, or `HEAD` if no tag was resolved, or `"local"` for local sources). This value is persisted to metadata.json and provenance-map.json so downstream workflows (update-skill, audit-skill) can re-access the same source ref.
 
+**The `source_root` metadata.json records** is `{resolved-source-path}` (`assets/skill-sections.md`): the local path for a local source; the remote URL for a remote source read without a tree (Quick tier, or a run degraded to source reading) or one whose workspace path holds a folder that is not SKF's clone; SKF's workspace clone (resolve's `clone`) for a remote source read from a private tree; null for a docs-only skill. Never the tree itself: step 7 removes it, while update-skill, test-skill and audit-skill read the skill's source from the workspace clone.
+
 ---
 
 ## Version Reconciliation (all tiers, source mode only)
@@ -220,7 +114,7 @@ Also store `source_ref` in context (from tag resolution above, or `HEAD` if no t
 
 **If `source_type: "docs-only"`:** skip this section — no source files exist to reconcile.
 
-After the source path is accessible (local path from step 1, or workspace/ephemeral clone from above), check whether the source contains a version identifier and reconcile it with `brief.version`. Look for the first matching version file in the resolved source path:
+After the source path is accessible (local path from step 1, or the private tree from above), check whether the source contains a version identifier and reconcile it with `brief.version`. Look for the first matching version file in the resolved source path:
 
 - Python: `pyproject.toml` (`[project] version`), `setup.py` (`version=`), `__version__` in `__init__.py`
 - JavaScript/TypeScript: `package.json` (`"version"`). **Monorepo resolution:** When multiple `package.json` files exist (workspace root + packages), resolve version using this priority:

package/src/skf-create-skill/references/step-auto-shard.md

@@ -2,11 +2,18 @@
 nextStepFile: 'step-doc-rot.md'
 # Resolve `{shardBodyHelper}` by probing `{shardBodyProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
-# path wins. HALT if neither resolves — hand line-counting is the least reliable
-# deterministic op and would silently ship an over-budget body or wrongly HALT.
+# path wins. HALT (exit code 3, helper-missing) if neither resolves: hand
+# line-counting would silently ship an over-budget body or wrongly halt.
 shardBodyProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-shard-body.py'
   - '{project-root}/src/shared/scripts/skf-shard-body.py'
+# HARD HALT helpers (Rules).
+sourceTreeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-source-tree.py'
+  - '{project-root}/src/shared/scripts/skf-source-tree.py'
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -26,14 +33,15 @@ Proactively reduce oversized SKILL.md bodies to under 400 lines by extracting Ti
 - Do not modify frontmatter — only body content and references/ directory
 - Do not invoke `npx skill-check split-body` — this step uses direct extraction
 - Do not invoke the Description Guard Protocol — frontmatter is untouched
+- A HARD HALT, once step 3 §2b has bound `{source_tree}`, first runs `uv run {sourceTreeHelper} close --tree "{source_tree}"` from `{project-root}` (resolved from `{sourceTreeProbeOrder}`) and goes on whatever it prints, and emits through `{emitEnvelopeHelper}`, resolved from `{emitEnvelopeProbeOrder}` when it is not bound. After its envelope, under `--batch` it ends only this brief: return to `references/batch-mode.md` §3, even when the halt reads as the end of the run.
 
 ## MANDATORY SEQUENCE
 
-### §0. Run the Shard Script (primary path)
+### §0. Run the Shard Script
 
-The counting, boundary detection, size-sort, file writes, and blockquote replacement described in §1–§5 are fully deterministic and run every invocation — so a script owns them, not the model. Do not count body lines or extract sections by hand when the script ran.
+A script owns the counting, the section boundaries, the size sort, the file writes and the cross-reference blockquotes, on every run: do not count body lines or extract sections by hand.
 
-**Resolve `{shardBodyHelper}`** from `{shardBodyProbeOrder}`; first existing path wins. HALT if no candidate exists.
+**Resolve `{shardBodyHelper}`** from `{shardBodyProbeOrder}`; first existing path wins. If no candidate exists, **HARD HALT** (exit code 3, `helper-missing`, phase `auto-shard`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "Cannot shard the body: skf-shard-body.py is missing. Re-install SKF, then re-run create-skill."
 
 Run:
 
@@ -41,97 +49,16 @@ Run:
 uv run {shardBodyHelper} <staging-skill-dir>/SKILL.md --budget 400
 ```
 
-The script performs everything §1–§5 document — it counts the body between the frontmatter close and EOF, enumerates the `## Full` Tier 2 sections, extracts the largest first to `references/` until the body fits, writes the extracted files and the trimmed SKILL.md through the atomic-write helper, rewrites each section as a cross-reference blockquote, and checks Tier 1 preservation and cross-reference integrity. Read its JSON and set context directly:
+The script counts the body between the frontmatter close and EOF. Over 400 lines, it extracts the Tier 2 sections, the ones whose heading starts `## Full` (`## Full API Reference` goes to `references/full-api-reference.md`, `## Full Type Definitions` to `references/full-type-definitions.md`, `## Full Integration Patterns` to `references/full-integration-patterns.md`), largest first, until the body fits. It writes the extracted files and the trimmed SKILL.md through the atomic-write helper, puts a cross-reference blockquote (`> See [Full API Reference](references/full-api-reference.md)`) in each extracted section's place, and checks that every Tier 1 section inline before is still inline (`tier1_preserved`, with any pulled heading in `tier1_missing`) and that each cross-reference resolves (`xref_ok`). Read its JSON and set context directly:
 
-- **`action: "skip"`** → the body was already within budget. Log `"auto-shard: skipped (body {body_lines_before} lines)"`, set `auto_shard_triggered: false`, `sections_extracted: []`, `body_lines_before`/`body_lines_after` from the report, then skip to §6.
+- **`action: "skip"`** → the body was already within budget. Log `"auto-shard: skipped (body {body_lines_before} lines)"`, set `auto_shard_triggered: false`, `sections_extracted: []`, `body_lines_before`/`body_lines_after` from the report, then skip to §1.
 - **`action: "shard"`** → set `auto_shard_triggered: true` and copy `sections_extracted`, `body_lines_before`, `body_lines_after` straight from the report.
-- **HALT** if `tier1_preserved` is false: `"Auto-shard removed Tier 1 section(s) {tier1_missing}. Aborting."`
-- **HALT** if `xref_ok` is false: `"Auto-shard cross-references did not resolve. Aborting."`
-- If `under_budget` is false, selective Tier 2 extraction alone could not bring the body under budget (rare — Tier 1 itself exceeds ~300 lines). Apply the §4 editing-judgment trim, then continue.
+- If `tier1_preserved` is false, **HARD HALT** (exit code 5, `tier1-not-preserved`, phase `auto-shard`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): `"Auto-shard removed Tier 1 section(s) {tier1_missing}. Aborting."`
+- If `xref_ok` is false, **HARD HALT** (exit code 5, `shard-xref-broken`, phase `auto-shard`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): `"Auto-shard cross-references did not resolve. Aborting."`
+- If `under_budget` is false, selective Tier 2 extraction alone could not bring the body under budget (rare: Tier 1 itself exceeds about 300 lines). Trim `## Key API Summary` and `## Architecture at a Glance` until the body fits the 400-line budget, never moving a Tier 1 section to `references/`, then run the script again and take `body_lines_after` from it.
 
-Log: `"auto-shard: {N} sections extracted, body reduced from {body_lines_before} to {body_lines_after} lines"`, then proceed to §6.
+Log: `"auto-shard: {N} sections extracted, body reduced from {body_lines_before} to {body_lines_after} lines"`, then proceed to §1.
 
-**Manual fallback (only when `uv`/Python is unavailable):** perform §1–§5 by hand as documented below — they describe exactly what the script does.
-
-### §1. Count Body Lines
-
-The script counts all lines in the staging SKILL.md between the frontmatter closing `---` and EOF, excluding trailing blank lines, and reports the total as `body_lines_before`.
-
-```
-body_lines_before = body_line_count
-```
-
-**IF `body_line_count` <= 400:** the script emits `action: "skip"` and writes nothing —
-- Log: `"auto-shard: skipped (body {body_line_count} lines)"`
-- Set context: `auto_shard_triggered: false`, `sections_extracted: []`, `body_lines_before: {body_line_count}`, `body_lines_after: {body_line_count}`
-- Skip to §6 (Auto-Proceed)
-
-**ELSE:** the script proceeds to §2.
-
-### §2. Selective Shard — Tier 2 Extraction
-
-The script identifies Tier 2 sections by their `## Full` heading prefix:
-- `## Full API Reference` → `references/full-api-reference.md`
-- `## Full Type Definitions` → `references/full-type-definitions.md`
-- `## Full Integration Patterns` → `references/full-integration-patterns.md`
-
-Sections are sorted by line count descending (largest first).
-
-**FOR EACH Tier 2 section (largest first):**
-
-1. Extract the full section content (from `## Full` heading to the next `##` heading or EOF)
-2. Derive the reference filename from the heading: kebab-case (as shown above)
-3. Write the extracted content (preserving the `##` heading) to `<staging-skill-dir>/references/{filename}` via the atomic-write helper
-4. Replace the extracted section in SKILL.md with a cross-reference blockquote:
-   ```markdown
-   > See [Full API Reference](references/full-api-reference.md)
-   ```
-5. Re-count body lines
-6. **IF `body_line_count` <= 400:** stop extracting, proceed to §3
-
-The report's `sections_extracted: [{heading, file, lines}]` records exactly which sections were pulled.
-
-### §3. Tier 1 Preservation Check
-
-The script verifies ALL Tier 1 sections that were inline before extraction remain inline in SKILL.md afterward. These headings:
-
-- `## Overview`
-- `## Quick Start`
-- `## Common Workflows`
-- `## Key API Summary` (or `## Component Catalog` for component-library scope)
-- `## Migration & Deprecation Warnings` (conditional — only checked if it was present before extraction)
-- `## Key Types`
-- `## Architecture at a Glance`
-- `## CLI` (conditional — only checked if present before extraction)
-- `## Scripts & Assets` (conditional — only checked if present before extraction)
-- `## Manual Sections` (conditional — only checked if present before extraction)
-
-The result surfaces as `tier1_preserved` (with any pulled headings in `tier1_missing`).
-
-**IF `tier1_preserved` is false:**
-HALT: `"Auto-shard removed Tier 1 section {name}. Aborting."`
-
-### §4. Post-Shard Validation
-
-The report's `body_lines_after` is the recount after all extraction. `under_budget` is true when the body now fits.
-
-**IF `under_budget` is false** (body still > 400 after all Tier 2 sections extracted — this is the one genuine editing-judgment step):
-- Trim oversized Tier 1 sections: reduce `## Key API Summary` and `## Architecture at a Glance` content to fit within the 400-line budget
-- Do not move any Tier 1 section to references/
-- Re-run `{shardBodyHelper}` (or re-count) and update `body_lines_after`
-
-### §5. Cross-Reference Integrity
-
-The script verifies, for each extracted reference file, that the file exists at `<staging-skill-dir>/references/{filename}` and that the cross-reference blockquote in SKILL.md links to it — reported as `xref_ok`. HALT if `xref_ok` is false.
-
-Log: `"auto-shard: {N} sections extracted, body reduced from {body_lines_before} to {body_lines_after} lines"`
-
-Set context:
-- `auto_shard_triggered: true`
-- `sections_extracted: [{heading names}]`
-- `body_lines_before: {before}`
-- `body_lines_after: {after}`
-
-### §6. Auto-Proceed
+### §1. Auto-Proceed
 
 Load, read the entire file, then execute `{nextStepFile}`.