bmad-module-skill-forge 1.4.1 → 1.5.0

package/src/skf-analyze-source/customize.toml

@@ -0,0 +1,55 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-analyze-source.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (uv probe, config load).
+# Overrides append. Use for org-wide pre-flight checks (auth, network,
+# compliance) that must precede any source-analysis work.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (house style, naming conventions, scope guardrails).
+# Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Recommended skills must align with our agent stack."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/analysis-style.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Optional asset overrides ---
+#
+# Lift the canonical asset paths so orgs can substitute house-style copies
+# without forking the skill. Empty string = use the bundled default.
+
+unit_detection_heuristics_path = ""
+brief_schema_path = ""
+analysis_report_template_path = ""
+
+# Pipeline-integration hook invoked after the final result JSON is written
+# (see generate-briefs.md). The command is called as:
+#   <on_complete> --result-path=<absolute_path_to_result_json>
+# Useful for Slack notifications, dashboard ingest, CI hooks, or chaining
+# into checkpoint-preview / a brief linter. Failures are logged to
+# workflow_warnings[] but never fail the workflow.
+#
+# Empty string = no-op (default).
+
+on_complete = ""

package/src/skf-analyze-source/{steps-c/step-01b-continue.md → references/continue.md}

@@ -1,13 +1,15 @@
 ---
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 nextStepOptions:
-  step-02: './step-02-scan-project.md'
-  step-03: './step-03-identify-units.md'
-  step-04: './step-04-map-and-detect.md'
-  step-05: './step-05-recommend.md'
-  step-06: './step-06-generate-briefs.md'
+  step 2: 'scan-project.md'
+  step 3: 'identify-units.md'
+  step 4: 'map-and-detect.md'
+  step 5: 'recommend.md'
+  step 6: 'generate-briefs.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1b: Continue Analysis
 
 ## STEP GOAL:
@@ -22,8 +24,6 @@ To resume the analyze-source workflow from where it was left off in a previous s
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Welcome Back
 
 "**Welcome back!** Let me check where we left off with the source analysis..."
@@ -56,11 +56,11 @@ Map the last completed step to the next step file:
 
 | Last Completed | Next Step |
 |----------------|-----------|
-| step-01-init | step-02-scan-project |
-| step-02-scan-project | step-03-identify-units |
-| step-03-identify-units | step-04-map-and-detect |
-| step-04-map-and-detect | step-05-recommend |
-| step-05-recommend | step-06-generate-briefs |
+| init | scan-project |
+| scan-project | identify-units |
+| identify-units | map-and-detect |
+| map-and-detect | recommend |
+| recommend | generate-briefs |
 
 **IF all steps completed:**
 "**This analysis appears to be complete.** All steps have been finished. Would you like to start a new analysis?"

package/src/skf-analyze-source/{steps-c/step-06-generate-briefs.md → references/generate-briefs.md}

@@ -1,9 +1,11 @@
 ---
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 schemaFile: 'assets/skill-brief-schema.md'
-nextStepFile: './step-07-health-check.md'
+nextStepFile: 'health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
+
 # Step 6: Generate Briefs
 
 ## STEP GOAL:
@@ -19,8 +21,6 @@ To generate a valid skill-brief.yaml file for each confirmed unit using the sche
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Context
 
 Read {outputFile} completely to obtain:
@@ -89,7 +89,7 @@ For each generated brief, check against {schemaFile} validation rules:
 **Validation:** {all passed / N issues found}
 {List any validation issues}
 
-**Ready to write {count} skill-brief.yaml files.** Confirm to proceed? (Y to write / N to abort / M to modify a specific brief)"
+**Ready to write {count} skill-brief.yaml files.** Confirm to proceed? (Y to write all briefs / N to skip writing but continue to report update / M to modify a specific brief / X to cancel and exit the workflow)"
 
 Wait for explicit user confirmation before writing files.
 
@@ -107,10 +107,13 @@ For each confirmed brief:
 - Update the YAML, re-validate, present again
 - Return to confirmation prompt
 
-**IF user aborts (N):**
-- Document abort decision
+**IF user skips writing (N):**
+- Document the skip decision
 - Skip file writing, proceed to report update
 
+**IF user cancels (X):**
+- HARD HALT with exit code 6 (`user-cancelled`). Emit the `SKF_ANALYZE_RESULT_JSON` envelope on stderr with `status: "error"`, `halt_reason: "user-cancelled"`, `brief_paths: []`, and `unit_counts` reflecting the confirmed/skipped/maybe state from step 5
+
 ### 6. Determine Next Workflow Per Unit
 
 For each generated brief, recommend the appropriate next workflow:
@@ -128,7 +131,7 @@ For each generated brief, recommend the appropriate next workflow:
 
 Append the complete "## Generation Results" section to {outputFile}:
 
-Replace `[Appended by step-06-generate-briefs]` with:
+Replace `[Appended by generate-briefs]` with:
 
 **Generated Briefs:**
 | # | Unit Name | Output Path | Validation | Next Workflow |
@@ -146,8 +149,8 @@ Replace `[Appended by step-06-generate-briefs]` with:
 
 Update {outputFile} frontmatter:
 ```yaml
-stepsCompleted: [append 'step-06-generate-briefs' to existing array]
-lastStep: 'step-06-generate-briefs'
+stepsCompleted: [append 'generate-briefs' to existing array]
+lastStep: 'generate-briefs'
 nextWorkflow: '{primary recommendation}'
 ```
 
@@ -182,7 +185,23 @@ To refine any brief, run the recommended next workflow. To re-analyze with diffe
 
 Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_data_folder}/analyze-source-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all generated `skill-brief.yaml` paths in `outputs` and brief counts in `summary`.
 
+### 9b. On-Complete Hook (pipeline integration)
+
+If `{onCompleteCommand}` is non-empty, invoke it now — after the timestamped result JSON and the `analyze-source-result-latest.json` copy have both been written:
+
+```
+{onCompleteCommand} --result-path={result_json_path}
+```
+
+Where `{result_json_path}` is the absolute path to the freshly written `analyze-source-result-latest.json` (stable path is preferred over the timestamped copy so downstream consumers don't need to discover the timestamp).
+
+- 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 (Slack, dashboards, CI), not for gating skill-brief production.
+
+If `{onCompleteCommand}` is empty, skip this section entirely (default behavior — no hook configured).
+
 ### 10. Chain to Health Check
 
-ONLY WHEN the briefs have been written (or skipped per user abort), the report updated, the summary presented, and the result contract saved 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.
+ONLY WHEN the briefs have been written (or skipped per user abort), the report updated, the summary presented, the result contract saved, and the on-complete hook invoked (or skipped per empty `{onCompleteCommand}`) 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.
 

package/src/skf-analyze-source/{steps-c/step-07-health-check.md → references/health-check.md}

@@ -1,10 +1,12 @@
 ---
 # `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, `src/` during development),
+# NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 7: Workflow Health Check
 
 ## STEP GOAL:
@@ -13,7 +15,7 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step-06
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 6
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
 

package/src/skf-analyze-source/{steps-c/step-03-identify-units.md → references/identify-units.md}

@@ -1,9 +1,12 @@
 ---
-nextStepFile: './step-04-map-and-detect.md'
+nextStepFile: 'map-and-detect.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 heuristicsFile: 'references/unit-detection-heuristics.md'
+disqualifyCandidatesScript: '{project-root}/src/shared/scripts/skf-disqualify-candidates.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 3: Identify Units
 
 ## STEP GOAL:
@@ -18,8 +21,6 @@ To classify each detected boundary from the project scan into discrete skillable
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Context
 
 Read {outputFile} to obtain:
@@ -49,13 +50,41 @@ For EACH detected boundary from the scan:
 - `specific-modules` — selected components or packages
 - `public-api` — only exported interfaces
 
-**Step D — Check disqualification rules:**
-- Too small (fewer than 3 source files or 100 lines)
-- Generated code
-- Pure configuration
-- Test-only
-- Vendor/dependency copy
-- Already skilled (exists in existing_skills list)
+**Step D — Run deterministic disqualification filter (script):**
+
+Run the shared disqualification helper to apply the deterministic subset of the rules from {heuristicsFile} (file-count, LoC, generated-code paths, auto-generated header sentinels). The script collapses what was prose-orchestrated counting + path-substring + header scanning into one deterministic call.
+
+1. **Build the boundaries JSON** from the detected boundaries (one entry per candidate boundary). Use forward-slash paths throughout. Shape:
+   ```json
+   [
+     {"name": "<unit-name>",
+      "path": "<rel-from-project-root>",
+      "files": ["<rel-path>", ...]},
+     ...
+   ]
+   ```
+2. **Invoke the script** via stdin:
+   ```bash
+   uv run {disqualifyCandidatesScript} filter --boundaries - --source-root {project-root}
+   ```
+   piping the boundaries JSON on stdin. The script emits:
+   ```json
+   {
+     "kept":    [{"name": "...", "path": "...", "files_count": N, "loc_total": L}, ...],
+     "dropped": [{"name": "...", "reason": "<too-few-files|too-low-loc|generated-code|auto-generated-tag>", "context": {...}}, ...],
+     "stats":   {"kept": N, "dropped": N, "by_reason": {"<reason>": N, ...}}
+   }
+   ```
+3. **Parse the JSON result** and stash `kept[]` and `dropped[]` in workflow state for §3 (classification table) and §5 (recommendation summary). The `kept` set is the candidate pool for the boundary-type + scope-type classification that follows; the `dropped` set drives the Disqualification table.
+
+**LLM-judged disqualifications (not in script — apply on top of `kept[]`):**
+- **Pure configuration** — only config files (e.g., `.json`/`.yaml`) with no executable logic
+- **Test-only** — test utilities with no production code
+- **Already skilled** — exists in `existing_skills` list (recommend `update-skill` instead)
+
+Remove any boundary that fails one of these LLM-judged rules from the working `kept` set and append it to `dropped[]` with the appropriate reason. Reasons recorded by the script (`too-few-files`, `too-low-loc`, `generated-code`, `auto-generated-tag`) are authoritative; do NOT re-evaluate those rules manually.
+
+**Qualification CONFIRMATION:** Visually skim the script's `kept`/`dropped` decisions for sanity (e.g., a boundary you expected to qualify that landed in `dropped` — surface the script's `reason` and `context.first_match` to the user in §5 so they can override if the heuristic was wrong for this project).
 
 ### 3. Build Unit Classification Table
 
@@ -105,7 +134,7 @@ Wait for user feedback. Adjust classifications based on user input.
 
 Append the complete "## Identified Units" section to {outputFile}:
 
-Replace the placeholder `[Appended by step-03-identify-units]` with:
+Replace the placeholder `[Appended by identify-units]` with:
 - Classification table (qualifying units)
 - Disqualification table
 - Already-skilled units list
@@ -114,17 +143,18 @@ Replace the placeholder `[Appended by step-03-identify-units]` with:
 
 Update {outputFile} frontmatter:
 ```yaml
-stepsCompleted: [append 'step-03-identify-units' to existing array]
-lastStep: 'step-03-identify-units'
+stepsCompleted: [append 'identify-units' to existing array]
+lastStep: 'identify-units'
 ```
 
 ### 7. Present MENU OPTIONS
 
-Display: "**Select:** [C] Continue to Export Mapping and Integration Detection"
+Display: "**Select:** [C] Continue to Export Mapping and Integration Detection | [X] Cancel and exit"
 
 #### Menu Handling Logic:
 
 - IF C: Save classifications to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
+- IF X: HARD HALT with exit code 6 (`user-cancelled`). Emit the `SKF_ANALYZE_RESULT_JSON` envelope on stderr with `status: "error"`, `halt_reason: "user-cancelled"`, and counts/paths reflecting state at cancellation
 - IF Any other: help user, then [Redisplay Menu Options](#7-present-menu-options)
 
 #### EXECUTION RULES:

package/src/skf-analyze-source/{steps-c/step-01-init.md → references/init.md}

@@ -1,10 +1,12 @@
 ---
-nextStepFile: './step-02-scan-project.md'
-continueFile: './step-01b-continue.md'
+nextStepFile: 'scan-project.md'
+continueFile: 'continue.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 templateFile: 'templates/analysis-report-template.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1: Initialize Analysis
 
 ## STEP GOAL:
@@ -19,8 +21,6 @@ To initialize the analyze-source workflow by loading configuration, detecting co
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Check for Existing Report (Continuation Detection)
 
 Look for {outputFile}.
@@ -46,6 +46,8 @@ Look for {outputFile}.
 
 ### 3. Collect Project Path
 
+**Headless flag consumption:** If `--project-path <path>` was passed at invocation, set `project_paths[]` directly from the flag value (comma-split if multiple paths were supplied), skip the prompt below, and proceed to validation. Otherwise prompt as today.
+
 "**Welcome to Analyze Source — the SKF decomposition engine.**
 
 I'll analyze your project to identify discrete skillable units and produce skill-brief.yaml files for each recommended unit.
@@ -68,8 +70,25 @@ Wait for user input.
 - **IF any invalid:** "Path `{path}` doesn't appear to be valid. Please correct it."
 - Store as `project_paths[]` array in report frontmatter (single path stored as 1-element array for consistency)
 
+**Collect intent hint** (drives recommendation ranking in Step 5):
+
+**Headless flag consumption:** If `--intent-hint <text>` was passed at invocation, set workflow-context `intent_hint` directly from the flag value, skip the prompt below, and proceed. If `{headless_mode}` is true and no `--intent-hint` was supplied, set `intent_hint = ""` (empty) and proceed without prompting.
+
+"**Optional: What are you hoping to get out of this analysis?**
+
+For example:
+- Skills for a specific domain (e.g., 'authentication and authorization')
+- Target consumer agents (e.g., 'skills our backend team's AI assistants will call')
+- Constraints (e.g., 'we only want stable public APIs, no internal modules')
+
+Type details, or press Enter to skip."
+
+Wait for user input. Store as workflow-context `intent_hint` (empty string if skipped).
+
 ### 4. Collect Optional Scope Hints
 
+**Headless flag consumption:** If `--scope-hint <text>` was passed at invocation, set workflow-context `scope_hint` directly from the flag value, skip the prompt below, and proceed. If `{headless_mode}` is true and no `--scope-hint` was supplied, set `scope_hint = ""` (empty) and proceed without prompting.
+
 "**Optional: Do you have scope hints to narrow the analysis?**
 
 For example:
@@ -99,8 +118,8 @@ Create {outputFile} from {templateFile}.
 
 **Populate frontmatter:**
 ```yaml
-stepsCompleted: ['step-01-init']
-lastStep: 'step-01-init'
+stepsCompleted: ['init']
+lastStep: 'init'
 lastContinued: ''
 date: '{current_date}'
 user_name: '{user_name}'
@@ -108,6 +127,8 @@ project_name: '{project_name}'
 project_paths: ['{provided_project_path}']
 forge_tier: '{detected_tier}'
 existing_skills: [{list of existing skill names}]
+intent_hint: '{intent_hint or empty string}'
+scope_hint: '{scope_hint or empty string}'
 confirmed_units: []
 stack_skill_candidates: []
 nextWorkflow: ''

package/src/skf-analyze-source/{steps-c/step-04-map-and-detect.md → references/map-and-detect.md}

@@ -1,9 +1,11 @@
 ---
-nextStepFile: './step-05-recommend.md'
+nextStepFile: 'recommend.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 heuristicsFile: 'references/unit-detection-heuristics.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 4: Map Exports and Detect Integrations
 
 ## STEP GOAL:
@@ -12,15 +14,13 @@ To analyze each qualifying unit's export surface and import graph, detect cross-
 
 ## Rules
 
-- Use subprocess Pattern 2 (per-unit deep analysis) when available
+- Delegate per-unit deep analysis to a subagent when available (parallelizes across units; main-thread fallback is fine)
 - For each qualifying unit, perform thorough export surface analysis — do not shortcut
 - Do not make recommendations (Step 05)
 - Tier-aware depth: Quick (file-level), Forge (AST), Deep (AST + semantic)
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Context
 
 Read {outputFile} to obtain:
@@ -29,23 +29,31 @@ Read {outputFile} to obtain:
 
 Load {heuristicsFile} for stack skill candidate detection rules.
 
-### 2. Map Export Surfaces Per Unit
+### 2. Map Export Surfaces Per Unit (Subagent Fan-Out)
+
+DO NOT BE LAZY — For EACH qualifying unit, delegate deep analysis to a subagent so per-unit work runs in parallel and the parent's context stays clean.
 
-DO NOT BE LAZY — For EACH qualifying unit, launch a subprocess (or analyze in main thread) that:
+**Subagent fan-out protocol:**
 
-**Size-aware strategy selection:**
-- **< 50 files:** Full export scan — analyze every file for exports
-- **50-200 files:** Targeted scan — entry points (`__init__.py`, `index.ts`, `lib.rs`) + public modules + barrel exports only
-- **200+ files:** Entry-point strategy — analyze top-level entry point for public API surface, list submodule entry points, analyze each submodule entry point only. Report coverage confidence based on percentage of files analyzed.
+1. **Build the qualifying-unit list.** Read the unit list produced upstream (Step §3 / §4 outputs already in workflow context — names, paths, scope types, languages, file counts). Do NOT re-scan the project here.
 
-**Per-unit analysis (scaled by strategy above):**
+2. **Delegate per-unit deep analysis to a subagent.** For each qualifying unit, launch a subagent task with these explicit constraints:
+   - The subagent reads ONLY that unit's directory tree
+   - The subagent analyzes exports / usage / CCC signals / scripts+assets for that one unit
+   - **The parent does NOT read the unit's source files before delegating** (avoid the implicit-read trap — the whole point of fan-out is to keep large source bodies out of the parent's context)
 
-1. Scans the unit's directory for export/public interface files
-2. Counts and categorizes exports based on forge tier:
+3. **Per-unit analysis the subagent performs (scaled by size-aware strategy):**
+
+   **Size-aware strategy selection:**
+   - **< 50 files:** Full export scan — analyze every file for exports
+   - **50-200 files:** Targeted scan — entry points (`__init__.py`, `index.ts`, `lib.rs`) + public modules + barrel exports only
+   - **200+ files:** Entry-point strategy — analyze top-level entry point for public API surface, list submodule entry points, analyze each submodule entry point only. Report coverage confidence based on percentage of files analyzed.
+
+   **Tier-aware depth:**
    - **Quick tier:** Count files by type, identify index/barrel files, list directory structure
    - **Forge tier:** Parse export statements, identify public API surface, count exported functions/classes/types
    - **Forge+ tier:** All Forge analysis plus:
-     - If `tools.ccc` is true: run `ccc_bridge.search("{unit_name} exports public API", top_k=15)` — **Tool resolution:** `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search` CLI; see `knowledge/tool-resolution.md` — to discover semantically relevant files beyond directory scan
+     - If `tools.ccc` is true: run `ccc_bridge.search("{unit_name} exports public API", top_k=15)` to discover semantically relevant files beyond directory scan. Tool resolution: prefer the `/ccc` skill search (Claude Code) or ccc MCP server (Cursor); fall back to the `ccc search` CLI if neither is available; if no ccc tool resolves, skip CCC discovery and record `ccc: unavailable` in per-unit findings.
      - Merge CCC-discovered files with scoped file list — files from CCC that are within the unit's directory are added to the analysis queue
      - Record CCC signals in per-unit findings: top 3 CCC-ranked file names (or "—" if no ccc results)
    - **Deep tier:** All Forge analysis plus:
@@ -53,20 +61,39 @@ DO NOT BE LAZY — For EACH qualifying unit, launch a subprocess (or analyze in
      - ast-grep type/interface mapping: `ast-grep -p 'interface $NAME' --lang typescript` or `ast-grep -p 'class $NAME($$$)' --lang python`
      - If QMD available: query for temporal evolution of identified exports (deprecation signals, recent additions, refactoring patterns)
      - Record semantic relationships between exports (which exports reference/depend on each other)
-3. Returns structured findings to parent:
-   - Export count (files, functions, types, classes)
-   - Primary export patterns (barrel exports, direct exports, re-exports)
-   - Public API surface size estimate
-   - Key entry points
-   - Script/asset presence: check for `scripts/`, `bin/`, `assets/`, `templates/` directories and files matching detection signals in `{heuristicsFile}`. Record counts in per-unit findings.
+
+   **Subagent must also record:**
+   - Script/asset presence: check for `scripts/`, `bin/`, `assets/`, `templates/` directories and files matching detection signals in `{heuristicsFile}`
    - Analysis strategy used and coverage confidence
 
-**Per-unit export summary:**
+4. **Subagent return contract.** Each subagent returns ONLY this JSON object — no prose, no commentary, no markdown fences:
+
+   ```json
+   {
+     "unit_name": "...",
+     "files_count": N,
+     "exports_count": N,
+     "export_pattern": "...",
+     "api_surface": ["..."],
+     "scripts_assets": {"scripts": [], "assets": []},
+     "ccc_signals": {"top_files": [], "available": <bool>},
+     "strategy_used": "ast-grep|regex|main-thread",
+     "confidence": "T1|T2|T1-low"
+   }
+   ```
+
+5. **Parent post-processing.** Strip any wrapping markdown fences (subagents sometimes wrap JSON in ` ```json … ``` ` despite the contract) before parsing. Validate each payload against the contract; if a key is missing, log a warning to `workflow_warnings[]` and continue with that unit's degraded record.
+
+6. **Aggregate.** Collect all per-unit JSON payloads into `per_unit_findings[]` in workflow context for use by §3 (import graph), §4 (integration points), §5 (stack candidates), §6 (findings presentation), and downstream stages (recommend.md, generate-briefs.md).
+
+**Per-unit export summary (built from `per_unit_findings[]`):**
 
 | Unit | Files | Exports | Export Pattern | API Surface | Scripts/Assets | CCC Signals |
 |------|-------|---------|----------------|-------------|----------------|-------------|
 | {name} | {count} | {count} | {pattern} | {small/medium/large} | {N scripts, M assets or --} | {CCC signals or --} |
 
+**Graceful degradation.** If subagents are unavailable in the current runtime, the parent performs the per-unit analysis sequentially in the main thread using the same size-aware strategy and tier-aware depth as above. Each main-thread analysis still produces the same JSON record shape so downstream stages remain agnostic to the execution mode. Record `strategy_used: "main-thread"` for every unit processed this way.
+
 ### 3. Map Import Graph
 
 For each qualifying unit, analyze inbound and outbound imports:
@@ -143,20 +170,20 @@ Wait for user feedback. Adjust analysis based on user input.
 ### 7. Append to Report
 
 Append the complete "## Export Map" section to {outputFile}:
-Replace `[Appended by step-04-map-and-detect]` under Export Map with:
+Replace `[Appended by map-and-detect]` under Export Map with:
 - Per-unit export summary table
 - Export pattern analysis
 
 Append the complete "## Integration Points" section to {outputFile}:
-Replace `[Appended by step-04-map-and-detect]` under Integration Points with:
+Replace `[Appended by map-and-detect]` under Integration Points with:
 - Cross-reference matrix
 - Integration point details
 - Stack skill candidate flags
 
 Update {outputFile} frontmatter:
 ```yaml
-stepsCompleted: [append 'step-04-map-and-detect' to existing array]
-lastStep: 'step-04-map-and-detect'
+stepsCompleted: [append 'map-and-detect' to existing array]
+lastStep: 'map-and-detect'
 stack_skill_candidates: [{list flagged candidate groupings}]
 ```
 

package/src/skf-analyze-source/{steps-c/step-05-recommend.md → references/recommend.md}

@@ -1,11 +1,13 @@
 ---
-nextStepFile: './step-06-generate-briefs.md'
+nextStepFile: 'generate-briefs.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 schemaFile: 'assets/skill-brief-schema.md'
 advancedElicitationSkill: '/bmad-advanced-elicitation'
 partyModeSkill: '/bmad-party-mode'
 ---
 
+<!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
+
 # Step 5: Recommend
 
 ## STEP GOAL:
@@ -20,8 +22,6 @@ To present each qualifying unit as a recommendation with evidence-based rational
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Context
 
 Read {outputFile} completely to obtain:
@@ -30,9 +30,12 @@ Read {outputFile} completely to obtain:
 - Integration points and coupling analysis
 - Stack skill candidates from frontmatter
 - Existing skills from frontmatter
+- `intent_hint` from frontmatter (captured in init.md §3 — user's stated goal for the analysis; empty string if skipped)
 
 Load {schemaFile} for reference on what skill-brief.yaml requires (so recommendations are actionable).
 
+**Apply `intent_hint` when ranking units.** If `intent_hint` is non-empty, use it to bias the order in which recommendation cards are presented and to soften the rationale for units that fall outside the stated intent (e.g., when `intent_hint` mentions "authentication and authorization", rank auth-related units first and flag unrelated units with a one-line rationale acknowledging the mismatch). If `intent_hint` is empty, present in the deterministic order from the export map.
+
 ### 2. Build Recommendation Cards
 
 For EACH qualifying unit, prepare a recommendation card:
@@ -81,7 +84,10 @@ Present each recommendation card, then after ALL cards:
 - **N** — Reject: skip this unit
 - **M** — Modify: adjust name, scope, or description before confirming
 
-You can respond with a list (e.g., '1:Y, 2:Y, 3:N, 4:M') or address each individually.
+**Bulk shortcuts:**
+- `all-Y` — confirm every recommendation as-is
+- `all-N` — skip every recommendation
+- Individual response list (e.g., `1:Y, 2:N, 3:M, ...`) — explicit per-unit decisions (use this when you want to mix Y/N/M or modify any unit)
 
 **Questions?** Ask 'why?' about any recommendation and I'll explain my reasoning with specific evidence."
 
@@ -137,7 +143,7 @@ Wait for explicit final confirmation.
 
 Append the complete "## Recommendations" section to {outputFile}:
 
-Replace `[Appended by step-05-recommend]` with:
+Replace `[Appended by recommend]` with:
 - All recommendation cards (including rationale)
 - User decisions per unit (confirmed/rejected/modified)
 - Stack skill candidate decisions
@@ -145,15 +151,15 @@ Replace `[Appended by step-05-recommend]` with:
 
 Update {outputFile} frontmatter:
 ```yaml
-stepsCompleted: [append 'step-05-recommend' to existing array]
-lastStep: 'step-05-recommend'
+stepsCompleted: [append 'recommend' to existing array]
+lastStep: 'recommend'
 confirmed_units: [{list of confirmed unit names}]
 stack_skill_candidates: [{updated list with user decisions}]
 ```
 
 ### 8. Present MENU OPTIONS
 
-Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [D] Discover Additional Source [C] Continue to Brief Generation"
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [D] Discover Additional Source [C] Continue to Brief Generation [X] Cancel and exit"
 
 #### Menu Handling Logic:
 
@@ -161,6 +167,7 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [D] Disc
 - IF P: Invoke {partyModeSkill}, and when finished redisplay the menu
 - IF D: Accept a new repo path/URL from the user. Run a lightweight scan + classify (subset of steps 02-03) for the new source only. Merge new units into the existing report and update `project_paths[]` in frontmatter. Run export mapping for the new units (same logic as step 04 section 2). Generate recommendation cards for the new units and present them for confirmation. Then redisplay this menu.
 - IF C: Save recommendations to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
+- IF X: HARD HALT with exit code 6 (`user-cancelled`). Emit the `SKF_ANALYZE_RESULT_JSON` envelope on stderr with `status: "error"`, `halt_reason: "user-cancelled"`, and counts/paths reflecting state at cancellation
 - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options)
 
 #### EXECUTION RULES: