bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/skf-create-stack-skill/references/parallel-extract.md

@@ -3,6 +3,16 @@ nextStepFile: 'detect-integrations.md'
 enumerateStackSkillsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-enumerate-stack-skills.py'
   - '{project-root}/src/shared/scripts/skf-enumerate-stack-skills.py'
+renderStackMetadataProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-render-stack-metadata.py'
+  - '{project-root}/src/shared/scripts/skf-render-stack-metadata.py'
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
+bundleFile: '{run_dir}/extraction-bundle.json'
+exportRecordsFile: '{run_dir}/export-records.json'
+importCountsFile: '{run_dir}/import-counts.json'
+stackInventoryFile: '{run_dir}/stack-inventory.json'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -17,31 +27,62 @@ For each confirmed dependency, extract key exports, usage patterns, and API surf
 
 - Extract per-library using subprocess Pattern 4 (parallel) when available; if unavailable, extract sequentially
 - Each subprocess returns structured extraction, not raw file contents
+- Label each export by the tool that read it, never by the forge tier
 - Do not analyze cross-library integrations (Step 05)
 
 ## MANDATORY SEQUENCE
 
+**Halt envelope.** Every HALT in this step names its exit code, `halt_reason` and phase. Stage `{run_dir}/halt.json` as `{"phase": "<phase>", "halt_reason": "<halt_reason>", "reason": "<the halt message, one line>", "skill_name": "{stack_name}", "mode": "<code|compose>", "stack_libraries": ["<confirmed library>", ...]}`, then run:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-stack-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+Display the line it prints, then stop with the halt's exit code (`references/invocation-contract.md` lists every halt). If `{emitEnvelopeHelper}` is not bound, resolve it from `{emitEnvelopeProbeOrder}`; if no path exists, or the emitter exits non-zero or prints no line, display the halt message alone.
+
+**Warnings.** Each `workflow_warnings[]` entry this step appends is recorded at once: write its `[{step}/{severity}] {code}: {message}` line to `{run_dir}/warning.txt` with a file write, then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/warning.txt")"`.
+
+**Extraction bundle.** What this step extracts goes to `{bundleFile}`, so no later step works from memory: step 5 reads each library's tier there and adds the pairs it keeps, step 6 compiles from it, and step 7 writes the reference files, `metadata.json` and the provenance map from it. It is one JSON object, written with the run's other files in `{run_dir}`:
+
+```json
+{
+  "mode": "code|compose",
+  "scope": ["<confirmed library>"],
+  "per_library_extractions": [
+    {"library": "<name>", "status": "success|partial", "version": "<version>",
+     "confidence": "T1|T1-low|T2|T3", "files_analyzed": 0,
+     "usage_patterns": ["<pattern with file:line>"], "warnings": [], "temporal": {}}
+  ],
+  "failed": [{"library": "<name>", "reason": "<why>"}],
+  "integrations": [],
+  "hubs": [],
+  "cross_cutting": []
+}
+```
+
+`scope` is step 3's `confirmed_dependencies`; step 5 fills `integrations`, `hubs` and `cross_cutting`. A compose-mode entry also holds `skill_dir`, `skill_package_path`, `exports`, `exports_source` and `source_authority` (§0). A code-mode entry also holds `file_count`, the library's step 3 import count, and its export records sit beside the bundle in `{exportRecordsFile}` (§3a).
+
 ### 0. Check Compose Mode
 
 **If `compose_mode` is true:**
 
 "**Extraction data already available from individual skills. Skipping extraction phase.**"
 
-For each confirmed skill, load SKILL.md from the version-aware path resolved in step 2.
+For each confirmed skill, load SKILL.md from its `skill_package_path` (step 2, refreshed below): its usage patterns come from there.
 
-**Re-resolve at step 4 entry (S17):** Between step 2 manifest detection and step 4 extraction, a concurrent write could have advanced a skill's `active_version`. On entering this step, re-resolve `skill_package_path` for each confirmed skill via the export-manifest (or symlink fallback) and capture the freshly-read `version` and `metadata_hash` into workflow state. If the `metadata_hash` diverges from the value stored in step 2, log a warning `"constituent '{skill_name}' changed between step 2 and step 4 — using fresh values"` and replace the workflow-state entry (so step 7 provenance records the hash active at extraction time, with the drift logged for audit).
+**Re-resolve at step 4 entry (S17):** a concurrent write could have advanced a skill's version between step 2 and step 4. Re-resolve each confirmed skill from this step's helper result below: the `skills[]` entry whose `name` is its `skill_dir` gives the fresh `skill_package_path` (`{skills_output_folder}/{path}`) and `metadata_hash`. **The provenance anchor (S13) is the hash of the package this step reads**: step 2's value, unless the package changed since. When the `metadata_hash` diverges from the value step 2 stored, append a `workflow_warnings[]` entry (`step: "step-04"`, `severity: "warn"`, `code: "constituent-changed"`, `message`: "constituent '{skill_name}' changed between step 2 and step 4: using fresh values") and replace the workflow-state entry. If a confirmed skill has no `skills[]` entry now, HALT (exit 3, `halt_reason: "resolution-failure"`, phase `parallel-extract:constituent-gone`) with "constituent `{skill_dir}` is no longer an SKF skill package: re-run [SS]."
 
-Use `skill_package_path` (stored in step 2 and optionally refreshed above) directly — this already points to the resolved `{skill_package}` or `{active_skill}` directory containing the skill's artifacts. If `skill_package_path` is not available, resolve via the `{active_skill}` template: `{skills_output_folder}/{skill_dir}/active/{skill_dir}/SKILL.md` (see `knowledge/version-paths.md`).
+Use `skill_package_path` directly — it points to the package the helper resolved.
 
-**Exports resolution order (H1) — script-driven:** Do NOT walk per-skill `metadata.json` → `references/` → SKILL.md by hand. Invoke the helper once at step entry to compute the full inventory for every confirmed skill in one deterministic call:
+**Exports resolution order (H1), script-driven:** Do NOT walk per-skill `metadata.json` → `references/` → SKILL.md by hand. Invoke the helper once at step entry to compute the full inventory for every confirmed skill in one deterministic call:
 
-**Resolve `{enumerateStackSkillsHelper}`** from `{enumerateStackSkillsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+**Resolve `{enumerateStackSkillsHelper}`** from `{enumerateStackSkillsProbeOrder}`; first existing path wins. If no candidate exists, HALT (exit 3, `halt_reason: "helper-missing"`, phase `parallel-extract:enumerate`) with "**Cannot proceed.** `skf-enumerate-stack-skills.py` is missing, so no constituent's exports can be read. Re-install SKF, then re-run."
 
 ```bash
-uv run {enumerateStackSkillsHelper} enumerate {skills_output_folder}
+uv run {enumerateStackSkillsHelper} enumerate {skills_output_folder} > "{stackInventoryFile}"
 ```
 
-The script emits JSON of the form:
+Its JSON, in `{stackInventoryFile}`, has the form:
 
 ```json
 {
@@ -52,34 +93,40 @@ The script emits JSON of the form:
       "exports": ["..."],
       "exports_source": "metadata|references|skill-md|unknown",
       "confidence": "T1|T2|T1-low",
-      "metadata_hash": "sha256:..." | null
+      "evidence_tier": "T1|T1-low|T2|T3",
+      "metadata_hash": "sha256:..."
     }
   ],
   "cycles": ["<skill-name>"],
-  "warnings": ["<text>"]
+  "warnings": ["<text>"],
+  "not_skf_output": ["<skill-name>"]
 }
 ```
 
-Cache this result as `stack_skill_inventory` in workflow state — the per-skill subagent fan-out at §1+ MUST read from this cache rather than re-reading each skill's `SKILL.md` / `metadata.json` / `references/` to determine exports. Append every entry in `warnings[]` to workflow state for the evidence report (the script already labels them per-skill, e.g. `"<skill-name>: no exports found via any resolution path"`). If `cycles[]` is non-empty, a composes-cycle makes the stack unbuildable — emit the result envelope on stderr per the Result Contract in SKILL.md and exit `3`:
+§0 reads this JSON from `{stackInventoryFile}`: each constituent's exports come from it, never from memory or from re-reading its `SKILL.md`, `metadata.json` or `references/`. Append to `workflow_warnings[]` the `warnings[]` entries that name a confirmed skill (each starts with `<skill_dir>: `, e.g. `"<skill-name>: no exports found via any resolution path"`). If `cycles[]` names a confirmed skill, a composes-cycle makes the stack unbuildable: HALT (exit 3, `halt_reason: "resolution-failure"`, phase `parallel-extract:cycle`) with "composes cycle among the confirmed skills: {the `cycles[]` names}."
 
-```
-SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":[],"mode":"compose","exit_code":3,"halt_reason":"resolution-failure"}
-```
-
-Build a `per_library_extractions[]` entry for each skill by reading from the cached inventory:
+Build a `per_library_extractions[]` entry for each confirmed skill, from the `skills[]` entry whose `name` is its `skill_dir`:
 - `library`: `inventory.skills[i].name`
 - `exports`: `inventory.skills[i].exports`
 - `exports_source`: `inventory.skills[i].exports_source` (one of `metadata|references|skill-md|unknown` — capture for step 7 provenance)
-- `confidence`: `inventory.skills[i].confidence` (one of `T1|T2|T1-low`; `unknown` source ⇒ `T1-low`). Do not silently drop T3 evidence; carry whatever tier the source skill declared if §1+ subagent analysis upgrades the value.
-- `metadata_hash`: `inventory.skills[i].metadata_hash` — record for step 7 provenance (null when exports came from references/ or SKILL.md prose).
-- `usage_patterns`: populated by the §1+ per-skill subagent fan-out, NOT by this script. The script provides the inventory + exports; the subagent does the per-skill usage analysis. They're complementary.
+- `confidence`: `inventory.skills[i].evidence_tier` (one of `T1|T1-low|T2|T3`), the library's tier, which steps 5 and 7 read. Never `inventory.skills[i].confidence`: it only says where the export list came from.
+- No `metadata_hash`: step 7's provenance helper copies the anchor above from `{stackInventoryFile}` into `constituents[]`.
+- `skill_dir`, `skill_package_path`, `version` and `source_authority`: from step 2's entry, the path refreshed above.
+- `usage_patterns`: read from the constituent's `SKILL.md` loaded above, each with the file and line it cites there.
 
-Report the loaded extractions — for each skill: export count, confidence tier, and load status. Then auto-proceed to the next step.
+Write `{bundleFile}`: `mode`, `scope` and these entries. Then report the loaded extractions: for each skill, export count, confidence tier, and load status. Then auto-proceed to the next step.
 
 **If not compose_mode:** Continue with section 1 (existing flow).
 
 ### 1. Prepare Extraction Plan
 
+**Export labels, at every tier:**
+
+- An export an ast-grep rule matched: `extraction_method: "ast_bridge"`, `confidence: "T1"`, `signature_source: "T1"`.
+- An export read by eye, for any reason (Quick tier, ast-grep unavailable, a file ast-grep could not parse, a rule that matched nothing, or a file read instead of running a rule): `extraction_method: "source_reading"`, `confidence: "T1-low"`, `signature_source: "T1-low"`.
+
+Deep-tier temporal findings are T2 annotations, never export labels.
+
 **AST Tool Availability Check (Forge/Deep only):**
 
 This workflow operates on local project files and installed library packages. Remote source resolution does not apply — libraries are analyzed as they exist within the project's dependency tree.
@@ -88,11 +135,11 @@ This workflow operates on local project files and installed library packages. Re
 
 ⚠️ **Warn the user explicitly:** "AST tools are unavailable — extraction will use source reading (T1-low). Run [SF] Setup Forge to detect and configure AST tools for T1 confidence."
 
-Degrade to Quick tier extraction. Note the degradation reason in context for the evidence report.
+Degrade to Quick tier extraction, and append a `workflow_warnings[]` entry (`step: "step-04"`, `severity: "warn"`, `code: "ast-degraded"`, `message`: the tier and the reason), which the evidence report lists.
 
 **Per-file AST failure handling:**
 
-If ast-grep fails on an individual file (parse error, unsupported syntax), fall back to source reading for that file only. Label the affected file's results T1-low; unaffected files retain T1. Log a warning noting which file degraded and why.
+If ast-grep fails on an individual file (parse error, unsupported syntax), fall back to source reading for that file only, and log a warning noting which file degraded and why.
 
 For each library in `confirmed_dependencies`, determine extraction strategy based on forge tier:
 
@@ -100,16 +147,14 @@ For each library in `confirmed_dependencies`, determine extraction strategy base
 - Read source files that import the library
 - Extract usage patterns from import statements and function calls
 - Identify key exports used in this project
-- Confidence: T1-low (source reading inference)
 
 **Forge Tier (adds to Quick):**
 - Use ast_bridge to analyze structural exports from library source
 - Extract function signatures, type definitions, class hierarchies
 - Map parameter types and return types
-- Confidence: T1 (AST-verified structural extraction)
 
 **Deep Tier (adds to Forge):**
-- Perform all Forge tier extractions (T1)
+- Perform all Forge tier extractions
 - Additionally: query existing QMD temporal collections for each library
 - Read the `qmd_collections` registry from `{sidecar_path}/forge-tier.yaml`
 - For each library in `confirmed_dependencies`, search for a registry entry where `skill_name` matches the library name AND `type` is `"temporal"`
@@ -123,26 +168,36 @@ For each library in `confirmed_dependencies`, determine extraction strategy base
 - **If no matching temporal collection found:**
   - Log: "No temporal collection for {library_name}. T2 enrichment skipped."
   - Continue with T1/T1-low extraction only
-- Confidence: T1 for structural (AST), T2 for temporal annotations (QMD-enriched)
 
 ### 2. Launch Parallel Extraction
 
 **Launch subprocesses in parallel** (max_parallel_generation: 3–5 concurrent Agent tool calls in Claude Code, IDE-dependent in Cursor, CPU core count in CLI) — one per confirmed library:
 
 Each subprocess:
-1. Reads all files importing the library (from step 03 file lists)
+1. Reads all files importing the library (its `files[]` in `{importCountsFile}`, step 3's import counts, whose paths are relative to `{project_root}`, as `source_file` is)
 2. Extracts key exports used in this project (functions, classes, types, constants)
 3. Identifies usage patterns (initialization, configuration, common call patterns)
-4. Labels confidence tier based on extraction method
-5. Returns structured extraction to parent:
+4. Labels each export by the tool that read it (§1)
+5. Returns structured extraction to parent, one record per export:
 
 ```
 {
   library: "name",
   version: "from_manifest",
-  exports_found: ["fn1", "fn2", "Type1"],
+  exports: [
+    {
+      export_name: "fn1",
+      export_type: "function|class|type|constant",
+      params: ["typed param strings"],
+      return_type: "type",
+      source_file: "path relative to {project_root}",
+      source_line: 0,
+      extraction_method: "ast_bridge|source_reading",
+      confidence: "T1|T1-low",
+      signature_source: "T1|T1-low"
+    }
+  ],
   usage_patterns: ["pattern description with file:line"],
-  confidence: "T1|T1-low|T2|T3",
   files_analyzed: count,
   warnings: [],
   temporal: {
@@ -154,6 +209,8 @@ Each subprocess:
 }
 ```
 
+`{project_root}` is the project root, `project_root` from step 1, whatever folder `{scan_root}` narrowed steps 2, 3 and 5 to: `source_file` is relative to it, with forward slashes (a library installed outside it, in a global site-packages say, is relative to its install folder, and step 7 warns on it). `source_line` is the export's `def`, `class` or declaration line, not a decorator above it. The subprocess returns no library tier: §3a sets it.
+
 **If parallel subprocess unavailable:** Process libraries sequentially in main thread. Report progress after each library.
 
 **Per-subprocess timeout (S6):** Apply a 60-second wall-clock timeout to each library's extraction subprocess. On timeout, mark the library as `partial-failure` with `warnings: ["extraction timeout after 60s"]`, store whatever partial data was returned (if any), and continue with the remaining libraries. Do NOT abort the batch on a single timeout.
@@ -162,7 +219,7 @@ Each subprocess:
 
 For each library extraction:
 
-**Success:** Store extraction result.
+**Success:** Store the extraction result as the library's `per_library_extractions[]` entry.
 
 **Partial failure:** Store partial result with warnings, continue with other libraries.
 
@@ -170,18 +227,35 @@ For each library extraction:
 
 "**Warning:** Extraction failed for {library}: {reason}. Excluding from stack skill."
 
-**If ALL extractions fail:** HALT — cannot produce meaningful stack skill. Before halting (B7):
+Record each excluded library in the bundle's `failed[]` and append a `workflow_warnings[]` entry (`step: "step-04"`, `severity: "warn"`, `code: "extraction-failed"`, `message`: the library and the reason).
+
+**If ALL extractions fail:** HALT (exit 2, `halt_reason: "all-extractions-failed"`, phase `parallel-extract:all-failed`, `stack_libraries` the confirmed library names that failed): nothing remains to build a stack from (B7). The run folder stays, as after every halt but a cancel: its `warnings.jsonl` holds the `extraction-failed` entry that says why each library failed.
+
+**Otherwise** write `{bundleFile}`: `mode`, `scope`, one `per_library_extractions[]` entry per library that returned (each export record moves to `{exportRecordsFile}` in §3a, so the entry keeps none) and `failed[]`.
+
+### 3a. Check the Export Labels
 
-1. Purge any in-flight staging artifacts under the forge workspace: remove `{forge_data_folder}/{project_name}-stack/{version}/*-tmp` and any `{forge_data_folder}/{project_name}-stack/{version}/*.skf-tmp` directories so partial state does not linger.
-2. Emit the result envelope on stderr per the Result Contract in SKILL.md (`stack_libraries` carries the confirmed library names that failed extraction), and exit `2`:
+Code mode only (compose mode leaves this step at §0). Steps 5 to 7 read the labels checked here, from the file this section writes and keeps for the rest of the run.
+
+Write every export record, each with `source_library` set to its library, as `{"entries": [...]}` to `{exportRecordsFile}`. Resolve `{renderStackMetadataHelper}` from `{renderStackMetadataProbeOrder}`; first existing path wins. If no candidate exists, HALT (exit 3, `halt_reason: "helper-missing"`, phase `parallel-extract:library-tiers`) with "**Cannot proceed.** `skf-render-stack-metadata.py` is missing, so no export label can be checked and no library tier set. Re-install SKF, then re-run." Otherwise relabel the records:
+
+```bash
+uv run {renderStackMetadataHelper} relabel --records "{exportRecordsFile}"
+```
+
+Keep its `confidence_distribution` (one count per record, never `metadata.json`'s) as §4's export label counts. When its `relabeled[]` is not empty, append one `workflow_warnings[]` entry (`step: "step-04"`, `severity: "info"`, `code: "export-labels-relabeled"`) naming each relabeled export and its library. When it exits `1` (a violation it could not fix, in its `coherence.violations[]`) or `2` (no JSON: its stderr says why), append a `workflow_warnings[]` entry (`step: "step-04"`, `severity: "warn"`, `code: "label-check-skipped"`, `message`: those violations or its stderr) and go on.
+
+**Library tiers.** Run the same helper on the checked records, with every library of the bundle's `per_library_extractions[]`, comma-separated:
+
+```bash
+uv run {renderStackMetadataHelper} library-tiers --records "{exportRecordsFile}" --libraries "<names>"
+```
 
-   ```
-   SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":["<confirmed-lib>", "..."],"mode":"{code|compose}","exit_code":2,"halt_reason":"all-extractions-failed"}
-   ```
+Set each library's `per_library_extractions[].confidence` in `{bundleFile}` to its `tier`, the helper's one rule for a code-mode library. On exit `2` its stderr names the input it refused, such as a record whose `source_library` is not a stack library: fix the record or the list and run it again. Step 5 takes each integration's tier from these tiers, and step 7 bins each library once by them.
 
 ### 4. Display Extraction Summary
 
-Report the extraction results: per library the export count, pattern count, confidence tier, and success/partial status; the overall `{success_count}/{total_count}` extracted; and the T1 / T1-low / T2 confidence distribution. At Deep tier, add the T2-enrichment count (`{enriched_count}/{total_count}` libraries with temporal collections available); and if any library lacked a temporal collection, add the tip: run **[CS] Create Skill** at Deep tier for those libraries to generate temporal collections, then re-run **[SS]** for full T2 enrichment. Note any warning count.
+Report the extraction results from `{bundleFile}`: per library the export count, pattern count, confidence tier, and success/partial status; the overall `{success_count}/{total_count}` extracted; the number of libraries at each tier (the unit of `metadata.json`'s `confidence_distribution`); and the export label counts §3a kept. At Deep tier, add the T2-enrichment count (`{enriched_count}/{total_count}` libraries with temporal collections available); and if any library lacked a temporal collection, add the tip: run **[CS] Create Skill** at Deep tier for those libraries to generate temporal collections, then re-run **[SS]** for full T2 enrichment. Note any warning count.
 
 ### 5. Auto-Proceed to Next Step
 

package/src/skf-create-stack-skill/references/rank-and-confirm.md

@@ -1,5 +1,12 @@
 ---
 nextStepFile: 'parallel-extract.md'
+countImportsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-count-imports.py'
+  - '{project-root}/src/shared/scripts/skf-count-imports.py'
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
+importCountsFile: '{run_dir}/import-counts.json'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -8,26 +15,34 @@ nextStepFile: 'parallel-extract.md'
 
 ## STEP GOAL:
 
-Count import frequency for each dependency across the codebase, rank by usage, and present for user confirmation of which libraries to include in the stack skill.
+Count the files under `{scan_root}` that import each dependency, rank by usage, and confirm at one gate which libraries the stack skill includes.
 
 ## Rules
 
 - Focus on counting imports, ranking, and getting user confirmation — do not extract documentation (Step 04)
-- Use subprocess Pattern 1 (grep/search) when available
+- Take every count from `skf-count-imports.py`; never count imports by hand
 
 ## MANDATORY SEQUENCE
 
+**Halt envelope.** Every HALT in this step names its exit code, `halt_reason` and phase. Stage `{run_dir}/halt.json` as `{"phase": "<phase>", "halt_reason": "<halt_reason>", "reason": "<the halt message, one line>", "skill_name": "{stack_name}", "mode": "<code|compose>"}`, then run:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-stack-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+Display the line it prints, then stop with the halt's exit code (`references/invocation-contract.md` lists every halt). If `{emitEnvelopeHelper}` is not bound, resolve it from `{emitEnvelopeProbeOrder}`; if no path exists, or the emitter exits non-zero or prints no line, display the halt message alone.
+
+**Warnings.** Each `workflow_warnings[]` entry this step appends is recorded at once: write its `[{step}/{severity}] {code}: {message}` line to `{run_dir}/warning.txt` with a file write, then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/warning.txt")"`.
+
 ### 1. Count Import Frequency
 
 **If `compose_mode` is true:**
 
-Skip import counting entirely. All skills are included by default.
-
-Set `confirmed_dependencies` = all `raw_dependencies` (the list already stored as workflow state from Step 02).
+Skip import counting entirely. All skills are included by default: the recommended scope is every `raw_dependencies` entry (the list step 2 stored).
 
 **Apply scope_overrides:** If `scope_overrides` were provided in step 01, apply them now — force-include or force-exclude skills as specified. Log any overrides applied.
 
-**Validate override keys (S4):** Every key in `scope_overrides` MUST be present in `raw_dependencies`. For any unknown key, emit `"scope_override: unknown dependency '{key}' — skipping"` and drop that override entry (do not fail the run). Known-key overrides still apply.
+**Validate override keys (S4):** Every key in `scope_overrides` MUST be present in `raw_dependencies`. For any unknown key, append a `workflow_warnings[]` entry (`step: "step-03"`, `severity: "warn"`, `code: "scope-override-unknown"`, `message`: "scope_override: unknown dependency '{key}', skipped") and drop that override entry (do not fail the run). Known-key overrides still apply.
 
 Present skills sorted by architectural layer (from architecture doc if available):
 - If `architecture_doc_path` is not null: **wrap the architecture-doc parse in try/except (S5)**. On any parse error (file unreadable, malformed markdown, no H2 structure), fall back to alphabetical ordering and log a warning `"architecture-doc parse failed: {error} — falling back to alphabetical"`. Otherwise parse section headers to determine layer grouping.
@@ -39,100 +54,67 @@ Display skills as a table:
 |---|-------|----------|------|--------------------|
 | 1 | {name} | {language} | {confidence_tier} | {layer or 'Unclassified'} |
 
-User confirms inclusion/exclusion at the gate (same [C] menu as code-mode).
-
-Skip to [Present MENU OPTIONS](#5-present-menu-options).
+Set `confirmed_dependencies` ← that scope, with the overrides applied, and skip to [Confirm the Scope](#3-confirm-the-scope).
 
 **If not compose_mode:**
 
-For each dependency in `raw_dependencies`:
+Count, for each dependency, the files under `{scan_root}` that import it, with the shared helper that holds the counting rules (its `--help` states them). **Resolve `{countImportsHelper}`** from `{countImportsProbeOrder}`; first existing path wins. If no candidate exists, HALT (exit 3, `halt_reason: "helper-missing"`, phase `rank-and-confirm:count`) with "**Cannot proceed.** `skf-count-imports.py` is missing, so no import can be counted. Re-install SKF, then re-run."
 
-**Launch a subprocess** that runs grep across all source files in the project to count import statements for each library. Return only the counts, not file contents.
+```bash
+uv run {countImportsHelper} count {scan_root} --deps - --relative-to {project_root} > "{importCountsFile}"
+```
 
-**Subprocess resolution:** Use the Grep tool (Claude Code), built-in search (Cursor), or `grep`/`rg` (CLI). See `knowledge/tool-resolution.md`.
+Pipe `raw_dependencies` on stdin: step 2's scan JSON as it stands, or, when step 2 took `explicit_deps`, those names as a JSON array (if stdin piping is unavailable, write it to `{run_dir}/dependencies.json` and pass that path to `--deps`). `{project_root}` is `project_root` from step 1: the helper scans only `{scan_root}` and writes each path relative to the project root, the base every path this run records shares. Its JSON goes to `{importCountsFile}`, the run's import counts, which this step ranks from: step 4 reads each library's files from it, and step 5 §1 passes it to the pair helper as it stands. Each `dependencies[]` entry gives `file_count`, `files[]` (`path`, and `line`, the first line that imports it) and `above_threshold` (2 or more files); a dependency only the dev sections list carries `scope: "dev"`.
 
-Use ecosystem-appropriate import patterns:
-- JavaScript/TypeScript: `import .* from ['"]library`, `require\(['"]library`
-- Python: `import library`, `from library import`
-- Rust: `use library::`, `extern crate library`
-- Go: `"library"` in import blocks
-- (Match patterns from `{manifestPatternsPath}`)
-
-**Subprocess returns:** `{library_name: import_count, files: [file_paths]}` for each dependency.
-
-**If subprocess unavailable:** Perform grep operations in main thread sequentially.
-
-Exclude from counting:
-- Test files (*/test/*, *_test.*, *.spec.*, *.test.*)
-- Config files (*.config.*, .eslintrc, etc.)
-- Build artifacts (dist/, build/, node_modules/, target/, __pycache__/)
+**Unresolved names.** `unresolved[]` lists, each with its `reason`, the dependencies the helper cannot count with confidence: a guessed import name that matched no file, no import name, or an ecosystem with no import rules; the helper never counts them as 0. For a runtime entry whose import name you know (`python-dateutil` is imported as `dateutil`), run the call again with that name and without the `>` redirect, which would replace the file, piping `[{"name": "<name>", "ecosystem": "<its ecosystem>", "modules": ["<import name>"]}]`, add the `dependencies[]` entry it returns to `{importCountsFile}`, drop the entry from `unresolved[]`, keep `dependencies[]` sorted by `file_count` (highest first), then name, and write the file back, so the library ranks and pairs like the others. Every other unresolved entry goes below the threshold with its `reason`.
 
 ### 2. Rank and Filter
 
-Sort dependencies by import count (descending).
+`dependencies[]` comes ranked: by `file_count`, highest first, then by name.
 
 Apply filtering:
-- **Include by default:** Libraries with 2+ import files
-- **Flag as trivial:** Libraries with 0-1 import files
+- **Include by default:** the runtime libraries with `above_threshold` true
+- **Below threshold:** every other library: under 2 files, a dev-only dependency, or an unresolved one
 - **Apply scope_overrides** from step 01 if provided (force include/exclude)
 
-### 3. Present Ranked List
-
-"**Dependency ranking complete.** Here are your project's libraries ranked by usage:
+Set `confirmed_dependencies` ← the recommended scope: the libraries included by default, with the overrides applied. The gate below keeps it, or the user's edits change it.
 
-| # | Library | Imports | Files | Category |
-|---|---------|---------|-------|----------|
-| 1 | {name} | {count} | {file_count} | runtime |
-| 2 | {name} | {count} | {file_count} | runtime |
-| ... | ... | ... | ... | ... |
+### 3. Confirm the Scope
 
-**Below threshold** (0-1 imports — excluded by default):
-| Library | Imports | Category |
-|---------|---------|----------|
-| {name} | {count} | {category} |
+Present the scope and the one gate. **In code mode:**
 
-**Total:** {total} dependencies detected, {above_threshold} recommended for inclusion
-
----
-
-**Please confirm your scope:**
-- Type **C** to accept the recommended scope (all above-threshold libraries)
-- Type library names to **add** from the below-threshold list
-- Type **-library_name** to **exclude** a recommended library
-- Type a custom list to override entirely"
-
-### 4. Process User Response
-
-**If C (accept recommended):**
-Store all above-threshold libraries as `confirmed_dependencies`.
+"**Dependency ranking complete.** Here are your project's libraries ranked by usage:
 
-**If modifications requested:**
-Apply additions/exclusions, display updated list, and ask for final confirmation.
+| # | Library | Files | Category |
+|---|---------|-------|----------|
+| 1 | {name} | {file_count} | runtime |
+| 2 | {name} | {file_count} | runtime |
+| ... | ... | ... | ... |
 
-**If custom list provided:**
-Use the custom list as `confirmed_dependencies`.
+**Below threshold** (excluded by default):
+| Library | Files | Category |
+|---------|-------|----------|
+| {name} | {file_count, or the unresolved `reason`} | {runtime, or dev for a `scope: "dev"` dependency} |
 
-Display the resolved scope:
+**Total:** {total} dependencies detected, {above_threshold} recommended for inclusion"
 
-"**Scope confirmed:** {count} libraries selected for stack skill extraction.
+**In compose mode** the skills table of §1 is the scope.
 
-{List confirmed libraries}"
+Display: **Select:** [C] Continue to extraction with this scope | [X] Cancel and exit, or type library names to **add** from the below-threshold list, **-library_name** to **exclude** one, or a custom list to replace the scope.
 
-The extraction itself begins only once the user clears the gate below.
+#### EXECUTION RULES:
 
-### 5. Present MENU OPTIONS
+- This is a confirmation gate: advancing without the user's `C` would extract and ship a stack scope they never approved. Halt and wait for input after presenting the scope.
+- **GATE [default: C]**: If `{headless_mode}`: auto-proceed with [C] Continue, keeping `confirmed_dependencies` as §2 set it (the recommended libraries in code mode, every skill in compose mode), and record the auto-decision, which names each library the default left out: stage `{"gate": "rank-and-confirm.scope", "default_action": "C", "taken_action": "C", "reason": "headless: kept the recommended scope", "evidence": {"scope": ["<confirmed library>", ...], "dropped": [{"library": "<name>", "reason": "<under 2 files, dev only, its unresolved reason, or excluded by scope_overrides>"}, ...]}}` as `{run_dir}/decision.json` and run:
 
-Display: **Select:** [C] Continue to Extraction | [X] Cancel and exit
+  ```bash
+  uv run {emitEnvelopeHelper} record --workflow skf-create-stack-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+  ```
 
-#### EXECUTION RULES:
-
-- This is a confirmation gate — advancing without the user's `C` would extract and ship a stack scope they never approved. Halt and wait for input after presenting scope.
-- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue (accept all ranked libraries), log: "headless: auto-confirm library scope"
-- Proceed to the next step only once the user confirms scope by selecting `C`.
+- Proceed to the next step only once the user approves the scope by selecting `C`.
 
 #### Menu Handling Logic:
 
-- IF C: Store current `confirmed_dependencies` (including any modifications made since initial presentation), then load, read entire file, then execute {nextStepFile}
-- IF X: Invoke the rollback contract (purge any `{forge_data_folder}/{project_name}-stack/{version}/*-tmp` and `*.skf-tmp` staging artifacts under the forge workspace, leave any existing committed stack package untouched), emit the `SKF_STACK_RESULT_JSON` envelope on stderr with `status: "error"`, `halt_reason: "user-cancelled"`, `exit_code: 6`, and exit with code 6
-- IF Any other: Process as scope modification (add/remove skills from `confirmed_dependencies`), update the in-memory `confirmed_dependencies` list accordingly, redisplay the updated skills table, then [Redisplay Menu Options](#5-present-menu-options)
-
+- IF C: Display "**Scope confirmed:** {count} libraries selected for stack skill extraction." with the list, then load, read entire file, then execute {nextStepFile}
+- IF X: HALT (exit 6, `halt_reason: "user-cancelled"`, phase `rank-and-confirm:scope`): leave any existing committed stack package untouched, emit the envelope, then delete the run folder (`rm -rf "{run_dir}"`)
+- IF Any other: Process it as a scope change (add or remove libraries from `confirmed_dependencies`, or replace them with a custom list), redisplay the updated table, then [Redisplay the gate](#3-confirm-the-scope)