bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/skf-analyze-source/references/map-and-detect.md

@@ -1,7 +1,31 @@
 ---
 nextStepFile: 'recommend.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-heuristicsFile: '{unitDetectionHeuristicsPath}'
+heuristicsFile: 'references/unit-detection-heuristics.md'
+discoverFile: 'references/discover-additional-source.md'
+unitExportsFile: 'references/map-unit-exports.md'
+scanRootFile: 'references/scan-root.md'
+extractPublicApiProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-extract-public-api.py'
+  - '{project-root}/src/shared/scripts/skf-extract-public-api.py'
+scanManifestsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-scan-manifests.py'
+  - '{project-root}/src/shared/scripts/skf-scan-manifests.py'
+countImportsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-count-imports.py'
+  - '{project-root}/src/shared/scripts/skf-count-imports.py'
+findCyclesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-find-cycles.py'
+  - '{project-root}/src/shared/scripts/skf-find-cycles.py'
+pairIntersectProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-pair-intersect.py'
+  - '{project-root}/src/shared/scripts/skf-pair-intersect.py'
+skillInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
+checkUnitRecordsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-check-unit-records.py'
+  - '{project-root}/src/shared/scripts/skf-check-unit-records.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -10,22 +34,31 @@ heuristicsFile: '{unitDetectionHeuristicsPath}'
 
 ## STEP GOAL:
 
-To analyze each qualifying unit's export surface and import graph, detect cross-unit integration points, and flag potential stack skill candidates — completing the analysis foundation needed for recommendations.
+To analyze each qualifying unit's export surface and import graph, detect cross-unit integration points, propose composite merges and flag potential stack skill candidates, completing the analysis foundation needed for recommendations.
 
 ## Rules
 
 - 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
 
+Every HARD HALT in this step names its exit code, `halt_reason` and phase. When `{headless_mode}` is true it first prints its envelope on stderr through the shared emitter (`{emitEnvelopeHelper}` and `{run_dir}` come from SKILL.md On Activation): stage `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "mode": "interactive", "report_path": "{outputFile as an absolute path}"}`, plus `"path"` when the halt names one, then run
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+and display the line it prints verbatim. Write the payload as valid JSON: in the halt message and `path`, replace each backslash with / and each double quote with a backtick. If the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing.
+
 ### 1. Load Context
 
 Read {outputFile} to obtain:
-- Qualifying units from Identified Units section (names, paths, scope types, languages)
-- `forge_tier` from frontmatter
+- Qualifying units from the Identified Units section: names, project paths, paths, scope types, languages, file counts, statuses and each unit's own manifest (path, name and ecosystem). A unit whose status is `deferred` (outside the goal the user stated) stays in the report and is not analyzed here
+- `forge_tier`, `scan_roots` (each project path's scan root) and `refs` from frontmatter
+
+**A scan root that is gone.** A session that resumed this report runs in a new run folder, and the folder of the session that made a copy may be gone. When a recorded scan root no longer exists, make it again by {scanRootFile} into this run's `{run_dir}/source-{i}` and update `scan_roots` in {outputFile}'s frontmatter. If a command there fails, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `map-and-detect:1`, path `{path}`): "{path} could not be fetched: {the first stderr line}."
 
 Load {heuristicsFile} for stack skill candidate detection rules.
 
@@ -33,91 +66,65 @@ Load {heuristicsFile} for stack skill candidate detection rules.
 
 For each qualifying unit, delegate deep analysis to a subagent so per-unit work runs in parallel and the parent's context stays clean.
 
+**Resolve `{extractPublicApiHelper}`** from `{extractPublicApiProbeOrder}` and **`{checkUnitRecordsHelper}`** from `{checkUnitRecordsProbeOrder}`; first existing path wins for each. If one has no candidate, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `map-and-detect:2`): "`{the missing script}` is missing. Re-install SKF."
+
 **Subagent fan-out protocol:**
 
-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.
-
-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)
-
-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)` 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:
-     - ast-grep structural export extraction: `ast-grep -p 'export $$$' --lang typescript` or equivalent per language to build a verified export inventory
-     - 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)
-
-   **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
-
-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).
+1. **Build the qualifying-unit list.** Read the unit list produced upstream (names, project paths, paths, scope types, languages, file counts), leaving out the deferred units. Do not re-scan the project here.
 
-**Per-unit export summary (built from `per_unit_findings[]`):**
+2. **Map each unit's exports.** Load, read the entire file, then execute {unitExportsFile} for the qualifying units: it delegates each one to a subagent with `{unit_root}` its path under the scan root of its project path and its file count from Identified Units, has the subagent write the unit's record to `{run_dir}/unit-records/{unit_name}.json`, checks the records and returns them.
 
-| 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 --} |
+3. **Aggregate.** Collect the checked `records` into `per_unit_findings[]` in workflow context for use by §3 (import graph), §4 (integration points), §5 (composites and stack candidates), §6 (findings presentation), and downstream stages (recommend.md, generate-briefs.md).
 
-**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.
+**Per-unit export summary (built from `per_unit_findings[]`):**
+
+| Unit | Files | Exports | Export Pattern | API Surface | CCC Signals |
+|------|-------|---------|----------------|-------------|-------------|
+| {name} | {count} | {count} | {pattern} | {small/medium/large} | {CCC signals or --} |
 
 ### 3. Map Import Graph
 
-For each qualifying unit, analyze inbound and outbound imports:
+Which unit imports which, how many files import each unit, which units are imported together and which import each other in a cycle each have one right answer per tree, so the helpers compute them and this section reads their output.
+
+**Resolve `{scanManifestsHelper}`, `{countImportsHelper}`, `{findCyclesHelper}` and `{pairIntersectHelper}`** from their probe orders; first existing path wins for each. If one has no candidate, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `map-and-detect:3`): "`{the missing script}` is missing. Re-install SKF."
+
+**Units JSON.** One entry per qualifying unit, from its Identified Units row: `{"name": "<unit name>", "path": "<its path, relative to the source root>", "manifest_name": "<its own manifest's name>", "ecosystem": "<its own manifest's ecosystem>"}`, with `manifest_name` and `ecosystem` left out for a unit without a manifest. The import helper works out the names other code imports each unit by from what the unit declares. Add `"modules"` only for a folder without a manifest that code imports by name: a Python package folder (`["acme"]`) or a Go package inside a module (`["example.com/svc/internal/auth"]`).
+
+Run this once per project path, the `{i}`-th entry of `project_paths[]`, with `{source_root}` its scan root, over the units under it. `{run_dir}/manifests-{i}.json` is the manifest scan scan-project wrote; when it is missing, as in a session that resumed the report, run `uv run {scanManifestsHelper} scan "{source_root}" > "{run_dir}/manifests-{i}.json"` first.
+
+```bash
+cat > "{run_dir}/units-{i}.json" <<'SKF_UNITS'
+{"units": [<one entry per qualifying unit under {source_root}>]}
+SKF_UNITS
+uv run {countImportsHelper} count "{source_root}" --units "{run_dir}/units-{i}.json" --deps "{run_dir}/manifests-{i}.json" > "{run_dir}/imports-{i}.json"
+uv run {countImportsHelper} summary "{run_dir}/imports-{i}.json" --manifests "{run_dir}/manifests-{i}.json"
+uv run {findCyclesHelper} find --edges "{run_dir}/imports-{i}.json"
+uv run {countImportsHelper} count "{source_root}" --units "{run_dir}/units-{i}.json" --format libraries > "{run_dir}/importers-{i}.json"
+uv run {pairIntersectHelper} intersect --libraries "{run_dir}/importers-{i}.json"
+```
 
-**Outbound imports (this unit imports from):**
-- Which other qualifying units does it depend on?
-- Which external dependencies does it use?
+A helper that exits non-zero names the problem on stderr (a unit name or path given twice, a malformed entry): fix the units JSON and run the block again.
 
-**Inbound imports (other units import from this):**
-- Which other qualifying units consume this unit's exports?
-- How many import sites exist?
+Read the output. The `summary` line prints the graph without the file lists, which stay in `{run_dir}/imports-{i}.json`:
+
+- **Imports From / Imported By:** each summary `units[]` entry's `imports_from` and `imported_by`. Its `file_count` is the number of import sites (files outside the unit that import it).
+- **External Deps:** each summary `units[]` entry's `external_dep_count`, the number of manifest dependencies its files import.
+- **Mutual dependencies:** each `cycles[]` entry (`["a", "b", "a"]` is two units that import each other).
+- **Co-imported units:** each `pairs[]` entry: `intersection_count` files import both units, listed in `files`. When `truncated` is true, run that last call again with `--top-k` set to its `total_pairs`, so no pair is left out.
+- **Cohesion evidence:** the summary's `umbrella_candidates[]` and `manifests[]` (each manifest's `name`, `private` and `internal_deps`), which §5 reads.
 
 **Build cross-reference matrix:**
 
-| Unit | Imports From | Imported By | External Deps |
-|------|-------------|-------------|---------------|
-| {name} | {list units} | {list units} | {count} |
+| Unit | Imports From | Imported By | Import Sites | External Deps |
+|------|-------------|-------------|--------------|---------------|
+| {name} | {imports_from} | {imported_by} | {file_count} | {external_dep_count, or --} |
 
 ### 4. Detect Integration Points
 
 Identify cross-unit integration patterns:
 
 **Direct integrations:**
-- Unit A imports from Unit B → document the interface boundary
+- Each §3 summary `edge_files[]` entry (unit `from` imports from unit `to` in `file_count` files, the first of them listed in `files` with the line of their first import) → document the interface boundary. When the boundary needs every file, read that entry in `{run_dir}/imports-{i}.json`
 - Shared type definitions across units
 - Cross-unit function calls
 
@@ -127,70 +134,81 @@ Identify cross-unit integration patterns:
 - Files involved (with paths)
 - Coupling strength (tight / loose / indirect)
 
-### 5. Flag Stack Skill Candidates
+### 5. Decide Composites and Stack Skill Candidates
+
+Decide both here, in one pass over §3's graph and §4's integration map, so each group of units is judged once: a **composite** when its units only deliver value together, a **stack skill candidate** when each is useful on its own and they are also used together. A group is never both.
 
-Check each of the four stack-skill indicators defined in {heuristicsFile}'s Stack Skill Candidate Detection section — co-import frequency, integration adapter, shared state, orchestration layer — against the units.
+**Resolve `{skillInventoryHelper}`** from `{skillInventoryProbeOrder}`; first existing path wins. If no candidate exists, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `map-and-detect:5`): "`skf-skill-inventory.py` is missing. Re-install SKF."
 
-**For each candidate, document:**
+1. **Composite merge proposals.** Apply the Composite Boundary triggers in {heuristicsFile} (mutual hard dependency, shared integration surface, and the Cohesion Triggers: umbrella facade, shared runtime contract, internal building blocks) to the qualifying units. The evidence comes from the helpers: `cycles[]` for a mutual dependency, `edge_files[]` and §4's shared types for a shared integration surface, and the §3 summary's `umbrella_candidates[]` and each manifest's `internal_deps` and `private` for the cohesion triggers. For each group that meets a trigger, propose one composite:
+   - **Constituents:** the unit names and paths merged
+   - **Heuristic and evidence:** the trigger and what showed it (the cycle, the umbrella candidate and the members its `internal_deps` cover, the `private` flags, the shared types and their files)
+   - **Name:** name every proposal in one call to the helper that names every unit and brief ({heuristicsFile}'s Unit Names), one entry each: `target` is its constituents' project path, `manifest_name` the facade's manifest name when an umbrella facade triggered the merge (else null), and `members` the constituents' manifest names:
+     ```bash
+     uv run {skillInventoryHelper} derive-name --from - <<'SKF_COMPOSITE_NAMES'
+     [{"target": "<project path>", "manifest_name": "<facade name or null>", "members": ["<constituent manifest name>", ...]}, ...]
+     SKF_COMPOSITE_NAMES
+     ```
+     Each `names[].name` is that proposal's name; give the entries `unnamed` and `duplicates` list a name of your own, from their constituents.
+2. **Stack skill candidates.** Check the four stack-skill indicators defined in {heuristicsFile}'s Stack Skill Candidate Detection section against the units no composite proposal groups: co-import frequency is a §3 `pairs[]` entry with an `intersection_count` of 3 or more, and integration adapter, shared state and orchestration layer come from §4. When the user rejects a composite in §6, check its constituents here too.
+
+**For each stack skill candidate, document:**
 - Units involved
 - Detection signal
 - Recommended stack skill grouping
 - Evidence (specific files/lines)
 
-### 6. Present Findings
+### 6. Present the Findings and Confirm
 
-"**Export Mapping and Integration Detection Complete**
+Show the user the per-unit export summary, the cross-reference matrix, each integration point (source to target, type, coupling), the composite merge proposals, the stack skill candidates (units involved and detection signal), and the observations (key architectural patterns, tightly and loosely coupled areas). Present the proposals as a table:
 
-**Export Map Summary:**
-{Per-unit export summary table}
+| # | Composite Name | Constituents | Heuristic | Evidence |
+|---|----------------|--------------|-----------|----------|
+| 1 | {name} | {constituent unit names and paths} | {mutual hard dependency / shared integration surface / umbrella facade / shared runtime contract / internal building blocks} | {evidence} |
 
-**Cross-Reference Matrix:**
-{Import graph matrix}
+Then display:
 
-**Integration Points:** {count}
-{List each integration with source → target, type, coupling}
+"Accept or reject each composite merge proposal (every one is accepted unless you reject it), or name an integration pattern to investigate further. **Select:** [C] Continue to Recommendations | [D] Discover Additional Source | [X] Cancel and exit"
 
-**Stack Skill Candidates:** {count}
-{List each candidate with units involved and detection signal}
+An approved composite replaces its constituents as one unit: `Boundary Type: Composite`, its constituents' paths as its Path, the project path they share, the scope type and language of its dominant constituent (the one with the most exports), and confidence from the strength of its trigger. A rejected one leaves its constituents as separate units.
 
-**Observations:**
-- {Key architectural patterns observed}
-- {Tightly coupled areas}
-- {Loosely coupled areas ideal for independent skills}
+#### Menu Handling Logic:
 
-Does this analysis look complete? Any integration patterns I should investigate further?"
+- IF C: go to §7
+- IF D: load, read the entire file, then execute {discoverFile} with the project path the user gives. It adds the new path's units to Identified Units and returns their export records, import graph, composite proposals and stack skill candidates, which join the findings here, so §7 writes the Export Map and Integration Points with them: redisplay §6 with them included.
+- IF X: HARD HALT (exit code 6, `halt_reason: "user-cancelled"`, phase `map-and-detect:6`): "Cancelled at the export mapping."
+- IF Any other: apply the composite decisions, investigate what the user named, show what changed, then [Redisplay Menu Options](#6-present-the-findings-and-confirm)
+
+**GATE [default: C]**: present the menu and wait for the user's choice. If `{headless_mode}`: accept every composite merge proposal and continue with [C], and record that decision the moment it is taken: stage `{run_dir}/decision.json` as `{"gate": "map-and-detect.findings", "default_action": "C", "taken_action": "C", "reason": "headless: auto-accept {count} composite merges and continue past the integration analysis", "evidence": {"composites": [<the name of each accepted composite>], "stack_skill_candidates": <the candidate count>}}`, then run
+
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-analyze-source --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+```
 
-Wait for user feedback. Adjust analysis based on user input.
+If the command fails, go on: only that entry is lost.
 
-### 7. Append to Report
+### 7. Append to Report and Continue
 
-Append the complete "## Export Map" section to {outputFile}:
-Replace `[Appended by map-and-detect]` under Export Map with:
+Replace `[Appended by map-and-detect]` under Export Map in {outputFile} with:
 - Per-unit export summary table
 - Export pattern analysis
 
-Append the complete "## Integration Points" section to {outputFile}:
 Replace `[Appended by map-and-detect]` under Integration Points with:
 - Cross-reference matrix
 - Integration point details
+- Composite merge proposals and decisions: name, constituents with their paths, heuristic, evidence
 - Stack skill candidate flags
 
+In the Identified Units classification table, replace the constituent rows of each approved composite with the composite's one row (its Path the constituents' paths), so recommend builds one card for it.
+
 Update {outputFile} frontmatter:
 ```yaml
 stepsCompleted: [append 'map-and-detect' to existing array]
 lastStep: 'map-and-detect'
+confirmed_composites: [{list of approved composites: {name, constituents: [{name, path}], heuristic}}]
 stack_skill_candidates: [{list flagged candidate groupings}]
 ```
 
-### 8. Present MENU OPTIONS
-
-Display: "**Select:** [C] Continue to Recommendations | [D] Discover Additional Source"
-
-#### Menu Handling Logic:
-
-- IF C: Save findings to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
-- IF D: Accept a new repo path/URL from the user. Run a lightweight scan (directory structure + manifest detection from step 02) and classify (unit identification from step 03) for the new source only. Merge results into the existing report — append new units to the unit list, update `project_paths[]` in frontmatter. Then redisplay this step's export mapping for the new units before returning to the menu.
-- IF Any other: help user, then [Redisplay Menu Options](#8-present-menu-options)
-
-**GATE [default: C]** — present the menu and wait for the user's choice. If `{headless_mode}`: auto-proceed with [C] Continue past export/integration findings, log: "headless: auto-continue past integration analysis".
+(`confirmed_composites` is an empty array when no composite was proposed or all were rejected. generate-briefs puts every constituent's path in the composite brief's `scope.include`.)
 
+Then load, read the entire file, then execute {nextStepFile}.

package/src/skf-analyze-source/references/map-unit-exports.md

@@ -0,0 +1,68 @@
+<!-- Config: communicate in {communication_language}. -->
+
+# Map Each Unit's Exports
+
+The per-unit export analysis, stated once for the two files that run it: map-and-detect section 2, for every qualifying unit, and discover-additional-source section 4, for the units it adds. The file that loads this one has resolved `{extractPublicApiHelper}` and `{checkUnitRecordsHelper}` and gives each unit its name, its scope type (`{unit_scope_type}`), its language, its folder (`{unit_root}`: its path under the scan root of its project path) and its file count (the `files_count` of its disqualification record, which the Files column of Identified Units shows); `{forge_tier}` is the report's. This file returns to it with the checked records.
+
+## 1. Delegate Each Unit to a Subagent
+
+For each 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 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)
+- The subagent writes its record (§3) to a file of the run folder and returns only that file's path, so the parent never copies a record: pass it `{run_dir}` and the resolved `{extractPublicApiHelper}`
+
+**Graceful degradation.** If subagents are unavailable in the current runtime, the parent performs the per-unit analysis sequentially in the main thread with the same export-surface call and tier-aware extras. Each main-thread analysis still writes the same JSON record, so the later steps do not depend on the execution mode.
+
+## 2. Analyze One Unit
+
+**Export surface (every tier):** run the recipe runner on the unit's own folder. For the languages it has ast-grep recipes for (Python, JavaScript and TypeScript, Rust, Go, Vue) it lists the files, runs the recipes, follows the entry points and counts the public API, so the subagent neither greps nor counts those exports by hand:
+
+```bash
+uv run {extractPublicApiHelper} --mode full --source-root "{unit_root}" --scope-type {unit_scope_type} --tier {forge_tier}
+```
+
+**No recipe for the unit's language:** when `files_in_scope` is 0, or `files_without_recipes` lists the extension of the unit's language (Java, Kotlin, Swift, C#, PHP, Ruby and C or C++ have no recipe), the run counted none of its exports, whatever its exit code. Read the public declarations of the unit's source files by eye, as on exit 3: `exports_count`, `api_surface` and `export_pattern` from what you read (for example "public classes: 14, interfaces: 3"), `strategy_used: "source-read"`, `confidence: "T1-low"`.
+
+Otherwise read the JSON by the exit code:
+
+- **0 or 1:** `exports_count` ← `counts.exports_public_api`, `api_surface` ← the names in `entry_point_diff.public[]`, `export_pattern` ← `entry_points.status` with `aggregates.by_type` (for example "barrel: 12 functions, 5 classes", marked "capped" when `truncated` is true), `strategy_used: "ast-grep"`, `confidence: "T1"`. Then read by eye what the recipes could not, and name each one in `warnings`: every `entry_point_diff.extraction_gaps[]` name (public, but no recipe found its definition: read it at its `file` and `line`) and every `file_issues[]` file (one the parser could not fully read: add the exports it shows to `api_surface`). Exit 1 (`status: "incomplete"`) means an ast-grep run failed on some files: keep what it returned and put its `errors[]` in `warnings`.
+- **3** (no ast-grep the runner can run): the JSON still lists `entry_points.files`. Read the exports from those entry-point files by eye (from the unit's source files when it lists none), with `strategy_used: "source-read"` and `confidence: "T1-low"`.
+- **2:** an input error, named on stderr (a wrong path or flag): fix the call and run it again.
+
+**Tier-aware extras:** when `tools.ccc` is true (Forge+, or Deep with ccc installed), search `"{unit_name} exports public API"` (top 15) with the ccc tool the runtime offers (the `/ccc` skill, a ccc MCP server or the `ccc search` CLI) and record the top 3 files in `ccc_signals.top_files`, with `available: true`; with no ccc tool, record `available: false`.
+
+The subagent also records the export-surface call's `strategy_used`, `confidence` and `warnings`.
+
+## 3. Record Contract
+
+Each subagent writes only this JSON object, with no prose, no commentary and no markdown fence, to `{run_dir}/unit-records/{unit_name}.json` (creating the folder), and returns that path:
+
+```json
+{
+  "unit_name": "...",
+  "files_count": N,
+  "exports_count": N,
+  "export_pattern": "...",
+  "api_surface": ["..."],
+  "ccc_signals": {"top_files": [], "available": <bool>},
+  "strategy_used": "ast-grep|source-read",
+  "confidence": "T1|T1-low",
+  "warnings": []
+}
+```
+
+`files_count` is the unit's file count the loading file gave (the `files_count` of its disqualification record), not the runner's `files_in_scope`, which leaves out every file no recipe reads.
+
+## 4. Check the Records
+
+Once every subagent has returned its path (a main-thread analysis writes its record the same way), check all the records in one call:
+
+```bash
+uv run {checkUnitRecordsHelper} --dir "{run_dir}/unit-records"
+```
+
+The script drops a wrapping markdown fence (a subagent sometimes writes one despite the contract), checks each record against the contract above and fills a missing or wrong-typed key with its empty value, so a degraded record still goes on. Its `records` are the per-unit payloads. Record each `problems` entry as the warning `{unit_name}: {problem}` and each `warnings` entry as it is, so they reach the envelope's `warnings`: one `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning '<the warning>'` per entry, a single quote in it written as a backtick. A unit with no file in the folder, or a file the script lists in `unreadable` (it held no JSON object), is analyzed again in the main thread (graceful degradation, §1), and the check runs once more. Record only the entries of the units this pass analyzed: a record an earlier pass checked was recorded then.
+
+Return to the file that loaded this one with the checked `records` of these units.

package/src/skf-analyze-source/references/recommend.md

@@ -1,7 +1,8 @@
 ---
 nextStepFile: 'generate-briefs.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-schemaFile: '{briefSchemaPath}'
+schemaFile: 'assets/skill-brief-schema.md'
+discoverFile: 'references/discover-additional-source.md'
 advancedElicitationSkill: '/bmad-advanced-elicitation'
 partyModeSkill: '/bmad-party-mode'
 ---
@@ -16,21 +17,29 @@ To present each qualifying unit as a recommendation with evidence-based rational
 
 ## Rules
 
-- This is the primary user decision point — do not rush through it
-- Do not proceed without explicit confirmation for each unit
+- This is the primary user decision point: every unit gets a decision before the run moves on, which a headless run takes by the §7 GATE default
 - Present evidence for each recommendation, invite questions and pushback
 
 ## MANDATORY SEQUENCE
 
+Every HARD HALT in this step names its exit code, `halt_reason` and phase. When `{headless_mode}` is true it first prints its envelope on stderr through the shared emitter (`{emitEnvelopeHelper}` and `{run_dir}` come from SKILL.md On Activation): stage `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "mode": "interactive", "report_path": "{outputFile as an absolute path}"}`, plus `"path"` when the halt names one, then run
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+and display the line it prints verbatim. Write the payload as valid JSON: in the halt message and `path`, replace each backslash with / and each double quote with a backtick. If the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing.
+
 ### 1. Load Context
 
 Read {outputFile} completely to obtain:
-- Qualifying units from Identified Units
+- Qualifying units from Identified Units, each with its project path (the deferred ones are listed in the summary, not given a card)
 - Export map data per unit
 - 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)
+- `intent_hint` from frontmatter (the goal the user stated at init; empty when none)
+- `refs` from frontmatter: a unit's ref is its project path's entry there (none without one)
 
 Load {schemaFile} for reference on what skill-brief.yaml requires (so recommendations are actionable).
 
@@ -42,6 +51,7 @@ For each qualifying unit, prepare a recommendation card:
 
 ```
 **Unit: {name}**
+- Source: {its project path}{, at {its ref} when it has one}
 - Path: {path}
 - Language: {language}
 - Boundary: {type} | Scope: {scope_type}
@@ -51,12 +61,12 @@ For each qualifying unit, prepare a recommendation card:
 - Coupling: {tight/loose/indirect}
 - Confidence: {high/medium/low}
 - Stack Skill: {yes — grouped with {units} / no}
-- Status: {new / already-skilled → recommend update-skill}
+- Status: {new / briefed: a brief from an earlier analysis at {its path}, rewritten if you confirm the unit / already-skilled → recommend update-skill}
 
 **Rationale:** {2-3 sentences explaining WHY this should be a skill, citing specific detection signals and file paths}
 
 **Proposed Brief Fields:**
-- name: {suggested kebab-case name}
+- name: {the unit's name, as identify-units or map-and-detect derived it}
 - scope.type: {full-library / specific-modules / public-api / component-library / reference-app / docs-only}
 - scope.include: {suggested glob patterns}
 - description: {suggested 1-3 sentence description, containing a literal `Use when` clause}
@@ -64,6 +74,8 @@ For each qualifying unit, prepare a recommendation card:
 
 ### 3. Present Recommendations
 
+**Headless** (`{headless_mode}` true): no one answers the questions below. Take the §7 GATE default now (confirm every card as proposed and flag every stack skill candidate for create-stack-skill), record it as that GATE says, then continue at §6. No question of §3 to §5 is asked.
+
 "**Recommendations for {project_name}**
 
 I've analyzed {count} qualifying units. Here are my recommendations for skill creation:
@@ -78,97 +90,66 @@ Present each recommendation card, then after ALL cards:
 - **Recommended for new skills:** {count}
 - **Already-skilled (recommend update-skill):** {count}
 - **Stack skill candidates:** {count}
+- **Deferred (outside the stated goal, not analyzed):** {count, with their names}
 
 **For each unit above, please indicate:**
-- **Y** — Confirm: generate skill-brief.yaml
-- **N** — Reject: skip this unit
-- **M** — Modify: adjust name, scope, or description before confirming
+- **Y**: Confirm: generate skill-brief.yaml
+- **N**: Reject: skip this unit
+- **M**: Modify: adjust name, scope, or description before confirming
 
 **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)
+- `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."
 
 ### 4. Process User Decisions
 
-For each unit:
-
-**IF Y (Confirm):**
-- Add to confirmed_units list with proposed brief fields
-
-**IF N (Reject):**
-- Document rejection with user's reason (if provided)
-- Remove from confirmed list
-
-**IF M (Modify):**
-- Ask what to modify (name, scope, description, scope.include patterns)
-- Update the recommendation with user changes
-- Confirm the modified version
-
-**Continue until ALL units have a decision (Y/N/M).**
+Record a decision for every unit before moving on: Y adds it to `confirmed_units` with its proposed brief fields; N records the user's reason; M asks what to change (name, scope type, include patterns, description), applies it and confirms the result.
 
 ### 5. Confirm Stack Skill Candidates
 
-If stack skill candidates were flagged:
-
-"**Stack Skill Candidates:**
-
-The following unit groupings show strong co-integration patterns and may benefit from a consolidated stack skill via create-stack-skill:
-
-{For each candidate: list units, detection signal, evidence}
-
-Would you like to flag these for create-stack-skill? (Y/N per candidate)"
-
-Document decisions.
+If stack skill candidates were flagged, list them (units, detection signal, evidence): their units show strong co-integration patterns and may benefit from a consolidated stack skill via create-stack-skill. Ask "Flag these for create-stack-skill? (Y/N per candidate)" and record each decision.
 
-### 6. Present Final Confirmation
+### 6. Append to Report
 
-"**Confirmed Units for Brief Generation:** {count}
-
-{List each confirmed unit with final name, scope type, and description}
-
-**Rejected Units:** {count}
-{List with reasons}
-
-**Stack Skill Flags:** {count}
-{List groupings flagged for create-stack-skill}
-
-**This is your final confirmation before I generate skill-brief.yaml files.** All confirmed?"
-
-Wait for explicit final confirmation.
-
-### 7. Append to Report
-
-Append the complete "## Recommendations" section to {outputFile}:
-
-Replace `[Appended by recommend]` with:
+Replace `[Appended by recommend]` in {outputFile} with:
 - All recommendation cards (including rationale)
 - User decisions per unit (confirmed/rejected/modified)
 - Stack skill candidate decisions
-- Final confirmation status
 
 Update {outputFile} frontmatter:
 ```yaml
-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
+A later pass through this section (after [A], [P] or [D], or in a session that resumed this step) replaces what the earlier one wrote. The step is marked complete only when [C] leaves it, so a run cancelled at the §7 menu resumes at these recommendations.
+
+### 7. Present MENU OPTIONS
+
+Lead with the decisions, so the menu is chosen against the final list:
+
+"**Confirmed for brief generation:** {count}: {each confirmed unit with its final name, scope type and description}
+**Rejected:** {count}: {each with its reason}
+**Flagged for create-stack-skill:** {count}: {each grouping}"
 
 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:
 
-- IF A: Invoke {advancedElicitationSkill}, and when finished redisplay the menu
-- 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 error envelope on stderr with `halt_reason: "user-cancelled"` and counts/paths reflecting state at cancellation (shape in `references/headless-contract.md`)
-- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options)
+- IF A: Invoke {advancedElicitationSkill}. For each unit what it surfaced changes, take the decision again as §4 says, redo §6, then redisplay this menu
+- IF P: Invoke {partyModeSkill}, then handle what it surfaced as [A] does
+- IF D: load, read the entire file, then execute {discoverFile} with the project path the user gives. It returns the new path's units with their export records and composite proposals. Present each proposal (accepted unless the user rejects it; an accepted one replaces its constituents as one unit and joins `confirmed_composites` in the frontmatter), build the cards of the new units (§2), take their decisions (§3 to §5), redo §6, then redisplay this menu
+- IF C: update {outputFile} frontmatter (`stepsCompleted`: append `recommend`; `lastStep: 'recommend'`), then load, read the entire file, then execute {nextStepFile}
+- IF X: HARD HALT (exit code 6, `halt_reason: "user-cancelled"`, phase `recommend:7`, with `unit_counts` reflecting the decisions made so far in its payload): "Cancelled at the recommendations."
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)
+
+**GATE [default: C]**: present the menu and wait for the user's choice. The default also answers every question of §3 to §5: confirm every card as proposed and flag every stack skill candidate. If `{headless_mode}`, §3 takes that default before any question and records it the moment it does: stage `{run_dir}/decision.json` as `{"gate": "recommend.recommendations", "default_action": "C", "taken_action": "C", "reason": "headless: auto-accept all recommendations and flag every stack skill candidate", "evidence": {"confirmed": [<each confirmed unit name>], "stack_skill_candidates": <the flagged candidate count>}}`, then run
 
-**GATE [default: C]** — present the menu and wait for the user's choice. If `{headless_mode}`: accept all recommendations and auto-proceed, log: "headless: auto-accept all recommendations".
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-analyze-source --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+```
 
+If the command fails, go on: only that entry is lost. At this menu a headless run continues with [C].