bmad-module-skill-forge 1.9.0 → 2.0.1

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

@@ -1,7 +1,24 @@
 ---
 nextStepFile: 'health-check.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-shapeDetectScript: 'src/shared/scripts/skf-shape-detect.py'
+shapeDetectProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-shape-detect.py'
+  - '{project-root}/src/shared/scripts/skf-shape-detect.py'
+validatePinsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-pins.py'
+  - '{project-root}/src/shared/scripts/skf-validate-pins.py'
+skillInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
+scanManifestsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-scan-manifests.py'
+  - '{project-root}/src/shared/scripts/skf-scan-manifests.py'
+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'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -33,7 +50,7 @@ Apply the following heuristic to classify the input:
 | `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 | §0a (docs-only) |
+| 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) |
 
 Store the classification result (documentation URL vs. repo/local/other). For all input types, continue to §0b (Pin Resolution).
@@ -48,23 +65,24 @@ This section validates and resolves version pins. It runs for repo URLs and loca
 
 **For repo URLs when `--pin` is provided:**
 
+**Resolve `{validatePinsHelper}`** from `{validatePinsProbeOrder}`; first existing path wins; HALT if neither resolves.
+
 ```bash
-uv run python src/shared/scripts/skf-validate-pins.py --repo-url {project_path} --pin {pin_value}
+uv run {validatePinsHelper} --repo-url {project_path} --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 error envelope:
-  ```
-  SKF_ANALYZE_RESULT_JSON: {"status":"error","report_path":null,"brief_paths":[],"unit_counts":{"confirmed":0,"skipped":0,"maybe":0},"exit_code":3,"halt_reason":"pin-invalid","mode":"auto"}
-  ```
-- **Exit 2** (error): HARD HALT with exit code 3 (`resolution-failure`). Emit error envelope with `halt_reason: "resolution-failure"`.
+- **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"`.
+
+**For repo URLs when `--pin` is not provided (default):**
 
-**For repo URLs when `--pin` is NOT provided (default):**
+Using the same `{validatePinsHelper}` resolved above:
 
 ```bash
-uv run python src/shared/scripts/skf-validate-pins.py --repo-url {project_path}
+uv run {validatePinsHelper} --repo-url {project_path}
 ```
 
 Handle exit codes:
@@ -79,32 +97,37 @@ This section checks for existing skills matching the target before proceeding. I
 
 **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:
+
 ```bash
-uv run python src/shared/scripts/skf-skill-inventory.py {skills_output_folder}
+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 to the next section: §0a 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 continue: load, read fully, then execute `references/auto-docs-only.md` for documentation URLs; §1 for all other input types.
 
-**2. Match target against existing skills:**
+**2. Read the match set:**
 
-For each skill in the inventory, check two match conditions (either triggers a hit):
+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:
 
-- **URL match:** Normalize both the target URL/path and the skill's `metadata.source_repo` — strip scheme (`http://`, `https://`), strip trailing `.git`, strip trailing `/`, compare case-insensitively. A match on the normalized values is a hit.
-- **Name match:** Derive the expected skill name from the target (same logic as §6 for repo URLs, §0a for doc URLs — kebab-case from the project/domain name), then compare against each skill's `name`.
+```json
+{ "name": "...", "active_version": "...", "source_repo": "...", "active_path": "...", "match_reason": "url" | "name" | "both" }
+```
 
-**3. If zero matches:**
+**3. If `matches[]` is empty:**
 
-Complete silently. Continue to §0a for documentation URLs, §1 for all other input types. No user output.
+Complete silently. Continue: execute `references/auto-docs-only.md` for documentation URLs; §1 for all other input types. No user output.
 
-**4. If one or more matches — coexistence gate:**
+**4. If `matches[]` has one or more entries — coexistence gate:**
 
-Present the user with the coexistence decision:
+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`):
 
 ```
 ⚠️ Existing skill(s) found for {target_name}:
 
   • {skill_name} (v{version}) — source: {source_repo}
-  [repeat for each match]
+  [repeat for each entry in matches[]]
 
 Actions:
   [A]longside — Create a new wiki skill with "-wiki" suffix (existing skill untouched)
@@ -118,201 +141,160 @@ In headless mode (`{headless_mode}` is true): auto-select `[A]longside` and log:
 
 **5. Handle user selection:**
 
-- **[A]longside:** Set `{coexistence_suffix}` to `-wiki`. Continue to §0a for documentation URLs, §1 for all other input types. The existing skill is untouched.
+- **[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 multiple skills match, prompt the user to select which one to merge into before proceeding. Emit a redirect envelope signaling the forger to route to the US workflow for the selected skill:
+- **[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 §0a or §1.**
+  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 §0a or §1.**
-
-### 0a. Docs-Only Short-Circuit
+  Chain to {nextStepFile} (health-check.md). **STOP HERE — do not proceed to the docs-only sub-flow or §1.**
 
-This section handles documentation URLs that are not GitHub repos or local paths. It validates the URL, writes a minimal brief and analysis report, emits the envelope, and chains directly to health-check — skipping §1 through §11 entirely.
+### 1. Load Context
 
-**1. Validate URL reachability:**
+Read {outputFile} frontmatter to obtain:
+- `project_paths[]` — the root(s) to analyze
+- `forge_tier` — for brief generation
+- `project_name`, `user_name`, `date`
 
-```bash
-curl -sI --max-time 5 {url}
-```
+Load `references/step-shape-detect.md` as reference for shape detection invocation contract and shape→scope mapping.
 
-- On **2xx/3xx** response: URL is reachable. Continue.
-- On **4xx/5xx**, DNS failure, or timeout: HARD HALT with exit code 3 (`resolution-failure`). Emit error message: `"Documentation URL unreachable: {url} — {status or error}"`. Emit error envelope:
-  ```
-  SKF_ANALYZE_RESULT_JSON: {"status":"error","report_path":null,"brief_paths":[],"unit_counts":{"confirmed":0,"skipped":0,"maybe":0},"exit_code":3,"halt_reason":"path-invalid","mode":"auto","source_type":"docs-only"}
-  ```
+### 2. Manifest Scan
 
-**2. Derive skill name from URL domain:**
+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:
 
-Extract the hostname from the URL (e.g., `docs.example.com` from `https://docs.example.com/guide/intro`), convert to kebab-case (replace `.` with `-`), yielding e.g. `docs-example-com`. If `{coexistence_suffix}` is non-empty, append it to the skill name (e.g., `docs-example-com-wiki`).
+**For each path in `project_paths[]`:**
 
-**3. Write analysis report:**
+- **Local filesystem path** (starts with `/`, `./`, `~/`, `~`, or is an existing directory) — scan it directly:
 
-Update {outputFile} with docs-only results.
+  ```bash
+  uv run {scanManifestsHelper} scan {path}
+  ```
 
-**Update frontmatter:**
-```yaml
-stepsCompleted: ['init', 'auto-scope']
-lastStep: 'auto-scope'
-source_type: docs-only
-confirmed_units:
-  - name: '{skill_name}'
-    shape: 'docs-only'
-    confidence: 1.0
-    export_count: 0
-    package_count: 0
-```
+- **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:
 
-**Append body section:**
-```markdown
-## Auto-Scope Analysis
+  ```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"
+  ```
 
-**Mode:** auto (docs-only short-circuit)
-**Source Type:** docs-only
-**Documentation URL:** {url}
-**Skill Name:** {skill_name}
-```
+  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.
+
+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.
+
+**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):
+
+- **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#^\./##')"
+  ```
 
-**4. Write skill brief via canonical writer:**
+Record `<grammar_matches>` and `<tree_paths>` (each a comma-joined list, possibly empty) for §3.
 
-Create directory `{forge_data_folder}/{skill_name}/` if it does not exist.
+**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`.
 
-Write `{forge_data_folder}/{skill_name}/skill-brief.yaml` through the canonical writer (`skf-write-skill-brief.py`) with the following context:
+### 3. Invoke Shape Detection
 
-```json
-{
-  "name":             "{skill_name}",
-  "target_version":   null,
-  "detected_version": null,
-  "source_type":      "docs-only",
-  "source_repo":      "{url}",
-  "language":         "",
-  "description":      "Skill created from documentation at {url}",
-  "forge_tier":       "{forge_tier}",
-  "created":          "{current_date}",
-  "created_by":       "{user_name}",
-  "scope_type":       "docs-only",
-  "scope_include":    [],
-  "scope_exclude":    [],
-  "scope_notes":      "Docs-only skill created from documentation URL",
-  "scope_rationale":  null,
-  "scope_tier_a_include": null,
-  "scope_amendments":     null,
-  "doc_urls":         [{"url": "{url}", "label": "Primary Documentation"}],
-  "scripts_intent":   null,
-  "assets_intent":    null,
-  "source_authority": "community",
-  "target_ref":       null,
-  "source_ref":       null,
-  "version_resolved": "1.0.0"
-}
-```
+**Resolve `{shapeDetectHelper}`** from `{shapeDetectProbeOrder}`; first existing path wins; HALT if neither resolves.
 
-**5. Emit success envelope:**
+Invoke the shape detection script with the discovered manifests and the harvested tree-level signals:
 
 ```
-SKF_ANALYZE_RESULT_JSON: {"status":"success","report_path":"{outputFile_path}","brief_paths":["{brief_path}"],"unit_counts":{"confirmed":1,"skipped":0,"maybe":0},"exit_code":0,"halt_reason":null,"mode":"auto","source_type":"docs-only"}
+uv run {shapeDetectHelper} --repo-url <project_path_or_url> \
+  --manifests <comma_separated_manifest_paths> \
+  --grammar-files <grammar_matches> --tree-paths <tree_paths>
 ```
 
-If `{coexistence_suffix}` is non-empty (i.e., [A]longside was selected in §0c), include `"coexistence":"alongside"` in the envelope.
-
-The `source_type` field signals downstream consumers (BS) to skip repo-based enrichment.
-
-**6. Write result contract** per `shared/references/output-contract-schema.md`: the per-run record and latest copy, same as §10.
-
-If `{onCompleteCommand}` is non-empty, invoke it now with `--result-path={result_json_path}`.
-
-**7. Chain to health check:**
-
-Load, read fully, then execute {nextStepFile} to run the shared workflow health check. **Skip §1 through §11 entirely.**
-
-### 1. Load Context
+`<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}`
 
-Read {outputFile} frontmatter to obtain:
-- `project_paths[]` — the root(s) to analyze
-- `forge_tier` — for brief generation
-- `project_name`, `user_name`, `date`
-
-Load `references/step-shape-detect.md` as reference for shape detection invocation contract and shape→scope mapping.
-
-### 2. Manifest Scan
-
-Perform a lightweight manifest scan — find standard package manifests in the project root and workspace paths. Do NOT crawl the full directory tree.
+**Handle exit codes:**
 
-**For each path in `project_paths[]`:**
+- **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"`.
 
-1. Check the project root for: `package.json`, `pyproject.toml`, `Cargo.toml`
-2. If a workspace configuration exists (e.g., `pnpm-workspace.yaml`, Cargo.toml `[workspace].members`), scan workspace member paths for additional manifests
-3. Record each discovered manifest as `{path, type}` pairs
+### 3a. Check Decomposition Thresholds
 
-**IF no manifests found:**
-- Emit fallback message: "**Auto-scope could not find any package manifests — switching to interactive mode.**"
-- Load, read fully, then execute `references/scan-project.md`. **STOP HERE.**
+Evaluate the shape detection output to determine whether this **monorepo** should be decomposed into multiple skills.
 
-### 3. Invoke Shape Detection
+Apply the **Decomposition Thresholds** ladder from `step-shape-detect.md` (loaded at §1). A *single* package with a large API surface is **not** a trigger — only a genuine multi-package monorepo is.
 
-Invoke the shape detection script with discovered manifests:
+**Decision:**
 
-```
-uv run python {shapeDetectScript} --repo-url <project_path_or_url> --manifests <comma_separated_manifest_paths>
-```
+- **Threshold not met** (`package_count ≤ 3`) → Continue to §4 (single-scope flow, entirely unchanged).
+- **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)".
 
-Parse the JSON output: `{shape, signals, confidence, export_count, package_count}`
+### 3b. Cohesion Check — Merge to One Skill vs Split into N
 
-**Handle exit codes:**
+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:
 
-- **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:
-  ```
-  SKF_ANALYZE_RESULT_JSON: {"status":"error","report_path":null,"brief_paths":[],"unit_counts":{"confirmed":0,"skipped":0,"maybe":0},"exit_code":3,"halt_reason":"resolution-failure","mode":"auto"}
-  ```
+**Merge into ONE cohesive skill** (override the threshold → continue to §4 single-scope) when **any** of these hold:
 
-### 3a. Check Decomposition Thresholds
+- **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.
 
-Evaluate the shape detection output to determine whether this repo should be decomposed into multiple skills.
+**Split into N skills** (→ §4a) when:
 
-**Threshold conditions** (both constants are `[PENDING VALIDATION]` — subject to empirical tuning):
+- 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.
 
-| Threshold | Condition | Signal |
-|-----------|-----------|--------|
-| Large export surface | `export_count > 500` `[PENDING VALIDATION]` | Single skill covering 500+ exports produces unwieldy output |
-| Monorepo / multi-package | `package_count > 3` `[PENDING VALIDATION]` | 4+ packages are almost always multi-concern |
+If genuinely unsure, **prefer merge** — a too-broad single skill is recoverable with `US`; N fragmented skills are not.
 
-**Decision:**
+**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:
 
-- **Neither threshold met** → Continue to §4 (single-scope flow, entirely unchanged).
-- **Either or both thresholds met** → Route to §4a (multi-scope decomposition flow). Log: "Auto-decomposition triggered: {reason} ({value} exceeds threshold {threshold} `[PENDING VALIDATION]`)" where reason is `export_threshold`, `package_threshold`, or `both`.
+- 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 shape→scope.type mapping:
-
-| Shape (from skf-shape-detect.py) | scope.type | Condition |
-|----------------------------------|------------|-----------|
-| `library-API` | `full-library` | export_count ≤ 200 |
-| `library-API` | `public-api` | export_count > 200 |
-| `reference-app` | `reference-app` | — |
-| `language-reference` | `full-library` | — |
-| `stack-compose` | `full-library` | Multi-scope via §3a when `package_count > 3` `[PENDING VALIDATION]` |
+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).
 
 ### 5. Generate Include/Exclude Patterns
 
 Generate `scope.include` and `scope.exclude` arrays from the detected language and project structure.
 
-**Detect primary language** from manifest type:
-- `package.json` → TypeScript/JavaScript
-- `pyproject.toml` → Python
-- `Cargo.toml` → Rust
-- `go.mod` → Go
+**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:
+
+```bash
+echo '{"tree": [<§2 supported manifest paths + harvested tree paths>]}' | uv run {detectLanguageHelper}
+```
+
+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):**
 
@@ -321,6 +303,10 @@ Generate `scope.include` and `scope.exclude` arrays from the detected language a
 | 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.
 
@@ -332,41 +318,53 @@ scope:
   type: '{mapped_scope_type}'
   include: ['{generated_include_patterns}']
   exclude: ['{generated_exclude_patterns}']
-  notes: 'Auto-scoped from shape detection (shape: {shape}, confidence: {confidence})'
+  notes: 'Auto-scoped from shape detection (shape: {shape}, confidence: {confidence}).{corpus_caveat}'
 ```
 
 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.
 
-Detect the primary language from the manifest ecosystem:
-- `npm` → `typescript` (or `javascript` if no `.ts` files in includes)
-- `python` → `python`
-- `rust` → `rust`
+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).
 
-### 4a. Multi-Scope Decomposition
+### 6b. Seed Companion Corpora (whole-language references only)
 
-This section is reached only from §3a when one or both decomposition thresholds are met. It replaces §4→§5→§6 for repos that will produce N > 1 skills.
+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.
 
-**Determine decomposition path:**
+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.
 
-- **Monorepo path** (`package_count > 3`): 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.
-- **Large-export path** (`export_count > 500`, single package): Group by top-level source directory modules (e.g., `src/auth/`, `src/core/`, `src/api/`). Each directory subtree with a meaningful export surface becomes a separate skill boundary. Candidate boundaries with fewer than ~50 exports `[PENDING VALIDATION]` should be merged into an "other" catch-all skill rather than becoming standalone skills. Name each skill as `{project_name}-{module_name}` (kebab-case); if `{coexistence_suffix}` is non-empty, append it. If no clear module structure exists (flat `src/` with all files at root level), **do not force decomposition** — fall back to single-scope flow at §4.
-- **Combined path** (both thresholds met): Use the monorepo path. Package boundaries are explicit and take priority over export-count grouping (which is heuristic).
+**Resolve `{detectLanguageHelper}`** from `{detectLanguageProbeOrder}` and **`{languageCorporaHelper}`** from `{languageCorporaProbeOrder}` (first existing path wins).
 
-**Per-boundary shape→scope mapping:**
+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.
 
-For each decomposed boundary, apply the shape→scope mapping from §4 independently — the boundary's local characteristics determine its scope.type:
+### 4a. Multi-Scope Decomposition
 
-| Decomposition Type | Per-Boundary Shape Mapping |
-|--------------------|---------------------------|
-| Monorepo (`package_count > 3`) | 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). |
-| Large-export (`export_count > 500`) | All boundaries inherit the parent shape. scope.type varies by per-boundary export count (e.g., ≤200 → `full-library`, >200 → `public-api`). |
+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.
 
-### 5a. Generate Multi-Scope Patterns
+**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.
+
+**Per-boundary shape→scope mapping:**
+
+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).
 
-For each decomposed boundary, generate include/exclude patterns using the same language-aware rules as §5, but scoped to the boundary's source paths.
+### 5a. Generate Multi-Scope Patterns
 
-- Monorepo boundaries: patterns are rooted at the package path (e.g., `packages/auth/src/**/*.ts` instead of `src/**/*.ts`)
-- Large-export boundaries: patterns are rooted at the module directory (e.g., `src/auth/**/*.ts`)
+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`).
 
 ### 6a. Build Multi-Scope
 
@@ -382,7 +380,7 @@ After building all N scopes, continue to §7 with the full set of boundaries.
 
 ### 7. Write Analysis Report
 
-Update {outputFile} with auto-scope results.
+Update {outputFile} with auto-scope results. If the write fails, HARD HALT with exit code 4 (`write-failed`) per `references/headless-contract.md`.
 
 **Update frontmatter:**
 ```yaml
@@ -404,11 +402,11 @@ Add `decomposition` to frontmatter:
 ```yaml
 decomposition:
   triggered: true
-  reason: 'export_threshold' | 'package_threshold' | 'both'
+  reason: 'package_threshold'
   boundary_count: N
 ```
 
-Each `confirmed_units` entry includes `boundary_path` — the relative path to the boundary's root (e.g., `packages/core` for monorepo, `src/auth` for large-export). Omit the `decomposition` key entirely when single-scope (N = 1).
+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).
 
@@ -428,6 +426,17 @@ 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:
+
+```markdown
+## Companion Corpora (language-reference)
+
+**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)
@@ -453,9 +462,9 @@ For multi-scope (N > 1):
 
 **For each confirmed unit** (1 for single-scope, N for decomposition):
 
-Create directory `{forge_data_folder}/{skill_name}/` if it does not exist.
+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`.
 
-Write `{forge_data_folder}/{skill_name}/skill-brief.yaml` conforming to the skill-brief schema (`assets/skill-brief-schema.md`):
+Write `{forge_data_folder}/{skill_name}/skill-brief.yaml` conforming to the skill-brief schema (`{briefSchemaPath}`):
 
 ```yaml
 name: '{skill_name}'
@@ -468,13 +477,22 @@ scope:
     - '{include_patterns}'
   exclude:
     - '{exclude_patterns}'
-  notes: 'Auto-scoped from shape detection (shape: {shape}, confidence: {confidence})'
+  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}'
 ```
 
+**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'
+```
+
+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:
@@ -484,7 +502,7 @@ Loop over all N boundaries. For each boundary:
 - `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
 
-**Version detection:** Attempt to auto-detect the source version per the version detection rules in `assets/skill-brief-schema.md`. Fall back to `1.0.0` if detection fails.
+**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.
 
 **Pin data (from §0b):** When `{pinned_ref}` is non-null, enrich the brief with pin data:
 
@@ -494,7 +512,7 @@ Loop over all N boundaries. For each boundary:
 
 When `{pinned_ref}` is null (no pin, no releases): leave `target_version` = null, `target_ref` = null — existing version detection applies unchanged.
 
-In the docs-only path (§0a), `--pin` is ignored (already skipped at §0b). No changes to §0a.
+In the docs-only path (`references/auto-docs-only.md`), `--pin` is ignored (already skipped at §0b). No changes to that path.
 
 ### 9. Emit Result Envelope
 
@@ -504,22 +522,18 @@ Emit the `SKF_ANALYZE_RESULT_JSON` envelope on stdout:
 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"}
 ```
 
-`brief_paths` contains N paths (one per confirmed unit). `unit_counts.confirmed` is N. The envelope JSON format is structurally unchanged — `brief_paths` was already an array and `unit_counts.confirmed` was already a number. No breaking change for downstream consumers.
+`brief_paths` contains N paths (one per confirmed unit). `unit_counts.confirmed` is N.
 
 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 (backward-compatible — existing consumers don't expect them).
+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.
+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`.
 
 If `{onCompleteCommand}` is non-empty, invoke it now with `--result-path={result_json_path}`.
 
 ### 11. Chain to Health Check
 
 Load, read fully, then execute {nextStepFile} to run the shared workflow health check.
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the analysis report has been updated, the skill-brief.yaml written and validated, the result envelope emitted, and the result contract saved will you load and read fully {nextStepFile} to begin the health check.