bmad-module-skill-forge 1.4.0 → 1.5.0

package/src/skf-create-stack-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skf-create-stack-skill
-description: Consolidated project stack skill with integration patterns — code-mode (analyzes manifests) or compose-mode (synthesizes from existing skills + architecture doc). Use when the user requests to "create a stack skill."
+description: Consolidated project stack skill with integration patterns — code-mode (analyzes manifests) or compose-mode (synthesizes from existing skills + architecture doc). Use when the user requests to "create a stack skill", "forge a stack", or "stack this project".
 ---
 
 # Create Stack Skill
@@ -9,46 +9,80 @@ description: Consolidated project stack skill with integration patterns — code
 
 Produces a consolidated stack skill documenting how libraries connect. **Code-mode** analyzes dependency manifests and co-import patterns from actual source code. **Compose-mode** synthesizes from pre-generated individual skills and architecture documents when no codebase exists yet. Every finding must trace to actual code with file:line citations; in compose-mode, inferred integrations are permitted but must be labeled `[inferred from shared domain]`.
 
+## Conventions
+
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
 ## Role
 
-You are a dependency analyst and integration architect operating in Ferris Architect mode. You bring expertise in dependency analysis, cross-library integration patterns, and compositional architecture, while the user brings their project knowledge and scope preferences.
+You are a dependency analyst and integration architect. You bring expertise in dependency analysis, cross-library integration patterns, and compositional architecture, while the user brings their project knowledge and scope preferences.
 
 ## Workflow Rules
 
 These rules apply to every step in this workflow:
 
 - Zero hallucination — all extracted content must trace to actual source code (compose-mode inferences must be labeled)
-- Read each step file completely before taking any action
-- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
 - Only load one step file at a time — never preload future steps
 - If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
 - Always communicate in `{communication_language}`
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
-- **Workflow state contract — `workflow_warnings[]` accumulator (M4):** every step that emits a warning ("log a warning", "record in workflow state for the evidence report", "Warning: ...", etc.) MUST append a structured entry to a single in-memory list named `workflow_warnings[]`. Each entry has the shape `{step: "step-NN", severity: "info|warn|error", code: "<short-slug>", message: "<human text>", context: {<optional fields>}}`. Step-07 surfaces these in `evidence-report.md`; step-08 may add validation findings; step-09 §5 reads the accumulated list and renders the user-facing "Warnings" section. Do not invent a per-step warning channel — there is exactly one accumulator for the whole workflow.
+- Warnings use a single accumulator — see `## Workflow state contract` below for shape and surfacing.
+
+## Workflow state contract
+
+Every step that emits a warning ("log a warning", "record in workflow state for the evidence report", "Warning: ...", etc.) appends a structured entry to a single in-memory list named `workflow_warnings[]`. Each entry has the shape `{step: "step-NN", severity: "info|warn|error", code: "<short-slug>", message: "<human text>", context: {<optional fields>}}`. Step 7 surfaces these in `evidence-report.md`; step 8 may add validation findings; step 9 §5 reads the accumulated list and renders the user-facing "Warnings" section. There is exactly one accumulator for the whole workflow — do not invent per-step channels.
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Initialize & Mode Detection | steps-c/step-01-init.md | No (confirm) |
-| 2 | Detect Manifests | steps-c/step-02-detect-manifests.md | Yes |
-| 3 | Rank & Confirm Libraries | steps-c/step-03-rank-and-confirm.md | No (confirm) |
-| 4 | Parallel Extract | steps-c/step-04-parallel-extract.md | Yes |
-| 5 | Detect Integrations | steps-c/step-05-detect-integrations.md | Yes |
-| 6 | Compile Stack | steps-c/step-06-compile-stack.md | No (review) |
-| 7 | Generate Output | steps-c/step-07-generate-output.md | Yes |
-| 8 | Validate | steps-c/step-08-validate.md | Yes |
-| 9 | Report | steps-c/step-09-report.md | Yes |
-| 10 | Workflow Health Check | steps-c/step-10-health-check.md | Yes |
+| 1 | Initialize & Mode Detection | references/init.md | No (confirm) |
+| 2 | Detect Manifests | references/detect-manifests.md | Yes |
+| 3 | Rank & Confirm Libraries | references/rank-and-confirm.md | No (confirm) |
+| 4 | Parallel Extract | references/parallel-extract.md | Yes |
+| 5 | Detect Integrations | references/detect-integrations.md | Yes |
+| 6 | Compile Stack | references/compile-stack.md | No (review) |
+| 7 | Generate Output | references/generate-output.md | Yes |
+| 8 | Validate | references/validate.md | Yes |
+| 9 | Report | references/report.md | Yes |
+| 10 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
 | **Inputs** | project_path [required], mode (code/compose) [auto-detected] |
-| **Gates** | step-03: Confirm Gate [C] | step-06: Review Gate [C] |
+| **Gates** | step 3: Confirm Gate [C] | step 6: Review Gate [C] |
 | **Outputs** | SKILL.md (stack), context-snippet.md, metadata.json |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning              | Raised by                                                                                  |
+| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
+| 0    | success              | step 10 (terminal handoff to shared health-check)                                          |
+| 2    | input-missing / input-invalid | step 1 §0 (`config.yaml` missing or malformed); step 2 §2 headless cannot proceed without manifests (S2); step 4 §3 all extractions failed (B7); step 5 §2 feasibility-report `schemaVersion` mismatch; compose-mode-rules `schemaVersion` mismatch |
+| 3    | resolution-failure   | step 1 §1 (`forge-tier.yaml` missing); step 2 §0 compose-mode skill resolution corruption (manifest + symlink both fail); step 2 §0 compose-mode zero qualifying skills (S1/S3) |
+| 4    | write-failure        | step 7 §1 stage-dir / commit-dir failure; step 7 §1 group-dir collision when an existing non-stack skill occupies the target path |
+| 5    | overwrite-cancelled  | step 7 collision when the user declines to replace an existing stack package |
+| 6    | user-cancelled       | any interactive menu in step 3 / step 6 (user selected `[X]` Cancel and exit) |
+
+## Result Contract (Headless)
+
+When `{headless_mode}` is true, step 9 emits a single-line JSON envelope on **stdout** before chaining to step 10, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+
+```
+SKF_STACK_RESULT_JSON: {"status":"success|error","skill_package":"…|null","skill_name":"…","stack_libraries":["…"],"mode":"code|compose","exit_code":0,"halt_reason":null}
+```
+
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `skill_package` is the absolute path to the committed stack-skill directory (or `null` on error before commit). `skill_name` is the stack skill's published name (e.g. `{project_name}-stack`). `stack_libraries` is the array of library names included in the stack (constituent skill names in compose-mode, dependency names in code-mode). `mode` is `"code"` or `"compose"` per the run's resolved mode. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"forge-tier-missing"`, `"config-missing"`, `"no-manifests"`, `"all-extractions-failed"`, `"schema-version-mismatch"`, `"resolution-failure"`, `"write-failure"`, `"overwrite-cancelled"`, `"user-cancelled"`. `exit_code` matches the table above.
 
 ## On Activation
 
@@ -61,4 +95,29 @@ These rules apply to every step in this workflow:
    3. **Preferences fallback.** Otherwise, read `headless_mode` from `{sidecar_path}/preferences.yaml` (`true` or `false`).
    4. **Default:** `false`.
 
-3. Load, read the full file, and then execute `./steps-c/step-01-init.md` to begin the workflow.
+3. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+
+   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the five scalars, if the merged value is empty or absent, use the bundled default:
+
+   - `{stackSkillTemplatePath}` ← `workflow.stack_skill_template_path` if non-empty, else `assets/stack-skill-template.md`
+   - `{integrationPatternsPath}` ← `workflow.integration_patterns_path` if non-empty, else `references/integration-patterns.md`
+   - `{manifestPatternsPath}` ← `workflow.manifest_patterns_path` if non-empty, else `references/manifest-patterns.md`
+   - `{composeModeRulesPath}` ← `workflow.compose_mode_rules_path` if non-empty, else `references/compose-mode-rules.md`
+   - `{provenanceMapSchemaPath}` ← `workflow.provenance_map_schema_path` if non-empty, else `assets/provenance-map-schema.md`
+
+   Stash all five as workflow-context variables. Stage files reference `{stackSkillTemplatePath}` / `{integrationPatternsPath}` / `{manifestPatternsPath}` / `{composeModeRulesPath}` / `{provenanceMapSchemaPath}` directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default; non-empty values let orgs swap in house-style copies without forking the skill.
+
+4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-create-stack-skill/assets/provenance-map-schema.md

@@ -0,0 +1,102 @@
+---
+type: static-reference
+---
+
+# provenance-map.json Schema
+
+Canonical schema templates for the workspace `provenance-map.json` artifact written in step 7 §7. Two variants exist — choose by the run's resolved mode:
+
+- **code-mode** — when the workflow analyzed a real codebase with manifest files and AST-extracted exports
+- **compose-mode** — when the workflow synthesized a stack from pre-generated constituent skills + an architecture document
+
+Both variants share the top-level `provenance_version`, `skill_name`, `skill_type`, `generated_at`, `entries[]`, and `integrations[]` shape. They differ in source-anchor fields (`source_repo` / `source_commit` / `source_ref`), in `entries[].extraction_method` values, in `integrations[].detection_method` values, and in compose-mode's additional `constituents[]` array which enables drift detection via metadata-hash comparison.
+
+> **Note:** Per-export entries use the same schema as single skills (see `skill-sections.md`), with `source_library` identifying the originating library. In compose-mode, `constituents[]` enables audit to detect constituent drift via metadata hash comparison.
+
+## Code-mode variant
+
+Used when the workflow ran in code-mode against an actual codebase. `source_repo` and `source_commit` capture the upstream anchor(s); `entries[].extraction_method` records how each export was discovered (`ast_bridge`, `source_reading`, or `qmd_bridge`). `integrations[].detection_method` is `"co-import grep"` because integration pairs are confirmed by co-import file evidence.
+
+```json
+{
+  "provenance_version": "2.0",
+  "skill_name": "{project_name}-stack",
+  "skill_type": "stack",
+  "source_repo": ["{repo_url_1}", "{repo_url_2}"],
+  "source_commit": {"{repo_1}": "{hash_1}", "{repo_2}": "{hash_2}"},
+  "generated_at": "{ISO-8601}",
+  "entries": [
+    {
+      "export_name": "{name}",
+      "export_type": "{type}",
+      "source_library": "{library-name}",
+      "params": [],
+      "return_type": "{type}",
+      "source_file": "{file}",
+      "source_line": 0,
+      "confidence": "T1|T1-low|T2",
+      "extraction_method": "ast_bridge|source_reading|qmd_bridge",
+      "signature_source": "T1|T2|T3"
+    }
+  ],
+  "integrations": [
+    {
+      "libraries": ["{libA}", "{libB}"],
+      "pattern_type": "{type}",
+      "detection_method": "co-import grep",
+      "co_import_files": [{"file": "{path}", "line": 0}],
+      "confidence": "T1|T2"
+    }
+  ]
+}
+```
+
+## Compose-mode variant
+
+Used when the workflow ran in compose-mode against pre-generated constituent skills. Source-anchor fields (`source_repo`, `source_commit`, `source_ref`) are `null` because there is no codebase to anchor against — provenance traces back to the constituent skills instead, captured in the `constituents[]` array. Each entry's `extraction_method` is `"compose-from-skill"`; integrations have `detection_method` of `"architecture_co_mention"` (named in the architecture doc) or `"inferred_from_shared_domain"` (synthesized inference, must carry T2/T3 confidence).
+
+```json
+{
+  "provenance_version": "2.0",
+  "skill_name": "{project_name}-stack",
+  "skill_type": "stack",
+  "source_repo": null,
+  "source_commit": null,
+  "source_ref": null,
+  "generated_at": "{ISO-8601}",
+  "entries": [
+    {
+      "export_name": "{name}",
+      "export_type": "{type}",
+      "source_library": "{library-name}",
+      "params": [],
+      "return_type": "{type}",
+      "source_file": "{from constituent skill}",
+      "source_line": 0,
+      "confidence": "T1|T1-low|T2",
+      "extraction_method": "compose-from-skill",
+      "signature_source": "T1|T2|T3"
+    }
+  ],
+  "integrations": [
+    {
+      "libraries": ["{libA}", "{libB}"],
+      "pattern_type": "{type}",
+      "detection_method": "architecture_co_mention|inferred_from_shared_domain",
+      "co_import_files": [],
+      "confidence": "T2|T3"
+    }
+  ],
+  "constituents": [
+    {
+      "skill_name": "{constituent-skill-name}",
+      "skill_path": "skills/{skill-dir}/",
+      "version": "{version from constituent metadata.json}",
+      "composed_at": "{ISO-8601}",
+      "metadata_hash": "sha256:{hash of constituent metadata.json}"
+    }
+  ]
+}
+```
+
+**Use the `metadata_hash` value already stored in workflow state during step 2 (S13) — do NOT re-read and re-hash at step 7 time. The stored hash captures the state as it was at manifest-detection time, which is the correct provenance anchor.**

package/src/skf-create-stack-skill/assets/stack-skill-template.md

@@ -32,7 +32,7 @@ description: >
 
 | Library | Imports | Key Exports | Confidence | Reference |
 |---------|---------|-------------|------------|-----------|
-| {name} | {count} | {top_exports} | {tier} | [ref](./references/{name}.md) |
+| {name} | {count} | {top_exports} | {tier} | [ref](references/{name}.md) |
 
 ## Per-Library Summaries
 

package/src/skf-create-stack-skill/customize.toml

@@ -0,0 +1,46 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-create-stack-skill.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (uv probe, config load).
+# Overrides append. Use for org-wide pre-flight checks (auth, network,
+# compliance) that must precede any stack compilation work.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (house style, naming conventions, integration-pattern guardrails).
+# Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Stack skills must cite their constituent libraries."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/stack-style.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Optional asset overrides ---
+#
+# Lift the canonical asset paths so orgs can substitute house-style copies
+# without forking the skill. Empty string = use the bundled default.
+
+stack_skill_template_path = ""
+integration_patterns_path = ""
+manifest_patterns_path = ""
+compose_mode_rules_path = ""
+provenance_map_schema_path = ""

package/src/skf-create-stack-skill/{steps-c/step-06-compile-stack.md → references/compile-stack.md}

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-07-generate-output.md'
+nextStepFile: 'generate-output.md'
 stackSkillTemplate: 'assets/stack-skill-template.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
+
 # Step 6: Compile Stack Skill
 
 ## STEP GOAL:
@@ -17,8 +19,6 @@ Assemble the main SKILL.md by combining per-library extractions with the integra
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Load Template Structure
 
 Load `{stackSkillTemplate}` and prepare SKILL.md section structure.
@@ -74,7 +74,7 @@ For each confirmed library (ordered by integration connectivity, then import cou
 - Key exports used in this project
 - Usage patterns from extraction
 - Confidence tier label
-- Link to reference file: `./references/{library}.md`
+- Link to reference file: `references/{library}.md`
 
 ### 5. Compile Project Conventions
 
@@ -117,7 +117,7 @@ Create the reference index table:
 
 ### 8. Present MENU OPTIONS
 
-Display: **Select:** [C] Continue to Output Generation
+Display: **Select:** [C] Continue to Output Generation | [X] Cancel and exit
 
 #### EXECUTION RULES:
 
@@ -128,5 +128,6 @@ Display: **Select:** [C] Continue to Output Generation
 #### Menu Handling Logic:
 
 - IF C: Store skill_content, 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 feedback, adjust compilation, redisplay preview, then [Redisplay Menu Options](#8-present-menu-options)
 

package/src/skf-create-stack-skill/references/compose-mode-rules.md

@@ -1,3 +1,5 @@
+<!-- Config: communicate in {communication_language}. -->
+
 # Compose Mode Rules
 
 Rules for synthesizing a stack skill from pre-generated individual skills and an architecture document, without requiring a codebase.
@@ -19,7 +21,7 @@ Skills use version-nested directories — see `knowledge/version-paths.md` for t
 
 ## Compose-mode Co-mention Precision
 
-Prose co-mention detection is heuristic — it can only provide `Plausible`-class evidence (compared to code-mode's co-imports, which are literal). To reduce false positives the matcher in step-05 §2 applies three guards:
+Prose co-mention detection is heuristic — it can only provide `Plausible`-class evidence (compared to code-mode's co-imports, which are literal). To reduce false positives the matcher in step 5 §2 applies three guards:
 
 1. **Word-boundary matching** (`\b{skill_name}\b`, case-insensitive). Substring matches are rejected (no `react` inside `reactive`).
 2. **Section filtering.** Paragraphs under H1/H2 headers that normalise to `introduction`, `overview`, `glossary`, `table of contents`, `references`, `appendix`, or `index` are excluded — they typically enumerate all libraries without describing integration. Headings themselves are also excluded as co-mention sources.

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

@@ -1,9 +1,12 @@
 ---
-nextStepFile: './step-06-compile-stack.md'
+nextStepFile: 'compile-stack.md'
 integrationPatterns: 'references/integration-patterns.md'
 composeModeRules: 'references/compose-mode-rules.md'
+pairIntersectScript: '{project-root}/src/shared/scripts/skf-pair-intersect.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 5: Detect Integrations
 
 ## STEP GOAL:
@@ -18,17 +21,35 @@ Analyze co-import patterns between confirmed libraries to identify integration p
 
 ## 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.
+From `confirmed_dependencies`, conceptually you have N*(N-1)/2 unordered pairs. Rather than enumerating and grep-testing each one, prune the matrix via a deterministic **file-list intersection fast path** (MANDATORY first pass, all N): pairs whose per-library file lists do not overlap cannot be integration candidates by construction — drop them. Subsequent grep passes (§2) 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.
+
+**Compute the intersection deterministically via the shared script:**
+
+1. **Build the libraries JSON** from the per-library file enumeration recorded by step 3 import-count extraction. Skip libraries where step 04 reported extraction failure. Shape:
+   ```json
+   [
+     {"name": "<library-name>", "files": ["<rel-path-forward-slash>", ...]},
+     ...
+   ]
+   ```
+2. **Invoke the script** via stdin (or a temp file under `{forge_data_folder}/` if stdin piping is unavailable):
+   ```bash
+   uv run {pairIntersectScript} intersect --libraries -
+   ```
+   piping the libraries JSON on stdin. The script emits:
+   ```json
+   {
+     "pairs": [{"a": "<lib>", "b": "<lib>", "intersection_count": N, "files": [...]}, ...],
+     "truncated": <bool>,
+     "total_pairs": <int>
+   }
+   ```
+   `pairs[]` is sorted by `intersection_count` DESC, then `(a, b)` ASC for stable ordering. Default Top-K cap is **20** (matches S7 below); pass `--top-k N` to override.
+3. **Parse the JSON result** and use `pairs[]` as the qualifying-pair set for §2 onward. The `intersection_count` is the candidate file count for the §2 2-file threshold pre-grep; `files[]` is the grep-scope for that pair.
+
+**Top-K cap (S7, 20):** If the script's response has `truncated: true`, more pairs than the cap had non-empty intersections. Surface a user-visible warning composed as: `"non-empty-intersection pair count {total_pairs} exceeds cap — analyzing top 20 by intersection size; {total_pairs - 20} pairs skipped"`. Record this cap in the evidence report. (Tie-break by intersection size is what the script sorts on; if you need to override the cap intentionally, pass `--top-k N` and document the rationale.) 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)**...**"
 
@@ -63,7 +84,7 @@ All integration evidence inherits confidence tiers from the source skills. Load
 - 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`)
+- 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 4, or reload SKILL.md from the version-aware path: use `skill_package_path` from step 2, 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
 

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

@@ -1,8 +1,11 @@
 ---
-nextStepFile: './step-03-rank-and-confirm.md'
+nextStepFile: 'rank-and-confirm.md'
 manifestPatterns: 'references/manifest-patterns.md'
+scanManifestsScript: '{project-root}/src/shared/scripts/skf-scan-manifests.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2: Detect Manifests
 
 ## STEP GOAL:
@@ -17,8 +20,6 @@ Scan the project root for dependency manifest files, parse each to extract depen
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 0. Check Compose Mode
 
 **If `compose_mode` is true AND `explicit_deps` was provided in step 01:**
@@ -57,7 +58,7 @@ For each skill found:
 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. **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.
+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 2 read and step 7 write is captured.
 6. Store as `raw_dependencies` with source: "existing_skill"
 
 Display:
@@ -85,20 +86,33 @@ Store the explicit list as `raw_dependencies` and skip to [Display Detection Sum
 
 **If no explicit list:** Continue to section 2.
 
-### 2. Scan for Manifest Files
+### 2. Scan and Parse Manifests
+
+Invoke the deterministic manifest scanner — it walks the project root, parses every recognised manifest, dedupes the production dep set, and flags monorepo layout:
+
+```bash
+uv run {scanManifestsScript} scan {scan_root}
+```
 
-Load `{manifestPatterns}` for supported ecosystem detection patterns.
+Where `{scan_root}` is the project root path. Load `{manifestPatterns}` for the ecosystem reference table that documents supported filenames, dependency keys, and normalisation rules; the script implements exactly that table (npm/pnpm/yarn, python pip/poetry/pdm, rust cargo, go modules, java/kotlin maven + gradle, ruby bundler, composer, swift package manager). Exclusion patterns (`node_modules/`, `.venv/`, `vendor/`, `dist/`, `build/`, `target/`, `.git/`, hidden dirs) are applied internally.
 
-Scan the project root (depth 0-1) for manifest files, **excluding directories listed in the Scan Exclusion Patterns section of `{manifestPatterns}`**:
+Parse the JSON output — shape:
 
-- Search for each supported manifest filename
-- Record: file path, ecosystem type, file size
-- **Apply exclusion patterns** from `{manifestPatterns}` — skip `node_modules/`, `.venv/`, `vendor/`, `dist/`, `build/`, `target/`, `.git/`, and all hidden directories when globbing
-- Note any unusual structures (monorepo with multiple manifests, workspace configurations)
+```
+{
+  "manifests": [
+    {"path": "<rel-from-root>", "ecosystem": "<name>", "deps": [{"name": "...", "version": "..."}]},
+    ...
+  ],
+  "total_unique": N,
+  "monorepo": <bool>,
+  "warnings": ["..."]   // optional, only if any parse warning fired
+}
+```
 
-**If no manifest files found:**
+If `manifests` is empty:
 
-**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.
+**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 2","reason":"no manifests found, headless cannot prompt"}` on stderr and exit non-zero. Headless mode cannot proceed without an explicit dependency list.
 
 **Interactive mode:**
 
@@ -115,21 +129,7 @@ Searched for: package.json, requirements.txt, Cargo.toml, go.mod, pom.xml, build
 
 STOP — wait for user response.
 
-### 3. Parse Each Manifest
-
-For each discovered manifest file:
-
-1. Read the file contents
-2. Extract dependency names and version constraints using ecosystem-specific parsing:
-   - JSON manifests: parse dependencies/devDependencies keys
-   - TOML manifests: parse [dependencies] sections
-   - Text manifests: parse line-by-line (name==version or name>=version)
-   - XML manifests: parse dependency elements
-   - Gradle: parse implementation/api/compile declarations
-3. Categorize: runtime vs dev-only
-4. Normalize dependency names across ecosystems
-
-Deduplicate dependencies found across multiple manifests.
+Otherwise, store the parsed `manifests[]` and `total_unique` as `raw_dependencies` (dedup is already applied by the scanner), surface any `warnings[]` to the user as parse-quality notes, and inspect the `monorepo` flag: if `true`, mention the monorepo layout in the detection summary so the user can decide whether to scope the ranking to a specific package or proceed across all manifests.
 
 ### 4. Display Detection Summary