bmad-module-skill-forge 1.4.1 → 1.5.1

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,14 @@
 ---
-nextStepFile: './step-06-compile-stack.md'
+nextStepFile: 'compile-stack.md'
 integrationPatterns: 'references/integration-patterns.md'
 composeModeRules: 'references/compose-mode-rules.md'
+pairIntersectProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-pair-intersect.py'
+  - '{project-root}/src/shared/scripts/skf-pair-intersect.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 5: Detect Integrations
 
 ## STEP GOAL:
@@ -18,17 +23,38 @@ 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):
+
+   **Resolve `{pairIntersectHelper}`** from `{pairIntersectProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+   ```bash
+   uv run {pairIntersectHelper} 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 +89,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,13 @@
 ---
-nextStepFile: './step-03-rank-and-confirm.md'
+nextStepFile: 'rank-and-confirm.md'
 manifestPatterns: 'references/manifest-patterns.md'
+scanManifestsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-scan-manifests.py'
+  - '{project-root}/src/shared/scripts/skf-scan-manifests.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2: Detect Manifests
 
 ## STEP GOAL:
@@ -17,8 +22,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 +60,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 +88,35 @@ 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:
+
+**Resolve `{scanManifestsHelper}`** from `{scanManifestsProbeOrder}`; first existing path wins. HALT if no candidate exists.
 
-Load `{manifestPatterns}` for supported ecosystem detection patterns.
+```bash
+uv run {scanManifestsHelper} scan {scan_root}
+```
 
-Scan the project root (depth 0-1) for manifest files, **excluding directories listed in the Scan Exclusion Patterns section of `{manifestPatterns}`**:
+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.
 
-- 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)
+Parse the JSON output — shape:
 
-**If no manifest files found:**
+```
+{
+  "manifests": [
+    {"path": "<rel-from-root>", "ecosystem": "<name>", "deps": [{"name": "...", "version": "..."}]},
+    ...
+  ],
+  "total_unique": N,
+  "monorepo": <bool>,
+  "warnings": ["..."]   // optional, only if any parse warning fired
+}
+```
 
-**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.
+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 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 +133,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
 

package/src/skf-create-stack-skill/{steps-c/step-07-generate-output.md → references/generate-output.md}

@@ -1,6 +1,7 @@
 ---
-nextStepFile: './step-08-validate.md'
+nextStepFile: 'validate.md'
 stackSkillTemplate: 'assets/stack-skill-template.md'
+provenanceMapSchemaPath: 'assets/provenance-map-schema.md'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves — stage/commit/flip-link/write below
@@ -10,6 +11,8 @@ atomicWriteProbeOrder:
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
+<!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
+
 # Step 7: Generate Output Files
 
 ## STEP GOAL:
@@ -24,8 +27,6 @@ Write all deliverable and workspace artifact files to their target directories.
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Resolve Paths and Stage Target Directory
 
 Resolve `{version}` from the primary library version or default to `1.0.0` (see S11 in "Primary library" note below). The final artifact paths are:
@@ -40,7 +41,7 @@ Resolve `{version}` from the primary library version or default to `1.0.0` (see
 
 Where the skill name is `{project_name}-stack` and `{version}` is the semver version (with build metadata stripped per `knowledge/version-paths.md`).
 
-**Primary library definition (S11):** In code-mode, the primary library is the dependency with the highest import count from step-03; its `version` (from the manifest) becomes `{primary_library_version}`. In compose-mode, use the highest semver across constituent skill `metadata.json` files. If neither is available, fall back to `1.0.0`.
+**Primary library definition (S11):** In code-mode, the primary library is the dependency with the highest import count from step 3; its `version` (from the manifest) becomes `{primary_library_version}`. In compose-mode, use the highest semver across constituent skill `metadata.json` files. If neither is available, fall back to `1.0.0`.
 
 **Pre-flight: group-dir type check (S3):** If `{skills_output_folder}/{project_name}-stack/` already exists, probe `{skills_output_folder}/{project_name}-stack/active/{project_name}-stack/metadata.json`. If that metadata exists and `skill_type != "stack"`, HALT with:
 
@@ -74,7 +75,7 @@ mkdir -p {forge_version}
 python3 {atomicWriteHelper} commit-dir --rollback --target {skill_package}
 ```
 
-Then abort with a structured error contract (see B7): purge any `{forge_version}/*-tmp` staging artifacts, emit `{"status":"error","skill":"skf-create-stack-skill","stage":"step-07","reason":"<message>"}` on stderr, and halt the workflow.
+Then abort with a structured error contract (see B7): purge any `{forge_version}/*-tmp` staging artifacts, emit `{"status":"error","skill":"skf-create-stack-skill","stage":"step 7","reason":"<message>"}` on stderr, and halt the workflow.
 
 ### 2. Stage SKILL.md
 
@@ -136,7 +137,7 @@ Write `{skill_staging}/metadata.json`:
 Populate all fields from the metadata.json schema defined in `{stackSkillTemplate}`.
 
 **Tier fields:**
-- `forge_tier` — the run tier (Quick/Forge/Forge+/Deep) resolved in step-01.
+- `forge_tier` — the run tier (Quick/Forge/Forge+/Deep) resolved in step 1.
 - `confidence_tier` — the dominant T-code from `confidence_distribution`. Pick the tier with the highest count; resolve ties toward the weaker tier (T1-low > T1, T2 > T1-low, T3 > T2) so the reported value never overstates confidence. When `confidence_distribution` is empty (no libraries extracted), emit `"T1-low"` as the conservative default.
 
 ```json
@@ -191,87 +192,12 @@ If any workspace write fails, invoke the rollback contract from §1.
 
 **provenance-map.json:**
 
-**In code-mode:**
-```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"
-    }
-  ]
-}
-```
+Use the schema from `{provenanceMapSchemaPath}` — see that asset for the canonical templates and field definitions of both variants:
 
-**In compose-mode:**
-```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}"
-    }
-  ]
-}
-```
+- **In code-mode:** use the code-mode variant (`source_repo` / `source_commit` populated; `extraction_method` ∈ `ast_bridge|source_reading|qmd_bridge`; `detection_method = "co-import grep"`).
+- **In compose-mode:** use the compose-mode variant (source-anchor fields `null`; `extraction_method = "compose-from-skill"`; `detection_method ∈ "architecture_co_mention|inferred_from_shared_domain"`; includes the additional `constituents[]` array for drift detection).
 
-> **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. **Use the `metadata_hash` value already stored in workflow state during step-02 (S13) — do NOT re-read and re-hash at step-07 time. The stored hash captures the state as it was at manifest-detection time, which is the correct provenance anchor.**
+**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.**
 
 **evidence-report.md:**
 - Extraction summary per library

package/src/skf-create-stack-skill/{steps-c/step-10-health-check.md → references/health-check.md}

@@ -1,10 +1,12 @@
 ---
 # `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
+# (`{project-root}/_bmad/skf/` when installed, `src/` during development), NOT relative
 # to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 10: Workflow Health Check
 
 ## STEP GOAL:
@@ -13,7 +15,7 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step-09
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 9
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
 

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

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-02-detect-manifests.md'
+nextStepFile: 'detect-manifests.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1: Initialize
 
 ## STEP GOAL:
@@ -15,8 +17,6 @@ Load forge tier configuration, validate prerequisites, and prepare the stack ski
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 0. Validate Project Config
 
 Before anything else, load `{project-root}/_bmad/skf/config.yaml`. If the file is missing OR fails YAML parse OR lacks the required top-level keys (`project_name`, `output_folder`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`), HALT with:
@@ -29,6 +29,72 @@ Before anything else, load `{project-root}/_bmad/skf/config.yaml`. If the file i
 
 STOP — do not proceed.
 
+### 0b. Resume Check
+
+Before any further init work, check for an interrupted prior run.
+
+**Probe path.** Resolve `{resume_skill_name}` as `{project_name}-stack` (the same skill name used at step 7) and probe `{forge_data_folder}/{resume_skill_name}/in-progress.json`. (The file lives at the version-agnostic skill root so it can be found before `{version}` resolution.)
+
+**If no in-progress.json exists:** Continue to §1.
+
+**If in-progress.json exists:** Load and parse it. Read `last_completed_step` and `started_at` (ISO-8601 timestamp). Surface a soft gate:
+
+"**Resume previous run?**
+
+Found a previous in-progress run at `{forge_data_folder}/{resume_skill_name}/in-progress.json` from {started_at}, last completed at step {last_completed_step}.
+
+- **[C] Continue** (recommended) — resume from the next step after {last_completed_step}, restoring saved workflow state.
+- **[F] Fresh** — archive the existing in-progress.json (rename to `in-progress.{timestamp}.json`) and start over from step 1.
+- **[X] Cancel and exit** — leave the in-progress.json untouched and halt.
+
+Select [C/F/X]:"
+
+**Headless default:** `[C]` Continue.
+
+**On [C] Continue:**
+1. Restore workflow context from in-progress.json fields: `last_completed_step`, `workflow_state` (mode, tier, scope), and any accumulator fields (partial extractions, ranked libraries, integration pairs, compile-stack output) that the writing step persisted.
+2. Determine the resume target: the step file that runs immediately after `last_completed_step`.
+3. Jump directly to that step file by loading and executing it (skip the remaining §0b–§5 init substeps for this run).
+
+**On [F] Fresh:**
+1. Compute `{archive_timestamp}` as the current UTC time in `YYYYMMDDTHHMMSSZ` form.
+2. Rename `{forge_data_folder}/{resume_skill_name}/in-progress.json` → `{forge_data_folder}/{resume_skill_name}/in-progress.{archive_timestamp}.json`.
+3. Continue with §1 of this file as if no prior run existed.
+
+**On [X] Cancel and exit:** HARD HALT with exit code 6 (user-cancelled). Do NOT modify the in-progress.json. Emit the result envelope on stderr per the Result Contract in SKILL.md:
+
+```
+SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{resume_skill_name}","stack_libraries":[],"mode":null,"exit_code":6,"halt_reason":"user-cancelled"}
+```
+
+**in-progress.json schema (read side).** This PR wires only the READ side of the resume protocol. The WRITE side — each stage step persisting an updated in-progress.json after it completes — is deferred to a follow-up PR. When write-side wiring lands, each step writes the file via `skf-atomic-write.py write` at the end of its mandatory sequence with this shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "skill_name": "{project_name}-stack",
+  "started_at": "{ISO-8601 of step 1 start}",
+  "updated_at": "{ISO-8601 of most recent step completion}",
+  "last_completed_step": "step-NN",
+  "workflow_state": {
+    "mode": "code|compose",
+    "forge_tier": "Quick|Forge|Forge+|Deep",
+    "headless_mode": false,
+    "scope": {"explicit_deps": [], "scope_overrides": {}, "architecture_doc_path": null}
+  },
+  "accumulators": {
+    "manifests": [],
+    "ranked_libraries": [],
+    "extractions": {},
+    "integration_pairs": [],
+    "compiled_stack": null,
+    "workflow_warnings": []
+  }
+}
+```
+
+Until the write side is wired, in-progress.json will not naturally appear and §0b will fall through to §1 on every run. The resume gate is a no-op until that follow-up lands.
+
 ### 1. Load Forge Tier Configuration
 
 Load `{forgeTierFile}` from the Ferris sidecar.
@@ -60,7 +126,7 @@ Extract:
 **Tier-dependent tools:**
 - **Quick:** gh_bridge (source reading) — graceful degradation to local file reading if unavailable
 - **Forge:** ast_bridge (ast-grep structural analysis) — required for Forge tier
-- **Forge+:** ast_bridge + ccc_bridge (ccc semantic co-import augmentation) — ccc available for step-05
+- **Forge+:** ast_bridge + ccc_bridge (ccc semantic co-import augmentation) — ccc available for step 5
 - **Deep:** qmd_bridge (QMD temporal enrichment) — required for Deep tier
 
 See `knowledge/tool-resolution.md` for how each bridge name resolves to concrete tools per IDE environment.

package/src/skf-create-stack-skill/references/integration-patterns.md

@@ -1,3 +1,5 @@
+<!-- Config: communicate in {communication_language}. -->
+
 # Integration Pattern Detection Rules
 
 ## Co-Import Detection

package/src/skf-create-stack-skill/references/manifest-patterns.md

@@ -1,3 +1,5 @@
+<!-- Config: communicate in {communication_language}. -->
+
 # Manifest Detection Patterns
 
 ## Supported Ecosystems