bmad-module-skill-forge 1.3.0 → 1.4.0

package/src/skf-brief-skill/steps-c/step-02-analyze-target.md

@@ -1,5 +1,9 @@
 ---
 nextStepFile: './step-03-scope-definition.md'
+versionResolutionFile: 'references/version-resolution.md'
+extractPublicApiScript: '{project-root}/src/shared/scripts/skf-extract-public-api.py'
+detectWorkspacesScript: '{project-root}/src/shared/scripts/skf-detect-workspaces.py'
+detectLanguageScript: '{project-root}/src/shared/scripts/skf-detect-language.py'
 ---
 
 # Step 2: Analyze Target
@@ -13,6 +17,7 @@ To analyze the target repository by resolving its location, reading its structur
 - 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
 
@@ -21,23 +26,68 @@ To analyze the target repository by resolving its location, reading its structur
 ### 1. Resolve Target Location
 
 **For GitHub URLs:**
-- Use `gh api repos/{owner}/{repo}` to verify the repository exists
-- Use `gh api repos/{owner}/{repo}/git/trees/HEAD?recursive=1` to get the file tree
+- Issue both probes in **one message with two parallel Bash calls** — they are independent:
+  - `gh api repos/{owner}/{repo}` (verify repo exists)
+  - `gh api repos/{owner}/{repo}/git/trees/HEAD?recursive=1` (fetch file tree)
+- If the repo-existence probe fails, fall through to the failure-class triage below; the tree response from the parallel call is discarded in that case.
 
 **Truncation detection:** After receiving the tree response, check the `truncated` field in the JSON output. If `truncated: true`:
 - Display: "Note: GitHub API returned a truncated tree response ({count} items). Full analysis may require a local clone."
 - Record in analysis summary: "Tree listing is partial — some files may not appear in the analysis."
-- For very large repos (>1000 files in tree response): suggest local clone for complete analysis.
+- For very large repos (>1000 files in tree response): offer a recovery path instead of just warning. Interactive — present:
+  ```
+  Tree is truncated. How would you like to proceed?
+    [L] Clone locally and re-analyze (slower but complete)
+    [P] Proceed with the partial tree (faster, may miss exports under deeper paths)
+  ```
+  On `[L]`: shallow-clone (`git clone --depth 1 {url} {tmp_dir}`), restart this section against the local path, and remove `{tmp_dir}` after the analysis summary in §5. On `[P]` (or under headless): record `tree_truncated: true` in the analysis summary and continue without HALT.
 
-- If inaccessible: **HALT** — "**Error:** Cannot access repository at {url}. Please verify the URL is correct and you have access. If private, ensure `gh auth` is configured."
+**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."
 
 **For local paths:**
 - Verify the directory exists
 - List the directory tree
-- If path doesn't exist: **HALT** — "**Error:** Directory not found at {path}. Please verify the path is correct."
+- If path doesn't exist: **HALT** — "**Error:** Directory not found at {path}. Verify the path is correct."
 
 Display: "**Resolving target...**"
 
+### 1b. Detect Monorepo / Workspace Layout
+
+Delegate workspace detection to `{detectWorkspacesScript}` instead of reasoning through manifest rules in prose. Build a payload from the tree fetched in §1 plus the small set of root manifests the detector needs, then invoke the script:
+
+```bash
+echo '{"tree": [<flat list of repo-relative file paths>], "manifests": {"package.json": "<raw text>", "Cargo.toml": "<raw text>", "pnpm-workspace.yaml": "<raw text>", "lerna.json": "<raw text>"}}' | \
+  uv run {detectWorkspacesScript}
+```
+
+- **`tree`** — pass the flat list of repo-relative file paths already fetched in §1 (for GitHub: the `path` values from the `gh api .../git/trees/HEAD?recursive=1` response; for local: the equivalent listing).
+- **`manifests`** — only the root manifests need contents; child-workspace manifests are looked up from the tree by the script. Include any of `package.json`, `Cargo.toml`, `pnpm-workspace.yaml`, `lerna.json` that appears at the repo root. Fetch them in **one message with N parallel Bash calls** (`gh api .../contents/{path}` for GitHub, file reads for local), then base64-decode together. Per-workspace manifest contents (e.g. `packages/foo/package.json`) are optional — including them populates the workspace `name` field with the manifest's declared package name; omitting them falls back to the directory basename.
+
+The script returns a JSON envelope: `{is_monorepo, manifest_kind, workspaces[], warnings[]}`. Apply the result deterministically — see `src/shared/scripts/schemas/workspace-detection.v1.json` for the full contract.
+
+**If `is_monorepo: false`** — skip this section silently and continue to §2.
+
+**If `is_monorepo: true`** — present the discovered workspaces and prompt:
+
+```
+This looks like a monorepo ({manifest_kind}) with these workspaces:
+  1. {workspaces[0].name} ({workspaces[0].path})
+  2. {workspaces[1].name} ({workspaces[1].path})
+  ...
+Which one should the skill cover? Pick a number, type 'all' to scope at the repo root, or 'list' to keep listing more.
+```
+
+Interactive: wait for the user choice. On a numbered choice, store `monorepo_workspace: {path}` and rebase §2-§4b against that path. On `'all'`, leave `monorepo_workspace` unset and proceed at the repo root with a note in the analysis summary that scope is unfiltered.
+
+Headless: if the input contract supplied an `include` glob that begins with one of the workspace paths, auto-select that workspace (log `"headless: auto-selected workspace {name} from include glob"`). Otherwise default to repo root and log `"warn: monorepo detected ({manifest_kind}) but no workspace pre-selected — analyzing at repo root"`.
+
+Surface any non-empty `warnings[]` from the script to the operator log so a malformed root manifest is debuggable; the workflow does not HALT — falling back to repo-root analysis is always safe.
+
 ### 2. Read Repository Structure
 
 List the top-level directory structure:
@@ -54,53 +104,79 @@ List the top-level directory structure:
 
 ### 3. Detect Primary Language
 
-Examine file extensions and configuration files to detect the primary language:
+Delegate the rule walk to `{detectLanguageScript}` instead of evaluating manifest presence and extension frequency in prose:
+
+```bash
+echo '{"tree": [<flat list of repo-relative file paths from §1>]}' | uv run {detectLanguageScript}
+```
 
-**Detection signals (check in order):**
-1. `package.json` → JavaScript/TypeScript
-2. `tsconfig.json` → TypeScript
-3. `Cargo.toml` → Rust
-4. `pyproject.toml` or `setup.py` or `setup.cfg` → Python
-5. `go.mod` → Go
-6. `pom.xml` or `build.gradle` → Java
-7. `*.csproj` or `*.sln` → C#
-8. `Gemfile` → Ruby
-9. File extension frequency analysis as fallback
+The script returns `{language, confidence, detection_source, fallback_to_extension_frequency}` after walking the documented rule table (manifest presence first — package.json with tsconfig.json disambiguation, Cargo.toml, pyproject.toml/setup.py/setup.cfg, go.mod, pom.xml, build.gradle.kts, build.gradle Groovy with Java/Kotlin disambiguation, *.csproj/*.sln, Gemfile — then extension-frequency fallback over recognized source extensions). Use the returned values directly:
 
 "**Detected language:** {language}
-**Confidence:** {high/medium/low}
-**Detection source:** {what config file or pattern confirmed it}"
+**Confidence:** {confidence}
+**Detection source:** {detection_source}"
 
-If confidence is low or ambiguous: flag for user override in step 03.
+If `confidence` is `low` (or `unknown` is returned for `language`): flag for user override in step 03 §4.
 
 ### 4. List Top-Level Modules and Exports
 
-Based on detected language, identify public API surface:
+Identify the public API surface. **Delegate the parsing to `{extractPublicApiScript}` whenever the detected language is supported** — the script is the single source of truth for manifest parsing, export discovery, and version detection across the whole SKF pipeline. Hand-rolling these in prose creates drift seams the LLM cannot fully close.
 
-**For JavaScript/TypeScript:**
-- Check `package.json` for `main`, `exports`, `module` fields
-- Look for `index.ts`/`index.js` in `src/`
-- List directories under `src/` as potential modules
+**Script-supported languages** (use the script): `js`, `ts`, `javascript`, `typescript`, `python`, `rust`, `go`, `java`, `kotlin`.
 
-**For Python:**
-- Check `__init__.py` files for public exports
-- List top-level packages under the source directory
+This section runs exactly one of §4.1 (script path) or §4.2 (fallback path) based on the detected language, then always emits §4.3 (output format) and conditionally §4.4 (semantic signals).
 
-**For Rust:**
-- Check `lib.rs` for `pub mod` declarations
-- List modules from `src/` directory
+#### 4.1 Procedure — script-supported languages
 
-**For other languages:**
-- List top-level source directories as potential modules
-- Note any obvious entry points
+1. Read the relevant files into memory (no parsing yet — just collect content). For GitHub sources, issue **all N `gh api repos/{owner}/{repo}/contents/{file}` calls in a single message with N parallel Bash calls** (one per manifest + each entry point), then base64-decode the responses together — these are 2-4 independent fetches per typical run. For local sources read directly (also parallelisable, but local reads are fast enough that serial Read tool calls are acceptable).
+
+   | Language | Manifest | Entry points (mode=quick) |
+   |----------|----------|--------------------------|
+   | js / ts / javascript / typescript | `package.json` (root, or primary workspace package per `references/version-resolution.md`) | `index.{ts,js}` and/or `src/index.{ts,js}` if present |
+   | python | `pyproject.toml` (or `setup.py` / `setup.cfg` if no `pyproject.toml`) | top-level `__init__.py` of the package, plus `_version.py` if present |
+   | rust | `Cargo.toml` (`[package]` — workspace root if `version = { workspace = true }`) | `src/lib.rs` |
+   | go | `go.mod` | top-level `*.go` exporting the package surface |
+   | java | `pom.xml` | (manifest alone is sufficient for the modules listing) |
+   | kotlin | `build.gradle` / `build.gradle.kts` | (manifest alone) |
+
+2. Build a JSON payload matching the script contract:
+
+   ```json
+   {
+     "language": "<one of the supported values>",
+     "manifest": {"path": "<relative path>", "content": "<file contents>"},
+     "entries":  [{"path": "<relative path>", "content": "<file contents>"}, ...],
+     "mode":     "quick"
+   }
+   ```
+
+3. Invoke the script and parse its JSON stdout:
+
+   ```bash
+   echo '<payload-json>' | uv run {extractPublicApiScript} --language <lang> --mode quick
+   ```
+
+   On a non-zero exit (codes 1 or 2 per the script's docstring), capture stderr, log it, and fall through to §4.2 (the prose-fallback path) — never HALT just because the script choked on an unusual manifest.
+
+4. Render the returned `package_name`, `exports` (each entry's `name`/`type`/`source_file`), `dependencies`, and any `warnings` to the user. The script also returns `version` — feed that into §4b instead of re-deriving.
+
+5. The script does not enumerate directories under `src/`. The LLM still lists those as "Top-Level Modules/Directories" so the user sees structural context (Maven and Gradle are the exception — for those, the script returns a `modules` array which IS the list).
+
+#### 4.2 Procedure — fallback (not script-supported)
+
+Languages outside the script coverage (Ruby / C# / Swift / etc.) take this path. The §4.1 fall-through on script error also lands here.
+
+Fall back to ad-hoc inspection — `Gemfile` / `*.csproj` / `*.sln` / `Package.swift` / file extension frequency. List top-level source directories as potential modules and note any obvious entry points. Flag the limitation in the analysis summary so the user knows scoping is on coarser signals.
+
+#### 4.3 Output format (both paths)
 
 "**Top-Level Modules/Directories:**
 {numbered list of modules with brief description of each}
 
 **Detected Exports/Entry Points:**
-{numbered list of public-facing items found}"
+{numbered list of public-facing items found — from script output when available, ad-hoc inspection otherwise}"
 
-**Semantic Signals (Forge+ and Deep with ccc only):**
+#### 4.4 Semantic Signals (Forge+/Deep with ccc only)
 
 **Remote source guard:** If the target source was resolved via GitHub API (remote URL, not a local file path), skip this CCC subsection — CCC requires a local source index and cannot operate on remote-only sources. Note: "CCC semantic discovery skipped — target is remote. CCC discovery will run automatically during create-skill after the source is cloned."
 
@@ -124,29 +200,21 @@ If CCC is unavailable or returns no results: skip this subsection silently.
 
 ### 4b. Detect Source Version
 
-**If `target_version` was provided in step 01:**
-- Display: "**Target version:** {target_version} (user-specified)"
-- Still run auto-detection below for informational purposes.
+**When the language was script-supported (§4 took the script path):** the `version` field returned by `{extractPublicApiScript}` IS the detected version — do not re-derive it and do not load `{versionResolutionFile}`. The script already implements the language-specific lookups documented in that reference, so loading the reference here only burns context.
 
-Attempt to auto-detect the source version using the rules from the skill-brief-schema.md Version Detection section:
+**When the language was not script-supported:** load `{versionResolutionFile}` and follow the prose Detection Algorithm directly (Ruby / C# / Swift / etc. fall outside the script's coverage).
 
-**For Python:** Check `pyproject.toml` `[project] version` (static) → if `dynamic = ["version"]`, check `__init__.py` for `__version__` → `_version.py` if exists → `setup.py` `version=` → `git describe --tags --abbrev=0`
-**For JavaScript/TypeScript:** Check root `package.json` `"version"` field → if root has `"private": true` with a `"workspaces"` array or lacks a `"version"` field, fall back to a primary workspace package's `package.json` (e.g., `code/core/package.json`, or the first matching `packages/*/package.json`). For GitHub sources, prefer `gh api repos/{owner}/{repo}/releases/latest` → `tag_name` when a non-pre-release tag exists, over a default-branch pre-release. Treat a version containing `-alpha`, `-beta`, `-rc`, `-next`, or `-canary` as a pre-release.
-**For Rust:** Check `Cargo.toml` `[package] version` (static) → if `version = { workspace = true }`, resolve from workspace root `Cargo.toml` → `git describe --tags --abbrev=0`
-**For Go:** Check `go.mod` or `git describe --tags --abbrev=0`
+Surface the result regardless of which path produced it:
 
-**For GitHub repos:** Use `gh api repos/{owner}/{repo}/contents/{file}` to read version files (decode base64 content).
-**For local repos:** Read the file directly.
+**If `target_version` was provided in step 01:**
+- Display: "**Target version:** {target_version} (user-specified)"
 
 Display: "**Detected version:** {version or 'Not detected — will default to 1.0.0'}"
 
 {If target_version was provided AND auto-detected version differs:}
-"**Note:** Detected version ({detected_version}) differs from your target version ({target_version}). Using target version."
-
-{If target_version was provided:}
-Store `target_version` as the brief's `version` field (overrides auto-detection).
+"**Note:** Detected version ({detected_version}) differs from your target version ({target_version}). Using target version (per `references/version-resolution.md` precedence rules)."
 
-If detection fails or returns a non-semver value: note that version will default to `"1.0.0"` and the user can override in step 04.
+If detection fails or returns a non-semver value: note that version will default to `"1.0.0"` and the user can override in step 04. The actual write happens in step 05.
 
 ### 5. Report Analysis Summary
 

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: