bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/skf-analyze-source/references/step-auto-scope.md

@@ -1,6 +1,10 @@
 ---
 nextStepFile: 'health-check.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
+heuristicsFile: 'references/unit-detection-heuristics.md'
+coexistenceFile: 'references/step-auto-scope-coexistence.md'
+splitFile: 'references/step-auto-scope-split.md'
+corporaFile: 'references/step-auto-scope-corpora.md'
 shapeDetectProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-shape-detect.py'
   - '{project-root}/src/shared/scripts/skf-shape-detect.py'
@@ -16,9 +20,15 @@ scanManifestsProbeOrder:
 detectLanguageProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-language.py'
   - '{project-root}/src/shared/scripts/skf-detect-language.py'
-languageCorporaProbeOrder:
-  - '{project-root}/_bmad/skf/shared/scripts/skf-language-corpora.py'
-  - '{project-root}/src/shared/scripts/skf-language-corpora.py'
+detectWorkspacesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-workspaces.py'
+  - '{project-root}/src/shared/scripts/skf-detect-workspaces.py'
+writeSkillBriefProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-write-skill-brief.py'
+  - '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
+validateBriefSchemaProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
+  - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -36,217 +46,165 @@ To automatically scope a repo using shape detection and export surface analysis,
 - Must produce the same output artifacts as the interactive chain: analysis report + skill-brief.yaml
 - On unknown shape (exit code 1), fall back to `scan-project.md` (the normal interactive entry point)
 - On error (exit code 2), HARD HALT with exit code 3 (`resolution-failure`)
+- Every brief goes through the brief writer and the schema gate (§8): a brief either one rejects halts the run before any brief is written
 
 ## MANDATORY SEQUENCE
 
+Every HARD HALT in this step names its exit code, `halt_reason` and phase. When `{headless_mode}` is true it first prints its envelope on stderr through the shared emitter (`{emitEnvelopeHelper}` and `{run_dir}` come from SKILL.md On Activation): stage `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "mode": "auto"}`, plus `"path"` when the halt names one, then run
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+and display the line it prints verbatim. Write the payload as valid JSON: in the halt message and `path`, replace each backslash with / and each double quote with a backtick. If the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing.
+
 ### 0. URL Type Detection
 
-Read the target URL or path from the pipeline context (`{project_path}` or the first entry in `project_paths[]`).
+**Resolve `{skillInventoryHelper}`** from `{skillInventoryProbeOrder}`; first existing path wins. If neither resolves, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `step-auto-scope:0`): "`skf-skill-inventory.py` is missing. Re-install SKF." The helper classifies `{project_path}` (the first of `project_paths[]`):
 
-Apply the following heuristic to classify the input:
+```bash
+uv run {skillInventoryHelper} derive-name --target "{project_path}" --probe-git
+```
 
-| Input Pattern | Classification | Route |
-|---------------|---------------|-------|
-| `github.com/{owner}/{repo}` (with or without `.git` suffix, with or without scheme prefix) | GitHub repo | §1 (standard auto-scope) |
-| `gitlab.com/...`, `bitbucket.org/...` | Git hosting | §1 (standard auto-scope) |
-| Starts with `/`, `./`, `~/`, or `~` | Local filesystem path | §1 (standard auto-scope) |
-| Any other `https://` or `http://` URL | Documentation URL | `references/auto-docs-only.md` (docs-only, via §0c) |
-| Anything else (SSH URLs, `git://`, bare hostnames, etc.) | Unclassified | §1 (standard auto-scope) |
+| `kind` | Classification | Route |
+|---|---|---|
+| `docs` | Documentation URL | HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `step-auto-scope:0`, path `{project_path}`) with its `halt_message` when it gives one, else `references/auto-docs-only.md`, via §0c |
+| `local` | Local filesystem path | §1 |
+| `remote` | Repo URL, cloned from `clone_url` | §1 |
 
-Store the classification result (documentation URL vs. repo/local/other). For all input types, continue to §0b (Pin Resolution).
+Store `{kind}` and `{clone_url}`; every kind continues to §0b.
 
 ### 0b. Pin Resolution
 
-This section validates and resolves version pins. It runs for repo URLs and local paths only — skip for documentation URLs (doc URLs have no git repo to pin against). Initialize `{pinned_ref}`, `{pinned_ref_type}`, and `{pinned_version}` as null.
+This section validates and resolves version pins. Initialize `{pinned_ref}`, `{pinned_ref_type}`, and `{pinned_version}` as null.
 
-**For documentation URLs:** Skip this section entirely. Continue to §0c.
+**For documentation URLs** (no git repo to pin against): skip to §0c.
 
-**For local paths when `--pin` is provided:** Emit a warning: "**Local source may not match pinned version {pin_value}.** Ensure you've checked out the correct version locally, or use a remote GitHub URL so SKF can clone from the git tag automatically." Store `{pinned_ref}` = `{pin_value}`, `{pinned_ref_type}` = `"local"`, `{pinned_version}` = `{pin_value}`. Continue to §0c without running `skf-validate-pins.py`.
+**For a local path (`{kind}` is `local`) when `--pin` is provided:** Emit a warning: "**Local source may not match pinned version {pin_value}.** Ensure you've checked out the correct version locally, or use a remote GitHub URL so SKF can clone from the git tag automatically." Store `{pinned_ref}` = `{pin_value}`, `{pinned_ref_type}` = `"local"`, `{pinned_version}` = `{pin_value}`. Continue to §0c without running `skf-validate-pins.py`.
 
-**For repo URLs when `--pin` is provided:**
+**For a repo URL (`{kind}` is `remote`) when `--pin` is provided:**
 
-**Resolve `{validatePinsHelper}`** from `{validatePinsProbeOrder}`; first existing path wins; HALT if neither resolves.
+**Resolve `{validatePinsHelper}`** from `{validatePinsProbeOrder}`; first existing path wins. If neither resolves, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `step-auto-scope:0b`): "`skf-validate-pins.py` is missing. Re-install SKF."
 
 ```bash
-uv run {validatePinsHelper} --repo-url {project_path} --pin {pin_value}
+uv run {validatePinsHelper} --repo-url "{clone_url}" --pin {pin_value}
 ```
 
 Handle exit codes:
 
 - **Exit 0** (`status: "valid"`): Store `{pinned_ref}` = `resolved_ref`, `{pinned_ref_type}` = `ref_type`, `{pinned_version}` = `version`. Continue to §0c.
-- **Exit 1** (`status: "invalid"`): HARD HALT with exit code 3 (`resolution-failure`). Emit error: `"Version pin '{pin_value}' not found in {project_path}. Available matches: {suggestions}. Use a valid tag, branch, or omit --pin for latest."` Emit the error envelope (shape in `references/headless-contract.md`) with `exit_code: 3`, `halt_reason: "pin-invalid"`, `mode: "auto"`.
-- **Exit 2** (error): HARD HALT with exit code 3 (`resolution-failure`). Emit the error envelope with `halt_reason: "resolution-failure"`.
+- **Exit 1** (`status: "invalid"`): HARD HALT (exit code 3, `halt_reason: "pin-invalid"`, phase `step-auto-scope:0b`): "Version pin '{pin_value}' not found in {project_path}. Available matches: {suggestions}. Use a valid tag, branch, or omit --pin for latest."
+- **Exit 2** (error): HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `step-auto-scope:0b`): "The version pin could not be checked: {the helper's error}."
 
 **For repo URLs when `--pin` is not provided (default):**
 
 Using the same `{validatePinsHelper}` resolved above:
 
 ```bash
-uv run {validatePinsHelper} --repo-url {project_path}
+uv run {validatePinsHelper} --repo-url "{clone_url}"
 ```
 
 Handle exit codes:
 
 - **Exit 0** (`status: "resolved"`): Store `{pinned_ref}` = `resolved_ref`, `{pinned_ref_type}` = `ref_type`, `{pinned_version}` = `version`. Log: "Default pin resolved: {resolved_ref}". Continue to §0c.
 - **Exit 1** (no releases found): Set `{pinned_ref}` = null, `{pinned_ref_type}` = null, `{pinned_version}` = null. Log: "No release tags found — using HEAD." Continue to §0c without pinning.
-- **Exit 2**: Log warning, continue without pinning (same as exit 1 behavior).
+- **Exit 2**: record the warning with `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning 'pin_unresolved: <the helper message, a single quote written as a backtick>'` (if it fails, go on), then continue to §0c without pinning, as on exit 1.
 
 ### 0c. Coexistence Detection
 
-This section checks for existing skills matching the target before proceeding. It runs for all input types (repo URLs, doc URLs, and local paths). Initialize `{coexistence_suffix}` as empty.
+This section checks for existing skills matching the target, whatever its kind, then goes on to its **route**: load, read fully, then execute `references/auto-docs-only.md` for a documentation URL, §1 for every other kind. Initialize `{coexistence_suffix}` as empty.
 
 **1. Load skill inventory:**
 
-**Resolve `{skillInventoryHelper}`** from `{skillInventoryProbeOrder}`; first existing path wins; HALT if neither resolves.
-
-Pass the target (`{project_path}`) so the helper computes the coexistence match set for you — do not re-match by hand:
+Pass the target (`{project_path}`) to `{skillInventoryHelper}`, resolved in §0, so the helper computes the coexistence match set for you; do not re-match by hand:
 
 ```bash
-uv run {skillInventoryHelper} {skills_output_folder} --match-target {project_path}
+uv run {skillInventoryHelper} "{skills_output_folder}" --match-target "{project_path}"
 ```
 
-Parse the JSON output. If the exit code is non-zero or the `skills` array is empty, skip coexistence detection silently (no existing skills to conflict with) and continue: load, read fully, then execute `references/auto-docs-only.md` for documentation URLs; §1 for all other input types.
+Parse the JSON output. If the exit code is non-zero or the `skills` array is empty, skip coexistence detection silently (no existing skills to conflict with) and go on to the route.
 
 **2. Read the match set:**
 
-The helper already performed the match deterministically — scheme / trailing-`.git` / trailing-slash normalization, kebab expected-name derivation (§6 repo/package name, doc hostname per `references/auto-docs-only.md`), and case-insensitive comparison of both the normalized `source_repo` (URL match) and the derived name (name match). Read the top-level **`matches[]`** array from the JSON; do not normalize, derive, or compare anything in the prompt. Each entry is:
+Read the top-level **`matches[]`** array; the helper has already matched, so do not re-match. Each entry is:
 
 ```json
-{ "name": "...", "active_version": "...", "source_repo": "...", "active_path": "...", "match_reason": "url" | "name" | "both" }
+{ "name": "...", "active_version": "...", "source_repo": "...", "active_path": "...", "match_reason": "url" | "name" | "both", "skf_skill": true | false }
 ```
 
-**3. If `matches[]` is empty:**
-
-Complete silently. Continue: execute `references/auto-docs-only.md` for documentation URLs; §1 for all other input types. No user output.
-
-**4. If `matches[]` has one or more entries — coexistence gate:**
-
-Present the user with the coexistence decision, one bullet per `matches[]` entry (`{skill_name}` = `matches[].name`, `{version}` = `matches[].active_version`, `{source_repo}` = `matches[].source_repo`):
+`skf_skill` is true when SKF generated the matched skill (its `metadata.json` carries an SKF marker). Only those are offered for a merge: a merge hands the skill to update-skill, which rewrites its files, and SKF changes only the skills it generated.
 
-```
-⚠️ Existing skill(s) found for {target_name}:
-
-  • {skill_name} (v{version}) — source: {source_repo}
-  [repeat for each entry in matches[]]
-
-Actions:
-  [A]longside — Create a new wiki skill with "-wiki" suffix (existing skill untouched)
-  [M]erge     — Update the existing skill via US workflow (wiki data enriches it)
-  [S]kip      — Do not create or modify any skill for this library
-
-Choose [A/M/S]:
-```
-
-In headless mode (`{headless_mode}` is true): auto-select `[A]longside` and log: "Headless: coexistence detected for {target_name}, auto-selecting [A]longside"
+**3. If `matches[]` is empty:**
 
-**5. Handle user selection:**
+Complete silently and go on to the route. No user output.
 
-- **[A]longside:** Set `{coexistence_suffix}` to `-wiki`. Continue: execute `references/auto-docs-only.md` for documentation URLs; §1 for all other input types. The existing skill is untouched.
-
-- **[M]erge:** If `matches[]` has more than one entry, prompt the user to select which one to merge into before proceeding. Read `{matched_skill_name}` = the selected entry's `matches[].name` and `{matched_active_path}` = its `matches[].active_path`. Emit a redirect envelope signaling the forger to route to the US workflow for the selected skill:
-  ```
-  SKF_ANALYZE_RESULT_JSON: {"status":"redirect","redirect_to":"US","skill_name":"{matched_skill_name}","skill_path":"{matched_active_path}","exit_code":0,"halt_reason":null,"mode":"auto","coexistence":"merge"}
-  ```
-  Write the result contract per `shared/references/output-contract-schema.md` with `status: "redirect"`.
-  Chain to {nextStepFile} (health-check.md). **STOP HERE — do not proceed to the docs-only sub-flow or §1.**
-
-- **[S]kip:** Emit a skip envelope:
-  ```
-  SKF_ANALYZE_RESULT_JSON: {"status":"skipped","report_path":null,"brief_paths":[],"unit_counts":{"confirmed":0,"skipped":1,"maybe":0},"exit_code":0,"halt_reason":null,"mode":"auto","coexistence":"skip","skipped_reason":"Existing skill for {matched_skill_name}"}
-  ```
-  Write the result contract with `status: "skipped"`.
-  Chain to {nextStepFile} (health-check.md). **STOP HERE — do not proceed to the docs-only sub-flow or §1.**
+**4. If `matches[]` has one or more entries:** load, read fully, then execute {coexistenceFile}, the coexistence gate. Its [A]longside comes back here with `{coexistence_suffix}` set to `-wiki` and goes on to the route; its [M]erge and [S]kip end the run through §9.
 
 ### 1. Load Context
 
 Read {outputFile} frontmatter to obtain:
-- `project_paths[]` — the root(s) to analyze
-- `forge_tier` — for brief generation
+- `project_paths[]`: the root(s) to analyze
+- `forge_tier`: for brief generation
 - `project_name`, `user_name`, `date`
+- `scope_hint` (the folders or packages to focus on or skip) and `intent_hint` (the goal of the analysis), each possibly empty: §3b, §5 and §6 apply them
 
 Load `references/step-shape-detect.md` as reference for shape detection invocation contract and shape→scope mapping.
 
 ### 2. Manifest Scan
 
-Enumerate package manifests **deterministically** via `{scanManifestsHelper}` (the same helper the interactive `scan-project.md` uses) — do not hand-scan. Resolve `{scanManifestsHelper}` as the first path in `{scanManifestsProbeOrder}` that exists. The scanner reads a **local directory**, so how you point it at the target depends on the input form classified in §0:
+Enumerate package manifests **deterministically** via `{scanManifestsHelper}` (the same helper the interactive `scan-project.md` uses): do not hand-scan. Resolve `{scanManifestsHelper}` as the first path in `{scanManifestsProbeOrder}` that exists; if none does, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `step-auto-scope:2`): "`skf-scan-manifests.py` is missing. Re-install SKF." The scanner reads a **local directory**, so how you point it at the target depends on its `kind`: §0 gave `{kind}` and `{clone_url}` for its target, and §0's `derive-name --target` call gives them for any other path, and its `halt_message` halts the run as in §0, with phase `step-auto-scope:2` and that path as `{project_path}`.
 
 **For each path in `project_paths[]`:**
 
-- **Local filesystem path** (starts with `/`, `./`, `~/`, `~`, or is an existing directory) — scan it directly:
+- **`kind` is `local`:** scan it directly. Its **scan root** is the path itself, with a leading `~` written as `$HOME`: the commands below quote every path, and a `~` inside double quotes does not expand.
 
   ```bash
-  uv run {scanManifestsHelper} scan {path}
+  uv run {scanManifestsHelper} scan "<the path's scan root>" > "{run_dir}/manifests-{i}.json"
   ```
 
-- **Remote git URL** (e.g. `github.com/{owner}/{repo}`) — auto-scope has no working tree yet and the scanner cannot read a URL. Fetch **just the manifests** first (blobless + sparse + depth-1 — no source blobs, typically KB–MB even for large monorepos), then scan that tree:
+- **`kind` is `remote`:** auto-scope has no working tree yet and the scanner cannot read a URL. Fetch **just the manifests** into the run folder (blobless + sparse + depth-1: no source blobs, typically KB to MB even for large monorepos); `{run_dir}/clone-{i}`, for the `{i}`-th entry of `project_paths[]` (`clone-1` for §0's target), is the path's **scan root**:
 
   ```bash
-  tmp="$(mktemp -d)"
-  git clone --filter=blob:none --no-checkout --depth 1 {pinned_branch_flag} {path} "$tmp"
-  git -C "$tmp" sparse-checkout set --no-cone '**/package.json' '**/Cargo.toml' '**/pyproject.toml' '**/go.mod' '**/pom.xml' '**/build.gradle' '**/build.gradle.kts' '**/Package.swift' 'pnpm-workspace.yaml' '**/pnpm-workspace.yaml'
-  git -C "$tmp" checkout
-  uv run {scanManifestsHelper} scan "$tmp"
+  git clone --filter=blob:none --no-checkout --depth 1 {pinned_branch_flag} "{clone_url}" "{run_dir}/clone-{i}"
+  git -C "{run_dir}/clone-{i}" sparse-checkout set --no-cone '**/package.json' '**/Cargo.toml' '**/pyproject.toml' '**/go.mod' '**/pom.xml' '**/build.gradle' '**/build.gradle.kts' '**/Package.swift' 'pnpm-workspace.yaml' '**/pnpm-workspace.yaml' 'lerna.json' 'rush.json' 'nx.json'
+  git -C "{run_dir}/clone-{i}" checkout
+  uv run {scanManifestsHelper} scan "{run_dir}/clone-{i}" > "{run_dir}/manifests-{i}.json"
   ```
 
-  where `{pinned_branch_flag}` is `--branch {pinned_ref}` when a pin was resolved in §0b (so manifests match the target version), otherwise omitted. **Retain `"$tmp"` through §3** — shape detection reads the discovered manifest files from it — then it may be discarded.
-
-Parse the JSON envelope: `{manifests: [{path, ecosystem, ...}], total_unique, monorepo, warnings?}`. The scanner discovers the project root plus monorepo workspace members (npm/pnpm/yarn `workspaces`, Cargo `[workspace]`, and other ecosystems) and sets the `monorepo` flag — so members are found without hand-listing each workspace convention, for both local trees and remote fetches.
+  where `{pinned_branch_flag}` is `--branch {pinned_ref}` when a pin was resolved in §0b (so manifests match the target version), otherwise omitted. If a `git` command fails, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `step-auto-scope:2`, path `{path}`): "{path} could not be fetched: {the first stderr line}." The clone stays in the run folder until the run ends, so §3 and §5 read it in later commands.
 
-From the envelope, record:
+Each `{run_dir}/manifests-{i}.json` holds the scanner's JSON envelope: `{manifests: [{path, ecosystem, ...}], total_unique, monorepo, warnings?}`, each `path` relative to the scan root. The scanner discovers the project root plus monorepo workspace members (npm/pnpm/yarn `workspaces`, Cargo `[workspace]`, and other ecosystems) and sets the `monorepo` flag, so members are found without hand-listing each workspace convention, for both local trees and remote fetches. Shape detection (§3) reads `{run_dir}/manifests-1.json` itself, so no manifest list passes through you. From the envelope, record:
 
-1. **Supported manifest paths** — filter `manifests[].path` to the types `skf-shape-detect.py` accepts (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `build.gradle.kts`, `Package.swift`). Each `manifests[].path` is **relative to the scan root**, so resolve them against that root (`{path}` for a local scan, `"$tmp"` for a remote fetch) before use. This filtered, comma-joined list of resolved paths is fed to shape detection in §3. For a monorepo, it includes each workspace member's manifest, so the package surface is classified accurately rather than from a bare (and often export-less) repo root. The scanner may discover ecosystems shape detection does not yet classify; those are excluded here, so a repo with no supported manifest falls back to interactive at the next check rather than auto-scoping.
-2. **`monorepo` flag** and the count of discovered supported packages — carried forward as a signal for the decomposition decision in §3a.
+1. **The `monorepo` flag**, a signal for the decomposition decision in §3a.
+2. **The names and flags §3b, §6 and the split branch read:** the scan-root manifest's `name` and `private` (the `manifests[]` entry whose `path` has no folder), each member manifest's `name`, `private` and `internal_deps`, and `umbrella_candidates[]`. Read them from the envelope; never open a member manifest for them.
 
-**Harvest tree-level language signals.** A whole-language repo may declare no parser-generator dependency (a hand-written compiler such as rustc, TypeScript, or the Go toolchain) or carry no supported manifest at all (CPython, Ruby). From the **same** fetched tree — no second clone and no blobs, since tree objects are already present in the blobless clone — collect two signals for shape detection. These are pure path listings (`git ls-tree` reads tree objects; no checkout, no blob download):
+**List the target's files once.** Shape detection (§3) and language detection (§5 and the split branch) read the whole file list of the target (`{project_path}`, §0's target) from one run file, `{run_dir}/tree.txt`, so the listing never passes through you or a shell variable. Write it with the first command that fits the target, where `{scan_root}` is the target's scan root:
 
-- **Remote fetch** (`"$tmp"`), or a **local path** that is a git repo (`git -C {path}`):
-  ```bash
-  files="$(git -C "$tmp" ls-tree -r    --name-only HEAD)"   # every file path
-  dirs="$( git -C "$tmp" ls-tree -r -d --name-only HEAD)"   # every directory
-  # Grammar files (depth-capped to skip deep vendored fixtures, hard-capped):
-  grammar_matches="$(printf '%s\n' "$files" \
-    | grep -Ei '\.(g4|pest|lalrpop|y|gram|lark|ebnf|peg|ungram)$|/grammar\.(js|json)$' \
-    | awk -F/ 'NF<=4' | head -n 50 | paste -sd, -)"
-  # Directory signals (trailing /) + depth-capped file basenames, narrowed to
-  # compiler-relevant paths so the argument stays bounded on huge repos. The
-  # filter is a loose superset of shape detection's gates — the script does the
-  # precise matching; this only keeps the list small.
-  tree_paths="$({ printf '%s\n' "$dirs" | sed 's#$#/#'; \
-                  printf '%s\n' "$files" | awk -F/ 'NF<=5'; } \
-    | grep -Ei '(^|/)(compiler|compile|syntax|scanner|lexer|tokeniz|parser|parse|ast|binder|checker|codegen|ssagen|interpreter|vm|eval|rustc_[a-z]+)' \
-    | head -n 400 | paste -sd, -)"
-  ```
-- **Local path that is not a git repo** (`{path}`): list the tree with `find` instead, then derive `grammar_matches` / `tree_paths` the same way:
-  ```bash
-  files="$(cd {path} && find . -type f -not -path '*/.git/*' | sed 's#^\./##')"
-  dirs="$( cd {path} && find . -type d -not -path '*/.git/*' | sed 's#^\./##')"
-  ```
-
-Record `<grammar_matches>` and `<tree_paths>` (each a comma-joined list, possibly empty) for §3.
+```bash
+git -C "{scan_root}" -c core.quotePath=false ls-tree -r --name-only HEAD > "{run_dir}/tree.txt"
+git -C "{scan_root}" -c core.quotePath=false ls-files > "{run_dir}/tree.txt"
+(cd "{scan_root}" && find . -type f -not -path '*/.git/*' | sed 's#^\./##') > "{run_dir}/tree.txt"
+```
 
-**IF no supported manifests are found** (the filtered list is empty):
-- **AND** `<grammar_matches>` is empty **AND** `<tree_paths>` shows no compiler directory (none of `compiler/`, `src/compiler/`, `cmd/compile/`, `internal/syntax/`, or a `Parser/`): the repo carries no language signal — emit fallback message: "**Auto-scope could not find any supported package manifests — switching to interactive mode.**" Load, read fully, then execute `references/scan-project.md`. **STOP HERE.**
-- **Otherwise** (a grammar file or a compiler directory is present) the repo is a manifest-less language toolchain (CPython, Ruby): proceed to §3 with an **empty** `--manifests` and the harvested `--grammar-files` / `--tree-paths`.
+The first lists a remote fetch (tree objects only: the blobless clone downloads no file for it), the second a local path inside a git work tree (`git -C "{scan_root}" rev-parse --is-inside-work-tree` prints `true`), the third any other local folder. If the command fails or writes an empty file, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `step-auto-scope:2`, path `{project_path}`): "The files of {project_path} could not be listed: {the first stderr line}."
 
 ### 3. Invoke Shape Detection
 
-**Resolve `{shapeDetectHelper}`** from `{shapeDetectProbeOrder}`; first existing path wins; HALT if neither resolves.
+**Resolve `{shapeDetectHelper}`** from `{shapeDetectProbeOrder}`; first existing path wins. If neither resolves, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `step-auto-scope:3`): "`skf-shape-detect.py` is missing. Re-install SKF."
 
-Invoke the shape detection script with the discovered manifests and the harvested tree-level signals:
+Invoke the shape detection script on the §2 manifest scan and file list. It keeps the manifest types it classifies, resolves each against the scan root and finds the tree-level signals (grammar files, a compiler folder and its lexer, parser and ast) itself, so a manifest-less language toolchain (CPython, Ruby) is recognized from its files:
 
-```
-uv run {shapeDetectHelper} --repo-url <project_path_or_url> \
-  --manifests <comma_separated_manifest_paths> \
-  --grammar-files <grammar_matches> --tree-paths <tree_paths>
+```bash
+uv run {shapeDetectHelper} --repo-url "{project_path}" --manifests-file "{run_dir}/manifests-1.json" --manifest-dir "{scan_root}" --tree-file "{run_dir}/tree.txt"
 ```
 
-`<comma_separated_manifest_paths>` may be empty for a manifest-less language repo, provided `<grammar_matches>` or `<tree_paths>` carries the signal. Parse the JSON output: `{shape, signals, confidence, export_count, package_count}`
+Parse the JSON output: `{shape, signals, confidence, export_count, package_count}`
 
 **Handle exit codes:**
 
 - **Exit 0 (shape classified):** Continue to §3a.
-- **Exit 1 (unknown shape):** Emit fallback message: "**Auto-scope could not classify this repo — switching to interactive mode.**" Load, read fully, then execute `references/scan-project.md`. **STOP HERE.**
-- **Exit 2 (error):** HARD HALT with exit code 3 (`resolution-failure`). Emit the error envelope (shape in `references/headless-contract.md`) with `exit_code: 3`, `halt_reason: "resolution-failure"`, `mode: "auto"`.
+- **Exit 1 (unknown shape):** the run goes on as an interactive analysis. Set `mode: 'interactive'` in {outputFile}'s frontmatter (so a later session resumes it: init archives an unfinished `'auto'` report) and `{auto_mode}` to false. When `{pinned_ref_type}` is `"tag"` or `"branch"`, also set `target_ref: '{pinned_ref}'` and `refs: {each project path: '{pinned_ref}'}` there, so the chain scans every path and writes every brief at the §0b pin (a `"local"` pin, or none, sets neither, as the §8 pin table gives no `target_ref` for them). Then emit the fallback message: "**Auto-scope could not classify this repo: switching to interactive mode.**", then load, read fully, and execute `references/scan-project.md`. **STOP HERE.**
+- **Exit 2 (error):** HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `step-auto-scope:3`): "Shape detection failed: {the `error` its stderr JSON names}."
 
 ### 3a. Check Decomposition Thresholds
 
@@ -256,131 +214,94 @@ Apply the **Decomposition Thresholds** ladder from `step-shape-detect.md` (loade
 
 **Decision:**
 
-- **Threshold not met** (`package_count ≤ 3`) → Continue to §4 (single-scope flow, entirely unchanged).
+- **Threshold not met** (`package_count ≤ 3`) → Continue to §4 (single-scope flow).
 - **Threshold met** (`package_count > 3`) → this repo is a **decomposition candidate**. A threshold firing means the repo *could* decompose, not that it *should* — continue to §3b to decide merge-vs-split. Log: "Auto-decomposition candidate: package_threshold ({value} packages exceeds 3)".
 
 ### 3b. Cohesion Check — Merge to One Skill vs Split into N
 
-Reached only when §3a flagged a decomposition candidate. Most published monorepos are **cohesive** and produce a better single skill than a pile of fragments — empirically, 5/5 real monorepos (animato 15 crates, trpc, react 38 packages, aws-sdk-js-v3 442 packages, plus zod) were best served as one cohesive skill or a curated few, not one-skill-per-package. Decide deliberately:
+Reached only when §3a flagged a decomposition candidate. Most published monorepos are **cohesive** and produce a better single skill than a pile of fragments. Load {heuristicsFile} and apply its **Cohesion Triggers**, the one statement of when members belong in one skill, reading their evidence from the §2 envelope (`umbrella_candidates[]`, and each member's `name`, `private` and `internal_deps`) and never from the member manifests themselves. Decide deliberately:
 
-**Merge into ONE cohesive skill** (override the threshold → continue to §4 single-scope) when **any** of these hold:
+- **Merge into ONE cohesive skill** (override the threshold → continue to §4 single-scope) when **any** cohesion trigger holds.
+- **Split into N skills** when the members meet its split condition instead: load, read fully, then execute {splitFile}, which replaces §4 to §6 and returns to §7.
 
-- **Umbrella facade** — one package re-exports the members: a root or named package whose dependencies include the other workspace members, or which `pub use` / `export *`s them. The facade *is* the public surface (e.g. animato's `crates/animato` re-exporting its 15 sub-crates).
-- **Shared runtime contract** — the members are consumed together through one entry point, and teaching the shared invariant covers them (e.g. tRPC's adapters around `@trpc/server`; aws-sdk's `new XClient(...) → client.send(new YCommand(...))` shared by every `@aws-sdk/client-*`).
-- **Internal building blocks** — the members are private/internal pieces of one product, not independently meaningful to a consumer.
+If genuinely unsure, **prefer merge** — a too-broad single skill is recoverable with `US`; N fragmented skills are not.
 
-**Split into N skills** (→ §4a) when:
+**Record the decision** the moment you make it, so the run's result and a later halt both carry it: write `{run_dir}/decision.json` as `{"gate": "auto-scope.cohesion", "default_action": "merge", "taken_action": "<merge or split>", "reason": "<the cohesion trigger that held, or why the members split>", "evidence": {"package_count": <package_count>, "members": [<the §2 member names>]}}` and run
 
-- The members are **independently published with distinct public surfaces serving different concerns**, **and no umbrella re-exports them** — e.g. `react-dom` and `react-server-dom-*` are separate installs with separate jobs, or a federated SDK where a consumer only ever wants one service. Each genuinely-distinct facet earns its own skill.
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-analyze-source --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+```
 
-If genuinely unsure, **prefer merge** — a too-broad single skill is recoverable with `US`; N fragmented skills are not.
+If the command fails, go on: only that entry is lost.
 
 **Facet-coverage guard (merged facet-diverse repos only).** When you merge a repo whose members have genuinely distinct surfaces and you scope to only some of them, record the decision explicitly — never drop a facet silently:
 
-- In `scope.notes`, name the in-scope facets **and** the excluded major facets, e.g. _"Scoped to react + react-dom core; excludes react-server-dom-\* (RSC), the specialized renderers (react-art/native/test), and the compiler — forge a separate skill for those."_
+- When `intent_hint` is not empty, the facets it names are the ones in scope.
+- In `scope.notes`, name the in-scope facets **and** the excluded major facets, e.g. _"Scoped to react + react-dom core; excludes react-server-dom-\* (RSC), the specialized renderers (react-art/native/test), and the compiler: forge a separate skill for those."_
 - Surface the excluded facets in the analysis report (§7) so the operator can re-scope or forge a companion skill.
 
 ### 4. Map Shape to Scope
 
-Apply the canonical **Shape → Scope Type Mapping** table from `step-shape-detect.md` (loaded at §1) — the single source of truth for this ladder (the `export_count > 200 → public-api` split, the `language-reference` corpora caveat, and the `stack-compose` decomposition note).
+Apply the canonical **Shape → Scope Type Mapping** table from `step-shape-detect.md` (loaded at §1).
 
-### 5. Generate Include/Exclude Patterns
+**An app or a library on a framework.** When §3's `signals` hold `app_or_library:framework_dep`, take that table's row for it and judge which of its two cases the repository is from the scan-root manifest's `description` (its `manifests[]` entry in `{run_dir}/manifests-1.json`), or, when that does not settle it, the README's opening paragraph (a remote fetch checked out only the manifests: `git -C "{scan_root}" sparse-checkout add '/README*'` brings the README in). From here on `{shape}` is the shape you chose. Record the choice: write `{run_dir}/decision.json` as `{"gate": "auto-scope.shape", "default_action": "reference-app", "taken_action": "<reference-app or library-API>", "reason": "<the sentence of the description or README that decided>", "evidence": {"signals": [<the §3 signals>]}}` and run `uv run {emitEnvelopeHelper} record --workflow skf-analyze-source --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"` (if it fails, go on).
 
-Generate `scope.include` and `scope.exclude` arrays from the detected language and project structure.
+**A language on a parser.** When §3's `signals` hold `language_or_user:parser_dep`, judge which case of that signal's row the repository is, from the same description or README: from here on `{shape}` is the shape that case gives. Record it the same way (after the choice above when both hold), with `default_action` the shape you judged from and `taken_action` the new `{shape}`.
 
-**Detect the primary language once, deterministically**, via the shared helper — the single source of truth for the manifest→language rule table (§6b resolves the same helper; do not restate the table in prose, where it drifts from the script). **Resolve `{detectLanguageHelper}`** from `{detectLanguageProbeOrder}` (first existing path wins). Pipe the §2 supported-manifest paths (and, for a manifest-less toolchain, the harvested `<tree_paths>`) as the file tree:
+### 5. Generate Include/Exclude Patterns
+
+**Detect the primary language once**, from the §2 file list, with the shared helper. **Resolve `{detectWorkspacesHelper}`** from `{detectWorkspacesProbeOrder}` and **`{detectLanguageHelper}`** from `{detectLanguageProbeOrder}`; first existing path wins for each. If one has no candidate, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `step-auto-scope:5`): "`{the missing script}` is missing. Re-install SKF." First find the workspace layout, which reads the root manifests from the scan root (§2):
 
 ```bash
-echo '{"tree": [<§2 supported manifest paths + harvested tree paths>]}' | uv run {detectLanguageHelper}
+uv run {detectWorkspacesHelper} --tree-file "{run_dir}/tree.txt" --manifest-dir "{scan_root}"
 ```
 
-Read `.language` as `{detected_language}` (and `.confidence`) — the helper owns the `tsconfig.json` JS-vs-TS and `build.gradle` Java-vs-Kotlin disambiguation. §6 reuses `{detected_language}` for the brief's `language` field: detect once.
-
-**Default patterns (adjust based on actual project structure):**
-
-| Language | Default include | Default exclude |
-|----------|-----------------|-----------------|
-| TypeScript/JavaScript | `['src/**/*.ts', 'src/**/*.tsx']` | `['**/*.test.ts', '**/*.spec.ts', '**/node_modules/**']` |
-| Python | `['src/**/*.py']` or `['{package_name}/**/*.py']` | `['**/*_test.py', '**/test_*.py', '**/tests/**']` |
-| Rust | `['src/**/*.rs']` | `['**/tests/**', '**/benches/**']` |
-| Go | `['**/*.go']` | `['**/*_test.go', '**/vendor/**']` |
-| Java | `['src/main/java/**/*.java']` | `['**/src/test/**']` |
-| Kotlin | `['src/main/kotlin/**/*.kt']` | `['**/src/test/**']` |
-| Swift | `['Sources/**/*.swift']` | `['**/Tests/**']` |
-
-**Adjust for actual layout:** If the project uses a non-standard layout (e.g., `lib/` instead of `src/`, or a named package directory for Python), detect and use the actual paths. Check for the existence of common source directories (`src/`, `lib/`, `pkg/`, the package name directory) and prefer the one that exists.
+`{workspace_kind}` ← its `manifest_kind` (null when it exits non-zero). Then detect the language, passing `--workspace-signal {workspace_kind}` only when `{workspace_kind}` is not null, so a Cargo or Python workspace root wins over a nested package.json:
 
-### 6. Build Scope and Determine Skill Name
-
-Build the scope object:
-```yaml
-scope:
-  type: '{mapped_scope_type}'
-  include: ['{generated_include_patterns}']
-  exclude: ['{generated_exclude_patterns}']
-  notes: 'Auto-scoped from shape detection (shape: {shape}, confidence: {confidence}).{corpus_caveat}'
+```bash
+uv run {detectLanguageHelper} --tree-file "{run_dir}/tree.txt" [--workspace-signal {workspace_kind}]
 ```
 
-Determine the skill name from the project name or package name (kebab-case, lowercase). Use the manifest `name` field if available, otherwise derive from the project directory name. If `{coexistence_suffix}` is non-empty, append it to the skill name.
-
-For the brief's `language` field, **reuse `{detected_language}` from §5** — do not re-detect (the §5 helper already resolved js-vs-ts from `tsconfig.json` and Java-vs-Kotlin from the tree).
-
-### 6b. Seed Companion Corpora (whole-language references only)
-
-Runs only when §3 classified the repo as `language-reference` **via a whole-language signal** — the `signals` array contains a `grammar_file:` or `tree_triad:` entry (a compiler / interpreter / grammar repo such as rust-lang/rust, TypeScript, CPython). **Skip** when `language-reference` fired only from `parser_producer:` / `parser_dep:` signals (a parser *library* such as pest or lalrpop): there the code **is** the product, so no companion prose is needed and the §6/§7 caveat below does not apply.
-
-A whole-language skill's value is in the language's **prose** — the guide/Book, the standard/library API docs, idioms — not the compiler internals. Seed those canonical corpora so the forged skill teaches the language rather than its implementation.
-
-**Resolve `{detectLanguageHelper}`** from `{detectLanguageProbeOrder}` and **`{languageCorporaHelper}`** from `{languageCorporaProbeOrder}` (first existing path wins).
-
-1. **Derive the corpus language key `{corpus_language}`.** Prefer `{detected_language}` (from §5) when non-empty. Otherwise — a manifest-less toolchain such as CPython or Ruby — resolve it from the file paths harvested in §2:
-   ```bash
-   echo '{"tree": [<harvested §2 file paths>]}' | uv run {detectLanguageHelper}
-   ```
-   Use its `language` field. (`.c`/`.h`/`.y` are not in the detector's extension map, so a C-hosted language resolves by its real sources — Ruby via `.rb`.)
-2. **Look up canonical corpora:**
-   ```bash
-   uv run {languageCorporaHelper} --language {corpus_language}
-   ```
-   - exit 0 → parse the `[{url, label, source}]` array (each seed carries `source: language-registry`) → these are `{corpus_seeds}`.
-   - exit 1 → no registry entry (long-tail language) → `{corpus_seeds}` is empty (README detection in brief-skill remains the only source).
-   - exit 2 → log a warning and treat as empty (best-effort; never halt).
-3. Record `{N}` = number of seeds and `{corpus_labels}` = comma-joined labels, carried into the brief `doc_urls` (§8) and the honest caveat (§6/§7).
-4. Build `{corpus_caveat}` (appended to `scope.notes` in §6/§8 and surfaced in §7) so the operator knows a code-only whole-language skill is low-value:
-   - `{N}` ≥ 1: `" LANGUAGE-REFERENCE CAVEAT: this skill's value is the {corpus_language} prose (guide/Book + std/library docs), not compiler internals. Seeded {N} corpus URL(s): {corpus_labels}. create-skill foregrounds this registry prose as the skill's Language Guide and demotes compiler-internal signatures to a reference-only section — review the forged skill if compiler internals still dominate."`
-   - `{N}` == 0: `" LANGUAGE-REFERENCE CAVEAT: no canonical corpora were found for {corpus_language} (README detection and the registry both came up empty). This skill is LOW-VALUE as code-only — attach the {corpus_language} guide + std/library docs manually (re-run with a doc URL, or enrich via US) before forging."`
-
-   For a parser-library `language-reference` (skipped above) and every other shape, `{corpus_caveat}` is empty.
+The helper owns the `tsconfig.json` JS-vs-TS and `build.gradle` Java-vs-Kotlin disambiguation, ranks the manifests nearest the root first, and never lets a manifest in a docs, example, test or tool folder decide while another one exists. Read `{detected_language}`:
 
-### 4a. Multi-Scope Decomposition
+- **`detected_languages` has one entry or none, or `.confidence` is `high` and the §2 scan-root manifests (the `manifests[]` entries whose `path` has no folder) are all of one ecosystem:** `{detected_language}` ← `.language`. A manifest at the root decided, so the choice below would give the same answer.
+- **Otherwise** (several languages, and no single-ecosystem root manifest decided): `.language` is the helper's first guess, not the answer. Choose the language the skill documents: among `detected_languages`, the language of the scan-root manifest (the §2 `manifests[]` entry whose `path` has no folder; with several, the one whose `name` is the package this repository publishes), or, when there is none, `.source_language`, the language most of the files are written in (CPython's listing holds only manifests below its root, so `.confidence` is `medium` and its sources say `python`). Record the choice: write `{run_dir}/decision.json` as `{"gate": "auto-scope.language", "default_action": "<detected_languages[0]>", "taken_action": "<the language you chose>", "reason": "<the manifest or the source files that decided>", "evidence": {"detected_languages": [<detected_languages>], "source_language": "<source_language>"}}` and run `uv run {emitEnvelopeHelper} record --workflow skf-analyze-source --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"` (if it fails, go on).
 
-This section is reached only from §3b when the cohesion check decided to **split** a monorepo (members are independently published with distinct surfaces and no umbrella re-exports them). It replaces §4→§5→§6 for repos that will produce N > 1 skills.
+**Take the patterns from the §2 listing**, never from the folders on disk (a remote scan root holds only the manifests): `scope.include` and `scope.exclude` are what this prints:
 
-**Decompose by workspace package:** Use workspace package discovery from §2 manifest scan results. Each workspace package with its own manifest becomes a separate skill boundary. Name each skill as `{project_name}-{package_name}` (kebab-case); if `{coexistence_suffix}` is non-empty, append it. Trivial workspace members (no source files, no exports) are excluded.
+```bash
+uv run {detectLanguageHelper} scope-patterns --tree-file "{run_dir}/tree.txt" --language {detected_language}
+```
 
-**Per-boundary shape→scope mapping:**
+**Apply `scope_hint`** when it is not empty: root the include patterns at the folders or packages it focuses on (`packages/auth/**/*.ts`), and add `<folder>/**` to the exclude patterns for each folder it skips. Name the hint in `scope.notes`.
 
-For each decomposed boundary, apply the shape→scope mapping from §4 independently — re-run the shape→scope heuristic ladder from `step-shape-detect.md` per package using each package's own manifest data. Packages may have different shapes (e.g., a `library-API` core + a `reference-app` CLI).
+### 6. Build Scope and Determine Skill Name
 
-### 5a. Generate Multi-Scope Patterns
+The single-scope brief's scope (§8 hands these values to the brief writer):
 
-For each decomposed boundary, generate include/exclude patterns using the same language-aware rules as §5, but scoped to the boundary's source paths. Monorepo boundaries are rooted at the package path (e.g., `packages/auth/src/**/*.ts` instead of `src/**/*.ts`).
+- `scope.type`: the §4 mapped scope type
+- `scope.include` and `scope.exclude`: the §5 patterns
+- `scope.notes`: `Auto-scoped from shape detection (shape: {shape}, confidence: {confidence}).{corpus_caveat}`, plus the `scope_hint` note of §5 when there is one
 
-### 6a. Build Multi-Scope
+**Whole-language reference:** when §3 classified the repo as `language-reference` and its `signals` hold a `grammar_file:` or `tree_triad:` entry, load, read fully, then execute {corporaFile} now: it sets `{corpus_seeds}`, `{corpus_caveat}`, `{corpus_doc_urls}` and the report's Companion Corpora subsection, then returns here. Otherwise (every other shape, a parser library included) `{corpus_caveat}` is empty and `{corpus_doc_urls}` null.
 
-For each boundary, build a scope object following the same structure as §6.
+Name the skill with the helper that names every brief, by {heuristicsFile}'s Unit Names, so the name the brief gets is the name the coexistence check looks up:
 
-Include decomposition metadata in `scope.notes`: "Decomposed from {project_name} — boundary {i}/{N} ({reason})"
+```bash
+uv run {skillInventoryHelper} derive-name --from - --skills-folder "{skills_output_folder}" <<'SKF_SKILL_NAME'
+[{"target": "{project_path}", "manifest_name": <name>, "private": <private>, "members": [<member names>]}]
+SKF_SKILL_NAME
+```
 
-Determine each boundary's skill name from the boundary-derived name (kebab-case, lowercase). If `{coexistence_suffix}` is non-empty, append it to each skill name. Detect the primary language from each boundary's manifest ecosystem (same rules as §6).
+`manifest_name` is the umbrella candidate's `name` when §3b merged on the umbrella facade trigger, else the §2 scan-root manifest's `name` (null without one), and `private` that manifest's `private`. `members` lists the `name` of every §2 member manifest whose `private` is not `true` (`[]` for a single package): a merged monorepo whose root names no published package takes the name they share (`aws-sdk` for the `@aws-sdk/*` packages), else the repository's. `{skill_name}` ← `names[0].name`; when the entry is in `unnamed` (a target with no folder name), name the skill after the analyzed folder yourself. A split names its boundaries in one call the same way, and names the entries `unnamed` and `duplicates` list from their folders.
 
-**Pin data (from §0b):** All N decomposed briefs share the same pin — the pin targets a repo-level ref, not a package-level version. Apply the same `target_version`/`target_ref` values from §0b to all N boundaries at brief write time (§8).
+When `names[0].existing` is not null and names a skill §0c did not present (a skill from another source that already has the name this brief gets), load, read fully, then execute {coexistenceFile} with it as the one `matches[]` entry before §7 writes anything: [M]erge and [S]kip end the run there; [A]longside, the headless choice, sets `{coexistence_suffix}` to `-wiki` and continues here. Then, if `{coexistence_suffix}` is non-empty, append it to the skill name.
 
-After building all N scopes, continue to §7 with the full set of boundaries.
+The brief's `description` (one to three sentences, from the shape, the language and the manifest name) is worded toward `intent_hint` when it is not empty.
 
 ### 7. Write Analysis Report
 
-Update {outputFile} with auto-scope results. If the write fails, HARD HALT with exit code 4 (`write-failed`) per `references/headless-contract.md`.
+Update {outputFile} with auto-scope results. If the write fails, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `step-auto-scope:7`, path `{outputFile}`): "The analysis report could not be written: {the error}."
 
 **Update frontmatter:**
 ```yaml
@@ -408,11 +329,11 @@ decomposition:
 
 Each `confirmed_units` entry includes `boundary_path` — the relative path to the boundary's root (e.g., `packages/core`). Omit the `decomposition` key entirely when single-scope (N = 1).
 
-**When single-scope (N = 1):** No `decomposition` key. `confirmed_units` contains a single entry (existing behavior).
+**When single-scope (N = 1):** No `decomposition` key. `confirmed_units` contains a single entry.
 
 **Append body section:**
 
-For single-scope (unchanged):
+For single-scope:
 ```markdown
 ## Auto-Scope Analysis
 
@@ -426,114 +347,108 @@ For single-scope (unchanged):
 **Exclude Patterns:** {exclude patterns}
 ```
 
-**When the shape is a whole-language `language-reference`** (§6b ran — a `grammar_file:`/`tree_triad:` signal), append a Companion Corpora subsection so the operator sees whether the skill has the prose that makes it useful. The status is computed from the **final** brief `doc_urls` (the entries that will actually be fetched), not the seed count alone:
+**When {corporaFile} ran** (a whole-language `language-reference`), append the Companion Corpora subsection it gives.
 
-```markdown
-## Companion Corpora (language-reference)
+**For a split (N > 1):** append the decomposition body {splitFile} gives instead of the single-scope section.
 
-**Why:** A whole-language skill's value is its prose (guide/Book, std/library docs, idioms), not compiler internals.
-**Corpora in brief doc_urls:** {final_doc_urls_count}
-  - {label}: {url}   # one line per doc_urls entry
-**Status:** {ATTACHED — canonical corpora present | DEGRADED — code-only, no canonical corpora; attach the {corpus_language} guide + std/library docs before forging}
-```
-
-For multi-scope (N > 1):
-```markdown
-## Auto-Scope Analysis — Decomposition ({N} skills)
+### 8. Write Skill Briefs
 
-**Mode:** auto
-**Decomposition:** {reason} ({N} boundaries)
-**Parent Shape:** {shape} (confidence: {confidence})
-**Export Count:** {export_count}
-**Package Count:** {package_count}
+The brief writer renders, checks and writes every brief, and applies the version precedence (`target_version`, then `detected_version`, then `1.0.0`) and the rule that `target_version` equals `version`. This section supplies values and never writes YAML. **Resolve `{writeSkillBriefHelper}`** from `{writeSkillBriefProbeOrder}` and **`{validateBriefSchemaHelper}`** from `{validateBriefSchemaProbeOrder}`; first existing path wins for each. If one has no candidate, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `step-auto-scope:8`): "`{the missing script}` is missing. Re-install SKF."
 
-### Boundary 1: {boundary_name}
-**Scope Type:** {scope_type}
-**Boundary Path:** {boundary_path}
-**Include Patterns:** {include patterns}
-**Exclude Patterns:** {exclude patterns}
-**Rationale:** {boundary_rationale}
+**For each confirmed unit** (1 for single-scope, N for decomposition), write its context as `{run_dir}/brief-{skill_name}.json`, a file and never an echo'd string (the language caveat holds an apostrophe):
 
-### Boundary 2: {boundary_name}
-...
+```json
+{
+  "name": "{skill_name}",
+  "target_version": "{target_version from the pin table, or null}",
+  "target_ref": "{target_ref from the pin table, or null}",
+  "detected_version": "{detected_version, or null}",
+  "source_type": "source",
+  "source_repo": "{project_path}",
+  "language": "{detected_language}",
+  "description": "{1-3 sentence description based on shape, language, and manifest name}",
+  "forge_tier": "{forge_tier}",
+  "created": "{current_date}",
+  "created_by": "{user_name}",
+  "scope_type": "{scope_type}",
+  "scope_include": ["{include_patterns}"],
+  "scope_exclude": ["{exclude_patterns}"],
+  "scope_notes": "{scope.notes}",
+  "scope_rationale": null,
+  "scope_tier_a_include": null,
+  "scope_amendments": null,
+  "scope_registry_path": null,
+  "scope_ui_variants": null,
+  "scope_demo_patterns": null,
+  "doc_urls": null,
+  "scripts_intent": null,
+  "assets_intent": null,
+  "source_authority": null,
+  "source_ref": null
+}
 ```
 
-### 8. Write Skill Brief
+Only `description` and `scope_notes` are in your words. Every other value comes from an earlier section:
 
-**For each confirmed unit** (1 for single-scope, N for decomposition):
+- `name`, `scope_type`, `scope_include`, `scope_exclude` and `scope_notes`: §6 for a single scope; the split branch's §6a for each boundary of a decomposition.
+- `language`: §5's `{detected_language}` for a single scope (detect once); the split branch's §6a for each boundary.
+- `detected_version`: by `assets/skill-brief-schema.md`'s **Version Detection**, for the §2 scan-root manifest (its `manifests[]` entry in `{run_dir}/manifests-1.json`).
+- `target_version` and `target_ref`, from the §0b pin, the same for every brief:
 
-Create directory `{forge_data_folder}/{skill_name}/` if it does not exist. If a brief write fails, HARD HALT with exit code 4 (`write-failed`) per `references/headless-contract.md`.
+  | `{pinned_ref_type}` | `target_version` | `target_ref` |
+  |---|---|---|
+  | `"tag"` | `{pinned_version}` | `{pinned_ref}` |
+  | `"branch"` | null | `{pinned_ref}` |
+  | `"local"` | `{pinned_version}` when it is a version (`X.Y.Z`, with an optional leading `v`), else null | null |
+  | null (no pin, no release) | null | null |
 
-Write `{forge_data_folder}/{skill_name}/skill-brief.yaml` conforming to the skill-brief schema (`{briefSchemaPath}`):
+- `doc_urls`: `{corpus_doc_urls}` (null unless {corporaFile} seeded corpora).
 
-```yaml
-name: '{skill_name}'
-version: '{detected_version or 1.0.0}'
-source_repo: '{project_path}'
-language: '{detected_language}'
-scope:
-  type: '{scope_type}'
-  include:
-    - '{include_patterns}'
-  exclude:
-    - '{exclude_patterns}'
-  notes: 'Auto-scoped from shape detection (shape: {shape}, confidence: {confidence}).{corpus_caveat}'
-description: '{1-3 sentence description based on shape, language, and manifest name}'
-forge_tier: '{forge_tier}'
-created: '{current_date}'
-created_by: '{user_name}'
-```
+**Gate every brief before any is written.** For each one, render it into the run folder and run on it the schema check skf-brief-skill runs when it reads a brief:
 
-**Companion corpora (whole-language references).** When §6b produced `{corpus_seeds}` (`{N}` ≥ 1), add them as the brief's `doc_urls` so the language's prose is fetched and assembled alongside the code:
-
-```yaml
-doc_urls:
-  - { url: '{seed.url}', label: '{seed.label}', source: '{seed.source}' }   # one entry per §6b seed; source is 'language-registry'
+```bash
+uv run {writeSkillBriefHelper} write --target "{run_dir}/briefs/{skill_name}/skill-brief.yaml" --from-flat < "{run_dir}/brief-{skill_name}.json"
+uv run {validateBriefSchemaHelper} "{run_dir}/briefs/{skill_name}/skill-brief.yaml"
 ```
 
-These are the brief's *existing* `doc_urls`; brief-skill's README detection then merges additional discovered docs on top (existing entries win). **When `{N}` is 0, omit the `doc_urls` key entirely** — the schema requires at least one entry when the key is present.
-
-**When decomposition is active (N > 1 units):**
-
-Loop over all N boundaries. For each boundary:
-- `name` is the boundary-derived skill name (e.g., `my-monorepo-core`)
-- `include`/`exclude` patterns are boundary-scoped (from §5a)
-- `scope.notes` includes decomposition context: "Decomposed from {project_name} ({N} skills) — boundary {i}/{N}: {boundary_description}"
-- `description` references the parent project and boundary role (e.g., "Core library package of the my-monorepo project, providing...")
-- All N briefs share the same `version`, `source_repo`, `language`, `forge_tier`, `created`, `created_by` values as the parent project
+When the writer exits non-zero or the validator answers `valid: false`, the brief is rejected: HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `step-auto-scope:8`, path `{forge_data_folder}/{skill_name}/skill-brief.yaml`): "The brief for {skill_name} was rejected: {the writer's `message` and `field`, or each `errors[].message` of the validator}." No brief reaches `{forge_data_folder}` then, so the run never reports a brief that does not validate.
 
-**Version detection:** Attempt to auto-detect the source version per the version detection rules in `{briefSchemaPath}`. Fall back to `1.0.0` if detection fails.
+**Then write each brief** to its place, from the same context (the writer renders the same bytes, creates the folder and writes atomically):
 
-**Pin data (from §0b):** When `{pinned_ref}` is non-null, enrich the brief with pin data:
-
-- If `{pinned_ref_type}` is `"tag"`: set `target_version` = `{pinned_version}`, `target_ref` = `{pinned_ref}`, `version` = `{pinned_version}`.
-- If `{pinned_ref_type}` is `"branch"`: set `target_ref` = `{pinned_ref}`, leave `target_version` = null, `version` = auto-detected or `1.0.0`.
-- If `{pinned_ref_type}` is `"local"`: set `target_version` = `{pinned_version}`, `target_ref` = null, `version` = `{pinned_version}`.
-
-When `{pinned_ref}` is null (no pin, no releases): leave `target_version` = null, `target_ref` = null — existing version detection applies unchanged.
+```bash
+uv run {writeSkillBriefHelper} write --target "{forge_data_folder}/{skill_name}/skill-brief.yaml" --from-flat < "{run_dir}/brief-{skill_name}.json"
+```
 
-In the docs-only path (`references/auto-docs-only.md`), `--pin` is ignored (already skipped at §0b). No changes to that path.
+Keep each `brief_path` it prints for §9. If it exits non-zero, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `step-auto-scope:8`, path `{forge_data_folder}/{skill_name}/skill-brief.yaml`, with `unit_counts` and the `brief_paths` written so far): "The brief for {skill_name} could not be written: {its `message`}."
 
-### 9. Emit Result Envelope
+### 9. End the Run
 
-Emit the `SKF_ANALYZE_RESULT_JSON` envelope on stdout:
+The shared emitter writes the result files and prints the envelope; this section stages their content, in every mode. After §8, write `{run_dir}/result-context.json` (a redirect or a skip from §0c has already written its own and comes here directly):
 
-```
-SKF_ANALYZE_RESULT_JSON: {"status":"success","report_path":"{outputFile_path}","brief_paths":["{brief_path_1}","{brief_path_2}",...,"{brief_path_N}"],"unit_counts":{"confirmed":N,"skipped":0,"maybe":0},"exit_code":0,"halt_reason":null,"mode":"auto"}
+```json
+{
+  "status": "success",
+  "report_path": "{outputFile as an absolute path}",
+  "brief_paths": ["{the brief_path of each brief §8 wrote}"],
+  "unit_counts": {"confirmed": <N>, "skipped": 0, "maybe": 0},
+  "mode": "auto",
+  "result_contract": {
+    "skill": "skf-analyze-source",
+    "status": "success",
+    "outputs": [{"type": "report", "path": "{outputFile as an absolute path}"}, {"type": "brief", "path": "{each brief_path}"}],
+    "summary": {"mode": "auto", "shape": "{shape}", "brief_count": <N>, "units": ["{each skill_name}"]}
+  }
+}
 ```
 
-`brief_paths` contains N paths (one per confirmed unit). `unit_counts.confirmed` is N.
+Add `"coexistence": "alongside"` when `{coexistence_suffix}` is non-empty ([A]longside was selected in §0c), `"pinned_ref": "{pinned_ref}"` when `{pinned_ref}` is non-null, and `"pinned_version": "{pinned_version}"` when `{pinned_version}` is non-null (a branch pin, or a latest release whose tag is not a version, has none): these flow downstream to BS/CS for provenance recording. Put the same pin fields in `summary`. Then run:
 
-If `{coexistence_suffix}` is non-empty (i.e., [A]longside was selected in §0c), include `"coexistence":"alongside"` in the envelope.
-
-When `{pinned_ref}` is non-null, include `"pinned_ref":"{pinned_ref}"` and `"pinned_version":"{pinned_version}"` in the envelope. These flow downstream to BS/CS for provenance recording. When `{pinned_ref}` is null, omit these fields.
-
-### 10. Write Result Contract
-
-Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_data_folder}/analyze-source-result-latest.json`. `outputs` lists all N brief paths and `summary` includes the brief count N. If the per-run record cannot be written, HARD HALT with exit code 4 (`write-failed`) per `references/headless-contract.md`.
+```bash
+uv run {emitEnvelopeHelper} emit --workflow skf-analyze-source --run-dir "{run_dir}" --result-dir "{forge_data_folder}" < "{run_dir}/result-context.json"
+```
 
-If `{onCompleteCommand}` is non-empty, invoke it now with `--result-path={result_json_path}`.
+The emitter stamps the UTC time, the run id and the decisions and warnings the run recorded into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout (field rules in `references/headless-contract.md`). When `{headless_mode}` is true, display the line verbatim. A result file that could not be written leaves the line's `result_path` null and a `result_file_write_failed` warning in it, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `step-auto-scope:9`, path `{forge_data_folder}`): "The result contract could not be written: {its message}."
 
-### 11. Chain to Health Check
+If `{onCompleteCommand}` is non-empty and the line's `result_path` is not null, invoke it now: `{onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json`. Display a hook failure; it never fails the run.
 
-Load, read fully, then execute {nextStepFile} to run the shared workflow health check.
+Then delete the run folder, whose payloads the emitter has read: `rm -rf "{run_dir}"`. Load, read fully, then execute {nextStepFile} to run the shared workflow health check.