bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/shared/tool-requirements.yaml

@@ -0,0 +1,201 @@
+# The external tools SKF uses, with the oldest version SKF supports
+# (minimum) and the versions SKF has run on (tested). This is the one list:
+# the prerequisites table in docs/getting-started.md is generated from it,
+# and the installer copies it to _bmad/skf/shared/ with the rest of
+# src/shared/, so the CLI and the Python helpers can read it too.
+#
+# How the numbers are set:
+# - `tested` lists versions SKF has actually run on, and `basis` names the
+#   run: a CI pin, the CI runner, the install smoke test or a named release
+#   run. An empty list means no run is recorded yet.
+# - `minimum` starts at a tested version, the only version SKF has evidence
+#   for. It starts lower only where the repository already sets a floor for
+#   a stated reason (Node 22, Python 3.11, git 2.15), and `basis` says which.
+# - A minimum comes down only after a run on an older version passes. It is
+#   never guessed lower.
+# - `minimum: null` means SKF has no floor it can check yet. A null minimum
+#   never warns. Node and Python always have one, since --check compares
+#   their copies with it.
+# - A tier tool's minimum also decides its tier: skf-setup counts a tier tool
+#   below its minimum as unavailable. So a first minimum for gh, qmd or ccc
+#   waits for a recorded run, and stays at or below the versions package
+#   managers ship, or their users drop out of Deep or Forge+. Other tools
+#   below their minimum only warn.
+# - Raising a minimum, or giving a tool its first one, is a breaking change:
+#   the release check (tools/covered-surfaces.js) asks for a major release
+#   and a breaking change fragment that names the tool. Lowering or removing
+#   one is additive, and changing `tested` is neither.
+#
+# To change a version, edit this file and run
+# `node tools/tool-requirements.js --write`, which regenerates the
+# prerequisites table. `node tools/tool-requirements.js --check` (run in CI)
+# also compares the copies elsewhere in the repository: the minimums in the
+# README, docs/ and CONTRIBUTING.md, `engines.node` in package.json, the
+# workflows' node-version and python-version, .nvmrc, the ast-grep-cli pin in
+# package.json `test:python`, and the README Acknowledgements rows.
+#
+# Keys of each tool (keyed like skf-detect-tools.py's tool keys where it
+# probes the tool):
+#   name             the name the docs use
+#   summary          what the tool is, in a few words (optional)
+#   kind             runtime (SKF needs it at every tier), tier (a capability
+#                    tier needs it) or optional (a workflow uses it when present)
+#   tiers            the capability tiers that need it (none for optional)
+#   workflows        the workflows that run it, as skf-<name> folder names
+#                    without the prefix, or [all]
+#   used_for         what SKF uses it for, as the prerequisites table says it
+#   minimum          the oldest supported version as a string, or null
+#   tested           the versions SKF has run on, as strings
+#   basis            where minimum and tested come from
+#   version_command  the command that prints the installed version
+#   install_url      where to install it from
+#   upgrade          how to upgrade it
+#   acknowledged_as  its row in the README Acknowledgements table (required
+#                    for tier and optional tools)
+
+schema_version: 1
+tools:
+  node:
+    name: Node.js
+    kind: runtime
+    tiers: [Quick, Forge, Forge+, Deep]
+    workflows: [all]
+    used_for: Installation, npx commands
+    minimum: "22"
+    tested: ["22", "24"]
+    basis: The minimum is package.json engines.node, which the install smoke test runs on Linux, Windows and macOS. CI runs the version in .nvmrc.
+    version_command: [node, --version]
+    install_url: https://nodejs.org
+    upgrade: Install the current LTS release from https://nodejs.org
+
+  python:
+    name: Python
+    kind: runtime
+    tiers: [Quick, Forge, Forge+, Deep]
+    workflows: [all]
+    used_for: Deterministic scoring, validation, and utility scripts. The minimum is what the helpers that read package manifests need (used by Quick Skill, Brief Skill, Analyze Source and Stack Skill)
+    minimum: "3.11"
+    tested: ["3.11", "3.12"]
+    basis: The minimum is set by the helpers that import tomllib, new in Python 3.11. The quality workflow runs the Python tests on 3.11 and the release workflow on 3.12.
+    version_command: [python3, --version]
+    install_url: https://www.python.org
+    upgrade: uv python install
+
+  uv:
+    name: uv
+    summary: Python package runner
+    kind: runtime
+    tiers: [Quick, Forge, Forge+, Deep]
+    workflows: [all]
+    used_for: Running Python scripts with automatic dependency management
+    minimum: null
+    tested: ["0.12.15", "0.12.23"]
+    basis: No minimum yet. CI installs the latest uv without pinning one, so each run takes that day's release. Quality & Validation run 37190025809 (2026-10-04, pull request 665, the tree of main b5150b08, the v3.0.0 release candidate) ran the Python tests through uv 0.12.23 on ubuntu-latest and windows-latest. Pull request 665's npm run quality on its branch head (issue 556 step 5b fix round 8, 2026-10-04, commit 4fecff22, the same tree) ran on uv 0.12.15 on Linux.
+    version_command: [uv, --version]
+    install_url: https://docs.astral.sh/uv/getting-started/installation/
+    upgrade: uv self update
+
+  git:
+    name: git
+    kind: runtime
+    tiers: [Quick, Forge, Forge+, Deep]
+    workflows: [analyze-source, audit-skill, brief-skill, create-skill, setup, test-skill, update-skill]
+    used_for: Reading remote sources, and checking that a local source is still at the commit a skill was built from
+    minimum: "2.15"
+    tested: ["2.47.3", "2.55.0"]
+    basis: The minimum is the one skf-source-tree.py states. No run is recorded on it. Quality & Validation run 37190025809 (2026-10-04, pull request 665, the tree of main b5150b08, the v3.0.0 release candidate) ran the Python tests, which drive real git, on the runners' git 2.55.0 (2.55.0.windows.5 on windows-latest). Pull request 665's npm run quality on its branch head, and its verification of skf-skill-inventory.py derive-name --probe-git against live remotes (issue 556 step 5b fix round 8, 2026-10-04, commit 4fecff22, the same tree), ran on git 2.47.3 on Linux.
+    version_command: [git, --version]
+    install_url: https://git-scm.com/downloads
+    upgrade: Install the latest release from https://git-scm.com/downloads
+
+  gh_cli:
+    name: gh
+    summary: GitHub CLI
+    kind: tier
+    tiers: [Deep]
+    workflows: [analyze-source, audit-skill, brief-skill, campaign, create-skill, forger, quick-skill, test-skill]
+    used_for: Required for the Deep tier, for Campaign, and for `forge-auto --pin`. Optional otherwise, where it makes reading GitHub sources easier
+    minimum: null
+    tested: ["2.102.0"]
+    basis: No minimum yet. The tests stub gh. On 2026-10-04 the v3.0.0 pre-release tool check (recorded in the pull request that added these versions) ran every helper of main b5150b08 (the release candidate) that calls gh, the way the step files call them, against honojs/hono at v4.6.0 on gh 2.102.0, and each exited 0. They were skf-github-probe.py (repo, tags, tree), skf-validate-pins.py, skf-fetch-temporal.py, skf-detect-docs.py, campaign-provenance.py and skf-github-fetch.py, whose gh fallback ran with raw.githubusercontent.com blocked. Setup's skf-detect-tools.py also read the version.
+    version_command: [gh, --version]
+    install_url: https://cli.github.com
+    upgrade: Install the latest release from https://cli.github.com
+    acknowledged_as: GitHub CLI
+
+  ast_grep:
+    name: ast-grep
+    summary: CLI tool for code structural search, lint, and rewriting
+    kind: tier
+    tiers: [Forge, Forge+, Deep]
+    workflows: [analyze-source, audit-skill, brief-skill, create-skill, create-stack-skill, test-skill, update-skill]
+    used_for: Forge, Forge+ and Deep tiers
+    minimum: "0.45.3"
+    tested: ["0.45.3"]
+    basis: The create-skill recipes are verified by test/test-skf-create-skill-recipes.py on the ast-grep-cli version package.json test:python pins. No older version has run them.
+    version_command: [ast-grep, --version]
+    install_url: https://ast-grep.github.io
+    upgrade: npm install -g @ast-grep/cli@latest
+    acknowledged_as: ast-grep
+
+  ccc:
+    name: ccc
+    summary: cocoindex-code semantic code search
+    kind: tier
+    tiers: [Forge+]
+    workflows: [analyze-source, audit-skill, brief-skill, create-skill, create-stack-skill, update-skill]
+    used_for: Forge+ tier, and the Deep tier when installed
+    minimum: null
+    tested: ["0.2.41"]
+    basis: No minimum yet. The tests stub ccc. On 2026-10-04 the v3.0.0 pre-release tool check (recorded in the pull request that added these versions) ran the ccc commands of main b5150b08 (the release candidate) on cocoindex-code 0.2.41. skf-detect-tools.py found ccc with a healthy daemon (Forge+), and skf-merge-ccc-exclusions.py in setup and clone mode (ccc init, ccc index and ccc status) and the create-skill and audit-skill ccc search commands ran on scratch projects. Earlier full workflow runs on 0.2.41 were /skf-setup on SKF 2.2.0 (issue 490, 2026-09-23), the workspace-clone and audit-skill runs of pull request 509 (2026-09-27), and the /skf-setup re-runs of pull request 517 (2026-09-28). Both pull requests are unreleased v3 development.
+    # ccc has no --version flag: the version is on the cocoindex-code line of
+    # `uv tool list` when ccc was installed with uv.
+    version_command: [uv, tool, list]
+    install_url: https://github.com/cocoindex-io/cocoindex-code
+    upgrade: uv tool upgrade cocoindex-code
+    acknowledged_as: cocoindex-code
+
+  qmd:
+    name: qmd
+    summary: local hybrid search engine for project files
+    kind: tier
+    tiers: [Deep]
+    workflows: [audit-skill, brief-skill, create-skill, create-stack-skill, update-skill]
+    used_for: Deep tier
+    minimum: null
+    tested: ["2.8.3"]
+    basis: No minimum yet. The tests stub qmd. On 2026-10-04 the v3.0.0 pre-release tool check (recorded in the pull request that added these versions) ran the qmd commands of main b5150b08 (the release candidate) on qmd 2.8.3 with an isolated index. It ran create-skill's qmd collection remove and add (first run and re-run) and qmd search, audit-skill's qmd ls and qmd search, and setup's qmd status and collection classifier. qmd embed and the vector searches did not run, because no embedding model was cached and the check downloaded none. Before that, qmd 2.8.3 ran in the Deep-tier create-skill runs of 2026-09-28 in bmad-module-ultracode-goal, which built four skills with qmd collection add, embed and search, on SKF main 8ce1db01, an unreleased build between v2.2.0 and v3.0.0.
+    version_command: [qmd, --version]
+    install_url: https://github.com/tobi/qmd
+    upgrade: bun install -g @tobilu/qmd@latest
+    acknowledged_as: QMD
+
+  tessl:
+    name: tessl
+    summary: Tessl CLI
+    kind: optional
+    tiers: []
+    workflows: [create-skill, test-skill]
+    used_for: Opt-in Tessl Review in Create Skill and Test Skill (`tessl_review_workspace` in preferences)
+    minimum: null
+    tested: ["0.111.0"]
+    basis: No minimum yet, since no older tessl has run Tessl Review. The tests stub tessl. Pull request 517 (unreleased v3 development, merged 2026-09-28 as 2b3b5113) records live create-skill and test-skill runs on tessl 0.111.0 in which Tessl Review returned a score. On 2026-10-04 the v3.0.0 pre-release tool check (recorded in the pull request that added these versions) ran `skf status` from main b5150b08 (the release candidate), which read tessl 0.111.0, and ran skf-tessl-review.py collect against it signed out, which starts no review.
+    version_command: [tessl, --version]
+    install_url: https://tessl.io
+    upgrade: tessl cli update
+    acknowledged_as: tessl
+
+  skill_check:
+    name: skill-check
+    summary: skill validator
+    kind: optional
+    tiers: []
+    workflows: [create-skill, create-stack-skill, quick-skill, test-skill, update-skill]
+    used_for: Spec validation, auto-fix and quality scoring. SKF runs it with npx, so it needs no install; without it, validation is done by hand
+    minimum: null
+    tested: ["1.2.0"]
+    basis: SKF runs it through npx at whatever version npx resolves, so there is no floor it can check. In the v3.0.0 pre-release tool check (recorded in the pull request that added these versions) on 2026-10-04, on main b5150b08 (the release candidate), npx resolved skill-check 1.2.0, npm's latest since 2026-02-21, and test-skill's check (`npx skill-check check <skill-dir> --format json --no-security-scan`) on a copy of an oh-my-skills skill returned every field SKF reads. No other version has a recorded run.
+    version_command: [skill-check, --version]
+    install_url: https://github.com/thedaviddias/skill-check
+    upgrade: npm install -g skill-check@latest
+    acknowledged_as: skill-check

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

@@ -7,12 +7,14 @@ description: Discover what to skill in a large repo and produce recommended skil
 
 ## Overview
 
-Analyzes a large repo or multi-service project to identify discrete skillable units, map exports and integration points, and produce recommended skill-brief.yaml files as the primary entry point for brownfield onboarding. The analysis must be thorough enough to produce actionable briefs, but scoped enough to avoid overwhelming the user with false positives. Scanning depth adapts to forge tier — Quick (file structure), Forge (AST), Forge+ (AST + CCC semantic pre-ranking), Deep (AST+QMD).
+Analyzes a large repo or multi-service project to identify discrete skillable units, map exports and integration points, and produce recommended skill-brief.yaml files as the primary entry point for brownfield onboarding. The analysis must be thorough enough to produce actionable briefs, but scoped enough to avoid overwhelming the user with false positives. Exports come from the ast-grep recipe runner at every forge tier (read by eye where ast-grep is missing or the language has no recipe).
 
 ## Conventions
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
-- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root; e.g. `shared/health-check.md`, which the terminal step chains to.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `assets/` holds the brief schema and `templates/` the analysis report skeleton.
 - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
 - `{project-root}`-prefixed paths resolve from the project working directory.
 - `{skill-name}` resolves to the skill directory's basename.
@@ -26,24 +28,26 @@ You are a source code analyst and decomposition architect collaborating with a d
 These rules apply to every step in this workflow:
 
 - Only load one step file at a time — never preload future steps
-- Always communicate in `{communication_language}` (the language for user-facing prose). Written artifact text — the per-unit recommendation `description` and `scope.notes` persisted into `skill-brief.yaml` — is in `{document_output_language}`; per-step rules call this out where it applies. The two values may be the same.
-- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- Always communicate in `{communication_language}`; the text persisted into `skill-brief.yaml` (each recommendation's `description` and `scope.notes`) is written in `{document_output_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action, and record each one in the run sink as the gate says
 
 ## Stages
 
 | # | Step | File | Auto-proceed | Condition |
 |---|------|------|--------------|-----------|
 | 1 | Initialize | references/init.md | Yes | Always |
-| 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 |
+| 1a | Auto-Scope | references/step-auto-scope.md | Conditional (the coexistence gate) | `[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 | An unfinished step-by-step report (`mode` not `'auto'`) of the same target and inputs, run again without `[auto]` (init section 1) |
 | 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 |
+| 4 | Map & Detect | references/map-and-detect.md | No (confirm) | Interactive mode only |
 | 5 | Recommend | references/recommend.md | No (confirm) | 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:** 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`.
+**Auto mode path:** With `[auto]` present, init routes directly to step 1a, which loads a branch file only when its branch fires: `references/step-auto-scope-coexistence.md` (a skill already matches), `references/step-auto-scope-split.md` (a monorepo splits into N briefs) and `references/step-auto-scope-corpora.md` (a whole-language reference), and routes docs-only targets to `references/auto-docs-only.md`.
+
+**[D] Discover Additional Source** (steps 4 and 5) loads `references/discover-additional-source.md`. Step 2 and [D] make each project path's scan root by `references/scan-root.md` (steps 3 and 4 make one again when a resumed session no longer finds it), and step 4 and [D] map each unit's exports by `references/map-unit-exports.md`.
 
 **Shape detection reference:** `references/step-shape-detect.md` — loaded by step 1a as a reference doc (not a chained step).
 
@@ -51,51 +55,52 @@ These rules apply to every step in this workflow:
 
 | Aspect | Detail |
 |--------|--------|
-| **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) |
+| **Inputs** | project_path [required], intent_hint, scope_hint, target_ref or target_refs [optional]. `project_path` is a repository URL or a local path, or in `[auto]` mode a documentation URL (routed docs-only). An interactive run reads them from the invocation and asks at most one opening question. |
+| **Headless inputs** | `--project-path <path>` (comma-separated for several), `--scope-hint <text>` (folders or packages to focus on or skip, `[auto]` included), `--intent-hint <text>` (the goal: ranks the step 5 recommendations; an interactive run also defers the units outside it before step 4, restorable, a headless run never; `[auto]` keeps a merged repo's facets it names), `--target-ref <ref>` (a tag or branch for every project path, written into every brief; not `[auto]`, which pins with `--pin`), `--target-refs <path:ref,...>` (one ref per path, written into each unit's brief; not with `--target-ref`, and not `[auto]`), `--pin <version>` (`[auto]` only: a tag or branch; absent, the latest release tag; a step-by-step analysis an `[auto]` run falls back to keeps its pin) |
 | **Headless flag** | `--headless` / `-H` flips every confirm gate to auto-proceed |
 | **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 `references/headless-contract.md` |
+| **Gates** | one per step: steps 2 to 4 [C] (step 4 also takes composite merges, default accept); step 5 [C] after the decisions (default: confirm every card, flag every stack skill candidate); step 6 [Y] (write briefs). Headless takes each default and records it in `headless_decisions`. Auto mode: only the step 1a coexistence gate (default [A]longside) |
+| **Outputs** | analysis-report.md, skill-brief.yaml files (one per recommended unit) and the run's result files, written by every run that ends, zero confirmed units included; final `SKF_ANALYZE_RESULT_JSON` line on stdout when `{headless_mode}` is true. In auto mode, the envelope includes `"mode":"auto"`. |
+| **Exit codes** | Envelope, emitter, result files, `halt_reason` enum and exit codes: `references/headless-contract.md` |
 
-## Headless Result Contract
+## On Activation
 
-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.
+1. **Resolve the envelope helper.** `{emitEnvelopeHelper}` ← the first existing path of `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py` and `{project-root}/src/shared/scripts/skf-emit-result-envelope.py`. If neither path exists, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `on-activation:helpers`) and display only: "`skf-emit-result-envelope.py` is missing. Nothing was changed. Re-install SKF." In headless mode every other HARD HALT prints its envelope on stderr through the emitter: with the first command below once step 5 has created `{run_dir}`, before that with the second, the payload on one line. `references/headless-contract.md` (Halt Envelope) gives the payload rules, and each step file restates them in its opening.
 
-## On Activation
+   ```bash
+   uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+   uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --target stderr <<'SKF_ANALYZE_HALT'
+   {"phase": "on-activation:config", "reason": "<the halt message>", "halt_reason": "input-missing", "mode": "interactive"}
+   SKF_ANALYZE_HALT
+   ```
 
-1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+2. 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.
+   - If the config cannot be loaded, HARD HALT (exit code 2, `halt_reason: "input-missing"`, phase `on-activation:config`): "SKF cannot load `{project-root}/_bmad/skf/config.yaml`: the workflow has no forge context to run against. Run setup first." When `--headless` or `-H` was passed, print its envelope with the second command above.
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+3. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
 
-3. **Resolve workflow customization.** Run:
+4. **Resolve workflow customization.** Run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-analyze-source.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran) for step 5 to record in the run sink.
 
-   - `{skill-root}/customize.toml` — bundled defaults
-   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
-   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+   Then bind, so stage files use the variable with no conditional at the usage site:
 
-   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.
+   - `{analysisReportTemplatePath}` ← `workflow.analysis_report_template_path` (the bundled `templates/analysis-report-template.md` when an override leaves it empty)
+   - `{onCompleteCommand}` ← `workflow.on_complete` (empty: no hook)
 
-   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:
+   Run `workflow.activation_steps_prepend` now, and treat `workflow.persistent_facts` as standing context for the run (`file:`-prefixed entries load their file/glob contents as facts: the bundled default loads every `project-context.md` under `{project-root}`; an entry prefixed `!` drops each earlier entry it names and loads nothing itself, so an override's `"!file:{project-root}/**/project-context.md"` turns that default off).
 
-   - `{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 (hook invocation skipped)
+5. **Create the run folder.** It holds what the run stages for its helpers (the tree listing, each brief's context, the subagents' unit records, the halt and result payloads) and the sink of its auto-decisions:
 
-   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.
+   ```bash
+   mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-analyze-source-XXXXXXXX"
+   ```
 
-   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.
+   Bind `{run_dir}` ← the path it prints. The step that ends the run deletes it once the envelope is out; a HARD HALT keeps it. If it cannot be created, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `on-activation:run-folder`, path `{project-root}/_bmad-output/.skf-run`): "SKF cannot create its run folder under `{project-root}/_bmad-output/.skf-run/`: {the first stderr line}. Nothing was changed." Its envelope goes through the second command of step 1, its payload with `"customization_resolver_unavailable": "<reason>"` added when step 4 kept one. Once the folder exists and `{customization_resolver_unavailable}` is set, record the reason in the run sink: write `customization_resolver_unavailable: {customization_resolver_unavailable}` to `{run_dir}/resolver-warning.txt` with a file write, never `echo` (the reason can hold quotes or `$( )`), then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")"`.
 
-4. Load, read the full file, and then execute `references/init.md` to begin the workflow.
+6. Run `workflow.activation_steps_append`, then load, read the full file, and execute `references/init.md` to begin the workflow.

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

@@ -32,6 +32,9 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | `source_authority` | string | `official` / `community` / `internal`            | Default `community`. Set to `official` only when the skill creator is the library maintainer. Forced to `community` when `source_type: "docs-only"`.                                                                           |
 | `source_ref`       | string | Git ref (tag/branch/HEAD)                        | Resolved git ref used for source access. Set automatically during tag resolution — do not set manually.                                                                                                                        |
 | `scope.tier_a_include` | array | Glob patterns (min 1, non-empty)            | Optional narrower tier-A include list for a curated-subset skill — stratified monorepo packages, single-crate `specific-modules` scopes, and multi-entry exports-map packages. When present, `skf-test-skill` re-derives the coverage denominator from this list instead of the coarse `scope.include`. **It also exempts the brief from the denominator deflation guard**, so supply it only when it genuinely narrows the surface — never as an empty list, and never as a way to widen. See `skf-test-skill/references/source-access-protocol.md`. |
+| `scope.registry_path` | string | Path from the source root (non-empty) | Optional, for `scope.type: "component-library"`. The component registry file. `skf-create-skill` step 3d reads it instead of detecting a registry, and writes it back, with a `demo-and-registry` amendment, when the user confirms a detected registry or gives its path. |
+| `scope.ui_variants` | array | `{name, package?}` objects (`name` non-empty) | Optional, for `scope.type: "component-library"`. The design system variants, the first one primary. |
+| `scope.demo_patterns` | array | Glob patterns (non-empty strings) | Optional, for `scope.type: "component-library"`. The demo and example files `skf-create-skill` step 3d leaves out. Step 3d reads them instead of detecting demo files, and writes them back, with a `demo-and-registry` amendment per glob, when the user confirms or adjusts the detected ones. |
 
 When `source_type: "docs-only"`:
 - `source_repo` becomes optional (set to doc site URL for reference)
@@ -41,16 +44,12 @@ When `source_type: "docs-only"`:
 
 ## Version Detection
 
-During brief generation, attempt to auto-detect the source version before defaulting to `"1.0.0"`. Check the first matching file in the source:
+A brief's `detected_version` starts from the manifest scan: it is the `version` that `skf-scan-manifests.py` gives the unit's own manifest (a Cargo `version.workspace = true` already resolved from its workspace), passed to the brief writer as found, null when there is none. The writer keeps a full `X.Y.Z` semver version and falls back to `"1.0.0"` otherwise, with a warning. Look a version up by hand only in two cases, and pass what you find the same way:
 
-- **Python:** `pyproject.toml` `[project] version` (static) → if `dynamic = ["version"]`, check `__init__.py` for `__version__` → `_version.py` if exists → `setup.py` `version=` → `git describe --tags --abbrev=0`
-- **JavaScript/TypeScript:** root `package.json` (`"version"`) → if root has `"private": true` with a `"workspaces"` array or lacks a `"version"` field, fall back to a primary workspace package's `package.json` (e.g., `code/core/package.json`, or the first matching `packages/*/package.json`). For GitHub sources, prefer `gh api repos/{owner}/{repo}/releases/latest` → `tag_name` when a non-pre-release tag exists, over a default-branch pre-release. Treat a version containing `-alpha`, `-beta`, `-rc`, `-next`, or `-canary` as a pre-release.
-- **Rust:** `Cargo.toml` `[package] version` (static) → if `version = { workspace = true }`, resolve from workspace root `Cargo.toml` → `git describe --tags --abbrev=0`
-- **Go:** version tag from `go.mod` or `git describe --tags --abbrev=0`
+- **A `version_dynamic` manifest** (Python, a version computed at build time): `__version__` in the package's `__init__.py` → `_version.py` if it exists → `setup.py` `version=` → `git describe --tags --abbrev=0`
+- **A private workspace root that gives none** (JavaScript/TypeScript: the root `package.json` has `"private": true` with `"workspaces"`, or no `"version"`): the `version` the same scan gives a primary workspace package (e.g., `code/core/package.json`, or the first matching `packages/*/package.json`)
 
-If the source is a remote GitHub repo, use `gh api repos/{owner}/{repo}/contents/{file}` to read the version file. If the source is local, read the file directly.
-
-If detection succeeds, use the detected version. If it fails or returns a non-semver value, fall back to `"1.0.0"`.
+Read those files in the scan root. Where it holds only the manifests (step-auto-scope's remote fetch), `git -C "{scan_root}" sparse-checkout add '/<the file>'` brings one in.
 
 The create-skill workflow (extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
 

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

@@ -1,8 +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})
+# Team overrides:     {project-root}/_bmad/custom/skf-analyze-source.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-analyze-source.user.toml
 
 [workflow]
 
@@ -10,15 +10,17 @@
 #   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
 #   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
 
-# Steps to run before the standard activation (uv probe, config load).
-# Overrides append. Use for org-wide pre-flight checks (auth, network,
-# compliance) that must precede any source-analysis work.
+# Steps to run right after the customization resolve (On Activation step 4).
+# Config and preferences are already loaded by then, so a step here can read
+# them but cannot run before them. Overrides append. Use for org-wide
+# pre-flight checks (auth, network, compliance) that must precede any
+# source-analysis work.
 
 activation_steps_prepend = []
 
-# Steps to run after activation but before the first stage executes.
-# Overrides append. Use for context loads or banner customization that
-# should run once activation completes successfully.
+# Steps to run once activation is complete (the run folder exists), just
+# before the first stage executes. Overrides append. Use for context loads
+# or banner customization.
 
 activation_steps_append = []
 
@@ -26,32 +28,42 @@ activation_steps_append = []
 # (house style, naming conventions, scope guardrails).
 # Overrides append.
 #
-# Each entry is either:
+# Each entry is one of:
 #   - a literal sentence, e.g. "Recommended skills must align with our agent stack."
 #   - a file reference prefixed with `file:`, e.g.
 #     "file:{project-root}/docs/analysis-style.md" (globs supported; file
 #     contents are loaded and treated as facts).
+#   - an entry prefixed with `!`, which loads nothing and drops each earlier
+#     entry it names.
+#
+# The default below loads every project-context.md under {project-root}.
+# Overrides append, so they cannot delete it; to stop loading those files,
+# set in {project-root}/_bmad/custom/skf-analyze-source.toml:
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
-# --- Optional asset overrides ---
+# --- Optional asset override ---
 #
-# Lift the canonical asset paths so orgs can substitute house-style copies
-# without forking the skill. Empty string = use the bundled default.
-
-unit_detection_heuristics_path = ""
-brief_schema_path = ""
-analysis_report_template_path = ""
-
-# Pipeline-integration hook invoked after the final result JSON is written
-# (see generate-briefs.md). The command is called as:
-#   <on_complete> --result-path=<absolute_path_to_result_json>
-# Useful for Slack notifications, dashboard ingest, CI hooks, or chaining
-# into checkpoint-preview / a brief linter. Failures are logged to
-# workflow_warnings[] but never fail the workflow.
+# The analysis report skeleton init copies to
+# {forge_data_folder}/analyze-source-report-<project>.md: a path from the
+# skill root, or a {project-root}/... path. A house-style copy keeps the
+# frontmatter keys and the six `## ...` sections with their
+# `[Appended by <step>]` placeholders, since each step replaces its own.
+
+analysis_report_template_path = "templates/analysis-report-template.md"
+
+# Pipeline hook: a shell command the run calls once the shared emitter has
+# written the result files, at the end of every run that writes them
+# (generate-briefs.md, step-auto-scope.md and auto-docs-only.md), as:
+#   <on_complete> --result-path=<forge_data_folder>/analyze-source-result-latest.json
+# A run whose result file could not be written (result_path null in the
+# envelope) and a HALT call no hook. Useful for Slack notifications,
+# dashboard ingest, CI hooks, or chaining into a brief linter. A hook
+# failure is displayed and never fails the run.
 #
-# Empty string = no-op (default).
+# Empty string = no hook (default).
 
 on_complete = ""