bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/skf-analyze-source/references/identify-units.md

@@ -1,10 +1,14 @@
 ---
 nextStepFile: 'map-and-detect.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-heuristicsFile: '{unitDetectionHeuristicsPath}'
+heuristicsFile: 'references/unit-detection-heuristics.md'
+scanRootFile: 'references/scan-root.md'
 disqualifyCandidatesProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-disqualify-candidates.py'
   - '{project-root}/src/shared/scripts/skf-disqualify-candidates.py'
+skillInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
 detectLanguageProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-language.py'
   - '{project-root}/src/shared/scripts/skf-detect-language.py'
@@ -16,7 +20,7 @@ detectLanguageProbeOrder:
 
 ## STEP GOAL:
 
-To classify each detected boundary from the project scan into discrete skillable units by applying detection heuristics, assigning boundary types and scope types, and filtering out disqualified candidates.
+To classify each detected boundary from the project scan into discrete skillable units by applying detection heuristics, assigning boundary types and scope types, filtering out disqualified candidates and, in an interactive run with a stated goal, deferring the units outside it before export mapping.
 
 ## Rules
 
@@ -26,174 +30,156 @@ To classify each detected boundary from the project scan into discrete skillable
 
 ## 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:
-- Project Scan results (detected boundaries, manifests, entry points)
-- `forge_tier` from frontmatter
-- `existing_skills` from frontmatter
+- Project Scan results (detected boundaries, manifests, service configurations), grouped by project path
+- `project_paths`, `scan_roots` (each project path's scan root: the folder every helper of this step reads), `refs`, `forge_tier`, `intent_hint`, `existing_skills` and `existing_briefs` 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 `identify-units:1`, path `{path}`): "{path} could not be fetched: {the first stderr line}."
 
 Load {heuristicsFile} for classification rules.
 
 ### 2. Apply Detection Heuristics
 
-**Resolve `{disqualifyCandidatesHelper}`** from `{disqualifyCandidatesProbeOrder}`; first existing path wins. HALT if no candidate exists.
+**Resolve `{disqualifyCandidatesHelper}`** from `{disqualifyCandidatesProbeOrder}` and **`{skillInventoryHelper}`** from `{skillInventoryProbeOrder}`; first existing path wins for each. If one has no candidate, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `identify-units:2`): "`{the missing script}` is missing. Re-install SKF."
 
 For each detected boundary from the scan, apply the classification rules from {heuristicsFile} (loaded in §1):
 
-**Step A — Count detection signals:** tally the Strong / Moderate / Weak signals per its Detection Signals tables.
-
-**Step B — Classify boundary type** per its Boundary Classification section. (Composite is detected separately in §3b below — not during this initial per-boundary pass.)
-
-**Step C — Assign scope type** from that same section for the boundary's type.
+**Step A: Run the disqualification helper (script).** In one call per project path it lists each boundary's files itself, applies the deterministic subset of the rules from {heuristicsFile} (file count, LoC, generated files) and looks up the signal files and the boundary's own manifest. Its output is evidence that Step B judges, not a verdict.
 
-**Step D — Run deterministic disqualification filter (script):**
+Run it once per project path, the `{i}`-th entry of `project_paths[]`, over the boundaries found under it, with `{scan_root}` that path's scan root (never `{project-root}`, the forge workspace) and one entry per boundary, its path relative to the scan root (`.` for a boundary at the root), with forward slashes:
 
-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.
+```bash
+uv run {disqualifyCandidatesHelper} filter --boundaries - --source-root "{scan_root}" --tree-dir "{run_dir}/unit-trees/{i}" <<'SKF_BOUNDARIES'
+[{"name": "<boundary folder name>", "path": "<boundary path>"}, ...]
+SKF_BOUNDARIES
+```
 
-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-analyzed-source-root (project_paths[0])>",
-      "files": ["<rel-path>", ...]},
-     ...
-   ]
-   ```
-2. **Invoke the script** via stdin:
-   ```bash
-   uv run {disqualifyCandidatesHelper} filter --boundaries - --source-root {project_paths[0]}
-   ```
-   piping the boundaries JSON on stdin. `--source-root` is the analyzed-source root (`project_paths[0]`) — the directory the boundaries/manifest scan ran against — not `{project-root}` (the forge workspace), which differs whenever the analyzed target lives outside the forge workspace. The script emits:
+1. The script lists every boundary's files (what git lists under its path, so ignored build output and installed dependencies stay out), writes each list to the run folder and emits one record per boundary:
    ```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, ...}}
+     "kept":    [{"name": "...", "path": "...", "files_count": N, "loc_total": L, "non_source_count": K,
+                  "generated_files": [{"path": "...", "reason": "generated-code|auto-generated-tag", "match": "..."}],
+                  "generated_ratio": R, "passes_with_generated": true,
+                  "manifest": {"path": "...", "ecosystem": "npm", "name": "@acme/auth", "private": false},
+                  "signals": {...}, "tree_file": "..."}, ...],
+     "dropped": [{"name": "...", "reason": "<too-few-files|too-low-loc|generated-code|auto-generated-tag>", "context": {...}, ...}, ...],
+     "stats":   {"kept": N, "dropped": N, "mixed": 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)
+   A `dropped[]` record carries every `kept[]` field plus `reason` and `context`. Read `files_count` and `loc_total` (the boundary's own source files, counted as {heuristicsFile}'s Disqualification Rules say), `generated_files` and `generated_ratio` (the files Step B weighs), `passes_with_generated` (whether the size rules pass with those files counted too), `manifest` (the boundary's own manifest, null without one), `signals` (Step D) and `tree_file` (the boundary's file list, which §4 hands to the language helper).
+2. A boundary path that is no folder under the scan root makes the script exit 1 and name it on stderr: correct that entry and run the call again.
+3. **Stash the results** in workflow state, each record with its project path: `kept[]` is the candidate pool for the classification that follows, and `dropped[]` drives the Disqualification table.
 
-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.
+**Step B: Judge what the script cannot.**
 
-**Qualification check:** 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
-
-For each candidate that passes disqualification:
+- **Mixed cases** (`stats.mixed` counts them): a kept boundary whose `generated_files` is not empty. Read the flagged paths and their `match`. Build output or a vendored copy beside the unit's own code leaves the unit standing, and its counts already leave those files out. Drop a mixed boundary only when its own code is no more than glue around the generated files, with reason `generated-code` and one line on why.
+- **A drop the flagged files caused:** a boundary dropped as `generated-code`, `auto-generated-tag`, `too-few-files` or `too-low-loc` whose `generated_files` you judge to be its own code (a source folder named `build/` or `dist/`, a header its own tooling writes into code it maintains) goes back into `kept[]` when its `passes_with_generated` is true, with those files named in the notes. When it is false, the boundary stays dropped: even with those files it is too small.
+- **LLM-judged disqualifications** (not in the script; apply on top of `kept[]`), removing a boundary that fails one from the working `kept` set and appending it to `dropped[]` with the reason:
+  - **Pure configuration**: only config files (e.g., `.json`/`.yaml`) with no executable logic
+  - **Test-only**: test utilities with no production code
 
-| # | Unit Name | Path | Boundary Type | Scope Type | Signals | Confidence | Status |
-|---|-----------|------|---------------|------------|---------|------------|--------|
-| 1 | {name} | {path} | {type} | {scope} | {signal count: strong/moderate/weak} | {high/medium/low} | {new/already-skilled} |
+Show every drop and every restore in §6 with its reason and evidence (the record's `context`, `generated_ratio` and first `generated_files` path), so the user can override it; a headless run keeps the judgment made here.
 
-For disqualified candidates, note reason:
+**Step C: Name each unit (script), then check it is not already skilled.** The helper that names every brief names the units too, so a unit's name here is the name its brief gets.
 
-**Disqualified:**
-| Path | Reason |
-|------|--------|
-| {path} | {disqualification reason} |
+1. Name every unit in one call, by {heuristicsFile}'s Unit Names, one entry per kept boundary straight from its record: `target` is its `path` (its project path itself for a boundary at the root), and `manifest_name` and `private` are its `manifest.name` and `manifest.private` (null when `manifest` is null):
+   ```bash
+   uv run {skillInventoryHelper} derive-name --from - <<'SKF_UNIT_NAMES'
+   [{"target": "<boundary path>", "manifest_name": <manifest.name>, "private": <manifest.private>}, ...]
+   SKF_UNIT_NAMES
+   ```
+   Each `names[].name` is that unit's name from here on. Boundaries whose names would clash are already told apart by their parent folders (`clash` keeps the name they shared); give the entries `unnamed` and `duplicates` list a name of your own, from their folder.
+2. **Already skilled:** a unit whose name is in `existing_skills` (a compiled skill) fails the last LLM-judged rule: remove it from the working `kept` set and append it to `dropped[]` with reason `already-skilled` (recommend `update-skill` instead). A unit whose name is in `existing_briefs` only has a brief from an earlier analysis: it stays a candidate with status `briefed` and its brief's path, and generate-briefs rewrites that brief only if the unit is confirmed.
 
-### 3b. Detect Composite Unit Merges
+**Step D: Tally detection signals** per the Detection Signals tables in {heuristicsFile}: cite the file each record's `signals` entry names (and `large_directory`), and judge the signals the helper does not report, as that file says.
 
-After building the classification table, apply the Composite Boundary detection heuristic from {heuristicsFile} against the qualifying units:
+**Step E: Classify boundary type** per its Boundary Classification section, and **assign the scope type** from that same section for the boundary's type. This pass classifies each boundary on its own: composite merges are proposed in map-and-detect, once the import graph exists.
 
-1. **Scan for merge candidates:** Among the qualifying units (from `kept[]`), find groups of ≥2 Package or Module boundaries that meet either Composite trigger — **Mutual hard dependency** or **Shared integration surface** — as defined in {heuristicsFile}'s Composite Boundary heuristic.
+### 3. Build Unit Classification Table
 
-2. **If candidate groups are found**, propose each merge:
-   - Derive a composite name from the common namespace prefix or repo name
-   - List the constituents (boundary names and paths being merged)
-   - State the triggering heuristic and evidence
+For each candidate that passes disqualification:
 
-3. **If no candidate groups are found**, skip to §4.
+| # | Unit Name | Project Path | Path | Boundary Type | Scope Type | Files | Own Manifest | Signals | Confidence | Status |
+|---|-----------|--------------|------|---------------|------------|-------|--------------|---------|------------|--------|
+| 1 | {name} | {its project path} | {path} | {type} | {scope} | {files_count} | {manifest path, name and ecosystem, or --} | {signal count: strong/moderate/weak} | {high/medium/low} | {new/briefed/deferred} |
 
-**Merge does not fire for:** Units already flagged as Stack Skill Candidates in step 4 (map-and-detect §5) — those are multi-unit groupings that deliver value *separately* but are *also* useful together. Composite merges are for units that are *only* useful together (the key distinction). If a group of units is independently useful but commonly combined, it remains as separate units and is flagged as a stack skill candidate later.
+For disqualified candidates, note reason and evidence:
 
-**This step is a recommendation — not automatic.** Merges are presented to the user in §5 for confirmation (see "Composite Merge Proposals" below). If the user rejects a merge, the constituents remain as separate units in the classification table.
+**Disqualified:**
+| Path | Reason | Evidence |
+|------|--------|----------|
+| {path} | {disqualification reason} | {the record's `context`, or `generated_ratio` and the first `generated_files` path} |
 
 ### 4. Detect Primary Language Per Unit
 
-For each qualifying unit (including any approved composites from §3b), detect the primary language deterministically via the shared helper — the single source of truth for the manifest→language rule table (no in-prose restatement, which drifts from the script's tsconfig JS-vs-TS and `build.gradle` Java-vs-Kotlin disambiguation).
+For each qualifying unit, detect the primary language deterministically via the shared helper, the single source of truth for the manifest→language rule table.
 
-**Resolve `{detectLanguageHelper}`** from `{detectLanguageProbeOrder}`; first existing path wins.
+**Resolve `{detectLanguageHelper}`** from `{detectLanguageProbeOrder}`; first existing path wins. If neither exists, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `identify-units:4`): "`skf-detect-language.py` is missing. Re-install SKF."
 
-For each unit, pipe its file list — the `files` array built for that boundary in the §2 boundaries JSON — as the tree:
+For each unit, hand the helper the file list §2 wrote for it, its record's `tree_file`:
 
 ```bash
-echo '{"tree": [<unit files — forward-slash, repo-relative>]}' | uv run {detectLanguageHelper}
+uv run {detectLanguageHelper} --tree-file "{the unit's tree_file}"
 ```
 
-Read `.language` and `.confidence` for the unit. When confidence is low (the extension-frequency fallback fired — no manifest matched), surface it in §5 so the user can override the guess.
-
-### 5. Present Classifications
-
-"**Unit Identification Complete**
+Pass no `--workspace-signal` here: a workspace root's language would answer for every unit of the workspace (a TypeScript package in a Cargo workspace would read as `rust`). The unit's folder is the tree's root for the helper, so the unit's own manifest decides, and a manifest in its docs, examples, tests or tools folder never does while another one exists. Read `.language` and `.confidence` for the unit. When `detected_languages` has more than one entry, `.language` is the helper's first guess: choose the language the unit documents from its own manifest (the record's `manifest`), or, without one, `.source_language` (the language most of its files are written in), and name the choice and the other languages in §6. When confidence is low (the extension-frequency fallback fired: no manifest matched), surface it in §6 so the user can override the guess.
 
-**Qualifying Units:** {count}
+### 5. Defer What the Goal Leaves Out
 
-{Classification table}
+Interactive runs only, and only when `intent_hint` is not empty: mark each qualifying unit the stated goal clearly leaves out `deferred` in the Status column, with one line on why (for example "deferred: payments, outside the stated goal (authentication)"). Step 4 maps only the units that are not deferred, and the deferred ones stay in the classification table, so nothing is dropped without notice. A unit you are unsure about stays in. A headless run defers nothing: there `intent_hint` only ranks the step 5 recommendations.
 
-**Disqualified Candidates:** {count}
-{Disqualification table}
+### 6. Present the Classifications and Confirm
 
-**Already-Skilled Units:** {count from existing_skills match}
-{List with recommendation to run update-skill if source has changed}
+Show the user the classification table, then:
 
-{IF composite merge proposals exist from §3b:}
+- **Mixed cases** (`stats.mixed`): for each qualifying unit with generated files, its name, `generated_ratio`, the flagged folders or headers and why it stays; and each boundary §2 Step B restored, with the files that restored it
+- **Disqualified candidates**, with the table above
+- **Already-skilled units** (from `existing_skills`), each with a recommendation to run update-skill if its source changed
+- **Deferred units**, when §5 deferred any, with how to restore them
+- **Notes:** structure patterns observed, and ambiguous boundaries that need the user's call
 
-**Composite Merge Proposals:** {count}
+Then display:
 
-| # | Composite Name | Constituents | Heuristic | Evidence |
-|---|----------------|--------------|-----------|----------|
-| 1 | {name} | {list of constituent unit names} | {mutual hard dependency / shared integration surface} | {brief evidence} |
+"Add, remove, reclassify or restore any unit? Tell me, or **Select:** [C] Continue to Export Mapping and Integration Detection | [X] Cancel and exit"
 
-If approved, each composite replaces its constituents in the classification table as a single Composite Boundary unit. The constituents are recorded in the composite's metadata for downstream workflows (create-skill reads constituents to scope extraction across all member paths).
-
-{END IF}
+#### Menu Handling Logic:
 
-**Notes:**
-- {Any observations about project structure patterns}
-- {Any ambiguous boundaries that need user clarification}
+- IF C: go to §7
+- IF X: HARD HALT (exit code 6, `halt_reason: "user-cancelled"`, phase `identify-units:6`): "Cancelled at unit identification."
+- IF Any other: adjust the classifications as directed (restoring a deferred unit sets its status back to new or briefed), show what changed, then [Redisplay Menu Options](#6-present-the-classifications-and-confirm)
 
-Do these classifications look correct? Should any units be added, removed, or reclassified?
-{IF composites proposed:} Are the composite merge proposals correct? (Accept/reject each individually.)"
+**GATE [default: C]**: present the menu and wait for the user's choice. If `{headless_mode}`: accept every classification and continue with [C], and record that decision the moment it is taken: stage `{run_dir}/decision.json` as `{"gate": "identify-units.classifications", "default_action": "C", "taken_action": "C", "reason": "headless: auto-accept unit classifications", "evidence": {"qualifying": <the qualifying unit count>, "dropped": <the dropped boundary count>}}`, then run
 
-Wait for user feedback. Adjust classifications based on user input. For approved composites: remove the constituent rows from the qualifying units table and add a single composite row with `Boundary Type: Composite`, scope type inherited from the dominant constituent, and confidence reflecting the merge heuristic strength.
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-analyze-source --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+```
 
-### 6. Append to Report
+If the command fails, go on: only that entry is lost.
 
-Append the complete "## Identified Units" section to {outputFile}:
+### 7. Append to Report and Continue
 
-Replace the placeholder `[Appended by identify-units]` with:
-- Classification table (qualifying units, including approved composites)
-- Composite merge details (if any): composite name, constituents list, heuristic, evidence
+Replace the placeholder `[Appended by identify-units]` in {outputFile} with:
+- Classification table (qualifying units, under their §2 Step C names, with their project paths, file counts, own manifests and statuses, deferred units included)
+- Mixed cases and restored boundaries, with their evidence
 - Disqualification table
 - Already-skilled units list
-- Language detection results
+- Language detection results, and each unit's `tree_file`
 - Any user adjustments noted
 
 Update {outputFile} frontmatter:
 ```yaml
 stepsCompleted: [append 'identify-units' to existing array]
 lastStep: 'identify-units'
-confirmed_composites: [{list of approved composite merge objects: {name, constituents[], heuristic}}]
 ```
 
-(`confirmed_composites` is an empty array when no composites were proposed or all were rejected.)
-
-### 7. Present MENU OPTIONS
-
-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 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: help user, then [Redisplay Menu Options](#7-present-menu-options)
-
-**GATE [default: C]** — present the menu and wait for the user's choice. If `{headless_mode}`: accept all classifications and auto-proceed, log: "headless: auto-accept unit classifications".
-
+Then load, read the entire file, then execute {nextStepFile}.

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

@@ -3,6 +3,9 @@ nextStepFile: 'scan-project.md'
 continueFile: 'continue.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 templateFile: '{analysisReportTemplatePath}'
+skillInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -11,30 +14,45 @@ templateFile: '{analysisReportTemplatePath}'
 
 ## STEP GOAL:
 
-To initialize the analyze-source workflow by loading configuration, detecting continuation state, accepting the target project path, checking for existing skills, and creating the analysis report document.
+To initialize the analyze-source workflow by loading configuration, detecting continuation state, taking the target project path, the analysis goal and the scope from the invocation or one opening question, checking for existing skills, and creating the analysis report document.
 
 ## Rules
 
-- Focus only on initialization — do not begin scanning or analysis
-- Collect project path and scope hints from user
+- Focus only on initialization: do not begin scanning or analysis
+- Use what the invocation already says before asking anything, and ask at most one opening question
 - Verify prerequisites before proceeding
 
 ## MANDATORY SEQUENCE
 
-When `{headless_mode}` is true, every HARD HALT in this step emits the error envelope on **stderr** before exiting — shape and enum in `references/headless-contract.md` — using the exit code and `halt_reason` named at that HALT.
+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": "<auto when the invocation carries [auto], else interactive>"}`, 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. Check for Existing Report (Continuation Detection)
 
 Look for {outputFile}.
 
-**IF the file exists AND has `stepsCompleted` with entries:**
-- The report filename is keyed to `{project_name}` (the forge workspace), not the analyzed target — so a report from a *different* target can collide here. Before resuming, establish the requested target and compare it to the existing report:
-  - Determine the requested target now: if `--project-path <path>` was passed at invocation, set `project_paths[]` from it (comma-split if multiple); otherwise collect the path(s) using the section-3 "Collect Project Path" prompt and store as `project_paths[]`. (Section 3 does not re-prompt when `project_paths[]` is already populated here.)
-  - Read the existing report's frontmatter `project_paths`.
-  - **IF the existing report's `project_paths` matches the requested target:**
-    - **IF this invocation carries the `[auto]` flag (e.g. `AN[auto]`):** do not route to {continueFile} — auto mode is a single idempotent pass, not a resumable interactive session. Skip continuation and proceed to section 2; the `[auto]` check in §2b re-enters step-auto-scope.md, which re-runs cleanly and overwrites the prior auto report. (This keeps a re-invoked or interrupted auto run on the auto path instead of dropping it into the interactive chain.)
-    - **ELSE:** "**Found an existing analysis report. Resuming previous session...**" — Load, read entirely, then execute {continueFile}. **STOP HERE** — do not continue this sequence. ({continueFile} is mode-aware: a report written by a prior auto run resumes through the auto path, not the interactive chain.)
-  - **ELSE (different target — stale collision):** the existing report belongs to another analysis. Archive it by renaming to `{forge_data_folder}/analyze-source-report-{project_name}-<UTC-timestamp>.md`, announce "**Existing report belongs to a different target — archived as <name>; starting a fresh analysis.**", then continue to section 2 (skip re-collecting the path in section 3 — it is already set).
+**IF the file exists AND has `stepsCompleted` with entries:** the report filename is keyed to `{project_name}` (the forge workspace), not the analyzed target, so the report may belong to another analysis or to one that already ended. Apply the first rule that holds:
+
+1. **Finished:** `stepsCompleted` holds `generate-briefs` or `auto-scope`: that analysis already ended (with its briefs, or with none). Archive it (below), announce "**The previous analysis of this workspace is finished: archived as <name>; starting a fresh analysis.**", and continue to section 2. A finished report is never resumed, in headless mode either.
+2. **Auto invocation or auto report:** this invocation carries the `[auto]` flag (e.g. `AN[auto]`), or the report's `mode` is `'auto'` (an `[auto]` run that was interrupted or ended at step 1a's coexistence gate with [M]erge or [S]kip). Auto mode is one pass that never resumes, so archive the unfinished report the same way, announce "**An `[auto]` analysis never resumes: archived the unfinished report as <name>; starting a fresh analysis.**", and continue to section 2.
+3. **Unfinished:** establish the requested target and compare it to the report's. Take `project_paths[]` from the invocation as section 3 says (`--project-path`, comma-split, or a path the message names); when it gives none, ask section 3's opening question now (a headless run halts there instead), once: section 3 then asks nothing more. Read the report's frontmatter `project_paths`.
+   - **Same target:** compare the ref and hint flags this invocation passes with the report's frontmatter: `--target-ref` or `--target-refs`, resolved to each project path's ref as section 4 does, against `refs`, and `--scope-hint` and `--intent-hint` against `scope_hint` and `intent_hint`. A flag the invocation does not pass changes nothing.
+     - **The inputs match:** "**Found an unfinished analysis report. Resuming the previous session...**" Load, read entirely, then execute {continueFile}. **STOP HERE**: do not continue this sequence. Headless runs resume it too.
+     - **An input differs:** the later steps would read the report's old values, so archive it and announce "**The inputs changed: archived as <name>; starting a fresh analysis.**" In headless mode, also run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning 'inputs changed: the unfinished report was archived as <name>'`, a single quote in it written as a backtick (if it fails, go on). Then continue to section 2: section 3 keeps the path already set, and section 4 resolves the refs again.
+   - **Different target (stale collision):** archive it, announce "**Existing report belongs to a different target: archived as <name>; starting a fresh analysis.**", then continue to section 2 (section 3 keeps the path already set).
+
+**To archive a report** (rules 1 and 2, changed inputs and a different target; a report that resumes stays where it is), rename it, never overwrite it:
+
+```bash
+archive="{forge_data_folder}/analyze-source-report-{project_name}-$(date -u +%Y%m%d-%H%M%S).md" && mv -n "{outputFile}" "$archive" && printf '%s\n' "$archive"
+```
+
+and use the path it prints as `<name>`. If the rename fails, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `init:1`, path `{outputFile}`): "The earlier analysis report could not be archived: {the first stderr line}."
 
 **IF the file does not exist OR stepsCompleted is empty:**
 - Continue to section 2
@@ -43,7 +61,7 @@ Look for {outputFile}.
 
 **Check forge-tier.yaml:**
 - Look for `{sidecar_path}/forge-tier.yaml`
-- **IF missing:** HARD HALT — "**Cannot proceed.** forge-tier.yaml not found at `{sidecar_path}/forge-tier.yaml`. Please run the setup workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
+- **IF missing:** HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `init:2`, path `{sidecar_path}/forge-tier.yaml`): "**Cannot proceed.** forge-tier.yaml not found at `{sidecar_path}/forge-tier.yaml`. Please run the setup workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
 - **IF found:** Read and note the forge tier value
 
 **Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
@@ -56,9 +74,10 @@ Look for {outputFile}.
 
 **IF `{auto_mode}` is true:**
 
-1. **Resolve project path:** If `project_paths[]` is already populated (from §1 continuation detection or `--project-path` arg), use it. Otherwise, if `--project-path <path>` was passed at invocation, set `project_paths[]` from it (comma-split if multiple). If neither is available, HARD HALT with exit code 2 (`input-missing`): "**Auto mode requires `--project-path` — no project path available.**"
-2. **Validate the path(s):** For each provided path/URL, check that it exists (local) or is accessible (remote). If any invalid: HARD HALT with exit code 3 (`resolution-failure`): "**Path `{path}` doesn't appear to be valid.**"
-3. **Create the analysis report** from {templateFile}. Populate frontmatter:
+1. **Resolve project path:** If `project_paths[]` is already populated (from §1 continuation detection or `--project-path` arg), use it. Otherwise, if `--project-path <path>` was passed at invocation, set `project_paths[]` from it (comma-split if multiple). If neither is available, HARD HALT (exit code 2, `halt_reason: "input-missing"`, phase `init:2b`): "**Auto mode requires `--project-path`: no project path available.**"
+2. **Validate the path(s):** For each provided path/URL, check that it exists (local) or is accessible (remote). If any invalid: HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `init:2b`, path `{path}`): "**Path `{path}` doesn't appear to be valid.**"
+3. **Take the hints:** `intent_hint` ← the `--intent-hint` value and `scope_hint` ← the `--scope-hint` value (empty when the flag is absent). Step 1a reads both, and so does the interactive chain it may fall back to.
+4. **Create the analysis report** from {templateFile}. First build `existing_skills` and `existing_briefs` as section 5 does, without its messages: the step-by-step analysis an unclassified repository falls back to reads them. Populate frontmatter:
    ```yaml
    stepsCompleted: ['init']
    lastStep: 'init'
@@ -68,75 +87,52 @@ Look for {outputFile}.
    project_name: '{project_name}'
    project_paths: ['{provided_project_path}']
    forge_tier: '{detected_tier}'
-   existing_skills: []
+   existing_skills: [{list of existing skill names}]
+   existing_briefs: [{name and path of each existing brief, as {name: '...', path: '...'}}]
+   intent_hint: '{intent_hint}'
+   scope_hint: '{scope_hint}'
    confirmed_units: []
    stack_skill_candidates: []
    nextWorkflow: ''
    mode: 'auto'
    ```
-4. "**Auto mode activated — bypassing interactive analysis.**"
-5. **Route to auto-scope:** Load, read fully, then execute `references/step-auto-scope.md`. **STOP HERE** — do not continue to §3 or any subsequent section.
-
-**IF `{auto_mode}` is not true:**
-Continue to §3 as normal — the entire interactive flow below is unchanged.
-
-### 3. Collect Project Path
+5. "**Auto mode activated: bypassing interactive analysis.**"
+6. **Route to auto-scope:** Load, read fully, then execute `references/step-auto-scope.md`. **STOP HERE**: do not continue to §3 or any subsequent section.
 
-**Headless flag consumption:** If `project_paths[]` is already populated (e.g. collected by the section-1 stale-collision guard) OR `--project-path <path>` was passed at invocation, set/keep `project_paths[]` (comma-split the flag value if multiple paths were supplied), skip the prompt below, and proceed to validation. If `{headless_mode}` is true and no path is available from either source, HARD HALT with exit code 2 (`input-missing`): "**No project path — headless mode requires `--project-path`.**" (interactive prompting is unavailable headless). Otherwise prompt as today.
+**IF `{auto_mode}` is not true:** continue to §3.
 
-**Per-path ref overrides (`--target-refs`):** If `--target-refs <mapping>` was passed at invocation, parse it as a comma-separated list of `path:ref` pairs (e.g., `owner/repo:v1.0.0,owner/repo2:main`). Build a `constituent_refs` map from the pairs. Each key must match an entry in `project_paths[]` (validated after path collection). When `--target-refs` is absent but multiple `project_paths` exist, set `constituent_refs` to `{}` (empty — all paths use default ref resolution). When only a single path exists, omit `constituent_refs` entirely (use `target_ref` if set on the brief). `constituent_refs` and `target_ref` are mutually exclusive — if both are supplied, HALT with: "`--target-refs` and `--target-ref` are mutually exclusive. Use `--target-refs` for multi-path analysis, or `--target-ref` for single-path."
+### 3. Opening Question
 
-"**Please provide the project root path(s) to analyze** — I'll identify discrete skillable units and produce a skill-brief.yaml for each.
+Read the invocation first: its flags (`--project-path`, comma-split for several paths; `--intent-hint`; `--scope-hint`) and, in an interactive run, its message, which may name a path or URL, the goal of the analysis, or folders and packages to focus on or skip ("analyze /work/mono, I only care about auth, skip vendor/"). A flag wins over the message. `project_paths[]` set by section 1 stays as it is.
 
-This can be:
-- A single root directory of a repo or multi-service project
-- Multiple paths or URLs (comma-separated) for multi-repo analysis (e.g., integration/stack skills)
+- `intent_hint`: the goal, in the user's words (a domain such as authentication, the consumers the skills serve, a constraint such as stable public APIs only).
+- `scope_hint`: the folders or packages to focus on, and those to skip.
 
-Examples:
-- `/path/to/project`
-- `owner/repo, owner/repo2`
-- `/path/to/project, https://github.com/owner/repo2`"
+**Headless** (`{headless_mode}` true): ask nothing. With no path from a flag or section 1, HARD HALT (exit code 2, `halt_reason: "input-missing"`, phase `init:3`): "**No project path: headless mode requires `--project-path`.**" A hint no flag gave is empty: a headless run never reads one from the message.
 
-Wait for user input.
+**Interactive:** ask at most one question, and only for what is still missing:
 
-**Validate the path(s):**
-- For each provided path/URL: check that it exists (local) or is accessible (remote)
-- **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)
-- **IF `constituent_refs` was built from `--target-refs`:** Validate that every key in the map matches an entry in `project_paths[]`. If any key has no matching path, HALT: "constituent_refs key `{key}` does not match any entry in project_paths."
+- **No path yet:** "**Which project should I analyze?** Give the root path(s) or URL(s), comma-separated for several repositories (`/path/to/project`, `owner/repo, owner/repo2`). Optionally add what you want out of it and anything to focus on or skip (for example: auth packages only, skip `vendor/`)."
+- **A path, but no goal:** "**What should this analysis focus on, or keep out?** A domain, packages, folders to skip. Press Enter to analyze everything."
+- **A path and a goal:** ask nothing.
 
-**Collect intent hint** (drives recommendation ranking in Step 5):
+Wait for the answer, then fill what is still missing from it: `project_paths[]`, `intent_hint` and `scope_hint`, each empty when the answer gives none. A value the invocation gave stays.
 
-**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.
+### 4. Validate the Inputs
 
-"**Optional: What are you hoping to get out of this analysis?**
+**Paths:** for each entry of `project_paths[]`, check that it exists (local) or is accessible (remote). An invalid one: "Path `{path}` doesn't appear to be valid. Please correct it." and wait for the corrected path. In headless mode no one can correct it: HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `init:4`, path `{path}`) with that message.
 
-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')
+**Ref pins:** `--target-ref <ref>` names one git tag or branch for every project path: `target_ref` ← it. `--target-refs <mapping>` names one per path, as comma-separated `path:ref` pairs (`owner/repo:v1.0.0,owner/repo2:main`), and every key must be an entry of `project_paths[]`, else HARD HALT (exit code 2, `halt_reason: "input-missing"`, phase `init:4`): "`--target-refs` key `{key}` does not match any entry in project_paths." The two are mutually exclusive: when both are passed, HARD HALT (exit code 2, `halt_reason: "input-missing"`, phase `init:4`): "`--target-refs` and `--target-ref` are mutually exclusive. Use `--target-refs` for one ref per path, or `--target-ref` for one ref for every path." Resolve each project path's **ref** once, here: its `--target-refs` entry, else `target_ref`, else none (the default ref: HEAD for a local path, the default branch for a remote one). `refs` ← each project path that has a ref, mapped to it (`{}` when none has one). Every later step reads a path's ref from `refs` alone: scan-project reads each path at its ref, and generate-briefs writes each unit's ref into its brief as `target_ref`.
 
-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:
-- Specific packages to focus on (e.g., `packages/auth`, `services/api`)
-- Directories to exclude (e.g., `vendor/`, `node_modules/`, `dist/`)
-
-Enter scope hints, or press Enter to analyze the entire project."
+### 5. Check for Existing Skills
 
-Wait for user input. Document any hints provided.
+A unit is already skilled when a compiled skill carries its name. A brief alone does not make it one: an earlier analysis, archived in section 1, may have written it. **Resolve `{skillInventoryHelper}`** from `{skillInventoryProbeOrder}`; first existing path wins. If neither exists, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `init:5`): "`skf-skill-inventory.py` is missing. Re-install SKF." List the compiled skills:
 
-### 5. Check for Existing Skills
+```bash
+uv run {skillInventoryHelper} "{skills_output_folder}"
+```
 
-Scan `{forge_data_folder}/*/skill-brief.yaml` (one level deep — each skill has its own subdirectory) for existing skill briefs.
+`existing_skills` ← the `name` of every `skills[]` entry whose `skf_skill` is true (none when it exits non-zero: no skills folder yet). A skill SKF did not generate is left out: update-skill, which an already-skilled unit is sent to, changes only the skills SKF generated. Then scan `{forge_data_folder}/*/skill-brief.yaml` (one level deep: each skill has its own subdirectory): `existing_briefs` ← `{name, path}` of each brief whose folder name is not in `existing_skills`.
 
 **IF existing skills found:**
 "**Existing skills detected:**
@@ -144,12 +140,15 @@ Scan `{forge_data_folder}/*/skill-brief.yaml` (one level deep — each skill has
 
 These units will be flagged as 'already skilled' during analysis. If source changes are detected, I'll recommend running update-skill instead of generating new briefs."
 
-**IF no existing skills found:**
+**IF existing briefs found:**
+"**Briefs with no compiled skill yet:** {list each name and path}. Their units are analyzed again; a brief is rewritten only when you confirm its unit."
+
+**IF neither found:**
 "**No existing skills found.** All identified units will be treated as new."
 
 ### 6. Create Analysis Report
 
-Create {outputFile} from {templateFile}. If the write fails, HARD HALT with exit code 4 (`write-failed`) per `references/headless-contract.md`.
+Create {outputFile} from {templateFile}. If the write fails, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `init:6`, path `{outputFile}`): "The analysis report could not be written: {the error}."
 
 **Populate frontmatter:**
 ```yaml
@@ -160,9 +159,11 @@ date: '{current_date}'
 user_name: '{user_name}'
 project_name: '{project_name}'
 project_paths: ['{provided_project_path}']
-constituent_refs: {map from --target-refs, or omit if single path}
+target_ref: '{target_ref, or empty}'
+refs: {each project path with a ref: its ref}
 forge_tier: '{detected_tier}'
 existing_skills: [{list of existing skill names}]
+existing_briefs: [{name and path of each existing brief, as {name: '...', path: '...'}}]
 intent_hint: '{intent_hint or empty string}'
 scope_hint: '{scope_hint or empty string}'
 confirmed_units: []
@@ -170,14 +171,15 @@ stack_skill_candidates: []
 nextWorkflow: ''
 ```
 
-**`constituent_refs` presence rules:** Include the field only when `project_paths` has more than one entry. When present, keys are path strings matching `project_paths[]` entries, values are explicit git refs (tag/branch/commit). Paths with no explicit ref have no entry in the map (default ref resolution applies). Downstream steps (scan-project, brief generation) read this map to resolve per-constituent refs when cloning or reading off-HEAD constituents.
+`target_ref` stays for a path that discover-additional-source adds later, which takes it as its ref.
 
 "**Initialization complete.**
 
-**Project:** {project_path}
+**Project:** {project_paths, each with its ref when it has one}
 **Forge Tier:** {forge_tier}
 **Existing Skills:** {count}
-**Scope Hints:** {hints or 'None — full project analysis'}
+**Goal:** {intent_hint, or 'None: every unit is analyzed'}
+**Scope Hints:** {scope_hint, or 'None: full project analysis'}
 
 **Proceeding to project scan...**"