bmad-module-skill-forge 1.8.0 → 2.0.0

package/src/skf-campaign/scripts/campaign-validate-pins.py

@@ -0,0 +1,174 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""Campaign Validate Pins — validate all version pins in a campaign state file.
+
+Campaign-specific wrapper around the shared skf-validate-pins.py module.
+Reads the campaign state and brief, validates every skill's pin against
+real GitHub releases/tags, and outputs consolidated JSON.
+
+CLI:
+  uv run src/skf-campaign/scripts/campaign-validate-pins.py \
+      --state-file <path> --brief-file <path>
+
+Input:
+  --state-file   Path to _campaign-state.yaml
+  --brief-file   Path to campaign-brief.yaml
+
+Output (JSON on stdout):
+  {
+    "results": [
+      {
+        "name": "skill-name",
+        "status": "valid|invalid|resolved",
+        "pin": "input-pin-or-null",
+        "resolved_ref": "actual-tag-or-branch",
+        "ref_type": "tag|branch|null",
+        "version": "semver-or-null",
+        "suggestions": []
+      }
+    ],
+    "all_valid": true,
+    "invalid_count": 0,
+    "resolved_count": 0
+  }
+
+Exit codes:
+  0  all valid/resolved
+  1  one or more invalid pins
+  2  error (missing files, bad YAML, gh unavailable)
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+import yaml
+
+SHARED_SCRIPTS = Path(__file__).parent.parent.parent / "shared" / "scripts"
+VALIDATE_PINS_PATH = SHARED_SCRIPTS / "skf-validate-pins.py"
+
+
+def _load_validate_pin():
+    spec = importlib.util.spec_from_file_location("skf_validate_pins", VALIDATE_PINS_PATH)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod.validate_pin
+
+
+def _emit_error(message: str, code: str) -> None:
+    json.dump({"error": message, "code": code}, sys.stderr)
+    sys.stderr.write("\n")
+
+
+def _load_yaml(path: Path) -> Any:
+    with open(path, encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def run(state_file: str, brief_file: str) -> int:
+    state_path = Path(state_file)
+    brief_path = Path(brief_file)
+
+    if not state_path.is_file():
+        _emit_error(f"State file not found: {state_file}", "STATE_NOT_FOUND")
+        return 2
+
+    if not brief_path.is_file():
+        _emit_error(f"Brief file not found: {brief_file}", "BRIEF_NOT_FOUND")
+        return 2
+
+    try:
+        state = _load_yaml(state_path)
+    except Exception as exc:
+        _emit_error(f"Failed to parse state file: {exc}", "STATE_PARSE_ERROR")
+        return 2
+
+    try:
+        brief = _load_yaml(brief_path)
+    except Exception as exc:
+        _emit_error(f"Failed to parse brief file: {exc}", "BRIEF_PARSE_ERROR")
+        return 2
+
+    skills = state.get("skills", [])
+    if not isinstance(skills, list):
+        _emit_error("State file 'skills' is not an array", "INVALID_STATE")
+        return 2
+
+    targets = brief.get("targets", [])
+    if not isinstance(targets, list):
+        _emit_error("Brief file 'targets' is not an array", "INVALID_BRIEF")
+        return 2
+
+    name_to_repo: Dict[str, str] = {}
+    for target in targets:
+        name_to_repo[target["name"]] = target["repo_url"]
+
+    if not VALIDATE_PINS_PATH.is_file():
+        _emit_error(
+            f"Shared module not found: {VALIDATE_PINS_PATH.as_posix()}",
+            "SHARED_MODULE_NOT_FOUND",
+        )
+        return 2
+
+    validate_pin = _load_validate_pin()
+
+    results: List[Dict[str, Any]] = []
+    invalid_count = 0
+    resolved_count = 0
+
+    for skill in skills:
+        skill_name = skill["name"]
+        repo_url = name_to_repo.get(skill_name)
+        if repo_url is None:
+            _emit_error(
+                f"Skill '{skill_name}' not found in brief targets",
+                "SKILL_NOT_IN_BRIEF",
+            )
+            return 2
+
+        pin = skill.get("pin")
+        result = validate_pin(repo_url, pin=pin)
+        result["name"] = skill_name
+
+        if result["status"] == "invalid":
+            invalid_count += 1
+        elif result["status"] == "resolved":
+            resolved_count += 1
+
+        results.append(result)
+
+    all_valid = invalid_count == 0
+    output = {
+        "results": results,
+        "all_valid": all_valid,
+        "invalid_count": invalid_count,
+        "resolved_count": resolved_count,
+    }
+
+    json.dump(output, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+
+    if not all_valid:
+        return 1
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate all version pins in a campaign state file.",
+    )
+    parser.add_argument("--state-file", required=True, help="Path to _campaign-state.yaml")
+    parser.add_argument("--brief-file", required=True, help="Path to campaign-brief.yaml")
+    args = parser.parse_args()
+    return run(args.state_file, args.brief_file)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-campaign/scripts/campaign-validate-state.py

@@ -0,0 +1,207 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml", "jsonschema>=4.0"]
+# ///
+"""Campaign Validate State — schema check for _campaign-state.yaml on disk.
+
+Replaces the per-step "mentally validate the loaded state against the schema"
+prose with a deterministic check. Every campaign step that loads state runs
+this once on entry instead of asking the LLM to validate a draft-07 schema
+(nested objects, enums, additionalProperties:false, date-time) by hand — the
+exact check an LLM does unreliably and which, when wrong, silently corrupts a
+multi-session campaign.
+
+Loads the campaign state YAML, validates it against
+`assets/campaign-state-schema.json` (resolved relative to this script unless
+`--schema-file` overrides), and emits skill-friendly error records the calling
+step can forward verbatim.
+
+CLI:
+  uv run campaign-validate-state.py --state-file <path>
+  uv run campaign-validate-state.py --state-file <path> --schema-file <path>
+
+Output (JSON on stdout):
+  {
+    "valid": bool,
+    "errors":   [{"field": "campaign.current_stage", "message": "..."}, ...],
+    "halt_reason": "state-missing" | "state-malformed" | "state-invalid" | null
+  }
+
+Exit codes:
+  0  valid (errors empty)
+  1  invalid (schema violations) OR file/yaml load failed
+  2  configuration error (schema file missing or unreadable)
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+from jsonschema import Draft7Validator
+
+DEFAULT_SCHEMA_PATH = Path(__file__).resolve().parent.parent / "assets" / "campaign-state-schema.json"
+
+
+def _emit(envelope: dict) -> None:
+    json.dump(envelope, sys.stdout, separators=(",", ":"), default=str)
+    sys.stdout.write("\n")
+
+
+def _load_yaml_text(text: str) -> tuple[Any, str | None]:
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        return None, f"State is not valid YAML: {exc}"
+    if data is None:
+        return None, "State file is empty"
+    if not isinstance(data, dict):
+        return None, f"State root must be a YAML mapping; got {type(data).__name__}"
+    return data, None
+
+
+def _field_path(error_path) -> str:
+    parts: list[str] = []
+    for p in error_path:
+        if isinstance(p, int):
+            parts.append(f"[{p}]")
+        else:
+            parts.append(f".{p}" if parts else str(p))
+    return "".join(parts) or "(root)"
+
+
+def _translate(err) -> dict:
+    field = _field_path(err.absolute_path)
+    validator = err.validator
+    inst = err.instance
+
+    if validator == "required":
+        missing = err.message.split("'")[1] if "'" in err.message else "(unknown)"
+        return {
+            "field": missing,
+            "message": f"State validation failed: missing required field `{missing}`.",
+        }
+    if validator == "enum":
+        return {
+            "field": field,
+            "message": (
+                f"State validation failed: `{field}` value `{inst}` is not one of "
+                f"{err.validator_value}."
+            ),
+        }
+    if validator == "type":
+        if isinstance(inst, datetime.date) and "string" in str(err.validator_value):
+            return {
+                "field": field,
+                "message": (
+                    f"State validation failed: `{field}` parsed as a YAML date, not a "
+                    f"string. Quote it (e.g. `'2026-05-01T00:00:00Z'`)."
+                ),
+            }
+        return {
+            "field": field,
+            "message": (
+                f"State validation failed: `{field}` has type `{type(inst).__name__}`, "
+                f"expected `{err.validator_value}`."
+            ),
+        }
+    if validator == "additionalProperties":
+        return {
+            "field": field,
+            "message": f"State validation failed: `{field}` — {err.message}",
+        }
+    if validator in ("minimum", "maximum"):
+        return {
+            "field": field,
+            "message": f"State validation failed: `{field}` value `{inst}` violates {validator} `{err.validator_value}`.",
+        }
+    return {
+        "field": field,
+        "message": f"State validation failed: `{field}` — {err.message}",
+    }
+
+
+def validate_state(state: dict, schema: dict) -> dict:
+    validator = Draft7Validator(schema)
+    errors = [
+        _translate(err)
+        for err in sorted(validator.iter_errors(state), key=lambda e: list(e.absolute_path))
+    ]
+    return {"valid": not errors, "errors": errors}
+
+
+def run(state_file: str, schema_file: str | None = None) -> int:
+    schema_path = Path(schema_file) if schema_file else DEFAULT_SCHEMA_PATH
+    if not schema_path.is_file():
+        _emit(
+            {
+                "valid": False,
+                "errors": [{"field": "(schema)", "message": f"Schema not found at `{schema_path}`."}],
+                "halt_reason": "state-invalid",
+            }
+        )
+        return 2
+    try:
+        schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        _emit(
+            {
+                "valid": False,
+                "errors": [{"field": "(schema)", "message": f"Schema unreadable: {exc}"}],
+                "halt_reason": "state-invalid",
+            }
+        )
+        return 2
+
+    state_path = Path(state_file)
+    if not state_path.is_file():
+        _emit(
+            {
+                "valid": False,
+                "errors": [{"field": "(file)", "message": f"State not found at `{state_path}`."}],
+                "halt_reason": "state-missing",
+            }
+        )
+        return 1
+
+    state, load_err = _load_yaml_text(state_path.read_text(encoding="utf-8"))
+    if load_err is not None:
+        _emit(
+            {
+                "valid": False,
+                "errors": [{"field": "(file)", "message": load_err}],
+                "halt_reason": "state-malformed",
+            }
+        )
+        return 1
+
+    result = validate_state(state, schema)
+    if not result["valid"]:
+        _emit({**result, "halt_reason": "state-invalid"})
+        return 1
+
+    _emit({**result, "halt_reason": None})
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="campaign-validate-state",
+        description="Validate _campaign-state.yaml against the campaign state schema.",
+    )
+    parser.add_argument("--state-file", required=True, help="Path to _campaign-state.yaml")
+    parser.add_argument(
+        "--schema-file",
+        help="Path to campaign-state-schema.json (defaults to the bundled schema)",
+    )
+    args = parser.parse_args(argv)
+    return run(args.state_file, args.schema_file)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-campaign/templates/campaign-brief-template.yaml

@@ -0,0 +1,34 @@
+# Machine-generated campaign brief — resume context for fresh sessions (FR-35)
+# Populated by step-01-setup.md from operator inputs
+
+# Campaign identifier
+campaign_name: ""
+
+# ISO-8601 timestamp of campaign creation
+created_at: ""
+
+# Target skills for this campaign run
+targets: []
+# Each target entry:
+#   name: ""
+#   repo_url: ""
+#   tier: "A"           # A (full pipeline) or B (batch)
+#   pin: null            # version pin, or null for latest
+#   depends_on: []       # list of skill names this target depends on
+
+# Quality thresholds applied to all skills in this campaign
+quality_gate:
+  hard: "zero-critical-high"
+  soft_target: 90
+  soft_fallback: 80
+
+# Where health findings are routed: "local" (project-local) or "improvement" (shared queue)
+health_findings_queue: "local"
+
+# Optional path to the architecture document the verify (Stage 7) and refine
+# (Stage 8) stages consume. Empty string means those stages discover it at
+# runtime (docs/architecture.md, then _bmad-output/planning-artifacts/architecture.md).
+architecture_doc_path: ""
+
+# Operator-provided context or directives for this campaign
+notes: ""

package/src/skf-campaign/templates/campaign-report-template.md

@@ -0,0 +1,54 @@
+# Campaign Report — {{campaign_name}}
+
+## Campaign Summary
+
+| Field | Value |
+|-------|-------|
+| **Campaign** | {{campaign_name}} |
+| **Started** | {{started_at}} |
+| **Completed** | {{completed_at}} |
+| **Duration** | {{duration}} |
+| **Quality Gate (Hard)** | {{quality_gate_hard}} |
+| **Quality Gate (Soft Target)** | {{quality_gate_soft_target}} |
+| **Quality Gate (Soft Fallback)** | {{quality_gate_soft_fallback}} |
+| **Skills Completed** | {{skills_completed}} |
+| **Skills Failed** | {{skills_failed}} |
+| **Skills Skipped** | {{skills_skipped}} |
+
+## Skills Overview
+
+| Name | Tier | Status | Quality Score | Pin | Workarounds |
+|------|------|--------|---------------|-----|-------------|
+{{skills_table}}
+
+## Quality Scores
+
+| Metric | Value |
+|--------|-------|
+| **Minimum** | {{quality_min}} |
+| **Maximum** | {{quality_max}} |
+| **Average** | {{quality_avg}} |
+
+### Per-Skill Breakdown
+
+{{quality_breakdown}}
+
+## Findings Summary
+
+- **Total workarounds applied:** {{total_workarounds}}
+- **Skills with workarounds:** {{skills_with_workarounds}}
+- **Doc-rot corrections:** tracked per-skill in health-check findings (not aggregated in campaign state)
+
+## Workarounds Applied
+
+{{workarounds_list}}
+
+## Duration Breakdown
+
+| Skill | Started | Completed | Duration |
+|-------|---------|-----------|----------|
+{{duration_table}}
+
+## Failed / Skipped Skills
+
+{{failed_skipped_section}}

package/src/skf-campaign/templates/kickoff-template.md

@@ -0,0 +1,48 @@
+# Skill Kickoff — {{skill_name}}
+
+## Campaign Context
+
+- **Campaign:** {{campaign_name}}
+- **Current Stage:** {{current_stage}}
+- **Quality Gate:** {{quality_gate_summary}}
+
+## Skill Identity
+
+- **Skill:** {{skill_name}}
+- **Tier:** {{skill_tier}}
+- **Repository:** {{repo_url}}
+- **Pin:** {{pin}}
+- **Commit:** {{commit_sha}}
+
+## Brief Summary
+
+{{brief_summary}}
+
+## Campaign Facts
+
+{{persistent_facts}}
+
+## Dependency State
+
+{{dependency_status_table}}
+
+## Standing Directive
+
+{{directive_content}}
+
+## Workarounds Applied
+
+{{workarounds_list}}
+
+## Pipeline Instructions
+
+Execute the standard forge pipeline for **{{skill_name}}**:
+
+1. **AN** (Analyze) — scope and source intelligence
+2. **BS** (Brief Synthesis) — generate or validate the skill brief
+3. **CS** (Compile Skill) — compile the SKILL.md artifact
+4. **TS** (Test Skill) — run health-check validation
+
+**Parameters:**
+- Pin: {{pin}}
+- Quality target: {{quality_gate_summary}}

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

@@ -7,7 +7,7 @@ description: Compile a skill from a brief. Supports --batch for multiple briefs.
 
 ## 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.
+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. A single run is not resumable — if it is interrupted mid-compile, re-run from the brief (only `--batch` checkpoints progress across briefs).
 
 ## Conventions
 
@@ -43,6 +43,9 @@ These rules apply to every step in this workflow:
 | 3d | Component Extraction | references/component-extraction.md | Conditional |
 | 4 | Enrich | references/enrich.md | Yes |
 | 5 | Compile | references/compile.md | Yes |
+| 5a | Doc Sources | references/step-doc-sources.md | Yes |
+| 5b | Auto-Shard | references/step-auto-shard.md | Yes |
+| 5c | Doc-Rot | references/step-doc-rot.md | Yes |
 | 6 | Validate | references/validate.md | Conditional |
 | 7 | Generate Artifacts | references/generate-artifacts.md | Yes |
 | 8 | Report | references/report.md | Yes |

package/src/skf-create-skill/assets/compile-assembly-rules.md

@@ -290,6 +290,28 @@ Replace per-function subsections with `references/pattern-*.md` groupings: one r
 
 **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.
 
+### Whole-Language Reference Assembly Overrides
+
+A **whole-language reference** is a compiler/interpreter repo (rustc, CPython, the Go toolchain, TypeScript) enriched with the language's canonical prose — the guide/Book and the standard/library docs. It maps to `scope.type: full-library`, but its value to a skill consumer is the **language**, not the compiler's internal exports. The standard library-export layout above would foreground compiler-internal signatures and bury the prose; these overrides invert that.
+
+**GATE — apply ONLY when this is a whole-language reference.** The brief carries ≥1 `doc_urls` entry with `source: language-registry` (equivalently, `skf-derive-assembly-shape.py` returns `assembly_shape: "whole-language-reference"`). This is a structured, schema-validated signal — NOT a `scope.notes` substring — so an ordinary `full-library` library, a parser *library* (pest/lalrpop — its code IS the product, so §6b seeds no corpora), a component-library, a reference-app (including the language/spec-reference DSL sub-shape, which stays `scope.type: reference-app` and is handled by the reference-app override above), and a docs-only brief all fail the gate. When the gate does NOT fire, **skip this entire section** — the standard Tier 1 (sections 1–8) and Tier 2 (9–11) layout and the signature-fidelity rule run unchanged, so non-whole-language skills assemble byte-identically.
+
+When the gate fires, the assembler has a `language_guide[]` artifact from step 3c §4a (the retained corpora prose, carved out of the T3-vs-T1 conflict rule). Apply these overrides:
+
+**Empty-guide guard (check first):** If `language_guide[]` is absent or every entry's `prose` is null (all registry corpora failed to fetch), do NOT emit a thin Language Guide above a full internals section — fall back to the standard layout and record a warning in `evidence-report.md`: "Whole-language reference gated but no Language-Guide prose was retained — assembled as a standard library skill." This prevents the inverse-value outcome (prose section empty, compiler internals dominant).
+
+**New Section 1b — Language Guide (Tier 1, foregrounded):** Immediately after Section 1 (Overview) and BEFORE Quick Start, emit the skill's primary content from `language_guide[]`. One subsection per corpus (`{label}`), carrying the retained prose — language concepts, idioms, and usage examples — each block cited `[EXT:{url}]`. This is the section an agent reads to learn the language; it survives split-body as Tier 1.
+
+**Section 2 (Quick Start) — language-usage override:** Build the runnable examples from the Language-Guide prose (writing and running code *in* the language — a minimal program, a common idiom), cited `[EXT:{url}]`, NOT from compiler-internal export call chains. Fall back to the standard signature-only Quick Start only if the guide yields no examples.
+
+**Section 3 (Common Workflows) — "Writing {language}" override:** Replace function-call-chain workflows over compiler exports with common language tasks (define a type, handle errors, organize a module), each a short idiom from the guide.
+
+**Section 4 (Key API Summary) — demote compiler internals:** Replace the top-of-body compiler-export function table with a one-paragraph "Standard Library & Language Surface" pointer into the Language Guide. Move the AST/compiler-internal exports into a late-ordered Tier 2 subsection `### Compiler Internals (reference only)` with a one-line note: "Internal implementation surface of the {language} toolchain — most consumers want the Language Guide above, not these."
+
+**Signature fidelity is preserved (NOT relaxed):** this is an ordering/prominence change only. Any compiler signatures that DO appear (in Compiler Internals) keep their T1/AST-authoritative params and return types per Section 1b of `compile.md` and rule 7 below. The override never substitutes prose-derived signatures for AST-extracted ones; it changes which content leads, not which tier wins a per-export signature conflict.
+
+**metadata.json:** the skill stays `scope.type: full-library`; export-count stats are still emitted. (A whole-language skill's low public-API coverage versus the full compiler surface is expected — coverage-gate semantics for this shape are tracked separately and out of scope here.)
+
 ### Assembly Rules
 
 1. Assemble all Tier 1 sections first — these form the essential standalone body

package/src/skf-create-skill/assets/skill-sections.md

@@ -230,6 +230,8 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
   // 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" }],
   // "assets": [{ "file": "assets/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
+  // doc_sources[] — include ONLY when doc detection ran; omit if detection was skipped entirely
+  // "doc_sources": [{ "url": "https://...", "detected_via": "homepageUrl|readme_link|pages_api|docs_folder|readme_always", "content_hash": "sha256:{hex}|null", "recorded_at": "ISO-8601" }],
   "generated_by": "{quick-skill|create-skill}",
   "dependencies": [],
   "compatibility": "{semver-range}"

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

@@ -1,5 +1,5 @@
 ---
-nextStepFile: 'validate.md'
+nextStepFile: 'step-doc-sources.md'
 skillSectionsData: 'assets/skill-sections.md'
 assemblyRulesData: 'assets/compile-assembly-rules.md'
 ---
@@ -54,6 +54,8 @@ 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.
 
+**Shape-specific overrides:** the assembly-rules file defines gated override blocks for `component-library`, `reference-app`, and **whole-language reference** skills. Apply the override whose gate matches this brief. A whole-language reference is gated on `assembly_shape: "whole-language-reference"` (a `doc_urls` entry with `source: language-registry`, as step 3c §1 determined and as `skf-derive-assembly-shape.py` reports) and uses the `language_guide[]` artifact step 3c §4a retained — it foregrounds the Language Guide and demotes compiler internals. When no override gate matches, assemble the standard library-export layout unchanged.
+
 ### 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`.
@@ -115,7 +117,8 @@ Following the structure from the skill-sections data file:
 
     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.
 
-    **Reference-app carve-out:** never emit `effective_denominator` for `scope.type: "reference-app"`, even when the three conditions above are literally satisfied (a reference-app-in-monorepo matches all of them). A reference app's coverage basis is `pattern_surfaces_documented`, not library exports — see the Reference-App stats semantics in `{compileAssemblyRules}`.
+    **Reference-app carve-out:** never emit `effective_denominator` for `scope.type: "reference-app"`, even when the three conditions above are literally satisfied (a reference-app-in-monorepo matches all of them). A reference app's coverage basis is `pattern_surfaces_documented`, not library exports — see the Reference-App stats semantics in `assets/compile-assembly-rules.md`.
+- Set `confidence_distribution` by binning **each documented export exactly once** by its provenance-map `signature_source` tier (`T1` → `t1`, `T1-low` → `t1_low`, `T2` → `t2`, `T3` → `t3`) — the four bins MUST sum to `stats.exports_documented`. Do NOT add T2 annotation counts or T3 doc-item counts on top of the per-export bins; those are enrichment totals and belong in the evidence report's Extraction Summary, not in the distribution. `skf-test-skill` coverage-check §4b enforces this sum as an internal-consistency defect. Carve-outs (mirroring that consumer): a **stack** skill bins the cited constituents (sums to the constituent count, not `exports_documented`); a **reference-app** bins per-citation provenance entries (sums to the citation count, not `pattern_surfaces_documented`)
 - 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

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

@@ -55,7 +55,7 @@ Load `{extractionPatternsData}` completely. Identify the strategy for the curren
 
 From the brief, apply scope and pattern filters:
 
-- `scope.type` — determines what to extract (e.g., `full-library`, `specific-modules`, `public-api`, `component-library`, `reference-app`, `docs-only`). Use `reference-app` when the source is a whole app and the skill's value is wiring patterns rather than public exports (embedded-sidecar reference apps, CLI-demo repos, integration-pattern demonstrators). `reference-app` triggers the compile-assembly overrides in `{compileAssemblyRules}` that replace "Key API Summary" with a "Pattern Surface" section and make `stats.exports_documented` semantics pattern-oriented. Do NOT pick `full-library` for reference apps — downstream assembly will remap wiring onto export slots, producing fuzzy counts and an awkward SKILL.md.
+- `scope.type` — determines what to extract (e.g., `full-library`, `specific-modules`, `public-api`, `component-library`, `reference-app`, `docs-only`). Use `reference-app` when the source is a whole app and the skill's value is wiring patterns rather than public exports (embedded-sidecar reference apps, CLI-demo repos, integration-pattern demonstrators). `reference-app` triggers the compile-assembly overrides in `assets/compile-assembly-rules.md` that replace "Key API Summary" with a "Pattern Surface" section and make `stats.exports_documented` semantics pattern-oriented. Do NOT pick `full-library` for reference apps — downstream assembly will remap wiring onto export slots, producing fuzzy counts and an awkward SKILL.md.
 - `scope.include` — file globs to include
 - `scope.exclude` — file globs to exclude
 
@@ -274,6 +274,14 @@ Compile all extracted data into a structured inventory:
 
 **Docs-only note:** If `docs_only_mode` is active (`extraction_mode: "docs-only"`), display a brief note explaining that T3 content will be added by the doc-fetcher step (step 3c), then auto-proceed past this gate. Example: "Docs-only mode: extraction inventory is empty. Documentation content will be fetched from `doc_urls` in step 3c. Auto-proceeding."
 
+**Zero-export sanity check (source mode):** If `extraction_mode != "docs-only"` AND `export_count == 0` AND the brief declares no `doc_urls`, an empty extraction is almost always an error — a wrong branch/tag, an over-narrow `scope.include`, or a failed AST run — not a valid empty surface. Do NOT let this sail through to a green report. Surface a distinct warning at the gate:
+
+"**⚠️ Zero public exports extracted.** A source-type brief produced no documented surface and declares no `doc_urls`. This usually means a scope/branch/tag mismatch (wrong `target_version`, over-narrow `scope.include`) or a failed AST run — the compiled skill would document nothing. Verify the brief's source ref and scope before continuing.
+
+**[C] Continue anyway** — compile an empty surface (default)"
+
+Under `{headless_mode}`, do NOT auto-pass silently: set `status: "partial"` and `summary.warning: "zero-exports"` on the result contract (carried to step 8's record), log `"headless: zero public exports extracted — likely scope/branch/tag mismatch, continuing"`, append a `headless_decisions[]` entry `{step: "extract", gate: "zero-exports", decision: "C", rationale: "headless mode — zero exports, no human to confirm scope/ref", timestamp: {ISO}}`, and proceed. The distinct warning string surfaces the worst kind of failure (looks green, isn't) where a human or automator can act on it.
+
 Display the extraction findings for user confirmation:
 
 "**Extraction complete.**

package/src/skf-create-skill/references/extraction-patterns.md

@@ -287,7 +287,7 @@ rule:
   pattern: 'export class $NAME { $$$ }'
 ```
 
-> **Important:** The body (`{ $$$ }`) is required on ast-grep 0.42.x. The bare `export class $NAME` pattern returns zero matches — and emits a `Pattern contains an ERROR node` warning — through **both** `find_code()` and the CLI, because an incomplete class declaration does not parse as a complete statement (see Known Limitation #9). With the body present, the simple `find_code()` pattern detects class exports reliably; `find_code_by_rule` would additionally require an explicit AST `kind` rule.
+> **Important:** The body (`{ $$$ }`) is required on ast-grep 0.42.x. The bare `export class $NAME` pattern returns zero matches — and emits a `Pattern contains an ERROR node` warning — through **both** `find_code()` and the CLI, because an incomplete class declaration does not parse as a complete statement (see Known Limitation #9). With the body present, the simple `find_code()` pattern detects class exports reliably — it matches non-generic classes only; generic (`export class $NAME<T>`) and generic-extends (`export class $NAME<T> extends $BASE`) forms are skipped, so source-read them via `^export (abstract )?class` and merge by name+file (see Known Limitation #10). `find_code_by_rule` would additionally require an explicit AST `kind` rule.
 
 **JavaScript/TypeScript — re-export detection (use `find_code`):**
 
@@ -411,6 +411,8 @@ When using ast-grep for extraction, be aware of these documented limitations:
 
    Never silently accept zero results for a declaration form the source language commonly uses.
 
+10. **Generic class declarations do not match non-generic class patterns (ast-grep 0.42.x):** The non-generic patterns `export class $NAME { $$$ }` and `export class $NAME extends $BASE { $$$ }` silently skip every generic form on ast-grep 0.42.2 — verified via both the CLI (`ast-grep run -p ... -l typescript`) and `find_code()`, the first matched only a plain `Plain` and the second only a plain `PlainExtends` on a fixture of `Plain` / `Generic<T>` / `GenericExtends<T> extends Base<T>` / `abstract AbstractGeneric<T>` / `PlainExtends`. The per-shape generic patterns `export class $NAME<$$$P> { $$$ }`, `export class $NAME<$$$P> extends $BASE { $$$ }`, and `export abstract class $NAME<$$$P> { $$$ }` each match exactly **one** shape — no single pattern covers all of them. **Workaround:** Always run a source-read fallback `^export (abstract )?class` over the in-scope `.ts` sources (T1-low) and merge by name+file with the AST results, mirroring the `export function` guidance in #9. The bare `class $NAME` pattern catches every form but over-captures non-exported classes, so it still needs the source-read pass to re-impose the exported-only filter — this is the opposite trade from the Python #7 `^[^_]` re-filter, since TS has no name-prefix convention for exports. Never accept a class inventory that omits generic classes when the source uses them.
+
 ### Component Library Demo/Example Auto-Exclusion
 
 When `scope.type: "component-library"`, auto-detect and propose demo/example exclusions before extraction begins. **User confirmation is required before applying** — some `examples/` directories contain API-level code.