bmad-module-skill-forge 1.9.0 → 2.0.1

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

@@ -19,7 +19,7 @@
 | 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"`                                                                                                                                                    |
+| doc_urls           | array  | `{url, label, source?}` objects                  | Documentation URLs for T3 content. Required when `source_type: "docs-only"`. Optional `source` provenance enum: `language-registry` (registry-guaranteed corpus) \| `readme-detection` \| `homepage` \| `pages-api` \| `docs-folder` |
 | `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.                                                   |

package/src/skf-brief-skill/customize.toml

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-brief-skill.
+# Team overrides:     _bmad/custom/skf-brief-skill.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-brief-skill.user.toml (under {project-root})
 
 [workflow]
 
@@ -42,3 +44,15 @@ persistent_facts = [
 description_voice_examples_path = ""
 scope_templates_path = ""
 brief_schema_path = ""
+
+# Pipeline-integration hook invoked once the brief is written and the result
+# contract is finalized (write-brief.md, step 5), before the workflow chains to
+# the terminal health-check step. The command is called as:
+#   <on_complete> --result-path=<absolute_path_to_skill-brief.yaml>
+# Useful for chaining into create-skill, Slack notifications, dashboard ingest,
+# or CI hooks. Override wins. Failures are logged to workflow_warnings[] but
+# never fail the workflow.
+#
+# Empty string = no-op (default).
+
+on_complete = ""

package/src/skf-brief-skill/references/analyze-target.md

@@ -10,24 +10,21 @@ detectWorkspacesProbeOrder:
 detectLanguageProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-language.py'
   - '{project-root}/src/shared/scripts/skf-detect-language.py'
+emitBriefEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
 
 # Step 2: Analyze Target
 
-## STEP GOAL:
-
-To analyze the target repository by resolving its location, reading its structure, detecting the primary language, and listing top-level modules and exports — providing the user with a factual foundation for scoping decisions.
-
 ## Rules
 
-- Focus only on analysis — do not define scope yet (Step 03)
 - Do not make scoping decisions or recommendations
 - Do not hallucinate or guess about repository contents
-- All user-facing output in `{communication_language}`
 
-## MANDATORY SEQUENCE
+## Sequence
 
 ### 1. Resolve Target Location
 
@@ -56,15 +53,15 @@ To analyze the target repository by resolving its location, reading its structur
 
 **On API failure (non-200 from `gh api`):**
 
-Distinguish the failure class before reporting:
-- Auto-run `gh auth status` and capture its output. If it reports an unauthenticated state or expired token: HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** GitHub CLI is not authenticated. `gh auth status` says: `{captured output}`. Run `gh auth login` and retry."
-- If `gh auth status` reports authenticated but the call still failed (404/403): HALT (exit code 3, `halt_reason: "target-inaccessible"`) — "**Error:** Cannot access repository at `{url}`. The CLI is authenticated but the API returned `{status}`. Check the URL and that the account has access to private repositories if applicable."
-- If `gh auth status` itself fails to run (binary missing): HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** `gh` CLI not found on PATH. Install it from <https://cli.github.com> and re-run."
+Distinguish the failure class before reporting. In headless mode, every branch below emits the error envelope per **step 5 §4b** with its stated `halt_reason` before the HALT (pass the resolved `{skill_name}`, or the `"unknown"` placeholder documented in §4b if it is not yet set):
+- Auto-run `gh auth status` and capture its output. If it reports an unauthenticated state or expired token: emit the error envelope per **step 5 §4b** with `halt_reason: "gh-auth-failed"`, then HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** GitHub CLI is not authenticated. `gh auth status` says: `{captured output}`. Run `gh auth login` and retry."
+- If `gh auth status` reports authenticated but the call still failed (404/403): emit the error envelope per **step 5 §4b** with `halt_reason: "target-inaccessible"`, then HALT (exit code 3, `halt_reason: "target-inaccessible"`) — "**Error:** Cannot access repository at `{url}`. The CLI is authenticated but the API returned `{status}`. Check the URL and that the account has access to private repositories if applicable."
+- If `gh auth status` itself fails to run (binary missing): emit the error envelope per **step 5 §4b** with `halt_reason: "gh-auth-failed"`, then HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** `gh` CLI not found on PATH. Install it from <https://cli.github.com> and re-run."
 
 **For local paths:**
 - Verify the directory exists
 - List the directory tree
-- If path doesn't exist: **HALT** — "**Error:** Directory not found at {path}. Verify the path is correct."
+- If the path does not exist: HALT (exit code 3, `halt_reason: "target-inaccessible"`) — "**Error:** Directory not found at {path}. Verify the path is correct." In headless mode, emit the error envelope per **step 5 §4b** with `halt_reason: "target-inaccessible"` before the HALT (pass the resolved `{skill_name}`, or the `"unknown"` placeholder documented in §4b if it is not yet set), matching the GitHub-target failure branches above so a missing local path surfaces the same `SKF_BRIEF_RESULT_JSON` failure class.
 
 Display: "**Resolving target...**"
 
@@ -138,7 +135,9 @@ The script returns `{language, confidence, detection_source, fallback_to_extensi
 **Confidence:** {confidence}
 **Detection source:** {detection_source}"
 
-If `confidence` is `low` (or `unknown` is returned for `language`): flag for user override in step 03 §4.
+**Headless language override.** If `language_hint` was supplied as a headless argument, use it as the confirmed `{language}` (overriding the detected value) and carry it forward to §4 and step 03. The detector still runs so the "Detected language" line reflects what the source signals, but the explicit hint wins and the step 03 §4 low-confidence override does not fire. When `language_hint` is absent, carry the detected `{language}` forward.
+
+If `confidence` is `low` (or `unknown` is returned for `language`) and no `language_hint` was supplied: flag for user override in step 03 §4.
 
 ### 4. List Top-Level Modules and Exports
 
@@ -288,13 +287,9 @@ Pause briefly for user input. If the user provides corrections or asks questions
 
 - After analysis report is presented to user and any corrections addressed, load, read entire file, then execute {nextStepFile}
 
-#### EXECUTION RULES:
+#### Execution rules:
 
 - This is a soft auto-proceed step — present the pause prompt, wait briefly for user input
 - If user provides corrections: address them, then proceed
 - If no user input after a brief pause: proceed directly to step 03
 
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the analysis is complete and the summary has been presented to the user will you load and read fully `scope-definition.md` to begin scope definition.
-

package/src/skf-brief-skill/references/confirm-brief.md

@@ -1,7 +1,6 @@
 ---
 nextStepFile: 'write-brief.md'
 reviseStepFile: 'scope-definition.md'
-briefSchemaFile: 'assets/skill-brief-schema.md'
 advancedElicitationSkill: '/bmad-advanced-elicitation'
 partyModeSkill: '/bmad-party-mode'
 ---
@@ -10,17 +9,11 @@ partyModeSkill: '/bmad-party-mode'
 
 # Step 4: Confirm Brief
 
-## STEP GOAL:
-
-To present the complete skill brief in human-readable format, highlighting all fields that will be written to skill-brief.yaml, and obtain explicit user approval before writing.
-
 ## Rules
 
-- Focus only on presenting and confirming — do not write files yet (Step 05)
 - Do not proceed without explicit user approval (P2 confirmation gate)
-- All user-facing output in `{communication_language}`
 
-## MANDATORY SEQUENCE
+## Sequence
 
 ### 1. Assemble Complete Brief
 
@@ -163,15 +156,9 @@ Display: **Select an Option:** [R] Revise Scope [A] Advanced Elicitation [P] Par
 - IF X: Treat as user-cancellation. Display `"Cancelled — no brief was written."` and HALT (exit code 6, `halt_reason: "user-cancelled"`). Cancellation here is non-destructive — step 5 has not run, no skill-brief.yaml file exists yet. `[X]` is interactive-only; the headless GATE never reaches this branch.
 - IF Any other comments or queries: help user respond, apply any field adjustments, re-present brief if changed, then [Redisplay Menu Options](#5-present-menu-options)
 
-#### EXECUTION RULES:
+#### Execution rules:
 
-- ALWAYS halt and wait for user input after presenting menu
 - **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Confirm, log: "headless: auto-confirm brief"
-- ONLY proceed to write step when user selects 'C'
 - After other menu items execution, return to this menu
 - User can chat, request field changes, or ask questions — always respond and then redisplay menu
 
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN C is selected and the user has explicitly approved the brief will you load and read fully `write-brief.md` to write the skill-brief.yaml file.
-

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

@@ -4,31 +4,31 @@ The `.brief-draft.json` file at `{forge_data_folder}/{skill-name}/.brief-draft.j
 
 **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.
+The two halves of the lifecycle (resume after the target is confirmed in §3, 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)
+## Half 1 — Resume Check (loaded from §3 after the target is confirmed)
 
-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 5's overwrite gate is the right control point).
+Keyed on the confirmed **target**, not the derived skill name, so the offer can fire right after §3 — before the returning user re-answers version (§3b), intent (§4), or scope (§5), which is exactly the state a draft restores. The caller (gather-intent §3) has already globbed `{forge_data_folder}/*/.brief-draft.json`, kept only drafts whose `target_repo` equals the confirmed target (or whose `doc_urls` contain it, for docs-only) with no `skill-brief.yaml` beside them, and selected the most-recently-modified survivor. Its directory basename is the candidate skill `name`. Present the resume prompt for that draft.
 
-When the precondition is met, present:
+When a live draft is found, 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)
+  [N] Start fresh (ignore this draft and keep gathering)
 ```
 
 ### `[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**.
+Restore the candidate `name` (the matched draft's directory basename), then 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 §3b, §4, §5, §6, §7, and §7b** — so the version, intent, scope, and description the draft already holds are never re-gathered.
 
-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 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. §6 is skipped too, so the restored `name` is used as-is — it already cleared the collision and portfolio-similarity checks in the session that wrote the draft.
 
 The user can still revise any field at step 4 §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.
+Leave the draft in place and continue forward to §3b — the normal gather flow (§3b version, §4 intent, §5 scope, §6 name) resumes, and the §6 collision / portfolio-similarity checks run in their usual place. Do not delete the draft here: the skill name has not been chosen yet, so there is nothing to key a deletion on. If the user lands on the same name, step 5's atomic write overwrites the stale draft; otherwise it stays a harmless orphan that the resume check offers again on a future run targeting the same repo.
 
 ## Half 2 — Checkpoint Write (loaded from §7 after summary confirmation)
 

package/src/skf-brief-skill/references/gather-intent.md

@@ -2,7 +2,6 @@
 nextStepFile: 'analyze-target.md'
 ratifyTargetFile: 'confirm-brief.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'
@@ -22,10 +21,6 @@ emitBriefEnvelopeProbeOrder:
 
 # Step 1: Gather Intent
 
-## STEP GOAL:
-
-To initialize the brief-skill workflow by discovering the forge tier configuration, then gathering the user's target repository, intent, and any upfront scope hints for skill creation.
-
 ## Rules
 
 - Focus only on gathering intent — do not analyze the repo yet (Step 02)
@@ -33,7 +28,7 @@ To initialize the brief-skill workflow by discovering the forge tier configurati
 - Open-ended discovery facilitation — collect target repo, user intent, scope hints, skill name
 - All user-facing output in `{communication_language}`
 
-## MANDATORY SEQUENCE
+## Sequence
 
 ### 1. Discover Forge Tier
 
@@ -61,6 +56,7 @@ Attempt to load `{forgeTierFile}`:
 
 **If not found:**
 - "**Cannot proceed.** forge-tier.yaml not found at `{forgeTierFile}`. Run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
+- In headless mode, emit the error envelope per **step 5 §4b** with `halt_reason: "forge-tier-missing"` (`skill_name` is not yet resolved here — use the `"unknown"` placeholder convention documented in §4b).
 - HALT (exit code 3, `halt_reason: "forge-tier-missing"`) — do not proceed.
 
 ### 1b. Auto Mode Check
@@ -72,7 +68,7 @@ Attempt to load `{forgeTierFile}`:
 1. **Load upstream brief path:** Read `brief_path` from the pipeline data context (passed by the forger from AN's `SKF_ANALYZE_RESULT_JSON` `brief_paths[]`). If `brief_path` is not available, HARD HALT with exit code 2 (`input-missing`): "**Auto mode requires `brief_path` in pipeline context — AN must run before BS[auto].**"
 2. **Load source repo:** Read `source_repo` from the pipeline data context (the target repo URL or path, forwarded by the forger). If not available, attempt to extract it from the upstream brief at `brief_path`.
 3. "**Auto mode activated — bypassing interactive brief workflow.**"
-4. **Route to auto-brief:** Load, read fully, then execute `references/step-auto-brief.md`. **STOP HERE** — do not continue to §2 or any subsequent section.
+4. **Route to auto-brief:** Load, read fully, then execute `references/step-auto-brief.md`, and hand off there — do not fall through to §2 or any subsequent section of this file.
 
 **IF `{auto_mode}` is NOT true:**
 Continue to §2 as normal — the entire interactive flow below is unchanged.
@@ -85,12 +81,6 @@ Continue to §2 as normal — the entire interactive flow below is unchanged.
 
 I'll help you define exactly what to skill and produce a `skill-brief.yaml` that drives the create-skill compilation workflow.
 
-We'll work through this together:
-1. **Now:** Understand what you want to skill and why
-2. **Next:** Analyze the target repo structure
-3. **Then:** Define scope boundaries
-4. **Finally:** Confirm and write the brief
-
 {If tier override was applied:}
 **Your forge tier:** {override tier} (overridden from {original tier}) — {tier_gloss}
 {Else:}
@@ -106,8 +96,12 @@ This section has four sub-flows. Execute exactly one branch — 3.1a *or* 3.2 *o
 
 #### 3.1 Collect target
 
+**Open-floor opening.** Lead with an open invitation so an expert can state everything in one breath rather than being walked through seven discrete prompts — costs almost nothing token-wise and sharply improves the conversational feel of this, the most question-heavy mode. A first-timer who pastes only a bare URL still gets the full guided sequence below, unchanged.
+
 "**What repository or documentation do you want to create a skill for?**
 
+Tell me everything you have — the repo or docs, what you want to skill and why, any scope or version thoughts. Or just paste a URL and we'll go from there.
+
 Provide one of:
 - A **GitHub URL** (e.g., `https://github.com/org/repo`)
 - A **local path** (e.g., `/path/to/project`)
@@ -118,7 +112,7 @@ Or type `cancel` / `exit` / `[X]` to leave without writing anything.
 
 **Target:**"
 
-Wait for user response. Branch on the response:
+Wait for user response. **Parse the response for any of the fields the later sections collect** — `target_version` (§3b), intent (§4), scope hints (§5), source authority (§3.3), a proposed name (§6) — and pre-fill every field the user covered, holding them in workflow context. Sections §3b/§4/§5/§6/§7b then **acknowledge a pre-filled field instead of re-asking** ("I noted you're targeting v4.0.0"), and prompt only for the gaps. An expert who stated it all collapses to the §3.1 target branch plus the §7b description confirmation; a bare URL falls through to the full sequence. Then branch on the response for the target itself:
 
 - 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 1. Headless mode never reaches this branch (the GATE in §8 short-circuits the interactive sub-flows).
 - Path that resolves to an existing `skill-brief.yaml` (file path ending in `skill-brief.yaml` that exists, OR a directory containing a `skill-brief.yaml`) → §3.1a
@@ -218,6 +212,20 @@ Default to `"community"` if user does not specify or skips.
 
 Confirm the target.
 
+**Draft-resume check (interactive only).** Now that the target is confirmed — and *before* the version prompt (§3b), intent (§4), or scope (§5) spend the user's time — offer to resume an in-progress draft that already covers this exact target, so a returning user re-types nothing. Keying on the target (not the not-yet-derived skill name) is what lets the offer fire this early. When the flow is interactive:
+
+1. **Cheap pre-filter** — list any draft file that mentions the confirmed target at all:
+
+   ```bash
+   grep -lF "{target}" "{forge_data_folder}"/*/.brief-draft.json 2>/dev/null
+   ```
+
+   `{target}` is the repo URL, local path, or primary doc URL just entered. No output → no draft; skip straight to §3b.
+
+2. **Confirm each candidate on the target *field*, not free text.** Read the candidate draft's JSON and keep it only if its `target_repo` equals the confirmed target (source targets) or the target appears in its `doc_urls` (docs-only) — this rejects a draft that merely mentions the URL in its `intent` or `description`. Drop any candidate that has a finished `skill-brief.yaml` in the same directory (that brief is done; step 5's overwrite gate owns it).
+
+3. If one or more live drafts survive, load `{draftCheckpointFile}` and follow Half 1 (Resume Check) against the most-recently-modified survivor; its directory basename is the candidate skill name. On `[Y]` resume, Half 1 restores every gathered answer and jumps straight to §8 — **§3b, §4, §5, §6, §7, and §7b are all skipped**. Otherwise (headless, no surviving draft, or every match already has a finished brief beside it) skip the load and continue to §3b.
+
 ### 3b. Gather Target Version
 
 This step only collects `target_version` and validates its shape with the regex below — auto-detection runs in step 2 and precedence/invariant resolution lands in step 5's writer script. The canonical precedence rules live in `references/version-resolution.md`; load it from step 2 / step 5 only when the relevant section needs it.
@@ -267,6 +275,8 @@ Take your time — the more context you share, the better the brief."
 
 Wait for user response. Ask follow-up questions if intent is unclear.
 
+**Capture, don't interrupt.** If the user volunteers an out-of-scope aside while answering — "the v3 API is totally different", "we're deprecating the auth module next quarter" — do not redirect the conversation to chase it. Silently note it as a candidate `scope.notes` line (carried forward into the brief's `scope.notes` at step 3) and continue the current prompt. These unprompted asides are often the most useful scoping signal; the cost of losing them when the conversation moves on is higher than the cost of one stored line.
+
 ### 5. Capture Scope Hints
 
 If the user mentioned scope preferences in their intent response, acknowledge them:
@@ -314,7 +324,7 @@ Wait for confirmation or alternative.
 
 **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.
+(The resume-a-draft offer for a returning user fires earlier, right after the target is confirmed in §3 — see the §3 "Draft-resume check" — so the intent, scope, and description a draft holds are spared *before* they get re-gathered here.)
 
 ### 7. Summarize Gathered Intent
 
@@ -334,7 +344,7 @@ 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.
+**Draft checkpoint.** When the flow is interactive, load `{draftCheckpointFile}` (or reuse it if already loaded for the §3 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
 
@@ -377,9 +387,8 @@ Display: "**Select:** [C] Continue to Target Analysis · [X] Cancel and exit"
 - 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 1.
 - IF Any other: Help user, then [Redisplay Menu Options](#8-present-menu-options)
 
-#### EXECUTION RULES:
+#### Execution rules:
 
-- ALWAYS halt and wait for user input after presenting menu
 - **Resolve `{validateBriefInputsHelper}`** from `{validateBriefInputsProbeOrder}`; first existing path wins. HALT if no candidate exists.
 
 - **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 `{validateBriefInputsHelper}`; the table is the canonical operator-facing documentation, the script enforces it.
@@ -410,9 +419,3 @@ Display: "**Select:** [C] Continue to Target Analysis · [X] Cancel and exit"
 
   **Headless source-authority detection (derive route only — no `from_brief`).** 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
-
-ONLY WHEN C is selected and target repository is confirmed will you load and read fully `analyze-target.md` to execute target analysis.
-

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

@@ -12,7 +12,7 @@ Loaded by step 1 §8 only when `{headless_mode}` is true. Canonical operator-fac
 | `source_authority` | no | detected | `official` / `community` / `internal`. When absent and `target_repo` is a GitHub URL, step 1 §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 2 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 2/03 |
+| `language_hint` | no | — | Overrides language detection — consumed at step 2 §3: the detector still runs for the informational Detected-language line, but the hint becomes the confirmed language and the step 3 §4 low-confidence override does not fire |
 | `scope_type` | no | heuristic | `full-library` / `specific-modules` / `public-api` / `component-library` / `reference-app` / `docs-only`. When absent and `source_type=source`, step 3 §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 3 §3) |
 | `exclude` | no | — | Comma-separated globs (used by step 3 §3) |

package/src/skf-brief-skill/references/health-check.md

@@ -9,25 +9,4 @@ nextStepFile: 'shared/health-check.md'
 
 # Step 6: Workflow Health Check
 
-## STEP GOAL:
-
-Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of brief-skill — after the shared health check completes, the workflow is fully done.
-
-## Rules
-
-- No user-facing reports, file writes, or result contracts in this step — those belong in step 5
-- Delegate directly to `{nextStepFile}` with no additional commentary
-- Do not attempt any other action between loading this step and executing `{nextStepFile}`
-- All user-facing output in `{communication_language}`
-
-## MANDATORY SEQUENCE
-
-Load `{nextStepFile}`, read it fully, then execute it.
-
-## Completion criteria
-
-This is the terminal step of brief-skill. The workflow is complete when `{nextStepFile}` returns control — do not transition to any further step.
-
-## CRITICAL STEP COMPLETION NOTE
-
-Step 06 is the terminal stage of brief-skill. After `{nextStepFile}` returns control, the brief-skill workflow is fully complete — do not re-enter step 5 or step 6, do not load any further step file, and do not loop back into the workflow.
+This is the terminal step of brief-skill. Load `{nextStepFile}`, read it fully, then execute it — do nothing else here (no user-facing reports, file writes, or result contracts; those were step 5). After `{nextStepFile}` returns control, the brief-skill workflow is fully complete: do not re-enter step 5 or step 6, load any further step file, or loop back into the workflow.

package/src/skf-brief-skill/references/invocation-contract.md

@@ -0,0 +1,37 @@
+# Invocation Contract — skf-brief-skill
+
+Full argument set, gate map, exit codes, and headless result envelope for `skf-brief-skill`. Interactive callers can ignore this file; headless automators and pipeline integrators consult it. This is the canonical statement of the `from_brief` ratify contract — the source of truth for both the interactive (`gather-intent.md` §3.1a) and headless (step 1 §8 GATE) ratify paths.
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **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], `from_brief` [optional: path to a pre-authored `skill-brief.yaml` to *ratify* — when supplied it is the source of truth, `target_repo`/`skill_name` become optional/derived-from-brief, and the run mirrors the interactive §3.1a ratify path: schema-validate, skip analyze-target/scope-definition, write through the canonical writer in place], `[auto]` [optional: bracket modifier passed via pipeline context — when present, BS loads the upstream brief from `brief_path` in pipeline data, enriches it with doc detection, and writes through the canonical writer; requires `brief_path` from AN's `SKF_ANALYZE_RESULT_JSON`] |
+| **Gates** | step 1: Input Gate [use args] | step 3: Confirm Gate [C] | step 4: Confirm Gate [C] |
+| **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); supplying `from_brief <path>` instead routes the step 1 GATE to the ratify path described in the `from_brief` Inputs cell (schema-validate, skip analyze/scope, write in place — no `--force` needed) rather than deriving a new brief |
+| **Transient-failure retry** | This workflow does **not** auto-retry network or subprocess failures. A failed `gh` fetch (analyze-target.md §1, portfolio-similarity-check.md), QMD probe, or extraction script is logged and surfaced in the final result envelope as a warning, but the workflow continues with whatever signal it has. Headless pipelines that want retry semantics should wrap the invocation at their orchestrator level (e.g. CI re-runner on non-zero exit). Rationale: brief-skill is read-mostly with one terminal write (the YAML at step 5); a partial-signal retry has more failure modes than just re-running the whole workflow, which is cheap. |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning              | Raised by                                                                                  |
+| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
+| 0    | success              | step 6 (terminal)                                                                         |
+| 2    | input-missing / input-invalid | step 1 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 5 brief-context schema validation failure → `input-invalid` |
+| 3    | resolution-failure   | step 1 §1 (`forge-tier.yaml` missing); step 2 §1 (target inaccessible / `gh auth` fails) |
+| 4    | write-failure        | step 1 §1 pre-flight write probe (data folder unwritable: read-only mount, disk full, permissions denied); step 5 §4 (write to `{forge_data_folder}/{skill-name}/skill-brief.yaml` failed) |
+| 5    | overwrite-cancelled  | step 5 §2 (existing brief, `force` not supplied)                                          |
+| 6    | user-cancelled       | any interactive menu in step 1/03/04 (user selected `[X]` Cancel and exit)                |
+
+## Result Contract (Headless)
+
+When `{headless_mode}` is true, step 5 emits a single-line JSON envelope on **stdout** before chaining to step 6, 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,"mode":"auto|null"}
+```
+
+`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. `mode` is `"auto"` when BS was invoked with the `[auto]` flag (pipeline auto-brief generation), `null` otherwise (interactive or headless-without-auto).

package/src/skf-brief-skill/references/scope-definition.md

@@ -1,6 +1,5 @@
 ---
 nextStepFile: 'confirm-brief.md'
-scopeTemplatesFile: 'assets/scope-templates.md'
 recommendScopeTypeProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-recommend-scope-type.py'
   - '{project-root}/src/shared/scripts/skf-recommend-scope-type.py'
@@ -12,19 +11,13 @@ partyModeSkill: '/bmad-party-mode'
 
 # Step 3: Scope Definition
 
-## STEP GOAL:
-
-To collaboratively define the skill's inclusion and exclusion boundaries using the analysis findings from step 02, scope templates, and the user's intent from step 01.
-
 ## Rules
 
-- Focus only on defining scope boundaries — do not write the brief yet (Step 05)
 - Do not make scope decisions unilaterally — user drives all scope choices
 - Produce: scope type, include patterns, exclude patterns
-- All user-facing output in `{communication_language}`
 - **Re-entry from step 4 [R] revise:** prior selections (`scope.type`, `scope.include`, `scope.exclude`, `scope.notes`, `scope.tier_a_include`, `scope.rationale`, `scripts_intent`, `assets_intent`, supplemental `doc_urls`) are preserved as the current state. Re-present them at each section as the existing answer; the user only re-confirms or overrides. Do not reset to the §2c template menu unless the user explicitly asks to start scope over. When `scope.rationale` is preserved and the user changes `chosen` (the scope type) on this pass, recompute `accepted_recommendation` (`chosen == recommended`) and refresh `reason` and `recorded` per the §2c capture rules — revise in place, do not append.
 
-## MANDATORY SEQUENCE
+## Sequence
 
 ### 1. Present Scope Context
 
@@ -120,6 +113,8 @@ How broadly should this skill cover the library?
 
 Press Enter to accept the recommendation, or pick a different letter."
 
+**First-timer reassurance (interactive only, never-briefed user — the §4 first-timer rail fired in step 01).** Append one line so the harder scope-type call doesn't stall a first-timer: "The recommended type is almost always right — accept it and re-scope from step 4 if the analysis surprises you." Repeat users and headless skip this line.
+
 Wait for user selection. Empty input or just Enter accepts the recommendation; any of the five letters overrides.
 
 ### 3. Define Boundaries Based on Selection
@@ -154,6 +149,8 @@ The analysis detected **{language}** with low confidence. Is this correct, or sh
 
 Wait for confirmation or override.
 
+**Headless:** `language_hint`, when supplied, already set the language at step 02 §3; otherwise accept the detected language and continue. This confirmation prompt is interactive-only, so a headless run never stalls here.
+
 ### 5. Summarize Scope Decisions
 
 "**Scope Summary:**
@@ -199,9 +196,8 @@ Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Conti
 - IF X: Treat as user-cancellation. 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. `[X]` is interactive-only; the headless GATE never reaches this branch.
 - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options)
 
-#### EXECUTION RULES:
+#### Execution rules:
 
-- ALWAYS halt and wait for user input after presenting menu
 - **GATE [default: C]** — If `{headless_mode}`: consume the headless inputs from step 1 in priority order:
   - If `scope_type` was supplied, use it (must match one of the six valid types) and skip the §2c template menu.
   - Otherwise auto-select via `{recommendScopeTypeHelper}` — invoke the script with the **same payload shape** documented in §2c but with `mode: "headless"` (presence-only matching for the component-registry rule, since `entry_files` may not be available without an interactive context). Use the returned `scope_type` and log `"headless: scope_type={value} from heuristic={matched_heuristic}"`. The script's docs-only short-circuit handles `source_type=docs-only` automatically.
@@ -209,11 +205,6 @@ Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Conti
   - If `scripts_intent`/`assets_intent` were supplied, record them and skip §5b; otherwise default to `detect`.
   - Set `scope.rationale`: `recommended`/`heuristic` from the script (or `recommended = scope_type` arg, `heuristic = "user-supplied-arg"` when `scope_type` was passed); `chosen = <resolved type>`; `accepted_recommendation = (no scope_type arg)`; `reason = "<script rationale>"` (auto path) or `"headless: scope_type supplied as argument"` (arg path); `recorded = {date}`. No prompt — headless never asks "why".
   - Log: `"headless: scope_type={value} include={n} exclude={n} scripts_intent={value} assets_intent={value}"`.
-- ONLY proceed to next step when user selects 'C'
 - After other menu items execution, return to this menu
 - User can chat or ask questions — always respond and then redisplay menu
 
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN C is selected and scope boundaries are confirmed will you load and read fully `confirm-brief.md` to present the complete brief for confirmation.
-

package/src/skf-brief-skill/references/step-auto-brief.md

@@ -9,7 +9,12 @@ writeSkillBriefProbeOrder:
 emitBriefEnvelopeProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
   - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
-detectDocsScript: 'src/shared/scripts/skf-detect-docs.py'
+mergeDocUrlsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-merge-doc-urls.py'
+  - '{project-root}/src/shared/scripts/skf-merge-doc-urls.py'
+detectDocsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-docs.py'
+  - '{project-root}/src/shared/scripts/skf-detect-docs.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -69,10 +74,12 @@ Extract from the parsed brief:
 
 ### 2. Run Doc Detection
 
+**Resolve `{detectDocsHelper}`** from `{detectDocsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 Invoke doc detection to discover documentation URLs for the source repo:
 
 ```bash
-uv run python {project-root}/{detectDocsScript} --repo-url {source_repo}
+uv run {detectDocsHelper} --repo-url {source_repo}
 ```
 
 `--repo-url` is always required (the script uses it for GitHub API calls). If a local clone is also available at `{local_clone_path}`, add `--local-path {local_clone_path}` to enable docs-folder scanning in addition to API-based detection.
@@ -97,8 +104,18 @@ For each detected doc entry, create a brief `doc_urls` entry:
     - `"readme_link"` → `"README Link"`
     - `"pages_api"` → `"GitHub Pages"`
     - `"docs_folder"` → `"Docs Folder"`
+- `source` ← coarse provenance derived from `detected_via` (per the `skill-brief.v1.json` `doc_urls[].source` enum): `homepageUrl` → `homepage`, `readme_link` → `readme-detection`, `pages_api` → `pages-api`, `docs_folder` → `docs-folder`. This marks the entry as opportunistically detected, distinct from a registry-guaranteed corpus.
+
+**Merge via the canonical helper.** Resolve `{mergeDocUrlsHelper}` from `{mergeDocUrlsProbeOrder}` (first existing path wins; HALT if neither exists). Pass the upstream brief's `doc_urls` as `existing` and the entries just mapped above as `detected`:
+
+```bash
+echo '{"scope_type": "{scope_type}", "existing": {upstream brief doc_urls JSON, [] if none}, "detected": {mapped detected entries JSON}}' \
+  | uv run {mergeDocUrlsHelper}
+```
+
+The helper returns `{"doc_urls": [...], "suppressed": [...]}`. It deduplicates by **normalized** URL (lowercase host, strip a trailing `/index.html` and any trailing `/`), so a seeded `…/book/` and a README's `…/book/index.html` collapse to one entry; existing/corpora-seeded entries always win and keep their `source: language-registry`, so the registry-vs-detected distinction survives the merge. For a **whole-language reference** (`scope_type == "full-library"` AND ≥1 `existing` entry has `source: language-registry`) it additionally suppresses README noise on a corpus host: non-corpus path segments (`/whatsnew/`, `/contribute`, `/wiki/`) and non-primary-locale duplicates of a kept page (`/ja/master/` when `/en/master/` is kept). Ordinary skills (any other `scope_type`, or no registry corpora) pass through with dedup only — no suppression. Use the returned `doc_urls` as the brief's merged list.
 
-If the upstream brief already has `doc_urls`, merge the detected docs with the existing entries (deduplicate by URL — existing entries take precedence).
+**Log suppressed entries.** When `suppressed` is non-empty, log one line per entry — `"info: suppressed {url} ({reason})"` — so the operator can see what the whole-language noise filter dropped (never drop silently). The N==0 DEGRADED case (a whole-language repo whose registry returned no corpora) carries no `language-registry` entry, so suppression stays inactive and its README docs are kept — this is intentional (there is no canonical corpus host to filter against).
 
 ### 4. Validate Enriched Brief
 
@@ -123,7 +140,7 @@ Assemble the enriched brief context as a flat JSON object following the write-br
   "scope_rationale":  null,
   "scope_tier_a_include": null,
   "scope_amendments":     null,
-  "doc_urls":         [{"url": "...", "label": "..."}],
+  "doc_urls":         [{"url": "...", "label": "...", "source": "..."}],
   "scripts_intent":   "{scripts_intent or null}",
   "assets_intent":    "{assets_intent or null}",
   "source_authority": "{source_authority or null}",
@@ -164,8 +181,4 @@ echo '{"status":"error","skill_name":"{skill_name or unknown}","halt_reason":"{r
 
 ### 7. Chain to Auto-Validate
 
-Load, read fully, then execute {nextStepFile} to present the auto-brief validation gate, where the user can approve, edit, or reject the brief before the pipeline continues.
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the enriched brief has been written and validated will you load and read fully {nextStepFile} to begin the auto-brief validation gate.
+Load, read fully, then execute {nextStepFile} to present the auto-brief validation gate, where the user can approve, edit, or reject the brief before the pipeline continues. Do this only after the enriched brief has been written and validated.

package/src/skf-brief-skill/references/step-auto-validate.md

@@ -75,11 +75,11 @@ Scope:        {scope_type} ({N} include, {M} exclude patterns)
 Docs:         {doc_urls count} sources detected | "None detected"
 Version:      {version}
 Forge Tier:   {forge_tier}
-Quality:      90% target (deepwiki pipeline)
+Pipeline:     forge-auto ({forge_tier} tier)
 Description:  "{description}"
 ```
 
-Where `{N}` is the count of `scope_include` patterns and `{M}` is the count of `scope_exclude` patterns. If `doc_urls` is null or empty, display "None detected".
+Where `{N}` is the count of `scope_include` patterns and `{M}` is the count of `scope_exclude` patterns. If `doc_urls` is null or empty, display "None detected". The `Pipeline` line names the auto pipeline and the resolved `{forge_tier}` — it carries no numeric quality target, which would be an unverified guarantee an automator might parse as fact.
 
 ### 3. Validation Gate
 
@@ -200,10 +200,6 @@ echo '{"status":"error","skill_name":"{skill_name or unknown}","halt_reason":"{r
 
 ### 8. Chain
 
-Load, read fully, then execute the appropriate next step file based on the user's choice:
+Load, read fully, then execute the appropriate next step file — only after the user has made their choice and the corresponding action has been taken (envelope emitted or context hydrated):
 - [A]pprove or [E]dit (after final approve): {nextStepFile} (health-check.md)
 - [R]eject: {rejectTargetFile} (confirm-brief.md)
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the user has made their choice (approve, edit-then-approve, or reject) and the appropriate action has been taken (envelope emitted or context hydrated) will you load and read fully the next step file.

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

@@ -29,7 +29,7 @@ The brief's `version` field is resolved from three candidate sources, in priorit
 
 ## Invariant
 
-When `target_version` is set, the written brief MUST satisfy:
+When `target_version` is set, the written brief must satisfy:
 
 ```
 brief.target_version == brief.version