bmad-module-skill-forge 1.3.0 → 1.4.1

package/src/skf-brief-skill/SKILL.md

@@ -1,13 +1,17 @@
 ---
 name: skf-brief-skill
-description: Design a skill scope through guided discovery. Use when the user requests to "create a skill brief" or "brief a skill."
+description: Design a skill scope through guided discovery. Use when the user requests to "create a skill brief" or "brief a skill".
 ---
 
 # Brief Skill
 
 ## Overview
 
-Helps the user define what to skill — target repo, scope, language, inclusion/exclusion patterns — and produces a skill-brief.yaml that drives create-skill. This is the first step in the skill creation pipeline. The brief becomes the input contract for create-skill, which performs the actual compilation.
+Helps the user define what to skill — target repo, scope, language, inclusion/exclusion patterns — and produces a `skill-brief.yaml` that drives create-skill. This is the first step in the skill creation pipeline; the brief is the input contract for create-skill, which performs the actual compilation.
+
+A good skill brief sets a tight, cohesive boundary: one capability with 3-8 primary functions, an unambiguous public API surface, and a description short enough to fit in a registry row. Briefs that try to cover several unrelated concerns (e.g. authentication *and* data visualization) compile into skills that no agent can route to confidently — a brief covering too much is a worse failure mode than a brief covering too little, and this workflow steers toward the smaller, sharper version when scope is unclear.
+
+Brief-skill is split from create-skill so the scoping conversation runs *once*, on cheap signals (manifests, top-level exports, intent), without paying for AST extraction. Compilation is expensive; scoping decisions are cheap to revise. Keeping them in separate workflows lets a user iterate on the brief, share it for review, and re-run create-skill against the same brief whenever the upstream version moves.
 
 ## Role
 
@@ -20,9 +24,19 @@ These rules apply to every step in this workflow:
 - Read each step file completely before taking any action
 - Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
 - Only load one step file at a time — never preload future steps
-- Always communicate in `{communication_language}`
+- **Lazy-load references and assets:** `references/*.md` and `assets/*.md` files are loaded inside the section that needs them, not at step entry. If a section is skipped (e.g. `version-resolution.md` when `{extractPublicApiScript}` already returned a version, `scope-templates.md` for the `docs-only` branch that bypasses §2c), do not load that file. Each unnecessary load costs context (~5-10 KB per reference) and biases the LLM toward consulting material the current path does not need.
+- Always communicate in `{communication_language}` (the language for user-facing prose). Written artifact text — the `description`, `notes`, and other free-form fields persisted into `skill-brief.yaml` — is in `{document_output_language}`; per-step rules call this out where it applies (see step-05). 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
 
+## On Activation
+
+1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+   - `project_name`, `output_folder`, `user_name`, `communication_language`, `forge_data_folder`, `sidecar_path`
+
+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. Load, read the full file, and execute `./steps-c/step-01-gather-intent.md`.
+
 ## Stages
 
 | # | Step | File | Auto-proceed |
@@ -32,22 +46,37 @@ These rules apply to every step in this workflow:
 | 3 | Scope Definition | steps-c/step-03-scope-definition.md | No (interactive) |
 | 4 | Confirm Brief | steps-c/step-04-confirm-brief.md | No (confirm) |
 | 5 | Write Brief | steps-c/step-05-write-brief.md | Yes |
-| 6 | Workflow Health Check | steps-c/step-06-health-check.md | Yes |
+| 6 | Workflow Health Check (terminal) | steps-c/step-06-health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | target_repo [required], skill_name [required], scope_hint [optional], language_hint [optional] |
+| **Inputs** | `target_repo` [required], `skill_name` [required], `scope_hint` [optional], `language_hint` [optional], `target_version` [optional], `source_authority` [optional: official/community/internal, default community], `source_type` [optional: source/docs-only, default source], `doc_urls` [optional: list of `url[,label]` for source_type=docs-only or supplemental], `scope_type` [optional: full-library/specific-modules/public-api/component-library/reference-app/docs-only], `include` [optional: comma-separated globs], `exclude` [optional: comma-separated globs], `scripts_intent` [optional: detect/none/free-text, default detect], `assets_intent` [optional: detect/none/free-text, default detect], `intent` [optional: free-text used to derive description], `force` [optional: overwrite existing brief without prompting] |
 | **Gates** | step-01: Input Gate [use args] | step-03: Confirm Gate [C] | step-04: Confirm Gate [C] |
-| **Outputs** | skill-brief.yaml |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Outputs** | `skill-brief.yaml` at `{forge_data_folder}/{skill-name}/skill-brief.yaml`; final `SKF_BRIEF_RESULT_JSON` line on stdout when `{headless_mode}` is true |
+| **Headless** | All gates auto-resolve with heuristic-driven or default action when `{headless_mode}` is true; pre-supplied inputs consumed at the gates that would otherwise prompt; absent `source_authority` and `scope_type` are resolved by signal-driven detection (see `references/headless-args.md`); existing briefs are preserved unless `--force` was supplied (HALT with `overwrite-cancelled` otherwise) |
+| **Exit codes** | See "Exit Codes" below |
 
-## On Activation
+## Exit Codes
 
-1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
-   - `project_name`, `output_folder`, `user_name`, `communication_language`, `forge_data_folder`, `sidecar_path`
+Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+| Code | Meaning              | Raised by                                                                                  |
+| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
+| 0    | success              | step-06 (terminal)                                                                         |
+| 2    | input-missing / input-invalid | step-01 GATE — required headless arg absent (`target_repo`, `skill_name`, or `doc_urls` when `source_type=docs-only`) → `input-missing`; enum violation, malformed semver, non-kebab `skill_name`, or step-05 brief-context schema validation failure → `input-invalid` |
+| 3    | resolution-failure   | step-01 §1 (`forge-tier.yaml` missing); step-02 §1 (target inaccessible / `gh auth` fails) |
+| 4    | write-failure        | step-01 §1 pre-flight write probe (data folder unwritable: read-only mount, disk full, permissions denied); step-05 §4 (write to `{forge_data_folder}/{skill-name}/skill-brief.yaml` failed) |
+| 5    | overwrite-cancelled  | step-05 §2 (existing brief, `force` not supplied)                                          |
+| 6    | user-cancelled       | any interactive menu in step-01/03/04 (user selected `[X]` Cancel and exit)                |
+
+## Result Contract (Headless)
+
+When `{headless_mode}` is true, step-05 emits a single-line JSON envelope on **stdout** before chaining to step-06, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+
+```
+SKF_BRIEF_RESULT_JSON: {"status":"success|error","brief_path":"…|null","skill_name":"…","version":"…|null","language":"…|null","scope_type":"…|null","exit_code":0,"halt_reason":null}
+```
 
-3. Load, read the full file, and then execute `./steps-c/step-01-gather-intent.md` to begin the workflow.
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"forge-tier-missing"`, `"target-inaccessible"`, `"gh-auth-failed"`, `"write-failed"`, `"overwrite-cancelled"`, `"user-cancelled"`. `exit_code` matches the table above.

package/src/skf-brief-skill/assets/description-voice-examples.md

@@ -0,0 +1,19 @@
+# Description Voice Examples
+
+Loaded by step-01 §7b only. The five examples below show the *range* of acceptable voices for the `description` field — they vary in lead, structure, and trigger phrasing on purpose. The point is to anchor the LLM to "two facts must come through (what the skill is, when to use it); everything else is voice — do not template-stamp."
+
+## Examples
+
+> Render Markdown to HTML using the marked library. Use when the user pastes raw Markdown and wants formatted output, or asks how to convert MD files in a build pipeline.
+
+> Stripe API client for Node.js — payment intents, subscriptions, customer portal, webhooks. Triggers on tasks involving Stripe-managed payments, subscription billing, or webhook event handling.
+
+> Charts and visualizations powered by D3.js. Reach for this when the user asks to plot data, build interactive graphs, or wants bare D3 control instead of a React-charts abstraction.
+
+> Lint Python code with Ruff. Use when the user wants to add or configure Ruff in a Python project, debug rule selectors, or understand why a specific check fired.
+
+> Date and time arithmetic via Luxon — parsing, formatting, time zones, durations, intervals. Use when working with dates in ways that exceed `Date.toISOString()` but you don't want a full Moment.js footprint.
+
+## Notes on Voice
+
+Each example leads differently (verb / noun / "Charts and..." / verb / noun-phrase) and matches the trigger phrasing ("Use when...", "Triggers on...", "Reach for this when...") to the voice rather than copy-pasting a single template. Compose in that spirit using the gathered material — the target repo, the user's intent, the version if set, and any scope hints — but **do not template-stamp**.

package/src/skf-brief-skill/assets/scope-templates.md

@@ -7,26 +7,31 @@ Present these options to the user for selection:
 **[F] Full Library** — Include everything. Best for smaller, focused libraries.
 - All public exports, all modules
 - Exclude only tests, build artifacts, and internal utilities
+- *Looks like:* `marked` (single-purpose Markdown→HTML); `nanoid` (id generator); `zod` (validation library)
 
 **[M] Specific Modules** — Select which modules to include. Best for large libraries where only some parts are relevant.
 - You choose which modules/directories
 - Fine-grained control over what's in and out
+- *Looks like:* `lodash` skill scoped to just `lodash/array` and `lodash/string`; `aws-sdk` skill scoped to just S3 and DynamoDB
 
 **[P] Public API Only** — Include only the public-facing API surface. Best for libraries with a clear public/private boundary.
 - Entry points and exported interfaces only
 - Internal implementation excluded
+- *Looks like:* `stripe` (payment intents, subscriptions, webhooks — not internal HTTP plumbing); `redis` client (connection + commands, not protocol parsers)
 
 **[C] Component Library** — Optimized for UI component libraries with registries, props-based APIs, and design system variants.
 - Component registry as primary API surface (not individual exports)
 - Props interfaces as API contracts (not function signatures)
 - Auto-exclude demo/example/story files (with user confirmation)
 - Variant consolidation across design systems
+- *Looks like:* `shadcn-ui` (Button, Dialog, Form... 50+ components); Material-UI; Carbon Design System
 
 **[R] Reference App** — Whole-app pattern-reference skill. Use when the source is a working example app and the skill's value is **wiring patterns** (lifecycle, IPC, build-config, distribution) rather than a public library API.
 - Pattern surface as primary API slot (not individual exports)
 - Adoption Steps as primary workflow format (not API-call chains)
 - Tier 2 organized as `references/pattern-*.md` groupings (not per-function)
 - Export-count stats are pattern-surface proxies, not library exports
+- *Looks like:* a Tauri starter app (window setup + IPC bridge + build config); a Next.js auth example (route handlers + middleware + session storage wiring)
 
 ## Boundary Definitions by Scope Type
 

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

@@ -171,46 +171,7 @@ scope:
 
 ## Human-Readable Presentation Format
 
-When presenting the brief for confirmation (brief-skill step 04 only — not applicable to analyze-source batch generation), display as:
-
-```
-Skill Brief: {name}
-====================
-
-Target:      {source_repo}
-Language:    {language}
-Forge Tier:  {forge_tier}
-Description: {description}
-
-Scope: {scope.type}
-  Include: {scope.include patterns, one per line}
-  Exclude: {scope.exclude patterns, one per line}
-  Notes:   {scope.notes}
-
-{If source_type is "docs-only":}
-Source Type: docs-only
-Doc URLs:
-  {doc_urls, one per line with labels}
-
-{If source_type is "source" AND supplemental doc_urls collected:}
-Supplemental Docs:
-  {doc_urls, one per line with labels}
-
-{If scripts_intent or assets_intent was explicitly set (not default "detect"):}
-Scripts:    {scripts_intent}
-Assets:     {assets_intent}
-
-Source Authority: {source_authority}
-
-{If target_version is set:}
-Target Version:   {target_version} (user-specified)
-Detected Version: {detected_version or "N/A"}
-{Else:}
-Version:    {version}
-{End if}
-Created:    {created}
-Created by: {created_by}
-```
+The runtime template lives in `steps-c/step-04-confirm-brief.md` §2 — that is the single source of truth for how the brief is rendered for user confirmation (brief-skill step-04 only; analyze-source batch generation does not render). If the rendering format needs to change, edit the step file. This asset documents the data contract; the step owns the presentation.
 
 ## Validation Rules
 

package/src/skf-brief-skill/references/draft-checkpoint.md

@@ -0,0 +1,46 @@
+# Draft Checkpoint Lifecycle
+
+The `.brief-draft.json` file at `{forge_data_folder}/{skill-name}/.brief-draft.json` is a step-01 in-flight-state checkpoint. It exists only while the workflow has progressed past §7 but not yet completed step-05 — once the final brief writes successfully, step-05 §4 removes it.
+
+**Headless mode skips this entire lifecycle** — the run completes in a single invocation, so no resume is meaningful and no checkpoint is written.
+
+The two halves of the lifecycle (resume on entry, write on §7 confirmation) form a pair. This file documents both so a single load covers them.
+
+## Half 1 — Resume Check (loaded from §6 after name confirmation)
+
+After the skill name is confirmed in §6, check for an in-progress draft at `{forge_data_folder}/{name}/.brief-draft.json`. **Only present the resume prompt** when the file exists AND no `skill-brief.yaml` sits beside it (a finished brief uses the same dir; if a finished brief exists, the draft is stale and step-05's overwrite gate is the right control point).
+
+When the precondition is met, present:
+
+```
+**An in-progress draft for `{name}` was found** (last updated: {mtime}).
+  [Y] Resume from the saved draft (jump to §8 with prior answers restored)
+  [N] Start fresh (delete the draft and re-gather)
+```
+
+### `[Y]` — Resume
+
+Load the JSON and restore the captured fields: `target_repo`, `source_type`, `source_authority`, `target_version`, `doc_urls`, `intent`, `scope_hint`, `description`, `forge_tier`, `tier_source`. Then jump directly to §8 — **skip the rest of §6, all of §7, and all of §7b**.
+
+The skip rule for §7b is load-bearing: re-running §7b would overwrite the user's previously accepted `description` with a fresh candidate synthesized from the seed material. The restored `description` is authoritative.
+
+The user can still revise any field at step-04 §3 if a refinement is needed after the full brief is visible.
+
+### `[N]` — Start fresh
+
+Delete `.brief-draft.json` and continue forward to §7 — the collision check and portfolio-similarity check have already executed earlier in §6 (before the resume prompt fired) and do not repeat. §7 / §7b then proceed in their normal order.
+
+## Half 2 — Checkpoint Write (loaded from §7 after summary confirmation)
+
+After the user confirms the §7 summary, persist the captured state atomically. Write a single JSON object with all of:
+
+- `target_repo`, `source_type`, `source_authority`
+- `target_version` (if set)
+- `doc_urls` (if collected)
+- `intent`, `scope_hint`
+- `description` (the §7b accepted text)
+- `forge_tier`, `tier_source` (for diagnostics)
+
+Atomic-write protocol: write to `.brief-draft.json.tmp` first, then `mv .brief-draft.json.tmp .brief-draft.json`. The rename is atomic on a single filesystem; a partial write never becomes visible as `.brief-draft.json`.
+
+The file is removed by step-05 §4 after the final brief writes successfully.

package/src/skf-brief-skill/references/headless-args.md

@@ -0,0 +1,22 @@
+# Headless Argument Table
+
+Loaded by step-01 §8 only when `{headless_mode}` is true. Canonical operator-facing documentation for the argument set consumed at step-01's GATE; the `{validateBriefInputsScript}` enforces these rules deterministically (its `KNOWN_FIELDS` set must stay in sync with this table).
+
+| Argument | Required | Default | Notes |
+|----------|----------|---------|-------|
+| `target_repo` | yes | — | HALT (exit 2, `halt_reason: "input-missing"`) if absent |
+| `skill_name` | yes | — | HALT (exit 2, `halt_reason: "input-missing"`) if absent; HALT (exit 2, `halt_reason: "input-invalid"`) if non-kebab |
+| `source_type` | no | `source` | If `docs-only`, `doc_urls` becomes required |
+| `doc_urls` | conditional | — | Required when `source_type=docs-only` (HALT exit 2, `halt_reason: "input-missing"` if empty). List of `url` or `url,label` |
+| `source_authority` | no | detected | `official` / `community` / `internal`. When absent and `target_repo` is a GitHub URL, step-01 §8 GATE probes `gh api user` and compares its login to the URL owner — match → `official`, otherwise → `community`. Local-path or `gh api user` failure → `community`. Forced to `community` when `source_type=docs-only` |
+| `target_version` | no | — | Auto-detected in step-02 if absent. Full X.Y.Z semver required (HALT exit 2, `halt_reason: "input-invalid"` on partial forms like `1`, `1.2`, `v2`) |
+| `scope_hint` | no | — | Free-text steering for §5 |
+| `language_hint` | no | — | Overrides language detection in step-02/03 |
+| `scope_type` | no | heuristic | `full-library` / `specific-modules` / `public-api` / `component-library` / `reference-app` / `docs-only`. When absent and `source_type=source`, step-03 §2c runs five signal-driven heuristics (component-registry presence, reference-app keywords, specific-module intent, narrow public API) and uses the first match; falls back to `full-library` only if no heuristic fires. `source_type=docs-only` always short-circuits to `docs-only` |
+| `include` | no | — | Comma-separated globs (used by step-03 §3) |
+| `exclude` | no | — | Comma-separated globs (used by step-03 §3) |
+| `scripts_intent` | no | `detect` | `detect` / `none` / free-text |
+| `assets_intent` | no | `detect` | `detect` / `none` / free-text |
+| `intent` | no | — | Free-text used to derive `description` in §7b |
+| `force` | no | — | Overwrite existing brief without prompting (consumed in step-05 §2b) |
+| `preset` | no | — | Name of a preset YAML file at `{sidecar_path}/brief-presets/{preset}.yaml`. Loaded at step-01 §8 GATE and merged as defaults; explicit args override preset values. Useful for repeated patterns (e.g. briefing 5 SaaS API SDKs with the same `source_authority`/`scope_type`/`scripts_intent`). The preset file is YAML containing any subset of the headless args above; unknown fields are ignored with a warning |

package/src/skf-brief-skill/references/headless-source-authority-detection.md

@@ -0,0 +1,26 @@
+# Headless Source-Authority Detection
+
+Loaded by step-01 §8 only when **all three** preconditions hold:
+
+1. `{headless_mode}` is true
+2. `source_authority` is absent from the validator's `normalized` output (the validator intentionally leaves it absent so detection can run here — when it was supplied in args, the supplied value wins and detection does not run)
+3. `source_type=source` AND `target_repo` is a GitHub URL
+
+When any precondition is unmet, skip this entire procedure: docs-only forces `community` in §3.2; local-path targets default to `community` directly; non-GitHub source URLs are not classifiable from `gh api user` and also default to `community`.
+
+## Procedure
+
+Probe the operator's GitHub login:
+
+```bash
+gh api user --jq .login
+```
+
+Compare the result to the `owner` segment of `target_repo` (URL pattern `https://github.com/<owner>/<repo>`) — **lower-case both values before comparing**. GitHub owner matching is case-insensitive but the API preserves case in responses, so a literal-string comparison would miss the match.
+
+| Outcome | Set | Rationale |
+|---------|-----|-----------|
+| login matches owner (case-insensitive) | `source_authority: "official"` | The operator is the repo's GitHub owner |
+| login does not match | `source_authority: "community"` | The operator is a downstream consumer |
+| `gh api user` errors (unauthenticated, network failure, missing binary) | `source_authority: "community"` (fallback) | Log `"warn: source-authority detection skipped — gh api user failed"` |
+| Local-path target | `source_authority: "community"` (no probe) | Comparison does not apply |

package/src/skf-brief-skill/references/portfolio-similarity-check.md

@@ -0,0 +1,35 @@
+# Portfolio-Similarity Check
+
+Loaded by step-01 §6 only when **all three** preconditions hold:
+
+1. Forge tier is `Deep`
+2. `tools.qmd` is true in `forge-tier.yaml`
+3. The flow is interactive (the headless path skips this check entirely — it would either need to HALT on duplicates [over-aggressive for an automator] or silently log [no operator to act on it]; either choice has a side effect on the QMD index that is best avoided headlessly)
+
+This check catches **semantic near-duplicates** that exact-name collision misses (e.g. `markdown-renderer` proposed when `marked` already exists, or `auth-gateway` when `auth-middleware` already exists). Exact-name collision is handled separately at §6 before this check runs.
+
+## Procedure
+
+The brief portfolio is already indexed in QMD collections — one `{skill-name}-brief` collection per existing brief, registered by step-05 §5 of every prior Deep-tier run. The qmd CLI does not support glob-style collection selection, so enumerate first then query per collection in **a single message with N parallel Bash calls**:
+
+```bash
+# 1. Enumerate brief collections (one per existing brief)
+qmd collection list | awk '/-brief$/{print $1}'
+
+# 2. For each collection, query the proposed name + intent text:
+qmd query "{name} {synthesized-or-intent-text}" -c {collection-name} -n 1 --min-score 0.6
+```
+
+Aggregate the top hits across all `-brief` collections; keep the 3 highest-scoring across the union. If any results come back, surface them as a heads-up — *not* a HALT:
+
+```
+**Heads up — these existing briefs look semantically close to `{name}`:**
+  1. {existing-name} (similarity: {score})  — {existing-description}
+  2. {existing-name} (similarity: {score})  — {existing-description}
+
+Continue with `{name}`, or pick a different name?
+```
+
+## Failure modes
+
+On any QMD failure (binary missing, collection list empty, any per-collection query times out): log `"warn: portfolio-similarity check skipped — qmd query failed: {error}"` and continue silently — never HALT. Quick / Forge / Forge+ tiers do not run this check (qmd is Deep-tier-only per the canonical tier definition: `Deep = + ast-grep + gh + QMD` in `skf-forge-tier-rw.py`).

package/src/skf-brief-skill/references/qmd-collection-registration.md

@@ -0,0 +1,52 @@
+# QMD Collection Registration (Deep Tier)
+
+Loaded by step-05 §5 only when forge tier is Deep AND QMD is available. Skipped silently otherwise.
+
+Index the skill brief into a QMD collection so portfolio-level searches can find existing briefs and avoid duplicate skill creation across large monorepos.
+
+## Collection Creation
+
+Create a QMD collection targeting only the brief file:
+
+```bash
+qmd collection add {forge_data_folder}/{skill-name} --name {skill-name}-brief --mask "skill-brief.yaml"
+qmd embed
+```
+
+If the collection already exists (re-briefing): remove and recreate for atomic replace:
+
+```bash
+qmd collection remove {skill-name}-brief
+qmd collection add {forge_data_folder}/{skill-name} --name {skill-name}-brief --mask "skill-brief.yaml"
+qmd embed
+```
+
+## Embed Verification
+
+After `qmd embed` completes, verify the collection was embedded:
+
+- Run `qmd status` or `qmd collection list` and confirm `{skill-name}-brief` shows document count > 0
+- If verification succeeds: proceed to registry update with no `status` field
+- If verification fails: log warning "QMD embed verification failed for {skill-name}-brief — collection may not be searchable yet", proceed to registry update but include `status: "pending"` in the entry
+
+## Registry Update (Delegated to Script)
+
+Build the entry JSON and pipe it to the `register-qmd-collection` subcommand:
+
+```bash
+echo '{
+  "name": "{skill-name}-brief",
+  "type": "brief",
+  "source_workflow": "brief-skill",
+  "skill_name": "{skill-name}",
+  "created_at": "{current ISO date}"
+  // include "status": "pending" only when embed verification failed
+}' | uv run {forgeTierRwScript} register-qmd-collection --target {forgeTierFile}
+```
+
+The script handles the upsert deterministically (replace existing entry with same `name`, else append) and preserves all other forge-tier state (tools, tier, ccc_index, ccc_index_registry, other qmd_collections entries) — no need to reason about YAML re-rendering or section comments.
+
+## Error Handling
+
+- If `qmd embed` or `qmd collection add` fails: log the error. Do NOT fail the workflow — the brief file was already written successfully.
+- If the `register-qmd-collection` script call fails: log the error JSON, continue. The brief is the user-visible artifact; the registry entry is a portfolio-search optimisation.

package/src/skf-brief-skill/references/version-resolution.md

@@ -0,0 +1,46 @@
+# Version Resolution
+
+Single source of truth for how brief-skill resolves the `version` field of `skill-brief.yaml`. Loaded by step-02 §4b (auto-detect, fallback path only when the language is not script-supported) and step-05 §3 (resolve & write) so both operate on the same precedence rules and invariant. Step-01 §3b references this file in prose for human-readable rationale but does not load it — that step only collects `target_version` and validates its shape with an inline regex.
+
+**Aligned with** `assets/skill-brief-schema.md` "Version Detection" section. If you change one, change the other.
+
+## Detection Algorithm
+
+For the detected source language, attempt the lookups in order. Stop at the first match.
+
+- **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 the 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`.
+
+For remote GitHub sources, fetch version-bearing files via `gh api repos/{owner}/{repo}/contents/{file}` (decode base64). For local sources, read the file directly.
+
+If every step fails or returns a non-semver value, the detected version is `null` — the resolver below falls back to `"1.0.0"`.
+
+**Pre-release handling:** preserve detected pre-release tags (`1.0.0-beta.0`, `2.0.0-rc.1`) verbatim. Do not strip them.
+
+## Precedence — Resolving the `version` Field
+
+The brief's `version` field is resolved from three candidate sources, in priority order:
+
+1. **`target_version`** — collected interactively in step-01 §3b or supplied as a headless argument. When present, this value wins outright. The auto-detection above still runs for informational purposes (the user sees both "Target version" and "Detected version" side-by-side at the analysis summary), but the brief's `version` field is set from `target_version`.
+2. **Auto-detected version** — from §"Detection Algorithm" above. Used when `target_version` is absent.
+3. **Default** — `"1.0.0"` when both of the above fail or yield a non-semver value.
+
+## Invariant
+
+When `target_version` is set, the written brief MUST satisfy:
+
+```
+brief.target_version == brief.version
+```
+
+Step-05 §3 enforces this by setting both fields to the same string when `target_version` is present. Downstream tooling (e.g. `skf-create-skill`) can distinguish "user-requested" from "auto-detected" by the presence of `target_version` without re-deriving provenance — but the values themselves are identical. Different values are a contract violation and a bug.
+
+## Step-Level Responsibilities
+
+| Step | Responsibility |
+|------|----------------|
+| 01 §3b | Collect `target_version` (interactive prompt, or headless arg). Do not auto-detect — that is step 02's job. |
+| 02 §4b | Run the detection algorithm regardless of whether `target_version` is set. If `target_version` is set and the detected version differs, surface the disagreement to the user — but the precedence above is unchanged: `target_version` wins. |
+| 05 §3 | Apply the precedence rules and write `version`. If `target_version` is set, also write the `target_version` field with the identical value. Enforce the invariant. |