bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/{workflows/create-stack-skill → skf-create-stack-skill}/steps-c/step-02-detect-manifests.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-02-detect-manifests'
-description: 'Scan project for dependency manifests and extract raw dependency list'
-
 nextStepFile: './step-03-rank-and-confirm.md'
-manifestPatterns: '../data/manifest-patterns.md'
+manifestPatterns: 'references/manifest-patterns.md'
 ---
 
 # Step 2: Detect Manifests
@@ -12,39 +9,11 @@ manifestPatterns: '../data/manifest-patterns.md'
 
 Scan the project root for dependency manifest files, parse each to extract dependency names and versions, and produce a raw dependency list for ranking.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a dependency analyst operating in Ferris Architect mode
-- ✅ Prescriptive precision — report exactly what was found, nothing assumed
-- ✅ Zero hallucination — only list dependencies actually present in manifest files
-
-### Step-Specific Rules:
+## Rules
 
-- 🎯 Focus ONLY on finding and parsing manifest files
-- 🚫 FORBIDDEN to count imports or rank dependencies — that is step 03
-- 🚫 FORBIDDEN to extract library documentation — that is step 04
-- 💬 If explicit dependency list was provided in step 01, use it and skip detection
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Load manifest-patterns.md for detection rules
-- 💾 Store manifests found and raw dependency list as workflow state
-- 📖 Auto-proceed to step 03 after successful detection
-- 🚫 HALT if no manifests found and no explicit list provided — **unless `compose_mode` is true** (compose mode skips manifest detection)
-
-## CONTEXT BOUNDARIES:
-
-- From step 01: forge tier, available tools, optional explicit_deps, project_root
-- This step produces: manifests[], raw_dependencies[]
-- Does NOT rank, filter, or analyze — just detect and parse
+- Focus only on finding and parsing manifest files
+- Do not count imports or rank dependencies (Step 03) or extract documentation (Step 04)
+- If explicit dependency list was provided in step 01, use it and skip detection
 
 ## MANDATORY SEQUENCE
 
@@ -58,23 +27,38 @@ Use the explicit dependency list directly. Store the explicit list as `raw_depen
 
 **If `compose_mode` is true AND `explicit_deps` was NOT provided:**
 
-Discover skills in `{skills_output_folder}` using version-aware resolution — see [knowledge/version-paths.md](../../../knowledge/version-paths.md) for path templates.
+Discover skills in `{skills_output_folder}` using version-aware resolution — see `knowledge/version-paths.md` for path templates.
 
 **Version-aware skill enumeration:**
 
 1. **Primary: Export manifest** — Read `{skills_output_folder}/.export-manifest.json`. For each entry in `exports`, resolve the active version path: `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/` — this directory must contain both `SKILL.md` and `metadata.json`.
-2. **Fallback: `active` symlinks** — If the manifest does not exist, is empty, or a manifest entry lacks an `active_version`, scan for `{skills_output_folder}/*/active/*/SKILL.md`. Each match resolves to a skill package at `{skills_output_folder}/{skill-name}/active/{skill-name}/` (the `{active_skill}` template).
 
-**Filter:** Skip any skill named `{project_name}-stack` or any skill where `metadata.json` has `"skill_type": "stack"` — stack skills must not be loaded as source dependencies to avoid self-referencing loops.
+   **Stale manifest fallback (H6):** If a manifest entry resolves to a path that does not exist (broken `active_version`, deleted version dir, missing `SKILL.md` / `metadata.json`), do NOT HALT for that single entry. Instead:
+   a. Fall back to the symlink scan (rule 2) **for that one skill only**: probe `{skills_output_folder}/{skill-name}/active/{skill-name}/SKILL.md`.
+   b. If the symlink-based path resolves, use it and log a warning: `"export-manifest entry '{skill-name}' is stale — resolved via active symlink instead"`.
+   c. If BOTH the manifest path AND the symlink path fail, only then HALT with a manifest-corruption diagnostic naming the affected skill and pointing the user at `[SKF-update-skill]` to repair.
+
+   **Manifest JSON parse guard (B3):** Wrap the `.export-manifest.json` parse in try/except. If JSON parsing fails for any reason, fall through entirely to the `active` symlink scan (rule 2) across all skills; log a warning and validate each symlink target exists before including it.
+
+2. **Fallback: `active` symlinks** — If the manifest does not exist, is empty, JSON-parse fails, or an individual manifest entry fails to resolve, scan for `{skills_output_folder}/*/active/*/SKILL.md`. Each match resolves to a skill package at `{skills_output_folder}/{skill-name}/active/{skill-name}/` (the `{active_skill}` template). Verify the active symlink target actually exists and contains both `SKILL.md` and `metadata.json`.
+
+**Filter & cycle guard (B4):** Skip any skill where the filter below matches:
+
+- Skill name equals `{project_name}-stack`, OR
+- `metadata.json` has `"skill_type": "stack"`, OR
+- `metadata.json` is missing or unreadable (treat `skill_type: unknown` as non-loadable — exclude to avoid loading a partially-written or self-referential skill).
+
+Maintain a **visited set keyed by `skill_dir`** (the top-level dir under `{skills_output_folder}`) while resolving. If a skill would be revisited via a circular reference (e.g., a constituent that claims another stack as dependency), skip the duplicate and log a warning `"cycle detected at {skill_dir} — skipping"`. Stack skills must not be loaded as source dependencies to avoid self-referencing loops.
 
 **If zero skills remain after filtering:** HALT with: "**Cannot proceed in compose-mode.** No individual skills found in `{skills_output_folder}` (after filtering stack skills). Run [CS] Create Skill or [QS] Quick Skill to generate individual skills first, then re-run [SS]."
 
 For each skill found:
-1. Read `metadata.json` from the resolved version-aware path (`{skill_package}` or `{active_skill}`)
+1. Read `metadata.json` from the resolved version-aware path (`{skill_package}` or `{active_skill}`). **Skill-type gate (S1):** the sibling `metadata.json` MUST be present AND parseable AND contain a `skill_type` field whose value is one of the known set (`skill`, `stack`, or any future values explicitly recognised by this workflow). Directories lacking a qualifying `metadata.json`/`skill_type` are NOT treated as skills — log `"{dir_name}: not a skill (no valid metadata.json/skill_type) — excluding"` and skip.
 2. Extract: name, language, confidence_tier, source_repo, exports count, version
 3. Store the skill group directory name as `skill_dir` (the top-level name under `{skills_output_folder}`, distinct from `name` — the directory may differ from the metadata name)
 4. Store the resolved package path as `skill_package_path` for use in later steps
-5. Store as `raw_dependencies` with source: "existing_skill"
+5. **Hash the constituent metadata at read-time (S13):** compute `sha256` of the raw `metadata.json` bytes just read, and store it in workflow state as `metadata_hash` alongside `skill_package_path`. Step-07 uses this stored hash (not a re-read) for `constituents[].metadata_hash` in `provenance-map.json`, so drift between step-02 read and step-07 write is captured.
+6. Store as `raw_dependencies` with source: "existing_skill"
 
 Display:
 "**Loaded {N} existing skills as dependencies.**
@@ -114,6 +98,10 @@ Scan the project root (depth 0-1) for manifest files, **excluding directories li
 
 **If no manifest files found:**
 
+**Headless auto-cancel (S2):** If `{headless_mode}` is true, do NOT wait for user input. Emit a structured error contract `{"status":"error","skill":"skf-create-stack-skill","stage":"step-02","reason":"no manifests found, headless cannot prompt"}` on stderr and exit non-zero. Headless mode cannot proceed without an explicit dependency list.
+
+**Interactive mode:**
+
 "**No dependency manifests detected** in the project root.
 
 Searched for: package.json, requirements.txt, Cargo.toml, go.mod, pom.xml, build.gradle, Gemfile, composer.json, *.csproj
@@ -161,25 +149,3 @@ Deduplicate dependencies found across multiple manifests.
 
 Load, read the full file and then execute `{nextStepFile}`.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- All manifest files in project root detected
-- Each manifest parsed with dependency names extracted
-- Runtime vs dev-only categorization applied
-- Deduplication across multiple manifests completed
-- Detection summary displayed with accurate counts
-- Auto-proceeded to step 03
-
-### ❌ SYSTEM FAILURE:
-
-- Missing manifest files that exist in the project
-- Inventing dependencies not in manifest files
-- Starting to rank or analyze dependencies (step 03's job)
-- Not halting when no manifests found
-- Displaying A/P menu (this is auto-proceed)
-
-**Master Rule:** Detect and parse only. No ranking, no filtering, no analysis.

package/src/{workflows/create-stack-skill → skf-create-stack-skill}/steps-c/step-03-rank-and-confirm.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-03-rank-and-confirm'
-description: 'Rank dependencies by import frequency and confirm scope with user'
-
 nextStepFile: './step-04-parallel-extract.md'
 ---
 
@@ -11,40 +8,10 @@ nextStepFile: './step-04-parallel-extract.md'
 
 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.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a dependency analyst operating in Ferris Architect mode
-- ✅ Prescriptive precision — import counts must reflect actual code
-- ✅ User has final authority on scope — present data, let them decide
-
-### Step-Specific Rules:
-
-- 🎯 Focus on counting imports, ranking, and getting user confirmation
-- 🚫 FORBIDDEN to extract library documentation — that is step 04
-- 💬 Present data clearly so user can make informed scope decisions
-- 🎯 Use subprocess (Pattern 1 — grep/search): In Claude Code, use the Grep tool or Bash with `rg`. In Cursor, use built-in search. In CLI, use `grep`/`rg` directly. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Count imports per library across the codebase
-- 💾 Store confirmed_dependencies as workflow state
-- 📖 Wait for user confirmation before proceeding
-- 🚫 FORBIDDEN to proceed without explicit user scope confirmation
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- From step 02: raw_dependencies[] with ecosystem info
-- This step produces: confirmed_dependencies[] (user-approved scope)
-- User interaction: Gate 1 — scope confirmation required
-- Apply scope_overrides from step 01 if provided
+- Focus on counting imports, ranking, and getting user confirmation — do not extract documentation (Step 04)
+- Use subprocess Pattern 1 (grep/search) when available
 
 ## MANDATORY SEQUENCE
 
@@ -60,9 +27,11 @@ Set `confirmed_dependencies` = all `raw_dependencies` (the list already stored a
 
 **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.
+
 Present skills sorted by architectural layer (from architecture doc if available):
-- If `architecture_doc_path` is not null: parse architecture doc for section headers to determine layer grouping
-- If `architecture_doc_path` is null or layers not detectable: present alphabetically
+- 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.
+- If `architecture_doc_path` is null or layers not detectable: present alphabetically.
 
 Display skills as a table:
 
@@ -80,7 +49,7 @@ For each dependency in `raw_dependencies`:
 
 **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.
 
-**Subprocess resolution:** Use the Grep tool (Claude Code), built-in search (Cursor), or `grep`/`rg` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+**Subprocess resolution:** Use the Grep tool (Claude Code), built-in search (Cursor), or `grep`/`rg` (CLI). See `knowledge/tool-resolution.md`.
 
 Use ecosystem-appropriate import patterns:
 - JavaScript/TypeScript: `import .* from ['"]library`, `require\(['"]library`
@@ -158,6 +127,7 @@ Display: **Select:** [C] Continue to Extraction
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user 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"
 - ONLY proceed to next step when user confirms scope and selects 'C'
 
 #### Menu Handling Logic:
@@ -165,23 +135,3 @@ Display: **Select:** [C] Continue to Extraction
 - IF C: Store current `confirmed_dependencies` (including any modifications made since initial presentation), then load, read entire file, then execute {nextStepFile}
 - 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)
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Import counts reflect actual codebase usage (not guesses)
-- Dependencies ranked by import frequency
-- Trivial dependencies filtered below threshold
-- User explicitly confirmed scope
-- confirmed_dependencies stored for step 04
-
-### ❌ SYSTEM FAILURE:
-
-- Fabricating import counts without grepping
-- Proceeding without user scope confirmation
-- Including test/config files in import counts
-- Starting library extraction (step 04's job)
-
-**Master Rule:** Present data, let user decide. No extraction until scope is confirmed.

package/src/{workflows/create-stack-skill → skf-create-stack-skill}/steps-c/step-04-parallel-extract.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-04-parallel-extract'
-description: 'Extract per-library documentation in parallel using tier-dependent tools'
-
 nextStepFile: './step-05-detect-integrations.md'
 ---
 
@@ -11,40 +8,11 @@ nextStepFile: './step-05-detect-integrations.md'
 
 For each confirmed dependency, extract key exports, usage patterns, and API surface documentation using tier-dependent tools in parallel.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a dependency analyst operating in Ferris Architect mode
-- ✅ Zero hallucination — only extract what exists in actual source code
-- ✅ Every export and pattern must cite actual file:line references
-
-### Step-Specific Rules:
+## Rules
 
-- 🎯 Extract per-library using Pattern 4 (parallel): In Claude Code, use multiple parallel Agent tool calls or `run_in_background: true`. In Cursor, use parallel requests (IDE-dependent). In CLI, use `xargs -P` or background processes. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
-- 💬 Each subprocess returns structured extraction, not raw file contents
-- 🚫 FORBIDDEN to analyze cross-library integrations — that is step 05
-- ⚙️ If parallel subprocess unavailable, extract libraries sequentially in main thread
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Launch parallel extraction per confirmed library
-- 💾 Store per_library_extractions with confidence tier labels
-- 📖 Report extraction summary before auto-proceeding
-- 🚫 FORBIDDEN to proceed if zero libraries successfully extracted
-
-## CONTEXT BOUNDARIES:
-
-- From step 03: confirmed_dependencies[] (user-approved scope)
-- From step 01: forge_tier, available_tools
-- This step produces: per_library_extractions[] per library
-- Each extraction includes: exports, patterns, confidence tier
+- Extract per-library using subprocess Pattern 4 (parallel) when available; if unavailable, extract sequentially
+- Each subprocess returns structured extraction, not raw file contents
+- Do not analyze cross-library integrations (Step 05)
 
 ## MANDATORY SEQUENCE
 
@@ -56,11 +24,24 @@ For each confirmed dependency, extract key exports, usage patterns, and API surf
 
 "**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-02. Use `skill_package_path` (stored in step-02) 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](../../../knowledge/version-paths.md)). Build a `per_library_extractions[]` entry for each skill with the following fields:
+For each confirmed skill, load SKILL.md from the version-aware path resolved in step-02.
+
+**Re-resolve at step-04 entry (S17):** Between step-02 manifest detection and step-04 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-02, log a warning `"constituent '{skill_name}' changed between step-02 and step-04 — using fresh values"` and replace the workflow-state entry (so step-07 provenance records the hash active at extraction time, with the drift logged for audit).
+
+Use `skill_package_path` (stored in step-02 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`).
+
+**Exports resolution order (H1):** For each confirmed skill, populate the `exports` field using the first source that returns a non-empty list:
+
+1. **Primary — `metadata.json.exports[]`:** Read the skill's `metadata.json` and use the `exports[]` array directly. This is the most structured and trustworthy source.
+2. **Fallback — `references/`:** If `metadata.json.exports[]` is empty or missing, scan the `references/` subdirectory of the skill package for per-export files and reconstruct the export list from filenames/headers. Log a warning: `"{skill_name}: metadata.json.exports[] empty — reconstructed from references/"` and record the warning in workflow state for the evidence report.
+3. **Last resort — SKILL.md prose parsing:** If both prior sources are unavailable, parse the SKILL.md "Exports" / "API" section prose. Log a stronger warning: `"{skill_name}: falling back to SKILL.md prose parsing — exports may be incomplete"` and record it in workflow state.
+
+Build a `per_library_extractions[]` entry for each skill with the following fields:
 - `library`: skill name from metadata.json
-- `exports`: exports list extracted from the SKILL.md exports section
+- `exports`: exports list resolved via the order above
+- `exports_source`: one of `metadata|references|prose` — capture which resolution path was used (so step-07 provenance can record it)
 - `usage_patterns`: usage patterns from the SKILL.md usage section
-- `confidence`: the skill's existing confidence tier (T1, T1-low, T2) — inherited directly
+- `confidence`: the skill's existing confidence tier (one of `T1|T1-low|T2|T3` per `confidence-tiers.md`) — inherited directly. Do not silently drop T3 evidence; carry whatever tier the source skill declared.
 
 Display an extraction summary:
 
@@ -113,7 +94,7 @@ For each library in `confirmed_dependencies`, determine extraction strategy base
   - Query `qmd_bridge.search("{library_name} deprecated OR removed OR breaking change")` for deprecation context
   - Query `qmd_bridge.search("{library_name} migration OR upgrade")` for migration patterns
   - Query `qmd_bridge.search("{library_name} version issue OR bug OR workaround")` for version-specific warnings
-  - **Tool resolution for qmd_bridge:** Use QMD MCP tools — `mcp__plugin_qmd-plugin_qmd__search` (Claude Code), qmd MCP server (Cursor), `qmd search "{query}"` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
+  - **Tool resolution for qmd_bridge:** Use QMD MCP tools — `mcp__plugin_qmd-plugin_qmd__search` (Claude Code), qmd MCP server (Cursor), `qmd search "{query}"` (CLI). See `knowledge/tool-resolution.md`
   - Classify each result as T2-past (historical) or T2-future (planned changes) per confidence-tiers.md
   - Append temporal findings to the library's extraction as T2 annotations with `[QMD:{collection}:{doc}]` citations
 - **If no matching temporal collection found:**
@@ -138,7 +119,7 @@ Each subprocess:
   version: "from_manifest",
   exports_found: ["fn1", "fn2", "Type1"],
   usage_patterns: ["pattern description with file:line"],
-  confidence: "T1|T1-low|T2",
+  confidence: "T1|T1-low|T2|T3",
   files_analyzed: count,
   warnings: [],
   temporal: {
@@ -152,6 +133,8 @@ Each subprocess:
 
 **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.
+
 ### 3. Handle Extraction Failures
 
 For each library extraction:
@@ -164,7 +147,11 @@ For each library extraction:
 
 "**Warning:** Extraction failed for {library}: {reason}. Excluding from stack skill."
 
-**If ALL extractions fail:** HALT — cannot produce meaningful stack skill.
+**If ALL extractions fail:** HALT — cannot produce meaningful stack skill. Before halting (B7):
+
+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 a structured error contract on stderr: `{"status":"error","skill":"skf-create-stack-skill","stage":"step-04","reason":"all extractions failed","libraries":[...]}`.
+3. Exit with a non-zero status so headless pipelines detect the failure.
 
 ### 4. Display Extraction Summary
 
@@ -188,25 +175,3 @@ For each library extraction:
 
 Load, read the full file and then execute `{nextStepFile}`.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- All confirmed libraries have extraction attempted
-- Extractions cite actual file:line references
-- Confidence tiers correctly assigned per extraction method
-- Partial failures handled gracefully (skip library, continue)
-- Extraction summary displayed with accurate counts
-- Auto-proceeded to step 05
-
-### ❌ SYSTEM FAILURE:
-
-- Fabricating exports not found in source code
-- Not assigning confidence tiers to extractions
-- Halting on single library failure (should degrade gracefully)
-- Analyzing cross-library integrations (step 05's job)
-- Returning raw file contents instead of structured extractions
-
-**Master Rule:** Extract per-library only. Every export must trace to actual code. Degrade gracefully on individual failures.

package/src/skf-create-stack-skill/steps-c/step-05-detect-integrations.md

@@ -0,0 +1,164 @@
+---
+nextStepFile: './step-06-compile-stack.md'
+integrationPatterns: 'references/integration-patterns.md'
+composeModeRules: 'references/compose-mode-rules.md'
+---
+
+# Step 5: Detect Integrations
+
+## STEP GOAL:
+
+Analyze co-import patterns between confirmed libraries to identify integration points — where and how libraries connect in this specific codebase.
+
+## Rules
+
+- Focus on detecting cross-library patterns using subprocess Pattern 1 (grep/search)
+- Do not compile SKILL.md (Step 06)
+- Integration detection is the core differentiator of stack skills vs individual skills
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Generate Library Pairs
+
+From `confirmed_dependencies`, generate all unique pairs:
+- N libraries → N*(N-1)/2 pairs
+- Skip pairs where either library had extraction failure in step 04
+
+**File-list intersection fast path (MANDATORY first pass, all N):** before issuing any pair grep, compute each pair's candidate file set by **intersecting the per-library file lists recorded by step-03 import-count extraction**. Pairs with an empty intersection cannot be integration candidates by construction — drop them. Subsequent grep passes run only against pairs with a non-empty intersection, and grep scope is restricted to those intersection files rather than the whole source tree. This is NOT a "subprocess-unavailable" fallback; it is the default strategy for every N. Rationale: at N≈21 this collapses 210 prescribed pair greps to ~12 non-empty-intersection pairs in typical codebases; at larger N the compression is even greater.
+
+**Top-K cap (S7, lowered to 20):** If the file-list-intersection prune still leaves more than **20** non-empty-intersection pairs, cap at the top 20 pairs ranked by intersection size (or by import count if tied). Dropped pairs are excluded from integration detection — warn the user explicitly: `"non-empty-intersection pair count {N} exceeds cap — analyzing top 20 by intersection size; {excluded_count} pairs skipped"`. Record this cap in the evidence report. The legacy 50-dependency threshold that formerly gated a separate Top-K pass is retired — the file-intersection prune does the bulk of the work and the cap is now a second-order safety limit, not a primary strategy.
+
+Report: "**Analyzing {pair_count} library pairs for integration patterns** (pruned from {N*(N-1)/2} via file-list intersection; {capped_count} after Top-K if applicable)**...**"
+
+### 2. Detect Co-Import Files
+
+**If `compose_mode` is true:**
+
+Instead of co-import grep, detect integrations from architecture document:
+
+1. Load `{composeModeRules}` for integration evidence format rules
+2. **If `{architecture_doc_path}` is null or not available:** Skip directly to the "If no architecture document available" fallback below
+3. Load the architecture document from `{architecture_doc_path}`
+4. **Prose-based co-mention analysis with precision guards (H2):**
+   - Use **word-boundary matching** when searching for skill names in the architecture document: `\b{skill_name}\b` (case-insensitive). This prevents substring false positives (e.g., `react` matching inside `reactive`).
+   - **Exclude non-body sections.** Detect H1 and H2 markdown headers (`^# ` and `^## `) and skip any paragraphs under headers that normalise to `introduction`, `overview`, `glossary`, `table of contents`, `references`, `appendix`, or `index`. Co-mentions inside headings themselves also do not qualify.
+   - **Require ≥2 qualifying paragraphs.** A pair `(A, B)` qualifies only when at least two distinct body paragraphs each contain word-boundary matches for both `A` and `B`. A single co-mention paragraph is insufficient evidence.
+   - Risks and rationale are documented in `{composeModeRules}` under "Compose-mode co-mention precision".
+5. For each detected integration pair:
+   - Load both skills' export lists and API signatures
+   - Compose an integration section following the format from `{composeModeRules}`
+   - Include VS feasibility verdict if a feasibility report matching the filename pattern defined in `src/shared/references/feasibility-report-schema.md` exists under `{forge_data_folder}/` (timestamped `feasibility-report-{project_slug}-{YYYYMMDD-HHmmss}.md` or the stable `feasibility-report-{project_slug}-latest.md` copy). Schema version `"1.0"` is required; see the schema for the full contract.
+   - Cite evidence from both skills: `[from skill: {skill_name}]`
+
+All integration evidence inherits confidence tiers from the source skills. Load and apply the full **Confidence Tier Inheritance** matrix from `{composeModeRules}` to compute the correct tier for each pair (covers T1+T1, T1+T1-low, T1-low+T1-low, T1+T2, T1-low+T2, T2+T2 cases). Apply the `[composed]` suffix to all confidence labels — e.g., `T1 [composed]`, `T1-low [composed, +T2 annotations]`.
+
+**VS verdict parsing (if feasibility report exists):** The feasibility report format is defined by the shared schema at `src/shared/references/feasibility-report-schema.md` (single source of truth; skf-verify-stack is the producer, this skill is the consumer). Follow the schema strictly:
+
+- Locate the report via the filename pattern in the schema: `{forge_data_folder}/feasibility-report-{project_slug}-{YYYYMMDD-HHmmss}.md` (or the stable `feasibility-report-{project_slug}-latest.md` copy next to it).
+- **Schema version guard:** Parse the report's YAML frontmatter and verify `schemaVersion == "1.0"`. If the field is missing or mismatched, HALT with an explicit error: `"feasibility-report schemaVersion mismatch: expected '1.0', got '{value}' — refusing to proceed"`. Do NOT attempt to interpret unknown versions.
+- Read `overallVerdict` from frontmatter (exactly one of `FEASIBLE|CONDITIONALLY_FEASIBLE|NOT_FEASIBLE`).
+- Parse the `## Integration Verdicts` markdown table for per-pair verdicts (exactly one of `Verified|Plausible|Risky|Blocked`). Any unknown verdict token is a hard error per the schema — do not silently drop or map.
+- For each architecture-detected pair, include `VS overall: {overallVerdict}` and `VS pair: {verdict}` in the integration evidence per the format in `{composeModeRules}`. VS verdicts do not apply to inferred integrations since the VS report operates on architecture-described interactions only. Additionally, flag any pairs where VS reported `Risky` or `Blocked` by appending a `[VS: Risky]` or `[VS: Blocked]` warning annotation to the integration entry.
+
+If no architecture document available:
+- Infer potential integrations from skills sharing the same `language` field or sharing domain keywords in their SKILL.md descriptions (use the `usage_patterns` and `exports` fields from `per_library_extractions[]` built in step-04, or reload SKILL.md from the version-aware path: use `skill_package_path` from step-02, or resolve via `{skills_output_folder}/{skill_dir}/active/{skill_dir}/SKILL.md` — see `knowledge/version-paths.md`)
+- Mark inferred integrations: `[inferred from shared domain]` — use this suffix instead of `[composed]` for inferred integrations
+- Inferred integrations qualify automatically — no file-count threshold applies
+
+Skip to section 3 (Classify Integration Types) with the compose-mode pairs.
+
+**If not compose_mode:**
+
+For each library pair (A, B):
+
+**Launch a subprocess** that greps across all source files to find files importing BOTH library A and library B. Return only file paths and import line numbers.
+
+**Subprocess resolution:** Use the Grep tool (Claude Code), built-in search (Cursor), or `grep`/`rg` (CLI). See `knowledge/tool-resolution.md`.
+
+**Subprocess returns:** `{pair: [A, B], co_import_files: [{path, line_A, line_B}], count: N}`
+
+**Note on file-list intersection:** per §1, the intersection has already been computed and the pair's `intersection_files` set is known. The grep below runs against that set only, not the whole source tree. If a subprocess is entirely unavailable, the intersection itself is the integration evidence — count the intersection files against the 2-file threshold below without the grep. The intersection is mandatory first-pass work, not a fallback.
+
+**Threshold:** A pair must have 2+ co-import files to qualify as an integration pattern (single file co-imports may be incidental).
+
+**CCC Semantic Augmentation (Forge+ and Deep with ccc):**
+
+If `tools.ccc` is true AND `ccc_index.status` is `"fresh"` or `"stale"` in forge-tier.yaml, augment co-import detection with semantic search (max 1 query per library pair):
+
+For each library pair with **0 or 1 co-import files** (below the 2-file threshold — S9, symmetric to give the 0-hit case the same chance as the 1-hit case), run `ccc_bridge.search("{libA} {libB}", source_root, top_k=10)` to find files where the two libraries interact semantically — even without explicit import co-location. If CCC returns additional files where both libraries appear, add them to the pair's co-import candidate list and re-evaluate against the 2-file threshold.
+
+**CCC precision guard for 1-file pairs (H3):** When a CCC hit would elevate a 1-file pair to qualifying status, run a post-hoc verification on that file: re-grep the file and confirm it contains explicit import statements for **both** libraries (per the ecosystem import patterns from `references/manifest-patterns.md`). If either import is missing (e.g., one library is only name-dropped in a comment or string), drop the CCC-added file from the candidate list. Only pairs with ≥2 files that each contain explicit imports for both libraries qualify. Log rejected CCC candidates in workflow state for the evidence report.
+
+**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{libA} {libB}" --path {source_root} --top 10` (CLI). See `knowledge/tool-resolution.md`.
+
+For pairs that already qualify (2+ files), CCC is not needed for detection — but the CCC results may surface additional integration files for richer classification in section 3.
+
+CCC failures: skip augmentation silently, proceed with grep-only results.
+
+### 3. Classify Integration Types
+
+Load `{integrationPatterns}` for classification rules.
+
+For each qualifying pair, analyze to classify the integration type (**in compose-mode**: all architecture-document-detected pairs qualify automatically — the 2+ co-import file threshold applies only in code-mode; **in code-mode**: pair must have 2+ co-import files):
+
+- **Type 1: Middleware Chain** — Sequential function calls piping output between libraries
+- **Type 2: Shared Types** — Type definitions exchanged between libraries
+- **Type 3: Configuration Bridge** — One library configuring or initializing another
+- **Type 4: Event Handler** — Event patterns crossing library boundaries
+- **Type 5: Adapter/Wrapper** — Thin wrapper connecting library interfaces
+- **Type 6: State Sharing** — Shared state stores or context providers
+
+For each detected integration:
+- Identify the top 3 files demonstrating the pattern
+- Extract a brief description of how the libraries connect
+- **Assign confidence (M1/M3) — derive from per-library tiers + detection-method qualifier (NOT from AST):** integration detection here is grep + co-import (optionally CCC-augmented), never AST. The integration's confidence is the **weaker** of the two libraries' tiers from `per_library_extractions[]` (tie-break: T1-low > T1, T2 > T1-low, T3 > T2 — never overstate). Then append a detection-method qualifier:
+  - `grep-co-import` — the pair qualified via direct co-import grep (the default).
+  - `ccc-augmented` — the pair qualified only after CCC semantic search elevated it (per §2 CCC augmentation), and the post-hoc import verification (H3) confirmed both imports.
+  - `architecture-co-mention` — compose-mode pair qualified via word-boundary co-mention in the architecture document (per §2 H2 guards).
+  - `inferred-shared-domain` — compose-mode pair without an architecture document, inferred from shared `language` or domain keywords.
+  - Render as `{tier} ({qualifier})` — e.g., `T1-low (grep-co-import)`, `T1 (ccc-augmented)`, `T1-low (architecture-co-mention) [composed]`. The `[composed]`/`[inferred from shared domain]` suffix from `compose-mode-rules.md` is appended after the qualifier in compose-mode.
+
+### 4. Build Integration Graph
+
+Assemble the integration graph:
+- **Nodes:** Confirmed libraries (with extraction data from step 04)
+- **Edges:** Detected integration pairs with type, file count, and description
+- Identify **hub libraries** (connected to 3+ other libraries)
+- Identify **cross-cutting patterns** (patterns spanning 3+ libraries)
+
+### 5. Display Integration Summary
+
+**If integrations detected:**
+
+"**Integration detection complete.**
+
+**Integration graph:** {lib_count} libraries, {pair_count} integration pairs
+
+**Hub libraries** (connected to 3+ others):
+{For each hub:} - **{library}** — integrates with {partner_list}
+
+**Detected integrations:**
+| Library A | Library B | Type | Co-import Files | Confidence |
+|-----------|-----------|------|-----------------|------------|
+| {name} | {name} | {type} | {count} | {tier} |
+
+{If cross-cutting patterns:}
+**Cross-cutting patterns:**
+- {description spanning 3+ libraries}
+
+**Proceeding to stack compilation...**"
+
+**If no integrations detected:**
+
+"**No co-import integration patterns detected** between confirmed libraries.
+
+The libraries in this project appear to operate independently. The stack skill will contain library summaries without an integration layer.
+
+**Proceeding to stack compilation...**"
+
+### 6. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+