bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/workflows/brief-skill/data/skill-brief-schema.md

@@ -1,159 +0,0 @@
-# Skill Brief Schema
-
-## Required Fields
-
-| Field | Type | Constraint | Description |
-|-------|------|------------|-------------|
-| name | string | kebab-case `[a-z0-9-]+` | Unique skill identifier |
-| version | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | Auto-detect from source (see Version Detection below), fall back to `1.0.0` |
-| source_repo | string | GitHub URL or local path | Repository or project root (optional when `source_type: "docs-only"`) |
-| language | string | Recognized language | Primary programming language |
-| scope | object | See Scope Object below | Boundary definition |
-| description | string | 1-3 sentences | What the skill covers |
-| forge_tier | string | `Quick` / `Forge` / `Forge+` / `Deep` | Inherited from forge-tier.yaml (Title Case) |
-| created | string | ISO date `YYYY-MM-DD` | Generation date |
-| created_by | string | user_name from config | Who generated the brief |
-
-## Optional Fields
-
-| Field | Type | Constraint | Description |
-|-------|------|------------|-------------|
-| source_type | string | `source` or `docs-only` | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required |
-| doc_urls | array | `{url, label}` objects | Documentation URLs for T3 content. Required when `source_type: "docs-only"` |
-| `scripts_intent` | string | `detect` / `none` / free-text | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
-| `assets_intent` | string | `detect` / `none` / free-text | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/"). |
-| `target_version` | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | User-specified target version. When present, overrides auto-detection and becomes the skill's version. Recommended for docs-only skills where auto-detection is unavailable. |
-| `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. |
-
-When `source_type: "docs-only"`:
-- `source_repo` becomes optional (set to doc site URL for reference)
-- `doc_urls` must have at least one entry
-- `source_authority` is forced to `community` (T3 external documentation cannot be `official`)
-- All extracted content gets `[EXT:{url}]` citations
-
-## Version Detection
-
-During brief creation, attempt to auto-detect the source version before defaulting to `"1.0.0"`. Check the first matching file in the source:
-
-- **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:** `package.json` (`"version"`)
-- **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`
-
-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"`.
-
-The create-skill workflow (step-03-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.
-
-**Target version override:** When `target_version` is present in the brief, it takes precedence over auto-detection. Auto-detection still runs for informational purposes (displayed as "Detected version" alongside the user-specified "Target version"), but the `target_version` value is used as the brief's `version` field. This is particularly useful for docs-only skills (where no package manifest exists) and when the user wants to compile a skill for a specific older version.
-
-**Pre-release handling:** If the detected version contains a pre-release tag (e.g., `1.0.0-beta.0`, `2.0.0-rc.1`), preserve it as-is. Pre-release tags are valid semver and must not be stripped. When comparing versions during reconciliation, use semver-aware comparison that respects pre-release ordering.
-
-## Scope Object Structure
-
-```yaml
-scope:
-  type: full-library | specific-modules | public-api | component-library | docs-only
-  include:
-    - "src/**/*.ts"           # Glob patterns for included files/directories
-  exclude:
-    - "**/*.test.*"           # Glob patterns for excluded files
-    - "**/node_modules/**"
-  notes: "Optional notes about scope decisions"
-  # Additional fields when scope.type is "component-library":
-  # registry_path: "path/to/registry.ts"  # Optional — auto-detected if omitted
-  # ui_variants:                           # Optional — design system variants
-  #   - name: "shadcnui"
-  #     package: "packages/components/react-shadcn"
-  # demo_patterns:                         # Optional — auto-detected if omitted
-  #   - "**/demo/**"
-  #   - "**/*.stories.*"
-```
-
-## YAML Template
-
-```yaml
----
-name: "{skill-name}"
-version: "{detected-version or 1.0.0}"  # Auto-detect from source, fall back to 1.0.0
-source_type: "source"                    # "source" (default) or "docs-only"
-source_repo: "{github-url-or-local-path}"
-language: "{detected-language}"
-description: "{brief-description}"
-forge_tier: "{Quick|Forge|Forge+|Deep}"
-created: "{date}"
-created_by: "{user_name}"
-scope:
-  type: "{full-library|specific-modules|public-api|component-library|docs-only}"
-  include:
-    - "{pattern}"
-  exclude:
-    - "{pattern}"
-  notes: "{optional-scope-notes}"
-# target_version: "X.Y.Z"       # Optional: overrides auto-detection when specified
-# source_ref: "v0.5.0"          # Auto-resolved — do not set manually
-# Optional: documentation URLs for T3 content (required when source_type: "docs-only")
-# doc_urls:
-#   - url: "https://docs.example.com/api"
-#     label: "API Reference"
-# scripts_intent: detect         # Optional: detect | none | description
-# assets_intent: detect          # Optional: detect | none | description
-# source_authority: community    # Optional: official | community | internal
----
-```
-
-## 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}
-```
-
-## Validation Rules
-
-1. `name` must be unique within {forge_data_folder}
-2. `source_repo` must be accessible (gh api for GitHub, path exists for local)
-3. `language` must be a recognized programming language
-4. `scope.type` must be one of the five defined types
-5. `scope.include` must have at least one pattern (exception: `docs-only` scope, where include patterns are optional since no source code is available)
-6. `forge_tier` must be one of: Quick, Forge, Forge+, Deep (Title Case, must match the tier from forge-tier.yaml, or default to Quick)
-7. When `source_type: "docs-only"`: `doc_urls` must have >= 1 entry, `source_repo` becomes optional
-8. Each `doc_urls` entry must have a valid `url` field

package/src/workflows/brief-skill/workflow.md

@@ -1,58 +0,0 @@
----
-name: brief-skill
-description: Scope and design a skill through guided discovery
-web_bundle: true
-installed_path: '{project-root}/_bmad/skf/workflows/skillforge/brief-skill'
----
-
-# Brief Skill
-
-**Goal:** Help the user define what to skill — target repo, scope, language, inclusion/exclusion patterns — and produce a skill-brief.yaml that drives create-skill.
-
-**Your Role:** In addition to your name, communication_style, and persona, you are also a skill scoping architect collaborating with a developer who wants to create an agent skill. This is a partnership, not a client-vendor relationship. You bring expertise in source code analysis, API surface identification, and skill boundary design, while the user brings their domain knowledge and specific use case for the skill. Work together as equals.
-
-**Meta-Context:** This workflow is the first step in the skill creation pipeline. The skill-brief.yaml you produce together becomes the input contract for create-skill, which performs the actual compilation. Your job is to ensure the brief is well-scoped, accurate, and actionable — not to build the skill itself.
-
----
-
-## WORKFLOW ARCHITECTURE
-
-### Core Principles
-
-- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere to 1 file as directed at a time
-- **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so
-- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
-- **State Tracking**: Data is accumulated conversationally across steps and written as skill-brief.yaml in the final step
-- **Append-Only Building**: Each step builds on information gathered in previous steps
-
-### Step Processing Rules
-
-1. **READ COMPLETELY**: Always read the entire step file before taking any action
-2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
-3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
-4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
-5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
-
-### Critical Rules (NO EXCEPTIONS)
-
-- 🛑 **NEVER** load multiple step files simultaneously
-- 📖 **ALWAYS** read entire step file before execution
-- 🚫 **NEVER** skip steps or optimize the sequence
-- 🎯 **ALWAYS** follow the exact instructions in the step file
-- ⏸️ **ALWAYS** halt at menus and wait for user input
-- 📋 **NEVER** create mental todo lists from future steps
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
----
-
-## INITIALIZATION SEQUENCE
-
-### 1. Module Configuration Loading
-
-Load and read full config from {project-root}/_bmad/skf/config.yaml and resolve:
-
-- `project_name`, `output_folder`, `user_name`, `communication_language`, `forge_data_folder`, `sidecar_path`
-
-### 2. First Step Execution
-
-Load, read the full file and then execute `./steps-c/step-01-gather-intent.md` to begin the workflow.

package/src/workflows/create-skill/data/source-resolution-protocols.md

@@ -1,200 +0,0 @@
-# Source Resolution Protocols
-
-## Tag Resolution (when target_version is set)
-
-When `brief.target_version` is present AND `source_repo` is a remote URL, resolve the target version to a git tag before cloning:
-
-1. **List available tags:**
-   - `gh api repos/{owner}/{repo}/tags --paginate --jq '.[].name'`
-   - Fallback: `git ls-remote --tags {source_repo} | sed 's|.*refs/tags/||'`
-
-2. **Match `target_version` against tags** in priority order:
-   - **Exact match:** `{target_version}` (e.g., `0.5.0`)
-   - **With `v` prefix:** `v{target_version}` (e.g., `v0.5.0`)
-   - **With package scope (monorepos):** `{brief.name}@{target_version}` or `@{scope}/{brief.name}@{target_version}`
-
-3. **Resolution outcomes:**
-   - **Single match:** Store the matched tag as `source_ref`. Use it as `{branch}` in all subsequent clone/API commands.
-   - **Multiple matches:** Present the matching tags to the user — "Multiple tags match version {target_version}: {list}. Which one should I use?" Wait for selection.
-   - **Zero matches:** ⚠️ Warn: "No git tag found matching version {target_version}. Closest available tags: {list 5 nearest by semver sort}. Falling back to default branch — **extracted code may not match target version.**" Set `source_ref` to `HEAD` and proceed with default branch.
-
-4. **Store `source_ref`** in context. This value is written to metadata.json and provenance-map.json for downstream workflows (update-skill, audit-skill) to re-clone from the same ref.
-
-When `brief.target_version` is NOT set: skip tag resolution. Set `source_ref` to `HEAD` (default branch behavior, unchanged from before).
-
-### Local Source Warning
-
-When `brief.target_version` is set AND `source_repo` is a local path:
-
-⚠️ "**Local source may not match target version {target_version}.** Ensure you've checked out the correct version locally, or use a remote GitHub URL so SKF can clone from the git tag automatically."
-
-Proceed with local files as-is. Set `source_ref` to `"local"`.
-
----
-
-## Remote Source Resolution (Forge/Deep only)
-
-If `source_repo` is a local path: proceed with the tier-appropriate strategy as normal.
-
-If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is Forge or Deep:
-
-1. **Check `git` availability:** Verify `git` is functional (`git --version`). If `git` is not available, skip to the fallback warning below.
-
-2. **Ephemeral shallow clone:** Clone the repository to a system temp path for AST access. Use `source_ref` from tag resolution (or `{branch}` for the default branch if no tag was resolved):
-
-   ```
-   temp_path = {system_temp}/skf-ephemeral-{skill-name}-{timestamp}/
-   git clone --depth 1 --branch {source_ref} --single-branch --filter=blob:none {source_repo} {temp_path}
-   ```
-
-   **If `include_patterns` are NOT specified:**
-
-   ```
-   git clone --depth 1 --branch {source_ref} --single-branch --filter=blob:none {source_repo} {temp_path}
-   ```
-
-   **If `include_patterns` ARE specified**, use sparse-checkout to limit the clone scope:
-
-   ```
-   git clone --depth 1 --branch {branch} --single-branch --filter=blob:none --sparse {source_repo} {temp_path}
-   ```
-
-   **Mode selection:** Choose sparse-checkout mode based on whether `exclude_patterns` exist:
-
-   - **No `exclude_patterns`:** Use default **cone mode** (faster). Convert `include_patterns` to directory roots.
-   - **`exclude_patterns` present:** Use **`--no-cone` mode** which supports gitignore-style negation patterns (`!` prefix). This applies both include and exclude at the git level, avoiding unnecessary blob downloads.
-
-   **Cone mode (no exclude patterns):**
-
-   **IMPORTANT:** `git sparse-checkout set` expects **directories**, not glob patterns. Convert `include_patterns` before passing them:
-
-   **Classification rule:** A pattern is an **individual file** if it contains no glob characters (`*`, `?`, `[`) AND does not end with `/`. Everything else is a glob — strip it to its directory root (the path prefix before the first glob character or wildcard segment).
-
-   - Strip glob suffixes to directory roots (e.g., `src/core/**/*.py` → `src/core`, `src/api/*.ts` → `src/api`)
-   - Deduplicate the resulting directory list
-   - Individual files (e.g., `pyproject.toml`, `src/utils/helpers.py`) are kept as-is
-
-   **If only directory roots (no individual files):**
-
-   ```
-   git -C {temp_path} sparse-checkout set {converted_directory_roots}
-   ```
-
-   **If any individual files are present (or mixed):**
-
-   ```
-   git -C {temp_path} sparse-checkout set --skip-checks {converted_directory_roots} {individual_files}
-   ```
-
-   Example transformation:
-   ```
-   Brief include_patterns:        sparse-checkout args:
-   src/core/**/*.py          →    src/core          (directory root)
-   src/api/*.ts              →    src/api           (directory root)
-   examples/**/*.py          →    examples          (directory root)
-   pyproject.toml            →    pyproject.toml    (individual file, needs --skip-checks)
-   src/utils/helpers.py      →    src/utils/helpers.py (individual file, needs --skip-checks)
-   ```
-
-   **No-cone mode (exclude patterns present):**
-
-   When `exclude_patterns` exist, use `--no-cone` mode to pass both include and exclude patterns directly as gitignore-style rules:
-
-   1. Convert `include_patterns` to gitignore-style patterns. For patterns without glob characters (`*`, `?`, `[`) that do not end with `/`, apply the **file-detection heuristic**: if the last path segment contains a `.` (file extension), it is an **individual file** — prepend `/` and keep as-is (e.g., `packages/registry/registry.json` → `/packages/registry/registry.json`). If the last path segment has no extension, it is a **bare directory name** — append `/**` (e.g., `cognee` → `cognee/**`). Patterns that already contain glob characters are kept as-is (e.g., `cognee/**` → kept as-is).
-   2. Convert `exclude_patterns` to negation patterns by prepending `!`. Apply the same file-detection heuristic: individual files (last segment has `.` extension) get `!/` prefix only (e.g., `src/internal/config.json` → `!/src/internal/config.json`); bare directory names get `/**` appended (e.g., `cognee/tests` → `!cognee/tests/**`). Patterns with globs are kept as-is with `!` prefix (e.g., `cognee/tests/**` → `!cognee/tests/**`; `**/test_*` → `!**/test_*`).
-   3. **CRITICAL:** List all include patterns BEFORE negated exclude patterns — git processes patterns in order and a negation can only suppress a prior inclusion.
-   4. Pass to sparse-checkout — include patterns first, then negated exclude patterns:
-
-   ```
-   git -C {temp_path} sparse-checkout set --no-cone {include_gitignore_patterns} {negated_exclude_patterns}
-   ```
-
-   Example transformation:
-   ```
-   Brief include_patterns:          Brief exclude_patterns:
-   cognee/**                        cognee/tests/**
-   packages/registry/registry.json  cognee/alembic/**
-                                    **/test_*
-
-   sparse-checkout args (--no-cone):
-   'cognee/**' '/packages/registry/registry.json' '!cognee/tests/**' '!cognee/alembic/**' '!**/test_*'
-   ```
-
-   Note: `registry.json` is an individual file (has `.json` extension), so it gets `/` prefix instead of `/**` suffix.
-
-   **Note:** `--no-cone` mode is slower than cone mode for very large repositories but eliminates downloading excluded blobs entirely.
-
-   **Always-included root files:**
-
-   Regardless of `include_patterns`, always add these root-level version/manifest files to the sparse-checkout pattern list. These are needed for version reconciliation and must not require a fallback to `gh api`:
-
-   `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `setup.py`, `setup.cfg`, `VERSION`
-
-   In cone mode, always use the `--skip-checks` command form when adding these files — even if `include_patterns` resolved to only directory roots (which would normally use the form without `--skip-checks`). The command becomes: `git -C {temp_path} sparse-checkout set --skip-checks {directory_roots} pyproject.toml package.json Cargo.toml go.mod setup.py setup.cfg VERSION`. In no-cone mode, list them as explicit include patterns before any negation patterns. Do not flag them as extraneous inclusions during post-checkout filtering.
-
-   **Post-checkout filtering:**
-
-   After checkout, apply the original glob `include_patterns` as file-level filters when building the extraction file list — sparse-checkout gets the right directories, glob filtering narrows to the exact files. When `--no-cone` mode was used, most exclude filtering is already done at the git level, but apply `exclude_patterns` as a final pass to catch any edge cases where gitignore pattern matching diverges from the brief's glob semantics. Always-included root files (see above) are exempt from post-checkout filtering.
-
-3. **If clone succeeds:** Update the working source path to `{temp_path}` for all subsequent AST operations in this step. Capture the source commit: `git -C {temp_path} rev-parse HEAD` — store as `source_commit` in context. Proceed with the **Forge/Deep Tier** extraction strategy below. Mark `ephemeral_clone_active = true` for cleanup.
-
-4. **If clone fails (network error, auth failure, timeout):**
-
-   ⚠️ **Warn the user explicitly:**
-
-   "Ephemeral clone of `{source_repo}` failed: {error}. Degrading to source reading (T1-low) for this run. For T1 (AST-verified) confidence, clone the repository locally and update `source_repo` in your brief to the local path."
-
-   Proceed with Quick tier extraction strategy below. Note the degradation reason in context for the evidence report.
-
-**Ephemeral clone cleanup:** After extraction is complete for all files in scope (whether successful or partially failed), before presenting the Gate 2 summary (Section 6), if `ephemeral_clone_active`:
-
-1. **Reset working directory first:** Before deleting the clone, ensure the shell working directory is not inside the temp path. Run `cd {project-root}` using the **absolute path** captured at workflow start (not a relative path). This prevents `getcwd` errors when the temp directory is deleted while it is the shell's cwd — which happens if `cd {temp_path}` was used during CCC init or extraction operations.
-2. **Delete the clone:** `rm -rf {temp_path}`
-3. **Log:** "Ephemeral source clone cleaned up."
-
-This ensures cleanup runs even if some extractions failed, as long as the step itself is still executing. **If any error halts the extraction step before Gate 2 is reached**, cleanup must still occur: reset cwd to `{project-root}` and attempt to delete `{temp_path}` before halting. Log the cleanup attempt regardless of success.
-
----
-
-## Source Commit Capture (all tiers, source mode only)
-
-**If `source_type: "docs-only"`:** skip — set `source_commit: null`.
-
-After the source path is accessible, capture the current commit hash for provenance tracking:
-
-- **Local path:** `git -C {source_root} rev-parse HEAD` — if the path is a git repo
-- **Ephemeral clone (Forge/Deep):** already captured during clone (step 3 above)
-- **Quick tier (remote, no clone):** `gh api repos/{owner}/{repo}/commits/{source_ref} --jq '.sha'`
-
-Store the result as `source_commit` in context. If capture fails (not a git repo, API unavailable), set `source_commit: null` — this is not an error.
-
-Also store `source_ref` in context (from tag resolution above, or `HEAD` if no tag was resolved, or `"local"` for local sources). This value is persisted to metadata.json and provenance-map.json so downstream workflows (update-skill, audit-skill) can re-access the same source ref.
-
----
-
-## Version Reconciliation (all tiers, source mode only)
-
-**Target version override:** If `brief.target_version` is present, use it as the authoritative version for the skill. Do NOT warn about a brief-vs-source version mismatch — the user intentionally specified this version. Set the working version to `brief.target_version` and skip the rest of this reconciliation section. The `target_version` field indicates deliberate user intent (e.g., targeting an older version, or providing the version for a docs-only skill).
-
-**If `source_type: "docs-only"`:** skip this section — no source files exist to reconcile.
-
-After the source path is accessible (local path from step-01, or ephemeral clone from above), check whether the source contains a version identifier and reconcile it with `brief.version`. Look for the first matching version file in the resolved source path:
-
-- Python: `pyproject.toml` (`[project] version`), `setup.py` (`version=`), `__version__` in `__init__.py`
-- JavaScript/TypeScript: `package.json` (`"version"`). **Monorepo resolution:** When multiple `package.json` files exist (workspace root + packages), resolve version using this priority:
-  1. Package whose `name` field matches `brief.name` (e.g., the skill's target library name)
-  2. Package with a `bin` field (CLI entry point — represents the published version)
-  3. Root workspace `package.json` version (if present)
-  4. Fall back to `brief.version` if no version found. For monorepos using workspace protocols (pnpm, yarn, npm workspaces), the root `package.json` often has no `version` field — this is expected, not an error.
-- Rust: `Cargo.toml` (`[package] version`)
-- Go: `go.mod` (module version if tagged)
-
-**If a source version is found AND it differs from `brief.version`:**
-
-⚠️ Warn the user: "Brief version ({brief.version}) differs from source version ({source_version}). Using source version ({source_version})."
-
-Update the working version in context to the source version. Record the mismatch in context for the evidence report (step-08).
-
-**If no version file is found or version cannot be extracted:** keep `brief.version` as-is. No warning needed.
-
-**If source is remote and accessed via Quick tier (gh_bridge, no local files):** attempt to read the version file via `gh_bridge.read_file(owner, repo, "{version_file}")` — resolved as `gh api repos/{owner}/{repo}/contents/{version_file}` or direct file read if local (see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)) — for the primary version file of the detected language. If the read fails, keep `brief.version`.