bmad-module-skill-forge 1.3.0 → 1.4.1

package/src/skf-brief-skill/steps-c/step-03-scope-definition.md

@@ -1,6 +1,7 @@
 ---
 nextStepFile: './step-04-confirm-brief.md'
 scopeTemplatesFile: 'assets/scope-templates.md'
+recommendScopeTypeScript: '{project-root}/src/shared/scripts/skf-recommend-scope-type.py'
 advancedElicitationSkill: '/bmad-advanced-elicitation'
 partyModeSkill: '/bmad-party-mode'
 ---
@@ -16,6 +17,8 @@ To collaboratively define the skill's inclusion and exclusion boundaries using t
 - 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-04 [R] revise:** prior selections (`scope.type`, `scope.include`, `scope.exclude`, `scope.notes`, `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.
 
 ## MANDATORY SEQUENCE
 
@@ -65,6 +68,10 @@ Add, remove, or confirm these URLs."
 
 Wait for confirmation. Record any changes to `doc_urls`.
 
+HEAD-check the URLs in parallel — issue all N `curl -sI --max-time 5 {url}` calls in a **single message with N parallel Bash calls**, then process the responses together. On a 4xx/5xx, DNS failure, or timeout per URL, warn `"Could not reach {url} — {status or error}."` and offer the same correct/keep choice as step-01 §3. The check is best-effort — never HALT on a failed HEAD — but the failure must surface here so it is not discovered downstream during compilation.
+
+**On re-entry from step-04 [R]:** if `doc_urls` is byte-identical to the list that was probed on the previous pass through this subsection AND the prior per-URL probe results are still recoverable from conversation context, skip the parallel HEAD-check and reuse those results. Re-running the probes when the list has not changed wastes round-trips and can flap on transient failures. Any addition, removal, or edit to a URL invalidates the cache — re-probe the entire updated set. If the prior results are not recoverable (long session, compaction, etc.), re-probe — never cache-hit on a list whose results you cannot cite.
+
 **If no supplemental doc_urls were collected:** Skip this subsection.
 
 **Scope guidance for first-time users:** A well-scoped skill covers one cohesive capability with 3-8 primary functions. If the scope includes unrelated concerns (e.g., authentication AND data visualization), suggest splitting into separate briefs. If the scope is too narrow (single utility function), suggest expanding to the surrounding capability surface.
@@ -73,11 +80,41 @@ Wait for confirmation. Record any changes to `doc_urls`.
 
 Load `{scopeTemplatesFile}` for the scope type options ([F], [M], [P], [C], [R]) and their descriptions.
 
-Present: "**How broadly should this skill cover the library?**" followed by the scope type options from the loaded reference.
+**Recommend a scope type — don't present the five options as equal weight.** SKILL.md states this workflow "steers toward the smaller, sharper version when scope is unclear" — surface that opinion at decision time. Use the analysis from step-02 and the user's intent from step-01 to pick the best-fit recommendation, then present the menu with that option marked as the suggested default.
+
+**Delegate the recommendation to `{recommendScopeTypeScript}`** instead of walking the heuristic ladder in prose. The script is the single source of truth for the five-rule ladder (component-registry → reference-app keywords → specific-modules naming/count → narrow-public-api → default full-library) plus the docs-only short-circuit. Both the interactive recommendation and the §6 headless GATE invoke the same script — same inputs, same outputs, no drift.
+
+**Fetch registry-file contents before building the payload.** Step-02 §4.1 fetches `package.json` plus the entry-point files but does not fetch `registry.ts` / `components.ts` — the deep-match branch of the component-registry rule needs those contents. Scan the tree for any of `registry.ts` / `registry.tsx` / `components.ts` / `components.tsx` (any depth). For each match, fetch its contents in **one message with N parallel Bash calls** (`gh api repos/{owner}/{repo}/contents/{path}` for GitHub, file reads for local), then base64-decode the responses together. Skip the fetch if the tree contains no registry files.
+
+Build the payload and invoke:
+
+```bash
+echo '{
+  "intent": "<combined intent + scope_hint text from step-01>",
+  "module_count": <count from step-02 §4.3>,
+  "export_count": <count from step-02 §4.3>,
+  "tree": [<flat list of repo-relative file paths from step-02 §1>],
+  "entry_files": [{"path": "<registry path>", "content": "<contents>"}, ...],
+  "source_type": "source",
+  "mode": "interactive"
+}' | uv run {recommendScopeTypeScript}
+```
+
+`entry_files` carries the registry contents fetched above; omit when no registry files exist in the tree. `mode: "interactive"` activates the content-inspection branch of the component-registry rule (10+ entries or `Component[]` annotation); the headless GATE in §6 uses `mode: "headless"` which falls back to presence-only matching. `source_type: "docs-only"` short-circuits to `docs-only` regardless of the other signals.
+
+The script returns `{scope_type, matched_heuristic, signals, rationale}`. Use `rationale` directly — it already names the specific signals that fired.
+
+Present:
+
+"**Recommended scope type: [{letter}] {Name}** — {rationale from the script}.
+
+How broadly should this skill cover the library?
+
+{full menu from `{scopeTemplatesFile}` with the recommended letter marked, e.g. '[F] Full Library', '[M] Specific Modules', '[P] Public API Only ← recommended', '[C] Component Library', '[R] Reference App'}
 
-Ask: "Which scope type fits your needs?"
+Press Enter to accept the recommendation, or pick a different letter."
 
-Wait for user selection.
+Wait for user selection. Empty input or just Enter accepts the recommendation; any of the five letters overrides.
 
 ### 3. Define Boundaries Based on Selection
 
@@ -128,19 +165,25 @@ Record the response as `scripts_intent` and `assets_intent` in the brief. Defaul
 
 ### 6. Present MENU OPTIONS
 
-Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Brief Confirmation
+Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Brief Confirmation [X] Cancel and exit
 
 #### Menu Handling Logic:
 
 - IF A: Invoke {advancedElicitationSkill}, and when finished redisplay the menu
 - IF P: Invoke {partyModeSkill}, and when finished redisplay the menu
 - 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"`). 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:
 
 - ALWAYS halt and wait for user input after presenting menu
-- **GATE [default: C]** — If `{headless_mode}`: accept auto-detected scope (full-repo or manifest-based) and auto-proceed, log: "headless: using auto-detected scope"
+- **GATE [default: C]** — If `{headless_mode}`: consume the headless inputs from step-01 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 `{recommendScopeTypeScript}` — 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.
+  - If `include`/`exclude` were supplied, use them verbatim (split on comma) instead of running the boundary prompts in §3.
+  - If `scripts_intent`/`assets_intent` were supplied, record them and skip §5b; otherwise default to `detect`.
+  - 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

package/src/skf-brief-skill/steps-c/step-04-confirm-brief.md

@@ -16,16 +16,15 @@ To present the complete skill brief in human-readable format, highlighting all f
 
 - 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
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
-### 1. Load Schema
+### 1. Assemble Complete Brief
 
-Load `{briefSchemaFile}` to reference required fields and the human-readable presentation format.
-
-### 2. Assemble Complete Brief
+Use the values already accepted in steps 01-03 directly — do not re-load `{briefSchemaFile}` here. The 18 fields below are all in conversation; the schema is only consulted in §4 if an inline adjustment needs a specific field's validation rule cited.
 
 Compile all gathered data from steps 01-03 into the complete brief:
 
@@ -48,11 +47,11 @@ Compile all gathered data from steps 01-03 into the complete brief:
 - **assets_intent:** {detect/none/description from step 03, or "detect" if not explicitly set}
 - **source_authority:** {official/community/internal from step 01 — default "community"}
 
-### 3. Present Brief for Review
+### 2. Present Brief for Review
 
-Using the presentation format from the schema:
+Using the format below:
 
-"**Please review the complete skill brief before I write it.**
+"**Review the complete skill brief before I write it.**
 
 ---
 
@@ -62,7 +61,7 @@ Skill Brief: {name}
 
 Target:      {source_repo}
 Language:    {language}
-Forge Tier:  {forge_tier}
+Forge Tier:  {forge_tier} — {tier_gloss}
 Description: {description}
 
 Scope: {scope.type}
@@ -79,9 +78,8 @@ Doc URLs:
 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}
+Scripts:    {scripts_intent} — {scripts_gloss}
+Assets:     {assets_intent} — {assets_gloss}
 
 Source Authority: {source_authority}
 
@@ -95,17 +93,31 @@ Created:    {created}
 Created by: {created_by}
 ```
 
----"
+---
+
+Glosses (substitute the matching one-liner for `{tier_gloss}`, `{scripts_gloss}`, `{assets_gloss}` above so the user can decode each value at a glance):
+
+- **Forge tier glosses** —
+  - `Quick`: text-only extraction; AST and semantic discovery off
+  - `Forge`: AST-grep on; semantic and re-ranking off
+  - `Forge+`: AST-grep + ccc semantic discovery; re-ranking off
+  - `Deep`: full pipeline — AST + ccc + qmd portfolio search + LLM re-ranking
+
+- **`scripts_intent` / `assets_intent` glosses** —
+  - `detect`: SKF will scan source for the standard `scripts/`/`bin/`/`tools/`/`cli/` (or `assets/`/`templates/`/`schemas/`/`configs/`) directories during create-skill and decide automatically
+  - `none`: no script/asset packaging — create-skill will skip the detection pass
+  - free-text (anything else): a description of what to package; create-skill treats it as the user's spec
+
+(For `docs-only` and `public-api` scope types the scripts/assets prompt is skipped in step-03 §5b — the values default to `detect` but the create-skill detection pass also no-ops for these scope types, so the gloss just clarifies that the recorded value will not actually fire any scan.)"
 
-### 4. Highlight Items Needing Attention
+### 3. Highlight Items Needing Attention
 
 Flag any fields that may need review:
 
 {If language was overridden or low confidence:}
 "**Note:** Language was {auto-detected / manually overridden}."
 
-{If description was derived (not stated by user):}
-"**Note:** Description was derived from your stated intent. Adjust if needed."
+"**Description:** synthesized and confirmed in step-01 §7b. This is the text agents read when deciding whether to route to your skill — refine here if you want to tighten it now that the full brief is visible."
 
 {If forge tier was defaulted:}
 "**Note:** Forge tier defaulted to Quick (no forge-tier.yaml found)."
@@ -123,16 +135,17 @@ You can:
 - Revise scope boundaries by selecting [R]
 - Proceed to write by selecting [C]"
 
-### 5. Handle Inline Adjustments
+### 4. Handle Inline Adjustments
 
 If the user requests changes to specific fields (name, description, version, etc.):
+- If the adjustment requires explaining a field's validation rule or allowed values, load `{briefSchemaFile}` now (otherwise skip the read — the common path does not need it)
 - Make the adjustment
 - Re-present the updated brief
 - Return to the menu
 
-### 6. Present MENU OPTIONS
+### 5. Present MENU OPTIONS
 
-Display: **Select an Option:** [R] Revise Scope [A] Advanced Elicitation [P] Party Mode [C] Approve and Write
+Display: **Select an Option:** [R] Revise Scope [A] Advanced Elicitation [P] Party Mode [C] Approve and Write [X] Cancel and exit
 
 #### Menu Handling Logic:
 
@@ -140,7 +153,8 @@ Display: **Select an Option:** [R] Revise Scope [A] Advanced Elicitation [P] Par
 - IF A: Invoke {advancedElicitationSkill}, and when finished redisplay the menu
 - IF P: Invoke {partyModeSkill}, and when finished redisplay the menu
 - IF C: Load, read entire file, then execute {nextStepFile}
-- IF Any other comments or queries: help user respond, apply any field adjustments, re-present brief if changed, then [Redisplay Menu Options](#6-present-menu-options)
+- 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-05 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:
 

package/src/skf-brief-skill/steps-c/step-05-write-brief.md

@@ -1,6 +1,12 @@
 ---
 briefSchemaFile: 'assets/skill-brief-schema.md'
+versionResolutionFile: 'references/version-resolution.md'
+qmdRegistrationFile: 'references/qmd-collection-registration.md'
 nextStepFile: './step-06-health-check.md'
+writeSkillBriefScript: '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
+emitBriefEnvelopeScript: '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
+forgeTierRwScript: '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
+forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 ---
 
 # Step 5: Write Brief
@@ -15,145 +21,136 @@ To generate the complete skill-brief.yaml from the approved brief data and write
 - 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
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
-### 1. Load Schema Template
+### 1. Reference the Schema (LLM context only)
 
-Load `{briefSchemaFile}` to reference the YAML template structure.
+`{briefSchemaFile}` and `{versionResolutionFile}` document the brief contract for human readers. The deterministic enforcement of that contract lives in `{writeSkillBriefScript}` and its JSON Schema artifact at `src/shared/scripts/schemas/skill-brief.v1.json`. Load `{briefSchemaFile}` only if you need to explain a specific field to the user during inline adjustments — otherwise skip the read; the script is the source of truth.
 
-### 2. Create Output Directory
+### 2. Resolve Output Path
 
-Create the directory `{forge_data_folder}/{skill-name}/` if it doesn't already exist.
+Resolve the target write path:
+- Primary: `{forge_data_folder}/{skill-name}/skill-brief.yaml`
+- Fallback (when `{forge_data_folder}` is not set or doesn't exist): `{output_folder}/forge-data/{skill-name}/skill-brief.yaml` and inform user "**Note:** forge_data_folder not configured. Writing to {output_folder}/forge-data/{skill-name}/ instead."
 
-If `{forge_data_folder}` is not set or doesn't exist:
-- Fall back to `{output_folder}/forge-data/{skill-name}/`
-- Inform user: "**Note:** forge_data_folder not configured. Writing to {output_folder}/forge-data/{skill-name}/ instead."
+The script's atomic-write helper creates parent directories as needed (`mkdir -p`) — no separate mkdir call required.
 
-### 3. Generate skill-brief.yaml
+### 2b. Existing Brief — Overwrite Policy
 
-**Resolve the `version` field before generating the YAML:**
+Before writing, check whether the resolved target path already exists.
 
-- If `target_version` was set in step 01 (the user explicitly asked for a specific version), use `target_version` as the value of the `version` field. This is the authoritative version for create-skill.
-- Otherwise, use the auto-detected source version from step 02, or `1.0.0` if none was detected.
+**Interactive (`{headless_mode}` is false):**
 
-`target_version` and `version` must never carry different values in the written brief. When the user provided a `target_version`, also include it as a separate `target_version` field so downstream tooling can distinguish "user-requested" from "auto-detected" without re-deriving the provenance — but its value must be identical to `version`.
+If the file exists, present:
 
-Generate the YAML file using the approved field values and the schema template:
+"**An existing brief was found at `{path}`.**
+Overwrite it with the brief you just approved? [Y/N]"
 
-```yaml
----
-name: "{approved skill name}"
-version: "{resolved version — target_version if set, else detected source version, else 1.0.0}"
-source_type: "{source or docs-only}"
-source_repo: "{approved source repo or doc site URL}"
-language: "{approved language}"
-description: "{approved description}"
-forge_tier: "{approved forge tier}"
-created: "{current date}"
-created_by: "{user_name}"
-scope:
-  type: "{approved scope type}"
-  include:
-    - "{approved include patterns}"
-  exclude:
-    - "{approved exclude patterns}"
-  notes: "{approved scope notes or empty string}"
----
-```
+- **[Y]** Overwrite — proceed to §3.
+- **[N]** Cancel — emit a single-line stderr log `brief-skill: overwrite-cancelled at {path}` and HALT with exit code 5 (do not chain to step-06; the run produced no new artifact).
 
-**Conditional optional field inclusion:**
+**Headless (`{headless_mode}` is true):**
 
-**If `target_version` was set in step 01:**
-Include the `target_version` field in the generated YAML — its value MUST be identical to the `version` field above:
-```yaml
-target_version: "{target_version — same value as version}"
-```
+If the file exists:
 
-**If `source_type: "docs-only"` OR supplemental `doc_urls` were collected:**
-Include the `doc_urls` array (uncommented) in the generated YAML:
-```yaml
-doc_urls:
-  - url: "{documentation URL}"
-    label: "{page label}"
-```
-When `source_type: "docs-only"`: `doc_urls` is required (at least one entry), `source_repo` may be set to the doc site URL for reference or omitted.
+- If `force` was supplied as a headless argument: log `"headless: force-overwriting existing brief at {path}"` and proceed to §3.
+- Otherwise: emit the error envelope per §4b with `halt_reason: "overwrite-cancelled"`, then HALT with exit code 5.
 
-**If `scripts_intent` was collected and is not the default `"detect"`:**
-Include the `scripts_intent` field (uncommented):
-```yaml
-scripts_intent: "{none or description}"
-```
+If the file does not exist, proceed normally.
+
+### 3. Write the Brief
 
-**If `assets_intent` was collected and is not the default `"detect"`:**
-Include the `assets_intent` field (uncommented):
-```yaml
-assets_intent: "{none or description}"
+Assemble the brief context as a **flat** JSON object — every approved value is a top-level key, scope is split across four `scope_*` keys instead of nested, and every optional field is passed as `null` when not set rather than conditionally omitted. This eliminates the "decide what to omit" cognitive load that previously made this the most expensive HALT-typo site in the workflow:
+
+```json
+{
+  "name":             "{approved skill name}",
+  "target_version":   "{target_version from step 01, or null}",
+  "detected_version": "{auto-detected version from step 02, or null}",
+  "source_type":      "{source or docs-only}",
+  "source_repo":      "{approved source repo or doc site URL}",
+  "language":         "{approved language}",
+  "description":      "{approved description}",
+  "forge_tier":       "{Quick|Forge|Forge+|Deep}",
+  "created":          "{current ISO date YYYY-MM-DD}",
+  "created_by":       "{user_name}",
+  "scope_type":       "{approved scope type}",
+  "scope_include":    ["{approved include patterns}"],
+  "scope_exclude":    ["{approved exclude patterns}"],
+  "scope_notes":      "{approved scope notes or empty string}",
+  "doc_urls":         null | [{"url": "...", "label": "..."}],
+  "scripts_intent":   null | "{detect|none|free-text}",
+  "assets_intent":    null | "{detect|none|free-text}",
+  "source_authority": null | "{official|community|internal}"
+}
 ```
 
-**Always include** `source_authority` (default: `"community"`, forced to `"community"` when `source_type: "docs-only"`):
-```yaml
-source_authority: "{official|community|internal}"
+Pipe it into the writer script with the `--from-flat` flag:
+
+```bash
+echo '<context-json>' | uv run {writeSkillBriefScript} write --target {resolved-target-path} --from-flat
 ```
 
-### 4. Write the File
+The script translates flat → nested internally, drops the null optional fields, and runs the same schema validation and atomic write as before — pass every key always, the writer decides what reaches the YAML.
 
-Write the generated YAML to `{forge_data_folder}/{skill-name}/skill-brief.yaml`.
+The script:
+- Validates the context against `src/shared/scripts/schemas/skill-brief.v1.json`
+- Applies the version-precedence rule from `{versionResolutionFile}`
+- Enforces the `target_version == version` invariant (refuses to write a brief that violates it)
+- Renders YAML in canonical key order (byte-stable across runs)
+- Atomically writes the file via temp + fsync + rename (no half-written file ever visible)
+- Emits a JSON success envelope on stdout: `{"status":"ok","brief_path":"…","version":"…","bytes":…,"warnings":[…]}`
 
-If write fails: **HALT** — "**Error:** Failed to write skill-brief.yaml. Please check that the directory is writable and try again."
+**On script failure (non-zero exit):**
+- Exit 1 (validation/invariant): The error JSON on stderr names the offending field. This indicates a context-assembly bug, not a user error — surface the message to the user, log it, then HALT.
+  - Interactive: **HALT** — display the error JSON's `message` field.
+  - Headless: emit the error envelope per §4b with `halt_reason: "input-invalid"`, then `exit 2`.
+- Exit 2 (I/O failure): The atomic write failed (target unwritable, disk full, etc.).
+  - Interactive: **HALT** — "**Error:** Failed to write skill-brief.yaml. Check that the directory is writable and try again."
+  - Headless: emit the error envelope per §4b with `halt_reason: "write-failed"`, then `exit 4`.
 
-### 5. QMD Collection Registration (Deep Tier Only)
+**On success:** capture `brief_path` and `version` from the response envelope — both are needed for §4b and §6.
 
-**IF forge tier is Deep AND QMD tool is available:**
+**Draft cleanup.** After a successful write, remove `{forge_data_folder}/{skill-name}/.brief-draft.json` if it exists (`rm -f` — silent on absent). The draft was a step-01 §7 checkpoint covering the in-flight workflow window; once the brief is written it is no longer meaningful. In headless mode this rm is a no-op (drafts are only written interactively).
 
-Index the skill brief into a QMD collection so that portfolio-level searches can find existing briefs and avoid duplicate skill creation across large monorepos.
+### 4b. Headless Result Envelope (Canonical)
 
-**Collection creation:**
+This section is the canonical envelope-emission reference for the workflow. Every headless emission — the success terminal here and every HARD HALT in step-01/02/05 — uses this contract. Remote sites point here instead of restating it.
+
+**Success (this call site only — emitted from §3 directly):**
 
-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
+echo '{"status":"success","brief_path":"<from §3 response>","skill_name":"<name>","version":"<from §3 response>","language":"<language>","scope_type":"<scope.type>","halt_reason":null}' | \
+  uv run {emitBriefEnvelopeScript} emit
 ```
 
-If collection already exists (re-briefing): remove and recreate for atomic replace:
+**Error (used by every HARD HALT site):**
+
 ```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
+echo '{"status":"error","skill_name":"<name>","halt_reason":"<reason>"}' | \
+  uv run {emitBriefEnvelopeScript} emit --target stderr
 ```
 
-**Embed verification:**
+When the HALT fires before `skill_name` has been resolved (step-01 §1 pre-flight write probe, step-01 §8 input-missing on a malformed args bundle), pass the partially-gathered value or the literal `"unknown"` — the script accepts any non-empty string at this position.
 
-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 normally
-- If verification fails: log warning "QMD embed verification failed for {skill-name}-brief — collection may not be searchable yet", still proceed to registry update but add `status: "pending"` field to the registry entry
+The script derives `exit_code` deterministically from `halt_reason` (null→0, input-missing/input-invalid→2, forge-tier-missing/target-inaccessible/gh-auth-failed→3, write-failed→4, overwrite-cancelled→5, user-cancelled→6 [interactive-only — headless never raises this]), validates against `src/shared/scripts/schemas/skf-brief-result-envelope.v1.json`, and prints the prefixed `SKF_BRIEF_RESULT_JSON: {…}` line.
 
-**Registry update:**
+The script enforces the success/error halt_reason invariant (success requires null halt_reason; error requires non-null). The `user-cancelled` halt_reason is accepted for completeness (interactive `[X]` Cancel sites in step-01/03/04) but never appears on the headless code path.
 
-Read `{sidecar_path}/forge-tier.yaml` and update the `qmd_collections` array.
+Invocation sites (each pointed at this block, not duplicated): step-01 §1 (write-failed pre-resolution), step-01 §8 (input-missing/input-invalid GATE), step-05 §2b (overwrite-cancelled), step-05 §3 (input-invalid/write-failed from script). Step-01 §1 forge-tier-missing and step-02 §1 (target-inaccessible/gh-auth-failed) currently HALT without emitting an envelope — pre-existing gaps tracked separately, not addressed by this canonicalization.
 
-If an entry with `name: "{skill-name}-brief"` already exists, replace it. Otherwise, append:
+When `{headless_mode}` is false, skip this section silently — no envelope is emitted.
 
-```yaml
-  - name: "{skill-name}-brief"
-    type: "brief"
-    source_workflow: "brief-skill"
-    skill_name: "{skill-name}"
-    created_at: "{current ISO date}"
-    # status: "pending"    # Added only when embed verification fails
-```
-
-Write the updated forge-tier.yaml.
+### 5. QMD Collection Registration (Deep Tier Only)
 
-**Error handling:**
-- If QMD collection creation fails: log the error. Do NOT fail the workflow — the brief file was already written successfully.
-- If forge-tier.yaml update fails: log the error, continue.
+**IF forge tier is Deep AND QMD tool is available:** load `{qmdRegistrationFile}` and follow the procedure there to index the brief into a QMD collection and update the forge-tier registry.
 
-**IF forge tier is NOT Deep:** Skip this section silently. No messaging.
+**IF forge tier is NOT Deep OR QMD is not available:** skip this section silently — do not load `{qmdRegistrationFile}`. No messaging.
 
 ### 6. Display Success Summary
 
@@ -161,7 +158,7 @@ Write the updated forge-tier.yaml.
 
 ---
 
-**File:** `{forge_data_folder}/{skill-name}/skill-brief.yaml`
+**File:** `{brief_path from §3 response}`
 **Skill:** {name}
 **Language:** {language}
 **Scope:** {scope type}
@@ -190,4 +187,3 @@ ONLY WHEN the brief file has been written and the success summary displayed will
 ## CRITICAL STEP COMPLETION NOTE
 
 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.
-

package/src/skf-brief-skill/steps-c/step-06-health-check.md

@@ -1,7 +1,7 @@
 ---
 # `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/`
+# during development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
@@ -16,7 +16,16 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 - No user-facing reports, file writes, or result contracts in this step — those belong in step-05
 - 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-05 or step-06, do not load any further step file, and do not loop back into the workflow.

package/src/skf-create-skill/steps-c/step-07-generate-artifacts.md

@@ -106,11 +106,19 @@ The helper returns non-zero (exit 2) if `{skill_group}/active` already exists as
 ### 5. Verify Write Completion
 
 After all files are written, verify:
-- All 4 deliverable artifact types exist (SKILL.md, context-snippet.md, metadata.json, at least one file in references/), all 3 workspace artifacts exist (provenance-map.json, evidence-report.md, extraction-rules.yaml), plus scripts/ and assets/ files when inventories are non-empty
+- All 4 deliverable artifact types exist (SKILL.md, context-snippet.md, metadata.json, **and** either at least one file in `references/` **or** `references/` is empty AND Tier-2 content is inline in SKILL.md — see "Empty `references/` exception" below), all 3 workspace artifacts exist (provenance-map.json, evidence-report.md, extraction-rules.yaml), plus scripts/ and assets/ files when inventories are non-empty
 - The `active` symlink at `{skill_group}/active` resolves to `{version}`
 - Store `ref_count` = count of files written to `references/` for use in step-08 report
 - List each file with its path and size
 
+**Empty `references/` exception (Tier-2 inline):** `ref_count == 0` is a valid completion state when step-06 kept Tier-2 content inline in SKILL.md — e.g., the body was already under the size limit, or `skill-check` was unavailable and the manual fallback (step-06 §3) skipped the split. In that case, append a single line to `{forge_version}/evidence-report.md` recording the inline state so downstream tooling and audits can distinguish "inline by design" from "split-body skipped due to error":
+
+```
+ref_count: 0  # Tier-2 kept inline in SKILL.md (no split performed in step-06)
+```
+
+When `ref_count > 0` is expected (because step-06 ran a split) but no files were written, halt with: "Split-body produced zero reference files. Investigate step-06 output before retrying — empty `references/` after a split is never a valid state."
+
 **If any write failed:**
 Halt with: "Artifact generation failed: could not write `{file_path}`. Check permissions and disk space."
 

package/src/skf-export-skill/steps-c/step-01-load-skill.md

@@ -165,14 +165,22 @@ Load `{sidecar_path}/preferences.yaml` (if exists):
 
 ### 4b. Check Test Report (Quality Gate)
 
-Search for a test report at `{forge_data_folder}/{skill_name}/{active_version}/test-report-{skill_name}.md` (i.e., `{forge_version}/test-report-{skill_name}.md`). If not found at the versioned path, fall back to `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md`:
+`skf-test-skill` writes timestamped test-report filenames (`test-report-{skill_name}-{ISO-TIMESTAMP}-{HASH}.md`) — there is no exact-name `test-report-{skill_name}.md` on disk. Locate the most recent report by glob, not by exact filename:
+
+1. Glob `{forge_data_folder}/{skill_name}/{active_version}/test-report-{skill_name}-*.md` (i.e. `{forge_version}/test-report-{skill_name}-*.md`). Sort matches descending by the parsed ISO-timestamp segment in the filename (`YYYYMMDDTHHMMSSZ` between the skill name and the hash — `sort -r` on the filename works because the timestamp is the first variable component). Take the first match.
+2. If the versioned glob returns nothing, fall back to the same glob at the flat path `{forge_data_folder}/{skill_name}/test-report-{skill_name}-*.md`. Pick the newest by parsed timestamp.
+3. If neither glob returns anything, look for the stable companion `skf-test-skill-result-latest.json` in the same two directories (versioned first, then flat). Read the report path from `outputs[]` per the canonical contract documented at `shared/references/output-contract-schema.md` (resolved by skf-test-skill step-06 §4c) and load that file.
+4. If all three lookups fail, the skill has no test report.
+
+**If a test report is found:**
 
-**If test report found:**
 - Read frontmatter `testResult` and `score`
 - If `testResult: fail`: warn: "**Warning:** This skill failed its last test (score: {score}%). Consider running `@Ferris TS` and addressing gaps before export."
 - If `testResult: pass`: note: "Last test: **PASS** ({score}%)"
+- Always surface the actual file picked in the message (e.g. `test-report-my-base-ui-20260507T050917Z-487606-9b2f.md`) — not the no-longer-existent `test-report-{skill_name}.md` — so an operator can navigate to the report from the log.
+
+**If no test report found** (all three lookups returned nothing):
 
-**If no test report found:**
 - Warn: "**Note:** No test report found for this skill. Consider running `@Ferris TS` before export to verify completeness."
 
 Continue to step 5 regardless — this is advisory, not blocking.

package/src/skf-export-skill/steps-c/step-03-generate-snippet.md

@@ -62,9 +62,15 @@ Store `{skill_root}` for use in snippet generation. The context-snippet.md writt
 3. Read SKILL.md to extract: heading slugs for `#quick-start` and `#key-types`, inline summary of key types (~10 words)
 4. **Anchor verification (split-body awareness):** For each section anchor (`#quick-start`, `#key-types`), verify the heading exists in SKILL.md. If a `references/` directory exists and `## Full` headings in SKILL.md are absent or stubs (indicating split-body, not a stack skill's structural references), rewrite the anchor to point to the reference file path (e.g., `references/{file}.md#key-types`). If the heading cannot be resolved in either location, omit that anchor line from the snippet.
 5. Derive gotchas from: T2-future annotations in evidence report (breaking changes), async requirements, version-specific behavior.
+
+   **Detect first-export state before applying carry-forward logic.** The `[CARRIED]` one-cycle expiry is meaningful only on a *re-export*. On a first export, the prior `context-snippet.md` was authored by `create-skill` (or `update-skill`) from the evidence report inside the same forge cycle — those gotchas are freshly derived, not "left over from a previous export." Treating them as carry-forward primes them for premature expiry on the second export.
+
+   Read `{skills_output_folder}/.export-manifest.json` (the same file step-04 §4a will rewrite). If the skill name is **absent** from `exports`, OR present with no resolvable `last_exported` for any version under `versions`, this is a first export — set `is_first_export = true`. Otherwise `is_first_export = false`. (Step-04 reads the manifest authoritatively for the rebuild; this read is the lightweight probe step-03 needs to choose the right branch below.)
+
    - **If new gotchas are derived:** Use them (they supersede any prior gotchas). Write as `|gotchas: {pitfall-1}, {pitfall-2}` with no marker.
-   - **If NO new gotchas are derived BUT `prior_gotchas` exists AND `prior_gotchas_already_carried == false`:** First carry-forward cycle — preserve the prior gotchas line, prefixing the value with `[CARRIED]` so the next export can detect that expiry has been reached. Write as `|gotchas: [CARRIED] {prior gotchas content}`. Emit warning: "**Gotchas preserved from prior export (one-cycle carry-forward).** These gotchas will be DROPPED on the next export unless new gotchas are derived or you manually refresh them. Review now if they are still applicable."
-   - **If NO new gotchas are derived AND `prior_gotchas` exists AND `prior_gotchas_already_carried == true`:** Expiry reached — drop the gotchas line entirely. Emit warning: "**Stale gotchas dropped** — the prior gotchas were already carried forward once and cannot be derived from the current evidence report. The snippet now has no gotchas line. If the prior gotchas are still relevant, re-add them to the evidence report's T2-future section and re-run export."
+   - **If NO new gotchas are derived AND `is_first_export == true` AND `prior_gotchas` exists:** Treat the prior gotchas as **freshly derived** by create-skill/update-skill — write them **without** the `[CARRIED]` marker. (The marker only applies to re-exports.) No warning needed; this is the normal first-export shape.
+   - **If NO new gotchas are derived BUT `prior_gotchas` exists AND `is_first_export == false` AND `prior_gotchas_already_carried == false`:** First carry-forward cycle on a re-export — preserve the prior gotchas line, prefixing the value with `[CARRIED]` so the next export can detect that expiry has been reached. Write as `|gotchas: [CARRIED] {prior gotchas content}`. Emit warning: "**Gotchas preserved from prior export (one-cycle carry-forward).** These gotchas will be DROPPED on the next export unless new gotchas are derived or you manually refresh them. Review now if they are still applicable."
+   - **If NO new gotchas are derived AND `prior_gotchas` exists AND `prior_gotchas_already_carried == true`:** Expiry reached (re-export only — first-export branch above takes precedence) — drop the gotchas line entirely. Emit warning: "**Stale gotchas dropped** — the prior gotchas were already carried forward once and cannot be derived from the current evidence report. The snippet now has no gotchas line. If the prior gotchas are still relevant, re-add them to the evidence report's T2-future section and re-run export."
    - **If NO new gotchas derived AND no `prior_gotchas`:** Omit the gotchas line.
 
 Generate: