bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/skf-create-stack-skill/assets/metadata-contract.md

@@ -0,0 +1,51 @@
+# Stack metadata.json Contract
+
+The `metadata.json` every stack package carries, which step 7 §6 writes. This file is fixed: `stack_skill_template_path` overrides only the SKILL.md, context-snippet, catalog and reference-file structures of `assets/stack-skill-template.md`, never this contract. `generated_by`, `tool_versions.skf`, and `skill_type` with `forge_tier` or `confidence_tier` are the markers SKF's ownership check reads, so a stack written without them would be refused as not SKF output by every later run.
+
+## metadata.json Structure
+
+```json
+{
+  "skill_type": "stack",
+  "name": "{stack_name}",
+  "version": "1.0.0",
+  "generation_date": "{ISO-8601}",
+  "forge_tier": "{Quick|Forge|Forge+|Deep}",
+  "confidence_tier": "{T1|T1-low|T2|T3}",
+  "spec_version": "1.3",
+  "source_authority": "{official|community|internal}",
+  "generated_by": "create-stack-skill",
+  "exports": [],
+  "library_count": 0,
+  "integration_count": 0,
+  "libraries": ["lib1", "lib2"],
+  "integration_pairs": [["lib1", "lib2"]],
+  "language": "{primary language or list of languages from constituent skills}",
+  "ast_node_count": "{number-or-omitted-if-no-ast}",
+  "confidence_distribution": {
+    "t1": 0,
+    "t1_low": 0,
+    "t2": 0,
+    "t3": 0
+  },
+  "tool_versions": {
+    "ast_grep": "{version-or-null}",
+    "qmd": "{version-or-null}",
+    "skf": "{skf_version}"
+  },
+  "stats": {
+    "exports_documented": 0,
+    "exports_public_api": 0,
+    "exports_internal": 0,
+    "exports_total": 0,
+    "public_api_coverage": 0.0,
+    "total_coverage": 0.0,
+    "scripts_count": 0,
+    "assets_count": 0
+  },
+  "dependencies": [],
+  "compatibility": "{semver-range}"
+}
+```
+
+Step 7 §6 writes `library_count`, `integration_count`, `libraries`, `integration_pairs`, `confidence_distribution`, `confidence_tier` and `source_authority` verbatim from `skf-render-stack-metadata.py`. `confidence_distribution` counts libraries, each by its `per_library_extractions[].confidence`; the evidence report bins the provenance entries.

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

@@ -11,16 +11,16 @@ Canonical schema templates for the workspace `provenance-map.json` artifact writ
 
 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.
+> **Note:** A per-export entry has the fields the templates below give, with `source_library` naming its library and no `ast_node_type`: the stack methods `ast_bridge` and `source_reading` pair with no node kind.
 
 ## 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.
+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` names the tool that read the export (`ast_bridge` or `source_reading`): step 4 §1 gives the labels each method pairs with, and §3a relabels them with `skf-render-stack-metadata.py relabel`. `entries[].source_file` is relative to `{project_root}`, the project root (`project_root` from step 1), whatever folder `{scan_root}` narrowed the scan to, and `source_line` is the line that defines the export. `integrations[].co_import_files[]` holds each file that imports both libraries, as `skf-render-stack-metadata.py provenance` copies it from the `skf-pair-intersect.py` result step 5 saved (`path`, relative to `{project_root}` too because step 3 counts imports with `--relative-to {project_root}`, and `line_a` and `line_b`, the first line that imports each library). `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_name": "{stack_name}",
   "skill_type": "stack",
   "source_repo": ["{repo_url_1}", "{repo_url_2}"],
   "source_commit": {"{repo_1}": "{hash_1}", "{repo_2}": "{hash_2}"},
@@ -34,9 +34,9 @@ Used when the workflow ran in code-mode against an actual codebase. `source_repo
       "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"
+      "confidence": "T1|T1-low",
+      "extraction_method": "ast_bridge|source_reading",
+      "signature_source": "T1|T1-low"
     }
   ],
   "integrations": [
@@ -44,8 +44,8 @@ Used when the workflow ran in code-mode against an actual codebase. `source_repo
       "libraries": ["{libA}", "{libB}"],
       "pattern_type": "{type}",
       "detection_method": "co-import grep",
-      "co_import_files": [{"file": "{path}", "line": 0}],
-      "confidence": "T1|T2"
+      "co_import_files": [{"path": "{path}", "line_a": 0, "line_b": 0}],
+      "confidence": "T1|T1-low"
     }
   ]
 }
@@ -53,12 +53,12 @@ Used when the workflow ran in code-mode against an actual codebase. `source_repo
 
 ## 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), `"constituent_documented_contract"` (a cross-library contract documented in a constituent skill's integration docs but not co-mentioned in the architecture document — e.g. a grep-verified upstream seam cited from a source skill), or `"inferred_from_shared_domain"` (synthesized inference from shared language/domain, no cited contract). `detection_method` records *how* an edge was discovered; it is orthogonal to `confidence`, which is inherited from the constituent skills per the Confidence Tier Inheritance matrix in `{composeModeRulesPath}` (the integration tier is the weaker of the pair — never forced to a fixed band by detection method).
+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 together in the architecture doc, in a passage step 5 confirmed), `"constituent_documented_contract"` (a cross-library contract a constituent skill's own docs state, found when there is no architecture document, e.g. a grep-verified upstream seam cited from a source skill), or `"inferred_from_shared_domain"` (inferred from shared domain keywords, no cited contract; a shared language alone never makes a pair). `detection_method` records *how* an edge was discovered; it is orthogonal to `confidence`, which is inherited from the constituent skills per the Confidence Tier Inheritance rule in `references/compose-mode-rules.md` (the pair tier `skf-render-stack-metadata.py` gives, never forced to a fixed band by detection method).
 
 ```json
 {
   "provenance_version": "2.0",
-  "skill_name": "{project_name}-stack",
+  "skill_name": "{stack_name}",
   "skill_type": "stack",
   "source_repo": null,
   "source_commit": null,
@@ -66,16 +66,16 @@ Used when the workflow ran in compose-mode against pre-generated constituent ski
   "generated_at": "{ISO-8601}",
   "entries": [
     {
-      "export_name": "{name}",
+      "export_name": "{literal identifier}",
       "export_type": "{type}",
       "source_library": "{library-name}",
       "params": [],
       "return_type": "{type}",
       "source_file": "{from constituent skill}",
       "source_line": 0,
-      "confidence": "T1|T1-low|T2",
+      "confidence": "T1|T1-low|T2|T3",
       "extraction_method": "compose-from-skill",
-      "signature_source": "T1|T2|T3"
+      "signature_source": "T1|T1-low|T2|T3"
     }
   ],
   "integrations": [
@@ -90,7 +90,7 @@ Used when the workflow ran in compose-mode against pre-generated constituent ski
   "constituents": [
     {
       "skill_name": "{constituent-skill-name}",
-      "skill_path": "skills/{skill-dir}/",
+      "skill_path": "{skills_output_folder, relative to the project root}/{skill-dir}/",
       "version": "{version from constituent metadata.json}",
       "composed_at": "{ISO-8601}",
       "metadata_hash": "sha256:{hash of constituent metadata.json}"
@@ -99,4 +99,4 @@ Used when the workflow ran in compose-mode against pre-generated constituent ski
 }
 ```
 
-**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.**
+Step 7 writes `constituents[]` with `skf-render-stack-metadata.py provenance`, the only copier of each `metadata_hash`: the provenance anchor step 4 §0 read, copied from its saved inventory, never hashed again. Each `skill_path` is the constituent's folder in `skills_output_folder`, relative to the project root that Audit Skill resolves it from.

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

@@ -4,11 +4,12 @@
 
 ```markdown
 ---
-name: {project_name}-stack
+name: {stack_name}
 description: >
   Stack skill for {project_name} — {lib_count} libraries with
   {integration_count} integration patterns. Use when working with
-  this project's technology stack.
+  this project's technology stack. NOT for: individual library usage
+  outside this project's conventions.
 ---
 
 # {project_name} Stack Skill
@@ -26,7 +27,7 @@ description: >
 **Type:** {pattern_type}
 **Pattern:** {description}
 **Key files:** {file_list}
-**Confidence:** {T1/T1-low/T2}
+**Confidence:** {T1/T1-low/T2/T3}
 
 ## Library Reference Index
 
@@ -40,7 +41,8 @@ description: >
 **Role in stack:** {one-line description of what this library does in this project}
 **Key exports used:** {comma-separated list}
 **Usage pattern:** {brief pattern description}
-**Confidence:** {T1/T1-low/T2}
+**Confidence:** {T1/T1-low/T2/T3}
+**Reference:** [ref](references/{name}.md)
 
 ## Conventions
 
@@ -64,6 +66,10 @@ ceilings at compile time:
   below). For a **small stack**, keep them inline — inline passive context yields
   higher task accuracy than on-demand retrieval, and small stacks fit comfortably.
   Integration Patterns and Conventions stay inline regardless (Tier 1, load-bearing).
+  Whenever the catalog moves into `references/stack-catalog.md`, at compile time
+  or in a later body-size split, its Reference links become file-relative,
+  `[ref]({name}.md)`, because a link resolves from the file that holds it (see
+  "references/stack-catalog.md Structure" below).
 - **Inline pointer form** (replaces the two sections above when extracted):
 
   ```markdown
@@ -84,63 +90,22 @@ ceilings at compile time:
 Indexed format targeting ~80-120 tokens per stack:
 
 ```markdown
-[{project}-stack v{version}]|root: skills/{project}-stack/
-|IMPORTANT: {project}-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
+[{stack_name} v{version}]|root: skills/{stack_name}/
+|IMPORTANT: {stack_name} — 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}
 |gotchas: {1-2 most critical integration pitfalls}
 ```
 
-## metadata.json Structure
-
-```json
-{
-  "skill_type": "stack",
-  "name": "{project}-stack",
-  "version": "1.0.0",
-  "generation_date": "{ISO-8601}",
-  "forge_tier": "{Quick|Forge|Forge+|Deep}",
-  "confidence_tier": "{T1|T1-low|T2|T3}",
-  "spec_version": "1.3",
-  "source_authority": "{official|community|internal}",
-  "generated_by": "create-stack-skill",
-  "exports": [],
-  "library_count": 0,
-  "integration_count": 0,
-  "libraries": ["lib1", "lib2"],
-  "integration_pairs": [["lib1", "lib2"]],
-  "language": "{primary language or list of languages from constituent skills}",
-  "ast_node_count": "{number-or-omitted-if-no-ast}",
-  "confidence_distribution": {
-    "t1": 0,
-    "t1_low": 0,
-    "t2": 0,
-    "t3": 0
-  },
-  "tool_versions": {
-    "ast_grep": "{version-or-null}",
-    "qmd": "{version-or-null}",
-    "skf": "{skf_version}"
-  },
-  "stats": {
-    "exports_documented": 0,
-    "exports_public_api": 0,
-    "exports_internal": 0,
-    "exports_total": 0,
-    "public_api_coverage": 0.0,
-    "total_coverage": 0.0,
-    "scripts_count": 0,
-    "assets_count": 0
-  },
-  "dependencies": [],
-  "compatibility": "{semver-range}"
-}
-```
-
 ## references/stack-catalog.md Structure
 
 Written **only for large stacks** (see Sizing Guidance) when the catalog is
-extracted out of SKILL.md. Holds the two sections verbatim from the inline form:
+extracted out of SKILL.md. Holds the two sections from the inline form with
+their links rewritten: a link resolves from the file that holds it, and this
+file sits in `references/` beside the per-library files, so a link to one of
+them is `{name}.md` (the Reference column's `[ref]({name}.md)`). The inline
+form's `references/{name}.md` would resolve to `references/references/{name}.md`
+from here.
 
 ```markdown
 # {project_name} Stack — Library Catalog
@@ -152,7 +117,7 @@ extracted out of SKILL.md. Holds the two sections verbatim from the inline form:
 
 | Library | Imports | Key Exports | Confidence | Reference |
 |---------|---------|-------------|------------|-----------|
-| {name} | {count} | {top_exports} | {tier} | [ref](references/{name}.md) |
+| {name} | {count} | {top_exports} | {tier} | [ref]({name}.md) |
 
 ## Per-Library Summaries
 
@@ -160,7 +125,8 @@ extracted out of SKILL.md. Holds the two sections verbatim from the inline form:
 **Role in stack:** {one-line description of what this library does in this project}
 **Key exports used:** {comma-separated list}
 **Usage pattern:** {brief pattern description}
-**Confidence:** {T1/T1-low/T2}
+**Confidence:** {T1/T1-low/T2/T3}
+**Reference:** [ref]({name}.md)
 ```
 
 ## references/{library}.md Structure
@@ -170,7 +136,7 @@ extracted out of SKILL.md. Holds the two sections verbatim from the inline form:
 
 **Version:** {version_from_manifest}
 **Import count:** {count} files *(compose-mode: replace with **Export count:** {count} exports)*
-**Confidence:** {T1/T1-low/T2}
+**Confidence:** {T1/T1-low/T2/T3}
 
 ## Key Exports
 [Top exports used in this project with signatures]
@@ -189,7 +155,7 @@ extracted out of SKILL.md. Holds the two sections verbatim from the inline form:
 
 **Type:** {pattern_type}
 **Co-import files:** {count}
-**Confidence:** {T1/T1-low/T2 [composed]}
+**Confidence:** {T1/T1-low/T2/T3 [composed]}
 
 ## Integration Pattern
 [Detailed description of how these libraries connect]

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

@@ -1,8 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-create-stack-skill.
-# Team overrides:     _bmad/custom/skf-create-stack-skill.toml (under {project-root})
-# Personal overrides: _bmad/custom/skf-create-stack-skill.user.toml (under {project-root})
+# Team overrides:     {project-root}/_bmad/custom/skf-create-stack-skill.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-create-stack-skill.user.toml
 
 [workflow]
 
@@ -10,7 +10,9 @@
 #   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).
+# Steps SKILL.md On Activation step 3 runs right after the customization
+# resolve: config.yaml is loaded and headless mode resolved by then, and
+# init.md's pre-flight (the emitter, the run folder) has not run yet.
 # Overrides append. Use for org-wide pre-flight checks (auth, network,
 # compliance) that must precede any stack compilation work.
 
@@ -26,21 +28,29 @@ activation_steps_append = []
 # (house style, naming conventions, integration-pattern guardrails).
 # Overrides append.
 #
-# Each entry is either:
+# Each entry is one of:
 #   - 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).
+#   - an entry prefixed with `!`, which loads nothing and drops each earlier
+#     entry it names.
+#
+# The default below loads every project-context.md under {project-root}.
+# Overrides append, so they cannot delete it; to stop loading those files,
+# set in {project-root}/_bmad/custom/skf-create-stack-skill.toml:
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
-# Command invoked once the workflow reaches its terminal stage — after the
-# stack package is committed and the result contract is written (step 9,
-# report.md §6c), before the health-check chain. Override wins. Use for a
-# terminal action such as catalog registration or notifying a downstream
-# pipeline. Empty string = no terminal action. The hook never fails the run.
+# Command invoked once a run finishes (step 9, report.md §2c): after the
+# stack package is committed, the report is shown and the result files are
+# written, before the health-check chain. A run that halts never invokes it.
+# Override wins. Use for a terminal action such as catalog registration or
+# notifying a downstream pipeline. Empty string = no terminal action. The
+# hook never fails the run: a failure prints one report line.
 
 on_complete = ""
 
@@ -48,9 +58,10 @@ on_complete = ""
 #
 # 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 covers the SKILL.md, context snippet, catalog and
+# reference-file structures; the metadata.json contract
+# (assets/metadata-contract.md) carries SKF's ownership markers, so no
+# override replaces it.
 
 stack_skill_template_path = ""
 integration_patterns_path = ""
-manifest_patterns_path = ""
-compose_mode_rules_path = ""
-provenance_map_schema_path = ""

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

@@ -1,5 +1,16 @@
 ---
 nextStepFile: 'generate-output.md'
+renderStackMetadataProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-render-stack-metadata.py'
+  - '{project-root}/src/shared/scripts/skf-render-stack-metadata.py'
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
+bundleFile: '{run_dir}/extraction-bundle.json'
+exportRecordsFile: '{run_dir}/export-records.json'
+draftFolder: '{run_dir}/draft'
+# A fixed path: the compose rules are not a customization surface.
+composeModeRulesPath: 'references/compose-mode-rules.md'
 ---
 
 <!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
@@ -8,40 +19,39 @@ nextStepFile: 'generate-output.md'
 
 ## STEP GOAL:
 
-Assemble the main SKILL.md by combining per-library extractions with the integration layer, and present for user review before writing output files.
+Assemble the main SKILL.md by combining per-library extractions with the integration layer, write it as the run's draft, and get it approved before step 7 writes the package.
 
 ## Rules
 
 - Compile SKILL.md following the stack-skill-template structure — integration patterns go first
-- Do not write output files (Step 07)
-- Present compiled content for user review
+- Write only the draft in `{draftFolder}`: every file of the package is step 7's, staged from the approved draft
+- Present the stats and the draft's path for review; display the full draft only when the user asks, never in a headless run
 
 ## MANDATORY SEQUENCE
 
-### 1. Load Template Structure
+**Halt envelope.** Every HALT in this step names its exit code, `halt_reason` and phase. Stage `{run_dir}/halt.json` as `{"phase": "<phase>", "halt_reason": "<halt_reason>", "reason": "<the halt message, one line>", "skill_name": "{stack_name}", "mode": "<code|compose>", "stack_libraries": ["<confirmed library>", ...]}`, then run:
 
-Load `{stackSkillTemplatePath}` and prepare SKILL.md section structure.
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-stack-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
 
-### 2. Generate Frontmatter
+Display the line it prints, then stop with the halt's exit code (`references/invocation-contract.md` lists every halt). If `{emitEnvelopeHelper}` is not bound, resolve it from `{emitEnvelopeProbeOrder}`; if no path exists, or the emitter exits non-zero or prints no line, display the halt message alone.
 
-The SKILL.md MUST begin with YAML frontmatter (agentskills.io compliance):
+### 1. Load Template Structure
 
-```yaml
----
-name: {project_name}-stack
-description: >
-  Stack skill for {project_name} — {lib_count} libraries with
-  {integration_count} integration patterns. Use when working with
-  this project's technology stack. NOT for: individual library usage
-  outside this project's conventions.
----
+Load `{stackSkillTemplatePath}` and prepare SKILL.md section structure. Every section below compiles from `{bundleFile}`: step 4's per-library extractions and step 5's integration graph (`integrations[]`, `hubs`, `cross_cutting`), never from memory. A library's key exports are its records in `{exportRecordsFile}` in code mode (each with its `source_library`), and its bundle entry's `exports` in compose mode.
+
+**The stack's counts.** Take them from the helper step 7 §6 also runs, never by hand. Resolve `{renderStackMetadataHelper}` from `{renderStackMetadataProbeOrder}`; first existing path wins. If no candidate exists, HALT (exit 3, `halt_reason: "helper-missing"`, phase `compile-stack:stats`) with "**Cannot proceed.** `skf-render-stack-metadata.py` is missing, so the stack cannot be counted. Re-install SKF, then re-run." Otherwise run:
+
+```bash
+uv run {renderStackMetadataHelper} metadata --input -
 ```
 
-**Frontmatter rules:**
+piping `{"mode": "code|compose", "libraries": [{"name": "<library>", "confidence": "<its per_library_extractions[].confidence>"}, ...], "integrations": [{"a": "<library>", "b": "<library>"}, ...]}`, every library and every pair of `{bundleFile}`. On exit `2`, fix the input its stderr names and run it again. Bind `{lib_count}` ← its `library_count` and `{integration_count}` ← its `integration_count`, which §2's description and §7's stats name, and keep its `confidence_distribution` for §7.
+
+### 2. Generate Frontmatter
 
-- `name`: lowercase alphanumeric + hyphens only, must match skill output directory name. **Stack skills MUST end in `-stack`** (e.g., `{project_name}-stack`) — this is how consumers (skf-verify-stack, skf-test-skill) detect stack vs individual skills.
-- `description`: non-empty, max 1024 chars, trigger-optimized for agent discovery. MUST use third-person voice ("Processes..." not "I can..." or "You can..."). **Do NOT enumerate every library by name** — a 12+ library stack overruns 1024 chars. Keep the generic "{lib_count} libraries with {integration_count} integration patterns" form; if a per-library parenthetical is used, cap it to the top libraries by import/export count with a `+{N} more` suffix (full list lives in `metadata.json` `libraries[]`). See "Sizing Guidance for Large Stacks" in `{stackSkillTemplatePath}`.
-- No other frontmatter fields — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted by spec
+Use the template's frontmatter with the counts §1 bound; its Sizing Guidance caps the description.
 
 ### 3. Compile Integration Layer
 
@@ -59,6 +69,7 @@ Compile in order:
   - Pattern description with file:line citations
   - Key files demonstrating the integration
   - Confidence tier label
+- **In compose mode**, render each pair in the evidence format of `{composeModeRulesPath}` instead, from its entry's `evidence`, `reference`, `tier` and `qualifier`, adding the VS lines and annotation that file's Feasibility Report Integration gives when the entry's `vs` is set; a compose pair has no key files.
 
 **Hub library connections:**
 - For each hub library (3+ connections):
@@ -67,77 +78,57 @@ Compile in order:
 
 ### 4. Compile Per-Library Sections
 
-**Catalog placement (decide once, applies to this section and §6).** The
-`Per-Library Summaries` and `Library Reference Index` are the largest sections
-and grow with the stack. For a **large stack** (heuristic: **> 6 libraries OR
-> 6 integration patterns**), author both into `references/stack-catalog.md`
-(structure in `{stackSkillTemplatePath}`) and place only the inline pointer from the
-template's "Sizing Guidance" in SKILL.md — this keeps the body under the 500-line
-`body.max_lines` budget that step 08 enforces. For a **small stack**, keep both
-inline (inline passive context yields higher task accuracy). Either way, step 08's
-body-size gate is the backstop; step 08 (`validate.md` §4) accepts both forms.
-
-For each confirmed library (ordered by integration connectivity, then import count — **in compose-mode**, order by integration connectivity, then skill confidence tier since import counts are not available):
+**Catalog placement (decide once, applies to this section and §6).** By the template's Sizing Guidance, a large stack authors the `Per-Library Summaries` and `Library Reference Index` into `references/stack-catalog.md`, whose per-library links read `[ref]({name}.md)`, and leaves the inline pointer in SKILL.md; a small stack keeps both inline, its links reading `[ref](references/{name}.md)`. A link resolves from the file that holds it.
 
-- Role in stack (one-line description)
-- Key exports used in this project
-- Usage patterns from extraction
-- Confidence tier label
-- Link to reference file: `references/{library}.md`
+Order the libraries by integration connectivity, then import count (**in compose-mode**, connectivity then skill confidence tier, since import counts are not available).
 
 ### 5. Compile Project Conventions
 
-Extract project-specific conventions from the extractions:
-- Common initialization patterns
-- Error handling approaches across libraries
-- Configuration conventions
-- Import organization patterns
+The conventions the extractions show recurring across libraries.
 
 ### 6. Compile Library Reference Index
 
-Place per the §4 catalog-placement decision (inline for small stacks; in
-`references/stack-catalog.md` for large stacks). Create the reference index table:
+Per the template and §4's placement (**in compose-mode**: replace the Imports column with Export Count from source skill metadata, since import counts are not available).
 
-| Library | Imports | Key Exports | Confidence | Reference |
-|---------|---------|-------------|------------|-----------|
-| ... | ... | ... | ... | ... |
+The Reference column follows the §4 link rule: `[ref](references/{name}.md)` when the index stays in SKILL.md, `[ref]({name}.md)` when it goes to `references/stack-catalog.md`.
 
-(**in compose-mode**: replace the Imports column with Export Count from source skill metadata, since import counts are not available)
+### 7. Write the Draft and Its Stats
 
-### 7. Present Compiled SKILL.md Preview
+Write the compiled SKILL.md to `{draftFolder}/SKILL.md`, and, when §4 moved the catalog out, the catalog to `{draftFolder}/stack-catalog.md`. The draft is what the review approves: step 7 stages it verbatim.
 
-"**Stack skill compilation complete. Please review:**
+Then display, with the counts and the distribution of the §1 helper run:
 
----
-
-{Display full compiled SKILL.md content}
-
----
+"**Stack skill compilation complete. Please review the draft:** `{draftFolder}/SKILL.md`{IF catalog:} and `{draftFolder}/stack-catalog.md`{END IF}
 
 **Compilation stats:**
-- **Libraries:** {count}
-- **Integration pairs:** {count}
-- **Cross-cutting patterns:** {count}
-- **Confidence:** T1: {count}, T1-low: {count}, T2: {count}
+- **Libraries:** {lib_count}
+- **Integration pairs:** {integration_count}
+- **Cross-cutting patterns:** {each entry of the bundle's `cross_cutting`, or none}
+- **Confidence (libraries per tier, `per_library_extractions[].confidence`):** T1: {its `confidence_distribution.t1`}, T1-low: {`t1_low`}, T2: {`t2`}, T3: {`t3`}
 
 **Please review the integration layer and per-library sections.**
 - Does the integration layer capture how your libraries connect?
 - Are the per-library summaries accurate?
-- Any sections to adjust before writing output?"
+- Any sections to adjust before writing output? Edit the draft yourself, or tell me what to change."
 
 ### 8. Present MENU OPTIONS
 
-Display: **Select:** [C] Continue to Output Generation | [X] Cancel and exit
+Display: **Select:** [C] Continue to Output Generation | [P] Preview the full draft | [X] Cancel and exit
 
 #### EXECUTION RULES:
 
-- This is a review gate — advancing without the user's `C` would write output files from a compilation they never reviewed. Halt and wait for input after presenting the compiled SKILL.md.
-- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve stack compilation"
+- This is a review gate: advancing without the user's `C` would write output files from a compilation they never reviewed. Halt and wait for input after presenting the stats.
+- **GATE [default: C]**: If `{headless_mode}`: auto-proceed with [C] Continue, displaying no draft, and record the auto-decision: stage `{"gate": "compile-stack.review", "default_action": "C", "taken_action": "C", "reason": "headless: approved the compiled draft"}` as `{run_dir}/decision.json` and run:
+
+  ```bash
+  uv run {emitEnvelopeHelper} record --workflow skf-create-stack-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+  ```
+
 - Proceed to the next step only once the user approves by selecting `C`.
 
 #### 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)
-
+- IF C: The draft files as they stand on disk, the user's own edits included, are the approved compilation. Load, read entire file, then execute {nextStepFile}
+- IF P: Display the full draft files, then [Redisplay Menu Options](#8-present-menu-options)
+- IF X: HALT (exit 6, `halt_reason: "user-cancelled"`, phase `compile-stack:review`): leave any existing committed stack package untouched, emit the envelope, then delete the run folder (`rm -rf "{run_dir}"`), the draft and the bundle with it
+- IF Any other: Process it as feedback: apply it to the draft files in `{draftFolder}`. When it drops a library or a pair, drop it from `{bundleFile}` too (a library with its pairs, and its records from `{exportRecordsFile}`), so step 7 writes no file the draft no longer covers; then run the §1 helper call again, rebinding the counts, and rewrite the draft's `description` with them. Show the stats again, then [Redisplay Menu Options](#8-present-menu-options)