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

package/src/{workflows/create-skill → skf-create-skill}/steps-c/step-05-compile.md

@@ -1,9 +1,7 @@
 ---
-name: 'step-05-compile'
-description: 'Assemble SKILL.md, context-snippet, metadata, and references from extraction inventory'
 nextStepFile: './step-06-validate.md'
-skillSectionsData: '../data/skill-sections.md'
-assemblyRulesData: '../data/compile-assembly-rules.md'
+skillSectionsData: 'assets/skill-sections.md'
+assemblyRulesData: 'assets/compile-assembly-rules.md'
 ---
 
 # Step 5: Compile
@@ -12,44 +10,13 @@ assemblyRulesData: '../data/compile-assembly-rules.md'
 
 To assemble the complete skill content from the extraction inventory and enrichment annotations — building SKILL.md sections, context-snippet.md, metadata.json, and references/ content according to the agentskills.io format.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+## Rules
 
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🎯 ALWAYS follow the exact instructions in the step file
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a skill compilation engine performing structured assembly
-- ✅ Every instruction in SKILL.md must trace to source code with a provenance citation
-- ✅ Uncitable content is excluded, not guessed — zero hallucination
-
-### Step-Specific Rules:
-
-- 🎯 Focus ONLY on assembling content from extraction inventory + enrichment
-- 🚫 FORBIDDEN to include any content without a provenance citation
-- 💾 Sub-agents and compilation processes may write to a staging directory (e.g., `_bmad-output/{name}/`)
-- 🚫 FORBIDDEN to write final files to `skills/` or `forge-data/` — that's step-07
-- 🚫 FORBIDDEN to fabricate examples not found in source tests or docs
-- ⚒️ Seed `<!-- [MANUAL] -->` markers for future update-skill compatibility
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow MANDATORY SEQUENCE exactly
-- 💾 Build all content in context AND write to the staging directory (`_bmad-output/{name}/`) — staging write is mandatory for step-06 validation
-- 📖 Follow agentskills.io section structure from data file
-- 🚫 Do not promote any output files to final `skills/` or `forge-data/` directories — that's step-07
-
-## CONTEXT BOUNDARIES:
-
-- Available: extraction_inventory, enrichment_annotations (if Deep), doc_fetch_inventory (if doc_urls), brief_data, tier
-- Focus: Assembling structured content from verified data
-- Docs-only mode: If `source_type: "docs-only"`, all content is T3 `[EXT:{url}]`. Overview must note "Generated from external documentation." metadata.json `source_authority` forced to `community`. No AST/source citations exist — only `[EXT:...]` citations.
-- Limits: Do NOT write to final `skills/` or `forge-data/` directories, validate spec compliance, or report
-- Dependencies: Extraction inventory from step-03 (enrichment from step-04 if Deep)
+- Focus only on assembling content from extraction inventory + enrichment
+- Do not include any content without a provenance citation
+- Write all compiled artifacts to the staging directory `_bmad-output/{skill-name}/`. Do not write to `skills/` or `forge-data/` — step-07 promotes staged artifacts to their final versioned locations.
+- Do not fabricate examples not found in source tests or docs
+- Seed `<!-- [MANUAL] -->` markers for future update-skill compatibility
 
 ## MANDATORY SEQUENCE
 
@@ -59,6 +26,19 @@ To assemble the complete skill content from the extraction inventory and enrichm
 
 Load `{skillSectionsData}` and `{assemblyRulesData}` completely. These define the agentskills.io-compliant format and detailed assembly rules for all output artifacts.
 
+### 1a. Create Staging Directory
+
+Create `_bmad-output/{skill-name}/` (and `_bmad-output/{skill-name}/references/`). All artifacts produced in sections 2–7 below are written here:
+
+- `SKILL.md`
+- `context-snippet.md`
+- `metadata.json`
+- `references/*.md`
+- `provenance-map.json`
+- `evidence-report.md`
+
+This is the `<staging-skill-dir>` referenced by step-06 (`npx skill-check check`, `npx -y tessl skill review`). Step-07 reads from the in-context copies (resynced by step-06 after any `--fix` modifications) and writes to the final versioned layout.
+
 ### 1b. Signature Fidelity Rule
 
 **When assembling function signatures, parameter lists, and return types in any SKILL.md section or reference file:**
@@ -74,6 +54,24 @@ This rule applies to ALL sections including Tier 1 Key API Summary, Tier 2 Full
 
 Assemble each section in order using the assembly rules data file (`{assemblyRulesData}`). The data file specifies frontmatter format, Tier 1 section details (Sections 1-8, including conditional Section 7b for scripts/assets), Tier 2 section details (Sections 9-11), and assembly ordering rules. Follow it exactly. Assemble Section 7b (Scripts & Assets) only if `scripts_inventory` or `assets_inventory` is non-empty.
 
+### 2a. Description Sanitization Pass
+
+**Before writing SKILL.md frontmatter to disk**, sanitize the assembled `description` string by replacing every `<` with `{` and every `>` with `}`. Apply this pass unconditionally to the final assembled description in context, then write the result to `SKILL.md`.
+
+**Why unconditional?** Both `skill-check`'s `description_field` validator and `tessl`'s deterministic description check parse the frontmatter `description` as a raw string — they reject any `<` or `>` regardless of whether the content is inside a backtick span or a generic expression. The previous rule exempted backticked content on the assumption that backticks protect from XML-tag parsing, but that assumption is false for these validators: a backticked TypeScript generic like `` `Meta<typeof X>` `` still fails tessl's check because tessl reads the raw string before markdown parsing. Unconditional replacement guarantees no angle brackets reach either validator.
+
+**Coverage examples** (all handled by the same `<`/`>` → `{`/`}` replacement):
+
+- Standalone placeholders: `<name>` → `{name}`, `<component-id>` → `{component-id}` — curly braces are the standard placeholder notation in prose and render cleanly.
+- Backticked TypeScript / C++ / Rust generics: `` `Meta<typeof X>` `` → `` `Meta{typeof X}` ``, `` `Array<T>` `` → `` `Array{T}` ``, `` `Vec<u8>` `` → `` `Vec{u8}` `` — readable approximations that preserve the author's intent for code-ish fragments.
+- Any other angle-bracket content, whether inside backticks or bare, is also rewritten.
+
+**Scope:** This rule applies **only** to the frontmatter `description` field. Body content, code examples, reference files, and assembly-rule documents retain their original angle brackets — they are parsed through the markdown AST where backticks do protect content.
+
+Record the count of substitutions in context as `description_sanitizations: {count}` for the evidence report.
+
+**Rationale:** The LTS-stable guarantee is that no angle-bracket character reaches step-06 validation in the description field. The assembly rules in `{assemblyRulesData}` define this as a drafting rule; this step makes it an enforced pass so authors and reviewers don't have to remember it. If the rule is ever bypassed (e.g., by a downstream tool rewriting the description), step-06 §6 provides a recovery path — see `description-xml-tags-guarded-upstream` in `assets/tessl-dismissal-rules.md`.
+
 ### 3. Build context-snippet.md Content
 
 Vercel-aligned indexed format for CLAUDE.md managed section (~80-120 tokens):
@@ -109,6 +107,12 @@ Following the structure from the skill-sections data file:
   - `exports_total`: `exports_public_api` + `exports_internal`
   - `public_api_coverage`: `exports_documented / exports_public_api` (1.0 when all public API exports are documented; `null` if `exports_public_api` is 0)
   - `total_coverage`: `exports_documented / exports_total` (may be low for large codebases — this is expected; `null` if `exports_total` is 0)
+  - `effective_denominator` (**optional** — emit only for stratified-scope monorepo packages): the count of public exports from files matched by the brief's authoring-surface globs, filtered by `scope.exclude`, resolved against `source_path`. **Prefer `scope.tier_a_include` when the brief supplies it** — that narrow list represents the authoring surface the brief intends to document; resolve its globs across `source_path` and count the union of named exports. **Otherwise use `scope.include`** — the coarse list. This is the coverage denominator `skf-test-skill` uses when the package is a curated subset of a multi-package repository, so it must match the brief's authoring intent. Compute when ALL of the following hold:
+    1. The source is a monorepo (detected via `packages/` layout, `workspaces` field in root `package.json`, `lerna.json`, `rush.json`, `nx.json`, or Cargo `[workspace]`).
+    2. `scope.type` is not `full-library`, AND the resolved include list (`tier_a_include` if present, else `scope.include`) lists a curated file/directory subset rather than the full workspace.
+    3. `scope.notes` is present and documents the stratification strategy (e.g., a tiered A/B/C plan) — this serves as the intent marker confirming the subset is by design.
+
+    Otherwise omit the field entirely — when absent, `skf-test-skill` falls back to `exports_public_api`. See `skf-test-skill` `references/source-access-protocol.md` §Source API Surface Definition ("Stratified-scope monorepo packages") for the test-side consumption rules.
 - Set `description` from the SKILL.md frontmatter `description` field (already assembled in section 2)
 - Set `language` from source analysis (e.g., `"typescript"`, `"python"`) — use the primary language of the entry point file
 - Set `ast_node_count` from extraction stats if ast-grep was used (Forge/Deep tier), otherwise omit
@@ -142,55 +146,47 @@ Group functions logically by module, file, or functional area.
 
 ### 6. Build provenance-map.json Content
 
-One entry per extracted export: export_name, export_type, params[] (typed strings), return_type, source_file, source_line, confidence tier (T1/T1-low/T2), extraction_method, ast_node_type, signature_source ("T1"|"T1-low"|"T2"|"T3" — indicates which tier contributed the structural signature). If `scripts_inventory` or `assets_inventory` is non-empty, add `file_entries[]` with file_name, file_type, source_file, content_hash, confidence, extraction_method. See `{skillSectionsData}` for full schema.
+One entry per extracted export: export_name, export_type, params[] (typed strings), return_type, source_file, source_line, confidence tier (T1/T1-low/T2), extraction_method, ast_node_type, signature_source ("T1"|"T1-low"|"T2"|"T3" — indicates which tier contributed the structural signature).
+
+**File entries** — emit one `file_entries[]` row per tracked non-code file when any of these inventories are non-empty:
+
+- `scripts_inventory` → `file_type: "script"`, `extraction_method: "file-copy"`, stored in `{skill_package}/scripts/` by step-07
+- `assets_inventory` → `file_type: "asset"`, `extraction_method: "file-copy"`, stored in `{skill_package}/assets/` by step-07
+- `promoted_docs` (from step-03 §2a) → `file_type: "doc"`, `extraction_method: "promoted-authoritative"`, **NOT** copied into the skill package by step-07. The source file stays at its original path; only the provenance tracking entry is written. `content_hash` was pre-computed by §2a.
+
+Each `file_entries[]` row has the same shape regardless of `file_type`: `{file_name, file_type, source_file, content_hash, confidence, extraction_method}`. See `{skillSectionsData}` for full schema and the canonical list of `file_type` values.
 
 ### 7. Build evidence-report.md Content
 
 Compilation audit trail: generation date, forge tier, source info, tool versions, extraction summary (files/exports/confidence), warnings. For validation-specific fields (Schema, Body, Security, Content Quality, tessl, Metadata), insert the placeholder text `[PENDING — populated by step-06]`. Step-06 will replace these placeholders with actual results. See `{skillSectionsData}` for full template. Use the same `{skf_version}` value resolved in section 4 when populating the Tool Versions block.
 
+**Frontmatter — pinned fields (MANDATORY):** emit YAML frontmatter at the top of `evidence-report.md` with at minimum `skill_name`, `generated`, `forge_tier`, and `t2_future_count`. Compute `t2_future_count` as the count of forward-looking (T2-future) temporal annotations in the enrichment data produced by step-04 (`qmd query` + temporal classification). **Emit `t2_future_count: 0` when no T2-future annotations exist** — omission is indistinguishable from "no data" for downstream consumers and would silently flip the skf-test-skill §2b/§5b migration-section gate into Case 2/3 for a Case-1 skill. This frontmatter is the authoritative detection contract — `migration-section-rules.md` Case Rules parse it deterministically rather than grepping prose.
+
+**Auto-Decisions section (headless buffer flush):** read the in-context `headless_decisions[]` list (populated by step-01 tier-override handling, step-02 ecosystem gate, and any future step that auto-resolves a gate under `{headless_mode}`). Emit an `## Auto-Decisions` section with one row per entry:
+
+```
+## Auto-Decisions
+
+| Step | Gate | Decision | Rationale | Timestamp |
+|------|------|----------|-----------|-----------|
+| {step} | {gate} | {decision}{value?} | {rationale} | {timestamp} |
+```
+
+If `headless_decisions[]` is empty, emit the section header with a single line: `No auto-decisions — workflow ran interactively (or all gates had no match to auto-resolve).` This guarantees the section is always present so reviewers can tell "zero auto-decisions" apart from "section missing".
+
 ### 8. Menu Handling Logic
 
 **Auto-proceed step — no user interaction.**
 
-After all content is assembled in context (or written to the staging directory), immediately load, read entire file, then execute `{nextStepFile}`.
+After all content is assembled in context and written to the staging directory, immediately load, read entire file, then execute `{nextStepFile}`.
 
 #### EXECUTION RULES:
 
 - This is an auto-proceed assembly step with no user choices
-- All content stays in context or in the staging directory — no final files are written yet
+- All content must be both in context and in `_bmad-output/{skill-name}/` — no final files in `skills/` or `forge-data/` yet
 - Proceed directly to validation after assembly is complete
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN all 6 content artifacts (SKILL.md, context-snippet.md, metadata.json, references/, provenance-map.json, evidence-report.md) are assembled in context will you proceed to load `{nextStepFile}` for spec validation. Note: extraction-rules.yaml is generated by step-07 from extraction data, not assembled here.
-
----
+ONLY WHEN all 6 content artifacts (SKILL.md, context-snippet.md, metadata.json, references/, provenance-map.json, evidence-report.md) are assembled in context AND written to the staging directory `_bmad-output/{skill-name}/` will you proceed to load `{nextStepFile}` for spec validation. Note: extraction-rules.yaml is generated by step-07 from extraction data, not assembled here.
 
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Skill-sections data file and assembly rules data file loaded and followed
-- SKILL.md assembled with all required sections in agentskills.io format
-- Tier 1 sections assembled first and kept under 300 lines (excluding frontmatter)
-- Tier 2 sections assembled after all Tier 1 sections
-- Section 4b emitted only when Deep tier AND T2-future annotations exist; omitted entirely otherwise (no empty section)
-- Every function entry has a provenance citation
-- [MANUAL] markers seeded for update-skill compatibility
-- context-snippet.md, metadata.json, references/, provenance-map.json, evidence-report.md all assembled
-- No content without provenance citations included
-- Auto-proceeded to step-06
-
-### ❌ SYSTEM FAILURE:
-
-- Including functions or examples without provenance citations
-- Fabricating usage examples not found in source
-- Writing files to final `skills/` or `forge-data/` directories (that's step-07)
-- Missing required SKILL.md sections
-- Emitting an empty Section 4b when no T2-future annotations exist
-- Tier 1 content exceeding 300 lines without reduction
-- Assembling Tier 2 sections before Tier 1 sections
-- Not seeding [MANUAL] markers
-- Not building all 6 content artifacts (extraction-rules.yaml is built by step-07)
-
-**Master Rule:** Zero hallucination — every line of SKILL.md must trace to source code. Compile from data, not imagination.

package/src/skf-create-skill/steps-c/step-06-validate.md

@@ -0,0 +1,267 @@
+---
+nextStepFile: './step-07-generate-artifacts.md'
+tesslDismissalData: 'assets/tessl-dismissal-rules.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 — losing atomic-write guarantees is not
+# an option for the staging-directory artifacts this step produces.
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+---
+
+# Step 6: Validate
+
+## STEP GOAL:
+
+To validate the compiled SKILL.md content against the agentskills.io specification using skill-check, auto-fix any validation failures, and confirm spec compliance before artifact generation.
+
+## Rules
+
+- Focus only on validating compiled content against spec — only fix spec compliance issues
+- Validation and auto-fix modify files in the staging directory
+- `<staging-skill-dir>` resolves to `_bmad-output/{skill-name}/` as created by step-05. The directory name must match the skill's frontmatter `name` field exactly — `skill-check`'s `frontmatter.name_matches_directory` rule rejects any suffix.
+- If skill-check unavailable: skip validation, add warning to evidence report
+- Ignore non-zero exit codes from skill-check if JSON output shows 0 errors
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 0. Description Guard Protocol
+
+**Used by:** §2 (`skill-check check --fix`), §4 (`split-body`), and any future tool invocation that may modify SKILL.md.
+
+External validators occasionally rewrite the frontmatter `description` field — `skill-check --fix` may replace it with a generic or truncated version, and `split-body` may touch it during mechanical restructuring. The step-05 §2a compiled description is **authoritative**: it has already been sanitized of angle-bracket tokens and trigger-optimized for agent discovery. Losing it to a tool's well-meaning rewrite breaks discovery quality and re-introduces the angle-bracket failure mode.
+
+To prevent this, any tool invocation that may touch SKILL.md must run inside the following four-phase guard:
+
+1. **Capture.** Before invoking the tool, read the current SKILL.md frontmatter and snapshot the exact `description` value into a local variable (e.g., `guarded_description`). Capture the in-context copy as well.
+2. **Execute.** Run the tool as specified in its section.
+3. **Verify.** After the tool completes, re-read the on-disk SKILL.md and compare its frontmatter `description` against `guarded_description` as **token streams**: split each string on whitespace (`str.split()` — any run of spaces/tabs/newlines collapses) and compare the resulting lists element-by-element. This catches content divergence (missing words, replaced phrases, truncation, angle-bracket re-introduction) while ignoring cosmetic whitespace changes that a tool may apply (trailing newline, re-wrapped quoted strings). Do NOT use a normalized-string equality — a tool that rewrites `"foo  bar"` to `"foo bar"` (collapsed inner run) would trip a naive normalization even though no semantic content changed, and a tool that swapped one word would slip past a looser fuzzy match. Token-stream comparison is the sweet spot.
+4. **Restore on divergence.** If the post-tool description differs from `guarded_description` in any way other than whitespace normalization, write `guarded_description` back to the on-disk SKILL.md frontmatter and update the in-context copy to match. Record `description_guard_restored: true` with the tool name in context for the evidence report.
+5. **Re-validate restored description.** After a restore, run `python3 {project-root}/src/shared/scripts/skf-validate-frontmatter.py <staging-skill-dir>/SKILL.md` against the on-disk file to confirm the restored description still satisfies the frontmatter contract (length limits, forbidden tokens, required fields). Capture `schema_revalidation_result` in context. If the validator exits non-zero OR reports failure for the `description` field: flip the Schema result back to `FAIL` in the evidence report (overriding any prior PASS/WARN from §2), record `description_guard_revalidation: FAIL` with the validator's diagnostic message, and continue — do not halt (step-09 health-check and result contract still need to run so the failure is surfaced through the normal artifact path).
+
+**What counts as divergence:**
+
+- The description was replaced (different content).
+- The description was truncated (suffix missing).
+- Angle-bracket tokens were re-introduced (should never happen after step-05 §2a, but protect anyway).
+- The field was deleted entirely (extreme tool behavior).
+
+**What does NOT count as divergence:** whitespace-only differences (trailing newline, trimmed spaces) — treat as equivalent.
+
+**Why this is centralized:** previously, §2 and §4 each contained their own capture/verify/restore prose. Duplicated defensive code drifts: a fix in one section doesn't propagate to the other, and adding a new tool invocation in the future requires remembering to copy the pattern. Centralizing the protocol gives step-06 one place to update when external validator behavior changes.
+
+### 1. Check Tool Availability
+
+Run: `timeout 30s npx skill-check -h` — the short timeout protects against a cold `npx` download blocking the workflow indefinitely on a slow network.
+
+- If succeeds: Continue to automated validation (section 2)
+- If fails or times out: Perform manual fallback (section 3); add note to evidence-report: "Spec validation performed manually — skill-check tool unavailable". Also set `metadata.validation_status: 'manual-only'` in `metadata.json` (write via `python3 {atomicWriteHelper} write --target <staging-skill-dir>/metadata.json`), and in the evidence-report's `Validation Results` section mark Security, Body, and Content Quality (tessl) rows explicitly as `skipped — skill-check unavailable`. Downstream consumers (pipeline, forger, test-skill) check `validation_status` to decide how much weight to put on the artifact; leaving it unset would make a manual-only run look equivalent to a fully automated PASS.
+
+**Important:** Do not assume availability — empirical check required.
+
+### 2. Validate & Auto-Fix (skill-check check --fix)
+
+Run the external skill-check tool against the compiled skill staging directory.
+
+**Flag probe (run once, cache the result for §4 and §5 re-invocations):**
+
+```bash
+npx skill-check --help 2>/dev/null | grep -- --no-security-scan
+```
+
+- If the probe matches `--no-security-scan`: set `{security_scan_flag} = "--no-security-scan"`.
+- Else run a second probe — `npx skill-check --help 2>/dev/null | grep -- --skip-security` — and if it matches, set `{security_scan_flag} = "--skip-security"`.
+- If neither flag exists: set `{security_scan_flag} = ""` (empty) AND set `{skill_check_flag_fallback} = true`. Skip §2 and §4 automated flows entirely — fall through to §3 manual frontmatter validation. Record in evidence-report: `skill_check_flag_probe: neither --no-security-scan nor --skip-security supported by installed skill-check; validation performed manually`.
+
+**If a security-scan-disable flag was resolved (probe succeeded):**
+
+```bash
+npx skill-check check <staging-skill-dir> --fix --format json {security_scan_flag}
+```
+
+This performs frontmatter validation, description quality checks, body limit enforcement, local link resolution, file formatting, auto-fix of deterministic issues, and quality scoring (0-100) across five weighted categories.
+
+**Parse the JSON output** for: `qualityScore` (0-100), `diagnostics[]` (remaining issues), `fixed[]` (auto-corrected issues).
+
+**Description Guard Protocol:** This invocation may modify SKILL.md (especially when `fixed[]` is non-empty). Wrap the `skill-check check --fix` call in the four-phase protocol defined in §0: capture `guarded_description` before the call, execute, verify against the post-tool description, and restore on divergence. If `fixed[]` is non-empty, also re-read the modified SKILL.md to sync the in-context copy before proceeding — this prevents silent divergence between the in-context and on-disk versions that step-07 will use for artifact generation.
+
+**Note:** `skill-check` may return non-zero exit code even when `errorCount` is 0. Always rely on parsed JSON, not the shell exit code.
+
+- **Score ≥ 70:** Record "Schema: PASS (score: {score}/100)" in evidence-report
+- **Score < 70:** Log remaining diagnostics as warnings, record "Schema: WARN — score {score}/100, {count} remaining issues", proceed
+- **Unfixable errors:** Record specific rule IDs and suggestions, proceed with warnings
+
+### 3. Validate Frontmatter (Fallback)
+
+**If skill-check was available:** Skip — already validated in step 2.
+
+**If skill-check NOT available (fallback):** Perform manual frontmatter compliance check:
+
+- [ ] Frontmatter present — file starts with `---` and has closing `---`
+- [ ] `name` field — present, non-empty, lowercase alphanumeric + hyphens only, 1-64 chars
+- [ ] `name` matches skill output directory name
+- [ ] `description` field — present, non-empty, 1-1024 characters
+- [ ] No unknown fields — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` permitted
+- [ ] `version` and `author` are NOT in frontmatter (they belong in metadata.json)
+
+If fails: auto-fix (deterministic), re-validate once, record result. If passes: record "Frontmatter: PASS".
+
+### 4. Split Oversized Body (if needed)
+
+**If step 2 reported `body.max_lines` failure:**
+
+**Description Guard Protocol:** Split operations may rewrite the frontmatter. Wrap the split invocation in the four-phase protocol defined in §0 to capture `guarded_description` before the call, execute, verify, and restore on divergence.
+
+**Mandatory approach — selective split:** Identify Tier 2 sections by their `## Full` heading prefix (e.g., `## Full API Reference`, `## Full Type Definitions`, `## Full Integration Patterns`). Extract ONLY those sections to `references/`, starting with the largest. Keep ALL Tier 1 content and any smaller sections inline. Inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval (per Vercel research).
+
+**FORBIDDEN:** Running `npx skill-check split-body --write` without prior selective extraction. The `split-body --write` command extracts ALL `##` sections top-to-bottom, destroying Tier 1 inline content that the two-tier design depends on. This command is a LAST RESORT only after selective split has been attempted and proven insufficient.
+
+**If selective split alone does not bring body under the limit** (rare — typically only occurs when Tier 1 itself exceeds 300 lines): reduce Tier 1 Key API Summary and Architecture at a Glance sections to fit within limits. Do NOT fall back to automated `split-body --write` to solve a Tier 1 sizing problem.
+
+**Tier 1 preservation check:** After ANY split operation, verify that ALL of the following sections remain inline in SKILL.md (not moved to references/): Overview, Quick Start, Common Workflows, Key API Summary, Migration & Deprecation Warnings (if present), Key Types, Architecture at a Glance, CLI (if present), Scripts & Assets (if present), Manual Sections. If any Tier 1 section was moved to references/, restore it immediately and re-split targeting only Tier 2 sections.
+
+**Post-split Tier-1 count check (mandatory):** before invoking the splitter, count the Tier-1 `##`-level section headings present in SKILL.md (any heading whose title matches one of the Tier-1 names listed above) and store as `tier1_count_pre`. After the split completes, recount as `tier1_count_post`. **HALT** if `tier1_count_post < tier1_count_pre` with: "Split reduced Tier-1 section count from {pre} to {post}. Tier-1 sections must remain inline. Restoring from staging backup and aborting body split — manual review required." Do not proceed past §4 — Tier-1 preservation is a hard invariant and a count drop indicates the splitter pulled an inline section into references/ regardless of the section-list check above (e.g., heading-text variation, capitalization, or the splitter's own heuristics).
+
+**Anchor validation and remediation:** After any split, verify that context-snippet section anchors (`#quick-start`, `#key-types`) still resolve to headings in SKILL.md. If an anchor no longer resolves (section was split out), restore that section to SKILL.md inline content — the context-snippet must always reference sections that exist in the main file.
+
+Then re-validate: `npx skill-check check <staging-skill-dir> --format json {security_scan_flag}` — use the flag cached from §2's probe. If `{skill_check_flag_fallback}` is true, skip re-validation and rely on the §3 manual check.
+
+**If skill-check unavailable or no body size issue:** Skip.
+
+### 5. Security Scan
+
+**If skill-check available:**
+
+```bash
+npx skill-check check <staging-skill-dir> --format json
+```
+
+(Security scan enabled by default when `--no-security-scan` omitted. The scan uses [Snyk](https://docs.snyk.io/) to check for prompt injection risks, sensitive data exposure, and unsafe tool permissions.)
+
+Record any security warnings in evidence-report. Security findings are advisory — they do not block artifact generation. If the full validation re-run produces a different quality score than section 2, update the evidence-report with the newer score.
+
+**If security scan fails due to missing SNYK_TOKEN:**
+
+Display: "Security scan requires a Snyk Enterprise API token ([docs](https://docs.snyk.io/snyk-api/authentication-for-api)). Set `SNYK_TOKEN=your-token` in environment or `.env`, then re-run [SF] Setup Forge. Without Enterprise, use `--no-security-scan` to skip. Security scanning is optional and does not block skill compilation."
+
+Record: "Security scan skipped — SNYK_TOKEN not configured"
+
+**If skill-check unavailable:** Skip with note: "Security scan skipped — skill-check tool unavailable"
+
+### 6. Content Quality Review (tessl)
+
+**If tessl available**, run: `timeout 120s npx -y tessl skill review <staging-skill-dir>` — the 120s cap matches skf-test-skill's tessl invocation guard and prevents a stalled LLM call in tessl from blocking compilation. On timeout, treat the step as unavailable and record `tessl: timeout — content quality review skipped` in the evidence report.
+
+Parse output for: `description_score`, `content_score`, `review_score`, `validation_result`, `judge_suggestions[]`.
+
+**Load dismissal rules:** Before interpreting any findings, load `{tesslDismissalData}` completely. This file is the single source of truth for tessl findings that SKF expects and must dismiss. It defines score thresholds, suggestion dismissal patterns, and the action to take when each rule matches.
+
+**Apply dismissal rules** in this order:
+
+1. **Check score thresholds** against the "Score Thresholds" table in `{tesslDismissalData}`. Most importantly:
+   - If `description_score < 100`: follow the **recover-then-halt** path defined by the `description-xml-tags-guarded-upstream` rule in `{tesslDismissalData}`. Re-apply step-05 §2a's `<`/`>` → `{`/`}` substitution in place on the staging SKILL.md frontmatter `description`, re-sync the in-context copy, and re-run `npx -y tessl skill review <staging-skill-dir>` once. **Re-run gate:** treat `description_score == 100` on the re-run as the only successful recovery outcome. ANY value strictly less than 100 on the re-run — including 99, intermediate-but-improved scores like 95 (formerly tolerated as "close enough"), or 0 — counts as recovery failure: halt with the original `description-xml-tags-guarded-upstream` failure message from `{tesslDismissalData}`, do NOT proceed to §6b, and do NOT downgrade the recovery to a warning. If the re-run produces `description_score == 100`, log `description-recovery: applied ({count} substitutions)` in the evidence report under "Dismissed tessl suggestions" and continue suggestion iteration against the rerun's `judge_suggestions[]`.
+   - If `review_score < 60` or `content_score < 60`: record warnings in the evidence report, continue.
+2. **Iterate `judge_suggestions[]`.** For each suggestion:
+   - Cross-reference against the rules in `{tesslDismissalData}` in order.
+   - If a rule matches: record `{rule_id, rationale, suggestion_text}` under "Dismissed tessl suggestions" in the evidence report. Do not apply.
+   - If no rule matches: add to the "Novel tessl suggestions" list for §6b to surface to the user.
+3. **Short-circuit when empty.** If every suggestion was dismissed (no novel suggestions), §6b has nothing to show — auto-proceed to §7.
+
+- **Unavailable:** Skip with note: "Content quality review skipped — tessl tool unavailable"
+
+tessl installs automatically via `npx`. A missing tool is not an error — graceful skip.
+
+#### 6b. User Decision Gate (conditional)
+
+**If §6 produced no novel suggestions (all dismissed via `{tesslDismissalData}`) OR tessl was unavailable:** Skip this gate — auto-proceed.
+
+**If §6 produced novel suggestions** (ones not matched by any dismissal rule), present them to the user:
+
+"**Content quality review: {score}%**
+
+tessl suggestions (novel — not matched by `{tesslDismissalData}`):
+{numbered list of novel suggestions}
+
+**Select an option:**
+- **[S] Skip** — proceed with current content as-is (default)
+- **[A] Apply structural fixes** — apply only structural suggestions (split sections, consolidate duplicates). No new content generated.
+- **[R] Review all** — show each suggestion with proposed changes before applying"
+
+#### Gate Rules:
+
+- **Structural suggestions** (split reference section, consolidate duplicates, reorder sections) can be applied without zero-hallucination risk — they restructure existing content
+- **Semantic suggestions** (add examples, add error handling, add validation checkpoints) introduce content not verified from source code. If the user chooses to apply these:
+  - Warn: "This adds content not verified from source code."
+  - Mark applied content with `<!-- [TESSL:auto-fix] -->` markers
+  - Cite as `[TESSL:suggestion]` in the provenance map with `confidence: "TESSL"` (below T3)
+  - Record in evidence report: "TESSL-suggested content applied: {count} items (unverified)"
+- **If user selects [S]:** Record "tessl suggestions: skipped by user" in evidence report. Proceed to section 7.
+- **If user selects [A]:** Apply structural fixes only, re-run tessl to capture updated score, record results. Proceed to section 7.
+- **If user selects [R]:** Show each suggestion with the proposed change. For each, user confirms or skips. Apply confirmed changes, record results. Proceed to section 7.
+
+### 7. Validate metadata.json
+
+Cross-check metadata.json against extraction inventory:
+- `stats.exports_documented` / `stats.exports_public_api` / `stats.exports_internal` / `stats.exports_total` are accurate
+- `stats.public_api_coverage` and `stats.total_coverage` are correctly computed (null when denominator is 0)
+- `confidence_distribution.t1`, `confidence_distribution.t1_low`, `confidence_distribution.t2`, `confidence_distribution.t3` match actual counts
+- `spec_version` is "1.3"
+- If `scripts[]` or `assets[]` arrays present: verify `stats.scripts_count`/`stats.assets_count` match array lengths; verify `file_entries` count in provenance-map.json matches
+
+Auto-fix any discrepancies (these are computed values).
+
+### 8. Update Evidence Report
+
+Add validation results to evidence-report content in context:
+
+```markdown
+## Validation Results
+- Schema: {pass/fail} (quality score: {score}/100)
+- Frontmatter: {pass/fail}
+- Body: {pass/fail} {split-body applied if applicable}
+- Security: {pass/warn/skipped}
+- Content Quality (tessl): {pass/warn/skipped} (score: {score}%)
+- Metadata: {pass/fail}
+
+## Quality Score Breakdown
+- Frontmatter (30%): {score} | Description (30%): {score} | Body (20%): {score} | Links (10%): {score} | File (10%): {score}
+
+## Description Guard
+- Restored: {true/false}
+- Triggering tool: {tool_name or —}
+- Original description preserved: {true/false}
+- Notes: {one-sentence detail or —}
+
+## Auto-Fixed Issues
+- {list of issues automatically corrected by --fix}
+
+## Remaining Warnings / Security Findings / Content Quality (tessl)
+- {warnings, security results, tessl scores and suggestions — or "skipped"}
+```
+
+**Description Guard population:** if the §0 protocol fired during §2 (`skill-check --fix`) or §4 (`split-body`), fill the four Description Guard fields from context:
+
+- `Restored: true` when `description_guard_restored == true`, otherwise `false`.
+- `Triggering tool`: the tool name recorded by §0 (`skill-check --fix`, `skill-check split-body`, etc.), or `—` if the guard did not fire.
+- `Original description preserved`: `true` if the restore succeeded (on-disk now matches the pre-tool snapshot), `false` if restoration itself failed (rare — treat as a halt condition in a future version).
+- `Notes`: a one-sentence description of what the tool had changed. Typical values: `"replaced with generic summary"`, `"truncated at N chars"`, `"angle-bracket tokens re-introduced"`, `"field deleted entirely"`. If `Restored: false`, use `—`.
+
+When `Restored: false`, the three follow-up fields are all `—` — this is the clean-run expected state.
+
+### 9. Menu Handling Logic
+
+**Conditional interaction step.** If tessl produced suggestions, section 6b halts for user input. Otherwise, auto-proceed.
+
+After validation completes (including any user decisions from section 6b), immediately load, read entire file, then execute `{nextStepFile}`.
+
+- Tool unavailability is a skip, not a halt
+- Validation failures are warnings — proceed to artifact generation
+- tessl gate only triggers when suggestions exist — no gate for clean reviews or unavailable tools
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN validation is complete (or skipped) and evidence-report content is updated will you proceed to load `{nextStepFile}` for artifact generation.
+