@event4u/agent-config 6.1.0 → 7.0.1

package/src/scripts/lint_command_tiers.py

@@ -1,216 +0,0 @@
-#!/usr/bin/env python3
-"""Lint slash-command frontmatter for the `tier:` key.
-
-Hard-fails CI if any command under .agent-src.uncondensed/commands/
-lacks a `tier:` declaration or uses an unknown tier value. The valid
-tier set is locked by docs/contracts/command-surface-tiers.md.
-
-Hooked into `task ci` after `task lint-rule-tiers`.
-
-Exit codes:
-  0  every command declares a valid tier
-  1  one or more commands missing or using an invalid tier
-"""
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-QUIET = "--quiet" in sys.argv
-
-REPO = Path(__file__).resolve().parents[2]
-
-# Commands live under every artefact root post-monorepo Phase 4.
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-from _lib.agent_src import artefact_roots  # noqa: E402
-
-# Post-ADR-051 the command sources live at src/domains/<pack>/**/command.md;
-# legacy artefact-root commands/ dirs are kept for older checkouts. A root
-# whose commands/ holds only evals (no .md) is not a command source.
-COMMANDS_DIRS = [
-    root / "commands" for root in artefact_roots()
-    if (root / "commands").is_dir()
-    and any(p.name != "AGENTS.md" for p in (root / "commands").rglob("*.md"))
-]
-DOMAINS_DIR = REPO / "src" / "domains"
-# Consumer-facing projection — must also carry tier so .augment/commands/
-# (which symlinks to dist/agent-src/commands/) renders the tier filter.
-COMMANDS_DIR_CONDENSED = REPO / "dist/agent-src" / "commands"
-
-VALID_TIERS = frozenset({"0", "1", "2"})
-# ADR-090: `visibility:` is the named source of truth; `tier:` is the
-# back-compat integer alias. Both are validated; when both are present they
-# MUST agree per this mapping.
-VALID_VISIBILITIES = frozenset({"visible", "advanced", "internal"})
-TIER_TO_VISIBILITY = {"0": "visible", "1": "advanced", "2": "internal"}
-
-
-def parse_field(text: str, key: str) -> str | None:
-    if not text.startswith("---\n"):
-        return None
-    end = text.find("\n---\n", 4)
-    if end == -1:
-        return None
-    for line in text[4:end].splitlines():
-        if ":" not in line:
-            continue
-        k, _, v = line.partition(":")
-        if k.strip() == key:
-            return v.strip().strip('"').strip("'")
-    return None
-
-
-def parse_tier(text: str) -> str | None:
-    return parse_field(text, "tier")
-
-
-def visibility_error(text: str) -> str | None:
-    """Validate the visibility field (ADR-090). Returns an error string or None.
-
-    Requires a present + valid visibility, and consistency with the tier alias
-    whenever both are declared.
-    """
-    vis = parse_field(text, "visibility")
-    if vis is None:
-        return "missing visibility"
-    if vis not in VALID_VISIBILITIES:
-        return f"invalid visibility '{vis}'"
-    tier = parse_field(text, "tier")
-    if tier in TIER_TO_VISIBILITY and TIER_TO_VISIBILITY[tier] != vis:
-        return f"visibility '{vis}' disagrees with tier '{tier}' (expected '{TIER_TO_VISIBILITY[tier]}')"
-    return None
-
-
-def lint(commands_dir: Path, *, quiet: bool = False) -> int:
-    """Lint a commands directory. Returns 0 on success, 1 on failure."""
-    if not commands_dir.is_dir():
-        print(
-            f"lint_command_tiers: no commands dir at {commands_dir}",
-            file=sys.stderr,
-        )
-        return 1
-
-    files = sorted(commands_dir.rglob("*.md"))
-    # Sub-AGENTS.md companions are not slash commands.
-    commands = [p for p in files if p.name != "AGENTS.md"]
-
-    if not commands:
-        print(
-            f"lint_command_tiers: no commands found under {commands_dir}",
-            file=sys.stderr,
-        )
-        return 1
-
-    missing: list[str] = []
-    invalid: list[tuple[str, str]] = []
-    vis_errors: list[tuple[str, str]] = []
-
-    for cmd in commands:
-        rel = cmd.relative_to(commands_dir).as_posix()
-        text = cmd.read_text(encoding="utf-8")
-        tier = parse_tier(text)
-        if tier is None:
-            missing.append(rel)
-        elif tier not in VALID_TIERS:
-            invalid.append((rel, tier))
-        if (ve := visibility_error(text)) is not None:
-            vis_errors.append((rel, ve))
-
-    if missing or invalid or vis_errors:
-        print(
-            f"❌  lint_command_tiers: {len(missing)} missing tier, "
-            f"{len(invalid)} invalid tier, {len(vis_errors)} visibility "
-            f"(of {len(commands)} commands)",
-            file=sys.stderr,
-        )
-        for name in missing:
-            print(f"    missing tier: {name}", file=sys.stderr)
-        for name, tier in invalid:
-            print(f"    invalid tier '{tier}': {name}", file=sys.stderr)
-        for name, err in vis_errors:
-            print(f"    {err}: {name}", file=sys.stderr)
-        print(
-            f"    valid tiers: {sorted(VALID_TIERS)}; "
-            f"valid visibility: {sorted(VALID_VISIBILITIES)}",
-            file=sys.stderr,
-        )
-        print(
-            "    contract: docs/contracts/command-surface-tiers.md (ADR-090)",
-            file=sys.stderr,
-        )
-        return 1
-
-    if not quiet:
-        print(
-            f"✅  lint_command_tiers: {len(commands)} commands, "
-            f"all tier + visibility values valid"
-        )
-    return 0
-
-
-def lint_domain_sources(*, quiet: bool = False) -> int:
-    """Lint src/domains/**/command.md — the post-ADR-051 authoring tree."""
-    commands = sorted(DOMAINS_DIR.rglob("command.md"))
-    if not commands:
-        print(
-            f"lint_command_tiers: no command.md found under {DOMAINS_DIR}",
-            file=sys.stderr,
-        )
-        return 1
-    missing: list[str] = []
-    invalid: list[tuple[str, str]] = []
-    vis_errors: list[tuple[str, str]] = []
-    for c in commands:
-        rel = c.relative_to(REPO).as_posix()
-        text = c.read_text(encoding="utf-8")
-        tier = parse_tier(text)
-        if tier is None:
-            missing.append(rel)
-        elif tier not in VALID_TIERS:
-            invalid.append((rel, tier))
-        if (ve := visibility_error(text)) is not None:
-            vis_errors.append((rel, ve))
-    if missing or invalid or vis_errors:
-        print(
-            f"❌  lint_command_tiers: {len(missing)} missing tier, "
-            f"{len(invalid)} invalid tier, {len(vis_errors)} visibility "
-            f"(of {len(commands)} domain commands)",
-            file=sys.stderr,
-        )
-        for name in missing:
-            print(f"    missing tier: {name}", file=sys.stderr)
-        for name, tier in invalid:
-            print(f"    invalid tier '{tier}': {name}", file=sys.stderr)
-        for name, err in vis_errors:
-            print(f"    {err}: {name}", file=sys.stderr)
-        return 1
-    if not quiet:
-        print(
-            f"✅  lint_command_tiers: {len(commands)} domain commands, "
-            f"all tier + visibility values valid"
-        )
-    return 0
-
-
-def main() -> int:
-    if not COMMANDS_DIRS and not DOMAINS_DIR.is_dir():
-        print(
-            "lint_command_tiers: no commands dir found under any artefact root",
-            file=sys.stderr,
-        )
-        return 1
-    rc = 0
-    if DOMAINS_DIR.is_dir():
-        rc |= lint_domain_sources(quiet=QUIET)
-    for commands_dir in COMMANDS_DIRS:
-        rc |= lint(commands_dir, quiet=QUIET)
-    # The condensed projection is the consumer-facing tree (via the
-    # .augment/commands → dist/agent-src/commands symlink). It must also
-    # carry tier so the surface stays uniform.
-    if COMMANDS_DIR_CONDENSED.is_dir():
-        rc |= lint(COMMANDS_DIR_CONDENSED, quiet=QUIET)
-    return rc
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/src/scripts/lint_command_verbs.py

@@ -1,206 +0,0 @@
-#!/usr/bin/env python3
-"""Controlled-verb linter for visible commands (6.0.0-C Phase 2 Step 4; ADR-041).
-
-A VISIBLE command (tier 0/1) must have a leading token drawn from the approved
-verb allowlist in ``src/config/discovery/command-verbs.yml``. ``create-*`` is a
-banned leading token for new visible commands (``create-pr`` is grandfathered).
-
-FORWARD-ONLY: only command files **added** since ``--baseline`` (default
-``main``), plus files **promoted** to a visible tier since baseline, are
-checked. The existing surface is grandfathered — no rename wave. Mirrors the
-baseline-diff machinery of ``lint_no_new_atomic_commands.py``.
-
-Single modular lint: both the approved-verb rule and the banned-prefix rule run
-in one pass. Every rule blocks CI (no advisory-only tier — see ADR-041 § 6).
-
-Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
-
-Usage:
-    python3 scripts/lint_command_verbs.py
-    python3 scripts/lint_command_verbs.py --baseline origin/main
-    python3 scripts/lint_command_verbs.py --all     # check every visible command
-"""
-
-from __future__ import annotations
-
-import argparse
-import re
-import subprocess
-import sys
-from dataclasses import dataclass
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent.parent
-VERBS_YML = ROOT / "src" / "config" / "discovery" / "command-verbs.yml"
-_CMD_PATH_RE = re.compile(r"\.agent-src\.uncondensed/commands/.+\.md$")
-NAME_RE = re.compile(r"^name:\s*(.*)$", re.MULTILINE)
-TIER_RE = re.compile(r"^tier:\s*(\d+)", re.MULTILINE)
-SUB_RE = re.compile(r"^sub:\s*(.*)$", re.MULTILINE)
-VISIBLE_TIERS = {0, 1}
-
-
-@dataclass
-class Violation:
-    file: str
-    rule: str
-    reason: str
-
-
-def load_config() -> tuple[set[str], set[str], set[str]]:
-    import yaml
-    data = yaml.safe_load(VERBS_YML.read_text(encoding="utf-8")) or {}
-    approved = set(data.get("approved_verbs") or [])
-    banned = set(data.get("banned_prefixes") or [])
-    grandfathered = set(data.get("grandfathered") or [])
-    if not approved:
-        print(f"❌  No approved_verbs in {VERBS_YML}", file=sys.stderr)
-        sys.exit(3)
-    return approved, banned, grandfathered
-
-
-def _git(args: list[str], *, tolerant: bool = False) -> str:
-    try:
-        r = subprocess.run(["git", *args], capture_output=True, text=True,
-                           cwd=ROOT, timeout=15)
-    except (FileNotFoundError, subprocess.TimeoutExpired) as exc:
-        print(f"❌  git {' '.join(args)} failed: {exc}", file=sys.stderr)
-        sys.exit(3)
-    if r.returncode != 0:
-        if tolerant:
-            return ""
-        print(f"❌  git {' '.join(args)} exit {r.returncode}: {r.stderr}",
-              file=sys.stderr)
-        sys.exit(3)
-    return r.stdout
-
-
-def _parse(text: str) -> tuple[str | None, int, str | None]:
-    """(name, tier, sub) from frontmatter text; tier defaults to 2 (internal).
-
-    `sub` is the cluster sub-name frontmatter field (`sub: ci` on
-    `fix/ci/command.md`) — since names are plain hyphen slugs, `sub:` is the
-    only reliable way to find the verb token of a nested cluster command.
-    """
-    nm = NAME_RE.search(text)
-    name = nm.group(1).strip().strip('"').strip("'") if nm else None
-    tm = TIER_RE.search(text)
-    tier = int(tm.group(1)) if tm else 2
-    sm = SUB_RE.search(text)
-    sub = sm.group(1).strip().strip('"').strip("'") if sm else None
-    return name, tier, sub
-
-
-def changed_command_files(baseline: str) -> dict[str, str]:
-    """relpath → change kind ('A' added | 'M' modified) for command files."""
-    out: dict[str, str] = {}
-    for kind in ("A", "M"):
-        for p in _git(["diff", "--name-only", f"--diff-filter={kind}",
-                       f"{baseline}...HEAD"]).splitlines():
-            if p.strip() and _CMD_PATH_RE.search(p):
-                out[p.strip()] = kind
-    for line in _git(["status", "--porcelain", "-uall"]).splitlines():
-        st, path = line[:2].strip(), line[3:].strip().split(" -> ")[-1]
-        if _CMD_PATH_RE.search(path):
-            out[path] = "A" if st in ("A", "??", "AM") else out.get(path, "M")
-    return out
-
-
-def all_visible_command_files() -> dict[str, str]:
-    out: dict[str, str] = {}
-    pkgs = ROOT / "packages"
-    roots = [d for d in pkgs.glob("*/.agent-src.uncondensed/commands")
-             if d.is_dir()] if pkgs.is_dir() else []
-    for root in roots:
-        for md in root.rglob("*.md"):
-            if md.name == "AGENTS.md" or "_archive" in md.parts:
-                continue
-            out[str(md.relative_to(ROOT))] = "A"
-    return out
-
-
-def leading_token(name: str, sub: str | None = None) -> str:
-    """The verb token: the `sub:` frontmatter head for cluster commands, or
-    the bare name's head. Command names are always hyphen slugs (Agent-Skills
-    spec, 2026-06 Zed fix) — the legacy `:` split stays only to tolerate
-    colon-named shapes in git history."""
-    base = sub if sub else name.split(":")[-1]
-    return base.split("-")[0]
-
-
-def check(relpath: str, kind: str, baseline: str, approved: set[str],
-          banned: set[str], grandfathered: set[str]) -> list[Violation]:
-    abs_path = ROOT / relpath
-    if not abs_path.exists():
-        return []  # deleted
-    name, tier, sub = _parse(abs_path.read_text(encoding="utf-8"))
-    if name is None or tier not in VISIBLE_TIERS:
-        return []  # internal / unnamed — not gated
-    if kind == "M":
-        # Only a PROMOTION into visibility counts as a new visible surface.
-        prev = _git(["show", f"{baseline}:{relpath}"], tolerant=True)
-        if prev:
-            _, prev_tier, _ = _parse(prev)
-            if prev_tier in VISIBLE_TIERS:
-                return []  # already visible before — grandfathered
-
-    if name in grandfathered:
-        return []  # documented single-command exception — exempt from both rules
-    bare = sub if sub else name.split(":")[-1]
-    vio: list[Violation] = []
-    # Rule 1 — banned prefix (create-*).
-    for bp in banned:
-        if bare == bp or bare.startswith(bp + "-"):
-            vio.append(Violation(relpath, "banned-prefix",
-                                 f"`{name}` uses the banned leading token "
-                                 f"`{bp}` (no {bp}-* commands — ADR-041 § 2). "
-                                 f"Grandfather it in command-verbs.yml only with "
-                                 f"a documented exception."))
-            return vio  # banned message is the actionable one; don't pile on
-    # Rule 2 — approved verb.
-    tok = leading_token(name, sub)
-    if tok not in approved:
-        vio.append(Violation(relpath, "approved-verb",
-                             f"leading token `{tok}` of `{name}` is not an "
-                             f"approved verb. Rename to an existing verb, or add "
-                             f"`{tok}` to src/config/discovery/command-verbs.yml in "
-                             f"its own PR with an ADR (ADR-041 § 5)."))
-    return vio
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__)
-    ap.add_argument("--baseline", default="main",
-                    help="git ref to diff against (default: main)")
-    ap.add_argument("--all", action="store_true",
-                    help="check every visible command, not just changed ones")
-    ap.add_argument("--quiet", action="store_true")
-    args = ap.parse_args()
-
-    approved, banned, grandfathered = load_config()
-    targets = (all_visible_command_files() if args.all
-               else changed_command_files(args.baseline))
-    if not targets:
-        if not args.quiet:
-            print(f"✅  No new/changed commands under commands/ "
-                  f"(baseline: {args.baseline}).")
-        return 0
-
-    violations: list[Violation] = []
-    for relpath, kind in sorted(targets.items()):
-        violations += check(relpath, kind, args.baseline, approved,
-                            banned, grandfathered)
-
-    if violations:
-        print(f"❌  {len(violations)} controlled-verb violation(s):")
-        for v in violations:
-            print(f"  • [{v.rule}] {v.file} — {v.reason}")
-        print("\nSee docs/decisions/ADR-041-controlled-command-verbs.md.")
-        return 1
-    if not args.quiet:
-        print(f"✅  {len(targets)} new/changed command(s) all use an approved "
-              f"verb (baseline: {args.baseline}).")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/lint_commit_subjects.py

@@ -1,139 +0,0 @@
-#!/usr/bin/env python3
-"""Reject commit subjects that would leak into the auto-generated changelog.
-
-`scripts/release.py` reads commit subjects verbatim from
-`<prev-tag>..HEAD` and writes them into `CHANGELOG.md` sections (notably
-`### Breaking`). A sloppy subject — `wip`, `commit leftovers`, `fixup`,
-short typos — becomes a sloppy public changelog line. Per
-[ADR-033](../docs/decisions/ADR-033-distribution-identity-npm-primary.md)
-and Phase 3 of `road-to-distribution-identity.md` this lint is the
-CI-enforced gate that closes that surface.
-
-Rules (PRO commit, range `<base>..<head>`):
-
-- Subject length **after** stripping the Conventional-Commits type-prefix
-  (`feat:` / `fix(scope):` / `chore!:` / …) must be ≥ 10 characters.
-- Subject must not contain blocklist words as whole tokens:
-  `leftover` / `leftovers` / `wip` / `temp` / `tmp` / `fixup`.
-  Case-insensitive; matched on word boundaries so legitimate uses like
-  `template` or `tempor­ary` (rare) survive — the linter targets the
-  short hand-wave forms reviewers see in feedback rounds.
-
-Carve-outs:
-
-- Merge commits (`Merge pull request …`, `Merge branch …`) are skipped —
-  they are GitHub-generated and not consumer-visible in the changelog.
-- Revert commits (`Revert "…"`) are skipped — they ride the original
-  subject's discipline.
-
-Local invocation defaults to `origin/main..HEAD` (the "what I am about
-to push" range). CI sets `--base $GITHUB_BASE_REF --head $GITHUB_SHA`.
-
-Cap: ≤ 150 LOC, stdlib only. Hooked into `task ci` via
-`task lint-commit-subjects`.
-"""
-from __future__ import annotations
-
-import argparse
-import re
-import subprocess
-import sys
-
-BLOCKLIST = frozenset({"leftover", "leftovers", "wip", "temp", "tmp", "fixup"})
-MIN_SUBJECT_LEN = 10
-
-# Conventional Commits prefix — `type(scope)!?: message`. Matches the
-# heads our `scripts/release.py` and CHANGELOG section logic respect.
-CONVENTIONAL_PREFIX = re.compile(
-    r"^(feat|fix|chore|docs|refactor|test|perf|style|build|ci|revert)"
-    r"(\([^)]+\))?!?:\s+",
-    re.IGNORECASE,
-)
-
-# Skip lines — GitHub-generated merge subjects and revert commits.
-SKIP_PREFIXES = ("Merge pull request", "Merge branch", "Merge remote-tracking",
-                 'Revert "')
-
-
-def fetch_subjects(base: str, head: str) -> list[str]:
-    """Return one commit subject per element. Empty on no-range / no-commits."""
-    try:
-        result = subprocess.run(
-            ["git", "log", f"{base}..{head}", "--format=%s", "--no-merges"],
-            capture_output=True, text=True, check=True,
-        )
-    except subprocess.CalledProcessError as exc:
-        # CI without a proper base ref (force-push, first commit, weird state).
-        # Lint is advisory in that case — never block on git plumbing failures.
-        print(f"⚠️  git log {base}..{head} failed: {exc.stderr.strip()}",
-              file=sys.stderr)
-        return []
-    return [line.strip() for line in result.stdout.splitlines() if line.strip()]
-
-
-def check_subject(subject: str) -> list[str]:
-    """Return list of issue strings for the subject; empty = clean."""
-    if any(subject.startswith(p) for p in SKIP_PREFIXES):
-        return []
-    issues: list[str] = []
-    body = CONVENTIONAL_PREFIX.sub("", subject, count=1)
-    if len(body) < MIN_SUBJECT_LEN:
-        issues.append(
-            f"subject body < {MIN_SUBJECT_LEN} chars after Conventional-Commits "
-            f"prefix: {subject!r}"
-        )
-    tokens = {t.lower() for t in re.findall(r"[A-Za-z]+", body)}
-    hits = sorted(tokens & BLOCKLIST)
-    if hits:
-        issues.append(
-            f"blocklist token(s) {hits} in subject: {subject!r}"
-        )
-    return issues
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--base", default="origin/main",
-                        help="base ref (default: origin/main)")
-    parser.add_argument("--head", default="HEAD",
-                        help="head ref (default: HEAD)")
-    parser.add_argument("--quiet", action="store_true",
-                        help="suppress the clean-pass success line")
-    args = parser.parse_args()
-
-    subjects = fetch_subjects(args.base, args.head)
-    if not subjects:
-        if not args.quiet:
-            print(f"✅  No commit subjects to check in "
-                  f"{args.base}..{args.head}.")
-        return 0
-
-    failures: list[tuple[str, str]] = []
-    for subj in subjects:
-        for issue in check_subject(subj):
-            failures.append((subj, issue))
-
-    if failures:
-        print(f"❌  {len(failures)} commit-subject issue(s) in "
-              f"{args.base}..{args.head}:", file=sys.stderr)
-        for _, issue in failures:
-            print(f"   - {issue}", file=sys.stderr)
-        print(
-            "\nThese subjects feed the auto-generated CHANGELOG.md via "
-            "src/scripts/release.py — sloppy subjects become sloppy public "
-            "changelog lines. Per ADR-033 + "
-            "agents/roadmaps/road-to-distribution-identity.md § Phase 3.\n"
-            "Fix: rewrite the offending commits (e.g. `git rebase -i "
-            f"{args.base}` and `r`eword) with descriptive subjects, "
-            "then re-push.",
-            file=sys.stderr,
-        )
-        return 1
-
-    if not args.quiet:
-        print(f"✅  {len(subjects)} commit subject(s) clean.")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/src/scripts/lint_context_spine_usage.py

@@ -1,137 +0,0 @@
-#!/usr/bin/env python3
-"""Context-spine usage linter.
-
-Closes the lint gap left after `scripts/schemas/skill.schema.json`
-gained the `context_spine` enum: a skill can declare
-`context_spine: [product]` in frontmatter without ever citing the
-slot in its body, and the schema check will not catch it.
-
-This linter enforces the author checklist in
-`docs/contracts/context-spine.md` § 6: for every slot declared in
-frontmatter, the skill body MUST cite the slot at least once.
-A citation is any of these tokens:
-
-  - the literal path `agents/context-spine/<slot>.md`
-  - the slot name in bold: ``**<slot>**``
-  - the slot name in inline code: `` `<slot>` ``
-
-Cap: ≤ 150 LOC, stdlib only. Hooked into `task ci` via
-`task lint-context-spine-usage`.
-"""
-from __future__ import annotations
-
-import re
-import sys
-from pathlib import Path
-
-QUIET = "--quiet" in sys.argv
-
-REPO_ROOT = Path(__file__).resolve().parent.parent.parent
-SKILL_GLOBS = (
-    ".agent-src.uncondensed/skills/**/SKILL.md",
-    "dist/agent-src/skills/**/SKILL.md",
-)
-VALID_SLOTS = (
-    "product", "team", "repo",
-    "channel-stage", "funnel-stage", "customer-segment",
-    "fiscal-period", "org-stage", "regulatory-regime",
-)
-
-CONTEXT_SPINE_PAT = re.compile(
-    r"^context_spine:\s*\[([^\]]*)\]\s*$", re.MULTILINE
-)
-
-
-def _frontmatter_and_body(text: str) -> tuple[str, str]:
-    if not text.startswith("---\n"):
-        return "", text
-    end = text.find("\n---\n", 4)
-    if end == -1:
-        return "", text
-    return text[4:end], text[end + 5 :]
-
-
-def _read_spine(fm: str) -> list[str] | None:
-    m = CONTEXT_SPINE_PAT.search(fm)
-    if m is None:
-        return None
-    raw = m.group(1).strip()
-    if not raw:
-        return []
-    return [s.strip().strip("'\"") for s in raw.split(",") if s.strip()]
-
-
-def _slot_cited(body: str, slot: str) -> bool:
-    """A slot is cited if any of three forms appears in the body."""
-    forms = (
-        f"agents/context-spine/{slot}.md",
-        f"**{slot}**",
-        f"`{slot}`",
-    )
-    return any(form in body for form in forms)
-
-
-def lint_skill(path: Path) -> list[str]:
-    text = path.read_text(encoding="utf-8")
-    fm, body = _frontmatter_and_body(text)
-    if not fm:
-        return []
-    slots = _read_spine(fm)
-    if slots is None:
-        return []
-    problems: list[str] = []
-    for slot in slots:
-        if slot not in VALID_SLOTS:
-            problems.append(
-                f"unknown_context_spine_slot: '{slot}' "
-                f"(valid: {', '.join(VALID_SLOTS)})"
-            )
-            continue
-        if not _slot_cited(body, slot):
-            problems.append(
-                f"declared context_spine slot '{slot}' is never cited "
-                f"in the skill body — add `**{slot}**`, `` `{slot}` ``, "
-                f"or a link to `agents/context-spine/{slot}.md` "
-                f"(see docs/contracts/context-spine.md § 6)"
-            )
-    return problems
-
-
-def main() -> int:
-    skills: list[Path] = []
-    for pattern in SKILL_GLOBS:
-        skills.extend(sorted(REPO_ROOT.glob(pattern)))
-    if not skills:
-        print("❌  no SKILL.md files matched", file=sys.stderr)
-        return 1
-    failed = 0
-    declared = 0
-    for skill in skills:
-        rel = skill.relative_to(REPO_ROOT)
-        problems = lint_skill(skill)
-        text = skill.read_text(encoding="utf-8")
-        fm, _ = _frontmatter_and_body(text)
-        if fm and CONTEXT_SPINE_PAT.search(fm):
-            declared += 1
-        if problems:
-            failed += 1
-            print(f"❌  {rel}", file=sys.stderr)
-            for p in problems:
-                print(f"    - {p}", file=sys.stderr)
-    if failed:
-        print(
-            f"\n❌  {failed} skill(s) failed context-spine usage lint "
-            f"({declared} skill(s) declare a spine)",
-            file=sys.stderr,
-        )
-        return 1
-    if not QUIET:
-        print(
-            f"✅  {declared} skill(s) declare context_spine; "
-            f"all declared slots are cited in the body"
-        )
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())