bmad-module-skill-forge 2.1.0 → 3.0.0

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

@@ -1,10 +1,14 @@
 ---
 nextStepFile: 'identify-units.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-heuristicsFile: '{unitDetectionHeuristicsPath}'
+heuristicsFile: 'references/unit-detection-heuristics.md'
+scanRootFile: 'references/scan-root.md'
 scanManifestsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-scan-manifests.py'
   - '{project-root}/src/shared/scripts/skf-scan-manifests.py'
+detectWorkspacesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-workspaces.py'
+  - '{project-root}/src/shared/scripts/skf-detect-workspaces.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -13,71 +17,75 @@ scanManifestsProbeOrder:
 
 ## STEP GOAL:
 
-To map the complete project structure by scanning directory trees, detecting service boundaries, identifying package manifests, and cataloging entry points — building the foundation that subsequent steps use for unit identification.
+To map each project path's structure from its file list, its package manifests and its workspace layout, which the helpers read, and to list the candidate boundaries that subsequent steps use for unit identification.
 
 ## Rules
 
 - Focus only on structural scanning — do not classify units or map exports yet
-- Do not read source file contents beyond manifest files and entry points
-- Delegate per-file scanning to subagents in parallel when many files are involved (main-thread fallback is fine)
-- Tier-aware scanning depth: Quick (file structure), Forge (+ manifest parsing), Deep (+ config analysis)
+- Read no file contents: the helpers read the manifests
 
 ## 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": "interactive", "report_path": "{outputFile as an absolute path}"}`, 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.
+
 ### 1. Load Context
 
 Read {outputFile} frontmatter to obtain:
-- `project_paths[]` — the root(s) to scan (one or more paths/URLs)
-- `constituent_refs` — optional per-path git ref overrides (present only when `project_paths` has multiple entries and explicit refs were supplied via `--target-refs`)
-- `forge_tier` — determines scanning depth
-- Scope hints (if any were provided in step 01)
+- `project_paths[]`: the root(s) to scan (one or more paths/URLs)
+- `refs`: each project path's ref (a path it leaves out has none)
+- `scope_hint`: the folders or packages to focus on or skip (may be empty)
 
 Load {heuristicsFile} for reference on detection signals.
 
 ### 2. Scan Directory Structure
 
-**Resolve `{scanManifestsHelper}`** from `{scanManifestsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+**Resolve `{scanManifestsHelper}`** from `{scanManifestsProbeOrder}` and **`{detectWorkspacesHelper}`** from `{detectWorkspacesProbeOrder}`; first existing path wins for each. If one has no candidate, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `scan-project:2`): "`{the missing script}` is missing. Re-install SKF."
 
-**For each path in `project_paths[]`**, resolve the constituent ref (if any) and launch a subprocess that scans the project directory structure (aggregate results across all repos with clear repo-level grouping):
+**The scan root of each project path.** Every helper from here on reads a local folder, the path's **scan root**, which §6 records in `scan_roots` so the later steps read the same files. Load {scanRootFile} and make the scan root of each entry of `project_paths[]` as it says. If a command there fails, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `scan-project:2`, path `{path}`): "{path} could not be fetched: {the first stderr line}."
 
-**Per-path ref resolution:** If `constituent_refs` is present and contains an entry for the current path, use that ref. For remote paths, this means cloning or fetching at the specified ref (`git clone --branch {ref} --depth 1` or `git show {ref}:<subpath>` for off-HEAD access). For local paths with a non-HEAD ref, check out or read from the specified ref using `git show {ref}:<path>`. When no `constituent_refs` entry exists for a path, use default ref resolution (HEAD for local, latest tag or HEAD for remote).
+**For each path in `project_paths[]`**, the `{i}`-th, scan its scan root with the helpers, never by walking its tree yourself (aggregate the results across all repos, grouped by project path):
 
-1. Map the top-level directory tree (2-3 levels deep)
-2. Identify workspace configuration files (pnpm-workspace.yaml, lerna.json, Cargo.toml [workspace], go.work, etc.)
-3. Enumerate package manifests deterministically — invoke `uv run {scanManifestsHelper} scan {path}` and parse the JSON envelope. The script returns `{manifests[], total_unique, monorepo, warnings?}` covering npm/python/rust/go/maven/gradle/ruby/composer/swift; record each `{path, ecosystem}` for the manifests catalog in §4 and capture `monorepo` for the boundary-signal pass in §3
-4. Locate entry point files (index.ts, main.ts, app.ts, main.go, main.rs, __init__.py, etc.)
-5. Detect service configuration (Dockerfile, docker-compose.yml, kubernetes manifests, serverless.yml) — keep this step LLM-driven; file glob + presence check is sufficient, no parsing required
-6. Return structured findings — file paths and types only, not contents. When `constituent_refs` was used, include the resolved ref in each repo-level result group: `{path, ref, manifests[], monorepo, warnings?}`
+1. List its files once. For a scan root inside a git work tree (`git -C "{scan_root}" rev-parse --is-inside-work-tree` prints `true`) run the first command, which lists the tracked files and the untracked ones git does not ignore, as `skf-disqualify-candidates.py` lists a boundary's files. Run the second for any other folder, and when the first fails or writes an empty file (a folder that an outer work tree ignores). If neither lists a file, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `scan-project:2`, path `{path}`): "The files of {path} could not be listed: {the first stderr line}."
 
-**If subprocess unavailable:** Perform directory scanning in main thread using file I/O tools.
+   ```bash
+   git -C "{scan_root}" -c core.quotePath=false ls-files --cached --others --exclude-standard > "{run_dir}/tree-{i}.txt"
+   (cd "{scan_root}" && find . -type f -not -path '*/.git/*' | sed 's#^\./##') > "{run_dir}/tree-{i}.txt"
+   ```
 
-**Apply scope hints if provided:**
-- If specific directories were given, scan only those
-- If exclusion patterns were given, skip matching directories
+2. Take the structure overview and the workspace layout from the tree snapshot, which counts the listing so you never do:
 
-**Deep tier additional scanning (IF Deep tier):**
-- Use ast-grep to detect structural patterns across the codebase: `ast-grep -p 'class $NAME' --lang python` (or equivalent per language) to build a class/type inventory
-- Use ast-grep to identify exported function patterns: `ast-grep -p 'def $FUNC($$$PARAMS)' --lang python` at entry points
-- If QMD is available, query for temporal context on the project: recent changes, active development areas, refactoring patterns
-- Record Deep-tier findings separately — they supplement (not replace) the Quick/Forge scan results
+   ```bash
+   uv run {detectWorkspacesHelper} --tree-file "{run_dir}/tree-{i}.txt" --manifest-dir "{scan_root}" --snapshot > "{run_dir}/snapshot-{i}.json"
+   ```
 
-### 3. Detect Service Boundaries
+   It holds `file_count`, `dir_count`, `top_level_files`, `top_level_dirs`, the workspace layout (`manifest_kind`) and its `workspaces` (`{name, path, manifest}` each), and `warnings`.
+3. Enumerate the package manifests and the candidate boundaries, with the snapshot's workspaces:
+
+   ```bash
+   uv run {scanManifestsHelper} scan "{scan_root}" --workspaces-file "{run_dir}/snapshot-{i}.json" > "{run_dir}/manifests-{i}.json"
+   ```
 
-Based on scan results, identify potential service boundaries:
+   The envelope holds `manifests[]` (npm/python/rust/go/maven/gradle/ruby/composer/swift, each with its `path` and `ecosystem`, for the §4 catalog), `monorepo`, `services[]` (each Docker, compose or serverless file, for the §4 catalog: a presence check, no parsing), `candidates[]` (§3) and `warnings`.
 
-**Strong boundary signals:**
-- Independent package manifest (own package.json, Cargo.toml, etc.)
-- Docker/container configuration
-- Separate entry point file
-- Workspace member listing
+Keep, per project path, `{path, ref, scan_root}`, the snapshot's structure overview and the scan's `manifests[]`, `services[]`, `candidates[]`, `monorepo` and `warnings`: §3 to §6 read them.
+
+### 3. Detect Service Boundaries
+
+Each project path's candidate boundaries are its scan's `candidates[]` ({heuristicsFile}'s **Candidate Boundaries**). When `scope_hint` is not empty, keep only the candidates inside the folders or packages it focuses on, and drop those inside the folders it skips. A candidate's signals are reported, never judged: an independent package manifest (its `manifests`), a Docker or service definition (its `services`) and workspace membership (its `workspace_member`). Judge only each candidate's boundary type and confidence.
 
 **Document each detected boundary with:**
-- Path relative to project root
+- The project path it was found under, and its path relative to that path's scan root
 - Boundary type (service / package / module)
 - Detection signals found (list specific files)
 - Confidence level (strong / moderate / weak)
 
-### 4. Catalog Manifests and Entry Points
+### 4. Catalog Manifests and Service Configurations
 
 Create a structured catalog:
 
@@ -86,71 +94,39 @@ Create a structured catalog:
 |------|------|-------------------|
 | {path} | {manifest_type} | {language} |
 
-**Entry points found:**
-| Path | Type |
-|------|------|
-| {path} | {entry_type} |
-
 **Service configurations found:**
 | Path | Type |
 |------|------|
 | {path} | {config_type} |
 
-### 5. Present Scan Results
+### 5. Present the Scan and Confirm
 
-"**Project Scan Complete**
+Show the user, per project path: the structure overview, each detected boundary (path, type, signals, confidence), the §4 catalogs (manifests, service configurations), and the scope applied (`scope_hint`, or "Full project scan"). Then display:
 
-**Project:** {project_path}
-**Forge Tier:** {forge_tier}
+"Anything to rescan, investigate further or skip? Tell me, or **Select:** [C] Continue to Unit Identification | [X] Cancel and exit"
 
-**Structure Overview:**
-{top-level directory tree}
-
-**Detected Boundaries:** {count}
-{list each boundary with path, type, confidence}
-
-**Manifests Found:** {count}
-{summary table}
-
-**Entry Points Found:** {count}
-{summary table}
-
-**Service Configurations:** {count}
-{summary table}
+#### Menu Handling Logic:
 
-**Scope Applied:** {hints or 'Full project scan'}
+- IF C: go to §6
+- IF X: HARD HALT (exit code 6, `halt_reason: "user-cancelled"`, phase `scan-project:5`): "Cancelled at the project scan."
+- IF Any other: rescan or skip as directed, show what changed, then [Redisplay Menu Options](#5-present-the-scan-and-confirm)
 
-Does this scan look complete? Any directories I should investigate further or skip?"
+**GATE [default: C]**: present the menu and wait for the user's choice. If `{headless_mode}`: continue with [C], and record that decision the moment it is taken: stage `{run_dir}/decision.json` as `{"gate": "scan-project.scan", "default_action": "C", "taken_action": "C", "reason": "headless: auto-continue past scan results", "evidence": {"project_paths": <the project path count>, "boundaries": <the boundary count>}}`, then run
 
-Wait for user feedback. If user identifies gaps, rescan as directed.
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-analyze-source --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+```
 
-### 6. Append to Report
+If the command fails, go on: only that entry is lost.
 
-Append the complete "## Project Scan" section to {outputFile}:
+### 6. Append to Report and Continue
 
-Replace the placeholder `[Appended by scan-project]` with the full scan results including:
-- Structure overview
-- Detected boundaries table
-- Manifests catalog
-- Entry points catalog
-- Service configurations catalog
-- Scope notes
+Replace the placeholder `[Appended by scan-project]` in {outputFile} with the scan results: the structure overview, the detected boundaries table, the manifests and service configurations catalogs, and the scope notes, grouped by project path when there are several. Update its frontmatter:
 
-Update {outputFile} frontmatter:
 ```yaml
 stepsCompleted: [append 'scan-project' to existing array]
 lastStep: 'scan-project'
+scan_roots: {each project path: its scan root}
 ```
 
-### 7. Present MENU OPTIONS
-
-Display: "**Select:** [C] Continue to Unit Identification | [X] Cancel and exit"
-
-#### Menu Handling Logic:
-
-- IF C: Save scan results to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
-- IF X: HARD HALT with exit code 6 (`user-cancelled`). Emit the error envelope on stderr with `halt_reason: "user-cancelled"` and counts/paths reflecting state at cancellation (shape in `references/headless-contract.md`)
-- IF Any other: help user, then [Redisplay Menu Options](#7-present-menu-options)
-
-**GATE [default: C]** — present the menu and wait for the user's choice. If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-continue past scan results".
-
+Then load, read the entire file, then execute {nextStepFile}.

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

@@ -0,0 +1,39 @@
+---
+skillInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# The Scan Root of a Project Path
+
+Every helper of the step-by-step analysis reads a local folder, the project path's **scan root**, never `{project-root}` (the forge workspace). scan-project makes one for each entry of `project_paths[]` and records it in the report's `scan_roots`, discover-additional-source makes one for the path it adds, and identify-units and map-and-detect make one again when a session that resumed the report no longer finds it. `{i}` is the path's place in `project_paths[]` (1 for the first), and its **ref** is its entry in the report's `refs` (a path `refs` leaves out has none). In every command below, a leading `~` of a local path is written as `$HOME`: the commands quote every path, and a `~` inside double quotes does not expand.
+
+**What the path is.** The helper that names every unit tells a local path from a repository and gives the URL git clones a repository from. Resolve `{skillInventoryHelper}` from `{skillInventoryProbeOrder}` (first existing path wins; with none, the command below fails with "`skf-skill-inventory.py` is missing. Re-install SKF." as its first stderr line) and run:
+
+```bash
+uv run {skillInventoryHelper} derive-name --target "{path}" --probe-git
+```
+
+Its `kind` is `local` for a local path, `remote` for a repository and `docs` for a documentation URL, and its `clone_url` is the URL git reads for a repository.
+
+- **A local path** (`kind` is `local`) **with no ref:** the path itself. Nothing is copied.
+- **A local path with a ref:** the path's folder inside a copy of its repository at the ref, so a package folder of a monorepo is read at the ref too. Print the repository's top folder and the path's place in it, then copy the top folder:
+
+  ```bash
+  git -C "{path}" rev-parse --show-toplevel --show-prefix
+  git clone --quiet --branch {ref} "{the first line it printed}" "{run_dir}/source-{i}"
+  ```
+
+  The scan root is `{run_dir}/source-{i}/` followed by the second line without its trailing slash, or `{run_dir}/source-{i}` itself when that line is empty (the path is the top folder).
+- **A remote path** (`kind` is `remote`): a copy at its ref, or at the default branch when it has none, which is the scan root:
+
+  ```bash
+  git clone --quiet --depth 1 {ref_flag} "{clone_url}" "{run_dir}/source-{i}"
+  ```
+
+  `{ref_flag}` is `--branch {ref}` when the path has a ref, else nothing. The project path stays as it was given everywhere else: in `project_paths[]`, the keys of `scan_roots` and `refs`, and each brief's `source_repo`.
+- **A documentation URL** (`kind` is `docs`): there is no repository to scan. Treat it as a command that failed with its `halt_message` as the first stderr line when it gives one (the message the [auto] path halts with), else with "{path} is a documentation URL: run the analysis with [auto] for a docs-only brief".
+
+When a command fails, the file that loaded this one says what happens, with the first line it printed on stderr.

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

@@ -0,0 +1,47 @@
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 1a §0c: Coexistence Gate
+
+Loaded by `step-auto-scope.md` when a skill already holds the name or the source this run would forge: from §0c when its `matches[]` has one or more entries, and from §6 when the derived name belongs to a skill from another source, which §6 passes as the one `matches[]` entry. Each entry is `{name, active_version, source_repo, active_path, match_reason, skf_skill}`; `skf_skill` is true when SKF generated the matched skill. 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.
+
+## MANDATORY SEQUENCE
+
+### 4. Present the 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`). Append " (not SKF output, merge not offered)" to the bullet of every entry whose `matches[].skf_skill` is false, and leave the `[M]erge` line out when no entry has `matches[].skf_skill` true:
+
+```
+⚠️ 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; SKF-generated skills only)
+  [S]kip:      Do not create or modify any skill for this library
+
+Choose [A/M/S]:
+```
+
+**GATE [default: A]**: in headless mode (`{headless_mode}` is true), auto-select `[A]longside` and log: "Headless: coexistence detected for {target_name}, auto-selecting [A]longside". The envelope's `coexistence` field carries the choice.
+
+### 5. Handle the Selection
+
+- **[A]longside:** Set `{coexistence_suffix}` to `-wiki`; the existing skill is untouched. Return to the section that loaded this file: from §0c, continue with `references/auto-docs-only.md` for a documentation URL and with §1 for every other input; from §6, go on with §6.
+
+- **[M]erge:** Offered only for entries whose `matches[].skf_skill` is true. If more than one such entry exists, 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`. End the run as `step-auto-scope.md` §9 says, with a redirect that signals the forger to route to the US workflow for the selected skill: write `{run_dir}/result-context.json` as
+
+  ```json
+  {"status": "redirect", "redirect_to": "US", "skill_name": "{matched_skill_name}", "skill_path": "{matched_active_path}", "mode": "auto", "coexistence": "merge", "result_contract": {"skill": "skf-analyze-source", "status": "redirect", "outputs": [], "summary": {"mode": "auto", "redirect_to": "US", "skill_name": "{matched_skill_name}"}}}
+  ```
+
+  and go to §9 of `step-auto-scope.md`. **STOP HERE: do not proceed to the docs-only sub-flow or §1.**
+
+- **[S]kip:** End the run as `step-auto-scope.md` §9 says, with a skip: write `{run_dir}/result-context.json` as
+
+  ```json
+  {"status": "skipped", "unit_counts": {"confirmed": 0, "skipped": 1, "maybe": 0}, "mode": "auto", "coexistence": "skip", "skipped_reason": "Existing skill for {matched_skill_name}", "result_contract": {"skill": "skf-analyze-source", "status": "skipped", "outputs": [], "summary": {"mode": "auto", "skipped_reason": "Existing skill for {matched_skill_name}"}}}
+  ```
+
+  and go to §9 of `step-auto-scope.md`. **STOP HERE: do not proceed to the docs-only sub-flow or §1.**

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

@@ -0,0 +1,53 @@
+---
+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}. -->
+
+# Step 1a §6b: Seed Companion Corpora (whole-language references only)
+
+Loaded by `step-auto-scope.md` §6 only when §3 classified the repo as `language-reference` **via a whole-language signal**: its `signals` array holds a `grammar_file:` or `tree_triad:` entry (a compiler, interpreter or grammar repo such as rust-lang/rust, TypeScript or CPython). A `language-reference` that fired only from `parser_producer:` or `parser_dep:` signals (a parser *library* such as pest or lalrpop) never loads it: there the code **is** the product, so no companion prose is needed and no caveat applies.
+
+A whole-language skill's value is in the language's **prose** (the guide or Book, the standard and library API docs, idioms), not the compiler internals. Seed those canonical corpora so the forged skill teaches the language rather than its implementation. This file sets `{corpus_seeds}`, `{corpus_caveat}` and the Companion Corpora subsection, then returns to §6. It never halts: the lookup is best-effort.
+
+## MANDATORY SEQUENCE
+
+### 1. Look Up the Canonical Corpora
+
+**Resolve `{languageCorporaHelper}`** from `{languageCorporaProbeOrder}` (first existing path wins). When neither path exists, record the warning `language_corpora_unavailable: skf-language-corpora.py is missing` with `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning '<the warning>'` and treat `{corpus_seeds}` as empty.
+
+1. **The corpus language key `{corpus_language}`** ← `{detected_language}` from §5, which a manifest-less toolchain such as CPython or Ruby gets from its source files.
+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 (a long-tail language), so `{corpus_seeds}` is empty (README detection in brief-skill remains the only source).
+   - exit 2: record the warning `language_corpora_failed: <its first stderr line>` the same way and treat it as empty.
+3. Record `{N}` = the number of seeds and `{corpus_labels}` = their labels, comma-joined.
+
+### 2. Build the Caveat and the Brief's Doc URLs
+
+`{corpus_caveat}`, which §6 appends to `scope.notes`, tells the operator that 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."`
+
+`{corpus_doc_urls}`, which §8 writes as the brief's `doc_urls`: one `{"url": "{seed.url}", "label": "{seed.label}", "source": "{seed.source}"}` per seed (its `source` is `language-registry`), so the language's prose is fetched and assembled alongside the code (brief-skill's README detection then merges more docs on top, existing entries winning); null when `{N}` is 0.
+
+### 3. The Companion Corpora Subsection
+
+§7 appends this to the report, so the operator sees whether the skill has the prose that makes it useful. The status comes 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}
+```
+
+Then return to `step-auto-scope.md` §6.

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

@@ -0,0 +1,91 @@
+---
+skillInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
+detectLanguageProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-language.py'
+  - '{project-root}/src/shared/scripts/skf-detect-language.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 1a §4a: Split a Monorepo into N Skills
+
+Loaded by `step-auto-scope.md` §3b only when its cohesion check decided to **split** a monorepo (members independently published with distinct surfaces, and no umbrella re-exporting them). It replaces §4, §5 and §6 for a repo that produces N > 1 skills, then returns to §7 with the N boundaries. `{run_dir}`, `{scan_root}`, `{pinned_ref}`, `{coexistence_suffix}`, `intent_hint`, `scope_hint` and the §2 records carry into it.
+
+## MANDATORY SEQUENCE
+
+Every HARD HALT in this file 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.
+
+**Resolve `{skillInventoryHelper}`** from `{skillInventoryProbeOrder}` 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-split:0`): "`{the missing script}` is missing. Re-install SKF."
+
+### 4a. Decompose by Workspace Package
+
+Each workspace package of the §2 manifest scan with its own manifest becomes a separate skill boundary; trivial workspace members (no source files, no exports) are excluded, and so is a member outside the folders `scope_hint` focuses on or under a folder it skips. Name the boundaries in one call to the helper that names every brief, one entry per boundary with its manifest `name` and `private` from §2:
+
+```bash
+uv run {skillInventoryHelper} derive-name --from - --skills-folder "{skills_output_folder}" <<'SKF_BOUNDARY_NAMES'
+[{"target": "<boundary path>", "manifest_name": "<its manifest name>", "private": <its private flag>}, ...]
+SKF_BOUNDARY_NAMES
+```
+
+Each boundary's skill name is its `names[].name`: boundaries whose names would clash are already told apart by their parent folders, and the entries `unnamed` and `duplicates` list take a name you give them from their folder. A name whose `existing` is not null belongs to a skill from another source (§0c already offered the ones from this repository): give that boundary the `-wiki` suffix, as [A]longside does, and record it as a warning, so it reaches the envelope:
+
+```bash
+uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning 'coexistence: {name} exists, forging {name}-wiki alongside'
+```
+
+(a single quote in the name written as a backtick; if the command fails, go on). Then append `{coexistence_suffix}` to every name that does not already end with it, when it is non-empty.
+
+**Per-boundary shape to scope mapping:** for each boundary, apply the §4 mapping independently, re-running the shape-to-scope ladder of `step-shape-detect.md` per package with each package's own manifest data. Packages may have different shapes (for example a `library-API` core and a `reference-app` CLI).
+
+### 5a. Generate Multi-Scope Patterns
+
+For boundary `{i}`, list its files, detect its language from them without `--workspace-signal` (the workspace root's language would answer for every boundary) and read it as §5 says, the boundary's own manifest standing for the scan-root manifest. Its include and exclude patterns are the ones `scope-patterns` prints for that language, rooted at the boundary's source folder (`packages/auth/src/**/*.ts`):
+
+```bash
+awk -v p="<boundary path>/" 'index($0, p) == 1' "{run_dir}/tree.txt" > "{run_dir}/tree-{i}.txt"
+uv run {detectLanguageHelper} --tree-file "{run_dir}/tree-{i}.txt"
+uv run {detectLanguageHelper} scope-patterns --tree-file "{run_dir}/tree-{i}.txt" --language <its language>
+```
+
+### 6a. Build Multi-Scope
+
+This is the one statement of what each boundary's brief holds; §8 writes these values and the ones every brief shares (version, `source_repo`, `forge_tier`, `created`, `created_by` and the §0b pin: the pin targets a repo-level ref, not a package-level version). For boundary `{i}` of `{N}`:
+
+- **Name:** the one §4a gave it, suffix included.
+- **Scope:** `scope.type` from its §4a mapping, `scope.include` and `scope.exclude` from §5a, and `scope.notes` ← `Decomposed from {project_name} ({N} skills): boundary {i}/{N}, {boundary role}.`, where `{boundary role}` says in a few words what the boundary is for (for example `core library` or `CLI`).
+- **Language:** the one §5a detected.
+- **Description:** one to three sentences naming the parent project and the boundary's role (for example "Core library package of the my-monorepo project, providing..."), worded toward `intent_hint` when it is not empty.
+
+### 7. The Decomposition Report
+
+§7 writes `decomposition` into the frontmatter and appends this body in place of the single-scope section:
+
+```markdown
+## Auto-Scope Analysis: Decomposition ({N} skills)
+
+**Mode:** auto
+**Decomposition:** {reason} ({N} boundaries)
+**Parent Shape:** {shape} (confidence: {confidence})
+**Export Count:** {export_count}
+**Package Count:** {package_count}
+
+### Boundary 1: {boundary_name}
+**Scope Type:** {scope_type}
+**Boundary Path:** {boundary_path}
+**Include Patterns:** {include patterns}
+**Exclude Patterns:** {exclude patterns}
+**Rationale:** {boundary_rationale}
+
+### Boundary 2: {boundary_name}
+...
+```
+
+After building all N scopes, return to `step-auto-scope.md` §7 with the full set of boundaries.