bmad-module-skill-forge 0.2.0 → 0.4.0

package/src/workflows/create-skill/steps-c/step-04-enrich.md

@@ -61,15 +61,40 @@ Auto-proceed silently. Display no message. Immediately load, read entire file, t
 
 Continue to step 2.
 
-### 2. QMD Enrichment Searches (Deep Tier Only)
+### 2. Collection Inventory Pre-check (Deep Tier Only)
 
-For each major exported function in the extraction inventory, search QMD collections for temporal context:
+Before searching, check which QMD collections are available:
 
-**Search targets per function:**
+1. Read the sidecar `forge-tier.yaml` to get registered `qmd_collections` entries
+2. Identify which collections contain enrichment context — collections with `type` equal to `"temporal"` (issues, PRs, changelogs) or `"docs"` (fetched external documentation). Do NOT include `"extraction"` or `"brief"` type collections.
+3. **If no enrichment collections exist** (no `"temporal"` or `"docs"` type collections): report this and auto-proceed. Display:
 
-1. **Issues/PRs:** `qmd_bridge.search("{function_name}")` — find related discussions, bug reports, feature requests
-2. **Changelog entries:** `qmd_bridge.search("{function_name} changelog")` — find version history, breaking changes
-3. **Migration notes:** `qmd_bridge.vector_search("{function_name} migration deprecated")` — find deprecation or migration context
+"**Enrichment: no enrichment collections available.**
+Only brief-type or extraction-type QMD collections found — no temporal context (issues, PRs, changelogs) or docs collections indexed. Enrichment skipped (expected for first-run skill creation). Enrichment becomes available when temporal or docs context is indexed into QMD collections.
+
+Proceeding to compilation..."
+
+Then immediately load, read entire file, then execute `{nextStepFile}`.
+
+4. **If temporal collections exist:** Continue to step 3.
+
+### 3. QMD Enrichment Searches (Deep Tier Only)
+
+For each major exported function — limited to the **top-level public API surface** (typically 10-20 functions that will appear in the context-snippet), not all extracted exports — search the temporal QMD collections for context:
+
+**Search query construction:**
+
+For each function, derive the **module context** from the extraction inventory's source file path (e.g., `src/graph/neo4j/index.ts` → module context `graph neo4j`). This context improves search relevance by scoping results to the function's subsystem without adding extra queries.
+
+**Primary searches (BM25 — always runs, no GPU/VRAM dependency):**
+
+1. **Issues/PRs:** `qmd_bridge.search("{module_context} {function_name}")` — find related discussions scoped by module context
+2. **Changelog entries:** `qmd_bridge.search("{function_name} changelog")` — find version history, breaking changes (kept generic — changelogs rarely use module paths)
+3. **Migration notes:** `qmd_bridge.search("{function_name} migration deprecated breaking")` — find deprecation or migration context using exact keyword matching
+
+**Supplemental search (best-effort — requires GPU/VRAM, may fail):**
+
+4. **Semantic migration context:** `qmd_bridge.vector_search("{module_context} {function_name} migration deprecated")` — adds semantic matches (synonyms, paraphrases) that BM25 keyword search may miss. Merge results with search #3, deduplicating by document ID. If `vector_search` fails (VRAM, GPU driver, model loading), discard silently — the BM25 results from search #3 provide baseline coverage.
 
 **For each QMD result:**
 
@@ -84,7 +109,7 @@ For each major exported function in the extraction inventory, search QMD collect
 - If individual search fails: skip that function's enrichment, continue with others
 - If QMD returns no results for a function: no annotation added (absence is normal)
 
-### 3. Annotate Extraction Inventory
+### 4. Annotate Extraction Inventory
 
 Add enrichment annotations to the extraction inventory without modifying extraction data:
 
@@ -100,7 +125,7 @@ Add enrichment annotations to the extraction inventory without modifying extract
 - T2-past annotations: {count}
 - T2-future annotations: {count}
 
-### 4. Report Enrichment (Deep Tier Only)
+### 5. Report Enrichment (Deep Tier Only)
 
 Display brief enrichment summary:
 
@@ -111,7 +136,7 @@ Display brief enrichment summary:
 
 Proceeding to compilation..."
 
-### 5. Menu Handling Logic
+### 6. Menu Handling Logic
 
 **Auto-proceed step — no user interaction.**
 
@@ -135,7 +160,9 @@ ONLY WHEN enrichment is complete (Deep tier) or the step is skipped (Quick/Forge
 ### ✅ SUCCESS:
 
 - Quick/Forge tiers: skipped silently with no output, auto-proceeded
-- Deep tier: QMD searches performed per extracted function
+- Deep tier: collection inventory checked before searching
+- Deep tier: no temporal collections → reported and auto-proceeded (not silently skipped)
+- Deep tier: temporal collections exist → QMD searches performed per public API function (10-20, not all exports) with module context derived from extraction inventory source paths
 - T2 annotations added with proper provenance citations
 - Extraction data unmodified — enrichment is additive only
 - QMD failures handled gracefully (skip and continue)
@@ -146,6 +173,9 @@ ONLY WHEN enrichment is complete (Deep tier) or the step is skipped (Quick/Forge
 - Halting on QMD unavailability or search failures
 - Modifying T1 extraction results with QMD data
 - Displaying skip messages for Quick/Forge tiers (should be silent)
+- Pre-emptively skipping all searches without checking the collection inventory
+- Searching all 800+ exports instead of scoping to public API surface (10-20)
+- Using bare function names without module context when source path is available in extraction inventory
 - Beginning compilation or SKILL.md assembly in this step
 - Not labeling QMD annotations as T2 confidence
 

package/src/workflows/create-skill/steps-c/step-05-compile.md

@@ -3,6 +3,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'
 ---
 
 # Step 5: Compile
@@ -30,103 +31,73 @@ To assemble the complete skill content from the extraction inventory and enrichm
 
 - 🎯 Focus ONLY on assembling content from extraction inventory + enrichment
 - 🚫 FORBIDDEN to include any content without a provenance citation
-- 🚫 FORBIDDEN to write files — content stays in context until step-07
+- 💾 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 — do not write files
+- 💾 Build all content in context or write to a staging directory (`_bmad-output/{name}/`)
 - 📖 Follow agentskills.io section structure from data file
-- 🚫 Do not write any output files — that's step-07
+- 🚫 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), brief_data, tier
+- Available: extraction_inventory, enrichment_annotations (if Deep), doc_fetch_inventory (if doc_urls), brief_data, tier
 - Focus: Assembling structured content from verified data
-- Limits: Do NOT write files, validate spec compliance, or report
+- 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)
 
 ## MANDATORY SEQUENCE
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
 
-### 1. Load Section Structure
+### 1. Load Data Files
 
-Load `{skillSectionsData}` completely. This defines the agentskills.io-compliant format for all output artifacts.
+Load `{skillSectionsData}` and `{assemblyRulesData}` completely. These define the agentskills.io-compliant format and detailed assembly rules for all output artifacts.
 
 ### 2. Build SKILL.md Content
 
-Assemble each section in order from the skill-sections data file:
-
-**Frontmatter:**
-```yaml
----
-name: {brief.name}
-version: {brief.version}
-description: {brief.name} — {export_count} verified functions
-author: {source_author}
----
-```
-
-**Section 1 — Overview:**
-- What this skill provides
-- Source repo, version, branch
-- Forge tier used for compilation
-- Export count and confidence summary
-
-**Section 2 — Quick Start:**
-- Select the 3-5 most commonly used functions (by import frequency or documentation prominence)
-- Minimal usage examples — ONLY from source tests or official docs
-- If no examples exist in source, show signature-only quick start
-- Provenance citation for each function
-
-**Section 3 — API Reference:**
-- Group by module/file
-- For each exported function:
-  - Full signature with types
-  - Parameters table (name, type, required/optional, description)
-  - Return type
-  - Usage example (from source tests/docs ONLY — omit if none found)
-  - Provenance citation: `[AST:{file}:L{line}]` or `[SRC:{file}:L{line}]`
-  - T2 annotations (Deep tier only): temporal context from enrichment
-
-**Section 4 — Type Definitions:**
-- All exported types, interfaces, enums
-- Full type signatures with provenance citations
-
-**Section 5 — Integration Patterns (Forge/Deep only):**
-- Co-import patterns detected by ast_bridge
-- Common usage combinations
-- Skip for Quick tier (no co-import data available)
-
-**Section 6 — Manual Sections:**
-- Seed empty `<!-- [MANUAL] -->` markers:
-```markdown
-<!-- [MANUAL:additional-notes] -->
-<!-- Add custom notes here. This section is preserved during skill updates. -->
-<!-- [/MANUAL:additional-notes] -->
-```
-- Place after Quick Start and after API Reference sections
+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), Tier 2 section details (Sections 9-11), and assembly ordering rules. Follow it exactly.
 
 ### 3. Build context-snippet.md Content
 
-Compressed 2-line format for CLAUDE.md managed section:
+Vercel-aligned indexed format for CLAUDE.md managed section (~80-120 tokens):
 
 ```markdown
-{skill-name} -> skills/{skill-name}/
-  exports: {comma-separated top 10 function names}
+[{skill-name} v{version}]|root: skills/{skill-name}/
+|IMPORTANT: {skill-name} v{version} — read SKILL.md before writing {skill-name} code. Do NOT rely on training data.
+|quick-start:{SKILL.md#quick-start}
+|api: {top exports with () for functions, comma-separated}
+|key-types:{SKILL.md#key-types} — {inline summary of most important type values}
+|gotchas: {2-3 most critical pitfalls or breaking changes, inline}
 ```
 
+**Derivation rules:**
+
+- **version**: From source detection (reconciled in step-03), not brief default
+- **api**: Top 10 exports from extraction inventory, append `()` to function names
+- **key-types**: Inline summary of most important enum/type values from Key Types section
+- **gotchas**: Derived from T2-future annotations (breaking changes), async requirements, version-specific behavior changes. If no gotchas available, omit the gotchas line.
+- **Section anchors** (`#quick-start`, `#key-types`): Must match actual heading slugs in the assembled SKILL.md
+
 ### 4. Build metadata.json Content
 
 Following the structure from the skill-sections data file:
 - Populate all fields from brief_data, extraction inventory, and tier
-- Set `generated_at` to current ISO-8601 timestamp
+- Set `generation_date` to current ISO-8601 timestamp
 - Set `source_commit` from resolved source (if available)
-- Set `stats` from extraction aggregate counts
-- Set `tool_versions` based on tier and available tools
+- Set `stats` from extraction aggregate counts:
+  - `exports_documented`: count of exports with documentation in the assembled SKILL.md
+  - `exports_public_api`: count of exports from public entry points (`__init__.py`, `index.ts`, `lib.rs`, or equivalent)
+  - `exports_internal`: count of all other non-underscore-prefixed exports (internal modules, helpers, adapters)
+  - `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)
+- Set `tool_versions` based on tier and available tools. Resolve `{skf_version}` from the SKF module's `package.json` `version` field (run `node -p "require('./node_modules/bmad-module-skill-forge/package.json').version"` or read the installed module's `package.json`). If unresolvable, fall back to `git describe --tags --abbrev=0` in the SKF module root. Never hardcode the version.
 
 ### 5. Build references/ Content
 
@@ -140,37 +111,27 @@ Group functions logically by module, file, or functional area.
 
 ### 6. Build provenance-map.json Content
 
-One entry per extracted claim:
-- claim text
-- source_file and source_line
-- confidence tier (T1, T1-low, T2)
-- extraction_method (ast_bridge.scan_definitions, gh_bridge.read_file, qmd_bridge.search)
-- ast_node_type (if AST-extracted)
+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. See `{skillSectionsData}` for full schema.
 
 ### 7. Build evidence-report.md Content
 
-Compilation audit trail:
-- Generation date, forge tier, source info
-- Tool versions used
-- Extraction summary (files scanned, exports found, confidence breakdown)
-- Validation results (populated in step-06)
-- Warnings from extraction or enrichment
+Compilation audit trail: generation date, forge tier, source info, tool versions, extraction summary (files/exports/confidence), validation results (populated in step-06), warnings. See `{skillSectionsData}` for full template. Use the same `{skf_version}` value resolved in section 4 when populating the Tool Versions block.
 
 ### 8. Menu Handling Logic
 
 **Auto-proceed step — no user interaction.**
 
-After all content is assembled in context, immediately load, read entire file, then execute `{nextStepFile}`.
+After all content is assembled in context (or 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 — no files are written yet
+- All content stays in context or in the staging directory — no final files are written yet
 - Proceed directly to validation after assembly is complete
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN all 7 content artifacts (SKILL.md, context-snippet.md, metadata.json, references/, provenance-map.json, evidence-report.md, extraction-rules.yaml) are assembled in context will you proceed to load `{nextStepFile}` for spec validation.
+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.
 
 ---
 
@@ -178,8 +139,11 @@ ONLY WHEN all 7 content artifacts (SKILL.md, context-snippet.md, metadata.json,
 
 ### ✅ SUCCESS:
 
-- Skill-sections data file loaded and followed
+- 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
@@ -190,9 +154,12 @@ ONLY WHEN all 7 content artifacts (SKILL.md, context-snippet.md, metadata.json,
 
 - Including functions or examples without provenance citations
 - Fabricating usage examples not found in source
-- Writing files to disk (that's step-07)
+- 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 7 content artifacts
+- 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/workflows/create-skill/steps-c/step-06-validate.md

@@ -1,6 +1,6 @@
 ---
 name: 'step-06-validate'
-description: 'Validate compiled skill content against agentskills.io spec via skills_ref'
+description: 'Validate compiled skill content against agentskills.io spec via skill-check'
 nextStepFile: './step-07-generate-artifacts.md'
 ---
 
@@ -8,7 +8,7 @@ nextStepFile: './step-07-generate-artifacts.md'
 
 ## STEP GOAL:
 
-To validate the compiled SKILL.md content against the agentskills.io specification using skills_ref, auto-fix any validation failures, and confirm spec compliance before artifact generation.
+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.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -29,9 +29,10 @@ To validate the compiled SKILL.md content against the agentskills.io specificati
 
 - 🎯 Focus ONLY on validating compiled content against spec
 - 🚫 FORBIDDEN to add new content — only fix spec compliance issues
-- 🚫 FORBIDDEN to write files — content stays in context until step-07
+- 💾 Validation and auto-fix modify files in the staging directory (`_bmad-output/{name}/`)
 - 💬 If auto-fix fails, report issues clearly but proceed (warn, don't halt)
-- ⚙️ If skills_ref unavailable: skip validation, add warning to evidence report
+- ⚙️ If skill-check unavailable: skip validation, add warning to evidence report
+- ⚠️ Ignore non-zero exit codes from `skill-check` if the JSON output shows 0 errors — parse JSON output, not exit codes
 
 ## EXECUTION PROTOCOLS:
 
@@ -39,6 +40,7 @@ To validate the compiled SKILL.md content against the agentskills.io specificati
 - 💾 Validation results are added to evidence-report content in context
 - 📖 Auto-fix pattern: validate → fix → re-validate (once)
 - 🚫 Maximum one auto-fix attempt per validation failure
+- ⏸️ **Conditional interaction:** If tessl returns suggestions (section 6b), halt for user input. Otherwise auto-proceed. This is a conditional gate step, not a pure auto-proceed step.
 
 ## CONTEXT BOUNDARIES:
 
@@ -53,85 +55,171 @@ To validate the compiled SKILL.md content against the agentskills.io specificati
 
 ### 1. Check Tool Availability
 
-**If skills_ref tool is available:**
-Continue to validation steps.
+Run: `npx skill-check -h`
 
-**If skills_ref tool is NOT available:**
-- Add warning to evidence-report content: "Spec validation skipped — skills_ref tool unavailable"
-- Auto-proceed to next step
+- If succeeds: Continue to automated validation (section 2)
+- If fails: Perform manual fallback (section 3); add note to evidence-report: "Spec validation performed manually — skill-check tool unavailable"
 
-### 2. Validate Schema
+**Important:** Do not assume availability — empirical check required.
 
-Use `skills_ref.validate_schema()` against the compiled SKILL.md content.
+### 2. Validate & Auto-Fix (skill-check check --fix)
 
-**Check:**
-- Required sections present (Overview, Quick Start, API Reference, Type Definitions)
-- Section order follows agentskills.io standard
-- Frontmatter contains required fields (name, version, description, author)
-- Provenance citations present in API Reference entries
+Run the external skill-check tool against the compiled skill staging directory:
 
-**If validation passes:** Record "Schema: PASS" in evidence-report content.
+```bash
+npx skill-check check <staging-skill-dir> --fix --format json --no-security-scan
+```
+
+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).
+
+**Context sync after --fix:** If `fixed[]` is non-empty (i.e., `--fix` modified files on disk), re-read the modified SKILL.md to update the in-context copy. Verify the re-read content matches expectations before proceeding. This prevents silent divergence between the in-context SKILL.md and the on-disk version 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:**
+
+```bash
+npx skill-check split-body <staging-skill-dir> --write
+```
+
+Then re-validate: `npx skill-check check <staging-skill-dir> --format json --no-security-scan`
+
+**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 Agent Scan](https://github.com/snyk/agent-scan) 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 security scan fails due to missing SNYK_TOKEN:**
+
+Display actionable guidance:
+
+"Security scan requires a Snyk API token. **Important:** The Snyk API requires an Enterprise plan ([authentication docs](https://docs.snyk.io/snyk-api/authentication-for-api)). To enable:
+1. Obtain a Snyk Enterprise account with API access
+2. Get your API token from Account Settings → API Token
+3. Set `SNYK_TOKEN=your-token` in your environment or `.env`
+4. Re-run [SF] Setup Forge to update tool detection, then re-run [CS] Create Skill
+
+If you don't have an Enterprise account, use `--no-security-scan` flag in skill-check to skip, or `--security-scan-runner pipx|uvx|local` to control the execution method. Security scanning is optional and does not affect tier level or 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 validation fails:**
-1. Identify specific failures
-2. Attempt auto-fix (structural adjustments only — never invent content)
-3. Re-validate once
-4. If still failing: record "Schema: FAIL — {specific issues}" in evidence-report, add warnings, but proceed
+**If tessl available**, run: `npx -y tessl skill review <staging-skill-dir>`
 
-### 3. Validate Frontmatter
+Parse output for: `description_score`, `content_score`, `average_score`, `validation_result`, `judge_suggestions[]`.
 
-Use `skills_ref.validate_frontmatter()` against the SKILL.md frontmatter.
+- **Content score < 70%:** Record warning: "Content quality warning: tessl scored content at {score}%."
+- **Unavailable:** Skip with note: "Content quality review skipped — tessl tool unavailable"
 
-**Check:**
-- `name` matches brief.name (kebab-case)
-- `version` matches brief.version
-- `description` follows format: "{name} — {count} verified functions"
-- `author` is set
+> **EXPECTED BEHAVIOR — Two-Tier Scoring:** The Skill Forge two-tier design (Tier 1 Key API Summary + Tier 2 Full API Reference) intentionally includes progressive disclosure. tessl's `conciseness` scorer will flag this as redundancy (typically scoring 2/3), which is **expected behavior — not a defect**. tessl may also suggest removing `[MANUAL]` markers, moving Full API Reference to a separate file, or consolidating duplicate parameter documentation — **all three suggestions conflict with SKF design principles and must be dismissed.** Acceptable threshold: content scores >= 60% are normal for two-tier skills. Do NOT consolidate Tier 1 and Tier 2 content to improve the score — the two-tier structure is a deliberate design choice for standalone usability.
 
-**If validation passes:** Record "Frontmatter: PASS" in evidence-report content.
+tessl installs automatically via `npx`. A missing tool is not an error — graceful skip.
 
-**If validation fails:**
-1. Auto-fix frontmatter (these are deterministic fixes)
-2. Re-validate once
-3. Record result in evidence-report
+#### 6b. User Decision Gate (conditional)
 
-### 4. Validate metadata.json
+**If tessl returned no suggestions OR tessl was unavailable:** Skip this gate — auto-proceed.
 
-Cross-check metadata.json content against extraction inventory:
-- `stats.exports_documented` matches actual documented exports
-- `stats.exports_total` matches total extracted exports
-- `stats.coverage` is accurate (documented / total)
+**If tessl returned suggestions**, present them to the user:
+
+"**Content quality review: {score}%**
+
+tessl suggestions:
+{numbered list of judge_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_t1`, `confidence_t2`, `confidence_t3` match actual counts
 - `spec_version` is "1.3"
 
 Auto-fix any discrepancies (these are computed values).
 
-### 5. Update Evidence Report
+### 8. Update Evidence Report
 
-Add validation results to the evidence-report content in context:
+Add validation results to evidence-report content in context:
 
 ```markdown
 ## Validation Results
-- Schema: {pass/fail}
+- 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}
 
-## Warnings
-- {any warnings from validation}
-```
+## Quality Score Breakdown
+- Frontmatter (30%): {score} | Description (30%): {score} | Body (20%): {score} | Links (10%): {score} | File (10%): {score}
 
-### 6. Menu Handling Logic
+## 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"}
+```
 
-**Auto-proceed step — no user interaction.**
+### 9. Menu Handling Logic
 
-After validation is complete (or skipped if tools unavailable), immediately load, read entire file, then execute `{nextStepFile}`.
+**Conditional interaction step.** If tessl produced suggestions, section 6b halts for user input. Otherwise, auto-proceed.
 
-#### EXECUTION RULES:
+After validation completes (including any user decisions from section 6b), immediately load, read entire file, then execute `{nextStepFile}`.
 
-- This is an auto-proceed validation step with no user choices
 - Tool unavailability is a skip, not a halt
 - Validation failures are warnings — proceed to artifact generation
-- Proceed directly to next step after validation completes
+- tessl gate only triggers when suggestions exist — no gate for clean reviews or unavailable tools
 
 ## CRITICAL STEP COMPLETION NOTE
 
@@ -143,20 +231,21 @@ ONLY WHEN validation is complete (or skipped) and evidence-report content is upd
 
 ### ✅ SUCCESS:
 
-- Schema validation attempted (or skipped with warning if tool unavailable)
-- Frontmatter validation attempted
-- Metadata cross-check performed
-- Auto-fix applied for deterministic failures
-- Evidence report updated with validation results
-- Warnings recorded for any failures
-- Auto-proceeded to step-07
+- `npx skill-check check --fix --format json` executed (or skipped with warning if unavailable)
+- Quality score captured and recorded; auto-fix applied for deterministic issues
+- Split-body applied if `body.max_lines` failed; security scan executed (or skipped with warning)
+- `npx -y tessl skill review` executed (or skipped); content quality warning raised if score < 70%
+- tessl suggestions presented to user when available; user decision recorded
+- TESSL-applied content marked with `<!-- [TESSL:auto-fix] -->` and cited as `[TESSL:suggestion]`
+- Metadata cross-check performed; evidence report updated with structured results
+- Proceeded to step-07 (auto or after user gate)
 
 ### ❌ SYSTEM FAILURE:
 
-- Halting the workflow on validation failure (should warn and proceed)
-- Halting on skills_ref unavailability (should skip with warning)
-- Adding new content during validation (only structural fixes allowed)
-- Not recording validation results in evidence report
+- Halting on validation failure or skill-check unavailability (should warn and proceed)
+- Adding new content during validation without user approval via the tessl gate
+- Applying semantic tessl suggestions without warning the user about unverified content
+- Not recording quality score; skipping security scan without recording the skip
 - Attempting more than one auto-fix cycle per failure
 
-**Master Rule:** Validation informs, it does not block. Record results, fix what's deterministic, warn about the rest, and proceed.
+**Master Rule:** Validation informs, it does not block. Record results, fix what's deterministic, scan for security issues, warn about the rest, and proceed.