bmad-module-skill-forge 2.0.0 → 2.0.1

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

@@ -19,18 +19,12 @@ emitBriefEnvelopeProbeOrder:
 
 # 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
 
@@ -67,7 +61,7 @@ Distinguish the failure class before reporting. In headless mode, every branch b
 **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...**"
 
@@ -141,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
 
@@ -291,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

@@ -9,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
 
@@ -162,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

@@ -21,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)
@@ -32,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
 
@@ -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:}
@@ -222,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.
@@ -320,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
 
@@ -340,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
 
@@ -383,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.
@@ -416,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

@@ -11,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
 
@@ -155,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:**
@@ -200,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.
@@ -210,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

@@ -181,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

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

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

@@ -18,20 +18,15 @@ forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 
 # Step 5: Write Brief
 
-## STEP GOAL:
-
-To generate the complete skill-brief.yaml from the approved brief data and write it to the forge data folder, completing the brief-skill workflow.
-
 ## Rules
 
 - Focus only on writing the file — all decisions have been made
 - Do not change any field values without user request — the brief was already approved
-- Create the output directory if it doesn't exist
 - Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing success summary is NOT the terminal step
 - All user-facing output in `{communication_language}`; written artifact (`description`, `notes`) in `{document_output_language}`
 - **Determinism delegation:** YAML rendering, version-precedence, atomic write, the headless result envelope, and the QMD-collection registry mutation are all delegated to shared SKF scripts. The LLM's job in this step is to assemble inputs, branch on script results, and surface user-facing prose — not to render YAML, JSON envelopes, or YAML-mutation diffs in the model.
 
-## MANDATORY SEQUENCE
+## Sequence
 
 ### 1. Reference the Schema (LLM context only)
 
@@ -202,10 +197,22 @@ After compilation, you can:
 
 **Brief-skill workflow complete.**"
 
-### 7. Chain to Health Check
+### 6b. On-Complete Hook (pipeline integration)
+
+If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it now — after the brief has been written (§3) and the result contract finalized (§4b) — as:
+
+```bash
+{onCompleteCommand} --result-path={brief_path}
+```
+
+where `{brief_path}` is the absolute path captured from the §3 response envelope (the freshly written `skill-brief.yaml`, the stable artifact a downstream consumer chains from).
 
-ONLY WHEN the brief file has been written and the success summary displayed will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.
+- On success: log to `workflow_warnings[]` as informational only if the hook emitted stderr (`on_complete hook stderr: …`); otherwise no entry.
+- On non-zero exit / process error: log to `workflow_warnings[]` (`on_complete hook failed (exit {code}): {stderr_snippet}`).
+- **Never fail the workflow on hook errors** — the hook is for pipeline integration (chaining into create-skill, Slack, dashboards, CI), not for gating brief production.
 
-## CRITICAL STEP COMPLETION NOTE
+When `{onCompleteCommand}` is empty (bundled default), skip this section entirely — no hook is invoked.
+
+### 7. Chain to Health Check
 
-This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the brief-skill workflow is fully done.
+Once the brief file has been written and the success summary displayed, load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.