bmad-module-skill-forge 2.0.0 → 2.0.1

package/src/skf-campaign/scripts/campaign-deps.py

@@ -15,7 +15,8 @@ CLI:
 
 Output (JSON on stdout):
   --compute:
-    {"execution_order": [...], "circular_deps_detected": bool, "cycle_participants": [...] | null}
+    {"execution_order": [...], "circular_deps_detected": bool,
+     "cycle_participants": [...] | null, "tier_counts": {"A": int, "B": int}}
 
   --check:
     {"skill": "name", "ready": bool, "unmet_deps": [...], "forced": bool}
@@ -82,6 +83,12 @@ def compute(state_file: str) -> int:
 
     skill_map = _build_skill_map(skills)
 
+    tier_counts = {"A": 0, "B": 0}
+    for skill in skill_map.values():
+        tier = skill.get("tier")
+        if tier in tier_counts:
+            tier_counts[tier] += 1
+
     dangling = _validate_deps(skill_map)
     if dangling:
         _emit_error(
@@ -125,6 +132,7 @@ def compute(state_file: str) -> int:
             "execution_order": execution_order,
             "circular_deps_detected": True,
             "cycle_participants": cycle_participants,
+            "tier_counts": tier_counts,
         }
         json.dump(output, sys.stdout, separators=(",", ":"))
         sys.stdout.write("\n")
@@ -134,6 +142,7 @@ def compute(state_file: str) -> int:
         "execution_order": execution_order,
         "circular_deps_detected": False,
         "cycle_participants": None,
+        "tier_counts": tier_counts,
     }
     json.dump(output, sys.stdout, separators=(",", ":"))
     sys.stdout.write("\n")

package/src/skf-campaign/scripts/campaign-render-batch.py

@@ -0,0 +1,199 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""Campaign Render Batch — build the QS `--batch` input file for Tier B skills.
+
+step-06 batches every Tier B skill through `skf-quick-skill --batch`. The batch
+input file is a machine-consumed cross-tool contract: one target per line in the
+exact single-target shape `skf-quick-skill` parses (see
+src/skf-quick-skill/references/batch-mode.md). Hand-building that file in prose
+is filter + join + reformat-structured-data — the same mechanical, all-or-nothing
+work campaign-parse-manifest.py owns for the inverse direction, where a silent
+format slip corrupts the whole run. This script is the single source of truth for
+the generation side so the line format lives in one place, aligned with the
+consumer's contract, instead of being re-derived in the step prose.
+
+What it does:
+  - Filters `skills[]` for `tier == "B" && status == "pending"` (skips Tier A and
+    any already completed/failed/skipped — resume-safe).
+  - Looks up each skill's `repo_url` from the brief's `targets[]` (matched by
+    name); repo URLs live only in the brief, never in the state schema.
+  - Emits one line per skill in the CONSUMER's single-target shape:
+      {repo_url}                        (pin is null → latest)
+      {repo_url}@{pin}                  (skills[].pin is non-null)
+    with optional ` language=<lang>` / ` scope=<path>` modifiers appended when the
+    brief target carries a `language_hint`/`language` or `scope_hint`/`scope` hint.
+  - No skill-name field, no bare pin token — that would not parse as a target.
+
+CLI:
+  uv run campaign-render-batch.py --state-file <p> --brief-file <p> [-o <batchFile>]
+
+Output:
+  - Batch text (one target per line) to {batchFile} via -o, else to stdout.
+  - JSON summary {written, count, skipped_non_tierB, skipped_non_pending} to stderr.
+
+Exit codes:
+  0  batch file written (0+ targets)
+  2  state file missing / unreadable / bad YAML
+  8  brief missing / unreadable (missing-brief HALT), or a pending Tier B skill
+     has no matching brief target with a repo_url (unmatched-target)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+import yaml
+
+
+def _err(message: str, code: str, exit_code: int, **extra: Any) -> int:
+    payload: Dict[str, Any] = {"error": message, "code": code}
+    payload.update(extra)
+    json.dump(payload, sys.stderr)
+    sys.stderr.write("\n")
+    return exit_code
+
+
+def _target_line(repo_url: str, pin: Any, target: Dict[str, Any]) -> str:
+    """Render one batch line in the consumer's single-target shape."""
+    line = repo_url
+    if pin:
+        line += f"@{pin}"
+    lang = target.get("language_hint") or target.get("language")
+    scope = target.get("scope_hint") or target.get("scope")
+    if lang:
+        line += f" language={lang}"
+    if scope:
+        line += f" scope={scope}"
+    return line
+
+
+def build_batch(state: Dict[str, Any], brief: Dict[str, Any]) -> Tuple[List[str], Dict[str, Any]]:
+    """Filter Tier B pending skills and render batch lines.
+
+    Returns (lines, summary). `summary["unmatched"]` lists any pending Tier B
+    skill names with no brief target / repo_url; the caller HALTs (exit 8) when
+    it is non-empty.
+    """
+    skills = state.get("skills") or []
+    targets: Dict[str, Dict[str, Any]] = {
+        t.get("name"): t
+        for t in (brief.get("targets") or [])
+        if isinstance(t, dict) and t.get("name")
+    }
+
+    lines: List[str] = []
+    unmatched: List[str] = []
+    skipped_non_tierb = 0
+    skipped_non_pending = 0
+
+    for skill in skills:
+        if not isinstance(skill, dict):
+            continue
+        if skill.get("tier") != "B":
+            skipped_non_tierb += 1
+            continue
+        if skill.get("status") != "pending":
+            skipped_non_pending += 1
+            continue
+
+        name = skill.get("name")
+        target = targets.get(name)
+        repo_url = (target or {}).get("repo_url") or ""
+        if not repo_url:
+            unmatched.append(name)
+            continue
+
+        lines.append(_target_line(repo_url, skill.get("pin"), target))
+
+    summary = {
+        "count": len(lines),
+        "skipped_non_tierB": skipped_non_tierb,
+        "skipped_non_pending": skipped_non_pending,
+        "unmatched": unmatched,
+    }
+    return lines, summary
+
+
+def _load_yaml_mapping(path: str) -> Dict[str, Any]:
+    data = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError("top-level document is not a mapping")
+    return data
+
+
+def run(state_file: str, brief_file: str, output: str | None) -> int:
+    # State problems are plain file/parse errors (exit 2).
+    if not Path(state_file).is_file():
+        return _err(f"State file not found: {state_file}", "STATE_NOT_FOUND", 2)
+    try:
+        state = _load_yaml_mapping(state_file)
+    except (yaml.YAMLError, ValueError) as exc:
+        return _err(f"Failed to parse state YAML: {exc}", "STATE_PARSE_ERROR", 2)
+
+    # Brief problems preserve step-06 §4's missing-brief HALT (exit 8): repo_urls
+    # live only in the brief, so a missing/unreadable/corrupt brief is fatal here.
+    if not Path(brief_file).is_file():
+        return _err(f"Brief file not found: {brief_file}", "missing-brief", 8)
+    try:
+        brief = _load_yaml_mapping(brief_file)
+    except OSError as exc:
+        return _err(f"Brief unreadable: {exc}", "missing-brief", 8)
+    except (yaml.YAMLError, ValueError) as exc:
+        return _err(f"Brief unparseable: {exc}", "missing-brief", 8)
+
+    lines, summary = build_batch(state, brief)
+
+    unmatched = summary.pop("unmatched")
+    if unmatched:
+        return _err(
+            "No matching brief target (repo_url) for pending Tier B skill(s): "
+            + ", ".join(str(n) for n in unmatched),
+            "unmatched-target",
+            8,
+            skills=unmatched,
+        )
+
+    batch_text = "\n".join(lines)
+    if batch_text:
+        batch_text += "\n"
+
+    if output:
+        Path(output).write_text(batch_text, encoding="utf-8")
+        summary["written"] = output
+    else:
+        sys.stdout.write(batch_text)
+        summary["written"] = "<stdout>"
+
+    ordered = {
+        "written": summary["written"],
+        "count": summary["count"],
+        "skipped_non_tierB": summary["skipped_non_tierB"],
+        "skipped_non_pending": summary["skipped_non_pending"],
+    }
+    json.dump(ordered, sys.stderr)
+    sys.stderr.write("\n")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="campaign-render-batch",
+        description="Build the QS --batch input file for pending Tier B skills.",
+    )
+    parser.add_argument("--state-file", required=True)
+    parser.add_argument("--brief-file", required=True)
+    parser.add_argument("-o", "--output", dest="output", help="batch file path (default: stdout)")
+    args = parser.parse_args(argv)
+    return run(args.state_file, args.brief_file, args.output)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-campaign/scripts/campaign-status.py

@@ -0,0 +1,162 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""Campaign Status — deterministic state summary + optional backup-drift verdict.
+
+Collapses two in-prompt determinism leaks into one helper the LLM calls instead
+of hand-deriving:
+
+  - `campaign status` and the resume summary block tallied `skills[]` by status
+    ("N completed / M total, K pending, ...") in-prompt over a 15+ skill array.
+  - the `.bak` recovery path compared `primary` vs `backup` timestamps and stage
+    numbers by hand (an ISO-8601 + int compare across two YAML files).
+
+Both are mechanical, one-correct-answer computations. This script owns them so
+identical state always yields identical output.
+
+CLI:
+  uv run campaign-status.py --state-file <path>
+  uv run campaign-status.py --state-file <path> --backup-file <path>
+
+Output (JSON on stdout):
+  {
+    "campaign_name": "...",
+    "current_stage": 0,
+    "last_updated": "...",
+    "total": 0, "completed": 0, "pending": 0,
+    "active": 0, "failed": 0, "skipped": 0,
+    "backup_comparison": null | {
+      "primary_behind": bool,
+      "primary_last_updated": "...", "backup_last_updated": "...",
+      "primary_stage": 0, "backup_stage": 0
+    }
+  }
+
+Exit codes:
+  0  ok
+  2  error (state missing / unreadable / not a mapping)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import yaml
+
+STATUSES = ("pending", "active", "completed", "failed", "skipped")
+
+
+def _err(message: str, code: str) -> int:
+    json.dump({"error": message, "code": code}, sys.stderr)
+    sys.stderr.write("\n")
+    return 2
+
+
+def _load_state(path: Path) -> Optional[Dict[str, Any]]:
+    if not path.is_file():
+        return None
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (yaml.YAMLError, OSError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _parse_iso(value: Any) -> Optional[datetime]:
+    if not isinstance(value, str) or not value:
+        return None
+    text = value[:-1] + "+00:00" if value.endswith("Z") else value
+    try:
+        return datetime.fromisoformat(text)
+    except (ValueError, TypeError):
+        return None
+
+
+def _counts(state: Dict[str, Any]) -> Dict[str, int]:
+    skills = state.get("skills", []) or []
+    tally = {s: 0 for s in STATUSES}
+    for skill in skills:
+        status = skill.get("status")
+        if status in tally:
+            tally[status] += 1
+    tally["total"] = len(skills)
+    return tally
+
+
+def _compare_backup(primary: Dict[str, Any], backup: Dict[str, Any]) -> Dict[str, Any]:
+    p_c = primary.get("campaign", {}) or {}
+    b_c = backup.get("campaign", {}) or {}
+    p_updated = p_c.get("last_updated")
+    b_updated = b_c.get("last_updated")
+    p_stage = p_c.get("current_stage")
+    b_stage = b_c.get("current_stage")
+
+    stage_behind = (
+        isinstance(p_stage, int) and isinstance(b_stage, int) and p_stage < b_stage
+    )
+
+    ts_behind = False
+    p_ts = _parse_iso(p_updated)
+    b_ts = _parse_iso(b_updated)
+    if p_ts is not None and b_ts is not None:
+        try:
+            ts_behind = p_ts < b_ts
+        except TypeError:
+            # naive vs aware datetime — cannot order; defer to stage compare.
+            ts_behind = False
+
+    return {
+        "primary_behind": bool(stage_behind or ts_behind),
+        "primary_last_updated": p_updated,
+        "backup_last_updated": b_updated,
+        "primary_stage": p_stage,
+        "backup_stage": b_stage,
+    }
+
+
+def run(state_file: str, backup_file: Optional[str]) -> int:
+    state = _load_state(Path(state_file))
+    if state is None:
+        return _err(f"State not readable as a mapping: {state_file}", "STATE_UNREADABLE")
+
+    campaign = state.get("campaign", {}) or {}
+    result: Dict[str, Any] = {
+        "campaign_name": campaign.get("name", ""),
+        "current_stage": campaign.get("current_stage"),
+        "last_updated": campaign.get("last_updated"),
+        **_counts(state),
+        "backup_comparison": None,
+    }
+
+    if backup_file:
+        backup = _load_state(Path(backup_file))
+        if backup is not None:
+            result["backup_comparison"] = _compare_backup(state, backup)
+
+    json.dump(result, sys.stdout, separators=(",", ":"), default=str)
+    sys.stdout.write("\n")
+    return 0
+
+
+def main(argv: Optional[list] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="campaign-status",
+        description="Summarize campaign state and (optionally) compare it to its backup.",
+    )
+    parser.add_argument("--state-file", required=True, help="Path to _campaign-state.yaml")
+    parser.add_argument(
+        "--backup-file",
+        help="Path to _campaign-state.yaml.bak; when given, emit backup_comparison",
+    )
+    args = parser.parse_args(argv)
+    return run(args.state_file, args.backup_file)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -1,4 +1,4 @@
-# Machine-generated campaign brief — resume context for fresh sessions (FR-35)
+# Machine-generated campaign brief — resume context for fresh sessions
 # Populated by step-01-setup.md from operator inputs
 
 # Campaign identifier

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

@@ -28,7 +28,7 @@ These rules apply to every step in this workflow:
 - Never include content in SKILL.md that cannot be cited to source code
 - 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
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action, logging each auto-decision to the in-context `headless_decisions[]` buffer AND appending it as a JSON line to the on-disk auto-decision sink (established at step 1 §3) the moment it lands, so the audit trail survives context compaction before step 5 first writes the evidence report
 
 ## Stages
 
@@ -58,7 +58,7 @@ These rules apply to every step in this workflow:
 | Aspect | Detail |
 |--------|--------|
 | **Inputs** | brief_path (path to skill-brief.yaml) [required], --batch [optional] |
-| **Gates** | step 2: Choice Gate [P] (if match) | step 3: Review Gate [C] |
+| **Gates** | step 2: Choice Gate [P] (if match) | step 3: Review Gate [C] | step 6: Content-Quality Gate [C] (if novel tessl suggestions) |
 | **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 |
 
@@ -69,4 +69,15 @@ These rules apply to every step in this workflow:
 
 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 `references/load-brief.md` to begin the workflow.
+3. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append): `{skill-root}/customize.toml` (bundled defaults), `_bmad/custom/skf-create-skill.toml` under `{project-root}` (team overrides, committed), and `_bmad/custom/skf-create-skill.user.toml` under `{project-root}` (personal overrides, gitignored). If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly.
+
+   Apply the resolved values so the surface is not a silent no-op: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (entries prefixed `file:` are paths or globs whose contents load as facts); and stash `{onCompleteCommand}` ← `workflow.on_complete` (empty string = no-op) for the final stage to invoke after the result JSON and metadata.json are finalized. After activation completes, execute each entry in `workflow.activation_steps_append` in order.
+
+4. Load, read the full file, and then execute `references/load-brief.md` to begin the workflow.

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

@@ -1,6 +1,6 @@
 # SKILL.md Compilation Assembly Rules
 
-## Frontmatter (REQUIRED — agentskills.io compliance)
+## Frontmatter (agentskills.io compliance)
 
 ```yaml
 ---
@@ -15,8 +15,8 @@ description: >
 **Frontmatter rules:**
 
 - `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...") AND **MUST include a trigger phrase** so agents know when to match — one of `Use when …`, `Triggers on …`, or `Reach for this when …`. When using `Use when `, follow with a **gerund** (`Use when building/processing/analyzing X…`) or a noun-phrase clause (`Use when the user requests to "X"`); never a bare indicative verb like `builds`/`processes`, because `skill-check --fix` will prepend a literal `Use when ` to a description missing the trigger phrase, producing ungrammatical output (`Use when builds X…`). Inconsistent point-of-view or a missing trigger phrase causes discovery problems since the description is injected into the system prompt. See `skf-brief-skill/assets/description-voice-examples.md` for the canonical voice palette.
-- **`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:
+- `description`: non-empty, max 1024 chars, optimized for agent discovery. Use third-person voice ("Processes Excel files..." not "I can help you..." or "You can use this to...") and include a trigger phrase so agents know when to match — one of `Use when …`, `Triggers on …`, or `Reach for this when …`. When using `Use when `, follow with a **gerund** (`Use when building/processing/analyzing X…`) or a noun-phrase clause (`Use when the user requests to "X"`); never a bare indicative verb like `builds`/`processes`, because `skill-check --fix` will prepend a literal `Use when ` to a description missing the trigger phrase, producing ungrammatical output (`Use when builds X…`). Inconsistent point-of-view or a missing trigger phrase causes discovery problems since the description is injected into the system prompt. See `skf-brief-skill/assets/description-voice-examples.md` for the canonical voice palette.
+- **The `description` cannot 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}` ``.
@@ -27,7 +27,7 @@ description: >
 
 ## Two-Tier Assembly
 
-**CRITICAL: Two-tier assembly.** SKILL.md must retain actionable inline content that survives `split-body` extraction. Assemble Tier 1 sections first (always inline), then Tier 2 sections (reference-eligible, may be extracted by split-body).
+**Two-tier assembly.** SKILL.md must retain actionable inline content that survives `split-body` extraction. Assemble Tier 1 sections first (always inline), then Tier 2 sections (reference-eligible, may be extracted by split-body).
 
 ### Tier 1 — Always Inline (must survive split-body)
 
@@ -104,7 +104,7 @@ These sections form the essential standalone body. Target: **under 300 lines tot
 
 Assemble Sections 9-11 (Full API Reference, Full Type Definitions, Full Integration Patterns) as defined in the skill-sections data file. These contain full detail and are split into `references/` when the body exceeds 500 lines. Include T2 annotations from enrichment in the Full API Reference (Deep tier only).
 
-**CRITICAL — Tier 2 differentiation from Tier 1:** Tier 2 Full API Reference must contain content that is NOT present in Tier 1's Key API Summary. Specifically:
+**Tier 2 differentiation from Tier 1:** Tier 2 Full API Reference must contain content that is not present in Tier 1's Key API Summary. Specifically:
 
 - **Full parameter tables** with types, defaults, and required/optional flags (Tier 1 only lists key params)
 - **Return value details** including structure, types, and error conditions
@@ -112,7 +112,7 @@ Assemble Sections 9-11 (Full API Reference, Full Type Definitions, Full Integrat
 - **Usage examples** from source tests or documentation (Tier 1 has signature-only references)
 - **Edge cases and constraints** — parameter validation rules, size limits, behavioral notes
 
-Do NOT repeat Tier 1's name/purpose/key-params table format in Tier 2. Tier 2 is a deep reference, not a reformatted summary. This distinction prevents conciseness scorers from flagging the two-tier design as redundancy.
+Do not repeat Tier 1's name/purpose/key-params table format in Tier 2. Tier 2 is a deep reference, not a reformatted summary. This distinction prevents conciseness scorers from flagging the two-tier design as redundancy.
 
 ### Component Library Assembly Overrides
 
@@ -267,8 +267,8 @@ Replace per-function subsections with `references/pattern-*.md` groupings: one r
 
 - `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).
-- Do NOT emit `effective_denominator` for reference-app scope, even when the source is a monorepo. `effective_denominator` counts public exports from the authoring-surface barrel — a library concept that `pattern_surfaces_documented` already replaces here. A reference-app-in-monorepo literally satisfies `compile.md` §4's emit-conditions (monorepo + non-`full-library` + stratified `scope.notes`), so this carve-out takes precedence: pattern-surface coverage is the reference-app basis, and skf-test-skill skips library-export coverage for it.
+- 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).
+- Do not emit `effective_denominator` for reference-app scope, even when the source is a monorepo. `effective_denominator` counts public exports from the authoring-surface barrel — a library concept that `pattern_surfaces_documented` already replaces here. A reference-app-in-monorepo literally satisfies `compile.md` §4's emit-conditions (monorepo + non-`full-library` + stratified `scope.notes`), so this carve-out takes precedence: pattern-surface coverage is the reference-app basis, and skf-test-skill skips library-export coverage for it.
 
 **Language / spec-reference sub-shape:** A reference app that documents an engine- or spec-versioned **language** — a query language, grammar, or DSL (e.g. SurrealQL @ SurrealDB) whose value is construct idioms rather than wiring or exports — is a recognized reference-app sub-shape. Keep `scope.type: "reference-app"` (there is no separate enum value), so every carve-out above applies unchanged (`pattern_surfaces_documented` proxy, no `effective_denominator`, test-skill signature/type skip). Adapt the three overrides to the language's surface instead of app wiring:
 
@@ -288,27 +288,27 @@ Replace per-function subsections with `references/pattern-*.md` groupings: one r
 - **Tier 2** groups `references/*.md` by **language concern** (e.g. `statements.md`, `functions.md`, `types.md`) — one file per construct family — instead of `pattern-*.md` wiring concerns.
 - **metadata.json:** `pattern_surfaces_documented` counts the documented construct areas; the no-`effective_denominator` carve-out applies (a language has no export barrel). The brief's `language` field records the **documented** language (e.g. `surrealql`), which may differ from the source language it was extracted from (e.g. `rust`) — see `skf-analyze-source/assets/skill-brief-schema.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.
+**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.
+**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).
+**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 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.
+**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.)
 
@@ -316,7 +316,7 @@ When the gate fires, the assembler has a `language_guide[]` artifact from step 3
 
 1. Assemble all Tier 1 sections first — these form the essential standalone body
 2. Assemble all Tier 2 sections after — these are progressive disclosure detail
-3. Tier 1 content MUST be under 300 lines (excluding frontmatter)
+3. Tier 1 content stays under 300 lines (excluding frontmatter)
 4. If Tier 1 alone exceeds 300 lines, reduce Key API Summary and Architecture at a Glance
 5. Tier 1 sections are kept short enough that `split-body` targets the larger Tier 2 sections (`## Full ...` headings) instead
 6. After split-body, SKILL.md must still contain all Tier 1 sections with actionable content
@@ -330,32 +330,11 @@ When the gate fires, the assembler has a `language_guide[]` artifact from step 3
 
 ### Content Quality Rules
 
-These rules apply to all content assembled in SKILL.md and reference files.
+These SKF-specific rules apply to all content assembled in SKILL.md and reference files. Generic authoring craft — matching instruction freedom to task fragility, consistent terminology, avoiding time-sensitive instructions, progress checklists for multi-step workflows, and the plan-validate-execute pattern for batch/destructive operations — is assumed and not re-taught here. Only the two rules below encode a non-obvious SKF constraint or downstream-validator quirk that an author would not otherwise infer.
 
-**Degrees of freedom:** Match instruction specificity to the task's fragility and variability:
-- **High freedom** (text guidance): When multiple approaches are valid and context determines the best one. Example: code review patterns, architecture suggestions.
-- **Medium freedom** (pseudocode/parameterized scripts): When a preferred pattern exists but variation is acceptable. Example: configuration templates, report generation.
-- **Low freedom** (exact scripts, no parameters): When operations are fragile and consistency is critical. Example: database migrations, deployment sequences. Use "Run exactly this" language.
+**Zero-hallucination examples:** Include input/output or usage examples ONLY when concrete pairs exist in source tests or official docs — 2-3 such pairs convey the desired style and detail more clearly than a description alone. If no examples exist in source, note the gap rather than fabricating pairs — zero hallucination applies.
 
-**Consistent terminology:** Choose one term per concept and use it throughout the skill. Do not mix synonyms (e.g., "API endpoint" vs "URL" vs "route", or "field" vs "box" vs "element"). Consistency helps agents understand and follow instructions deterministically.
-
-**Avoid time-sensitive information:** Do not include date-conditional instructions ("If before August 2025, use the old API"). Instead, document the current method and place deprecated patterns in a collapsible "Old patterns" section with the deprecation date.
-
-**Template and examples patterns:**
-- **For strict requirements** (API responses, data formats): Provide an exact template with "ALWAYS use this exact structure" language.
-- **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:
+**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:
-- [ ] Step 1: {action}
-- [ ] Step 2: {action}
-```
-
-**Verifiable intermediate outputs:** For skills involving batch operations, destructive changes, or complex validation, recommend the plan-validate-execute pattern: create a structured plan file (e.g., `changes.json`), validate it with a script, then execute. This catches errors before changes are applied.