bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/shared/scripts/skf-write-skill-brief.py

@@ -51,7 +51,10 @@ Context payload shape (consumed by `write`):
     },
 
     # Conditionally present:
-    "doc_urls":         [{"url": "...", "label": "..."}],
+    "doc_urls":         [{"url": "...", "label": "...", "source": "..."}],
+    #   `source` (optional per #432): language-registry | readme-detection |
+    #   homepage | pages-api | docs-folder. Threaded through when present;
+    #   absent → entry renders as {url, label} only (no false drift).
     "scripts_intent":   "detect" | "none" | free-text,
     "assets_intent":    "detect" | "none" | free-text,
     "source_authority": "official" | "community" | "internal",
@@ -95,7 +98,7 @@ Flat input form (`--from-flat`):
     "scope_notes":          "",
     "scope_tier_a_include": null | ["code/core/src/**"],
     "scope_amendments":     null | [{...}],
-    "doc_urls":             null | [...],
+    "doc_urls":             null | [{"url": "...", "label": "...", "source": "..."}],
     "scripts_intent":       null | "detect" | "none" | "...",
     "assets_intent":        null | "detect" | "none" | "...",
     "source_authority":     null | "official" | "community" | "internal",
@@ -433,11 +436,24 @@ def assemble_brief(ctx: dict[str, Any], resolved_version: str) -> dict[str, Any]
             brief[ref_field] = ref_val
 
     # Conditional: doc_urls (always emitted when present)
+    #
+    # Each entry carries the {url, label} contract plus an OPTIONAL `source`
+    # provenance field (issue #432: language-registry | readme-detection |
+    # homepage | pages-api | docs-folder). `source` is emitted ONLY when present
+    # on the input entry — mirroring the source_authority null-drop discipline
+    # below (lines ~448-454): a legacy/hand-authored entry without `source`
+    # round-trips to exactly {url, label}, so a ratify/re-write of an old brief
+    # stays byte-identical. (An explicit empty-string source is treated as
+    # absent here; the schema enum is the real gate and rejects "" upstream.)
     doc_urls = ctx.get("doc_urls")
     if doc_urls:
-        brief["doc_urls"] = [
-            {"url": e["url"], "label": e.get("label", "")} for e in doc_urls
-        ]
+        rendered_doc_urls: list[dict[str, Any]] = []
+        for e in doc_urls:
+            entry = {"url": e["url"], "label": e.get("label", "")}
+            if e.get("source"):
+                entry["source"] = e["source"]
+            rendered_doc_urls.append(entry)
+        brief["doc_urls"] = rendered_doc_urls
 
     # Conditional: scripts_intent / assets_intent — emit when explicitly non-detect
     for intent_field in ("scripts_intent", "assets_intent"):

package/src/skf-analyze-source/SKILL.md

@@ -19,7 +19,7 @@ Analyzes a large repo or multi-service project to identify discrete skillable un
 
 ## Role
 
-You are a source code analyst and decomposition architect collaborating with a developer onboarding an existing project. You bring expertise in codebase analysis, service boundary detection, and skill scoping, while the user brings their domain knowledge. Work together as equals.
+You are a source code analyst and decomposition architect collaborating with a developer onboarding an existing project, pairing your codebase-analysis and skill-scoping expertise with their domain knowledge.
 
 ## Workflow Rules
 
@@ -34,16 +34,16 @@ These rules apply to every step in this workflow:
 | # | Step | File | Auto-proceed | Condition |
 |---|------|------|--------------|-----------|
 | 1 | Initialize | references/init.md | Yes | Always |
-| 1a | Auto-Scope | references/step-auto-scope.md | Yes | `[auto]` mode only. Includes §0b pin resolution — validates and resolves version pin before scoping. Includes §0c coexistence detection — checks for existing skills before proceeding. Includes §0 docs-only URL detection — doc URLs short-circuit auto-scope entirely |
+| 1a | Auto-Scope | references/step-auto-scope.md | Yes | `[auto]` mode only — bypasses steps 2–6; owns pin resolution, coexistence detection, and the docs-only short-circuit |
 | 1b | Continue (session resume) | references/continue.md | Yes | Always |
 | 2 | Scan Project | references/scan-project.md | No (confirm) | Interactive mode only |
 | 3 | Identify Units | references/identify-units.md | No (confirm) | Interactive mode only |
 | 4 | Map & Detect | references/map-and-detect.md | Yes | Interactive mode only |
 | 5 | Recommend | references/recommend.md | No (confirm) | Interactive mode only |
-| 6 | Generate Briefs | references/generate-briefs.md | Yes | Interactive mode only |
+| 6 | Generate Briefs | references/generate-briefs.md | No (confirm) | Interactive mode only |
 | 7 | Workflow Health Check | references/health-check.md | Yes | Always |
 
-**Auto mode path:** When `[auto]` flag is present, init (step 1) routes directly to step 1a, which performs manifest scan → shape detection → scope generation → brief write → health check, bypassing steps 2–6. After URL type detection (§0), pin resolution (§0b) validates the `--pin` argument (or resolves the latest release tag) and stores the resolved ref for downstream brief writes. Coexistence detection (§0c) then checks for existing skills matching the target. If found, the user chooses alongside/merge/skip. Headless mode auto-selects alongside. Auto-scope may produce N > 1 confirmed units when decomposition thresholds are met (`export_count > 500` `[PENDING VALIDATION]` or `package_count > 3` `[PENDING VALIDATION]`), resulting in N briefs and N `brief_paths` in the envelope. When the target is a documentation URL (not a GitHub repo or local path), auto-scope detects the docs-only input at §0, validates URL reachability, writes a docs-only brief, and emits the envelope without performing source analysis.
+**Auto mode path:** With `[auto]` present, init routes directly to step 1a. Step 1a may confirm N > 1 units (a monorepo splits into N briefs / N `brief_paths`, or merges to one), and routes docs-only targets to `references/auto-docs-only.md`.
 
 **Shape detection reference:** `references/step-shape-detect.md` — loaded by step 1a as a reference doc (not a chained step).
 
@@ -51,41 +51,24 @@ These rules apply to every step in this workflow:
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | project_path [required], scope_hint [optional]. `project_path` can be a GitHub repo URL, a local filesystem path, or a documentation URL for docs-only mode. The URL type heuristic at §0 determines the mode. |
-| **Headless inputs** | `--project-path <path>` (skip Step 1 project-path prompt; accepts documentation URLs for docs-only mode), `--scope-hint <text>` (skip Step 1 scope-hint prompt), `--intent-hint <text>` (pre-supply analysis intent; drives recommendation ranking in Step 5), `--pin <version>` (pin to a specific version tag or branch; accepts semver tags, git tags, and branch names; when absent, resolves to the latest release tag) |
+| **Inputs** | project_path [required], scope_hint [optional]. `project_path` is a GitHub repo URL or a local filesystem path. In `[auto]` mode it may also be a documentation URL — step 1a classifies the URL type and routes docs-only targets (see Stages row 1a). |
+| **Headless inputs** | `--project-path <path>` (skip Step 1 project-path prompt; in `[auto]` mode also accepts documentation URLs for docs-only mode), `--scope-hint <text>` (skip Step 1 scope-hint prompt), `--intent-hint <text>` (pre-supply analysis intent; drives recommendation ranking in Step 5), `--pin <version>` (`[auto]` mode only — pin to a specific version tag or branch; accepts semver tags, git tags, and branch names; when absent, resolves to the latest release tag; interactive/headless runs use `--target-refs`/`--target-ref` instead) |
 | **Headless flag** | `--headless` / `-H` flips every confirm gate to auto-proceed |
-| **Auto flag** | `[auto]` bracket modifier — activates auto-scope mode (step 1a). Pipelines pass this as `AN[auto]`. When active, init routes to `step-auto-scope.md` which performs shape detection → scope generation → brief write, bypassing interactive steps 2–6. Requires `--project-path`. |
-| **Gates** | step 2: Confirm Gate [C] | step 3: Confirm Gate [C] | step 5: Confirm Gate [C] (all skipped in auto mode) |
+| **Auto flag** | `[auto]` bracket modifier — activates auto-scope mode (step 1a; see **Auto mode path** above). Pipelines pass this as `AN[auto]`. Requires `--project-path`. |
+| **Gates** | steps 2/3/5: Confirm Gate [C]; step 6: Confirm Gate [Y] (write briefs) — all skipped in auto mode |
 | **Outputs** | analysis-report.md, skill-brief.yaml files (one per recommended unit); final `SKF_ANALYZE_RESULT_JSON` line on stdout when `{headless_mode}` is true. In auto mode, the envelope includes `"mode":"auto"`. |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
-| **Exit codes** | See "Exit Codes" below |
+| **Exit codes** | See `references/headless-contract.md` |
 
-## Exit Codes
+## Headless Result Contract
 
-Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
-
-| Code | Meaning              | Raised by                                                                                  |
-| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
-| 0    | success / skipped / redirect | step 7 (terminal — health check completion); also covers coexistence `"skipped"` and `"redirect"` statuses from §0c |
-| 2    | input-missing        | step 1 §2-3 — required config absent (config.yaml not loadable, project path empty/invalid in headless mode); step 1 §2b — auto mode without `--project-path` |
-| 3    | resolution-failure   | step 1 §2 (`forge-tier.yaml` missing at `{sidecar_path}/forge-tier.yaml`); step 1 §3 (project path does not exist or remote URL inaccessible); step 1a §0a (docs-only URL unreachable); step 1a §0b (pin validation failure — `halt_reason: "pin-invalid"` when the supplied `--pin` does not match any tag or branch); step 1a §3 (shape detection script error, exit code 2) |
-| 4    | write-failure        | step 1 §6 (analysis report write failed); step 6 §5 (skill-brief.yaml write failed); step 6 §9 (result contract write failed) |
-| 6    | user-cancelled       | any interactive menu in steps 2/3/5/6 (user selected `[X]` Cancel and exit)               |
-
-## Result Contract (Headless)
-
-When `{headless_mode}` is true, step 6 (interactive) or step 1a (auto) emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
-
-```
-SKF_ANALYZE_RESULT_JSON: {"status":"success|error","report_path":"…|null","brief_paths":["…"],"unit_counts":{"confirmed":N,"skipped":N,"maybe":N},"exit_code":0,"halt_reason":null,"mode":"interactive|auto"}
-```
-
-`status` is `"success"` on the terminal happy path, `"error"` on any HALT, `"redirect"` when coexistence detection routes to US (merge), or `"skipped"` when the user skips a conflicting target. `halt_reason` is one of: `null` (success), `"input-missing"`, `"forge-tier-missing"`, `"path-invalid"`, `"pin-invalid"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above. `brief_paths` is an array of absolute paths to every generated `skill-brief.yaml` (empty array if none were generated). `unit_counts` reports confirmed/skipped/maybe counts from step 5's user decisions. `mode` is `"auto"` when the `[auto]` flag was active, `"interactive"` otherwise (omitting `mode` is equivalent to `"interactive"` for backward compatibility). The `coexistence` field (present when §0c triggers) is `"alongside"`, `"merge"`, or `"skip"`, indicating the user's coexistence decision. The `pinned_ref` and `pinned_version` fields (present when §0b resolves a pin) record the resolved git ref and extracted semver version for provenance tracking.
+Headless/pipeline runs emit a single-line `SKF_ANALYZE_RESULT_JSON` envelope — on **stdout** for the terminal success path (step 6 or step 1a), on **stderr** with `status: "error"` for every HARD HALT — and exit with a stable code per failure class. The envelope shape, the `halt_reason` enum, and the exit-code table live in `references/headless-contract.md`; step files emit the concrete instance at each site.
 
 ## On Activation
 
 1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
    - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `forge_data_folder`, `skills_output_folder`, `sidecar_path`
+   - If the config cannot be loaded, HARD HALT with exit code 2 (`input-missing`) per `references/headless-contract.md` — the workflow has no forge context to run against.
 
 2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
 
@@ -104,13 +87,15 @@ SKF_ANALYZE_RESULT_JSON: {"status":"success|error","report_path":"…|null","bri
 
    If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
 
-   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each scalar, if the merged value is empty or absent, use the bundled default:
+   Apply the path-scalar fallback now, so stage files reference the resolved variable with no conditional at the usage site. For each scalar, if the merged value is empty or absent, use the bundled default:
 
    - `{unitDetectionHeuristicsPath}` ← `workflow.unit_detection_heuristics_path` if non-empty, else `references/unit-detection-heuristics.md`
    - `{briefSchemaPath}` ← `workflow.brief_schema_path` if non-empty, else `assets/skill-brief-schema.md`
    - `{analysisReportTemplatePath}` ← `workflow.analysis_report_template_path` if non-empty, else `templates/analysis-report-template.md`
-   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (no-op — workflow skips the hook invocation)
+   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (hook invocation skipped)
+
+   Stash all four as workflow-context variables. A non-empty value lets an org swap in a house-style copy (or wire a pipeline hook) without forking the skill.
 
-   Stash all four as workflow-context variables. Stage files reference `{unitDetectionHeuristicsPath}` / `{briefSchemaPath}` / `{analysisReportTemplatePath}` / `{onCompleteCommand}` directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default; non-empty values let orgs swap in house-style copies (or wire in pipeline hooks) without forking the skill.
+   Apply the array surfaces too: run `workflow.activation_steps_prepend` now, treat `workflow.persistent_facts` as standing context for the run (`file:`-prefixed entries load their file/glob contents as facts), then run `workflow.activation_steps_append` after activation.
 
 4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-analyze-source/assets/skill-brief-schema.md

@@ -23,7 +23,7 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | Field              | Type   | Constraint                                       | Description                                                                                                                                                                                                                    |
 |--------------------|--------|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | source_type        | string | `source` or `docs-only`                          | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required                                                                                                                                                |
-| doc_urls           | array  | `{url, label}` objects                           | Documentation URLs for T3 content. Required when `source_type: "docs-only"`                                                                                                                                                    |
+| doc_urls           | array  | `{url, label, source?}` objects                  | Documentation URLs for T3 content. Required when `source_type: "docs-only"`. Optional `source` provenance enum: `language-registry` (registry-guaranteed corpus) \| `readme-detection` \| `homepage` \| `pages-api` \| `docs-folder` |
 | `scripts_intent`   | string | `detect` / `none` / free-text                    | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
 | `assets_intent`    | string | `detect` / `none` / free-text                    | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/").        |
 | `target_version`   | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | User-specified target version. When present, overrides auto-detection and becomes the skill's version. Recommended for docs-only skills where auto-detection is unavailable.                                                   |

package/src/skf-analyze-source/customize.toml

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-analyze-source.
+# Team overrides:     _bmad/custom/skf-analyze-source.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-analyze-source.user.toml (under {project-root})
 
 [workflow]
 

package/src/skf-analyze-source/references/auto-docs-only.md

@@ -0,0 +1,116 @@
+---
+nextStepFile: 'health-check.md'
+outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
+writeSkillBriefProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-write-skill-brief.py'
+  - '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 1a §0a: Docs-Only Short-Circuit
+
+Reached from `step-auto-scope.md` §0c when the target is a documentation URL (not a GitHub repo or local path). It validates the URL, writes a minimal brief and analysis report, emits the result envelope, and chains directly to health-check — the standard auto-scope body (§1 through §11 in `step-auto-scope.md`) never runs for a docs-only target. `{coexistence_suffix}`, `{forge_tier}`, `{user_name}`, `{current_date}`, and the classification set upstream in §0/§0c carry into this file.
+
+## MANDATORY SEQUENCE — §0a
+
+### 1. Validate URL reachability
+
+```bash
+curl -sI --max-time 5 {url}
+```
+
+- 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}"`, then the error envelope (shape in `references/headless-contract.md`) with `exit_code: 3`, `halt_reason: "resolution-failure"`, `mode: "auto"`, `source_type: "docs-only"`.
+
+### 2. Derive skill name from URL domain
+
+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`).
+
+### 3. Write analysis report
+
+Update {outputFile} with docs-only results. If the write fails, HARD HALT with exit code 4 (`write-failed`) per `references/headless-contract.md` (applies equally to the brief write in §4 and the result contract in §6).
+
+**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
+```
+
+**Append body section:**
+```markdown
+## Auto-Scope Analysis
+
+**Mode:** auto (docs-only short-circuit)
+**Source Type:** docs-only
+**Documentation URL:** {url}
+**Skill Name:** {skill_name}
+```
+
+### 4. Write skill brief via canonical writer
+
+**Resolve `{writeSkillBriefHelper}`** from `{writeSkillBriefProbeOrder}`; first existing path wins; HALT if neither resolves.
+
+Create directory `{forge_data_folder}/{skill_name}/` if it does not exist.
+
+Pipe the flat context JSON below into the resolved writer with the `--from-flat` flag:
+
+```json
+{
+  "name":             "{skill_name}",
+  "target_version":   null,
+  "detected_version": null,
+  "source_type":      "docs-only",
+  "source_repo":      "{url}",
+  "language":         "documentation",
+  "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"
+}
+```
+
+```bash
+echo '<context-json>' | uv run {writeSkillBriefHelper} write --target {forge_data_folder}/{skill_name}/skill-brief.yaml --from-flat
+```
+
+### 5. Emit success envelope
+
+```
+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"}
+```
+
+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
+
+Write the result contract per `shared/references/output-contract-schema.md`: the per-run record and latest copy, same as `step-auto-scope.md` §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.

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

@@ -1,6 +1,7 @@
 ---
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 nextStepOptions:
+  step 1a: 'step-auto-scope.md'
   step 2: 'scan-project.md'
   step 3: 'identify-units.md'
   step 4: 'map-and-detect.md'
@@ -38,6 +39,7 @@ Load {outputFile} and read frontmatter:
 - `forge_tier`
 - `existing_skills`
 - `confirmed_units`
+- `mode` — `'auto'` when the report was produced by the auto-scope path; absent or any other value means interactive
 
 ### 3. Present Progress Summary
 
@@ -53,7 +55,11 @@ Load {outputFile} and read frontmatter:
 
 ### 4. Determine Next Step
 
-Map the last completed step to the next step file:
+**IF the report's `mode` is `'auto'`** (produced by the auto-scope path; reached here because the resume invocation did not carry `[auto]`): an auto analysis is a single idempotent pass, not a resumable interactive chain. Do not use the interactive table below.
+- If `auto-scope` is in `stepsCompleted`, the auto analysis already completed — announce "**This auto analysis is already complete.** Would you like to start a new analysis?" and stop.
+- Otherwise (an auto run interrupted before auto-scope finished), re-enter the auto path: load, read fully, then execute `step-auto-scope.md` (it reads the existing report frontmatter and re-runs cleanly). **STOP HERE.**
+
+For interactive reports, map the last completed step to the next step file:
 
 | Last Completed | Next Step |
 |----------------|-----------|
@@ -76,16 +82,5 @@ lastContinued: '{current_date}'
 
 "**Resuming from {next_step_name}...**"
 
-#### Menu Handling Logic:
-
-- After progress is confirmed, immediately load, read entire file, then execute the appropriate step from {nextStepOptions}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed continuation step
-- Route directly to the next incomplete step
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the progress state has been read, summarized to the user, and lastContinued updated will you load the appropriate next step file to resume the workflow.
+Auto-proceed: immediately load, read the entire file, then execute the next incomplete step from {nextStepOptions}.
 

package/src/skf-analyze-source/references/generate-briefs.md

@@ -1,6 +1,6 @@
 ---
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-schemaFile: 'assets/skill-brief-schema.md'
+schemaFile: '{briefSchemaPath}'
 validateBriefSchemaProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
   - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
@@ -20,7 +20,7 @@ To generate a valid skill-brief.yaml file for each confirmed unit using the sche
 - Generate only for units in confirmed_units — no extras, no omissions
 - Do not modify recommendations or re-ask for confirmations
 - Every generated field must trace back to data collected in steps 02-05
-- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is NOT the terminal step
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is not the terminal step
 
 ## MANDATORY SEQUENCE
 
@@ -40,7 +40,7 @@ Mark workflow complete and halt.
 
 ### 2. Generate Skill-Brief YAML Per Unit
 
-For EACH unit in `confirmed_units`, construct a skill-brief.yaml using:
+For each unit in `confirmed_units`, construct a skill-brief.yaml using:
 
 **Field mapping:**
 
@@ -74,7 +74,7 @@ YAML
 
 The script returns JSON `{valid, errors[], warnings[], halt_reason, brief}` — the same validator and contract `skf-brief-skill` runs at consumption time, so a brief that passes here will not be rejected there for structural reasons. Apply the result:
 
-- **`valid: false`** — the `errors[]` name the offending field (e.g. a `description` mis-indented under `scope:`, which leaves the required top-level `description` absent). Repair the assembled YAML and re-run the helper until `valid: true`. **Never write a brief that has not passed this gate.**
+- **`valid: false`** — the `errors[]` name the offending field (e.g. a `description` mis-indented under `scope:`, which leaves the required top-level `description` absent). Repair the assembled YAML and re-run the helper until `valid: true`. A brief is written only after it passes this gate.
 - **`valid: true`** — carry any non-empty `warnings[]` into the §4 preview, then proceed.
 
 This catches structural YAML errors where they are created, rather than letting them surface downstream as a HALT in `skf-brief-skill`'s ratify path.
@@ -84,13 +84,13 @@ This catches structural YAML errors where they are created, rather than letting
 1. **Name uniqueness** — no duplicate names within the batch or existing skills
 2. **Source accessible** — project_path exists
 3. **Language recognized** — valid programming language identifier
-4. **Include patterns** — at least one glob pattern present (the schema requires the `scope.include` key but does not enforce a non-empty list)
-5. **Forge tier match** — matches forge_tier from config
+4. **Forge tier match** — matches forge_tier from config
+
+(The non-empty `scope.include` constraint — at least one glob pattern for every scope type except `docs-only` — is enforced deterministically by the §3a gate, so it is not re-checked here.)
 
 **If any check fails:**
 - Document the failure with specific field and reason
-- Repair (3a structural errors) or present to user for correction (3b semantic issues) before writing
-- Do NOT write invalid briefs
+- Repair (3a structural errors) or present to user for correction (3b semantic issues) before writing — an invalid brief is not written
 
 ### 4. Present Generation Preview
 
@@ -113,6 +113,8 @@ This catches structural YAML errors where they are created, rather than letting
 
 Wait for explicit user confirmation before writing files.
 
+**GATE [default: Y]** — If `{headless_mode}` is true: auto-confirm [Y], write all briefs, and log: "headless: auto-write {count} briefs". Do not stall at this gate — it is the deliverable-producing step of a headless/pipeline run.
+
 ### 5. Write Files
 
 **IF user confirms (Y):**
@@ -120,7 +122,7 @@ Wait for explicit user confirmation before writing files.
 For each confirmed brief:
 1. Create directory `{forge_data_folder}/{unit-name}/` if it does not exist
 2. Write `skill-brief.yaml` to `{forge_data_folder}/{unit-name}/skill-brief.yaml` — write the exact YAML that passed the §3a schema gate verbatim; do not re-serialize, so the bytes on disk are the bytes that validated
-3. Verify file was written successfully
+3. Verify the file was written; if the write fails, HARD HALT with exit code 4 (`write-failed`) per `references/headless-contract.md`
 
 **IF user modifies (M):**
 - Ask which brief and what to change
@@ -132,7 +134,7 @@ For each confirmed brief:
 - Skip file writing, proceed to report update
 
 **IF user cancels (X):**
-- HARD HALT with exit code 6 (`user-cancelled`). Emit the `SKF_ANALYZE_RESULT_JSON` envelope on stderr with `status: "error"`, `halt_reason: "user-cancelled"`, `brief_paths: []`, and `unit_counts` reflecting the confirmed/skipped/maybe state from step 5
+- HARD HALT with exit code 6 (`user-cancelled`). Emit the error envelope on stderr with `halt_reason: "user-cancelled"`, `brief_paths: []`, and `unit_counts` reflecting the confirmed/skipped/maybe state from step 5 (shape in `references/headless-contract.md`)
 
 ### 6. Determine Next Workflow Per Unit
 
@@ -204,7 +206,21 @@ To refine any brief, run the recommended next workflow. To re-analyze with diffe
 
 ### 9. 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` (stable path for pipeline consumers — copy, not symlink). Include all generated `skill-brief.yaml` paths in `outputs` and brief counts in `summary`.
+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` (stable path for pipeline consumers — copy, not symlink). Include all generated `skill-brief.yaml` paths in `outputs` and brief counts in `summary`. If the per-run record cannot be written, HARD HALT with exit code 4 (`write-failed`) per `references/headless-contract.md`.
+
+### 9a. Emit Result Envelope
+
+When `{headless_mode}` is true, emit the `SKF_ANALYZE_RESULT_JSON` envelope on **stdout** — the success signal for the interactive path, alongside §9's on-disk record (both are produced):
+
+```
+SKF_ANALYZE_RESULT_JSON: {"status":"success","report_path":"{outputFile_abs_path}","brief_paths":["{brief_path_1}",…,"{brief_path_N}"],"unit_counts":{"confirmed":N,"skipped":N,"maybe":N},"exit_code":0,"halt_reason":null,"mode":"interactive"}
+```
+
+- `report_path` — absolute path to {outputFile}.
+- `brief_paths` — every `skill-brief.yaml` written in §5 (empty array when the user skipped writing with [N]).
+- `unit_counts` — confirmed/skipped counts from step 5 (`maybe` reserved; see `references/headless-contract.md`).
+
+When `{headless_mode}` is false (interactive human run), skip this section — there is no pipeline consumer to signal.
 
 ### 9b. On-Complete Hook (pipeline integration)
 
@@ -224,5 +240,5 @@ If `{onCompleteCommand}` is empty, skip this section entirely (default behavior
 
 ### 10. Chain to Health Check
 
-ONLY WHEN the briefs have been written (or skipped per user abort), the report updated, the summary presented, the result contract saved, and the on-complete hook invoked (or skipped per empty `{onCompleteCommand}`) will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.
+After the briefs are written (or skipped per user abort), the report updated, the summary presented, the result contract saved, and the on-complete hook invoked (or skipped per empty `{onCompleteCommand}`), load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — continue past the summary even though it reads as final.
 

package/src/skf-analyze-source/references/headless-contract.md

@@ -0,0 +1,33 @@
+# Headless Result Contract & Exit Codes
+
+Canonical headless/pipeline contract for skf-analyze-source. Step files emit the envelope and exit with the codes defined here.
+
+## Result Envelope
+
+When `{headless_mode}` is true, step 6 (interactive) or step 1a (auto) emits a single-line JSON envelope on **stdout** before chaining to step 7. Every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`, using the exit code and `halt_reason` named at that HALT — so an automator branches on the failure class without grepping message text.
+
+```
+SKF_ANALYZE_RESULT_JSON: {"status":"success|error|redirect|skipped","report_path":"…|null","brief_paths":["…"],"unit_counts":{"confirmed":N,"skipped":N,"maybe":N},"exit_code":0,"halt_reason":null,"mode":"interactive|auto"}
+```
+
+- `status` — `"success"` on the terminal happy path, `"error"` on any HALT, `"redirect"` when coexistence routes to US (merge), `"skipped"` when the user skips a conflicting target.
+- `halt_reason` — one of `null` (success), `"input-missing"`, `"resolution-failure"`, `"pin-invalid"`, `"write-failed"`, `"user-cancelled"`.
+- `exit_code` — matches the table below.
+- `report_path` — absolute path to the analysis report, or `null` on an early HALT.
+- `brief_paths` — array of absolute paths to every generated `skill-brief.yaml` (empty array if none).
+- `unit_counts` — `confirmed` (units approved for briefs) and `skipped` (rejected in step 5, or the skipped target in coexistence §0c) counts; auto mode reports `confirmed:N, skipped:0`. `maybe` is a reserved slot, currently always `0`.
+- `mode` — `"auto"` when the `[auto]` flag was active, `"interactive"` otherwise.
+
+In auto mode the envelope also carries `coexistence` (the §0c decision) and, when a pin resolves, `pinned_ref`/`pinned_version` — `step-auto-scope.md` §0b/§0c define those field semantics. The docs-only path adds `source_type: "docs-only"`.
+
+## Exit Codes
+
+Every HARD HALT exits with a stable code so headless automators can branch on the failure class.
+
+| Code | Meaning | Raised by |
+| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
+| 0    | success / skipped / redirect | step 7 (terminal — health check completion); coexistence `"skipped"`/`"redirect"` statuses from §0c |
+| 2    | input-missing        | On Activation (config.yaml not loadable); step 1 §3 (project path empty/invalid in headless mode); step 1 §2b (auto mode without `--project-path`) |
+| 3    | resolution-failure   | step 1 §2 (`forge-tier.yaml` missing at `{sidecar_path}/forge-tier.yaml`); step 1 §3 (project path does not exist or remote URL inaccessible); step 1a §0a (docs-only URL unreachable); step 1a §0b (`halt_reason: "pin-invalid"` when the supplied `--pin` matches no tag or branch); step 1a §3 (shape detection script error, exit code 2) |
+| 4    | write-failed         | a failed write of the analysis report (step 1 §6 / step 1a §7 / §0a), a `skill-brief.yaml` (step 6 §5 / step 1a §8 / §0a), or the result contract (step 6 §9 / step 1a §10 / §0a) |
+| 6    | user-cancelled       | any interactive menu in steps 2/3/5/6 (user selected `[X]` Cancel and exit) |

package/src/skf-analyze-source/references/health-check.md

@@ -16,8 +16,7 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 ## Rules
 
 - No user-facing reports, file writes, or result contracts in this step — those belong in step 6
-- Delegate directly to `{nextStepFile}` with no additional commentary
-- Do not attempt any other action between loading this step and executing `{nextStepFile}`
+- Delegate directly to `{nextStepFile}` with no other action or commentary in between
 
 ## MANDATORY SEQUENCE
 

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

@@ -1,10 +1,13 @@
 ---
 nextStepFile: 'map-and-detect.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-heuristicsFile: 'references/unit-detection-heuristics.md'
+heuristicsFile: '{unitDetectionHeuristicsPath}'
 disqualifyCandidatesProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-disqualify-candidates.py'
   - '{project-root}/src/shared/scripts/skf-disqualify-candidates.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}. -->
@@ -36,24 +39,13 @@ Load {heuristicsFile} for classification rules.
 
 **Resolve `{disqualifyCandidatesHelper}`** from `{disqualifyCandidatesProbeOrder}`; first existing path wins. HALT if no candidate exists.
 
-For EACH detected boundary from the scan:
+For each detected boundary from the scan, apply the classification rules from {heuristicsFile} (loaded in §1):
 
-**Step A — Count detection signals:**
-- Check strong signals (independent manifest, separate entry point, Docker config, distinct export surface, workspace member)
-- Check moderate signals (directory depth, naming convention, separate tests, README, CI/CD reference)
-- Check weak signals (large directory, comment boundaries, import clustering)
+**Step A — Count detection signals:** tally the Strong / Moderate / Weak signals per its Detection Signals tables.
 
-**Step B — Classify boundary type:**
-- Service Boundary — independent deployable unit
-- Package Boundary — workspace member or independently versioned
-- Module Boundary — logical grouping within a package
-- Library Boundary — third-party with significant project-specific usage
-- Composite Boundary — ≥2 boundaries that only deliver value together (detected in §3b below; not assigned during initial per-boundary classification)
+**Step B — Classify boundary type** per its Boundary Classification section. (Composite is detected separately in §3b below — not during this initial per-boundary pass.)
 
-**Step C — Assign scope type:**
-- `full-library` — entire codebase of the unit
-- `specific-modules` — selected components or packages
-- `public-api` — only exported interfaces
+**Step C — Assign scope type** from that same section for the boundary's type.
 
 **Step D — Run deterministic disqualification filter (script):**
 
@@ -87,9 +79,9 @@ Run the shared disqualification helper to apply the deterministic subset of the
 - **Test-only** — test utilities with no production code
 - **Already skilled** — exists in `existing_skills` list (recommend `update-skill` instead)
 
-Remove any boundary that fails one of these LLM-judged rules from the working `kept` set and append it to `dropped[]` with the appropriate reason. Reasons recorded by the script (`too-few-files`, `too-low-loc`, `generated-code`, `auto-generated-tag`) are authoritative; do NOT re-evaluate those rules manually.
+Remove any boundary that fails one of these LLM-judged rules from the working `kept` set and append it to `dropped[]` with the appropriate reason. Reasons recorded by the script (`too-few-files`, `too-low-loc`, `generated-code`, `auto-generated-tag`) are authoritative — do not re-evaluate those rules manually.
 
-**Qualification CONFIRMATION:** Visually skim the script's `kept`/`dropped` decisions for sanity (e.g., a boundary you expected to qualify that landed in `dropped` — surface the script's `reason` and `context.first_match` to the user in §5 so they can override if the heuristic was wrong for this project).
+**Qualification check:** Visually skim the script's `kept`/`dropped` decisions for sanity (e.g., a boundary you expected to qualify that landed in `dropped` — surface the script's `reason` and `context.first_match` to the user in §5 so they can override if the heuristic was wrong for this project).
 
 ### 3. Build Unit Classification Table
 
@@ -110,9 +102,7 @@ For disqualified candidates, note reason:
 
 After building the classification table, apply the Composite Boundary detection heuristic from {heuristicsFile} against the qualifying units:
 
-1. **Scan for merge candidates:** Among the qualifying units (from `kept[]`), find groups of ≥2 Package or Module boundaries that meet EITHER trigger:
-   - **Mutual hard dependency:** Every constituent imports from at least one other constituent in the group, AND no constituent's public API is self-contained
-   - **Shared integration surface:** Constituents share types/traits defined in one constituent but consumed by all others, AND the consuming constituents have no independent barrel
+1. **Scan for merge candidates:** Among the qualifying units (from `kept[]`), find groups of ≥2 Package or Module boundaries that meet either Composite trigger — **Mutual hard dependency** or **Shared integration surface** — as defined in {heuristicsFile}'s Composite Boundary heuristic.
 
 2. **If candidate groups are found**, propose each merge:
    - Derive a composite name from the common namespace prefix or repo name
@@ -121,16 +111,23 @@ After building the classification table, apply the Composite Boundary detection
 
 3. **If no candidate groups are found**, skip to §4.
 
-**Merge does NOT fire for:** Units already flagged as Stack Skill Candidates in step 4 (map-and-detect §5) — those are multi-unit groupings that deliver value *separately* but are *also* useful together. Composite merges are for units that are *only* useful together (the key distinction). If a group of units is independently useful but commonly combined, it remains as separate units and is flagged as a stack skill candidate later.
+**Merge does not fire for:** Units already flagged as Stack Skill Candidates in step 4 (map-and-detect §5) — those are multi-unit groupings that deliver value *separately* but are *also* useful together. Composite merges are for units that are *only* useful together (the key distinction). If a group of units is independently useful but commonly combined, it remains as separate units and is flagged as a stack skill candidate later.
 
 **This step is a recommendation — not automatic.** Merges are presented to the user in §5 for confirmation (see "Composite Merge Proposals" below). If the user rejects a merge, the constituents remain as separate units in the classification table.
 
 ### 4. Detect Primary Language Per Unit
 
-For each qualifying unit (including any approved composites from §3b), determine the primary programming language based on:
-- File extensions in the unit directory
-- Manifest file type (package.json → JS/TS, Cargo.toml → Rust, go.mod → Go, etc.)
-- Entry point file extension
+For each qualifying unit (including any approved composites from §3b), detect the primary language deterministically via the shared helper — the single source of truth for the manifest→language rule table (no in-prose restatement, which drifts from the script's tsconfig JS-vs-TS and `build.gradle` Java-vs-Kotlin disambiguation).
+
+**Resolve `{detectLanguageHelper}`** from `{detectLanguageProbeOrder}`; first existing path wins.
+
+For each unit, pipe its file list — the `files` array built for that boundary in the §2 boundaries JSON — as the tree:
+
+```bash
+echo '{"tree": [<unit files — forward-slash, repo-relative>]}' | uv run {detectLanguageHelper}
+```
+
+Read `.language` and `.confidence` for the unit. When confidence is low (the extension-frequency fallback fired — no manifest matched), surface it in §5 so the user can override the guess.
 
 ### 5. Present Classifications
 
@@ -195,16 +192,8 @@ Display: "**Select:** [C] Continue to Export Mapping and Integration Detection |
 #### Menu Handling Logic:
 
 - IF C: Save classifications to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
-- IF X: HARD HALT with exit code 6 (`user-cancelled`). Emit the `SKF_ANALYZE_RESULT_JSON` envelope on stderr with `status: "error"`, `halt_reason: "user-cancelled"`, and counts/paths reflecting state at cancellation
+- 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)
 
-#### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- **GATE [default: C]** — If `{headless_mode}`: accept all classifications and auto-proceed, log: "headless: auto-accept unit classifications"
-- ONLY proceed to next step when user selects 'C'
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the Identified Units section has been appended to {outputFile} with complete classification tables, disqualification records, and language detection results, and frontmatter stepsCompleted has been updated, will you load and read fully {nextStepFile} to begin export mapping and integration detection.
+**GATE [default: C]** — present the menu and wait for the user's choice. If `{headless_mode}`: accept all classifications and auto-proceed, log: "headless: auto-accept unit classifications".