@event4u/agent-config 6.0.0 → 7.0.0

package/src/scripts/lint_marketplace_install_completeness.py

@@ -1,198 +0,0 @@
-#!/usr/bin/env python3
-"""Lint that every command in `hooks/hooks.json` resolves to a real
-dispatcher subcommand in `scripts/_dispatch.bash`.
-
-Phase 6 of `road-to-hooks-actually-fire-in-consumers`.
-
-The linter checks **plugin-side completeness** — the package ships a
-valid `hooks.json` whose every command line points at a subcommand
-the dispatcher knows about. It does NOT check consumer-side
-scaffolding (that's the runtime `dispatch-issues.jsonl` log's job
-from Phase 1).
-
-This distinction is load-bearing — see Council R3 finding #1:
-"A valid plugin against an unscaffolded consumer is a PASS;
-the linter must not produce a false-positive on that state."
-
-Exit codes:
-  0 — every command resolves; clean.
-  1 — at least one command references an unknown subcommand.
-  2 — schema / file error.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import re
-import sys
-from pathlib import Path
-
-
-REPO_ROOT = Path(__file__).resolve().parent.parent.parent
-HOOKS_JSON = REPO_ROOT / "hooks" / "hooks.json"
-DISPATCH_BASH = REPO_ROOT / "src" / "scripts" / "_dispatch.bash"
-
-
-# Map agent-config-cli subcommand → dispatcher function name. The
-# subcommand is what appears after `./agent-config <subcommand>` in
-# the hooks.json command line; the function is what's defined in
-# _dispatch.bash. The user-facing subcommand uses colons; the
-# function uses underscores (e.g. `dispatch:hook` → `cmd_dispatch_hook`).
-def subcommand_to_function(subcommand: str) -> str:
-    # Normalise: replace `:` and `-` with `_`.
-    sanitised = subcommand.replace(":", "_").replace("-", "_")
-    return f"cmd_{sanitised}"
-
-
-def load_hook_commands(hooks_path: Path) -> list[tuple[str, str]]:
-    """Return [(event_name, command_line)] for every hook entry."""
-    try:
-        data = json.loads(hooks_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        raise SystemExit(f"lint-marketplace-install: cannot read {hooks_path}: {exc}")
-
-    hooks = data.get("hooks") or {}
-    if not isinstance(hooks, dict):
-        raise SystemExit(f"lint-marketplace-install: {hooks_path} `hooks` is not an object")
-
-    out: list[tuple[str, str]] = []
-    for event, groups in hooks.items():
-        if not isinstance(groups, list):
-            continue
-        for group in groups:
-            if not isinstance(group, dict):
-                continue
-            for entry in group.get("hooks", []) or []:
-                if not isinstance(entry, dict):
-                    continue
-                cmd = entry.get("command")
-                if isinstance(cmd, str) and cmd.strip():
-                    out.append((str(event), cmd))
-    return out
-
-
-# Pattern A: `"$CLAUDE_PROJECT_DIR"/agent-config <subcommand> [args...]`.
-# Accepts both quoted and bare CLAUDE_PROJECT_DIR.
-_CMD_RE = re.compile(
-    r'(?:"?\$\{?CLAUDE_PROJECT_DIR\}?"?/)?agent-config\s+([a-zA-Z0-9:_-]+)'
-)
-# Pattern B (ADR-020 global-binary fallback wrapper):
-#   BIN="$CLAUDE_PROJECT_DIR/agent-config"; [ -x "$BIN" ] || BIN=agent-config;
-#   "$BIN" <subcommand> [args...]
-# The subcommand follows the `"$BIN"` invocation; the wrapper must still
-# resolve an agent-config binary for the line to qualify.
-_BIN_CMD_RE = re.compile(r'"\$\{?BIN\}?"\s+([a-zA-Z0-9:_-]+)')
-
-
-def extract_subcommand(command_line: str) -> str | None:
-    """Pull the agent-config subcommand out of a hooks.json command line."""
-    m = _CMD_RE.search(command_line)
-    if m:
-        return m.group(1)
-    if "agent-config" in command_line:
-        m = _BIN_CMD_RE.search(command_line)
-        if m:
-            return m.group(1)
-    return None
-
-
-def load_dispatcher_subcommands(dispatch_path: Path) -> set[str]:
-    """Return the set of subcommand identifiers the dispatcher knows.
-
-    Reads `cmd_<name>` function definitions from _dispatch.bash and
-    converts back to subcommand form (underscores → colons / hyphens
-    is ambiguous, so we keep BOTH forms in the set — `dispatch_hook`
-    AND `dispatch:hook` — so the linter accepts either).
-    """
-    try:
-        text = dispatch_path.read_text(encoding="utf-8")
-    except OSError as exc:
-        raise SystemExit(f"lint-marketplace-install: cannot read {dispatch_path}: {exc}")
-
-    out: set[str] = set()
-    for match in re.finditer(r"^cmd_([a-zA-Z0-9_]+)\(\)", text, flags=re.MULTILINE):
-        ident = match.group(1)
-        # Add the underscore form.
-        out.add(ident)
-        # Also add a colon-substituted variant — agent-config supports
-        # `:` in user-facing subcommand names; the function strips them
-        # to underscores. We accept either spelling on the hook side.
-        # First _ → `:`, the rest stay (heuristic; covers `dispatch:hook`,
-        # `mcp:render`, `hooks:install` etc.).
-        if "_" in ident:
-            head, _, tail = ident.partition("_")
-            out.add(f"{head}:{tail}")
-    return out
-
-
-def lint(hooks_path: Path = HOOKS_JSON, dispatch_path: Path = DISPATCH_BASH) -> int:
-    if not hooks_path.is_file():
-        sys.stderr.write(f"lint-marketplace-install: {hooks_path} not found\n")
-        return 2
-    if not dispatch_path.is_file():
-        sys.stderr.write(f"lint-marketplace-install: {dispatch_path} not found\n")
-        return 2
-
-    commands = load_hook_commands(hooks_path)
-    known = load_dispatcher_subcommands(dispatch_path)
-
-    issues: list[str] = []
-    checked = 0
-    for event, cmd in commands:
-        sub = extract_subcommand(cmd)
-        if sub is None:
-            issues.append(
-                f"  {event}: command does not reference `agent-config <subcommand>`: "
-                f"{cmd!r}"
-            )
-            continue
-        checked += 1
-        if sub not in known:
-            issues.append(
-                f"  {event}: unknown_dispatcher_subcommand: {sub!r} "
-                f"(not in scripts/_dispatch.bash)"
-            )
-
-    if issues:
-        try:
-            relative = hooks_path.resolve().relative_to(REPO_ROOT)
-        except ValueError:
-            relative = hooks_path
-        sys.stderr.write(
-            f"lint-marketplace-install: {len(issues)} issue(s) in {relative}:\n"
-        )
-        for line in issues:
-            sys.stderr.write(line + "\n")
-        return 1
-
-    print(
-        f"✅  lint-marketplace-install: {checked} hook command(s) checked, "
-        f"all resolve to known dispatcher subcommands."
-    )
-    return 0
-
-
-def parse_args(argv: list[str]) -> argparse.Namespace:
-    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    p.add_argument(
-        "--hooks-json",
-        type=Path,
-        default=HOOKS_JSON,
-        help="Path to hooks/hooks.json (default: %(default)s)",
-    )
-    p.add_argument(
-        "--dispatch-bash",
-        type=Path,
-        default=DISPATCH_BASH,
-        help="Path to scripts/_dispatch.bash (default: %(default)s)",
-    )
-    return p.parse_args(argv)
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = parse_args(argv if argv is not None else sys.argv[1:])
-    return lint(args.hooks_json, args.dispatch_bash)
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/src/scripts/lint_mcp_registry_manifest.py

@@ -1,69 +0,0 @@
-#!/usr/bin/env python3
-"""Lint `dist/mcp/registry-manifest.json` against its JSON Schema.
-
-Asserts:
-  * file exists
-  * validates against `docs/contracts/mcp-registry-manifest.schema.json`
-  * `dist/mcp/awesome-mcp-servers.row.md` is non-empty and parses as a
-    single Markdown table row (one `|`-delimited line)
-  * `dist/mcp/mcp-cloudflare-catalogue.json` is valid JSON
-
-Exits 0 on success, 1 on any failure. `--quiet` suppresses the OK line.
-
-Roadmap: agents/roadmaps/strategic-visibility-mcp-topics-positioning.md Phase 2 exit gate.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from pathlib import Path
-
-import jsonschema
-
-ROOT = Path(__file__).resolve().parents[2]
-SCHEMA = ROOT / "docs" / "contracts" / "mcp-registry-manifest.schema.json"
-MANIFEST = ROOT / "dist" / "mcp" / "registry-manifest.json"
-ROW_MD = ROOT / "dist" / "mcp" / "awesome-mcp-servers.row.md"
-CF_JSON = ROOT / "dist" / "mcp" / "mcp-cloudflare-catalogue.json"
-
-
-def _fail(msg: str) -> int:
-    print(f"\u274c  {msg}", file=sys.stderr)
-    return 1
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    ap.add_argument("--quiet", action="store_true")
-    args = ap.parse_args()
-
-    for p in (SCHEMA, MANIFEST, ROW_MD, CF_JSON):
-        if not p.exists():
-            return _fail(f"missing: {p.relative_to(ROOT)}")
-
-    schema = json.loads(SCHEMA.read_text(encoding="utf-8"))
-    manifest = json.loads(MANIFEST.read_text(encoding="utf-8"))
-    try:
-        jsonschema.Draft202012Validator(schema).validate(manifest)
-    except jsonschema.ValidationError as e:
-        return _fail(f"schema validation: {e.message} at {list(e.absolute_path)}")
-
-    row = ROW_MD.read_text(encoding="utf-8").strip()
-    if not row:
-        return _fail("awesome-mcp-servers.row.md is empty")
-    if row.count("\n") != 0 or row.count("|") < 4:
-        return _fail("awesome-mcp-servers.row.md must be a single `|`-delimited row")
-
-    try:
-        json.loads(CF_JSON.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as e:
-        return _fail(f"mcp-cloudflare-catalogue.json: {e}")
-
-    if not args.quiet:
-        print(f"\u2705  mcp registry manifest OK ({len(manifest['registries'])} registries)")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/src/scripts/lint_media_policy_linkage.py

@@ -1,140 +0,0 @@
-#!/usr/bin/env python3
-"""Lint structural reachability of media governance policies.
-
-Every policy file under `agents/settings/policies/media/` (except README) must
-be linked from at least one of:
-
-  * a skill SKILL.md (any .agent-src.uncondensed/skills/*/SKILL.md
-    or .claude/skills/*/SKILL.md),
-  * a routing rule under .agent-src.uncondensed/rules/, or
-  * a sibling policy file under agents/settings/policies/media/.
-
-A policy that no surface references is a silent policy and a silent
-policy is a failed policy. This is the CI-side reachability guarantee
-the agent-in-the-loop enforcement model rests on (see
-agents/settings/policies/media/README.md § Enforcement model).
-
-Exit codes:
-  0  all policies linked
-  1  one or more orphan policies
-"""
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-QUIET = "--quiet" in sys.argv
-
-REPO = Path(__file__).resolve().parents[2]
-POLICY_DIR = REPO / "agents" / "policies" / "media"
-EXEMPT_STEMS = frozenset({"README"})
-
-# Surfaces scanned for inbound references to policy files.
-SCAN_ROOTS: tuple[Path, ...] = (
-    REPO / ".agent-src.uncondensed" / "skills",
-    REPO / ".agent-src.uncondensed" / "rules",
-    REPO / ".agent-src.uncondensed" / "commands",
-    REPO / ".claude" / "skills",
-    REPO / "agents" / "policies" / "media",
-)
-
-
-def emit(msg: str) -> None:
-    if not QUIET:
-        print(msg)
-
-
-def collect_policies() -> list[Path]:
-    if not POLICY_DIR.exists():
-        return []
-    return sorted(
-        p
-        for p in POLICY_DIR.glob("*.md")
-        if p.stem not in EXEMPT_STEMS
-    )
-
-
-def collect_scan_files() -> list[Path]:
-    files: list[Path] = []
-    for root in SCAN_ROOTS:
-        if not root.exists():
-            continue
-        files.extend(root.rglob("*.md"))
-    return files
-
-
-def referrers_for(policy: Path, scan_files: list[Path]) -> list[Path]:
-    """Return files that reference `policy` by its repo-relative name
-    or basename. We accept both the full path token
-    (`agents/settings/policies/media/likeness.md`) and the bare basename
-    (`likeness.md`) inside a markdown link, because sibling policies
-    link via relative `[likeness.md](likeness.md)` form.
-    """
-    needles = (
-        f"policies/media/{policy.name}",
-        f"]({policy.name})",
-    )
-    referrers: list[Path] = []
-    for scan_file in scan_files:
-        # A policy can't satisfy its own linkage requirement.
-        if scan_file.resolve() == policy.resolve():
-            continue
-        try:
-            text = scan_file.read_text(encoding="utf-8", errors="replace")
-        except OSError:
-            continue
-        if any(n in text for n in needles):
-            referrers.append(scan_file)
-    return referrers
-
-
-def main() -> int:
-    if not POLICY_DIR.exists():
-        emit(
-            "media-policy-linkage: agents/settings/policies/media/ missing — "
-            "nothing to lint."
-        )
-        return 0
-
-    policies = collect_policies()
-    if not policies:
-        emit(
-            "media-policy-linkage: agents/settings/policies/media/ has no policy "
-            "files — nothing to lint."
-        )
-        return 0
-
-    scan_files = collect_scan_files()
-    orphans: list[Path] = []
-    for policy in policies:
-        referrers = referrers_for(policy, scan_files)
-        rel = policy.relative_to(REPO)
-        if not referrers:
-            orphans.append(policy)
-            emit(f"❌  ORPHAN  {rel}")
-            continue
-        emit(f"✅  {rel}  ({len(referrers)} referrer(s))")
-
-    if orphans:
-        print(
-            f"\nmedia-policy-linkage: {len(orphans)} orphan policy "
-            f"file(s) — every policy must be linked from a skill, rule, "
-            f"or sibling policy.",
-            file=sys.stderr,
-        )
-        for o in orphans:
-            print(
-                f"  - {o.relative_to(REPO)}",
-                file=sys.stderr,
-            )
-        return 1
-
-    emit(
-        f"media-policy-linkage: {len(policies)} policy file(s) — all "
-        f"linked."
-    )
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/lint_model_tier_coverage.py

@@ -1,73 +0,0 @@
-#!/usr/bin/env python3
-"""Fail when a skill or command lacks a `model_tier` value.
-
-Phase 5 coverage gate of `road-to-model-capability-tiers.md` (ADR-035):
-every skill and command MUST declare an explicit `model_tier`
-(`opus | sonnet | gpt`) or `inherit`. An untagged artefact is an error — it
-leaves the per-skill model-switch surface with a silent gap. Run
-`python3 scripts/backfill_model_tier.py` to seed missing tags.
-
-The enum itself is validated by `scripts/validate_frontmatter.py`; this gate
-only enforces *presence* (an explicit decision was made for every artefact).
-
-CLI: python3 scripts/lint_model_tier_coverage.py [--quiet]
-Exit: 0 clean · 1 at least one untagged skill/command.
-"""
-from __future__ import annotations
-
-import argparse
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-from validate_frontmatter import parse_frontmatter  # noqa: E402
-from _lib.agent_src import artefact_roots, iter_commands  # noqa: E402
-
-ROOT = Path(__file__).resolve().parents[2]
-
-
-def _targets():
-    for root in artefact_roots():
-        sdir = root / "skills"
-        if sdir.exists():
-            for p in sorted(sdir.rglob("SKILL.md")):
-                yield "skill", p
-    # Commands live under packages/*/commands/ AND the 6.0.0-D
-    # src/domains/<pack>/<subpath>/command.md homes; iter_commands() covers both.
-    for p in iter_commands():
-        if p.name != "AGENTS.md":
-            yield "command", p
-
-
-def main(argv=None) -> int:
-    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    ap.add_argument("--quiet", action="store_true")
-    args = ap.parse_args(argv)
-
-    total = 0
-    missing = []
-    for kind, path in _targets():
-        total += 1
-        fm, _ = parse_frontmatter(path.read_text(encoding="utf-8"))
-        if not isinstance(fm, dict) or not fm.get("model_tier"):
-            missing.append((kind, path.relative_to(ROOT).as_posix()))
-
-    if missing:
-        for kind, rel in missing[:40]:
-            print(f"❌  [{kind}] {rel}: missing `model_tier` "
-                  f"(set lite/medium/high or inherit)")
-        if len(missing) > 40:
-            print(f"  ... and {len(missing) - 40} more")
-        print(
-            f"\n== model_tier coverage: {len(missing)}/{total} artefact(s) "
-            "untagged. Run `python3 scripts/backfill_model_tier.py`. ==",
-            file=sys.stderr,
-        )
-        return 1
-    if not args.quiet:
-        print(f"✅  lint-model-tier-coverage: {total} artefact(s) tagged.")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/lint_namespace.py

@@ -1,135 +0,0 @@
-#!/usr/bin/env python3
-"""Namespace linter. Enforces `<stem>-<intent>` kebab-case + reserved
-names list across skills / rules / commands / personas.
-
-Contract: docs/contracts/namespace.md.
-Wired into: `task lint-skills` (taskfiles/ci-fast.yml).
-"""
-from __future__ import annotations
-import argparse, re, sys
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent.parent
-SRC = ROOT / ".agent-src.uncondensed"
-
-# Source-of-truth regex; mirrored in docs/contracts/namespace.md § 1.
-NAME_RE = re.compile(r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$")
-
-MIN_LEN = 2
-MIN_LEN_SKILL = 3
-MAX_LEN = 64
-
-RESERVED = {"pattern", "claude-memories", "default", "index", "router"}
-
-# Filenames that are documentation, not artefacts.
-NON_ARTEFACTS = {"README.md", "INDEX.md"}
-
-# (kind, root, glob, depth, sub_verb) — depth tells us how to extract
-# the name. depth=0 → file stem; depth=1 → first directory under root.
-# sub_verb=True → the path is a `<group>/<verb>.md` form; reserved-name
-# check is skipped because the verb is namespaced under the group.
-TARGETS = [
-    ("skill",    SRC / "skills",    "*/SKILL.md", 1, False),
-    ("rule",     SRC / "rules",     "*.md",       0, False),
-    ("command",  SRC / "commands",  "*.md",       0, False),
-    ("command",  SRC / "commands",  "*/*.md",     0, True),
-    ("persona",  SRC / "personas",  "*.md",       0, False),
-]
-
-
-def _name_for(path: Path, root: Path, depth: int) -> str:
-    if depth == 0:
-        return path.stem
-    rel = path.relative_to(root)
-    return rel.parts[0]
-
-
-def _shape_errors(name: str, *, sub_verb: bool = False,
-                  kind: str = "command") -> list[str]:
-    errs = []
-    floor = MIN_LEN_SKILL if kind == "skill" else MIN_LEN
-    if not (floor <= len(name) <= MAX_LEN):
-        errs.append(f"length — {len(name)} chars (must be {floor}–{MAX_LEN})")
-    if not NAME_RE.match(name):
-        errs.append("regex — must match ^[a-z][a-z0-9]*(-[a-z0-9]+)*$")
-    if name in RESERVED and not sub_verb:
-        errs.append(f"reserved — '{name}' in reserved-names list")
-    return errs
-
-
-def _skill_name_field(path: Path) -> str | None:
-    """Read `name:` from skill frontmatter. None on missing / unparseable."""
-    try:
-        text = path.read_text(encoding="utf-8")
-    except Exception:
-        return None
-    if not text.startswith("---"):
-        return None
-    end = text.find("\n---", 3)
-    if end < 0:
-        return None
-    fm = text[3:end]
-    for line in fm.splitlines():
-        m = re.match(r"^name:\s*['\"]?([^'\"]+)['\"]?\s*$", line.strip())
-        if m:
-            return m.group(1).strip()
-    return None
-
-
-def scan() -> tuple[int, int]:
-    issues = 0
-    checked = 0
-    seen: set[tuple[str, str]] = set()
-    for kind, root, glob, depth, sub_verb in TARGETS:
-        if not root.is_dir():
-            continue
-        for path in sorted(root.glob(glob)):
-            if path.name in NON_ARTEFACTS:
-                continue
-            name = _name_for(path, root, depth)
-            key = (kind, str(path.relative_to(root)))
-            if key in seen:
-                continue
-            seen.add(key)
-            checked += 1
-            errs = _shape_errors(name, sub_verb=sub_verb, kind=kind)
-            if kind == "skill":
-                fm_name = _skill_name_field(path)
-                if fm_name and fm_name != name:
-                    errs.append(f"skill — frontmatter name='{fm_name}' != dir '{name}'")
-            for e in errs:
-                rel = path.relative_to(ROOT)
-                print(f"❌ {rel}: {e}", file=sys.stderr)
-                issues += 1
-    return checked, issues
-
-
-def check_single(name: str) -> int:
-    errs = _shape_errors(name)
-    if not errs:
-        print(f"✅ '{name}' is a valid artefact name")
-        return 0
-    for e in errs:
-        print(f"❌ '{name}': {e}", file=sys.stderr)
-    return 1
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__)
-    ap.add_argument("--name", help="Check a single candidate name and exit.")
-    ap.add_argument("--quiet", action="store_true",
-                    help="Suppress the summary line on success.")
-    args = ap.parse_args()
-    if args.name:
-        return check_single(args.name)
-    checked, issues = scan()
-    if issues:
-        print(f"BASELINE: {issues} issue(s) across {checked} name(s)", file=sys.stderr)
-        return 1
-    if not args.quiet:
-        print(f"BASELINE: 0 issues · {checked} name(s) checked")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())