bmad-module-skill-forge 1.6.0 → 1.8.0

package/src/shared/scripts/skf-rebuild-managed-sections.py

@@ -21,6 +21,7 @@ Actions:
 from __future__ import annotations
 
 import json
+import os
 import re
 import sys
 from datetime import datetime, timezone
@@ -47,6 +48,64 @@ def find_managed_section(content):
     return MARKER_PATTERN.search(content)
 
 
+def _atomic_write(file_path, text):
+    """Stage `text` into <file>.skf-tmp, fsync, then os.replace into place.
+
+    Mirrors skf-atomic-write.py's `write` so the marker-surgery actions deliver
+    the crash-safety the step file documents: a mid-write process kill leaves
+    the original file intact rather than truncated. Cleans up the temp file on
+    failure. Raises OSError on any I/O failure.
+    """
+    path = Path(file_path)
+    tmp = path.with_name(path.name + ".skf-tmp")
+    # O_BINARY (Windows only; 0 elsewhere) suppresses the text-mode \n -> \r\n
+    # translation that would otherwise diverge the on-disk bytes from the staged
+    # string and trip the byte-identity verify below.
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_BINARY", 0)
+    try:
+        fd = os.open(tmp, flags, 0o644)
+        try:
+            os.write(fd, text.encode("utf-8"))
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        os.replace(tmp, path)
+    except OSError:
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except OSError:
+                pass
+        raise
+
+
+def _write_and_verify(file_path, updated, *, expect_section):
+    """Atomically write `updated`, then re-read to confirm integrity.
+
+    Returns None on success or an error string. The re-read asserts the on-disk
+    bytes match what was staged (so content outside the markers is byte-identical)
+    and that managed-section marker presence matches `expect_section`.
+    """
+    try:
+        _atomic_write(file_path, updated)
+    except OSError as e:
+        return f"atomic write failed: {e}"
+
+    # Re-read raw bytes (no newline translation) for a true byte-identity check.
+    try:
+        on_disk = Path(file_path).read_bytes()
+    except OSError as e:
+        return f"post-write verification failed: {e}"
+    if on_disk != updated.encode("utf-8"):
+        return "post-write verification failed: on-disk bytes do not match staged content"
+    if (find_managed_section(on_disk.decode("utf-8")) is not None) != expect_section:
+        return (
+            "post-write verification failed: managed section "
+            + ("missing after write" if expect_section else "still present after clear")
+        )
+    return None
+
+
 def cmd_check(file_path):
     """Check if managed section exists."""
     content, err = read_context_file(file_path)
@@ -112,7 +171,9 @@ def cmd_replace(file_path, new_content):
     new_section = f"<!-- SKF:BEGIN updated:{today} -->\n{new_content}\n{END_MARKER}"
     updated = content[: match.start()] + new_section + content[match.end() :]
 
-    Path(file_path).write_text(updated, encoding="utf-8")
+    verify_err = _write_and_verify(file_path, updated, expect_section=True)
+    if verify_err:
+        return {"status": "error", "error": verify_err}
     return {"status": "ok", "action": "replaced", "bytes_written": len(updated)}
 
 
@@ -131,7 +192,9 @@ def cmd_clear(file_path):
     after = content[match.end() :].lstrip("\n")
     updated = before + ("\n\n" if before and after else "") + after
 
-    Path(file_path).write_text(updated, encoding="utf-8")
+    verify_err = _write_and_verify(file_path, updated, expect_section=False)
+    if verify_err:
+        return {"status": "error", "error": verify_err}
     return {"status": "ok", "action": "cleared", "bytes_written": len(updated)}
 
 
@@ -153,7 +216,9 @@ def cmd_insert(file_path, new_content):
     section = f"\n<!-- SKF:BEGIN updated:{today} -->\n{new_content}\n{END_MARKER}\n"
     updated = content.rstrip("\n") + "\n" + section if content.strip() else section.lstrip("\n")
 
-    Path(file_path).write_text(updated, encoding="utf-8")
+    verify_err = _write_and_verify(file_path, updated, expect_section=True)
+    if verify_err:
+        return {"status": "error", "error": verify_err}
     return {"status": "ok", "action": "inserted", "bytes_written": len(updated)}
 
 
@@ -179,15 +244,15 @@ def main():
     elif action == "read":
         result = cmd_read(file_path)
     elif action == "replace":
-        if content_arg is None:
-            result = {"status": "error", "error": "replace requires --content or stdin"}
+        if content_arg is None or not content_arg.strip():
+            result = {"status": "error", "error": "replace requires non-empty --content or stdin"}
         else:
             result = cmd_replace(file_path, content_arg)
     elif action == "clear":
         result = cmd_clear(file_path)
     elif action == "insert":
-        if content_arg is None:
-            result = {"status": "error", "error": "insert requires --content or stdin"}
+        if content_arg is None or not content_arg.strip():
+            result = {"status": "error", "error": "insert requires non-empty --content or stdin"}
         else:
             result = cmd_insert(file_path, content_arg)
     else:

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,30 @@ 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
+  uv run skf-validate-frontmatter.py <skill-md-path> --max-body-lines 500 --max-body-tokens 5000
 
 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.
+  Optional --max-body-tokens N: when set, emit a high-severity `body`
+  issue if the estimated body token count exceeds N. Token count is
+  estimated as ceil(character_count / 4). Callers pass the skill-check
+  `body.max_tokens` default (5000) to pre-catch that soft/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 +135,53 @@ 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 body_token_estimate(content: str) -> int | None:
+    """Estimate the SKILL.md body token count as ceil(char_count / 4).
+
+    Returns None when the frontmatter delimiters are absent or unclosed
+    (same boundary condition as body_line_count). The heuristic matches
+    the agentskills.io spec's token estimation convention.
+    """
+    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
+    body = "\n".join(lines[closing + 1:])
+    char_count = len(body)
+    return -(-char_count // 4)  # ceil division
+
+
 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 +247,36 @@ 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,
+    max_body_tokens: 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. When `max_body_tokens` is
+    set, emit a high-severity `body` issue if the estimated token count
+    exceeds that limit. Both are opt-in — the verdict is unchanged when
+    they are None. Returns a result dict with status, issues, frontmatter,
+    body_lines, body_tokens, 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}",
+        })
+
+    body_tokens = body_token_estimate(content)
+    if max_body_tokens is not None and body_tokens is not None and body_tokens > max_body_tokens:
+        issues.append({
+            "severity": "high",
+            "field": "body",
+            "message": f"body token estimate {body_tokens} exceeds max {max_body_tokens}",
+        })
+
     if fm is not None:
         # Name validation
         name = fm.get("name", "")
@@ -255,6 +338,8 @@ def validate_frontmatter(
         "status": status,
         "issues": issues,
         "frontmatter": fm,
+        "body_lines": body_lines,
+        "body_tokens": body_tokens,
         "summary": {
             "total": len(issues),
             **severity_counts,
@@ -288,6 +373,29 @@ 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(
+        "--max-body-tokens",
+        metavar="N",
+        type=int,
+        default=None,
+        help=(
+            "when set, emit a high-severity 'body' issue if the estimated body "
+            "token count exceeds N (opt-in; omitted = body tokens not checked). "
+            "Token estimate uses ceil(char_count / 4). Pass the skill-check "
+            "body.max_tokens default (5000) to pre-catch that reject."
+        ),
+    )
     parser.add_argument(
         "-o", "--output",
         metavar="FILE",
@@ -302,12 +410,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, args.max_body_tokens)
 
     output_text = json.dumps(result, indent=2)