bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/skf-create-stack-skill/references/init.md

@@ -1,6 +1,18 @@
 ---
 nextStepFile: 'detect-manifests.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
+frontmatterValidatorProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-frontmatter.py'
+  - '{project-root}/src/shared/scripts/skf-validate-frontmatter.py'
+scanManifestsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-scan-manifests.py'
+  - '{project-root}/src/shared/scripts/skf-scan-manifests.py'
+enumerateStackSkillsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-enumerate-stack-skills.py'
+  - '{project-root}/src/shared/scripts/skf-enumerate-stack-skills.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -9,17 +21,43 @@ forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 
 ## STEP GOAL:
 
-Load forge tier configuration, validate prerequisites, and prepare the stack skill workflow for execution.
+Load forge tier configuration, validate prerequisites, bind and check the invocation inputs, and choose the mode and the folder code mode scans.
 
 ## Rules
 
-- Focus only on loading configuration and validating prerequisites — do not start analyzing dependencies
+- Focus on configuration, prerequisites, inputs and the mode: the two helper runs of §3 only decide the mode and the scan scope, and ranking dependencies is step 3's work
 
 ## MANDATORY SEQUENCE
 
+**Pre-flight: the emitter and the run folder.** Both come first, so every later HALT can emit its envelope. Resolve `{emitEnvelopeHelper}` from `{emitEnvelopeProbeOrder}`; first existing path wins. It builds every `SKF_STACK_RESULT_JSON` line and the result files, and records each warning and auto-decision, so it stays bound for the whole run. If neither path exists, HALT (exit 3, `halt_reason: "helper-missing"`, phase `init:emitter`) and display only: "**Cannot proceed.** `skf-emit-result-envelope.py` is missing, so no result envelope can be built. Re-install SKF, then re-run." Then create the run folder:
+
+```bash
+mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-create-stack-skill-XXXXXXXX"
+```
+
+Bind `{run_dir}` ← the path it prints: the run's state lives there until step 9 deletes it. If the command fails, HALT (exit 4, `halt_reason: "write-failure"`, phase `init:run-folder`): "**Cannot proceed.** The run folder could not be created: {the first stderr line}." With no folder to stage in, emit with the payload on stdin:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-stack-skill --target stderr <<'SKF_JSON'
+{"phase": "init:run-folder", "halt_reason": "write-failure", "reason": "<the halt message, one line>"}
+SKF_JSON
+```
+
+**Halt envelope.** Every later HALT in this step names its exit code, `halt_reason` and phase. Stage `{run_dir}/halt.json` as `{"phase": "<phase>", "halt_reason": "<halt_reason>", "reason": "<the halt message, one line>", "skill_name": "{stack_name}"}`, leaving out `skill_name` before §0 binds `{stack_name}` and adding `"path"` when the halt names a file, then run:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-stack-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+Display the line it prints, then stop with the halt's exit code (`references/invocation-contract.md` lists every halt). If the emitter exits non-zero or prints no line, display the halt message alone.
+
+**Warnings.** Each `workflow_warnings[]` entry this step appends is recorded at once: write its `[{step}/{severity}] {code}: {message}` line to `{run_dir}/warning.txt` with a file write, then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/warning.txt")"`.
+
+**Resolver warning.** When SKILL.md On Activation bound `{customization_resolver_unavailable}` (the customization resolver could not run, so the `{project-root}/_bmad/custom/` overrides do not apply), record it now, as the run's first warning: write `[activation/warn] customization_resolver_unavailable: {customization_resolver_unavailable}` to `{run_dir}/warning.txt` with a file write, never an `echo` or a quoted `--warning` argument (a resolver error can hold quotes or `$( )`), then run the `record` command above.
+
 ### 0. Validate Project Config
 
-Before anything else, load `{project-root}/_bmad/skf/config.yaml`. If the file is missing OR fails YAML parse OR lacks the required top-level keys (`project_name`, `output_folder`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`), HALT with:
+Load `{project-root}/_bmad/skf/config.yaml`. If the file is missing OR fails YAML parse OR lacks the required top-level keys (`project_name`, `output_folder`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`), HALT with:
 
 "**Cannot proceed.** SKF is not initialized for this project (config.yaml missing or malformed).
 
@@ -27,12 +65,16 @@ Before anything else, load `{project-root}/_bmad/skf/config.yaml`. If the file i
 
 **Halting workflow.**"
 
-Then emit the result envelope on stderr per the Result Contract in SKILL.md (`project_name` is unresolved here, so `skill_name` is `null`), and STOP — do not proceed:
+That is a HALT (exit 2, `halt_reason: "config-missing"`, phase `init:config`), emitted per the halt envelope above with no `skill_name`: `project_name` is unresolved here.
 
-```
-SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":null,"stack_libraries":[],"mode":null,"exit_code":2,"halt_reason":"config-missing"}
+**Stack name.** Every later envelope and path names the stack, so bind `{stack_name}` now: the `stack_name` input, with `-stack` appended when it does not already end in it (`acme-web` gives `acme-web-stack`), else `{project_name}-stack`. When the input was given, check the bound name with the name rule step 7's pre-commit check applies to the stack's folder. Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}`; first existing path wins. If no candidate exists, HALT (exit 3, `halt_reason: "helper-missing"`, phase `init:stack-name`, no `skill_name`) with "**Cannot proceed.** `skf-validate-frontmatter.py` is missing, so SKF cannot check `stack_name`. Re-install SKF, then re-run." Otherwise run:
+
+```bash
+uv run {frontmatterValidator} --check-name {stack_name}
 ```
 
+On exit `1` (a name over 64 characters, two hyphens in a row, an upper-case letter or another character the rule refuses), HALT (exit 2, `halt_reason: "input-invalid"`, phase `init:stack-name`, no `skill_name`: the name was refused) with "**Cannot proceed.** `stack_name` `{value}` gives `{stack_name}`, which is not a skill name: {each `issues[]` message}. Fix the input and re-run."
+
 ### 1. Load Forge Tier Configuration
 
 Load `{forgeTierFile}` from the Ferris sidecar.
@@ -45,11 +87,7 @@ Load `{forgeTierFile}` from the Ferris sidecar.
 
 **Halting workflow.**"
 
-Then emit the result envelope on stderr per the Result Contract in SKILL.md (config loaded, so `skill_name` is known; `mode` is not yet resolved), and STOP — do not proceed:
-
-```
-SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":[],"mode":null,"exit_code":3,"halt_reason":"forge-tier-missing"}
-```
+That is a HALT (exit 3, `halt_reason: "forge-tier-missing"`, phase `init:forge-tier`, `path` `{forgeTierFile}`), emitted per the halt envelope above.
 
 **If forge-tier.yaml exists:**
 
@@ -68,7 +106,7 @@ Extract:
 **Tier-dependent tools:**
 - **Quick:** gh_bridge (source reading) — graceful degradation to local file reading if unavailable
 - **Forge:** ast_bridge (ast-grep structural analysis) — required for Forge tier
-- **Forge+:** ast_bridge + ccc_bridge (ccc semantic co-import augmentation) — ccc available for step 5
+- **Forge+:** ast_bridge + ccc_bridge (CCC semantic search, which step 5 uses to pick the files that best show each integration)
 - **Deep:** qmd_bridge (QMD temporal enrichment) — required for Deep tier
 
 See `knowledge/tool-resolution.md` for how each bridge name resolves to concrete tools per IDE environment.
@@ -77,39 +115,59 @@ Report tool availability. If a tier-required tool is missing, downgrade tier and
 
 "**Tier adjusted:** {original_tier} → {adjusted_tier} — {missing_tool} unavailable."
 
-### 3. Accept Optional Inputs
+### 3. Bind Inputs and Choose the Mode
+
+**Inputs.** Bind each input the invocation gives (`references/invocation-contract.md` lists them; `stack_name` is bound in §0), and check them all before the first question below:
+
+- `skills` → `explicit_deps`: a value that names an existing file is a list, one name per line; any other value is comma-separated names. In code mode they are the libraries to rank, and step 2 skips the manifest scan; in compose mode they are the constituent skills, each a skill folder name or a package path, which step 2's helper reduces to its skill folder.
+- `scope_overrides` → `scope_overrides`: `name: include` or `name: exclude` entries, which step 3 applies.
+- `architecture_doc_path` → `architecture_doc_path`: the document compose mode maps integrations from.
+- `mode` → `code` or `compose`.
+- `project_path` → `{scan_root}` (below).
+
+A `mode` other than `code` or `compose`, a `scope_overrides` value other than `include` or `exclude`, a `skills` list file that cannot be read, an `architecture_doc_path` that is not a readable file, or a `project_path` that is not a folder HALTs (exit 2, `halt_reason: "input-invalid"`, phase `init:inputs`) with "**Cannot proceed.** `{input}`: {why}. Fix the input and re-run."
 
-Check if the user provided:
+**Scan root.** `{scan_root}` is the folder code mode reads: step 2 scans its manifests, step 3 counts the imports in it, and step 5 pairs libraries by those counts. It is `project_path` when given (a relative path resolves from `project_root`), else `project_root`. Compose mode reads no source code, so it never uses `{scan_root}`: a `project_path` given to a compose-mode run is not read, and the run appends `{step: "step-01", severity: "warn", code: "project-path-ignored", message: "compose mode reads no source code: project_path not read"}` to `workflow_warnings[]`.
 
-**Explicit dependency list:**
-- If provided, store as `explicit_deps` and skip auto-detection in step 02
-- Format: comma-separated library names or a file path
+**Mode.** The first rule that applies sets `compose_mode`:
 
-**Scope overrides:**
-- If provided, store as `scope_overrides` for use in step 03
-- Format: `library_name: include|exclude`
+1. `mode` is `compose`: `compose_mode: true`.
+2. `mode` is `code`: `compose_mode: false`. An `architecture_doc_path` given with it is not read: append `{step: "step-01", severity: "warn", code: "architecture-doc-ignored", message: "mode code reads no architecture document"}` to `workflow_warnings[]`.
+3. `architecture_doc_path` was given: `compose_mode: true`.
+4. Otherwise two helpers decide. Resolve `{scanManifestsHelper}` from `{scanManifestsProbeOrder}` and `{enumerateStackSkillsHelper}` from `{enumerateStackSkillsProbeOrder}`; first existing path wins. When one has no candidate, HALT (exit 3, `halt_reason: "helper-missing"`, phase `init:mode`) with "**Cannot proceed.** `{script}` is missing, so SKF cannot choose the mode. Re-install SKF, then re-run." Scan `{scan_root}` and keep the JSON as `{manifest_scan}`, which step 2 reuses:
 
-**Compose mode detection:**
+   ```bash
+   uv run {scanManifestsHelper} scan {scan_root} --include-dev
+   ```
 
-Set `compose_mode: false` as the default.
+   When its `manifests` is empty, list the skills compose mode could build from, passing `--explicit` with the `explicit_deps` entries as given, comma-separated, when this section bound them, and keep the JSON as `{skill_candidates}`, which step 2 reuses (an exit `1`, no skills folder, means none):
 
-Skills use version-nested directories — see `knowledge/version-paths.md` for the full path templates and resolution rules.
+   ```bash
+   uv run {enumerateStackSkillsHelper} candidates {skills_output_folder} [--explicit "<names>"]
+   ```
 
-- If user provides an architecture document path for composition or explicitly requests compose mode → set `compose_mode: true` and store `architecture_doc_path`
-- If no manifest files exist in project root AND at least one skill is discoverable in `{skills_output_folder}` → suggest compose mode to the user and ask for optional architecture document path
-  - **Skill discovery (version-aware):** First, read `{skills_output_folder}/.export-manifest.json` — each entry in `exports` names a skill with an `active_version`, which resolves to `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/` containing `SKILL.md` and `metadata.json`. If the export manifest does not exist or is empty, fall back to scanning for `active` symlinks: check `{skills_output_folder}/*/active/*/SKILL.md` — each match indicates a skill whose package lives at `{skills_output_folder}/{skill-name}/active/{skill-name}/` (the `{active_skill}` template).
-  - **Headless default (B8):** If `{headless_mode}` is true, do NOT prompt — auto-accept the suggestion: set `compose_mode: true` and `architecture_doc_path: null` (unless an architecture doc path was supplied via the optional inputs above). This is the constructive default: with no manifests present, code-mode would only halt at step 2 (`no-manifests`), so compose is the sole path that produces output. Log the auto-decision by appending to `workflow_warnings[]`: `{step: "step-01", severity: "info", code: "headless-compose-autodetect", message: "no manifests + {N} discoverable skills — auto-selected compose mode", context: {discoverable_skills: {N}}}`.
-  - If user accepts → set `compose_mode: true` and store `architecture_doc_path` (may be `null` if user chose not to provide one)
-  - If user declines → `compose_mode` remains `false`, continue with code-mode
+   When its `kept[]` is not empty, suggest compose mode, naming its `{N}` skills, and ask for an optional architecture document path (ask again for a path that is not a readable file). If the user accepts, set `compose_mode: true` and store `architecture_doc_path` (`null` when the user gives none); if the user declines, code mode stays. In every other case the run uses code mode: step 2 ranks `explicit_deps` when given.
+
+   **GATE [default: accept]**, headless default (B8): do NOT prompt: accept the suggestion (`compose_mode: true`, `architecture_doc_path: null`). With no manifests, code mode would only halt at step 2 (`no-manifests`) or rank `explicit_deps` in a tree that declares none of them, while `kept[]` holds SKF skills (those `explicit_deps` names, when given): compose is the path that produces the stack. Record the auto-decision: stage `{"gate": "init.compose-suggestion", "default_action": "accept", "taken_action": "accept", "reason": "headless: no manifests and {N} SKF skills, so compose mode", "evidence": {"discoverable_skills": {N}}}` as `{run_dir}/decision.json` and run:
+
+   ```bash
+   uv run {emitEnvelopeHelper} record --workflow skf-create-stack-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+   ```
+
+**Scan scope (code mode).** Run the scan call above (resolving `{scanManifestsHelper}` as rule 4 does) when rule 2 set the mode, so `{manifest_scan}` holds the scan of `{scan_root}`. When its `folders[]` lists more than one folder and no `project_path` was given, ask once which folder the stack covers:
+
+"**This project holds several packages.** Type **A** to build the stack for the whole project (the default), or the folder of one package: {each `folders[]` entry's `path`, with its `names`}."
+
+A folder answer resolves from `project_root`. When it is no folder, ask again; otherwise set `{scan_root}` to it and run the scan call again, replacing `{manifest_scan}`. **GATE [default: A]**: headless, do not ask; keep the project root, record the auto-decision as B8 does, with `{"gate": "init.scan-root", "default_action": "A", "taken_action": "A", "reason": "headless: manifests in {N} folders, so the whole project; pass project_path to scan one package", "evidence": {"folders": {N}}}`, `{N}` being the `folders[]` count: its `reason` tells the user to pass `project_path`.
+
+Skills use version-nested directories: see `knowledge/version-paths.md` for the path templates.
 
 If compose_mode:
 - Display: "**Compose mode detected.** Synthesizing stack skill from existing skills + architecture document."
 
-If no optional inputs provided, auto-detection will be used.
-
 ### 4. Display Initialization Summary
 
-Report that the Stack Skill Forge is initialized, naming: the project (`{project_name}`); the forge tier (`{forge_tier}`) with its positive-capability framing (Quick = source reading and import counting; Forge = AST-backed structural analysis; Forge+ = AST structural + CCC semantic co-import augmentation; Deep = full intelligence — structural + contextual + temporal); the available tools (`{tool_list}`); and the resolved input mode (auto-detect, explicit dependency list, or compose mode).
+Report that the Stack Skill Forge is initialized, naming: the project (`{project_name}`); the forge tier (`{forge_tier}`) with its positive-capability framing (Quick = source reading and import counting; Forge = AST-backed structural analysis; Forge+ = AST structural + CCC semantic search for the files that show each integration; Deep = full intelligence: structural + contextual + temporal); the available tools (`{tool_list}`); the stack name (`{stack_name}`); and the resolved input mode (auto-detect, explicit dependency list, or compose mode), with the folder code mode scans (`{scan_root}`).
 
 ### 5. Auto-Proceed to Next Step
 

package/src/skf-create-stack-skill/references/integration-patterns.md

@@ -2,22 +2,6 @@
 
 # Integration Pattern Detection Rules
 
-## Co-Import Detection
-
-A co-import is detected when two or more confirmed libraries are imported in the same source file.
-
-### Detection Method
-
-1. For each file in the codebase, extract all import statements
-2. Map imports to confirmed library list
-3. If a file imports 2+ confirmed libraries → co-import detected
-4. Record: file path, library pair, line numbers
-
-### Minimum Threshold
-
-- A library pair must co-appear in **2+ files** to qualify as an integration pattern
-- Single file co-imports may be incidental
-
 ## Integration Pattern Types
 
 ### Type 1: Middleware Chain
@@ -59,5 +43,5 @@ Library A + Library B
   Files: [count] files with co-imports
   Key files: [top 3 files by integration density]
   Pattern: [brief description of how they integrate]
-  Confidence: [weaker of the two libraries' tiers from per_library_extractions[], with detection-method qualifier in parens — e.g., `T1-low (grep-co-import)`, `T1 (ccc-augmented)`, `T1-low (architecture-co-mention) [composed]`. Integration detection is grep + co-import, never AST — do not label integrations "AST-verified".]
+  Confidence: [the pair tier step 5 §3 takes from skf-render-stack-metadata.py, with the detection-method qualifier in parens, e.g. `T1-low (grep-co-import)`, `T1 (grep-co-import)`, `T1-low (architecture-co-mention) [composed]`. Integration detection is co-import evidence from the import counts, never AST: do not label integrations "AST-verified".]
 ```

package/src/skf-create-stack-skill/references/invocation-contract.md

@@ -0,0 +1,34 @@
+# Invocation Contract
+
+The headless contract of Stack Skill: its inputs, gates and outputs, the exit code and `halt_reason` of every HARD HALT, and the result envelope. A halting step names its exit code, `halt_reason` and phase and shows the emit command, so it needs nothing else from this file.
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | All optional; step 1 binds and checks each one, and halts with `input-invalid` on a value it cannot use. `project_path`: the folder code mode scans (default: the project root; an interactive run asks once when the manifests sit in several folders). `skills`: the libraries to rank, or the constituent skills in compose mode. `stack_name`: the stack's skill name (default `{project_name}-stack`). `scope_overrides`: step 3 scope overrides. `architecture_doc_path`: the document compose mode reads. `mode`: `code` or `compose` (default: step 1 detects it) |
+| **Gates** | step 1: compose suggestion [accept] and scan scope [A] (each asked only in an interactive run; headless takes the default and records it); step 2: no manifest found (headless: HALT `no-manifests`, exit 2); step 3: scope gate [C]; step 6: review gate [C] |
+| **Outputs** | SKILL.md (stack), context-snippet.md, metadata.json; `provenance-map.json` and `evidence-report.md` in `{forge_version}`; the result contract, `create-stack-skill-result-{YYYYMMDD-HHmmss}.json` and its `create-stack-skill-result-latest.json` copy in `{forge_version}`, with the `-latest` copy also at the stack group root `{forge_data_folder}/{stack_name}/`; a run folder under `{project-root}/_bmad-output/.skf-run/`, deleted when the run finishes or the user cancels and kept after any other HALT |
+| **Headless** | All gates auto-resolve with their default action when `{headless_mode}` is true, and each records its decision in the run sink, so the envelope's `headless_decisions` lists every one |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+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 (halt_reason)                                                                     |
+| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
+| 0    | success              | step 10 (terminal handoff to shared health-check)                                          |
+| 2    | input / precondition invalid | step 1 §0 `config.yaml` missing/malformed (`config-missing`); step 1 §0 or §3 an input it cannot use (`input-invalid`); step 2 §2 headless with no manifests (`no-manifests`, S2); step 4 §3 all extractions failed (`all-extractions-failed`, B7); step 5 §2 a feasibility report of another `schemaVersion` (`schema-version-mismatch`) or with a verdict token outside the schema's set (`unknown-verdict-token`) |
+| 3    | resolution-failure   | step 1 §1 `forge-tier.yaml` missing (`forge-tier-missing`); a shared helper that resolves to no path (`helper-missing`): `skf-emit-result-envelope.py` (step 1 pre-flight), `skf-validate-frontmatter.py` (step 1 §0), `skf-scan-manifests.py` or `skf-enumerate-stack-skills.py` (step 1 §3, step 2 §0 and §2, step 4 §0), `skf-count-imports.py` (step 3 §1), `skf-render-stack-metadata.py` (step 4 §3a, step 5 §3, step 6 §1, step 7 §6), `skf-pair-intersect.py` (step 5 §1), `skf-comention-pairs.py` (step 5 §2), `skf-atomic-write.py` (step 7 §1); step 2 §0 compose-mode stale manifest (a manifest key whose skill folder is gone) or zero qualifying skills (S1/B4), step 4 §0 compose cycle among confirmed skills or a confirmed skill no longer an SKF package (`resolution-failure`) |
+| 4    | write-failure        | step 1 pre-flight: the run folder cannot be created; step 7: a stage-dir, write or commit-dir failure (the §1 rollback contract), or a group-dir collision when an existing non-stack skill occupies the target path (`write-failure`) |
+| 5    | state-conflict       | step 7 §1 ownership check (S3, both phases): the stack's folder in skills_output_folder, or the version folder this run writes, is not SKF output or SKF cannot check it (`not-skf-output`); an SKF stack still in the flat layout (`flat-layout`) |
+| 6    | user-cancelled       | step 2 §2 option 3 (no manifests, interactive); `[X]` Cancel and exit at the step 3 scope gate or the step 6 review gate (`user-cancelled`) |
+
+## Result Contract (Headless)
+
+The shared emitter, `skf-emit-result-envelope.py`, builds every `SKF_STACK_RESULT_JSON: {...}` line from the payload a step stages in `{run_dir}`, folds in the decisions and warnings the run recorded there, derives `exit_code` from `halt_reason`, stamps `run_id` and `result_path`, and checks the line against `shared/scripts/schemas/skf-stack-result-envelope.v1.json` (installed under `{project-root}/_bmad/skf/`), whose descriptions say what each field holds. Never type the line yourself. Every HARD HALT prints one on **stderr**, in every mode, with `status: "error"`, except the `init:emitter` halt, which has no emitter to print one; step 9 prints the success line on **stdout** and displays it when `{headless_mode}` is true, before chaining to step 10:
+
+```
+SKF_STACK_RESULT_JSON: {"status":"success|error","skill_package":"...|null","skill_name":"...","stack_libraries":["..."],"mode":"code|compose","quality_score":null,"exit_code":0,"halt_reason":null,"run_id":"...","result_path":"...|null","headless_decisions":[],"warnings":[]}
+```
+
+A halt adds `error`: its `phase`, its message as `reason`, and `path` when it names a file or folder. When the customization resolver could not run, `warnings` holds `[activation/warn] customization_resolver_unavailable: <reason>`, which step 1 records before any other warning: the run used the bundled `customize.toml` alone, without the `{project-root}/_bmad/custom/` overrides.

package/src/skf-create-stack-skill/references/manifest-patterns.md

@@ -4,26 +4,38 @@
 
 ## Supported Ecosystems
 
-| Ecosystem             | Manifest File(s)                                    | Dependency Key                           | Import Pattern                            |
-|-----------------------|-----------------------------------------------------|------------------------------------------|-------------------------------------------|
-| JavaScript/TypeScript | package.json                                        | dependencies, devDependencies            | `import ... from '...'`, `require('...')` |
-| Python                | requirements.txt, setup.py, pyproject.toml, Pipfile | install_requires, [project.dependencies] | `import ...`, `from ... import`           |
-| Rust                  | Cargo.toml                                          | [dependencies]                           | `use ...`, `extern crate`                 |
-| Go                    | go.mod                                              | require                                  | `import "..."`                            |
-| Java                  | pom.xml, build.gradle                               | dependencies                             | `import ...`                              |
-| Ruby                  | Gemfile                                             | gem                                      | `require '...'`, `require_relative`       |
-| PHP                   | composer.json                                       | require, require-dev                     | `use ...`, `require_once`                 |
-| .NET                  | *.csproj                                            | PackageReference                         | `using ...`                               |
-
-<!-- Manifest scanning, name normalization, dedup, exclusion-dir filtering, and
-dev/build-tool filtering are performed by `skf-scan-manifests.py` (invoked in
-detect-manifests.md §2), which implements exactly the ecosystem table above.
-This file is loaded only for that reference table and the import-counting
-exclusions below — see the script's `--help` for the operative scan contract. -->
+`skf-scan-manifests.py` (invoked in detect-manifests.md §2) finds exactly the manifest files below and no others; the same list is its `searched_filenames[]`. The Ecosystem column is the value it writes in each manifest's `ecosystem` field. The table mirrors the script's `MANIFEST_ECOSYSTEMS`, and `test/test-skf-scan-manifests.py` fails when the two drift.
+
+| Ecosystem  | Language              | Manifest files                                                           | Runtime dependencies                                                                     | Dev dependencies (`scope: dev`)                                                     | Import syntax counted                                      |
+|------------|-----------------------|--------------------------------------------------------------------------|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|------------------------------------------------------------|
+| `npm`      | JavaScript/TypeScript | `package.json`                                                           | `dependencies`                                                                           | `devDependencies`                                                                   | `import ... from '...'`, `import('...')`, `require('...')` |
+| `python`   | Python                | `pyproject.toml`, `requirements.txt`, `setup.py`, `setup.cfg`, `Pipfile` | `[project] dependencies`, `[tool.poetry.dependencies]`, `install_requires`, `[packages]` | `[dependency-groups]`, dev extras, Poetry groups, `tests_require`, `[dev-packages]` | `import ...`, `from ... import ...`                        |
+| `rust`     | Rust                  | `Cargo.toml`                                                             | `[dependencies]`                                                                         | `[dev-dependencies]`                                                                | `use ...`, `extern crate ...`, `crate_name::path`          |
+| `go`       | Go                    | `go.mod`                                                                 | `require`                                                                                | none                                                                                | `import "..."`                                             |
+| `maven`    | Java/Kotlin           | `pom.xml`                                                                | `<dependency>` outside the `test`, `provided` and `system` scopes                        | `<scope>test</scope>`                                                               | `import ...`                                               |
+| `gradle`   | Java/Kotlin           | `build.gradle`, `build.gradle.kts`                                       | `implementation`, `api`, `compile`, `runtimeOnly`                                        | `test*` and `androidTest*` configurations                                           | `import ...`                                               |
+| `ruby`     | Ruby                  | `Gemfile`                                                                | `gem`                                                                                    | `gem` inside a `group :development` or `:test` block                                | `require '...'`                                            |
+| `composer` | PHP                   | `composer.json`                                                          | `require` (not `php` or `ext-*`)                                                         | `require-dev`                                                                       | `use ...`                                                  |
+| `swift`    | Swift                 | `Package.swift`                                                          | `.package(url: ...)`                                                                     | none                                                                                | `import ...`                                               |
+
+The scanner reports runtime dependencies by default; `--include-dev` adds the dev ones, each tagged `scope: dev`. For each manifest it also reports the package's own `name`, whether it is `private` (not published) and its `internal_deps`, the other scanned packages of the same ecosystem it depends on at runtime; `umbrella_candidates` lists the published packages that depend on at least 2, and at least half, of the other published members of their ecosystem (a facade that may re-export them). The script's docstring states the exact rules.
+
+## Scan Exclusion Patterns
+
+The scanner never descends into `node_modules/`, `.venv/`, `venv/`, `.env/`, `vendor/`, `Pods/`, `dist/`, `build/`, `out/`, `target/`, `__pycache__/`, `.next/`, `.nuxt/`, `.output/` or `.git/`, nor into any other directory whose name starts with a dot.
 
 ## Import Counting
 
-For each dependency, count distinct files that import it:
-- Use grep patterns from Import Pattern column
-- Count unique file paths, not total import statements
-- Exclude test files (`*/test/*`, `*_test.*`, `*.spec.*`, `*.test.*`), config files (`*.config.*`, `.eslintrc`, etc.), and build artifacts (`dist/`, `build/`, `node_modules/`, `target/`, `__pycache__/`) from count
+Import counts follow these rules, which `skf-count-imports.py` implements:
+
+- Count the distinct files that import each dependency, not the import statements: a file counts once, with the first line that imports the dependency.
+- Match on module boundaries: `react` counts `import ... from 'react'` and `'react/jsx-runtime'`, never `react-dom` or `react-router`; `yaml` counts `yaml` and `yaml.loader`, never `yamlordereddict`.
+- Map distribution names to import names: `PyYAML` is imported as `yaml`, `Pillow` as `PIL`, `beautifulsoup4` as `bs4`, `scikit-learn` as `sklearn`. A name outside the script's tables is guessed by a naming rule: a Python distribution as its name with `-` read as `_`, `google-cloud-storage` as `google.cloud.storage`, `@types/react` as `react`, `symfony/framework-bundle` as `Symfony\Bundle\FrameworkBundle`. A guess that matches no file goes to `unresolved[]` for you to judge instead of counting 0.
+- A dependency imported by 2 or more files is `above_threshold`.
+
+Excluded paths (a pattern ending in `/` names a directory at any depth; a pattern with no `/` matches a file name at any depth):
+
+- Hidden files and directories: `.*/`, `.*`
+- Tests: `test/`, `tests/`, `__tests__/`, `spec/`, `*.test.*`, `*.spec.*`, `*_test.*`, `test_*.py`, `*_spec.rb`, `conftest.py`
+- Config and build scripts: `*.config.*`, `setup.py`, `noxfile.py`, `*.gradle.kts`, `Package.swift`
+- Build output and vendored code: `dist/`, `build/`, `out/`, `target/`, `node_modules/`, `vendor/`, `venv/`, `Pods/`, `__pycache__/`