bmad-module-skill-forge 1.4.1 → 1.5.0

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

@@ -0,0 +1,375 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Scan Skill.md Structure — deterministic structural checks for SKILL.md.
+
+Replaces the synonym-grep loops, bash fence recipes, and inline Python
+table-parser in `references/coherence-check.md` §§2.1 / 2.2 / 2.3 / 2.6 with
+a single subprocess invocation that emits JSON.
+
+Subcommands:
+  scan <skill-md>
+      Emit JSON describing fence balance, bare opening fences (no language
+      tag), and table column-count drift:
+        {
+          "unbalanced_fences": <bool>,
+          "fence_count": N,
+          "bare_opening_fences": [{"line": N, "text": "..."}, ...],
+          "table_drift": [{"line": N, "section": "<heading>",
+                           "expected_cols": N, "actual_cols": N,
+                           "row": "..."}]
+        }
+
+  scan <skill-md> --required-sections
+      Emit JSON describing which of the three required section families
+      (description / usage / api_surface) are present, and which synonym
+      satisfied the requirement (case-insensitive, `##`/`###` tolerated):
+        {
+          "description":  {"satisfied": <bool>,
+                           "matched_synonym": "<heading>" | null,
+                           "tried": ["Description", "Overview", ...]},
+          "usage":        {"satisfied": <bool>,
+                           "matched_synonym": "..." | null,
+                           "tried": [...]},
+          "api_surface":  {"satisfied": <bool>,
+                           "matched_synonym": "..." | null,
+                           "tried": [...]}
+        }
+
+Heading match rule:
+  Match the first `^#+\\s+<heading>$` (any number of `#`, case-insensitive,
+  surrounding whitespace trimmed) that matches any synonym in a family.
+  The reported `matched_synonym` is the canonical synonym from the list,
+  not the heading text as it appears in the file.
+
+Fence balance:
+  Count triple-backtick (```) fence lines (`^```` at start of line, ignoring
+  leading whitespace). `unbalanced_fences=true` iff the count is odd.
+
+Bare opening fence:
+  A stateful open/close scan toggles `in_code` on each fence line. A bare
+  opening fence is one where `in_code` transitions 0→1 and the line, with
+  the leading ``` stripped, has no language tag (empty or whitespace-only
+  remainder). Closing fences are never flagged — they are bare by markdown
+  convention. This mirrors the Python recipe in coherence-check.md §2.3.
+
+Table drift:
+  Walks markdown table blocks. A block starts when a `^\\|.*\\|$` line is
+  found; subsequent contiguous `^\\|.*\\|$` lines are part of the same
+  block. The first row is the header. The second row, if it matches the
+  separator pattern (cells made of `-`, `:`, and whitespace), is ignored
+  in the drift count. For every other row, normalize escaped pipes (`\\|`)
+  to a sentinel before splitting on `|`, then drop the empty leading and
+  trailing fields produced by the bracketing pipes; flag rows whose column
+  count differs from the header's. Each flag includes the line number,
+  the most-recently-seen `^#+\\s+` heading, expected/actual column counts,
+  and the raw row text.
+
+  Escaped pipes appear inside TypeScript union types (e.g.
+  `string \\| undefined`). Normalizing prevents one false drift finding
+  per union-typed cell.
+
+Empty SKILL.md:
+  An empty file yields `fence_count: 0`, `unbalanced_fences: false`,
+  empty `bare_opening_fences`, empty `table_drift`; for
+  `--required-sections`, all three families have `satisfied: false`,
+  `matched_synonym: null`.
+
+Exit codes:
+  0 — operation succeeded
+  1 — user error (file not found, can't read)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+# --------------------------------------------------------------------------
+# Required-section synonym constants
+# --------------------------------------------------------------------------
+
+
+# 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).
+REQUIRED_SYNONYMS: dict[str, list[str]] = {
+    "description": ["Description", "Overview", "Purpose", "Summary"],
+    "usage": [
+        "Usage",
+        "Examples",
+        "How to use",
+        "Quickstart",
+        "Quick Start",
+        "Getting Started",
+        "Common Workflows",
+    ],
+    "api_surface": [
+        "API",
+        "API Surface",
+        "Exports",
+        "Public API",
+        "Interface",
+        "Reference",
+        "Key API Summary",
+    ],
+}
+
+
+# --------------------------------------------------------------------------
+# Required-section presence
+# --------------------------------------------------------------------------
+
+
+_HEADING_RE = re.compile(r"^\s*(#+)\s+(.*?)\s*$")
+
+
+def find_required_sections(text: str) -> dict[str, dict]:
+    """For each family, find the first matching heading.
+
+    Walks every line once, lower-cases the heading text, and looks it up
+    against pre-lowered synonym sets. Returns the structure described in
+    the module docstring.
+    """
+    # Build a lookup: lowered-heading → (family, canonical_synonym)
+    # Multiple families can never share a synonym, so a flat dict is fine.
+    lookup: dict[str, tuple[str, str]] = {}
+    for family, synonyms in REQUIRED_SYNONYMS.items():
+        for syn in synonyms:
+            lookup[syn.lower()] = (family, syn)
+
+    matched: dict[str, str] = {}
+    for line in text.splitlines():
+        m = _HEADING_RE.match(line)
+        if not m:
+            continue
+        heading_text = m.group(2).strip().lower()
+        hit = lookup.get(heading_text)
+        if hit is None:
+            continue
+        family, canonical = hit
+        if family in matched:
+            # first match wins
+            continue
+        matched[family] = canonical
+
+    result: dict[str, dict] = {}
+    for family, synonyms in REQUIRED_SYNONYMS.items():
+        if family in matched:
+            result[family] = {
+                "satisfied": True,
+                "matched_synonym": matched[family],
+                "tried": list(synonyms),
+            }
+        else:
+            result[family] = {
+                "satisfied": False,
+                "matched_synonym": None,
+                "tried": list(synonyms),
+            }
+    return result
+
+
+# --------------------------------------------------------------------------
+# Fence balance + bare opening fences
+# --------------------------------------------------------------------------
+
+
+def scan_fences(text: str) -> tuple[int, bool, list[dict]]:
+    """Count fences, decide balance, collect bare opening fences.
+
+    Uses a stateful toggle so closing fences are never flagged.
+    Returns (fence_count, unbalanced, bare_opening_fences[]).
+    """
+    fence_count = 0
+    bare: list[dict] = []
+    in_code = False
+    for lineno, raw in enumerate(text.splitlines(), start=1):
+        # match lines that start with ``` (allow leading whitespace,
+        # which markdown tolerates in some renderers)
+        stripped = raw.lstrip()
+        if not stripped.startswith("```"):
+            continue
+        fence_count += 1
+        # the part of the fence line after the opening ```
+        tail = stripped[3:].strip()
+        if not in_code:
+            # opening fence: a bare opening fence has empty tail
+            if tail == "":
+                bare.append({"line": lineno, "text": raw})
+            in_code = True
+        else:
+            # closing fence — never flagged
+            in_code = False
+    return fence_count, (fence_count % 2 == 1), bare
+
+
+# --------------------------------------------------------------------------
+# Table column drift
+# --------------------------------------------------------------------------
+
+
+_TABLE_ROW_RE = re.compile(r"^\s*\|.*\|\s*$")
+_TABLE_SEP_CELL_RE = re.compile(r"^\s*:?-+:?\s*$")
+_PIPE_SENTINEL = "\x00"
+
+
+def _split_row_cells(row_text: str) -> list[str]:
+    """Split a markdown table row into cells.
+
+    Normalizes escaped pipes to a sentinel before splitting, then drops
+    the empty leading/trailing fields produced by the bracketing pipes.
+    """
+    normalized = row_text.strip().replace("\\|", _PIPE_SENTINEL)
+    parts = normalized.split("|")
+    # parts looks like ["", "cell1", "cell2", ..., ""] for `|a|b|`;
+    # drop bracketing empties.
+    if parts and parts[0].strip() == "":
+        parts = parts[1:]
+    if parts and parts[-1].strip() == "":
+        parts = parts[:-1]
+    return [p.replace(_PIPE_SENTINEL, "|") for p in parts]
+
+
+def _is_separator_row(cells: list[str]) -> bool:
+    """True if every cell looks like a table separator (`---`, `:---:`, etc.)."""
+    if not cells:
+        return False
+    return all(_TABLE_SEP_CELL_RE.match(c) is not None for c in cells)
+
+
+def find_table_drift(text: str) -> list[dict]:
+    """Walk table blocks, flag rows whose column count differs from the header.
+
+    Tracks the most-recently-seen heading text so each finding can name the
+    section it's in. The heading text reported is the raw text after the `#`
+    characters, with surrounding whitespace stripped.
+    """
+    findings: list[dict] = []
+    lines = text.splitlines()
+    current_section = ""
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        heading = _HEADING_RE.match(line)
+        if heading is not None:
+            current_section = heading.group(2).strip()
+            i += 1
+            continue
+        if not _TABLE_ROW_RE.match(line):
+            i += 1
+            continue
+
+        # Start of a table block. Collect contiguous rows.
+        block_start = i
+        block_rows: list[tuple[int, str]] = []
+        while i < len(lines) and _TABLE_ROW_RE.match(lines[i]):
+            block_rows.append((i + 1, lines[i]))  # 1-based line numbers
+            i += 1
+
+        if not block_rows:
+            continue
+
+        header_lineno, header_text = block_rows[0]
+        header_cells = _split_row_cells(header_text)
+        expected = len(header_cells)
+
+        # If the second row is a separator, skip it from drift checking.
+        body_rows = block_rows[1:]
+        if body_rows:
+            _, second_text = body_rows[0]
+            if _is_separator_row(_split_row_cells(second_text)):
+                body_rows = body_rows[1:]
+
+        for row_lineno, row_text in body_rows:
+            cells = _split_row_cells(row_text)
+            actual = len(cells)
+            if actual != expected:
+                findings.append({
+                    "line": row_lineno,
+                    "section": current_section,
+                    "expected_cols": expected,
+                    "actual_cols": actual,
+                    "row": row_text,
+                })
+
+        # if the block ended at a non-row line, fall through to advance i;
+        # i already points past the block.
+        _ = block_start  # explicitly unused, kept for readability
+    return findings
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+
+def _read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def _cmd_scan(args: argparse.Namespace) -> int:
+    skill_md = Path(args.skill_md)
+    if not skill_md.is_file():
+        print(f"error: file not found: {skill_md}", file=sys.stderr)
+        return 1
+    try:
+        text = _read_text(skill_md)
+    except OSError as exc:
+        print(f"error: cannot read {skill_md}: {exc}", file=sys.stderr)
+        return 1
+
+    if args.required_sections:
+        payload = find_required_sections(text)
+    else:
+        fence_count, unbalanced, bare = scan_fences(text)
+        payload = {
+            "unbalanced_fences": unbalanced,
+            "fence_count": fence_count,
+            "bare_opening_fences": bare,
+            "table_drift": find_table_drift(text),
+        }
+
+    json.dump(payload, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skf-scan-skill-md-structure",
+        description=(
+            "Deterministic structural scans for SKILL.md: fence balance, "
+            "bare opening fences, table column drift, and required-section "
+            "presence (case-insensitive synonym match)."
+        ),
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_scan = sub.add_parser("scan", help="emit structural scan JSON")
+    p_scan.add_argument("skill_md", help="path to a SKILL.md file")
+    p_scan.add_argument(
+        "--required-sections",
+        action="store_true",
+        help="emit required-section presence JSON instead of fence/table data",
+    )
+    p_scan.set_defaults(func=_cmd_scan)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/shared/scripts/skf-update-active-symlink.py

@@ -0,0 +1,315 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Update Active Symlink — atomic + idempotent + verified flip of
+{skill_group}/active to point at a target version directory.
+
+`skf-update-skill/references/write.md §5b` previously asked the LLM to
+"create or update the active symlink at {skill_group}/active pointing
+to the new {version}; if the symlink already exists, remove it first
+and recreate". That two-step (`rm` then `ln`) leaves a brief window
+where the symlink doesn't exist — readers that resolve `active`
+mid-update see a `FileNotFoundError`. §6 then re-reads the symlink
+to verify it points where expected and halts on divergence.
+
+This helper consolidates the two steps into one workflow-specific
+invocation:
+
+  - detects whether a flip is required (idempotent: already pointing
+    at the target → no-op)
+  - performs the flip atomically (symlink → temp name → os.replace)
+    so concurrent readers never see a missing symlink
+  - verifies the post-state and surfaces ok / flipped / mismatch
+    / missing-target
+
+Two subcommands:
+
+  update --skill-group <path> --version <name>
+      Make {skill-group}/active point at {version}. Atomic.
+      Idempotent: returns status=ok with action=no-op when the link
+      already points there.
+
+  verify --skill-group <path> --version <name>
+      Read-only: check that {skill-group}/active currently points at
+      {version}. Used by step-06 derived-artifact verification.
+
+The target version directory (`{skill-group}/{version}/`) MUST exist
+on disk before this script is called. The helper refuses to point
+the symlink at a path that doesn't resolve — a dangling `active`
+silently breaks downstream consumers that expect it to resolve.
+
+Output JSON (stdout):
+  {
+    "status": "ok" | "flipped" | "mismatch" | "missing-target",
+    "skill_group": "<abs path>",
+    "active_link": "<abs path to active>",
+    "expected_target": "<version>",
+    "current_target": "<previous target>" | null,
+    "action_taken": "no-op" | "flipped" | "halt",
+    "log_message": "...",
+    "halt_message": "<multi-line user message>" | null
+  }
+
+Exit codes:
+  0  — ok (already correct) or flipped (just updated)
+  1  — script error (bad args, group path invalid)
+  2  — mismatch (verify mode and target diverges) OR missing-target
+       (the {version} directory doesn't exist; caller must halt)
+
+Platform: POSIX symlinks. On Windows this script intentionally
+exits 1 with a clear error — update-skill's documented supported
+platform is WSL2 (same as skf-atomic-write.py's flip-link).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+ACTIVE_NAME = "active"
+
+
+# --------------------------------------------------------------------------
+# Symlink primitives
+# --------------------------------------------------------------------------
+
+
+def read_link_target(link_path: Path) -> str | None:
+    """Return the symlink target as a relative string, or None if the link
+    doesn't exist. Raises ValueError if `link_path` exists but isn't a symlink
+    (someone replaced it with a regular dir/file)."""
+    if not link_path.exists() and not link_path.is_symlink():
+        return None
+    if not link_path.is_symlink():
+        raise ValueError(
+            f"{link_path} exists but is not a symlink — refusing to overwrite "
+            "(manual recovery required)"
+        )
+    return os.readlink(link_path)
+
+
+def atomic_flip_symlink(link_path: Path, target_name: str) -> None:
+    """Atomically point `link_path` at `target_name` using the
+    create-temp + rename pattern. `target_name` is a relative path
+    interpreted in the parent of `link_path` (same convention as
+    {skill_group}/active → version-dir-sibling).
+
+    Implementation: os.symlink writes a new link at link_path.tmp,
+    then os.replace atomically renames it over link_path. POSIX
+    rename is atomic for symlinks, so concurrent readers either see
+    the old target or the new one, never a missing file.
+    """
+    parent = link_path.parent
+    tmp = parent / f".{link_path.name}.skf-symlink.tmp"
+    # Clean up a stale temp from a prior crash, if any.
+    if tmp.is_symlink() or tmp.exists():
+        os.unlink(tmp)
+    try:
+        os.symlink(target_name, tmp)
+        os.replace(tmp, link_path)
+    except OSError:
+        # Best-effort cleanup; raise the original error.
+        try:
+            if tmp.is_symlink() or tmp.exists():
+                os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+# --------------------------------------------------------------------------
+# Core operations
+# --------------------------------------------------------------------------
+
+
+def _envelope_missing_target(skill_group: Path, version: str) -> dict:
+    return {
+        "status": "missing-target",
+        "skill_group": str(skill_group),
+        "active_link": str(skill_group / ACTIVE_NAME),
+        "expected_target": version,
+        "current_target": None,
+        "action_taken": "halt",
+        "log_message": (
+            f"active_symlink_update: missing-target "
+            f"({skill_group / version} does not exist)"
+        ),
+        "halt_message": (
+            f"Cannot point {skill_group / ACTIVE_NAME} at `{version}` — "
+            f"target directory `{skill_group / version}` does not exist on "
+            "disk. Verify the version directory was written before §5b runs."
+        ),
+    }
+
+
+def _envelope_ok(skill_group: Path, version: str, current: str | None) -> dict:
+    return {
+        "status": "ok",
+        "skill_group": str(skill_group),
+        "active_link": str(skill_group / ACTIVE_NAME),
+        "expected_target": version,
+        "current_target": current,
+        "action_taken": "no-op",
+        "log_message": f"active_symlink_update: ok ({version})",
+        "halt_message": None,
+    }
+
+
+def _envelope_flipped(skill_group: Path, version: str, previous: str | None) -> dict:
+    prev = previous if previous is not None else "(none)"
+    return {
+        "status": "flipped",
+        "skill_group": str(skill_group),
+        "active_link": str(skill_group / ACTIVE_NAME),
+        "expected_target": version,
+        "current_target": version,
+        "action_taken": "flipped",
+        "log_message": f"active_symlink_update: flipped ({prev} -> {version})",
+        "halt_message": None,
+    }
+
+
+def _envelope_mismatch(skill_group: Path, version: str, current: str | None) -> dict:
+    cur = current if current is not None else "(none)"
+    return {
+        "status": "mismatch",
+        "skill_group": str(skill_group),
+        "active_link": str(skill_group / ACTIVE_NAME),
+        "expected_target": version,
+        "current_target": current,
+        "action_taken": "halt",
+        "log_message": (
+            f"active_symlink_update: mismatch "
+            f"(expected={version}, current={cur})"
+        ),
+        "halt_message": (
+            f"Active symlink divergence. `{skill_group / ACTIVE_NAME}` "
+            f"resolves to `{cur}` but metadata.json reports `version: "
+            f"{version}`. §5b did not apply. Re-point the symlink manually "
+            f"(`ln -sfn {version} {skill_group / ACTIVE_NAME}`) or re-run "
+            "update-skill, then re-verify."
+        ),
+    }
+
+
+def update(skill_group: Path, version: str) -> dict:
+    """Idempotently flip {skill_group}/active to point at {version}."""
+    target_dir = skill_group / version
+    if not target_dir.is_dir():
+        return _envelope_missing_target(skill_group, version)
+
+    link_path = skill_group / ACTIVE_NAME
+    current = read_link_target(link_path)
+    if current == version:
+        return _envelope_ok(skill_group, version, current)
+
+    atomic_flip_symlink(link_path, version)
+
+    # Re-read to confirm
+    post = read_link_target(link_path)
+    if post != version:
+        # Should be impossible — os.replace would have raised — but defend
+        return _envelope_mismatch(skill_group, version, post)
+    return _envelope_flipped(skill_group, version, current)
+
+
+def verify(skill_group: Path, version: str) -> dict:
+    """Read-only check: assert active points at version."""
+    link_path = skill_group / ACTIVE_NAME
+    current = read_link_target(link_path)
+    if current == version:
+        return _envelope_ok(skill_group, version, current)
+    return _envelope_mismatch(skill_group, version, current)
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+
+def _exit_code_for_status(status: str) -> int:
+    if status in ("ok", "flipped"):
+        return 0
+    if status in ("mismatch", "missing-target"):
+        return 2
+    return 1
+
+
+def _cmd_update(args: argparse.Namespace) -> int:
+    skill_group = Path(args.skill_group)
+    if not skill_group.is_dir():
+        print(
+            f"error: skill-group not a directory: {skill_group}", file=sys.stderr
+        )
+        return 1
+    try:
+        result = update(skill_group, args.version)
+    except (ValueError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return _exit_code_for_status(result["status"])
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    skill_group = Path(args.skill_group)
+    if not skill_group.is_dir():
+        print(
+            f"error: skill-group not a directory: {skill_group}", file=sys.stderr
+        )
+        return 1
+    try:
+        result = verify(skill_group, args.version)
+    except (ValueError, OSError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return _exit_code_for_status(result["status"])
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skf-update-active-symlink",
+        description=(
+            "Atomically + idempotently update {skill-group}/active to point "
+            "at a target version directory."
+        ),
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_upd = sub.add_parser("update", help="flip the symlink if needed")
+    p_upd.add_argument("--skill-group", required=True, help="path to the skill_group dir")
+    p_upd.add_argument("--version", required=True, help="version directory name")
+    p_upd.set_defaults(func=_cmd_update)
+
+    p_ver = sub.add_parser("verify", help="read-only: assert symlink matches version")
+    p_ver.add_argument("--skill-group", required=True)
+    p_ver.add_argument("--version", required=True)
+    p_ver.set_defaults(func=_cmd_verify)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    if sys.platform.startswith("win"):
+        print(
+            "error: native Windows symlinks require admin/developer mode; "
+            "use WSL2 to run update-skill (same constraint as "
+            "skf-atomic-write.py flip-link)",
+            file=sys.stderr,
+        )
+        return 1
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())