bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-create-stack-skill/references/detect-manifests.md

@@ -1,9 +1,11 @@
 ---
 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'
+enumerateStackSkillsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-enumerate-stack-skills.py'
+  - '{project-root}/src/shared/scripts/skf-enumerate-stack-skills.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -26,7 +28,7 @@ Scan the project root for dependency manifest files, parse each to extract depen
 
 **If `compose_mode` is true AND `explicit_deps` was provided in step 01:**
 
-Use the explicit dependency list directly. Store the explicit list as `raw_dependencies` with `source: "explicit"` and skip to [Auto-Proceed to Next Step](#5-auto-proceed-to-next-step).
+Use the explicit dependency list directly. Store the explicit list as `raw_dependencies` with `source: "explicit"` and skip to [Auto-Proceed to Next Step](#4-auto-proceed-to-next-step).
 
 **If `compose_mode` is true AND `explicit_deps` was NOT provided:**
 
@@ -39,7 +41,11 @@ Discover skills in `{skills_output_folder}` using version-aware resolution — s
    **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.
+   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. Emit the result envelope on stderr per the Result Contract in SKILL.md, then STOP:
+
+   ```
+   SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":[],"mode":"compose","exit_code":3,"halt_reason":"resolution-failure"}
+   ```
 
    **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.
 
@@ -53,26 +59,33 @@ Discover skills in `{skills_output_folder}` using version-aware resolution — s
 
 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]."
+**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]." Then emit the result envelope on stderr per the Result Contract in SKILL.md, and STOP:
+
+```
+SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":[],"mode":"compose","exit_code":3,"halt_reason":"resolution-failure"}
+```
+
+**Deterministic metadata hashing (S13) — script-driven:** Do NOT compute `sha256` in-prompt (a model cannot reproduce a digest, so a hand-computed hash would false-diverge against step 4's script-computed hash). Invoke the same enumeration helper step 4 §0 uses to obtain every constituent's `metadata_hash` in one deterministic call:
+
+**Resolve `{enumerateStackSkillsHelper}`** from `{enumerateStackSkillsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+```bash
+uv run {enumerateStackSkillsHelper} enumerate {skills_output_folder}
+```
+
+Key the emitted `skills[].metadata_hash` (a `sha256:`-prefixed digest of the raw `metadata.json`, or `null` when no metadata.json is present) by `skills[].name` for use in rule 5 below. The script's `name` is the top-level subdirectory under `{skills_output_folder}` — i.e. the `skill_dir` captured in rule 3, not the metadata `name` — so join on `skill_dir`.
 
 For each skill found:
 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. **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.
+5. **Record the constituent metadata_hash (S13):** take this skill's `metadata_hash` from the enumerate-script inventory above (matched on `skill_dir`) and store it in workflow state alongside `skill_package_path`. The script is the single source of this hash — never hand-compute — so the step-4 drift check compares script-hash to script-hash and never false-positives on a model recomputation. 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:
-"**Loaded {N} existing skills as dependencies.**
-
-| Skill | Language | Tier | Exports | Source |
-|-------|----------|------|---------|--------|
-| {name} | {lang} | {tier} | {count} | {repo} |
-
-**Proceeding to scope confirmation...**"
+Report the `{N}` loaded skills — for each: name, language, confidence tier, export count, and source.
 
-Skip to [Auto-Proceed to Next Step](#5-auto-proceed-to-next-step) — the skills table above serves as the detection summary.
+Skip to [Auto-Proceed to Next Step](#4-auto-proceed-to-next-step) — this loaded-skills summary serves as the detection summary.
 
 **If not compose_mode:** Continue with section 1 (existing flow).
 
@@ -84,7 +97,7 @@ Skip to [Auto-Proceed to Next Step](#5-auto-proceed-to-next-step) — the skills
 
 **Dependencies:** {explicit_deps_count} libraries provided"
 
-Store the explicit list as `raw_dependencies` and skip to [Display Detection Summary](#4-display-detection-summary).
+Store the explicit list as `raw_dependencies` and skip to [Display Detection Summary](#3-display-detection-summary).
 
 **If no explicit list:** Continue to section 2.
 
@@ -98,7 +111,7 @@ Invoke the deterministic manifest scanner — it walks the project root, parses
 uv run {scanManifestsHelper} scan {scan_root}
 ```
 
-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.
+Where `{scan_root}` is the project root path. Load `{manifestPatternsPath}` 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.
 
 Parse the JSON output — shape:
 
@@ -116,7 +129,11 @@ Parse the JSON output — shape:
 
 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.
+**Headless auto-cancel (S2):** If `{headless_mode}` is true, do NOT wait for user input. Emit the result envelope on stderr per the Result Contract in SKILL.md and exit `2`. Headless mode cannot proceed without an explicit dependency list.
+
+```
+SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":[],"mode":"code","exit_code":2,"halt_reason":"no-manifests"}
+```
 
 **Interactive mode:**
 
@@ -135,21 +152,11 @@ STOP — wait for user response.
 
 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
-
-"**Manifest detection complete.**
-
-**Manifests found:** {count}
-{For each manifest:}
-- `{file_path}` ({ecosystem}) — {dep_count} dependencies
-
-**Total unique dependencies:** {total_count}
-- Runtime: {runtime_count}
-- Dev-only: {dev_count}
+### 3. Display Detection Summary
 
-**Proceeding to dependency ranking...**"
+Report the detected manifests (for each: path, ecosystem, dependency count) and the total unique dependency count split into runtime vs dev-only.
 
-### 5. Auto-Proceed to Next Step
+### 4. Auto-Proceed to Next Step
 
 Load, read the full file and then execute `{nextStepFile}`.
 

package/src/skf-create-stack-skill/references/generate-output.md

@@ -1,7 +1,5 @@
 ---
 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
@@ -49,7 +47,7 @@ Resolve `{version}` per S11 below — the primary library version in code-mode,
 
 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 3; its `version` (from the manifest) becomes `{primary_library_version}`, falling back to `1.0.0` if unavailable. In compose-mode, the stack carries its own release identity: default `{version}` to `1.0.0` (a stack-local scheme) — do NOT borrow the highest constituent semver. Constituent versions are preserved in `dependencies[]`, so no information is lost, and the package no longer reads as tracking whichever constituent happened to have the highest version. The `1.0.0` default applies only to a **genuinely new** stack — see the re-composition rule below.
+**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}`, falling back to `1.0.0` if unavailable. In compose-mode, the stack carries its own release identity: default `{version}` to `1.0.0` (a stack-local scheme) rather than borrowing the highest constituent semver. Constituent versions are preserved in `dependencies[]`, so no information is lost, and the stack's version does not track whichever constituent happens to have the highest version. The `1.0.0` default applies only to a **genuinely new** stack — see the re-composition rule below.
 
 **Re-composition versioning (S11, compose-mode):** When the S3 pre-flight resolves a `{prior_stack_version}` (re-composing a stack that already has a release line), continue that line instead of resetting — defaulting to `1.0.0` would publish a version *below* the existing release (e.g. `1.0.0` shadowing a prior `3.0.5`, a backward jump). Bump `{prior_stack_version}`:
 
@@ -62,7 +60,11 @@ Never emit a `{version}` ≤ `{prior_stack_version}`. Narrate the resolved versi
 
 "**Cannot proceed.** `{skills_output_folder}/{project_name}-stack/` exists but is not a stack skill (`skill_type={found_type}`). Rename the existing directory or choose a different `project_name` to avoid collision."
 
-Do NOT proceed to staging or commit.
+Do NOT proceed to staging or commit. Emit the result envelope on stderr per the Result Contract in SKILL.md and exit `4` (`stack_libraries` carries the confirmed library names; nothing was committed, so `skill_package` is `null`):
+
+```
+SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":["<confirmed-lib>", "..."],"mode":"{code|compose}","exit_code":4,"halt_reason":"write-failure"}
+```
 
 If that metadata exists and `skill_type == "stack"`, this run is a **re-composition**: capture its `version` as `{prior_stack_version}` and its `libraries` array as `{prior_libraries}` for the S11 re-composition rule above. If the group dir is absent — or exists but has no resolvable `active` stack metadata — treat this as a new stack and leave `{prior_stack_version}` unset.
 
@@ -92,7 +94,11 @@ 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 7","reason":"<message>"}` on stderr, and halt the workflow.
+Then abort (see B7): purge any `{forge_version}/*-tmp` staging artifacts, emit the result envelope on stderr per the Result Contract in SKILL.md, and halt the workflow. This is the single rollback exit shared by §7 (workspace-write failure) and §9 (commit-dir failure):
+
+```
+SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":["<confirmed-lib>", "..."],"mode":"{code|compose}","exit_code":4,"halt_reason":"write-failure"}
+```
 
 ### 2. Stage SKILL.md
 
@@ -102,20 +108,20 @@ Write the approved `skill_content` from step 06 to `{skill_staging}/SKILL.md` (r
 
 For each confirmed library, write `{skill_staging}/references/{library_name}.md`:
 
-Load structure from `{stackSkillTemplate}` references section:
+Load structure from `{stackSkillTemplatePath}` references section:
 - Library name, version from manifest (**in compose-mode**: version from source skill `metadata.json`)
 - Import count and file count (**in compose-mode**: export count from source skill metadata)
 - Key exports with signatures
 - Usage patterns with file:line citations (**in compose-mode**: usage patterns from source skill SKILL.md)
 - Confidence tier label
 
-**If the catalog was extracted** (large stack — step 06 §4 placed the `Library Reference Index` + `Per-Library Summaries` out of SKILL.md), also write `{skill_staging}/references/stack-catalog.md` using the structure in `{stackSkillTemplate}`, and confirm SKILL.md carries the inline pointer instead of the two sections. Small stacks keep the catalog inline and write no `stack-catalog.md`.
+**If the catalog was extracted** (large stack — step 06 §4 placed the `Library Reference Index` + `Per-Library Summaries` out of SKILL.md), also write `{skill_staging}/references/stack-catalog.md` using the structure in `{stackSkillTemplatePath}`, and confirm SKILL.md carries the inline pointer instead of the two sections. Small stacks keep the catalog inline and write no `stack-catalog.md`.
 
 ### 4. Stage Integration Pair Reference Files
 
 For each detected integration pair, write `{skill_staging}/references/integrations/{libraryA}-{libraryB}.md`:
 
-Load structure from `{stackSkillTemplate}` integrations section:
+Load structure from `{stackSkillTemplatePath}` integrations section:
 - Library pair and integration type
 - Co-import file count
 - Integration pattern description with file:line citations
@@ -131,7 +137,7 @@ Write `{skill_staging}/context-snippet.md`:
 Use the Vercel-aligned indexed format targeting **~80-120 tokens** (M2). Token estimation is heuristic — use `ceil(char_count / 4)` as the working approximation (the standard rule-of-thumb for English text in BPE-style tokenizers; precise counts differ per model). Compute against the rendered snippet body (excluding trailing newline).
 
 ```
-[{project_name}-stack v{version — per S11: code-mode primary_library_version or 1.0.0; compose-mode stack-local scheme — 1.0.0 for a new stack, or the bumped {prior_stack_version} on re-composition}]|root: skills/{project_name}-stack/
+[{project_name}-stack v{version — resolved in §1}]|root: skills/{project_name}-stack/
 |IMPORTANT: {project_name}-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
 |stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
 |integrations: {pattern-1}, {pattern-2}
@@ -151,52 +157,12 @@ If the snippet is still over budget after step 4, log a warning to workflow_warn
 
 ### 6. Stage metadata.json
 
-Write `{skill_staging}/metadata.json`:
-
-Populate all fields from the metadata.json schema defined in `{stackSkillTemplate}`.
+Write `{skill_staging}/metadata.json`, populating every field from the metadata.json schema in `{stackSkillTemplatePath}` (loaded in §3) — that template is the single schema source; do not re-transcribe it here. Resolve the field values whose template placeholders don't spell out the rule:
 
-**Tier fields:**
+- `version` — the `{version}` resolved in §1 (not the template's literal `1.0.0`, which is only the new-stack default).
 - `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
-{
-  "skill_type": "stack",
-  "name": "{project_name}-stack",
-  "version": "{version — resolved per S11: code-mode primary_library_version or 1.0.0; compose-mode 1.0.0 (new stack) or bumped {prior_stack_version} (re-composition)}",
-  "generation_date": "{current_date}",
-  "forge_tier": "{Quick|Forge|Forge+|Deep — the tier under which this run executed}",
-  "confidence_tier": "{T1|T1-low|T2|T3 — dominant T-code from confidence_distribution below}",
-  "spec_version": "1.3",
-  "source_authority": "{official|community|internal — use the lowest authority among constituent skills}",
-  "generated_by": "create-stack-skill",
-  "exports": [],
-  "library_count": N,
-  "integration_count": N,
-  "libraries": ["lib1", "lib2"],
-  "integration_pairs": [["lib1", "lib2"]],
-  "language": "{primary language or list of languages from constituent skills}",
-  "ast_node_count": "{number or omit if no AST extraction performed}",
-  "confidence_distribution": {"t1": N, "t1_low": N, "t2": N, "t3": N},
-  "tool_versions": {
-    "ast_grep": "{version or null}",
-    "qmd": "{version or null}",
-    "skf": "{skf_version}"
-  },
-  "stats": {
-    "exports_documented": N,
-    "exports_public_api": N,
-    "exports_internal": N,
-    "exports_total": N,
-    "public_api_coverage": 0.0,
-    "total_coverage": 0.0,
-    "scripts_count": N,
-    "assets_count": N
-  },
-  "dependencies": [],
-  "compatibility": "{semver-range}"
-}
-```
+- `source_authority` — the lowest authority among constituent skills (official > community > internal).
 
 ### 7. Write Forge Data Artifacts (Workspace)
 
@@ -216,7 +182,7 @@ Use the schema from `{provenanceMapSchemaPath}` — see that asset for the canon
 - **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|constituent_documented_contract|inferred_from_shared_domain"`; includes the additional `constituents[]` array for drift detection).
 
-**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.**
+Populate compose-mode `constituents[].metadata_hash` from the value stored in workflow state at step 2 (S13), not a fresh re-hash at step-7 time — `{provenanceMapSchemaPath}` carries the rationale for why the manifest-detection-time hash is the correct provenance anchor.
 
 **evidence-report.md:**
 - Extraction summary per library
@@ -226,9 +192,9 @@ Use the schema from `{provenanceMapSchemaPath}` — see that asset for the canon
 
 ### 8. Pre-Commit Frontmatter & Body-Size Gate
 
-The full schema/frontmatter validation runs in step 8 (`validate.md`) — but that runs *after* commit-dir and flip-link have already published the package. The most common non-auto-fixable `skill-check` hard rejects — a `description` over the 1024-char limit (which `skill-check --fix` cannot trim for you), a SKILL.md body over the `body.max_lines` limit (default **500**), and a body exceeding the `body.max_tokens` limit (default **5000**) — would therefore only surface on an already-committed, symlink-active artifact, forcing edits to the live `SKILL.md`. Additive re-composition of an already-large stack grows the body monotonically, so body overflow (lines or tokens) is the likeliest trigger. Catch all three here, while the package is still in `.skf-tmp`.
+The full schema/frontmatter validation runs in step 8 (`validate.md`) — but that runs *after* commit-dir and flip-link have already published the package. The most common non-auto-fixable `skill-check` hard rejects — a `description` over the 1024-char limit (which `skill-check --fix` cannot trim for you) and a SKILL.md body over the `body.max_lines` limit (default **500**) — would therefore only surface on an already-committed, symlink-active artifact, forcing edits to the live `SKILL.md`. `skill-check` also *warns* (non-blocking) when the body exceeds `body.max_tokens` (default **5000**). Additive re-composition of an already-large stack grows the body monotonically, so body overflow is the likeliest trigger. Catch these here, while the package is still in `.skf-tmp`.
 
-Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}` (first existing path wins). Run it against the **staged** `SKILL.md`, passing the real skill name so the directory-match check is not fooled by the `.skf-tmp` staging suffix, `--max-body-lines 500` to assert the skill-check body-line limit, and `--max-body-tokens 5000` to assert the skill-check body-token limit pre-commit:
+Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}` (first existing path wins). Run it against the **staged** `SKILL.md`, passing the real skill name so the directory-match check is not fooled by the `.skf-tmp` staging suffix, `--max-body-lines 500` to assert the skill-check body-line limit, and `--max-body-tokens 5000` to surface the skill-check body-token *warning* pre-commit (advisory — see disposition below):
 
 ```bash
 uv run {frontmatterValidator} {skill_staging}/SKILL.md --skill-dir-name {project_name}-stack --max-body-lines 500 --max-body-tokens 5000
@@ -238,10 +204,10 @@ The validator emits JSON: `status` (`pass`/`warn`/`fail`), `issues[]` (each with
 
 - **`status` is `fail`, OR any `issues[]` entry has `severity` `high` or `medium`** — a hard violation that `npx skill-check` (step 8) would reject and `--fix` cannot auto-correct. HALT-to-fix **in staging**, then re-run the validator until it clears. Remediate by `field`:
   - `description` / `name` / `compatibility` — trim/correct `{skill_staging}/SKILL.md` (e.g. shorten `description` to ≤ 1024 chars).
-  - `body` (`body lines N exceeds max 500` or `body token estimate N exceeds max 5000`) — reduce the staged body: prefer a **selective split** of the largest Tier-2 section(s) into `{skill_staging}/references/`, keeping Tier-1 content inline (mirrors `validate.md` §3); or trim redundant content. Re-run the gate until both `body_lines ≤ 500` and `body_tokens ≤ 5000`.
+  - `body` (`body lines N exceeds max 500`) — reduce the staged body: prefer a **selective split** of the largest Tier-2 section(s) into `{skill_staging}/references/`, keeping Tier-1 content inline (mirrors `validate.md` §3); or trim redundant content. Re-run the gate until `body_lines ≤ 500`. (An over-`body_tokens` estimate is advisory, not a hard stop — see the low-severity note below.)
 
   Do NOT proceed to §9 commit-dir with an unresolved high/medium issue. Note: an over-long `description` is rated `medium` and exits `0`, so key the HALT on the issue severities above — not on the exit code.
-- **Only `low`-severity issues (e.g. an unexpected field)** — record each as a WARNING in the evidence report and proceed; these do not block the commit.
+- **Only `low`-severity issues (e.g. an unexpected field, or a `body token estimate N exceeds max 5000` advisory)** — record each as a WARNING in the evidence report and proceed; these do not block the commit. The body-token estimate is a char/4 heuristic that runs higher than `skill-check`'s own whitespace-split count, and `skill-check` treats `body.max_tokens` as a non-blocking warning — so an over-token estimate is advisory here, not a HALT (the `body.max_lines` gate above remains the hard body pre-check).
 
 **If `{frontmatterValidator}` does not resolve** (neither probe path exists) **or the invocation cannot run**, emit a WARNING ("pre-commit frontmatter + body-size gate skipped — validator unavailable") and proceed. Step 8 (`validate.md`) remains the post-commit backstop (including the `body.max_lines` split path in its §3); this gate is a best-effort early catch, never a new hard dependency.
 
@@ -269,24 +235,7 @@ If `flip-link` fails, emit a warning (the committed package is still valid), not
 
 ### 11. Display Write Summary
 
-"**Output files written.**
-
-**Deliverables** ({skill_package}):
-- SKILL.md ({line_count} lines)
-- context-snippet.md ({token_estimate} tokens)
-- metadata.json
-- references/ -- {lib_count} library files
-- references/integrations/ -- {pair_count} integration files
-
-**Workspace** ({forge_version}):
-- provenance-map.json
-- evidence-report.md
-
-**Symlink:** {skill_group}/active -> {version}
-
-**Total files written:** {total_count}
-
-**Proceeding to validation...**"
+Report the files written: the `{skill_package}` deliverables (SKILL.md with `{line_count}` lines, context-snippet.md with `{token_estimate}` tokens, metadata.json, `references/` `{lib_count}` library files, `references/integrations/` `{pair_count}` integration files), the `{forge_version}` workspace (provenance-map.json, evidence-report.md), the `{skill_group}/active -> {version}` symlink, and the `{total_count}` total.
 
 ### 12. Auto-Proceed to Next Step
 

package/src/skf-create-stack-skill/references/init.md

@@ -27,74 +27,12 @@ Before anything else, load `{project-root}/_bmad/skf/config.yaml`. If the file i
 
 **Halting workflow.**"
 
-STOP — do not proceed.
+Then emit the result envelope on stderr per the Result Contract in SKILL.md (`project_name` is unresolved here, so `skill_name` is `null`), and 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": []
-  }
-}
+SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":null,"stack_libraries":[],"mode":null,"exit_code":2,"halt_reason":"config-missing"}
 ```
 
-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.
@@ -107,7 +45,11 @@ Load `{forgeTierFile}` from the Ferris sidecar.
 
 **Halting workflow.**"
 
-STOP — do not proceed.
+Then emit the result envelope on stderr per the Result Contract in SKILL.md (config loaded, so `skill_name` is known; `mode` is not yet resolved), and STOP — do not proceed:
+
+```
+SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":[],"mode":null,"exit_code":3,"halt_reason":"forge-tier-missing"}
+```
 
 **If forge-tier.yaml exists:**
 
@@ -156,6 +98,7 @@ Skills use version-nested directories — see `knowledge/version-paths.md` for t
 - If user provides an architecture document path for composition or explicitly requests compose mode → set `compose_mode: true` and store `architecture_doc_path`
 - If no manifest files exist in project root AND at least one skill is discoverable in `{skills_output_folder}` → suggest compose mode to the user and ask for optional architecture document path
   - **Skill discovery (version-aware):** First, read `{skills_output_folder}/.export-manifest.json` — each entry in `exports` names a skill with an `active_version`, which resolves to `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/` containing `SKILL.md` and `metadata.json`. If the export manifest does not exist or is empty, fall back to scanning for `active` symlinks: check `{skills_output_folder}/*/active/*/SKILL.md` — each match indicates a skill whose package lives at `{skills_output_folder}/{skill-name}/active/{skill-name}/` (the `{active_skill}` template).
+  - **Headless default (B8):** If `{headless_mode}` is true, do NOT prompt — auto-accept the suggestion: set `compose_mode: true` and `architecture_doc_path: null` (unless an architecture doc path was supplied via the optional inputs above). This is the constructive default: with no manifests present, code-mode would only halt at step 2 (`no-manifests`), so compose is the sole path that produces output. Log the auto-decision by appending to `workflow_warnings[]`: `{step: "step-01", severity: "info", code: "headless-compose-autodetect", message: "no manifests + {N} discoverable skills — auto-selected compose mode", context: {discoverable_skills: {N}}}`.
   - If user accepts → set `compose_mode: true` and store `architecture_doc_path` (may be `null` if user chose not to provide one)
   - If user declines → `compose_mode` remains `false`, continue with code-mode
 
@@ -166,22 +109,7 @@ If no optional inputs provided, auto-detection will be used.
 
 ### 4. Display Initialization Summary
 
-"**Stack Skill Forge initialized.**
-
-**Project:** {project_name}
-**Forge Tier:** {forge_tier} — {tier_description}
-
-Where tier_description follows positive capability framing:
-- Quick: "Source reading and import counting"
-- Forge: "AST-backed structural analysis"
-- Forge+: "AST structural + CCC semantic co-import augmentation"
-- Deep: "Full intelligence — structural + contextual + temporal"
-
-**Available Tools:** {tool_list}
-**Input Mode:** {auto-detect | explicit dependency list | compose mode}
-
-**If compose mode:** Proceeding to skill loading...
-**If code mode:** Proceeding to manifest detection..."
+Report that the Stack Skill Forge is initialized, naming: the project (`{project_name}`); the forge tier (`{forge_tier}`) with its positive-capability framing (Quick = source reading and import counting; Forge = AST-backed structural analysis; Forge+ = AST structural + CCC semantic co-import augmentation; Deep = full intelligence — structural + contextual + temporal); the available tools (`{tool_list}`); and the resolved input mode (auto-detect, explicit dependency list, or compose mode).
 
 ### 5. Auto-Proceed to Next Step
 

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

@@ -15,41 +15,11 @@
 | PHP                   | composer.json                                       | require, require-dev                     | `use ...`, `require_once`                 |
 | .NET                  | *.csproj                                            | PackageReference                         | `using ...`                               |
 
-## Detection Priority
-
-1. Search project root for manifest files (depth 0-1)
-2. Parse each found manifest to extract dependency names
-3. Normalize names across ecosystems (e.g., `@scope/package` → `package`)
-4. Deduplicate across multiple manifests
-
-## Scan Exclusion Patterns
-
-When scanning for manifest files, ALWAYS exclude these directories from glob results:
-
-**Dependency/Vendor Directories:**
-- `node_modules/`
-- `.venv/` / `venv/` / `.env/`
-- `vendor/` (PHP Composer, Go modules)
-- `Pods/` (iOS CocoaPods)
-
-**Build Output Directories:**
-- `dist/` / `build/` / `out/`
-- `target/` (Rust, Java/Maven)
-- `__pycache__/`
-- `.next/` / `.nuxt/` / `.output/`
-
-**Hidden and VCS Directories:**
-- `.git/`
-- Any directory starting with `.` (except project root hidden config files like `.csproj`)
-
-**Monorepo Note:** For monorepo structures (e.g., `packages/*/package.json`), the depth 0-1 scan rule already limits scope. If monorepo manifest detection is needed at deeper levels, these exclusions become critical to prevent scanning dependency trees within each package.
-
-## Filtering Rules
-
-- Exclude dev-only dependencies unless they appear in production imports
-- Exclude build tools (webpack, babel, eslint, etc.) unless significantly imported
-- Include all runtime dependencies by default
-- Flag transitive dependencies that appear in direct imports
+<!-- Manifest scanning, name normalization, dedup, exclusion-dir filtering, and
+dev/build-tool filtering are performed by `skf-scan-manifests.py` (invoked in
+detect-manifests.md §2), which implements exactly the ecosystem table above.
+This file is loaded only for that reference table and the import-counting
+exclusions below — see the script's `--help` for the operative scan contract. -->
 
 ## Import Counting
 

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

@@ -60,7 +60,11 @@ The script emits JSON of the form:
 }
 ```
 
-Cache this result as `stack_skill_inventory` in workflow state — the per-skill subagent fan-out at §1+ MUST read from this cache rather than re-reading each skill's `SKILL.md` / `metadata.json` / `references/` to determine exports. Append every entry in `warnings[]` to workflow state for the evidence report (the script already labels them per-skill, e.g. `"<skill-name>: no exports found via any resolution path"`). For every entry in `cycles[]`, halt with a structured-error contract on stderr — a composes-cycle makes the stack unbuildable.
+Cache this result as `stack_skill_inventory` in workflow state — the per-skill subagent fan-out at §1+ MUST read from this cache rather than re-reading each skill's `SKILL.md` / `metadata.json` / `references/` to determine exports. Append every entry in `warnings[]` to workflow state for the evidence report (the script already labels them per-skill, e.g. `"<skill-name>: no exports found via any resolution path"`). If `cycles[]` is non-empty, a composes-cycle makes the stack unbuildable — emit the result envelope on stderr per the Result Contract in SKILL.md and exit `3`:
+
+```
+SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":[],"mode":"compose","exit_code":3,"halt_reason":"resolution-failure"}
+```
 
 Build a `per_library_extractions[]` entry for each skill by reading from the cached inventory:
 - `library`: `inventory.skills[i].name`
@@ -70,15 +74,7 @@ Build a `per_library_extractions[]` entry for each skill by reading from the cac
 - `metadata_hash`: `inventory.skills[i].metadata_hash` — record for step 7 provenance (null when exports came from references/ or SKILL.md prose).
 - `usage_patterns`: populated by the §1+ per-skill subagent fan-out, NOT by this script. The script provides the inventory + exports; the subagent does the per-skill usage analysis. They're complementary.
 
-Display an extraction summary:
-
-"**Loaded {N} skill extractions from existing skills.**
-
-| Skill | Exports | Confidence | Status |
-|-------|---------|------------|--------|
-| {name} | {count} | {tier} | Loaded |"
-
-Auto-proceed to next step.
+Report the loaded extractions — for each skill: export count, confidence tier, and load status. Then auto-proceed to the next step.
 
 **If not compose_mode:** Continue with section 1 (existing flow).
 
@@ -177,26 +173,15 @@ For each library extraction:
 **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 4","reason":"all extractions failed","libraries":[...]}`.
-3. Exit with a non-zero status so headless pipelines detect the failure.
-
-### 4. Display Extraction Summary
+2. Emit the result envelope on stderr per the Result Contract in SKILL.md (`stack_libraries` carries the confirmed library names that failed extraction), and exit `2`:
 
-"**Library extraction complete.**
+   ```
+   SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":["<confirmed-lib>", "..."],"mode":"{code|compose}","exit_code":2,"halt_reason":"all-extractions-failed"}
+   ```
 
-| Library | Exports | Patterns | Confidence | Status |
-|---------|---------|----------|------------|--------|
-| {name} | {count} | {count} | {tier} | ✓ |
-| {name} | {count} | {count} | {tier} | ✓ |
-| {name} | — | — | — | ⚠ partial |
-
-**Results:** {success_count}/{total_count} libraries extracted
-**Confidence distribution:** T1: {count}, T1-low: {count}, T2: {count}
-{If Deep tier:} **T2 enrichment:** {enriched_count}/{total_count} libraries had temporal collections available
-{If libraries without temporal > 0:} **Tip:** Run [CS] Create Skill at Deep tier for individual libraries to generate temporal collections, then re-run [SS] for full T2 enrichment.
-{If warnings:} **Warnings:** {warning_count} issues noted
+### 4. Display Extraction Summary
 
-**Proceeding to integration detection...**"
+Report the extraction results: per library the export count, pattern count, confidence tier, and success/partial status; the overall `{success_count}/{total_count}` extracted; and the T1 / T1-low / T2 confidence distribution. At Deep tier, add the T2-enrichment count (`{enriched_count}/{total_count}` libraries with temporal collections available); and if any library lacked a temporal collection, add the tip: run **[CS] Create Skill** at Deep tier for those libraries to generate temporal collections, then re-run **[SS]** for full T2 enrichment. Note any warning count.
 
 ### 5. Auto-Proceed to Next Step
 

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

@@ -56,7 +56,7 @@ Use ecosystem-appropriate import patterns:
 - Python: `import library`, `from library import`
 - Rust: `use library::`, `extern crate library`
 - Go: `"library"` in import blocks
-- (Match patterns from manifest-patterns.md)
+- (Match patterns from `{manifestPatternsPath}`)
 
 **Subprocess returns:** `{library_name: import_count, files: [file_paths]}` for each dependency.
 
@@ -112,13 +112,13 @@ Apply additions/exclusions, display updated list, and ask for final confirmation
 **If custom list provided:**
 Use the custom list as `confirmed_dependencies`.
 
-Display final confirmation:
+Display the resolved scope:
 
 "**Scope confirmed:** {count} libraries selected for stack skill extraction.
 
-{List confirmed libraries}
+{List confirmed libraries}"
 
-**Proceeding to parallel extraction...**"
+The extraction itself begins only once the user clears the gate below.
 
 ### 5. Present MENU OPTIONS
 
@@ -126,9 +126,9 @@ Display: **Select:** [C] Continue to Extraction | [X] Cancel and exit
 
 #### EXECUTION RULES:
 
-- ALWAYS halt and wait for user input after presenting scope
+- This is a confirmation gate — advancing without the user's `C` would extract and ship a stack scope they never approved. Halt and wait for input after presenting scope.
 - **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue (accept all ranked libraries), log: "headless: auto-confirm library scope"
-- ONLY proceed to next step when user confirms scope and selects 'C'
+- Proceed to the next step only once the user confirms scope by selecting `C`.
 
 #### Menu Handling Logic: