bmad-module-skill-forge 1.3.0 → 1.4.0

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. |

package/src/skf-brief-skill/steps-c/step-01-gather-intent.md

@@ -1,6 +1,13 @@
 ---
 nextStepFile: './step-02-analyze-target.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
+descriptionVoiceExamplesFile: 'assets/description-voice-examples.md'
+headlessArgsFile: 'references/headless-args.md'
+headlessSourceAuthorityDetectionFile: 'references/headless-source-authority-detection.md'
+portfolioSimilarityCheckFile: 'references/portfolio-similarity-check.md'
+draftCheckpointFile: 'references/draft-checkpoint.md'
+validateBriefInputsScript: '{project-root}/src/shared/scripts/skf-validate-brief-inputs.py'
+emitBriefEnvelopeScript: '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
 ---
 
 # Step 1: Gather Intent
@@ -14,6 +21,7 @@ To initialize the brief-skill workflow by discovering the forge tier configurati
 - Focus only on gathering intent — do not analyze the repo yet (Step 02)
 - Do not examine source code or list exports in this step
 - Open-ended discovery facilitation — collect target repo, user intent, scope hints, skill name
+- All user-facing output in `{communication_language}`
 
 ## MANDATORY SEQUENCE
 
@@ -21,6 +29,16 @@ To initialize the brief-skill workflow by discovering the forge tier configurati
 
 ### 1. Discover Forge Tier
 
+**Pre-flight write probe.** Before any conversational state accumulates, verify `{forge_data_folder}` is writable. A read-only mount, full disk, or permissions-denied path otherwise only surfaces at step-05's atomic write — by then the user has invested 5–15 minutes. Run a single-byte write-and-remove probe:
+
+```bash
+mkdir -p "{forge_data_folder}" && \
+  printf 'probe' > "{forge_data_folder}/.skf-write-probe" && \
+  rm "{forge_data_folder}/.skf-write-probe"
+```
+
+`mkdir -p` succeeds on a pre-existing read-only mount, but the `printf > file` redirect actually attempts a write — that catches read-only, disk-full, and permissions-denied uniformly. **On any non-zero exit:** HALT (exit code 4, `halt_reason: "write-failed"`) — `"**Error:** {forge_data_folder} is not writable: {captured stderr}. Verify the path exists, the mount is writable, and there is free disk space, then re-run."` In headless mode, emit the error envelope per **step-05 §4b** with `halt_reason: "write-failed"` (skill_name is not yet resolved here — use the placeholder convention documented in §4b). On success, continue silently to the forge-tier load below.
+
 Attempt to load `{forgeTierFile}`:
 
 **If found:**
@@ -29,9 +47,13 @@ Attempt to load `{forgeTierFile}`:
 
 **Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
 
+**If found but the YAML cannot be parsed (corrupted or truncated):**
+- Display: "**Cannot read forge-tier.yaml** at `{forgeTierFile}` — the file exists but failed to parse: `{parser error message}`. The setup workflow can rewrite it cleanly. Until then, the brief workflow falls back to **Quick** tier (no extra tools assumed)."
+- Continue with `tier = "Quick"` and `tools = {}` — do not HALT. Record `tier_source: "fallback-corrupted-config"` for later diagnostics.
+
 **If not found:**
-- "**Cannot proceed.** forge-tier.yaml not found at `{forgeTierFile}`. Please run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
-- HALT — do not proceed.
+- "**Cannot proceed.** forge-tier.yaml not found at `{forgeTierFile}`. Run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
+- HALT (exit code 3, `halt_reason: "forge-tier-missing"`) — do not proceed.
 
 ### 2. Welcome and Explain
 
@@ -46,14 +68,22 @@ We'll work through this together:
 4. **Finally:** Confirm and write the brief
 
 {If tier override was applied:}
-**Your forge tier:** {override tier} (overridden from {original tier}) — this determines what compilation capabilities are available.
+**Your forge tier:** {override tier} (overridden from {original tier}) — {tier_gloss}
 {Else:}
-**Your forge tier:** {detected tier} — this determines what compilation capabilities are available.
+**Your forge tier:** {detected tier} — {tier_gloss}
+
+(Substitute `{tier_gloss}` with the matching one-liner so the user knows what the tier label means: `Quick` → "text-only extraction"; `Forge` → "AST-grep on, semantic discovery off"; `Forge+` → "AST-grep + ccc semantic discovery"; `Deep` → "full pipeline — AST + ccc + qmd portfolio search + LLM re-ranking". The tier sets the ceiling for what the downstream create-skill workflow can do; you can re-run setup later to change it.)
+
+**Wanted something different?** This workflow *creates* a new brief — a YAML scoping document for a skill that doesn't yet exist. If you meant to compile an existing brief into a skill (`/skf-create-skill`), package one for distribution (`/skf-export-skill`), or just ask SKF a question, type `cancel` at any prompt and run that workflow instead.
 
 Let's get started."
 
 ### 3. Gather Target Repository
 
+This section has three sub-flows. Execute exactly one branch — 3.2 *or* 3.3 — based on the user's response in 3.1, then end with the shared confirmation. Do not mix branches.
+
+#### 3.1 Collect target
+
 "**What repository or documentation do you want to create a skill for?**
 
 Provide one of:
@@ -61,33 +91,61 @@ Provide one of:
 - A **local path** (e.g., `/path/to/project`)
 - **Documentation URLs** for a docs-only skill (e.g., `https://docs.stripe.com/api`) — use this when no source code is available (SaaS, closed-source)
 
+Or type `cancel` / `exit` / `[X]` to leave without writing anything.
+
 **Target:**"
 
-Wait for user response.
+Wait for user response. Branch on the response:
+
+- Empty input, `cancel`, `exit`, `[X]`, `q`, or `:q` → Display `"Cancelled — no brief was written."` and HALT (exit code 6, `halt_reason: "user-cancelled"`). Cancellation here is non-destructive — no files have been written yet by step-01. Headless mode never reaches this branch (the GATE in §8 short-circuits the interactive sub-flows).
+- Documentation URLs only (no source location) → §3.2
+- GitHub URL or local filesystem path → §3.3
+- Any other free-form question (e.g. "what is this?", "show me an example", "how does SKF work?") → answer briefly, re-display the prompt
+
+#### 3.2 Branch — Documentation URLs (docs-only)
 
-**If user provides documentation URLs (not a repo):**
 - Set `source_type: "docs-only"` in the brief data
 - Collect one or more doc URLs with optional labels
-- Note: `source_authority` will be forced to `community` (T3 external documentation)
+- HEAD-check the collected URLs in parallel — do not loop sequentially. Issue all N `curl -sI {url}` (or equivalent) calls in a **single message with N parallel Bash calls**, then process the responses together. Each call must use a 5-second timeout (`curl -sI --max-time 5 {url}`) to bound worst-case wall-time on hung hosts. Per response:
+  - On 2xx/3xx: silently accept.
+  - On 4xx/5xx, DNS failure, or timeout: warn `"Could not reach {url} — {status or error}. Confirm the URL is correct, or proceed anyway."` Interactive: re-prompt for a corrected URL or `[K] Keep anyway`. Headless: keep the URL and log the warning — the brief still records it but the failure is now visible at brief-creation time instead of materializing hours later in skf-create-skill.
+- Set `source_authority: "community"` (forced for docs-only — T3 external documentation; the §3.3 source-authority prompt is skipped)
 - Note: `source_repo` becomes optional (can be set to the main doc site URL for reference)
 
-**If user provides a GitHub URL or local path:**
+Skip §3.3 and continue at "Confirm the target" below.
+
+#### 3.3 Branch — Source (GitHub URL or local path)
+
 - Set `source_type: "source"` (default)
+- **Pre-validate the target before continuing.** Issue these probes in a single message with parallel Bash calls:
+  - **GitHub URL:** `curl -sI --max-time 5 {url}`. On a 4xx (typically 404 for a typo'd repo or org), warn `"GitHub returned {status} for {url} — confirm the URL is correct."` and re-prompt. On 2xx, accept.
+  - **GitHub URL, in parallel:** `gh api repos/{owner}/{repo} --jq .name` (5-second timeout via `gh api --hostname github.com --method GET ... ` or just rely on default). On 403/404, warn `"GitHub API returned {status} for {owner}/{repo} — the repo may be private or your token may not have access. Step-02 will HALT here if this is not resolved. Continue anyway, or fix and re-prompt?"` and offer `[K] Keep anyway` / re-prompt for a corrected URL. Do not HALT — the canonical HALT still happens in step-02 §1, but surfacing access failures at URL-entry time prevents 5+ minutes of intent investment getting lost. On any other error (network failure, missing binary), log silently and let `gh auth status` below catch it. On 2xx, accept silently.
+  - **GitHub URL, in parallel:** `gh auth status` — if it reports unauthenticated or the binary is missing, warn `"GitHub CLI not authenticated; step-02 will HALT when it tries to fetch the tree. Run 'gh auth login' before continuing, or supply a local clone path instead."` (Do not HALT here — let the user choose to fix or proceed; the canonical HALT still happens in step-02 §1's failure-class triage.)
+  - **Local path:** verify the directory exists (`test -d {path}`). If not, warn `"Local path {path} does not exist."` and re-prompt.
 - Optionally ask: "Are there any documentation URLs you'd like to include for supplemental context? (These will be fetched as T3 external references.)"
 - If yes: collect doc URLs into `doc_urls`
 
-**Source authority (for all source-type skills):**
+**Source authority (this branch only — docs-only forces `community` in §3.2):**
+
+**Interactive only** — skip this prompt entirely when `{headless_mode}` is true; the GATE in §8 resolves source_authority headlessly via the detection branch documented there.
+
 "**Are you the maintainer of this library, or creating a community skill?**"
 - If maintainer: set `source_authority: "official"`
 - If community user: set `source_authority: "community"` (default)
 - If internal/proprietary: set `source_authority: "internal"`
 
-Default to `"community"` if user does not specify or skips. For `docs-only` skills, `source_authority` is always forced to `"community"`.
+Default to `"community"` if user does not specify or skips.
+
+---
 
 Confirm the target.
 
 ### 3b. Gather Target Version
 
+This step only collects `target_version` and validates its shape with the regex below — auto-detection runs in step-02 and precedence/invariant resolution lands in step-05's writer script. The canonical precedence rules live in `references/version-resolution.md`; load it from step-02 / step-05 only when the relevant section needs it.
+
+**Headless:** if `target_version` was supplied as an argument, store it and skip the interactive prompt below. If `doc_urls` were also supplied, treat the version-vs-doc-URL confirmation prompt as auto-confirmed (Y).
+
 "**Are you targeting a specific version of this library?**
 (Leave blank to auto-detect from source)"
 
@@ -96,7 +154,7 @@ Confirm the target.
 
 Wait for user response.
 
-**If user provides a version:** Store as `target_version`. Set `version` to this value.
+**If user provides a version:** Validate the shape against `^v?\d+\.\d+\.\d+([.\-+][0-9A-Za-z][0-9A-Za-z.\-+]*)?$` (full X.Y.Z form, with optional `v` prefix and pre-release / build suffix; CalVer like `2024.04.01` accepted; partial forms like `1`, `1.2`, `v2`, `latest` rejected). On a match, store as `target_version` and set `version` to this value. On a non-match, warn `"'{value}' doesn't look like semver — write the explicit triple (e.g. 1.0.0). Fix it now or skip auto-detection?"` and re-prompt for a corrected value or blank to fall through to step-02 auto-detection.
 **If blank:** Proceed without `target_version` — version will be auto-detected in step 02.
 
 {If target_version was set AND doc_urls are being collected (either docs-only primary or supplemental):}
@@ -104,10 +162,22 @@ Wait for user response.
 "**You're targeting version {target_version}. Do these documentation URLs correspond to that version?** [Y/N]"
 
 - **If Y:** Proceed.
-- **If N:** "Please provide the correct documentation URLs for version {target_version}." Re-collect doc_urls.
+- **If N:** "Provide the correct documentation URLs for version {target_version}." Re-collect doc_urls.
 
 ### 4. Gather User Intent
 
+**First-timer rail (interactive only).** Before the intent prompt, check whether `{forge_data_folder}/` contains any prior briefs:
+
+```bash
+find "{forge_data_folder}" -maxdepth 2 -name "skill-brief.yaml" -print -quit
+```
+
+If the command produces any output, skip this rail silently — repeat users don't need the warm-up. If it produces no output (the user has never produced a brief), ask:
+
+"**Want to see a few example descriptions first?** [Y/N] (Helpful if this is your first time — I'll show the voices we use so you have an anchor for what 'good intent' produces.)"
+
+On `[Y]`: load `{descriptionVoiceExamplesFile}` and present the five examples verbatim with a one-line preface (`"Each example shows a different voice — yours doesn't have to match any specific one."`). On `[N]` or empty: proceed silently.
+
 "**What's your intent for this skill?**
 
 Help me understand:
@@ -140,6 +210,34 @@ This will be used for the output directory and file naming. Want to use this nam
 
 Wait for confirmation or alternative.
 
+**Collision check (interactive and headless):** before locking the name, check whether `{forge_data_folder}/{name}/skill-brief.yaml` already exists. If it does:
+
+- Interactive: generate 1–3 non-colliding candidate alternates by scanning sibling directories under `{forge_data_folder}/`. Apply each rule that fires; skip rules whose precondition isn't met:
+  1. `{name}-v{N}` where `N` is the smallest positive integer that doesn't collide (e.g. `{name}-v2`, `{name}-v3`) — always applies
+  2. `{name}-{target_version}` if `target_version` is set and the suffix wouldn't collide (e.g. `marked-1.2.3`)
+  3. `{name}-{source_authority}` if `source_authority` is not `community` (e.g. `marked-internal` for an internal fork)
+
+  Number the surviving alternates `[1] [2] [3]…` in the order produced (1 alternate for a community-authority brief with no `target_version`; 2–3 otherwise). Then present:
+
+  ```
+  **Heads up — a brief for `{name}` already exists at `{path}`.**
+
+  Suggested alternates (none collide):
+    [1] {alternate-1}
+    {if a second alternate was produced:} [2] {alternate-2}
+    {if a third alternate was produced:} [3] {alternate-3}
+
+  Pick a number to use that name, type a different name, or press Enter to keep `{name}` and let step-05 §2b handle the overwrite prompt.
+  ```
+
+  On a numbered choice, replace `{name}` with the chosen alternate. On Enter, fall through to step-05's overwrite gate. On any other input, treat as a new candidate name and re-run the collision check against it.
+
+- Headless: log `"warn: skill name '{name}' collides with existing brief at {path}"` and proceed; the existing-brief overwrite policy in step-05 §2b is the canonical gate (HALT with `overwrite-cancelled` unless `force` was supplied).
+
+**Portfolio-similarity check.** When the flow is interactive AND forge tier is `Deep` AND `tools.qmd` is true in `forge-tier.yaml`, load `{portfolioSimilarityCheckFile}` and follow the procedure there to catch semantic near-duplicates that exact-name collision misses. Otherwise (headless, or tier below Deep, or qmd unavailable) skip the load — the check does not run.
+
+**Draft-resume check.** When the flow is interactive AND `{forge_data_folder}/{name}/.brief-draft.json` exists AND no `skill-brief.yaml` sits beside it, load `{draftCheckpointFile}` and follow Half 1 (Resume Check). On `[Y]` resume, the procedure jumps directly to §8 with prior answers restored — **the rest of §6, all of §7, and all of §7b are skipped**. Otherwise (headless, or no draft file, or a finished brief sits beside the draft) skip the load and continue with §6 normally.
+
 ### 7. Summarize Gathered Intent
 
 "**Here's what I've captured:**
@@ -158,19 +256,71 @@ Wait for confirmation or alternative.
 
 Ready to analyze the target repository?"
 
+**Draft checkpoint.** When the flow is interactive, load `{draftCheckpointFile}` (or reuse it if already loaded for the §6 resume check) and follow Half 2 (Checkpoint Write) to persist the captured state atomically. Headless mode skips this — the run completes in a single invocation, no resume is meaningful.
+
+### 7b. Synthesize Skill Description
+
+The schema's `description` field is 1-3 sentences and surfaces in skill registries — it must exist by the time step-04 presents the brief. Synthesize it explicitly here, while the user's intent is fresh, instead of letting it fall out implicitly later.
+
+Compose a candidate 1-3 sentence description from the gathered material. **Write like a human library maintainer would** — what does an agent get from this skill, and when should it route here? Two facts must come through (what the skill is, when to use it); everything else is voice. Resist filling in the same skeleton every time.
+
+Load `{descriptionVoiceExamplesFile}` for the five voice examples (range of acceptable leads, structures, and trigger phrasings) and the "do not template-stamp" guidance, then compose in that spirit. The asset documents what "in that spirit" means; the gathered material to draw on is the target repo, the user's intent, the version if set, and any scope hints.
+
+Present:
+
+"**Proposed skill description:**
+
+> {synthesized description}
+
+This is the text agents read when deciding whether to route to your skill — it sits in the registry row alongside dozens of other skills. Specific triggers ('use when…', 'reach for this when…') help agents match real user requests; generic descriptions blend in and get skipped. Edit, replace, or accept as-is."
+
+Wait for user confirmation or alternative.
+
+**Soft sentence-count check (interactive only).** Before storing the accepted text, count terminal sentence punctuation (`.`, `!`, `?` followed by whitespace or end-of-string) — abbreviations like `e.g.` will inflate the count slightly but the check is a soft nudge, not a HALT. If the count exceeds 3, present:
+
+"**Heads up — that description reads as ~{N} sentences.** The conventional norm is 1-3 (it surfaces in registry rows alongside other skills, where length crowds out the trigger phrase). Tighten now, or accept as-is?"
+
+On `tighten` or a fresh edit: re-prompt for the description. On `accept` or any non-edit response: store the accepted text and proceed. Counts of 1-3 store silently.
+
+Store the accepted text as the brief's `description` field. The same field is re-presented in step-04 §3 for a final review pass — refinements there flow back to this value.
+
+**Headless:** if the `intent` argument was supplied, load `{descriptionVoiceExamplesFile}` and run the same synthesis against it (in `{document_output_language}`), then store the result. If `intent` was not supplied, fall back in priority order:
+
+1. **GitHub repo description** — when `target_repo` is a GitHub URL, fetch `gh api repos/{owner}/{repo} --jq .description` (5-second timeout). If a non-empty description comes back, load `{descriptionVoiceExamplesFile}` and synthesize using the GitHub description as the seed in place of `intent`. Write the synthesized description in `{document_output_language}` regardless of the seed's language (the seed may be in any language; the output's language is dictated by the workflow's document-output configuration). Log `"info: description seeded from GitHub repo description"`. (The full `gh api repos` response is fetched again in step-02 §1; this lightweight `--jq .description` call only retrieves the one field.)
+2. **Generic stub** — when no GitHub description is available (local-path target, GitHub repo with empty description, or `gh api` fails): derive from `target_repo` + `skill_name` (`"Use the {skill_name} skill to work with code or content from {target_repo}."`) — the generic fallback does not need the asset — and log `"warn: description synthesized without intent or repo description — narrow registry text."`
+
 ### 8. Present MENU OPTIONS
 
-Display: "**Select:** [C] Continue to Target Analysis"
+Display: "**Select:** [C] Continue to Target Analysis · [X] Cancel and exit"
 
 #### Menu Handling Logic:
 
 - IF C: Load, read entire file, then execute {nextStepFile}
+- IF X: Treat as user-cancellation. Display `"Cancelled — no brief was written."` and HALT (exit code 6, `halt_reason: "user-cancelled"`). When `{headless_mode}` is true the GATE auto-proceeds and never reaches this branch — `[X]` is interactive-only. Cancellation here is non-destructive: no files have been written yet by step-01.
 - IF Any other: Help user, then [Redisplay Menu Options](#8-present-menu-options)
 
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
-- **GATE [default: use args]** — If `{headless_mode}`: consume pre-supplied arguments (target_repo, skill_name, scope_hint, language_hint) and auto-proceed. If required args missing, HALT: "headless mode requires target_repo and skill_name arguments."
+- **GATE [default: use args]** — If `{headless_mode}`, consume pre-supplied arguments and auto-proceed. The full argument set (required/optional, defaults, halt codes, enum values) is documented in `{headlessArgsFile}` — load it now if you need to look up a specific argument. Validation is delegated to `{validateBriefInputsScript}`; the table is the canonical operator-facing documentation, the script enforces it.
+
+  **Preset merge (before validation).** If the headless args include a `preset` field, load `{sidecar_path}/brief-presets/{preset}.yaml` and merge its contents as defaults — explicit args override preset values, key by key. The preset file is YAML; if it does not exist, log `"warn: preset '{name}' not found at {path} — proceeding without preset"` and continue (do not HALT). If it parses but contains unknown fields, log per-field warnings and pass through unchanged (the validator's KNOWN_FIELDS check will catch any that survive). Drop the `preset` key itself from the merged dict before passing to the validator (it is consumed at this level and is not a brief field).
+
+  **Delegate validation to `{validateBriefInputsScript}`** instead of reasoning through the table rules in prose:
+
+  ```bash
+  echo '<headless-args-as-json>' | uv run {validateBriefInputsScript}
+  ```
+
+  The script returns a JSON envelope: `{valid, errors[], warnings[], normalized, halt_reason}`. Apply the result deterministically:
+
+  - **`valid: false`** — emit the error envelope per **step-05 §4b** with the script's `halt_reason` (`"input-missing"` for absent required args / docs-only without doc_urls; `"input-invalid"` for enum violations, malformed semver, malformed kebab-case skill_name). Surface `errors[]` to the operator log so the failure is debuggable. HALT.
+  - **`valid: true`** — consume the `normalized` object as the source of truth (it has defaults applied per the table). Surface `warnings[]` to the operator log but do not HALT. Auto-proceed.
+
+  The script's `KNOWN_FIELDS` set must stay in sync with the table in `{headlessArgsFile}`.
+
+  **Headless source-authority detection.** After consuming `normalized`, if `source_authority` is absent AND `source_type=source` AND `target_repo` is a GitHub URL, load `{headlessSourceAuthorityDetectionFile}` and follow the procedure there. Otherwise (precondition unmet, value already supplied, docs-only, or local-path) skip the load — `community` is the implicit default for the unmet branches.
+
 - ONLY proceed to next step when user selects 'C'
 
 ## CRITICAL STEP COMPLETION NOTE