bmad-module-skill-forge 1.6.0 → 1.7.0

package/src/shared/scripts/skf-scan-skill-md-structure.py

@@ -97,28 +97,38 @@ from pathlib import Path
 
 # These mirror the canonical synonyms documented in
 # `src/skf-test-skill/references/coherence-check.md` §2.1, with the
-# SKF-template-specific headings (`Quick Start`, `Common Workflows`,
-# `Key API Summary`) folded in so they are first-class matches rather
-# than literal-name misses (per the §2.1 "Note" paragraph).
+# SKF-template-specific headings folded in so they are first-class
+# matches rather than literal-name misses (per the §2.1 "Note"
+# paragraph). The set covers the Deep/create-skill template
+# (`Quick Start`, `Common Workflows`, `Key API Summary`, `Key Types`),
+# the quick-skill template (`Usage Patterns`, `Key Exports`), and the
+# reference-app assembly overrides (`Adoption Steps` replaces Common
+# Workflows for usage; `Pattern Surface` replaces Key API Summary for
+# api_surface), since headings are matched on the full heading text,
+# not a substring.
 REQUIRED_SYNONYMS: dict[str, list[str]] = {
     "description": ["Description", "Overview", "Purpose", "Summary"],
     "usage": [
         "Usage",
+        "Usage Patterns",
         "Examples",
         "How to use",
         "Quickstart",
         "Quick Start",
         "Getting Started",
         "Common Workflows",
+        "Adoption Steps",
     ],
     "api_surface": [
         "API",
         "API Surface",
         "Exports",
+        "Key Exports",
         "Public API",
         "Interface",
         "Reference",
         "Key API Summary",
+        "Pattern Surface",
     ],
 }
 

package/src/shared/scripts/skf-validate-brief-inputs.py

@@ -14,10 +14,20 @@ CLI:
   echo '{...}' | uv run skf-validate-brief-inputs.py
 
 Input (JSON object on stdin or via --json):
-  Required:
+  Required (derive route — deriving a new brief from a repo/docs target):
     target_repo  — string (URL or path); error if absent
     skill_name   — string (kebab-case); error if absent or malformed
 
+  Ratify route (ratifying a pre-authored brief):
+    from_brief   — string path to an existing skill-brief.yaml (file or
+                   containing directory). When supplied, the run ratifies
+                   that brief instead of deriving one: target_repo and
+                   skill_name become optional (derived from the brief) and
+                   are ignored with a warning if also passed. The path's
+                   existence and the brief's schema are checked downstream
+                   by skf-validate-brief-schema.py — this validator only
+                   enforces that from_brief is a non-empty string.
+
   Optional with enum constraints:
     source_type      — "source" | "docs-only" (default "source")
     source_authority — "official" | "community" | "internal" (default "community")
@@ -63,6 +73,7 @@ from typing import Any
 KNOWN_FIELDS = {
     "target_repo",
     "skill_name",
+    "from_brief",
     "source_type",
     "source_authority",
     "scope_type",
@@ -113,23 +124,68 @@ def validate(inp: dict[str, Any]) -> dict[str, Any]:
     errors: list[dict[str, str]] = []
     warnings: list[dict[str, str]] = []
 
-    # Required: target_repo, skill_name
     target_repo = inp.get("target_repo")
     skill_name = inp.get("skill_name")
-    if not target_repo:
-        errors.append(_err("target_repo", "missing required argument target_repo"))
-    if not skill_name:
-        errors.append(_err("skill_name", "missing required argument skill_name"))
 
-    # skill_name format
-    if skill_name and isinstance(skill_name, str) and not KEBAB_RE.match(skill_name):
-        errors.append(
-            _err(
-                "skill_name",
-                f"skill_name must be kebab-case (lowercase letters/digits/hyphens, "
-                f"no leading or trailing hyphen). Got: {skill_name!r}",
+    # Ratify route: `from_brief` points at a pre-authored brief to ratify. When
+    # supplied it is the source of truth — target_repo / skill_name are derived
+    # from the brief, so they are neither required nor format-checked here, and
+    # are ignored (with a warning) if also passed. A null `from_brief` is treated
+    # as "absent" so callers can pass it unconditionally.
+    from_brief = inp.get("from_brief")
+    ratify_route = from_brief is not None
+    if ratify_route:
+        if not isinstance(from_brief, str):
+            errors.append(
+                _err(
+                    "from_brief",
+                    f"from_brief must be a string path to a skill-brief.yaml. "
+                    f"Got type {type(from_brief).__name__}",
+                )
+            )
+        elif not from_brief.strip():
+            errors.append(
+                _err(
+                    "from_brief",
+                    "from_brief is required but was empty — supply a path to a "
+                    "skill-brief.yaml (file or containing directory)",
+                )
+            )
+        else:
+            # Valid from_brief value — flag any redundant derive-route args.
+            if target_repo:
+                warnings.append(
+                    _err(
+                        "target_repo",
+                        "target_repo is ignored when from_brief is supplied — the "
+                        "ratify route derives the target from the brief",
+                    )
+                )
+            if skill_name:
+                warnings.append(
+                    _err(
+                        "skill_name",
+                        "skill_name is ignored when from_brief is supplied — the "
+                        "ratify route derives the name from the brief",
+                    )
+                )
+
+    # Required (derive route only): target_repo, skill_name
+    if not ratify_route:
+        if not target_repo:
+            errors.append(_err("target_repo", "missing required argument target_repo"))
+        if not skill_name:
+            errors.append(_err("skill_name", "missing required argument skill_name"))
+
+        # skill_name format
+        if skill_name and isinstance(skill_name, str) and not KEBAB_RE.match(skill_name):
+            errors.append(
+                _err(
+                    "skill_name",
+                    f"skill_name must be kebab-case (lowercase letters/digits/hyphens, "
+                    f"no leading or trailing hyphen). Got: {skill_name!r}",
+                )
             )
-        )
 
     # source_type enum
     source_type_raw = inp.get("source_type", "source")
@@ -186,15 +242,20 @@ def validate(inp: dict[str, Any]) -> dict[str, Any]:
                 )
             )
 
-    # docs-only requires doc_urls
+    # docs-only requires doc_urls — derive route only. On the ratify route the
+    # brief on disk is the source of truth for source_type/doc_urls, so a
+    # redundant `source_type: docs-only` arg must not HALT a run whose doc_urls
+    # live in the brief rather than the args.
     doc_urls = inp.get("doc_urls")
-    if source_type == "docs-only" and not doc_urls:
+    if not ratify_route and source_type == "docs-only" and not doc_urls:
         errors.append(
             _err("doc_urls", "doc_urls is required when source_type is docs-only")
         )
 
-    # target_repo shape (warning only — script doesn't HEAD-check)
-    if isinstance(target_repo, str) and target_repo:
+    # target_repo shape (warning only — script doesn't HEAD-check). Skipped on
+    # the ratify route, where target_repo is already flagged as ignored above —
+    # a second "doesn't look like a URL" warning would just be noise.
+    if not ratify_route and isinstance(target_repo, str) and target_repo:
         looks_like_url = URL_RE.match(target_repo) is not None
         looks_like_path = (
             target_repo.startswith("/")

package/src/shared/scripts/skf-validate-brief-schema.py

@@ -46,6 +46,7 @@ Exit codes:
 from __future__ import annotations
 
 import argparse
+import datetime
 import json
 import sys
 from pathlib import Path
@@ -133,6 +134,18 @@ def _translate_jsonschema_error(err) -> dict:
             ),
         }
     if validator == "type":
+        # A bare YAML date/datetime scalar (e.g. `created: 2026-05-01` without
+        # quotes) parses as a Python date, not a string. Give an actionable
+        # "quote it" hint instead of the opaque "has type `date`" message.
+        if isinstance(inst, datetime.date) and err.validator_value == "string":
+            return {
+                "field": field,
+                "message": (
+                    f"Brief validation failed: `{field}` was parsed as a YAML date, "
+                    f"not a string. Quote it (e.g. `'2026-05-01'`) so it is stored as "
+                    f"text. Update your skill-brief.yaml and re-run."
+                ),
+            }
         expected = err.validator_value
         actual = type(inst).__name__
         return {
@@ -207,6 +220,33 @@ def _docs_only_rules(brief: dict) -> tuple[list[dict], list[dict]]:
     return errors, warnings
 
 
+def _target_version_matches_version_rule(brief: dict) -> list[dict]:
+    """`target_version`, when present, must equal `version` (writer invariant).
+
+    The JSON schema constrains both fields to the semver pattern independently
+    but cannot express their cross-field equality. Without this check, a brief
+    with mismatched `target_version`/`version` passes schema validation (the
+    ratify gate) and only fails later at the writer's `assemble_brief`
+    invariant. Surfacing it here turns that into a clean `brief-invalid` at the
+    validation step. Non-string values are left to the schema's pattern/type
+    rules — we only compare when both are strings.
+    """
+    tv = brief.get("target_version")
+    v = brief.get("version")
+    if isinstance(tv, str) and isinstance(v, str) and tv != v:
+        return [
+            {
+                "field": "target_version",
+                "message": (
+                    f"Brief validation failed: `target_version` (`{tv}`) must equal "
+                    f"`version` (`{v}`). When `target_version` is set it becomes the "
+                    f"skill's version. Update your skill-brief.yaml and re-run."
+                ),
+            }
+        ]
+    return []
+
+
 def _version_non_empty_rule(brief: dict) -> list[dict]:
     """The §3 prose calls out version-whitespace-only as a hard error."""
     version = brief.get("version")
@@ -246,6 +286,7 @@ def validate_brief(brief: dict) -> dict:
     warnings.extend(cond_warnings)
 
     errors.extend(_version_non_empty_rule(brief))
+    errors.extend(_target_version_matches_version_rule(brief))
 
     return {
         "valid": not errors,
@@ -260,7 +301,12 @@ def validate_brief(brief: dict) -> dict:
 
 
 def _emit(envelope: dict) -> None:
-    json.dump(envelope, sys.stdout, indent=2)
+    # default=str keeps the echoed `brief` serializable even when it contains
+    # non-JSON scalars (e.g. a YAML date object from an unquoted `created:`
+    # field). Without it, emitting the invalid-brief envelope would crash with
+    # `TypeError: Object of type date is not JSON serializable` instead of
+    # returning the graded brief-invalid result.
+    json.dump(envelope, sys.stdout, indent=2, default=str)
     sys.stdout.write("\n")
 
 

package/src/shared/scripts/skf-validate-frontmatter.py

@@ -20,17 +20,24 @@ system-wide:
 
   uv run skf-validate-frontmatter.py <skill-md-path>
   uv run skf-validate-frontmatter.py <skill-md-path> --skill-dir-name <name>
+  uv run skf-validate-frontmatter.py <skill-md-path> --max-body-lines 500
 
 Input:
   Path to a SKILL.md file.
   Optional --skill-dir-name: expected directory name for name-match check.
   If omitted, derived from the parent directory of the SKILL.md path.
+  Optional --max-body-lines N: when set, emit a high-severity `body` issue
+  if the SKILL.md body (lines after the closing frontmatter delimiter)
+  exceeds N lines. Opt-in — when omitted, body size is never checked and
+  the verdict is unchanged. Callers pass the skill-check `body.max_lines`
+  default (500) to pre-catch that hard reject before commit.
 
 Output:
   JSON object:
     status:     "pass" | "fail" | "warn"
     issues:     list of { severity, field, message }
     frontmatter: parsed frontmatter dict (if parseable)
+    body_lines: int body-line count, or null when delimiters are absent
     summary:    { total, high, medium, low }
 
 Exit codes:
@@ -122,6 +129,31 @@ def parse_frontmatter(content: str) -> tuple[dict | None, list[dict]]:
     return fm, issues
 
 
+def body_line_count(content: str) -> int | None:
+    """Count the SKILL.md body lines — every line after the closing
+    frontmatter delimiter.
+
+    Mirrors skill-check's `body.max_lines` definition (body = content past
+    the frontmatter block) so a pre-commit gate keyed on this count agrees
+    with the post-commit `npx skill-check` verdict. Returns None when the
+    frontmatter delimiters are absent or unclosed — the body boundary is
+    then undefined and size cannot be assessed. Uses splitlines() to match
+    the line-counting convention used elsewhere in the SKF scripts (handles
+    LF/CRLF, no trailing-newline phantom line).
+    """
+    if not content.startswith("---\n") and not content.startswith("---\r\n"):
+        return None
+    lines = content.splitlines()
+    closing = -1
+    for i in range(1, len(lines)):
+        if lines[i] == "---":
+            closing = i
+            break
+    if closing == -1:
+        return None
+    return len(lines) - (closing + 1)
+
+
 def _validate_name(name: str, skill_dir_name: str | None) -> list[dict]:
     """Validate skill name format. Aligned with canonical validator.py."""
     issues: list[dict] = []
@@ -187,13 +219,26 @@ def _validate_name(name: str, skill_dir_name: str | None) -> list[dict]:
 def validate_frontmatter(
     content: str,
     skill_dir_name: str | None = None,
+    max_body_lines: int | None = None,
 ) -> dict:
     """Validate SKILL.md frontmatter against agentskills.io spec.
 
-    Returns a result dict with status, issues, frontmatter, and summary.
+    When `max_body_lines` is set, additionally emit a high-severity `body`
+    issue if the body exceeds that many lines (opt-in — the verdict is
+    unchanged when it is None, so the other consumers of this validator are
+    unaffected). Returns a result dict with status, issues, frontmatter,
+    body_lines, and summary.
     """
     fm, issues = parse_frontmatter(content)
 
+    body_lines = body_line_count(content)
+    if max_body_lines is not None and body_lines is not None and body_lines > max_body_lines:
+        issues.append({
+            "severity": "high",
+            "field": "body",
+            "message": f"body lines {body_lines} exceeds max {max_body_lines}",
+        })
+
     if fm is not None:
         # Name validation
         name = fm.get("name", "")
@@ -255,6 +300,7 @@ def validate_frontmatter(
         "status": status,
         "issues": issues,
         "frontmatter": fm,
+        "body_lines": body_lines,
         "summary": {
             "total": len(issues),
             **severity_counts,
@@ -288,6 +334,17 @@ def main() -> int:
         default=None,
         help="expected skill directory name (default: derived from parent directory)",
     )
+    parser.add_argument(
+        "--max-body-lines",
+        metavar="N",
+        type=int,
+        default=None,
+        help=(
+            "when set, emit a high-severity 'body' issue if the SKILL.md body "
+            "exceeds N lines (opt-in; omitted = body size not checked). Pass "
+            "the skill-check body.max_lines default (500) to pre-catch that reject."
+        ),
+    )
     parser.add_argument(
         "-o", "--output",
         metavar="FILE",
@@ -302,12 +359,13 @@ def main() -> int:
             "status": "fail",
             "issues": [{"severity": "high", "field": "file", "message": f"File not found: {skill_md_path}"}],
             "frontmatter": None,
+            "body_lines": None,
             "summary": {"total": 1, "high": 1, "medium": 0, "low": 0},
         }
     else:
         content = skill_md_path.read_text(encoding="utf-8")
         skill_dir_name = args.skill_dir_name or skill_md_path.parent.name
-        result = validate_frontmatter(content, skill_dir_name)
+        result = validate_frontmatter(content, skill_dir_name, args.max_body_lines)
 
     output_text = json.dumps(result, indent=2)
 

package/src/shared/scripts/skf-write-skill-brief.py

@@ -44,14 +44,19 @@ Context payload shape (consumed by `write`):
       "type":    "full-library" | ...,
       "include": ["src/**/*.ts"],
       "exclude": ["**/*.test.*"],
-      "notes":   ""
+      "notes":   "",
+      # Conditionally present (preserved verbatim on a ratify/re-write):
+      "tier_a_include": ["code/core/src/**"],   # stratified-scope monorepos
+      "amendments":     [{...}]                 # post-authoring audit log
     },
 
     # Conditionally present:
     "doc_urls":         [{"url": "...", "label": "..."}],
     "scripts_intent":   "detect" | "none" | free-text,
     "assets_intent":    "detect" | "none" | free-text,
-    "source_authority": "official" | "community" | "internal"
+    "source_authority": "official" | "community" | "internal",
+    "target_ref":       "livekit/v0.7.42",   # monorepo tag escape hatch
+    "source_ref":       "v0.5.0"             # auto-resolved git ref
   }
 
 Version precedence (resolved into the rendered YAML's `version` field):
@@ -84,14 +89,18 @@ Flat input form (`--from-flat`):
     "forge_tier":       "Quick",
     "created":          "2026-05-02",
     "created_by":       "armel",
-    "scope_type":       "full-library",
-    "scope_include":    ["src/**/*.ts"],
-    "scope_exclude":    ["**/*.test.*"],
-    "scope_notes":      "",
-    "doc_urls":         null | [...],
-    "scripts_intent":   null | "detect" | "none" | "...",
-    "assets_intent":    null | "detect" | "none" | "...",
-    "source_authority": null | "official" | "community" | "internal"
+    "scope_type":           "full-library",
+    "scope_include":        ["src/**/*.ts"],
+    "scope_exclude":        ["**/*.test.*"],
+    "scope_notes":          "",
+    "scope_tier_a_include": null | ["code/core/src/**"],
+    "scope_amendments":     null | [{...}],
+    "doc_urls":             null | [...],
+    "scripts_intent":       null | "detect" | "none" | "...",
+    "assets_intent":        null | "detect" | "none" | "...",
+    "source_authority":     null | "official" | "community" | "internal",
+    "target_ref":           null | "livekit/v0.7.42",
+    "source_ref":           null | "v0.5.0"
   }
 
 Output (success):
@@ -293,6 +302,42 @@ def validate_context(ctx: dict[str, Any]) -> list[str]:
                     field=f"scope.rationale.{rk}",
                 )
 
+    # scope.tier_a_include — optional narrower tier-A include list for
+    # stratified-scope monorepos (read by skf-test-skill for the coverage
+    # denominator). Absent/None → key omitted. When present it must be a list
+    # of glob strings; the writer preserves it verbatim so a ratify/re-write
+    # does not silently drop it.
+    tier_a_include = scope.get("tier_a_include")
+    if tier_a_include is not None:
+        if not isinstance(tier_a_include, list):
+            _die("scope.tier_a_include must be an array of glob strings", field="scope.tier_a_include")
+        for i, pat in enumerate(tier_a_include):
+            if not isinstance(pat, str) or not pat:
+                _die(
+                    f"scope.tier_a_include[{i}] must be a non-empty glob string",
+                    field="scope.tier_a_include",
+                )
+
+    # scope.amendments — optional additive audit log written post-authoring by
+    # skf-create-skill / skf-update-skill. The writer is not the amendments
+    # schema authority (those workflows own the entry shape); it only preserves
+    # the log verbatim on re-write. Light check: a list of objects.
+    amendments = scope.get("amendments")
+    if amendments is not None:
+        if not isinstance(amendments, list):
+            _die("scope.amendments must be an array of amendment objects", field="scope.amendments")
+        for i, entry in enumerate(amendments):
+            if not isinstance(entry, dict):
+                _die(f"scope.amendments[{i}] must be an object", field="scope.amendments")
+
+    # target_ref / source_ref — optional git refs (top-level). target_ref is a
+    # remote-monorepo tag escape hatch; source_ref is the auto-resolved ref.
+    # Both must round-trip on a ratify/re-write rather than being dropped.
+    for ref_field in ("target_ref", "source_ref"):
+        ref_val = ctx.get(ref_field)
+        if ref_val is not None and (not isinstance(ref_val, str) or not ref_val):
+            _die(f"{ref_field} must be a non-empty string when present", field=ref_field)
+
     # target_version semver shape (when present)
     tv = ctx.get("target_version")
     if tv is not None:
@@ -320,6 +365,19 @@ def assemble_brief(ctx: dict[str, Any], resolved_version: str) -> dict[str, Any]
     if source_type == "docs-only":
         source_authority = "community"  # forced
 
+    # Build the scope sub-object. tier_a_include (when present) sits between
+    # exclude and notes, matching the schema doc's illustrative order. Absent →
+    # the key is omitted, so briefs without it render byte-identically to before.
+    scope_obj: dict[str, Any] = {
+        "type": ctx["scope"]["type"],
+        "include": list(ctx["scope"]["include"]),
+        "exclude": list(ctx["scope"]["exclude"]),
+    }
+    scope_tier_a = ctx["scope"].get("tier_a_include")
+    if scope_tier_a is not None:
+        scope_obj["tier_a_include"] = list(scope_tier_a)
+    scope_obj["notes"] = ctx["scope"]["notes"]
+
     brief: dict[str, Any] = {
         "name": ctx["name"],
         "version": resolved_version,
@@ -330,12 +388,7 @@ def assemble_brief(ctx: dict[str, Any], resolved_version: str) -> dict[str, Any]
         "forge_tier": ctx["forge_tier"],
         "created": ctx["created"],
         "created_by": ctx["created_by"],
-        "scope": {
-            "type": ctx["scope"]["type"],
-            "include": list(ctx["scope"]["include"]),
-            "exclude": list(ctx["scope"]["exclude"]),
-            "notes": ctx["scope"]["notes"],
-        },
+        "scope": scope_obj,
     }
 
     # Conditional: scope.rationale — canonical position is after `notes` and
@@ -353,6 +406,13 @@ def assemble_brief(ctx: dict[str, Any], resolved_version: str) -> dict[str, Any]
             "recorded": scope_rationale["recorded"],
         }
 
+    # Conditional: scope.amendments — additive audit log, emitted verbatim after
+    # rationale (matches the schema doc order). The writer preserves it as-is;
+    # the writing authority for entry shape is skf-create-skill / skf-update-skill.
+    scope_amendments = ctx["scope"].get("amendments")
+    if scope_amendments is not None:
+        brief["scope"]["amendments"] = scope_amendments
+
     # Conditional: target_version (must equal version)
     tv = ctx.get("target_version")
     if tv is not None:
@@ -364,6 +424,14 @@ def assemble_brief(ctx: dict[str, Any], resolved_version: str) -> dict[str, Any]
             )
         brief["target_version"] = tv
 
+    # Conditional: target_ref / source_ref git refs — preserved verbatim when
+    # present (monorepo tag escape hatch + auto-resolved ref). Emitted after
+    # target_version so a ratify/re-write does not strip them.
+    for ref_field in ("target_ref", "source_ref"):
+        ref_val = ctx.get(ref_field)
+        if ref_val is not None:
+            brief[ref_field] = ref_val
+
     # Conditional: doc_urls (always emitted when present)
     doc_urls = ctx.get("doc_urls")
     if doc_urls:
@@ -412,8 +480,11 @@ def atomic_write(target: Path, content: str) -> int:
     target.parent.mkdir(parents=True, exist_ok=True)
     tmp = target.with_name(target.name + ".skf-tmp")
     encoded = content.encode("utf-8")
+    # O_BINARY (Windows only; 0 elsewhere) suppresses the text-mode \n -> \r\n
+    # translation that would otherwise corrupt verbatim writes on Windows.
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_BINARY", 0)
     try:
-        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+        fd = os.open(tmp, flags, 0o644)
         try:
             os.write(fd, encoded)
             os.fsync(fd)
@@ -439,6 +510,8 @@ _FLAT_SCOPE_KEYS = (
     "scope_exclude",
     "scope_notes",
     "scope_rationale",
+    "scope_tier_a_include",
+    "scope_amendments",
 )
 
 
@@ -493,6 +566,13 @@ def flat_to_nested(flat: dict[str, Any]) -> dict[str, Any]:
         # six-subkey object validated by validate_context.
         if "scope_rationale" in flat and flat["scope_rationale"] is not None:
             scope["rationale"] = flat["scope_rationale"]
+        # Optional stratified-scope tier-A include list and post-authoring
+        # amendments log. Same null-drop semantics — preserved on a ratify
+        # re-write so the brief's authored surface and audit trail survive.
+        if "scope_tier_a_include" in flat and flat["scope_tier_a_include"] is not None:
+            scope["tier_a_include"] = flat["scope_tier_a_include"]
+        if "scope_amendments" in flat and flat["scope_amendments"] is not None:
+            scope["amendments"] = flat["scope_amendments"]
         nested["scope"] = scope
     return nested
 

package/src/skf-analyze-source/assets/skill-brief-schema.md

@@ -27,6 +27,7 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | `scripts_intent`   | string | `detect` / `none` / free-text                    | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
 | `assets_intent`    | string | `detect` / `none` / free-text                    | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/").        |
 | `target_version`   | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | User-specified target version. When present, overrides auto-detection and becomes the skill's version. Recommended for docs-only skills where auto-detection is unavailable.                                                   |
+| `target_ref`       | string | Git ref (tag or branch)                          | Optional. Explicit git ref used verbatim as the resolved `source_ref`, bypassing version-to-tag matching. Escape hatch for monorepo crate tags whose prefix differs from the skill name (e.g. tag `livekit/v0.7.42` for skill `livekit-rust`). Remote sources only. |
 | `source_authority` | string | `official` / `community` / `internal`            | Default `community`. Set to `official` only when the skill creator is the library maintainer. Forced to `community` when `source_type: "docs-only"`.                                                                           |
 | `source_ref`       | string | Git ref (tag/branch/HEAD)                        | Resolved git ref used for source access. Set automatically during tag resolution — do not set manually.                                                                                                                        |
 
@@ -59,11 +60,15 @@ The create-skill workflow (extract) also performs version reconciliation at extr
 
 ```yaml
 scope:
-  type: full-library | specific-modules | public-api | component-library | docs-only
+  type: full-library | specific-modules | public-api | component-library | reference-app | docs-only
   include:
     - 'src/**/*.ts'          # At least one required
   exclude:
     - 'src/**/*.test.ts'     # Optional
+  # Optional: narrower tier-A include list for stratified-scope monorepos
+  # and reference-app pattern surfaces (refined later by skf-brief-skill)
+  # tier_a_include:
+  #   - 'code/core/src/manager-api/**'
   notes: 'Optional rationale for scope decision'
   # Additional fields when scope.type is "component-library":
   # registry_path: "path/to/registry.ts"  # Optional — auto-detected if omitted
@@ -83,8 +88,11 @@ scope:
 | specific-modules  | Selected components or packages                                                      |
 | public-api        | Only exported interfaces                                                             |
 | component-library | UI component libraries with registries, props-based APIs, and design system variants |
+| reference-app     | Whole app whose value is wiring patterns, not public exports (embedded sidecars, CLI demos, integration-pattern demonstrators). Also the home for **language / spec references** — engine- or spec-versioned query languages, grammars, or DSLs (e.g. SurrealQL) whose value is construct idioms, not exports. These have no separate scope type; they ride `reference-app` as a sub-shape (see `skf-create-skill` Language / spec-reference sub-shape) |
 | docs-only         | When source_type is docs-only — no source code available, all content from doc_urls  |
 
+> **Documented vs source language.** The `language` field records the language the skill *documents*. For a language / spec reference this may differ from the source language it is extracted from — e.g. a SurrealQL reference extracted from a Rust engine records `language: surrealql`, not `rust`. Use the documented language and a matching code-fence default (e.g. ` ```surql `) throughout the brief.
+
 ## YAML Template
 
 ```yaml
@@ -111,7 +119,7 @@ created_by: '{user_name}'
 1. **Name uniqueness**: No duplicate names within forge_data_folder
 2. **Source accessibility**: source_repo path must exist or be reachable
 3. **Language recognized**: Must be a known programming language
-4. **Scope type valid**: Must match one of the five defined types (full-library, specific-modules, public-api, component-library, docs-only)
+4. **Scope type valid**: Must match one of the six defined types (full-library, specific-modules, public-api, component-library, reference-app, docs-only)
 5. **Include patterns**: At least one include glob pattern required (exception: `docs-only` scope, where include patterns are optional since no source code is available)
 6. **Forge tier match**: Must match value in forge-tier.yaml
 7. **Docs-only mode**: When `source_type: "docs-only"`, `doc_urls` required (>= 1), `source_repo` optional