hive-skills 0.1.0

package/assets/tools/hive.py

@@ -0,0 +1,728 @@
+#!/usr/bin/env python3
+"""hive.py: CCS (Compiled Composable Skills) framework CLI for Hive.
+
+Tooling for the composable skill layout used under any <skill-root>/composable/
+directory. A skills root MAY organize skills into category subdirectories
+(e.g. skills/authored/<name>/, skills/converted/<name>/) or lay them out flat
+(skills/<name>/); discovery (`report`) recurses to find every composable/ dir
+at any depth:
+
+    skills/<name>/composable/
+        INDEX.md              # loading menu: which mini to load when
+        presets.json          # optional: {"preset-name": ["01", "04", ...]}
+        VERSION                # optional: single semver line, skill-level version
+        mini/
+            00-core.md         # optional, always-loaded foundation
+            01-....md
+            ...
+        BUNDLE.md              # compiled: all minis concatenated, generated
+        presets/<name>.md      # compiled: a named subset, generated
+
+Minis may start with a YAML-ish frontmatter block:
+
+    ---
+    pairs-with:
+      - 09-refactoring-and-communication.md
+    version: 1.0.0
+    ---
+
+Known frontmatter keys: model-hint, effort-hint, requires, pairs-with, version.
+
+Subcommands: compile, lint, parity, report, bump. See --help on each.
+
+Python 3.11, stdlib only.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+KNOWN_FRONTMATTER_KEYS = {"model-hint", "effort-hint", "requires", "pairs-with", "version"}
+LIST_KEYS = {"requires", "pairs-with"}
+PATH_LIKE_RE = re.compile(r"^[A-Za-z0-9_.\-]+(?:/[A-Za-z0-9_.\-]+)*\.md$")
+H1_RE = re.compile(r"^#\s+\S")
+H2_H3_RE = re.compile(r"^(#{2,3})\s+(.*)$")
+SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+$")
+STOPWORDS = {
+    "the", "and", "for", "with", "from", "into", "your", "this", "that",
+    "when", "what", "how", "are", "was", "were", "have", "has", "not",
+    "over", "under", "about", "per", "via", "vs", "step", "steps",
+}
+
+GENERATED_MARKER = "<!-- GENERATED by tools/hive.py compile. Do not hand-edit. -->"
+
+
+# --------------------------------------------------------------------------
+# Core parsing helpers
+# --------------------------------------------------------------------------
+
+def toks(text: str) -> float:
+    """Token estimate: chars / 4."""
+    return len(text) / 4.0
+
+
+def fmt_toks(n: float) -> str:
+    return str(round(n))
+
+
+@dataclass
+class FrontmatterResult:
+    data: dict | None  # None => no frontmatter block present
+    body: str
+    errors: list[str] = field(default_factory=list)
+
+
+def split_frontmatter(text: str) -> FrontmatterResult:
+    """Parse an optional leading YAML-ish frontmatter block.
+
+    Only supports the shapes actually used in this repo: top-level
+    ``key: value`` scalars and ``key:`` followed by ``  - item`` list
+    entries (also tolerates an inline ``[a, b]`` list).
+    """
+    if not text.startswith("---"):
+        return FrontmatterResult(None, text, [])
+
+    lines = text.split("\n")
+    if lines[0].strip() != "---":
+        return FrontmatterResult(None, text, [])
+
+    end_idx = None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        return FrontmatterResult(None, text, ["unterminated frontmatter block (no closing '---')"])
+
+    fm_lines = lines[1:end_idx]
+    body = "\n".join(lines[end_idx + 1:])
+
+    data: dict[str, object] = {}
+    errors: list[str] = []
+    i = 0
+    while i < len(fm_lines):
+        line = fm_lines[i]
+        if not line.strip():
+            i += 1
+            continue
+        if line[0].isspace():
+            errors.append(f"unexpected indented line outside a list: {line!r}")
+            i += 1
+            continue
+        m = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", line)
+        if not m:
+            errors.append(f"unparsable frontmatter line: {line!r}")
+            i += 1
+            continue
+        key, rest = m.group(1), m.group(2).strip()
+        if rest:
+            if rest.startswith("[") and rest.endswith("]"):
+                items = [x.strip() for x in rest[1:-1].split(",") if x.strip()]
+                data[key] = items
+            else:
+                data[key] = rest
+            i += 1
+        else:
+            items = []
+            j = i + 1
+            while j < len(fm_lines) and re.match(r"^\s*-\s+\S", fm_lines[j]):
+                items.append(re.sub(r"^\s*-\s+", "", fm_lines[j]).strip())
+                j += 1
+            data[key] = items
+            i = j
+
+    return FrontmatterResult(data, body, errors)
+
+
+def strip_frontmatter_body(text: str) -> str:
+    """Return the mini's body with any frontmatter block removed and
+    surrounding blank lines normalized to a single trailing newline."""
+    return split_frontmatter(text).body.strip("\n") + "\n"
+
+
+# --------------------------------------------------------------------------
+# Skill directory resolution
+# --------------------------------------------------------------------------
+
+def resolve_composable_dir(path: Path) -> Path:
+    """Accept either a skill root (containing composable/) or the
+    composable/ dir itself."""
+    if (path / "composable").is_dir():
+        return path / "composable"
+    return path
+
+
+def skill_name_for(composable_dir: Path) -> str:
+    # composable_dir is .../<name>/composable
+    return composable_dir.parent.name
+
+
+def mini_files(composable_dir: Path) -> list[Path]:
+    mdir = composable_dir / "mini"
+    if not mdir.is_dir():
+        return []
+    return sorted(mdir.glob("*.md"), key=lambda p: p.name)
+
+
+# --------------------------------------------------------------------------
+# Versioning
+# --------------------------------------------------------------------------
+
+def is_semver(value: str) -> bool:
+    return bool(SEMVER_RE.match(value.strip()))
+
+
+def version_path(composable_dir: Path) -> Path:
+    return composable_dir / "VERSION"
+
+
+def read_skill_version(composable_dir: Path) -> str | None:
+    """Return the raw (unvalidated) skill-level VERSION contents, stripped,
+    or None if the file doesn't exist."""
+    vpath = version_path(composable_dir)
+    if not vpath.is_file():
+        return None
+    text = vpath.read_text(encoding="utf-8").strip()
+    return text or None
+
+
+def bump_semver(version: str, part: str) -> str:
+    major, minor, patch = (int(x) for x in version.split("."))
+    if part == "major":
+        major, minor, patch = major + 1, 0, 0
+    elif part == "minor":
+        minor, patch = minor + 1, 0
+    elif part == "patch":
+        patch += 1
+    else:
+        raise ValueError(f"unknown version part: {part!r}")
+    return f"{major}.{minor}.{patch}"
+
+
+# --------------------------------------------------------------------------
+# compile
+# --------------------------------------------------------------------------
+
+def build_bundle_text(
+    skill_name: str,
+    minis: list[Path],
+    title_suffix: str = "",
+    skill_version: str | None = None,
+) -> str:
+    version_suffix = f" (v{skill_version})" if skill_version else ""
+    header = (
+        f"{GENERATED_MARKER}\n"
+        f"# {skill_name}: Compiled Skill Bundle{title_suffix}{version_suffix}\n\n"
+        f"All composable mini-skills for `{skill_name}` concatenated in index "
+        f"order, frontmatter stripped. Regenerate with "
+        f"`tools/hive.py compile <skill-dir>`. Do not edit by hand.\n"
+    )
+    parts = [header]
+    for mini in minis:
+        body = strip_frontmatter_body(mini.read_text(encoding="utf-8"))
+        parts.append(f"\n---\n<!-- module: {mini.name} -->\n\n{body}")
+    full = "".join(parts)
+    return full.rstrip("\n") + "\n"
+
+
+def resolve_preset_ids(minis: list[Path], ids: list[str]) -> tuple[list[Path], list[str]]:
+    """Map preset id tokens (e.g. '01', '01-review-method', '01-review-method.md')
+    to mini file paths, preserving the given order. Returns (paths, unmatched)."""
+    by_full = {p.name: p for p in minis}
+    by_stem = {p.stem: p for p in minis}
+    by_prefix: dict[str, Path] = {}
+    for p in minis:
+        prefix = p.stem.split("-", 1)[0]
+        by_prefix.setdefault(prefix, p)
+
+    resolved: list[Path] = []
+    unmatched: list[str] = []
+    for token in ids:
+        token = token.strip()
+        if not token:
+            continue
+        match = by_full.get(token) or by_stem.get(token) or by_prefix.get(token)
+        if match is None:
+            unmatched.append(token)
+        else:
+            resolved.append(match)
+    return resolved, unmatched
+
+
+def load_presets_json(composable_dir: Path) -> dict[str, list[str]]:
+    pj = composable_dir / "presets.json"
+    if not pj.is_file():
+        return {}
+    try:
+        data = json.loads(pj.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        print(f"[WARN] presets.json is not valid JSON: {e}", file=sys.stderr)
+        return {}
+    if not isinstance(data, dict):
+        print("[WARN] presets.json must be a JSON object of name -> [ids]", file=sys.stderr)
+        return {}
+    return {str(k): [str(x) for x in v] for k, v in data.items()}
+
+
+def cmd_compile(args: argparse.Namespace) -> int:
+    composable_dir = resolve_composable_dir(Path(args.skill_dir))
+    if not composable_dir.is_dir():
+        print(f"error: composable dir not found: {composable_dir}", file=sys.stderr)
+        return 1
+    skill_name = skill_name_for(composable_dir)
+    minis = mini_files(composable_dir)
+    if not minis:
+        print(f"error: no mini/*.md files found under {composable_dir}", file=sys.stderr)
+        return 1
+
+    skill_version = read_skill_version(composable_dir)
+
+    bundle_text = build_bundle_text(skill_name, minis, skill_version=skill_version)
+    bundle_path = composable_dir / "BUNDLE.md"
+    bundle_path.write_text(bundle_text, encoding="utf-8")
+    print(f"wrote {bundle_path} ({fmt_toks(toks(bundle_text))} tokens, {len(minis)} minis)")
+
+    # Presets: merge CLI-provided with presets.json (CLI wins on name clash).
+    preset_specs: dict[str, list[str]] = load_presets_json(composable_dir)
+    for spec in args.presets or []:
+        if "=" not in spec:
+            print(f"error: --presets entry must be name=ids, got {spec!r}", file=sys.stderr)
+            return 1
+        name, ids_csv = spec.split("=", 1)
+        preset_specs[name.strip()] = [x.strip() for x in ids_csv.split(",") if x.strip()]
+
+    if preset_specs:
+        presets_dir = composable_dir / "presets"
+        presets_dir.mkdir(exist_ok=True)
+        for name, ids in preset_specs.items():
+            resolved, unmatched = resolve_preset_ids(minis, ids)
+            if unmatched:
+                print(f"error: preset {name!r} references unknown minis: {unmatched}", file=sys.stderr)
+                return 1
+            preset_text = build_bundle_text(
+                skill_name, resolved, title_suffix=f" (preset: {name})", skill_version=skill_version,
+            )
+            preset_path = presets_dir / f"{name}.md"
+            preset_path.write_text(preset_text, encoding="utf-8")
+            print(f"wrote {preset_path} ({fmt_toks(toks(preset_text))} tokens, {len(resolved)} minis)")
+
+    return 0
+
+
+# --------------------------------------------------------------------------
+# lint
+# --------------------------------------------------------------------------
+
+class Reporter:
+    def __init__(self) -> None:
+        self.lines: list[str] = []
+        self.counts = {"PASS": 0, "WARN": 0, "FAIL": 0}
+
+    def line(self, status: str, msg: str) -> None:
+        self.counts[status] += 1
+        self.lines.append(f"[{status}] {msg}")
+
+    def has_fail(self) -> bool:
+        return self.counts["FAIL"] > 0
+
+    def summary(self) -> str:
+        return f"{self.counts['PASS']} pass, {self.counts['WARN']} warn, {self.counts['FAIL']} fail"
+
+
+def lint_skill(composable_dir: Path, r: Reporter) -> None:
+    skill_name = skill_name_for(composable_dir)
+    minis = mini_files(composable_dir)
+    mini_names = [p.name for p in minis]
+
+    index_path = composable_dir / "INDEX.md"
+    index_text = index_path.read_text(encoding="utf-8") if index_path.is_file() else None
+
+    if index_text is None:
+        r.line("FAIL", f"{skill_name}: INDEX.md not found at {index_path}")
+    else:
+        r.line("PASS", f"{skill_name}: INDEX.md exists")
+
+        # Every mini mentioned exactly once; no mini unlisted.
+        for name in mini_names:
+            count = index_text.count(name)
+            if count == 0:
+                r.line("FAIL", f"{skill_name}: mini '{name}' is not referenced in INDEX.md")
+            elif count > 1:
+                r.line("FAIL", f"{skill_name}: mini '{name}' is referenced {count} times in INDEX.md (expected exactly once)")
+            else:
+                r.line("PASS", f"{skill_name}: mini '{name}' referenced exactly once in INDEX.md")
+
+        # Index word count budget.
+        word_count = len(index_text.split())
+        threshold = 300 if len(minis) > 12 else 200
+        if word_count >= threshold:
+            r.line("WARN", f"{skill_name}: INDEX.md is {word_count} words (budget < {threshold} for {len(minis)} minis)")
+        else:
+            r.line("PASS", f"{skill_name}: INDEX.md word count {word_count} (< {threshold})")
+
+        # Knowledge-free heuristic: no single line should read like real content.
+        # The SPEC-mandated loading-policy header (§3.6) is exempt: it is
+        # required verbatim and is loading metadata, not knowledge.
+        long_lines = [
+            ln.strip() for ln in index_text.splitlines()
+            if len(ln.split()) > 30 and not ln.strip().startswith("Loading policy:")
+        ]
+        if long_lines:
+            r.line("WARN", f"{skill_name}: INDEX.md has {len(long_lines)} line(s) over ~30 words (looks like knowledge, not a menu)")
+        else:
+            r.line("PASS", f"{skill_name}: INDEX.md lines all under ~30 words")
+
+        # 00-core always-load marking.
+        core_path = composable_dir / "mini" / "00-core.md"
+        if core_path.is_file():
+            core_lines = [ln for ln in index_text.splitlines() if "00-core.md" in ln]
+            marked = any(
+                "always load" in ln.lower() or "always-load" in ln.lower()
+                for ln in core_lines
+            )
+            if marked:
+                r.line("PASS", f"{skill_name}: 00-core.md is marked always-load in INDEX.md")
+            else:
+                r.line("FAIL", f"{skill_name}: 00-core.md exists but is not marked always-load in INDEX.md")
+        else:
+            r.line("PASS", f"{skill_name}: no 00-core.md present (not required)")
+
+    # No mini unlisted: covered above per-mini when INDEX.md exists. Also
+    # flag stray files in mini/ that aren't .md (informational only; skip).
+
+    if not minis:
+        r.line("WARN", f"{skill_name}: no mini/*.md files found")
+
+    for mini in minis:
+        raw = mini.read_text(encoding="utf-8")
+        fm = split_frontmatter(raw)
+
+        if not fm.body.strip():
+            r.line("FAIL", f"{skill_name}/{mini.name}: file is empty after frontmatter")
+        else:
+            r.line("PASS", f"{skill_name}/{mini.name}: nonempty")
+
+        if any(H1_RE.match(ln) for ln in fm.body.splitlines()):
+            r.line("PASS", f"{skill_name}/{mini.name}: has an H1")
+        else:
+            r.line("FAIL", f"{skill_name}/{mini.name}: missing an H1 (# Title)")
+
+        if raw.startswith("---"):
+            if fm.data is None or fm.errors:
+                for err in (fm.errors or ["frontmatter present but unparsable"]):
+                    r.line("FAIL", f"{skill_name}/{mini.name}: invalid frontmatter: {err}")
+            else:
+                unknown = sorted(set(fm.data) - KNOWN_FRONTMATTER_KEYS)
+                if unknown:
+                    r.line("FAIL", f"{skill_name}/{mini.name}: unknown frontmatter key(s): {unknown}")
+                else:
+                    r.line("PASS", f"{skill_name}/{mini.name}: frontmatter keys OK ({sorted(fm.data)})")
+
+                for key in LIST_KEYS & set(fm.data):
+                    values = fm.data[key]
+                    if isinstance(values, str):
+                        values = [values]
+                    bad = [v for v in values if not PATH_LIKE_RE.match(v)]
+                    if bad:
+                        r.line("FAIL", f"{skill_name}/{mini.name}: {key} has non-path-like value(s): {bad}")
+                    else:
+                        r.line("PASS", f"{skill_name}/{mini.name}: {key} values look like paths")
+
+                # version: optional; silent when absent, FAIL on malformed semver.
+                if "version" in fm.data:
+                    value = fm.data["version"]
+                    if isinstance(value, str) and is_semver(value):
+                        r.line("PASS", f"{skill_name}/{mini.name}: version {value!r} is valid semver")
+                    else:
+                        r.line("FAIL", f"{skill_name}/{mini.name}: version {value!r} is not valid semver (expected X.Y.Z)")
+        else:
+            r.line("PASS", f"{skill_name}/{mini.name}: no frontmatter (ok, optional)")
+
+    # Skill-level VERSION file: optional; silent when absent, FAIL on malformed semver.
+    skill_version = read_skill_version(composable_dir)
+    if skill_version is not None:
+        if is_semver(skill_version):
+            r.line("PASS", f"{skill_name}: VERSION is valid semver ({skill_version})")
+        else:
+            r.line("FAIL", f"{skill_name}: VERSION {skill_version!r} is not valid semver (expected X.Y.Z)")
+
+    # BUNDLE.md staleness.
+    bundle_path = composable_dir / "BUNDLE.md"
+    if not minis:
+        pass
+    elif not bundle_path.is_file():
+        r.line("WARN", f"{skill_name}: BUNDLE.md missing; run `compile`")
+    else:
+        expected = build_bundle_text(skill_name, minis, skill_version=skill_version)
+        actual = bundle_path.read_text(encoding="utf-8")
+        if actual != expected:
+            r.line("FAIL", f"{skill_name}: BUNDLE.md is stale (does not match mini/*.md); re-run `compile`")
+        else:
+            r.line("PASS", f"{skill_name}: BUNDLE.md is up to date")
+
+
+def cmd_lint(args: argparse.Namespace) -> int:
+    composable_dir = resolve_composable_dir(Path(args.skill_dir))
+    if not composable_dir.is_dir():
+        print(f"error: composable dir not found: {composable_dir}", file=sys.stderr)
+        return 1
+    r = Reporter()
+    lint_skill(composable_dir, r)
+    print("\n".join(r.lines))
+    print(f"\n{r.summary()}")
+    return 1 if r.has_fail() else 0
+
+
+# --------------------------------------------------------------------------
+# parity
+# --------------------------------------------------------------------------
+
+def normalize_words(text: str) -> set[str]:
+    words = re.findall(r"[A-Za-z][A-Za-z']+", text.lower())
+    return {w for w in words if len(w) >= 4 and w not in STOPWORDS}
+
+
+def heading_is_covered(heading: str, mini_text_lower: str, mini_words: set[str]) -> bool:
+    clean = re.sub(r"[^A-Za-z0-9 ]", " ", heading).strip().lower()
+    if clean and clean in mini_text_lower:
+        return True
+    sig = normalize_words(heading)
+    if not sig:
+        return False
+    overlap = sig & mini_words
+    return len(overlap) / len(sig) >= 0.6
+
+
+def cmd_parity(args: argparse.Namespace) -> int:
+    composable_dir = resolve_composable_dir(Path(args.skill_dir))
+    source_dir = Path(args.source_dir)
+    if not composable_dir.is_dir():
+        print(f"error: composable dir not found: {composable_dir}", file=sys.stderr)
+        return 1
+    if not source_dir.is_dir():
+        print(f"error: source dir not found: {source_dir}", file=sys.stderr)
+        return 1
+
+    skill_name = skill_name_for(composable_dir)
+    minis = mini_files(composable_dir)
+    mini_bodies = [strip_frontmatter_body(p.read_text(encoding="utf-8")) for p in minis]
+    mini_union_text = "\n".join(mini_bodies)
+    mini_tokens = toks(mini_union_text)
+    mini_words = normalize_words(mini_union_text)
+    mini_text_lower = mini_union_text.lower()
+
+    source_files = sorted(source_dir.rglob("*.md"))
+    if not source_files:
+        print(f"error: no *.md files found under {source_dir}", file=sys.stderr)
+        return 1
+    source_texts = {p: p.read_text(encoding="utf-8") for p in source_files}
+    source_tokens = sum(toks(t) for t in source_texts.values())
+
+    ratio = (mini_tokens / source_tokens) if source_tokens else 0.0
+
+    print(f"Parity report: {skill_name}  (source: {source_dir})")
+    print(f"  source files : {len(source_files)}")
+    print(f"  source tokens: {fmt_toks(source_tokens)}")
+    print(f"  mini tokens  : {fmt_toks(mini_tokens)}  ({len(minis)} minis)")
+    print(f"  ratio        : {ratio:.1%}")
+
+    fail = False
+    if ratio < 0.85:
+        print(f"[FAIL] mini tokens are only {ratio:.1%} of source tokens (< 85%); summarization suspected")
+        fail = True
+    else:
+        print(f"[PASS] mini tokens are {ratio:.1%} of source tokens (>= 85%)")
+
+    dropped = []
+    for path, text in source_texts.items():
+        for line in text.splitlines():
+            m = H2_H3_RE.match(line.strip())
+            if not m:
+                continue
+            heading = m.group(2).strip()
+            if not heading:
+                continue
+            if not heading_is_covered(heading, mini_text_lower, mini_words):
+                dropped.append(f"{path.relative_to(source_dir)}: {heading}")
+
+    if dropped:
+        print(f"\n[WARN] {len(dropped)} source heading(s) with no fuzzy match in any mini (possibly dropped):")
+        for d in dropped:
+            print(f"    - {d}")
+    else:
+        print("\n[PASS] every source ## / ### heading has a fuzzy match in the minis")
+
+    return 1 if fail else 0
+
+
+# --------------------------------------------------------------------------
+# report
+# --------------------------------------------------------------------------
+
+def find_skill_roots(root: Path) -> list[Path]:
+    """Recursively find every skill root under ``root`` (any directory at any
+    depth containing a ``composable/`` subdirectory) so a categorized layout
+    (e.g. ``skills/authored/code-review/``) and a flat one are both discovered."""
+    skill_roots = [p.parent for p in root.rglob("composable") if p.is_dir()]
+    return sorted(skill_roots, key=lambda p: p.relative_to(root).as_posix())
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    root = Path(args.skills_root)
+    if not root.is_dir():
+        print(f"error: skills root not found: {root}", file=sys.stderr)
+        return 1
+
+    rows = []
+    any_fail = False
+    for child in find_skill_roots(root):
+        composable_dir = resolve_composable_dir(child)
+        minis = mini_files(composable_dir)
+        if not minis and not (composable_dir / "INDEX.md").is_file():
+            continue  # not a CCS skill dir
+
+        name = child.relative_to(root).as_posix()
+        version = read_skill_version(composable_dir) or "-"
+        index_path = composable_dir / "INDEX.md"
+        index_tokens = toks(index_path.read_text(encoding="utf-8")) if index_path.is_file() else 0.0
+
+        core_path = composable_dir / "mini" / "00-core.md"
+        core_tokens = toks(strip_frontmatter_body(core_path.read_text(encoding="utf-8"))) if core_path.is_file() else None
+
+        bundle_path = composable_dir / "BUNDLE.md"
+        bundle_tokens = toks(bundle_path.read_text(encoding="utf-8")) if bundle_path.is_file() else None
+
+        mini_token_counts = [toks(strip_frontmatter_body(p.read_text(encoding="utf-8"))) for p in minis]
+
+        r = Reporter()
+        lint_skill(composable_dir, r)
+        if r.has_fail():
+            any_fail = True
+
+        rows.append({
+            "name": name,
+            "version": version,
+            "minis": len(minis),
+            "index_tokens": index_tokens,
+            "core_tokens": core_tokens,
+            "bundle_tokens": bundle_tokens,
+            "min_mini": min(mini_token_counts) if mini_token_counts else None,
+            "max_mini": max(mini_token_counts) if mini_token_counts else None,
+            "lint": f"{r.counts['PASS']}P/{r.counts['WARN']}W/{r.counts['FAIL']}F",
+        })
+
+    if not rows:
+        print(f"no CCS skill directories found under {root}")
+        return 0
+
+    headers = ["skill", "version", "minis", "index_tok", "core_tok", "bundle_tok", "min_mini_tok", "max_mini_tok", "lint (P/W/F)"]
+
+    def fmt(v):
+        if v is None:
+            return "-"
+        if isinstance(v, float):
+            return fmt_toks(v)
+        return str(v)
+
+    table = [headers]
+    for row in rows:
+        table.append([
+            row["name"], row["version"], str(row["minis"]), fmt(row["index_tokens"]), fmt(row["core_tokens"]),
+            fmt(row["bundle_tokens"]), fmt(row["min_mini"]), fmt(row["max_mini"]), row["lint"],
+        ])
+
+    widths = [max(len(r[i]) for r in table) for i in range(len(headers))]
+    for i, row in enumerate(table):
+        line = "  ".join(cell.ljust(widths[j]) for j, cell in enumerate(row))
+        print(line)
+        if i == 0:
+            print("  ".join("-" * w for w in widths))
+
+    return 1 if any_fail else 0
+
+
+# --------------------------------------------------------------------------
+# bump
+# --------------------------------------------------------------------------
+
+def cmd_bump(args: argparse.Namespace) -> int:
+    composable_dir = resolve_composable_dir(Path(args.skill_dir))
+    if not composable_dir.is_dir():
+        print(f"error: composable dir not found: {composable_dir}", file=sys.stderr)
+        return 1
+
+    part = args.part
+    vpath = version_path(composable_dir)
+    old_raw = read_skill_version(composable_dir)
+    if old_raw is None:
+        # No VERSION file yet: initialize it rather than bumping from 0.0.0.
+        old_display = "(none)"
+        new = "0.1.0"
+    else:
+        if not is_semver(old_raw):
+            print(f"error: existing VERSION {old_raw!r} is not valid semver (expected X.Y.Z)", file=sys.stderr)
+            return 1
+        old_display = old_raw
+        new = bump_semver(old_raw, part)
+
+    vpath.write_text(f"{new}\n", encoding="utf-8")
+    print(f"{skill_name_for(composable_dir)}: {old_display} -> {new}")
+    return 0
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="hive.py",
+        description="Hive skill framework CLI (CCS spec): compile, lint, parity, report, bump.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_compile = sub.add_parser("compile", help="Regenerate BUNDLE.md (and optional presets) from mini/*.md")
+    p_compile.add_argument("skill_dir", help="Path to the skill root or its composable/ dir")
+    p_compile.add_argument(
+        "--presets", nargs="+", metavar="NAME=IDS",
+        help="e.g. --presets quick=01,04,05 deep=01,02,03,04,05,06",
+    )
+    p_compile.set_defaults(func=cmd_compile)
+
+    p_lint = sub.add_parser("lint", help="Check a skill's composable directory for structural issues")
+    p_lint.add_argument("skill_dir", help="Path to the skill root or its composable/ dir")
+    p_lint.set_defaults(func=cmd_lint)
+
+    p_parity = sub.add_parser("parity", help="Compare a compiled skill's minis against its source material")
+    p_parity.add_argument("skill_dir", help="Path to the skill root or its composable/ dir")
+    p_parity.add_argument("source_dir", help="Path to the original (pre-conversion) markdown source")
+    p_parity.set_defaults(func=cmd_parity)
+
+    p_report = sub.add_parser("report", help="Summarize all CCS skills under a skills root")
+    p_report.add_argument("skills_root", help="Path to a directory containing one subdir per skill")
+    p_report.set_defaults(func=cmd_report)
+
+    p_bump = sub.add_parser("bump", help="Bump (or initialize) a skill's composable/VERSION")
+    p_bump.add_argument("skill_dir", help="Path to the skill root or its composable/ dir")
+    p_bump.add_argument(
+        "part", nargs="?", choices=["major", "minor", "patch"], default="patch",
+        help="Version component to bump (default: patch)",
+    )
+    p_bump.set_defaults(func=cmd_bump)
+
+    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())