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

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

@@ -1,8 +1,6 @@
 ---
-name: 'step-05-write-brief'
-description: 'Generate and write skill-brief.yaml to the forge data folder'
-
-briefSchemaFile: '../data/skill-brief-schema.md'
+briefSchemaFile: 'assets/skill-brief-schema.md'
+nextStepFile: './step-06-health-check.md'
 ---
 
 # Step 5: Write Brief
@@ -11,43 +9,12 @@ briefSchemaFile: '../data/skill-brief-schema.md'
 
 To generate the complete skill-brief.yaml from the approved brief data and write it to the forge data folder, completing the brief-skill workflow.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-
-### Role Reinforcement:
-
-- ✅ You are a skill brief generator in Ferris Architect mode
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Generate output precisely matching the schema — no creative embellishment
-- ✅ This is the final step — deliver clean, validated output
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on writing the file — all decisions have been made
-- 🚫 FORBIDDEN to change any field values without user request — the brief was already approved
-- 💬 Approach: Prescriptive — generate exact YAML matching the schema template
-- 📋 Create the output directory if it doesn't exist
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Write skill-brief.yaml to {forge_data_folder}/{skill-name}/
-- 📖 This is the final step — mark workflow complete
-- 🚫 FORBIDDEN to modify approved field values
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available context: Complete approved brief data from steps 01-04
-- Focus: File generation and writing
-- Limits: No field changes — write exactly what was approved
-- Dependencies: Explicit user approval from step 04
+- Focus only on writing the file — all decisions have been made
+- Do not change any field values without user request — the brief was already approved
+- Create the output directory if it doesn't exist
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing success summary is NOT the terminal step
 
 ## MANDATORY SEQUENCE
 
@@ -216,37 +183,11 @@ After compilation, you can:
 
 **Brief-skill workflow complete.**"
 
-### 7. End Workflow
+### 7. Chain to Health Check
 
-This is the final step. No next step file to load. The workflow is complete.
+ONLY WHEN the brief file has been written and the success summary displayed will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the FINAL step of the brief-skill workflow. After writing the file and displaying the success summary, the workflow ends.
-
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Schema loaded for template reference
-- Output directory created (or fallback used with notification)
-- skill-brief.yaml generated with all required fields matching approved values
-- File written successfully to correct location
-- Deep tier: QMD collection `{skill-name}-brief` created/updated and registered in forge-tier.yaml
-- Non-Deep tier: QMD indexing skipped silently
-- Success summary displayed with next steps recommendation
-- Workflow marked as complete
-
-### ❌ SYSTEM FAILURE:
-
-- Modifying approved field values without user request
-- Writing to wrong location
-- Missing required fields in generated YAML
-- Not creating output directory before writing
-- Not displaying next steps recommendation
-- Not handling write failure gracefully
-- Failing the workflow due to QMD indexing errors (should degrade gracefully)
+This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the brief-skill workflow is fully done.
 
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. QMD indexing failures never block the workflow.

package/src/skf-brief-skill/steps-c/step-06-health-check.md

@@ -0,0 +1,22 @@
+---
+# `shared/health-check.md` resolves relative to the SKF module root
+# (`_bmad/skf/` when installed, `src/` during development), NOT relative
+# to this step file.
+nextStepFile: 'shared/health-check.md'
+---
+
+# Step 6: Workflow Health Check
+
+## STEP GOAL:
+
+Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of brief-skill — after the shared health check completes, the workflow is fully done.
+
+## Rules
+
+- No user-facing reports, file writes, or result contracts in this step — those belong in step-05
+- Delegate directly to `{nextStepFile}` with no additional commentary
+- Do not attempt any other action between loading this step and executing `{nextStepFile}`
+
+## MANDATORY SEQUENCE
+
+Load `{nextStepFile}`, read it fully, then execute it.

package/src/skf-create-skill/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: skf-create-skill
+description: Compile a skill from a brief. Supports --batch for multiple briefs. Use when the user requests to "create a skill" or "compile a skill."
+---
+
+# Create Skill
+
+## Overview
+
+Compiles a verified agent skill from a skill-brief.yaml and source code, producing an agentskills.io-compliant SKILL.md with provenance map, evidence report, and progressive disclosure references. The workflow is mostly autonomous with three interaction points — after ecosystem check (if match found), after source extraction (to confirm findings), and after content quality review (when tessl produces suggestions). Steps adapt behavior based on forge tier (Quick/Forge/Forge+/Deep). Zero hallucination tolerance: every instruction in the output must trace to source code with a confidence tier citation.
+
+## Role
+
+You are operating in Ferris Architect mode — a skill compilation engine performing structural extraction and assembly. Apply zero hallucination tolerance: uncitable content is excluded, not guessed.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- Never include content in SKILL.md that cannot be cited to source code
+- Read each step file completely before taking any action
+- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
+- Only load one step file at a time — never preload future steps
+- Always communicate in `{communication_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+
+## Stages
+
+| # | Step | File | Auto-proceed |
+|---|------|------|--------------|
+| 1 | Load Brief | steps-c/step-01-load-brief.md | Yes |
+| 2 | Ecosystem Check | steps-c/step-02-ecosystem-check.md | Conditional |
+| 2b | CCC Discover | steps-c/sub/step-02b-ccc-discover.md | Yes |
+| 3 | Extract | steps-c/step-03-extract.md | No (confirm) |
+| 3b | Fetch Temporal | steps-c/sub/step-03b-fetch-temporal.md | Yes |
+| 3c | Fetch Docs | steps-c/sub/step-03c-fetch-docs.md | Yes |
+| 3d | Component Extraction | steps-c/step-03d-component-extraction.md | Conditional |
+| 4 | Enrich | steps-c/step-04-enrich.md | Yes |
+| 5 | Compile | steps-c/step-05-compile.md | Yes |
+| 6 | Validate | steps-c/step-06-validate.md | Conditional |
+| 7 | Generate Artifacts | steps-c/step-07-generate-artifacts.md | Yes |
+| 8 | Report | steps-c/step-08-report.md | Yes |
+| 9 | Workflow Health Check | steps-c/step-09-health-check.md | Yes |
+
+*Sub-steps under `steps-c/sub/` are conditional branches (CCC discovery, temporal/doc enrichment) kept out of the top-level step count so main-line steps 1–9 drive the workflow. Step 3d (Component Extraction) stays top-level as an alternative main step that replaces the standard extraction path when `scope.type: "component-library"`.*
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | brief_path (path to skill-brief.yaml) [required], --batch [optional] |
+| **Gates** | step-02: Choice Gate [P] (if match) | step-03: Review Gate [C] |
+| **Outputs** | SKILL.md, context-snippet.md, metadata.json, provenance-map.json, evidence-report.md, references/ |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+   - `output_folder`, `user_name`, `communication_language`, `document_output_language`, `sidecar_path`, `skills_output_folder`, `forge_data_folder`
+
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+
+3. Load, read the full file, and then execute `./steps-c/step-01-load-brief.md` to begin the workflow.

package/src/{workflows/create-skill/data → skf-create-skill/assets}/compile-assembly-rules.md

@@ -16,6 +16,12 @@ description: >
 
 - `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name. Prefer gerund form (`processing-pdfs`, `analyzing-spreadsheets`) for clarity.
 - `description`: non-empty, max 1024 chars, optimized for agent discovery. **MUST use third-person voice** ("Processes Excel files..." not "I can help you..." or "You can use this to..."). Inconsistent point-of-view causes discovery problems since the description is injected into the system prompt.
+- **`description` must NOT contain angle brackets** — neither standalone placeholders like `<name>`, `<component>`, `<path>`, nor inline generics like `` `Array<T>` `` or `` `Meta<typeof X>` ``. Both `skill-check`'s `description_field` validator and `tessl`'s deterministic description check parse the frontmatter description as a raw string and reject any `<` or `>`, regardless of markdown context (backticks do NOT protect content here). A rejected description fails the review with 0% score. When the natural phrasing would use angle brackets:
+  - Prefer the curly-brace form in prose: `{name}`, `{component-id}`, `{path}` — readable and tessl-safe.
+  - Uppercase placeholders are also acceptable: `NAME`, `COMPONENT_ID`.
+  - For code-ish fragments, use curly braces in place of angle brackets inside the backticks: `` `Meta{typeof X}` ``, `` `Array{T}` ``.
+
+  Authors should not rely on remembering this — step-05 §2a enforces it via a pre-write sanitization pass that unconditionally replaces every `<` with `{` and every `>` with `}` in the frontmatter `description`. See step-05 §2a for the rule and `assets/tessl-dismissal-rules.md` (`description-xml-tags-guarded-upstream`) for the recovery path if a downstream tool rewrites the description after §2a has run.
 - Only `name` and `description` in frontmatter — `version` and `author` go in metadata.json
 - No other frontmatter fields for standard skills (only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted by spec)
 
@@ -216,6 +222,55 @@ When `scope.type: "component-library"`, add these fields to `stats`:
 
 These are in addition to the standard stats fields (exports_documented, etc.).
 
+### Reference-App Assembly Overrides
+
+When `scope.type: "reference-app"` in the brief, apply these overrides to the standard assembly. The skill's value is an integration pattern (wiring), not a library surface — the default library-export template would force assemblers to remap wiring onto export slots and produce fuzzy counts. These overrides give that value a first-class home.
+
+**Section 4 (Key API Summary) — Pattern Surface override:**
+
+Replace the per-function table with an ordered list of wiring steps. Each step names a file, a surface (decorator, build field, lifecycle hook, config key), and a one-line description of what the user does there — not a function signature. The goal is that a reader copying the pattern can follow the list in order.
+
+```markdown
+## Pattern Surface
+
+| # | File | Surface | Purpose |
+|---|------|---------|---------|
+| 1 | {src/main.py} | {@app.startup decorator} | {brief wiring purpose} |
+| 2 | {electron.vite.config.ts} | {build.copy field} | {brief wiring purpose} |
+| … | … | … | … |
+```
+
+Source: the authored pattern surface from extraction + brief `scope.tier_a_include` (when present) or the curated provenance-map entries (when absent). Provenance: cite the originating source files.
+
+**Section 3 (Common Workflows) — Adoption Steps override:**
+
+Replace the function-call-chain format with copy-this-wiring narrative. Prefer numbered imperative steps that the user can execute in order, not an API-call sequence. Keep each step's code snippet minimal (5–15 lines) — full wiring lives in Tier 2.
+
+```markdown
+## Adoption Steps
+
+1. **{Step name}** — {one-line description}
+   ```{language}
+   {minimal wiring snippet}
+   ```
+2. **{Step name}** — {one-line description}
+   …
+```
+
+**Tier 2 (Full API Reference) — pattern-oriented override:**
+
+Replace per-function subsections with `references/pattern-*.md` groupings: one reference file per coherent wiring concern (e.g. `pattern-lifecycle.md`, `pattern-build-config.md`, `pattern-ipc.md`). Each reference file covers every file/surface touched by that concern with full code snippets, gotchas, and provenance. Tier 1 (Pattern Surface) stays index-like; Tier 2 carries the copy-paste-able depth.
+
+**metadata.json — Reference-App stats semantics:**
+
+`stats.exports_documented` is a **library concept** and does not carry over cleanly. When `scope.type: "reference-app"`:
+
+- `stats.exports_documented` MAY be set to the Pattern Surface row count as a proxy, but its semantics change: it counts authored pattern surfaces, not public exports. Emit an adjacent `stats.pattern_surfaces_documented` with the same integer so downstream consumers (test-skill, feasibility, discovery) can discriminate.
+- `exports_public_api` / `exports_internal` / `exports_total` are not meaningful for a reference app — omit them, or set all three to the Pattern Surface count with a note in `stats.notes`: `"reference-app: export counts are pattern-surface proxies, not library exports"`.
+- Do NOT fabricate signature / type-coverage data from pattern surfaces. skf-test-skill will skip those categories when metadata flags a reference-app (same skip path as `stackSkill` once that flag is wired — see scoring-rules.md).
+
+**When this clause does NOT apply:** `full-library`, `specific-modules`, `public-api`, `component-library`, or `docs-only`. Those scope types have their own assembly semantics and export-count conventions — do not mix.
+
 ### Assembly Rules
 
 1. Assemble all Tier 1 sections first — these form the essential standalone body
@@ -250,6 +305,11 @@ These rules apply to all content assembled in SKILL.md and reference files.
 - **For flexible guidance** (reports, analysis): Provide a sensible default template with "Adjust sections as needed" language.
 - **Input/output examples:** When output quality depends on seeing examples and concrete pairs exist in source tests or official docs, include 2-3 input/output pairs sourced from those tests or docs. Examples help agents understand desired style and detail more clearly than descriptions alone. If no examples exist in source, note the gap rather than fabricating pairs — zero hallucination applies.
 
+**Generic-plus-signature code spans:** When documenting a generic class constructor or factory signature, do NOT place the generic brackets and the parameter list inside a single inline code span. `skill-check`'s `links.local_markdown_resolves` validator parses `` `ClassName[T](key: str)` `` as a broken markdown link (`[T]` becomes the link text, `(key: str)` becomes the URL) and emits a `broken local link` warning on the Links axis, regardless of the surrounding backticks. This applies to Tier 1 Key Types, Tier 2 Full API Reference, and reference files. Safe alternatives:
+- Split into two code spans: `` `ClassName[T]` — dataclass with fields `(key: str, value: int)` ``
+- Drop the explicit constructor and describe fields in prose: `` `ClassName[T]` — generic container parameterized by `T`, with field `key: str` ``
+- Use the curly-brace substitution used for frontmatter: `` `ClassName{T}(key: str)` `` (readable, avoids both markdown-link and angle-bracket parsing)
+
 **Workflow checklist pattern:** When a skill includes multi-step workflows, provide a copy-paste checklist that agents can track progress against:
 ```markdown
 Copy this checklist and track your progress:

package/src/{workflows/create-skill/data → skf-create-skill/assets}/skill-sections.md

@@ -28,18 +28,18 @@ SKILL.md uses a two-tier structure to ensure actionable content survives `split-
 
 #### Tier 1 — Always Inline (survives split-body, target <300 lines)
 
-| # | Section | Budget | Purpose |
-|---|---------|--------|---------|
-| 1 | **Overview** | ~10 lines | What the library does, source repo, version, tier, export count |
-| 2 | **Quick Start** | ~30 lines | 3-5 core functions with one runnable end-to-end example |
-| 3 | **Common Workflows** | ~30 lines | 4-5 typical function call sequences for common tasks |
-| 4 | **Key API Summary** | ~20 lines | Table of top 10-15 functions (name, purpose, key params) |
-| 4b | **Migration & Deprecation Warnings** | ~10 lines | T2-future warnings inline (Deep tier only, skip if none) |
-| 5 | **Key Types** | ~20 lines | Most important enum/type values inline |
-| 6 | **Architecture at a Glance** | ~10 lines | Bullet list of subsystem categories |
-| 7 | **CLI** | ~10 lines | Basic CLI commands (skip if no CLI) |
-| 7b | **Scripts & Assets** | ~10 lines | Manifest of included scripts and assets (skip if none detected) |
-| 8 | **Manual Sections** | ~5 lines | `<!-- [MANUAL] -->` markers for update-skill |
+| #  | Section                              | Budget    | Purpose                                                         |
+|----|--------------------------------------|-----------|-----------------------------------------------------------------|
+| 1  | **Overview**                         | ~10 lines | What the library does, source repo, version, tier, export count |
+| 2  | **Quick Start**                      | ~30 lines | 3-5 core functions with one runnable end-to-end example         |
+| 3  | **Common Workflows**                 | ~30 lines | 4-5 typical function call sequences for common tasks            |
+| 4  | **Key API Summary**                  | ~20 lines | Table of top 10-15 functions (name, purpose, key params)        |
+| 4b | **Migration & Deprecation Warnings** | ~10 lines | T2-future warnings inline (Deep tier only, skip if none)        |
+| 5  | **Key Types**                        | ~20 lines | Most important enum/type values inline                          |
+| 6  | **Architecture at a Glance**         | ~10 lines | Bullet list of subsystem categories                             |
+| 7  | **CLI**                              | ~10 lines | Basic CLI commands (skip if no CLI)                             |
+| 7b | **Scripts & Assets**                 | ~10 lines | Manifest of included scripts and assets (skip if none detected) |
+| 8  | **Manual Sections**                  | ~5 lines  | `<!-- [MANUAL] -->` markers for update-skill                    |
 
 #### Tier 2 — Reference-Eligible (extracted by split-body into references/)
 
@@ -137,12 +137,12 @@ When `scope.type: "component-library"`, these section formats replace their stan
 
 ### Provenance Citation Format
 
-| Tier | Format | Example |
-|------|--------|---------|
-| T1 (AST) | `[AST:{file}:L{line}]` | `[AST:src/auth/index.ts:L42]` |
-| T1-low (Source) | `[SRC:{file}:L{line}]` | `[SRC:src/auth/index.ts:L42]` |
-| T2 (QMD) | `[QMD:{collection}:{doc}]` | `[QMD:project:CHANGELOG.md]` |
-| T3 (External) | `[EXT:{url}]` | `[EXT:docs.example.com/api]` |
+| Tier            | Format                     | Example                       |
+|-----------------|----------------------------|-------------------------------|
+| T1 (AST)        | `[AST:{file}:L{line}]`     | `[AST:src/auth/index.ts:L42]` |
+| T1-low (Source) | `[SRC:{file}:L{line}]`     | `[SRC:src/auth/index.ts:L42]` |
+| T2 (QMD)        | `[QMD:{collection}:{doc}]` | `[QMD:project:CHANGELOG.md]`  |
+| T3 (External)   | `[EXT:{url}]`              | `[EXT:docs.example.com/api]`  |
 
 ### [MANUAL] Section Markers
 
@@ -224,6 +224,7 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
     "total_coverage": 0.0,
     "scripts_count": 0,
     "assets_count": 0
+    // "effective_denominator": 0  // optional — emitted for stratified-scope monorepo packages; test-skill uses this as the coverage denominator when present. See step-05-compile.md §4 emit rules.
   },
   // scripts[] and assets[] — include ONLY when inventories are non-empty; omit entirely otherwise
   // "scripts": [{ "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
@@ -262,15 +263,18 @@ Each reference file includes:
 
 ```json
 {
+  "provenance_version": "2.0",
   "skill_name": "{name}",
-  "source_repo": "{url}",
-  "source_commit": "{hash}",
+  "skill_type": "single|stack",
+  "source_repo": "{url or [urls] for multi-source}",
+  "source_commit": "{hash or {repo: hash} for multi-source}",
   "source_ref": "v0.5.0",
   "generated_at": "{ISO-8601}",
   "entries": [
     {
       "export_name": "getToken",
       "export_type": "function",
+      "source_library": "{library-name — defaults to skill name for single skills}",
       "params": ["userId: string", "options?: TokenOptions"],
       "return_type": "Token",
       "source_file": "src/auth/index.ts",
@@ -281,6 +285,24 @@ Each reference file includes:
       "signature_source": "T1"
     }
   ],
+  "integrations": [
+    {
+      "libraries": ["lib-a", "lib-b"],
+      "pattern_type": "provider-consumer",
+      "detection_method": "co-import grep|architecture_co_mention|inferred_from_shared_domain",
+      "co_import_files": [{"file": "src/app.ts", "line": 5}],
+      "confidence": "T1|T2|T3"
+    }
+  ],
+  "constituents": [
+    {
+      "skill_name": "{constituent-skill-name}",
+      "skill_path": "skills/{skill-dir}/",
+      "version": "{version at compose time}",
+      "composed_at": "{ISO-8601}",
+      "metadata_hash": "sha256:{hash of constituent metadata.json at compose time}"
+    }
+  ],
   "file_entries": [
     {
       "file_name": "scripts/{name}",
@@ -294,13 +316,40 @@ Each reference file includes:
 }
 ```
 
-`scripts` and `assets` arrays in metadata.json are optional — omit entirely (not empty arrays) when no scripts/assets exist. `file_entries` in provenance-map.json is optional — omit when no scripts/assets exist.
+- `provenance_version`: Schema version. `"2.0"` enables unified single/stack support. Audit reads both v1 (no version field) and v2.
+- `source_library`: Identifies which library an export belongs to. For single skills, defaults to the skill/package name. For stack skills, identifies the constituent library.
+- `integrations`: Stack-only. Describes cross-library integration patterns with their own schema — NOT shoehorned into entries.
+- `constituents`: Stack-only (compose-mode). Tracks the compose-time snapshot of each source skill for staleness detection. `metadata_hash` enables audit to detect constituent drift without re-reading all constituent files.
+- `file_entries` remains optional — omit when no scripts, assets, or promoted docs exist.
+- Single skills omit `integrations` and `constituents` arrays entirely (not empty arrays).
+
+**`file_type` enum — canonical values:**
+
+| Value | Source inventory | Copied to skill package? | `extraction_method` | Purpose |
+|---|---|---|---|---|
+| `"script"` | `scripts_inventory` | yes → `scripts/` | `"file-copy"` | Runnable scripts (CLI tools, validation scripts, etc.) bundled into the skill for execution. |
+| `"asset"` | `assets_inventory` | yes → `assets/` | `"file-copy"` | Data files (templates, JSON schemas, config fixtures) bundled for reference. |
+| `"doc"` | `promoted_docs` (from step-03 §2a) | **no** | `"promoted-authoritative"` | Authoritative AI documentation files (`llms.txt`, `AGENTS.md`, etc.) promoted into scope by the Discovered Authoritative Files Protocol. The source file is tracked for drift detection but not bundled into the skill — its content influences compile-time decisions (description, Quick Start) and is watched for upstream changes. |
+
+When `file_type: "doc"`:
+
+- `source_file` is the relative path from the source root to the authoritative doc.
+- `content_hash` is computed at promotion time (step-03 §2a) and persisted here so update-skill Category D can detect drift via hash comparison.
+- `file_name` convention: use the source-relative path prefixed with `docs/authoritative/` to namespace doc entries away from script/asset filenames in tools that iterate `file_entries[]` by `file_name`. Example: `docs/authoritative/apps/docs/public/llms.txt`. Step-07 does not write this path — it is a synthetic namespace used only within the provenance map.
+- `confidence` is `"T1-low"` (the promotion decision is source-level but the content was not AST-parsed).
 
 ---
 
 ## evidence-report.md Structure
 
 ```markdown
+---
+skill_name: {skill-name}
+generated: {date}
+forge_tier: {tier}
+t2_future_count: {N}
+---
+
 # Evidence Report: {skill-name}
 
 **Generated:** {date}
@@ -318,9 +367,29 @@ Each reference file includes:
 - Confidence: T1={n}, T1-low={n}, T2={n}, T3={n}
 
 ## 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}
+
+## Quality Score Breakdown
+- Frontmatter (30%): {score} | Description (30%): {score} | Body (20%): {score} | Links (10%): {score} | File (10%): {score}
 
-## Warnings
+## 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
 - {any warnings from extraction or validation}
 ```
+
+**Frontmatter — pinned detection contract:** the `t2_future_count` field is the authoritative forward-looking-annotation count for downstream gate checks (e.g. skf-test-skill §2b migration-section rule). Emit **always**, even when 0 — omission is indistinguishable from "no T2-future data" and silently flips the gate into Case 2/3 for a Case-1 skill. `generated` and `forge_tier` mirror the narrative header for consumers that read only the frontmatter. Downstream gate rules MUST parse `t2_future_count` from frontmatter, not grep prose — prose drift (heading renames, alternate phrasings like "forward-looking annotations") silently breaks the detection.
+
+**Description Guard slot:** populated by step-06 §0 (create-skill) and §0 (update-skill) when the guard protocol fires. `Restored: true` indicates that an external tool (typically `skill-check --fix` or `split-body`) rewrote the frontmatter `description` and the guard restored the pre-tool value. When `Restored: false`, leave `Triggering tool`, `Original description preserved`, and `Notes` as `—`. When `Restored: true`, fill all four fields: tool name, whether the original was successfully written back, and a one-sentence note describing what the tool had changed (e.g., "replaced with generic summary", "truncated at 80 chars", "angle-bracket tokens re-introduced"). Downstream test-skill assertions can grep for `Restored: true` to detect unintended tool rewrites without parsing free-form warning prose.

package/src/skf-create-skill/assets/tessl-dismissal-rules.md

@@ -0,0 +1,102 @@
+# tessl Dismissal Rules
+
+This file is the **single source of truth** for tessl review findings that Skill Forge expects and must dismiss. Step-06 §6 loads this file, parses the `tessl skill review` JSON output, and cross-references each finding against the rules below. Matches are dismissed with their rationale logged to the evidence report; non-matches surface to the user via §6b.
+
+**Why this file exists:** Previously, expected tessl behavior was enumerated as prose in step-06 itself. Each time tessl evolved a scorer or added a new rule, step-06 had to be manually patched and the prose re-read by every execution. This file moves the expected behavior into a structured list with stable rule IDs, rationales, and match criteria — one place to update when tessl changes, one place to audit what SKF expects.
+
+---
+
+## Score Thresholds
+
+When parsing tessl output, check these fields against the thresholds below. Violations trigger warnings or errors as specified.
+
+| Field | Threshold | Severity on violation | Rationale |
+|---|---|---|---|
+| `review_score` (overall) | `>= 60` | warn | Two-tier SKF skills trade some conciseness score for progressive disclosure. 60 is the floor below which something is genuinely wrong. |
+| `description_score` | `== 100` | **error — recover, then halt** | step-05 §2a unconditionally replaces `<` with `{` and `>` with `}` in the frontmatter description before validation. A score below 100 indicates the sanitizer was bypassed (downstream tool rewrote the description) or a novel tessl rule. Attempt recovery per rule `description-xml-tags-guarded-upstream` (re-apply the §2a substitution in place on the staging SKILL.md frontmatter and re-run tessl). Halt only if recovery fails. |
+| `content_score` | `>= 60` | warn | Two-tier design deliberately duplicates key API data across Tier 1 and Tier 2. Conciseness scorer penalizes this. 60 is the acceptable floor. |
+
+If `description_score < 100`, **attempt recovery first** per rule `description-xml-tags-guarded-upstream` below: re-apply step-05 §2a's `<` → `{` / `>` → `}` substitution in place on the staging SKILL.md frontmatter `description`, then re-run `npx -y tessl skill review <staging-skill-dir>` once. If the re-run produces `description_score == 100`, log `description-recovery: applied ({count} substitutions)` in the evidence report and proceed to normal suggestion handling. If recovery fails, halt with: "Description sanitization recovery failed — step-05 §2a's `<`/`>` → `{`/`}` replacement did not resolve the tessl finding. Investigate the staging SKILL.md frontmatter for non-angle-bracket content that tessl is still rejecting, and patch §2a accordingly. Do not edit the description manually." Do NOT proceed to §6b user prompt on an unrecovered failure.
+
+---
+
+## Suggestion Dismissal Rules
+
+Each rule below describes a tessl suggestion that Skill Forge expects and dismisses automatically. For each `judge_suggestion` in tessl output, check it against these rules in order. If any rule matches, record the dismissal in the evidence report (`rule_id`, `rationale`) and do NOT apply the suggestion. If no rule matches, the suggestion is novel and must surface to the user in §6b.
+
+### Rule: `remove-manual-markers`
+
+- **Scorer:** any
+- **Match criteria (any of):**
+  - Suggestion text contains `[MANUAL]` AND one of: `remove`, `delete`, `strip`, `clean up`
+  - Suggestion text contains `manual marker` AND one of: `remove`, `delete`, `unnecessary`
+- **Rationale:** `<!-- [MANUAL] -->` markers delineate author-added content that `skf-update-skill` preserves during merge operations. Removing them would cause update-skill to overwrite author edits on the next run. The markers are a load-bearing contract between create-skill, test-skill, and update-skill.
+- **Action:** dismiss.
+
+### Rule: `move-full-api-reference`
+
+- **Scorer:** any
+- **Match criteria (all of):**
+  - Suggestion text mentions `Full API Reference` OR a `## Full ...` section heading
+  - Suggestion text contains one of: `move`, `relocate`, `extract`, `split out`, `separate file`, `external file`
+- **Rationale:** The two-tier design (Tier 1 inline + Tier 2 inline) keeps Tier 2 sections inline by default. `skill-check split-body` relocates Tier 2 to `references/` only when the body exceeds size limits — see step-06 §4. Preemptive relocation destroys the standalone SKILL.md that the cited 100% task accuracy (vs. 79% for on-demand retrieval) depends on.
+- **Action:** dismiss.
+
+### Rule: `consolidate-duplicate-parameters`
+
+- **Scorer:** `conciseness` or any
+- **Match criteria (any of):**
+  - Suggestion mentions `duplicate parameter`, `redundant parameter`, `consolidate parameter`
+  - Suggestion mentions both `Key API` / `Key API Summary` AND `Full API Reference` and suggests merging them
+- **Rationale:** Tier 1 Key API Summary intentionally lists only key parameters for standalone discoverability. Tier 2 Full API Reference provides complete parameter tables, types, defaults, and edge cases. This is progressive disclosure, not duplication. Consolidating would force agents to scroll to Tier 2 for the most common function calls, defeating Tier 1's purpose and breaking the split-body Tier 1 preservation contract in step-06 §4.
+- **Action:** dismiss.
+
+### Rule: `conciseness-redundancy-between-tiers`
+
+- **Scorer:** `conciseness`
+- **Match criteria (all of):**
+  - Scorer is `conciseness`
+  - Suggestion or score rationale references redundancy between Tier 1 and Tier 2 sections (typically `Key API` ↔ `Full API` or `Quick Start` ↔ `Full Reference`)
+- **Expected score:** 2/3 is normal. 3/3 is only achievable by collapsing the two-tier design.
+- **Rationale:** Progressive disclosure is the intentional SKF design. The conciseness scorer has no concept of Tier 1 / Tier 2 and flags the structure as redundancy. Collapsing the two tiers would eliminate standalone discoverability and break split-body behavior.
+- **Action:** dismiss. Do not attempt to raise the score above 2/3.
+
+### Rule: `description-xml-tags-guarded-upstream`
+
+- **Scorer:** `description_field` (deterministic validator)
+- **Match criteria (any of):**
+  - Finding rule ID is `description_field` AND message mentions `XML tag`, `must not contain`, or angle-bracket-related text
+- **Expected occurrence:** zero. step-05 §2a unconditionally replaces `<` with `{` and `>` with `}` in the frontmatter description before SKILL.md is written.
+- **Action:** **Attempt recovery, then halt if recovery fails.** This is not a dismissal — the finding represents a real sanitizer bypass that step-06 must resolve before proceeding.
+  1. **Re-apply §2a in place.** Read the current `description` from the on-disk staging SKILL.md frontmatter, replace every `<` with `{` and every `>` with `}`, and write the result back to the frontmatter. Re-sync the in-context copy to match. Count the substitutions; if zero, the description is already clean and the tessl finding points at something other than angle brackets — skip to the halt branch below.
+  2. **Re-run tessl once.** Execute `npx -y tessl skill review <staging-skill-dir>` a second time and re-parse the JSON output.
+  3. **On success** (`description_score == 100`): log `description-recovery: applied ({count} substitutions)` in the evidence report under "Dismissed tessl suggestions", then continue §6 with the recovered review result (proceed to normal suggestion handling against the rules below). The rerun's `judge_suggestions[]` replaces the original.
+  4. **On failure** (`description_score` still < 100 after re-sanitization): halt with: "Description sanitization recovery failed — step-05 §2a's `<`/`>` → `{`/`}` replacement did not resolve the tessl finding. Investigate the staging SKILL.md frontmatter for non-angle-bracket content that tessl is still rejecting, and patch §2a accordingly. Do not edit the description manually."
+
+The recovery path makes the skill shippable when a downstream tool (`skill-check --fix`, `split-body`, or a future validator) re-introduces angle brackets into the description after §2a has run. The Description Guard Protocol in step-06 §0 is the first line of defense against such rewrites; this rule is the second line, active when the guard also missed.
+
+---
+
+## How Step-06 §6 Uses This File
+
+1. Load this file completely at the start of §6.
+2. Run `npx -y tessl skill review <staging-skill-dir>` and parse JSON output.
+3. Check score thresholds. For `description_score < 100`: follow the recovery-then-halt path described in the threshold table above and the `description-xml-tags-guarded-upstream` rule below — re-apply §2a in place, re-run tessl once, and continue on recovery success or halt on recovery failure. For other warns: continue, log warnings to evidence report.
+4. For each `judge_suggestions[]` entry in the output:
+   a. Iterate the rules above in order.
+   b. If a rule's match criteria are satisfied, record `{rule_id, rationale, suggestion_text}` in the evidence report under "Dismissed tessl suggestions" and move to the next suggestion.
+   c. If no rule matches, add the suggestion to the "Novel tessl suggestions" list that §6b surfaces to the user.
+5. Proceed to §6b if any novel suggestions exist, or auto-proceed if all suggestions were dismissed.
+
+---
+
+## Evolving This List
+
+When tessl introduces new rules, changes scorer behavior, or SKF design decisions change:
+
+1. **Add a new rule section** above with `Rule:`, `Scorer:`, `Match criteria`, `Rationale`, `Action`.
+2. **Link the rationale** to the concrete SKF design principle it protects (two-tier design, MANUAL markers, sanitization, split-body preservation, etc.). A rationale without a design-principle link is a smell.
+3. **Keep score thresholds above current production floors.** Do not lower them to suppress real regressions.
+4. **Never embed dismissal logic in step files.** If step-06 needs updated behavior, update this file first and reference it from step-06.
+
+This file is load-bearing: step-06 §6 has no other source of truth for expected tessl behavior.

package/src/{workflows/create-skill/data → skf-create-skill/references}/extraction-patterns-tracing.md

@@ -57,23 +57,23 @@ Scripts and assets are file-level artifacts, not code exports. They follow the *
 
 **Script file signals:**
 
-| Signal | Strength | Pattern |
-|--------|----------|---------|
-| Entry point declaration | Strong | `package.json` `bin` field, Cargo.toml `[[bin]]`, pyproject.toml `[project.scripts]` |
-| Shebang + executable | Strong | `#!/bin/bash`, `#!/usr/bin/env python`, `#!/usr/bin/env node` |
-| CLI argument parser | Moderate | `argparse`, `yargs`, `commander`, `cobra`, `clap` imports in file |
-| Directory convention | Moderate | File in `scripts/`, `bin/`, `tools/` directory |
-| CI/CD reference | Moderate | Script referenced in `.github/workflows/*.yml` |
+| Signal                  | Strength | Pattern                                                                              |
+|-------------------------|----------|--------------------------------------------------------------------------------------|
+| Entry point declaration | Strong   | `package.json` `bin` field, Cargo.toml `[[bin]]`, pyproject.toml `[project.scripts]` |
+| Shebang + executable    | Strong   | `#!/bin/bash`, `#!/usr/bin/env python`, `#!/usr/bin/env node`                        |
+| CLI argument parser     | Moderate | `argparse`, `yargs`, `commander`, `cobra`, `clap` imports in file                    |
+| Directory convention    | Moderate | File in `scripts/`, `bin/`, `tools/` directory                                       |
+| CI/CD reference         | Moderate | Script referenced in `.github/workflows/*.yml`                                       |
 
 **Asset file signals:**
 
-| Signal | Strength | Pattern |
-|--------|----------|---------|
-| JSON Schema | Strong | `*.schema.json`, file contains `"$schema"` key |
-| Config template | Strong | `*.example`, `*.template.*`, `*.sample` extension |
+| Signal           | Strength | Pattern                                             |
+|------------------|----------|-----------------------------------------------------|
+| JSON Schema      | Strong   | `*.schema.json`, file contains `"$schema"` key      |
+| Config template  | Strong   | `*.example`, `*.template.*`, `*.sample` extension   |
 | Official example | Moderate | File in `examples/` directory, referenced in README |
-| OpenAPI/GraphQL | Moderate | `openapi.json`, `*.graphql`, `swagger.yaml` |
-| Design tokens | Weak | `tokens.json`, `theme.json` in `assets/` |
+| OpenAPI/GraphQL  | Moderate | `openapi.json`, `*.graphql`, `swagger.yaml`         |
+| Design tokens    | Weak     | `tokens.json`, `theme.json` in `assets/`            |
 
 ### Inclusion Rules