check-family-plugins.py

#!/usr/bin/env python3
# SPDX-License-Identifier: Apache-2.0
# https://www.apache.org/licenses/LICENSE-2.0
"""Validate the marketplace plugins against the skills' `family:` frontmatter —
the source of truth.

Checks that every plugin is properly defined:

- every ecosystem manifest that declares the framework version
  (`.claude-plugin/plugin.json`, the Agent Plugins 1.0 `plugin.json`,
  `.codex-plugin/plugin.json`, `gemini-extension.json`, `apm.yml`) mirrors
  `pyproject.toml`'s `project.version` verbatim — including a `.devN` suffix;
- `magpie-setup`'s manifest wires the `hooks/check-upgrade.sh` SessionStart
  hook (which must exist) -- it rides on the one plugin the recommended floor
  always installs;
- the root `plugin.json` conforms to Agent Plugins 1.0 — the pinned `$schema`,
  the name pattern, the closed ten-field set (so a Claude-only component path
  never leaks in), and the same shared metadata as the Claude manifest;
- every `.claude-plugin/marketplace.json` entry resolves to a matching,
  uniquely-named `plugin.json` and carries the root manifest's version;
- the Codex and Copilot catalogs (`.agents/plugins/marketplace.json`,
  `marketplace.json`) list every family plugin and no all-in-one, with
  `magpie-setup` installed by default and the rest opt-in;
- for every family declared in a skill's `family:` frontmatter there is a
  `plugins/magpie-<family>/` plugin whose manifest is well-formed, inherits the
  root manifest's shared metadata (version, author, homepage, repository,
  license), and whose `skills/` directory contains exactly that family's skills
  as single-hop symlinks into the shared `skills/<skill>` tree;
- the skill → family map generated into the pre-flight checker
  (`setup_preflight/families.py`, which decides whether a family's first-run
  welcome guide applies) matches the frontmatter and the `skills/` mirror;
- every *substrate* plugin (`SUBSTRATE_PLUGINS` — a framework tool published as
  its own plugin rather than a family of skills) has a well-formed manifest that
  inherits the same shared metadata, declares the exact hook wiring the framework
  expects, and reaches its tool through a symlink that actually resolves.

Drift — a new skill, a changed family, a stale symlink, a malformed or
mis-named manifest, a dangling marketplace entry, a family manifest left behind
at the previous release's version — fails the check.

Run with `--fix` to propagate the version from `pyproject.toml` and regenerate
the family plugins + symlinks + marketplace entries from the frontmatter. A
release bump therefore has one edit point: `pyproject.toml`, then `--fix`.
"""

from __future__ import annotations

import argparse
import json
import re
import shutil
import subprocess
import sys
import tomllib
from pathlib import Path

SKILLS = Path("skills")
PLUGINS = Path("plugins")
MARKETPLACE = Path(".claude-plugin/marketplace.json")
ROOT_MANIFEST = Path(".claude-plugin/plugin.json")  # version + shared metadata anchor
UPGRADE_HOOK = Path("plugins/magpie-setup/hooks/check-upgrade.sh")  # magpie-setup SessionStart
# The wiring that fires it. It rides on magpie-setup because that plugin is the
# recommended floor -- always installed -- and is the one that performs the
# upgrade. Claude Code merges hooks from every enabled plugin, so exactly one
# owner keeps it firing once per session however many families are enabled.
SETUP_HOOKS = {
    "SessionStart": [
        {
            "matcher": "startup",
            "hooks": [
                {
                    "type": "command",
                    "command": "${CLAUDE_PLUGIN_ROOT}/hooks/check-upgrade.sh",
                    "timeout": 10,
                }
            ],
        }
    ]
}
# Every skill's pre-flight runs `setup_preflight`, and `setup config` installs it
# from the plugin on a marketplace install, so the package has to be inside
# magpie-setup's root: a symlink out to `tools/` would put magpie-setup, which the
# Codex and Copilot catalogs list, in breach of Agent Plugins 1.0 §4.1. The
# `tools/setup-preflight` workspace member reaches it through the inward link.
SETUP_PREFLIGHT_PACKAGE = Path("plugins/magpie-setup/skills/setup/setup_preflight")
SETUP_PREFLIGHT_MIRROR = Path("tools/setup-preflight/src/setup_preflight")
SETUP_PREFLIGHT_MIRROR_TARGET = Path("../../../plugins/magpie-setup/skills/setup/setup_preflight")
MIRROR_TARGET = "../plugins/{plugin}/skills/{alias}"  # relative to skills/

# A family plugin advertises each skill under its plugin *directory* name, and
# that name is where the family prefix comes off: `magpie-security` +
# `security-issue-triage` would otherwise be invoked as
# `/magpie-security:security-issue-triage`, saying "security" twice. The flat
# `skills/<name>` mirror keeps the prefix. The alias is also the skill's
# frontmatter `name:` (the Agent Skills spec requires `name:` to match the
# directory, and Claude Code and Codex invoke plugin skills by it).
#
# Skills whose mechanical alias is worse than the name it replaces.
ALIAS_OVERRIDES = {
    # Stripping "setup-" leaves nothing; `/magpie-setup:setup` is the install skill.
    "setup": "setup",
    # "to-committer" does not read as the name of anything.
    "contributor-to-committer": "contributor-to-committer",
    # The alias is also the skill's frontmatter `name:`, and Gemini CLI keeps
    # skill names in one flat registry, so aliases must be unique across every
    # family, not just within one. `magpie-issue` keeps `triage` / `stale-sweep`.
    "pr-management-triage": "pr-triage",
    "pr-stale-sweep": "pr-stale-sweep",
}
TOOL_SYMLINK_TARGET = "../../../tools/{tool}"  # relative to plugins/magpie-<p>/tools/
# `setup config` scaffolds adopter configuration from these templates, so on a
# marketplace install they have to ship inside magpie-setup's root; the Codex
# and Copilot catalogs list magpie-setup, and Agent Plugins 1.0 §4.1 forbids a
# link out of it. `projects/_template` keeps resolving through the inward link.
SETUP_TEMPLATES = Path("plugins/magpie-setup/templates")
SETUP_TEMPLATES_MIRROR = Path("projects/_template")
SETUP_TEMPLATES_MIRROR_TARGET = Path("../plugins/magpie-setup/templates")

# The vendor-neutral Agent Plugins 1.0 manifest for the repository itself.
# It lives at the repo root (the spec permits no alternative location) and is
# read by VS Code / Copilot, which auto-detect the format from the root manifest
# and treat the `$schema` value as the AP1 marker. Its schema is *closed*: only
# the ten fields below are permitted, so component paths (`skills`, `hooks`)
# must NOT appear — AP1 fixes skills at `skills/` and defines no hook component.
AP1_MANIFEST = Path("plugin.json")
AP1_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"
AP1_FIELDS = frozenset(
    {
        "$schema",
        "name",
        "version",
        "description",
        "author",
        "homepage",
        "repository",
        "license",
        "keywords",
        "extensions",
    }
)
AP1_AUTHOR_FIELDS = frozenset({"name", "email", "url"})

# The non-Claude catalogs list the ten family plugins. They could not, until
# each family owned its skills as real directories: a plugin whose skills were
# symlinks out to the flat tree installs on Codex with *zero* skills — it does
# not fail, it silently ships nothing, which was measured, not inferred.
# Reversing the direction fixed it without vendoring anything (PRINCIPLES §13):
# the flat `skills/<name>` tree is now the mirror, pointing inward.
# The all-in-one plugin is gone; installing everything was never the advice.
CODEX_SUBSTRATES = frozenset({"magpie-agent-guard", "magpie-vetted-ops"})
CODEX_CATALOG = Path(".agents/plugins/marketplace.json")  # Codex CLI repo marketplace
CLIENT_CATALOGS = (
    CODEX_CATALOG,
    Path("marketplace.json"),  # GitHub Copilot / VS Code
)

# Codex's per-plugin `policy` block. Both enums are closed and SCREAMING_SNAKE,
# and Codex parses the catalogue strictly: an unknown variant is not a
# mis-labelled plugin but a rejected *file* — `codex plugin marketplace add`
# fails with `unknown variant`, so nothing in the marketplace installs at all.
# This catalogue shipped with the invented values `manual` / `none` for a
# release, because every check here read names and versions and none read the
# policy values. Verified against codex 0.154.0.
#
# `installation` decides whether adding the marketplace also installs the
# plugin. Every family stays AVAILABLE — a machine that adds the marketplace
# gets the catalogue, not ten families' worth of always-on skills. The one
# exception is `magpie-setup`, which is INSTALLED_BY_DEFAULT: it is the floor
# the framework recommends to everyone, so arriving already installed is the
# point. `authentication` is optional and names *when* a
# plugin asks the user to authenticate; Magpie asks for no credential of its
# own, so it is absent rather than set to a "no auth" value, which the enum
# has no way to spell.
CODEX_POLICY_ENUMS = {
    "installation": frozenset({"NOT_AVAILABLE", "AVAILABLE", "INSTALLED_BY_DEFAULT"}),
    "authentication": frozenset({"ON_INSTALL", "ON_USE"}),
}
CODEX_REQUIRED_INSTALLATION = "AVAILABLE"
# `name`: 1–64 chars, lowercase alphanumeric plus `-`/`.`, no `--`/`..`,
# alphanumeric at both ends.
AP1_NAME_RE = re.compile(r"^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$")

# `pyproject.toml` is the single authority for the framework version — it is what
# the post-release `chore: bump version` commit edits. Every ecosystem manifest
# mirrors that string verbatim (including a `.devN` suffix), so `release-prepare`
# can bump them all with one literal search/replace. Dev versions are never
# published to a marketplace, so a PEP 440 suffix never reaches a consumer.
PYPROJECT = Path("pyproject.toml")
ECOSYSTEM_MANIFESTS = (
    ROOT_MANIFEST,
    AP1_MANIFEST,
    Path(".codex-plugin/plugin.json"),
    Path("gemini-extension.json"),
    Path("apm.yml"),
)
APM_VERSION_RE = re.compile(r"^(version:[ \t]*)(\S+)[ \t]*$", re.M)
# Substituted rather than re-serialised: these manifests are hand-authored, and a
# json.dumps() round-trip would reformat them (escaping em-dashes, expanding
# inline objects) far beyond the one string being bumped.
JSON_VERSION_RE = re.compile(r'("version"[ \t]*:[ \t]*")[^"]*(")')

# Metadata the per-family plugins and the marketplace entries inherit verbatim
# from the root manifest, so a release bump has exactly one edit point.
# `version` + `author` are what `claude plugin validate --strict` warns about
# when absent; the rest carry attribution into a marketplace listing.
INHERITED = ("version", "author", "homepage", "repository", "license")

# Per-family descriptions used when (re)generating manifests. Keep in sync with
# the family README; `check` does not enforce these (only structure/symlinks).
DESC = {
    "security": "security-issue handling lifecycle — import through CVE publication, triage, sync, dedup, invalidate. Maintainer-only.",
    "release-management": "ASF release lifecycle: plan, RC cut/sign, vote, tally, promote, announce, archive, audit.",
    "setup": "framework install/maintenance: install (adopt), upgrade, verify, override, status, secure-agent setup, shared-config sync.",
    "pr-management": "PR-queue management: triage, stats, deep code review, stack review, quick-merge, stale-sweep, reviewer routing, pre-first-PR checks.",
    "issue": "issue lifecycle: triage, reproduction, fix drafting, reassess, stale-sweep, dedup, backlog stats.",
    "repo-health": "read-only repo-health audits: runner labels, workflow security, dependency/license/NOTICE, flaky tests, audit-finding fixes.",
    "contributor-growth": "path-to-committer: activity sweeps, nominations, sentiment, readiness, committer/post-vote onboarding.",
    "utilities": "framework meta-skills: write-skill, optimize-skill, skill-reconciler, list-skills.",
    "mentoring": "newcomer mentoring: welcome, newcomer-issue explanations, good-first-issue authoring + sweep.",
    "pairing": "pair a change with a structured self-review or a multi-agent adversarial review.",
}


# Substrate plugins are *not* derived from any skill's `family:` frontmatter:
# they publish a framework tool as its own plugin so the tool runs from the
# installed plugin root, with nothing copied into a consumer repository. Each
# declares the hook wiring the framework expects and reaches its tool through a
# narrow symlink (the whole `tools/` tree is deliberately not exposed).
#
# A substrate plugin is a plugin of its own rather than a hook on some shared
# plugin because Claude Code merges hooks from *every* enabled plugin:
# wiring the guard into each family plugin would run it once per enabled family
# on every single Bash call. One dedicated owner runs it exactly once, whatever
# else is installed.
AGENT_GUARD_ENGINE = "tools/agent-guard/src/agent_guard/__init__.py"
# The dispatcher's entry point. `vetted-ops` publishes no hook — it is invoked
# from a skill's Bash call — but it is a substrate plugin for the *other* half of
# the reason: the tool must live where the agent cannot rewrite it. An agent that
# can edit `ops.py` has defeated the whole design, so the catalogue has to sit in
# the installed plugin tree rather than in a consumer repository.
VETTED_OPS_ENTRY = "tools/vetted-ops/src/vetted_ops/cli.py"
VETTED_OPS_LINK_HOOK = "tools/vetted-ops/hooks/link-stable-path.sh"
# Adversarial review runs other models' CLIs outside the sandbox (they need
# network and their own credentials), so like vetted-ops it has to run from the
# installed plugin tree, where the agent calling it cannot rewrite it.
ADVERSARIAL_REVIEW_ENTRY = "tools/adversarial-review/src/adversarial_review/cli.py"
ADVERSARIAL_REVIEW_LINK_HOOK = "tools/adversarial-review/hooks/link-stable-path.sh"
SUBSTRATE_PLUGINS: dict[str, dict] = {
    "magpie-agent-guard": {
        "description": (
            "Apache Magpie \u2014 deterministic pre-execution command guard: a PreToolUse hook "
            "that denies shell commands which would break a hard framework rule. Runs from "
            "the installed plugin, so no repository or worktree needs a local copy."
        ),
        # Materialize the runtime package inside the plugin. Marketplace clients
        # may drop symlinks whose targets escape the plugin root.
        "copies": {
            "tools/agent-guard/src/agent_guard": "tools/agent-guard/src/agent_guard",
        },
        "links": {},
        # Files that must exist inside the generated plugin for the hook to fire.
        "must_resolve": (AGENT_GUARD_ENGINE,),
        "hook_config": {
            "description": "Apache Magpie agent guard",
            "hooks": {
                "PreToolUse": [
                    {
                        "matcher": "Bash",
                        "hooks": [
                            {
                                "type": "command",
                                "command": (
                                    f'python3 "${{GROK_PLUGIN_ROOT:-${{CLAUDE_PLUGIN_ROOT}}}}/'
                                    f'{AGENT_GUARD_ENGINE}"'
                                ),
                                "timeout": 30,
                            }
                        ],
                    }
                ]
            },
        },
    },
    "magpie-vetted-ops": {
        "description": (
            "Apache Magpie \u2014 vetted-ops: a dispatcher for fixed, policy-scoped forge "
            "operations, so a session needs one allowlist entry instead of a dozen wildcard "
            "`ask` rules. Runs from the installed plugin, which is what keeps the operation "
            "catalogue out of reach of the agent that calls it."
        ),
        "links": {},
        "copies": {
            "tools/vetted-ops/src/vetted_ops": "tools/vetted-ops/src/vetted_ops",
            "tools/vetted-ops/hooks": "tools/vetted-ops/hooks",
            "tools/vetted-ops/pyproject.toml": "tools/vetted-ops/pyproject.toml",
            "tools/vetted-ops/README.md": "tools/vetted-ops/README.md",
            # The security-tracker backends vetted-ops runs beside itself
            # (tracker_backends.backend_dir): real copies, not links, so a
            # self-contained install (Codex, a plugin cache) carries them.
            "tools/jira/src/jira_bridge": "tools/jira/src/jira_bridge",
            "tools/jira/pyproject.toml": "tools/jira/pyproject.toml",
            "tools/jira/README.md": "tools/jira/README.md",
            "tools/local-tracker/src/magpie_local_tracker": "tools/local-tracker/src/magpie_local_tracker",
            "tools/local-tracker/pyproject.toml": "tools/local-tracker/pyproject.toml",
            "tools/local-tracker/README.md": "tools/local-tracker/README.md",
        },
        # The entry point skills invoke, and the hook that keeps the fixed path
        # permission rules name (~/.claude/magpie/vetted-ops) on this version.
        "must_resolve": (VETTED_OPS_ENTRY, VETTED_OPS_LINK_HOOK),
        "hook_config": {
            "description": "Apache Magpie vetted operations",
            "hooks": {
                "SessionStart": [
                    {
                        "hooks": [
                            {
                                "type": "command",
                                "command": f'bash "${{CLAUDE_PLUGIN_ROOT}}/{VETTED_OPS_LINK_HOOK}"',
                                "timeout": 10,
                            }
                        ],
                    }
                ]
            },
        },
    },
    "magpie-adversarial-review": {
        "description": (
            "Apache Magpie \u2014 adversarial review: runs other models' CLIs (Codex, Copilot, "
            "Gemini, Claude) read-only over a change before its PR is created, and merges their "
            "findings. Runs from the installed plugin, so no repository needs a copy."
        ),
        # The Claude Code command is a generated file in the tool (pinned there by a
        # test against the generator), published at the plugin's `commands/`.
        "links": {
            "tools/adversarial-review": "adversarial-review",
            "commands/adversarial-review.md": "adversarial-review/commands/adversarial-review.md",
        },
        # The entry point, the published command, and the hook that keeps the
        # fixed path the sandbox exclusion names (~/.claude/magpie/adversarial-review)
        # on this version.
        "must_resolve": (
            ADVERSARIAL_REVIEW_ENTRY,
            "commands/adversarial-review.md",
            ADVERSARIAL_REVIEW_LINK_HOOK,
        ),
        "hooks": {
            "SessionStart": [
                {
                    "hooks": [
                        {
                            "type": "command",
                            "command": f'bash "${{CLAUDE_PLUGIN_ROOT}}/{ADVERSARIAL_REVIEW_LINK_HOOK}"',
                            "timeout": 10,
                        }
                    ],
                }
            ]
        },
    },
}


def load_json(path: Path):
    try:
        return json.loads(path.read_text(encoding="utf-8")), None
    except (OSError, ValueError) as exc:
        return None, f"{path}: cannot read/parse ({exc})"


def validate_manifest(path: Path, expected_name: str, inherited: dict | None = None) -> list[str]:
    """A plugin.json must exist, be valid JSON, name itself correctly, and
    declare its skills + a description. Per-family manifests additionally carry
    the root manifest's shared metadata (`inherited`) verbatim."""
    if not path.is_file():
        return [f"{path}: missing plugin manifest"]
    data, err = load_json(path)
    if err:
        return [err]
    errors: list[str] = []
    if data.get("name") != expected_name:
        errors.append(f"{path}: name is {data.get('name')!r}, expected {expected_name!r}")
    if data.get("skills") != "./skills":
        errors.append(f"{path}: 'skills' is {data.get('skills')!r}, expected './skills'")
    if not str(data.get("description", "")).strip():
        errors.append(f"{path}: missing/empty 'description'")
    for key, want in (inherited or {}).items():
        if data.get(key) != want:
            errors.append(
                f"{path}: {key!r} is {data.get(key)!r}, expected {want!r} (inherited from {ROOT_MANIFEST})"
            )
    return errors


def substrate_manifest(name: str, shared: dict) -> dict:
    """The manifest `--fix` writes for a substrate plugin — the single source of
    truth `check` compares the on-disk file against."""
    spec = SUBSTRATE_PLUGINS[name]
    manifest = {"name": name, "description": spec["description"], **shared}
    # Some substrate plugins still publish inline manifest hooks. Others, such
    # as magpie-agent-guard, use hook_config so Claude and Grok share a single
    # hooks/hooks.json registration source.
    if "hooks" in spec:
        manifest["hooks"] = spec["hooks"]
    return manifest


def check_setup_templates() -> list[str]:
    """magpie-setup ships the project templates as real files, and
    `projects/_template` mirrors them rather than holding a second copy."""
    errors: list[str] = []
    index = SETUP_TEMPLATES / "project.md"
    if SETUP_TEMPLATES.is_symlink() or not index.is_file():
        errors.append(
            f"{SETUP_TEMPLATES}: must be a real directory holding {index.name} — "
            f"a marketplace install of magpie-setup would ship no templates to scaffold from"
        )
    if not SETUP_TEMPLATES_MIRROR.is_symlink():
        errors.append(f"{SETUP_TEMPLATES_MIRROR}: expected a symlink to {SETUP_TEMPLATES_MIRROR_TARGET}")
    elif SETUP_TEMPLATES_MIRROR.readlink() != SETUP_TEMPLATES_MIRROR_TARGET:
        errors.append(
            f"{SETUP_TEMPLATES_MIRROR} -> {SETUP_TEMPLATES_MIRROR.readlink()} "
            f"(expected {SETUP_TEMPLATES_MIRROR_TARGET})"
        )
    return errors


def packaged_file_bytes(src: Path, copies: dict[str, str]) -> bytes:
    """Keep shipped links local and point framework links at their public source."""
    if src.suffix != ".md":
        return src.read_bytes()

    def rebase(match: re.Match[str]) -> str:
        target, title = match.group(1), match.group(2) or ""
        if ":" in target or target.startswith(("#", "/", "<")):
            return match.group(0)
        path, sep, fragment = target.partition("#")
        resolved = (src.parent / path).resolve()
        for src_rel in copies.values():
            source = Path(src_rel).resolve()
            if resolved == source or (source.is_dir() and resolved.is_relative_to(source)):
                # Every copied tree preserves its layout beneath the tool root.
                # Current runtime README links are relative to that same root.
                return match.group(0)
        try:
            relative = resolved.relative_to(Path.cwd().resolve()).as_posix()
        except ValueError:
            # An outside-repository link has no public framework equivalent.
            # Preserve it for the link checker to report against the source.
            return match.group(0)
        return f"](https://github.com/apache/magpie/blob/main/{relative}{sep}{fragment}{title})"

    output: list[str] = []
    fence: tuple[str, int] | None = None
    for line in src.read_text(encoding="utf-8").splitlines(keepends=True):
        marker = re.match(r"^ {0,3}(`{3,}|~{3,})", line)
        if marker:
            token = marker.group(1)
            if fence is None:
                fence = (token[0], len(token))
            elif token[0] == fence[0] and len(token) >= fence[1]:
                fence = None
            output.append(line)
        elif fence is not None:
            output.append(line)
        else:
            output.append(re.sub(r"\]\(([^)\s]+)(\s+\"[^\"]*\"|\s+'[^']*')?\)", rebase, line))
    return "".join(output).encode()


def check_substrate(name: str, shared: dict) -> list[str]:
    """A substrate plugin's manifest, hook wiring, and tool symlinks.

    Unlike a family plugin it declares no `skills`, so it gets its own checks
    rather than `validate_manifest`'s.
    """
    spec = SUBSTRATE_PLUGINS[name]
    pdir = PLUGINS / name
    path = pdir / ".claude-plugin" / "plugin.json"
    if not path.is_file():
        return [f"{path}: missing plugin manifest"]
    data, err = load_json(path)
    if err:
        return [err]

    errors: list[str] = []
    if data.get("name") != name:
        errors.append(f"{path}: name is {data.get('name')!r}, expected {name!r}")
    if not str(data.get("description", "")).strip():
        errors.append(f"{path}: missing/empty 'description'")
    if "skills" in data:
        errors.append(f"{path}: substrate plugins ship a tool, not skills — drop 'skills'")
    hook_config = spec.get("hook_config")
    if hook_config is not None and "hooks" in data:
        errors.append(f"{path}: substrate hook wiring belongs in hooks/hooks.json, not the manifest")
    elif hook_config is None and data.get("hooks") != spec.get("hooks"):
        errors.append(
            f"{path}: 'hooks' does not match the wiring the framework expects (regenerate with --fix)"
        )

    hook_path = pdir / "hooks" / "hooks.json"
    if hook_config is not None:
        if not hook_path.is_file():
            errors.append(f"{hook_path}: missing substrate hook configuration")
        else:
            hook_data, hook_err = load_json(hook_path)
            if hook_err:
                errors.append(hook_err)
            elif hook_data != hook_config:
                errors.append(
                    f"{hook_path}: hook wiring does not match the framework expectation "
                    "(regenerate with --fix)"
                )
    for key, want in (shared or {}).items():
        if data.get(key) != want:
            errors.append(
                f"{path}: {key!r} is {data.get(key)!r}, expected {want!r} (inherited from {ROOT_MANIFEST})"
            )

    for link_path, tool in spec["links"].items():
        link = pdir / link_path
        want = Path(TOOL_SYMLINK_TARGET.format(tool=tool))
        if not link.is_symlink():
            errors.append(f"{name}: {link} is missing or not a symlink (expected -> {want})")
        elif link.readlink() != want:
            errors.append(f"{name}: {link} -> {link.readlink()} (expected {want})")

    for dest_rel, src_rel in spec.get("copies", {}).items():
        dest = pdir / dest_rel
        src = Path(src_rel)
        if src.is_file():
            if not dest.is_file() or dest.read_bytes() != packaged_file_bytes(src, spec.get("copies", {})):
                errors.append(f"{name}: copied runtime file {dest} is out of sync (regenerate with --fix)")
            continue
        if not dest.is_dir():
            errors.append(f"{name}: {dest} is missing copied runtime tree")
        elif not src.is_dir():
            errors.append(f"{name}: source runtime tree {src} is missing")
        else:
            src_files = sorted(
                path.relative_to(src)
                for path in src.rglob("*")
                if path.is_file() and "__pycache__" not in path.parts
            )
            dest_files = sorted(
                path.relative_to(dest)
                for path in dest.rglob("*")
                if path.is_file() and "__pycache__" not in path.parts
            )
            if dest_files != src_files:
                errors.append(f"{name}: copied runtime tree {dest} is out of sync (regenerate with --fix)")
            else:
                for rel in src_files:
                    if (dest / rel).read_bytes() != (src / rel).read_bytes():
                        errors.append(
                            f"{name}: copied runtime file {dest / rel} is out of sync (regenerate with --fix)"
                        )

    # A manifest and its packaged runtime can both look right while the hook is dead if
    # the file the command names is not reachable from the plugin root.
    for rel in spec["must_resolve"]:
        if not (pdir / rel).is_file():
            consequence = (
                "the hook command names it, so the guard cannot execute"
                if "hook_config" in spec
                else "the tool's entry point names it, so every call would fail to start"
            )
            errors.append(f"{name}: {pdir / rel} does not resolve — {consequence}")
    return errors


def write_substrate(name: str, shared: dict) -> None:
    """(Re)generate a substrate plugin dir: manifest + tool symlinks."""
    spec = SUBSTRATE_PLUGINS[name]
    pdir = PLUGINS / name
    (pdir / ".claude-plugin").mkdir(parents=True, exist_ok=True)
    for link_path, tool in spec["links"].items():
        link = pdir / link_path
        link.parent.mkdir(parents=True, exist_ok=True)
        want = TOOL_SYMLINK_TARGET.format(tool=tool)
        if link.is_symlink():
            if link.readlink() == Path(want):
                continue
            link.unlink()
        link.symlink_to(want)

    for dest_rel, src_rel in spec.get("copies", {}).items():
        dest_rel_path = Path(dest_rel)
        dest = pdir / dest_rel_path
        src = Path(src_rel)

        # A previous substrate layout may have exposed this destination through
        # a symlink whose target lives outside the plugin. Remove that ancestor
        # symlink itself before touching any descendant, otherwise rmtree()
        # would follow it and delete source files in the framework checkout.
        for depth in range(1, len(dest_rel_path.parts)):
            ancestor = pdir.joinpath(*dest_rel_path.parts[:depth])
            if ancestor.is_symlink():
                ancestor.unlink()
                break

        if dest.exists() or dest.is_symlink():
            if dest.is_symlink() or dest.is_file():
                dest.unlink()
            else:
                shutil.rmtree(dest)
        dest.parent.mkdir(parents=True, exist_ok=True)
        if src.is_file():
            dest.write_bytes(packaged_file_bytes(src, spec.get("copies", {})))
            continue
        shutil.copytree(
            src,
            dest,
            ignore=shutil.ignore_patterns(
                "__pycache__",
                "*.pyc",
                ".pytest_cache",
                ".ruff_cache",
                ".mypy_cache",
            ),
        )

    (pdir / ".claude-plugin" / "plugin.json").write_text(
        json.dumps(substrate_manifest(name, shared), indent=2) + "\n", encoding="utf-8"
    )
    if hook_config := spec.get("hook_config"):
        hook_dir = pdir / "hooks"
        hook_dir.mkdir(parents=True, exist_ok=True)
        (hook_dir / "hooks.json").write_text(json.dumps(hook_config, indent=2) + "\n", encoding="utf-8")


def pyproject_version() -> tuple[str | None, list[str]]:
    """The framework version — the single authority every manifest mirrors."""
    try:
        version = tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))["project"]["version"]
    except (OSError, ValueError, KeyError) as exc:
        return None, [f"{PYPROJECT}: cannot read project.version ({exc})"]
    return str(version), []


def manifest_version(path: Path) -> tuple[str | None, str | None]:
    """Read the version out of a manifest in whichever format it uses."""
    if path.suffix in (".yml", ".yaml"):
        try:
            m = APM_VERSION_RE.search(path.read_text(encoding="utf-8"))
        except OSError as exc:
            return None, f"{path}: cannot read ({exc})"
        return (m.group(2) if m else None), None
    data, err = load_json(path)
    if err:
        return None, err
    return data.get("version"), None


def write_manifest_version(path: Path, version: str) -> list[str]:
    """Rewrite a manifest's version in place, touching nothing else."""
    pattern = APM_VERSION_RE if path.suffix in (".yml", ".yaml") else JSON_VERSION_RE
    text = path.read_text(encoding="utf-8")
    new, n = pattern.subn(
        (rf"\g<1>{version}" if pattern is APM_VERSION_RE else rf"\g<1>{version}\g<2>"),
        text,
        count=1,
    )
    if n != 1:
        return [f"{path}: no 'version' declaration to rewrite"]
    path.write_text(new, encoding="utf-8")
    # The substitution is textual — confirm it produced the intended value.
    have, err = manifest_version(path)
    if err:
        return [err]
    if have != version:
        return [f"{path}: rewrite produced {have!r}, expected {version!r}"]
    return []


def check_ecosystem_versions(version: str) -> list[str]:
    """Every ecosystem manifest mirrors `pyproject.toml`'s version verbatim."""
    errors: list[str] = []
    for path in ECOSYSTEM_MANIFESTS:
        if not path.is_file():
            errors.append(f"{path}: missing (declares the framework version)")
            continue
        have, err = manifest_version(path)
        if err:
            errors.append(err)
        elif have != version:
            errors.append(f"{path}: version is {have!r}, expected {version!r} (from {PYPROJECT})")
    return errors


def validate_ap1_manifest(inherited: dict | None = None) -> list[str]:
    """The root `plugin.json` conforms to Agent Plugins 1.0.

    Enforced here rather than by a JSON-Schema dependency: the schema is small,
    closed, and the failure we actually care about is someone copying a
    Claude-only field (`skills`, `hooks`, `mcpServers`) into it, which AP1
    clients reject as a fatal manifest error rather than ignore.
    """
    if not AP1_MANIFEST.is_file():
        return [f"{AP1_MANIFEST}: missing (Agent Plugins 1.0 manifest)"]
    data, err = load_json(AP1_MANIFEST)
    if err:
        return [err]
    errors: list[str] = []

    if data.get("$schema") != AP1_SCHEMA:
        errors.append(
            f"{AP1_MANIFEST}: '$schema' is {data.get('$schema')!r}, expected {AP1_SCHEMA!r} "
            f"(without it, VS Code/Copilot fall back to the legacy format)"
        )
    name = data.get("name")
    if name != "magpie":
        errors.append(f"{AP1_MANIFEST}: name is {name!r}, expected 'magpie'")
    elif not AP1_NAME_RE.match(name):
        errors.append(f"{AP1_MANIFEST}: name {name!r} violates the AP1 name pattern")

    extra = sorted(set(data) - AP1_FIELDS)
    if extra:
        errors.append(
            f"{AP1_MANIFEST}: {', '.join(repr(k) for k in extra)} not permitted — "
            f"the AP1 manifest schema is closed to {len(AP1_FIELDS)} fields "
            f"(client-specific data belongs in 'extensions' or the client's own manifest)"
        )

    author = data.get("author")
    if author is not None:
        if not isinstance(author, dict):
            errors.append(f"{AP1_MANIFEST}: 'author' must be an object")
        else:
            bad = sorted(set(author) - AP1_AUTHOR_FIELDS)
            if bad:
                errors.append(
                    f"{AP1_MANIFEST}: author has {', '.join(repr(k) for k in bad)}; "
                    f"AP1 permits only {', '.join(sorted(AP1_AUTHOR_FIELDS))}"
                )

    # AP1 fixes the skills location; there is no manifest field to point
    # elsewhere, so the real `skills/` tree is what any AP1 client will load.
    if not SKILLS.is_dir():
        errors.append(f"{SKILLS}: missing — AP1 clients discover skills only here")

    for key, want in (inherited or {}).items():
        if data.get(key) != want:
            errors.append(
                f"{AP1_MANIFEST}: {key!r} is {data.get(key)!r}, expected {want!r} "
                f"(inherited from {ROOT_MANIFEST})"
            )
    return errors


def check_client_catalogs() -> list[str]:
    """The Codex and Copilot catalogs list every family plugin, and no all-in-one."""
    errors: list[str] = []
    for path in CLIENT_CATALOGS:
        if not path.is_file():
            errors.append(f"{path}: missing (client plugin catalog)")
            continue
        data, err = load_json(path)
        if err:
            errors.append(err)
            continue
        entries = data.get("plugins")
        if not isinstance(entries, list):
            errors.append(f"{path}: 'plugins' is missing or not a list")
            continue
        names = [e.get("name") for e in entries if isinstance(e, dict)]
        if "magpie" in names:
            errors.append(
                f"{path}: lists an all-in-one 'magpie' plugin. There is no all-in-one: "
                f"installing all ten families was never the advice, and the entry is what "
                f"forced every non-Claude client to take everything or nothing."
            )
        listed = {n for n in names if n}
        on_disk = {
            d.name
            for d in PLUGINS.glob("magpie-*")
            if d.is_dir() and d.name not in SUBSTRATE_PLUGINS and (d / "skills").is_dir()
        }
        if path == CODEX_CATALOG:
            on_disk |= CODEX_SUBSTRATES
        for fam in sorted(on_disk - listed):
            errors.append(f"{path}: missing family plugin entry '{fam}'")
        for extra in sorted(listed - on_disk - {"magpie"}):
            errors.append(f"{path}: lists '{extra}', which has no family plugin on disk")
        if path == CODEX_CATALOG:
            errors.extend(check_codex_policy(path, entries))
    return errors


def check_codex_policy(path: Path, entries: list) -> list[str]:
    """Codex `policy` values are closed enums; an unknown one rejects the file."""
    errors: list[str] = []
    for entry in entries:
        if not isinstance(entry, dict):
            continue
        name = entry.get("name", "?")
        policy = entry.get("policy")
        if policy is None:
            continue
        if not isinstance(policy, dict):
            errors.append(f"{path}: '{name}' has a 'policy' that is not an object")
            continue
        for field, allowed in CODEX_POLICY_ENUMS.items():
            if field not in policy:
                continue
            value = policy[field]
            if value not in allowed:
                errors.append(
                    f"{path}: '{name}' policy.{field} is {value!r} — Codex accepts only "
                    f"{', '.join(sorted(allowed))}. An unknown variant makes "
                    f"`codex plugin marketplace add` reject the whole catalogue"
                )
        if unknown := sorted(set(policy) - set(CODEX_POLICY_ENUMS)):
            errors.append(f"{path}: '{name}' policy has unknown field(s) {', '.join(unknown)}")
        # magpie-setup is the floor every adopter gets: it carries the
        # secure-isolation skills and the SessionStart upgrade check, so it
        # installs by default. Every other family is opt-in -- taking all ten
        # is the thing this framework argues against.
        installation = policy.get("installation")
        want = "INSTALLED_BY_DEFAULT" if name == "magpie-setup" else CODEX_REQUIRED_INSTALLATION
        if installation is not None and installation != want:
            errors.append(
                f"{path}: '{name}' policy.installation is {installation!r}, expected "
                f"{want!r}"
                + (
                    " — magpie-setup is always installed"
                    if name == "magpie-setup"
                    else " — every other family is opt-in, one problem at a time"
                )
            )
    return errors


def root_metadata() -> tuple[dict, list[str]]:
    """The subset of the root manifest that the family plugins inherit."""
    data, err = load_json(ROOT_MANIFEST)
    if err:
        return {}, [err]
    missing = [k for k in INHERITED if not data.get(k)]
    if missing:
        return {}, [f"{ROOT_MANIFEST}: missing {', '.join(repr(k) for k in missing)}"]
    return {k: data[k] for k in INHERITED}, []


def plugin_alias(skill: str, family: str) -> str:
    """The name a family plugin advertises ``skill`` under.

    Strips the longest leading family token the skill name repeats — the family
    itself (``pr-management-triage`` -> ``triage``) or its first segment
    (``release-vote-tally`` under ``release-management`` -> ``vote-tally``) —
    leaving the name alone when the remainder would be empty or when
    :data:`ALIAS_OVERRIDES` says the mechanical result reads badly.

    Aliases must be unique across every family, not only within one: the alias
    is also the skill's frontmatter ``name:``, and harnesses that keep skills in
    one flat registry (Gemini CLI) would otherwise collide them. ``check``
    enforces that; :data:`ALIAS_OVERRIDES` resolves a repeat.
    """
    if skill in ALIAS_OVERRIDES:
        return ALIAS_OVERRIDES[skill]
    for prefix in sorted({family, family.split("-")[0]}, key=len, reverse=True):
        if skill.startswith(prefix + "-") and skill[len(prefix) + 1 :]:
            return skill[len(prefix) + 1 :]
    return skill


def aliases_for(family: str, skills: set[str]) -> dict[str, str]:
    """``{alias: skill}`` for one family, rejecting a within-family collision."""
    out: dict[str, str] = {}
    for skill in sorted(skills):
        alias = plugin_alias(skill, family)
        if alias in out:
            raise SystemExit(
                f"alias collision in magpie-{family}: '{skill}' and '{out[alias]}' "
                f"both reduce to '{alias}' — add an ALIAS_OVERRIDES entry"
            )
        out[alias] = skill
    return out


def families_from_frontmatter() -> dict[str, set[str]]:
    fam: dict[str, set[str]] = {}
    for path in sorted(SKILLS.glob("*/SKILL.md")):
        m = re.search(r"^family:\s*(\S+)", path.read_text(encoding="utf-8"), re.M)
        if m:
            fam.setdefault(m.group(1), set()).add(path.parent.name)
    return fam


def check_setup_preflight_package() -> list[str]:
    """magpie-setup ships `setup_preflight` as real files, and the workspace
    member's `src/` mirrors them rather than holding a second copy."""
    errors: list[str] = []
    entry = SETUP_PREFLIGHT_PACKAGE / "__main__.py"
    if SETUP_PREFLIGHT_PACKAGE.is_symlink() or not entry.is_file():
        errors.append(
            f"{SETUP_PREFLIGHT_PACKAGE}: must be a real directory holding {entry.name} — "
            f"a marketplace install of magpie-setup would ship no pre-flight checker"
        )
    if not SETUP_PREFLIGHT_MIRROR.is_symlink():
        errors.append(f"{SETUP_PREFLIGHT_MIRROR}: expected a symlink to {SETUP_PREFLIGHT_MIRROR_TARGET}")
    elif SETUP_PREFLIGHT_MIRROR.readlink() != SETUP_PREFLIGHT_MIRROR_TARGET:
        errors.append(
            f"{SETUP_PREFLIGHT_MIRROR} -> {SETUP_PREFLIGHT_MIRROR.readlink()} "
            f"(expected {SETUP_PREFLIGHT_MIRROR_TARGET})"
        )
    return errors


def welcome_families(action: str) -> list[str]:
    """Run `setup_preflight.welcome` `check-constant` or `write-constant` here.

    The family map is a pure function of the frontmatter, so it is checked and
    regenerated with the rest of this script's frontmatter-derived output.
    A tree without the checker package (a test fixture) has nothing to check.
    """
    if not (SETUP_PREFLIGHT_PACKAGE / "welcome.py").is_file():
        return []
    result = subprocess.run(
        [sys.executable, "-m", "setup_preflight.welcome", action],
        capture_output=True,
        text=True,
        env={"PYTHONPATH": str(SETUP_PREFLIGHT_PACKAGE.parent), "PYTHONDONTWRITEBYTECODE": "1"},
        check=False,
    )
    if result.returncode == 0 or (action == "write-constant" and result.returncode == 1):
        return []
    detail = (result.stderr or result.stdout).strip()
    return [f"{SETUP_PREFLIGHT_PACKAGE}/families.py: {detail} (regenerate with --fix)"]


def check(fam: dict[str, set[str]]) -> list[str]:
    errors: list[str] = []

    market, err = load_json(MARKETPLACE)
    if err:
        return [err]
    entries = market.get("plugins", [])
    listed = {p.get("name") for p in entries}

    shared, meta_errs = root_metadata()
    errors += meta_errs

    # 0) Every ecosystem manifest mirrors pyproject.toml's version.
    version, verr = pyproject_version()
    errors += verr
    if version is not None:
        errors += check_ecosystem_versions(version)

    # 1) The root manifest conforms to AP1, no catalogue lists an all-in-one,
    #    and magpie-setup's SessionStart hook script is present + referenced.
    errors += validate_ap1_manifest(shared)
    errors += check_client_catalogs()
    if "magpie" in listed:
        errors.append(f"{MARKETPLACE}: lists an all-in-one 'magpie' plugin; there is no all-in-one")
    # Upgrade detection rides on magpie-setup, which the recommended floor always
    # installs and which is the skill that performs the upgrade. It lived on the
    # all-in-one until that plugin was removed.
    if not UPGRADE_HOOK.is_file():
        errors.append(f"{UPGRADE_HOOK}: missing (magpie-setup's SessionStart upgrade check)")
    setup_manifest = PLUGINS / "magpie-setup" / ".claude-plugin" / "plugin.json"
    setup_hooks_manifest = PLUGINS / "magpie-setup" / "hooks" / "hooks.json"
    setup_types = PLUGINS / "magpie-setup" / "hooks" / "types.d.ts"
    setup_data, _setup_err = load_json(setup_manifest)
    if setup_types.is_file() and setup_data is not None and setup_data.get("types") != "./hooks/types.d.ts":
        errors.append(f"{setup_manifest}: 'types' must declare './hooks/types.d.ts'")
    if setup_hooks_manifest.is_file():
        hooks_data, hooks_err = load_json(setup_hooks_manifest)
        if hooks_err:
            errors.append(f"{setup_hooks_manifest}: {hooks_err}")
        elif hooks_data is not None:
            if not isinstance(hooks_data, dict):
                errors.append(f"{setup_hooks_manifest}: expected a JSON object")
            else:
                if not isinstance(hooks_data.get("modules"), list) or not hooks_data.get("modules"):
                    errors.append(f"{setup_hooks_manifest}: 'modules' is missing or not a non-empty list")
                if "check-upgrade.sh" not in json.dumps(hooks_data.get("hooks", {})):
                    errors.append(
                        f"{setup_hooks_manifest}: SessionStart hook does not reference check-upgrade.sh"
                    )
        if setup_data is not None and "hooks" in setup_data:
            errors.append(
                f"{setup_manifest}: declares inline 'hooks' while {setup_hooks_manifest} is present; "
                "drop inline 'hooks' to avoid duplicate hooks collision in Claude Code"
            )
    else:
        if setup_data is not None and "check-upgrade.sh" not in json.dumps(setup_data.get("hooks", {})):
            errors.append(f"{setup_manifest}: SessionStart hook does not reference check-upgrade.sh")
    errors += check_setup_preflight_package()
    errors += welcome_families("check-constant")

    errors += check_setup_templates()

    # 2) Every marketplace entry resolves to a matching, uniquely-named manifest.
    seen: set[str] = set()
    for ent in entries:
        name = ent.get("name")
        source = ent.get("source")
        if not name or not source:
            errors.append(f"{MARKETPLACE}: entry missing 'name'/'source': {ent}")
            continue
        if name in seen:
            errors.append(f"{MARKETPLACE}: duplicate plugin entry '{name}'")
        seen.add(name)
        manifest = ROOT_MANIFEST if source == "." else Path(source) / ".claude-plugin" / "plugin.json"
        if not manifest.is_file():
            errors.append(f"{MARKETPLACE}: '{name}' source '{source}' has no {manifest}")
            continue
        data, jerr = load_json(manifest)
        if jerr is None and data.get("name") != name:
            errors.append(f"{MARKETPLACE}: '{name}' resolves to plugin.json named {data.get('name')!r}")
        if shared and ent.get("version") != shared["version"]:
            errors.append(
                f"{MARKETPLACE}: '{name}' version is {ent.get('version')!r}, "
                f"expected {shared['version']!r} (from {ROOT_MANIFEST})"
            )

    # 3) Per-family plugins: manifest well-formed + symlinks match the frontmatter.
    for family, skills in sorted(fam.items()):
        name = f"magpie-{family}"
        pdir = PLUGINS / name
        manifest_errs = validate_manifest(
            pdir / ".claude-plugin" / "plugin.json", name, inherited=shared or None
        )
        errors += manifest_errs
        if manifest_errs:
            continue
        if name not in listed:
            errors.append(f"{MARKETPLACE}: missing entry for '{name}'")

        sdir = pdir / "skills"
        # A family plugin OWNS its skills as real directories. Anything else
        # here is the pre-0.2 layout, where these were symlinks into the flat
        # tree — a shape Codex silently installs with zero skills.
        have: dict[str, Path] = {}
        for entry in sorted(sdir.iterdir()) if sdir.is_dir() else []:
            if entry.is_symlink():
                errors.append(
                    f"{name}: {entry} is a symlink; a family plugin must contain "
                    f"its skills as real directories"
                )
            elif entry.is_dir():
                have[entry.name] = entry
                if not (entry / "SKILL.md").is_file():
                    errors.append(f"{name}: {entry} has no SKILL.md")

        # Keyed on the advertised alias, not the flat name: the directory name
        # here is what the plugin invokes the skill as.
        want_links = aliases_for(family, skills)
        for alias in sorted(set(want_links) - set(have)):
            errors.append(
                f"{name}: missing skill directory '{alias}' for '{want_links[alias]}' (family={family})"
            )
        for alias in sorted(set(have) - set(want_links)):
            errors.append(f"{name}: stale skill directory '{alias}' — no family={family} skill claims it")

        # The flat tree is the mirror: skills/<flat> points back in here, so
        # every path that has always said skills/<flat> keeps resolving.
        for alias, flat in sorted(want_links.items()):
            mirror = SKILLS / flat
            want = Path(f"../plugins/{name}/skills/{alias}")
            if not mirror.is_symlink():
                errors.append(f"{mirror}: expected a symlink to {want}")
            elif mirror.readlink() != want:
                errors.append(f"{mirror} -> {mirror.readlink()} (expected {want})")

    # 3b) Aliases are unique across *all* families. The alias is the skill's
    #     frontmatter `name:`, and Gemini CLI registers skills by that name in
    #     one flat namespace, so a repeat across two families is a collision.
    owners: dict[str, list[str]] = {}
    for family, skills in sorted(fam.items()):
        for alias in aliases_for(family, skills):
            owners.setdefault(alias, []).append(f"magpie-{family}")
    for alias, plugins in sorted(owners.items()):
        if len(plugins) > 1:
            errors.append(
                f"alias '{alias}' is used by {', '.join(plugins)} — skill names must be "
                f"unique across families; add an ALIAS_OVERRIDES entry"
            )

    # 4) Substrate plugins: manifest + hook wiring + tool symlinks that resolve.
    for name in sorted(SUBSTRATE_PLUGINS):
        errors += check_substrate(name, shared)
        if name not in listed:
            errors.append(f"{MARKETPLACE}: missing entry for '{name}'")

    # 5) No orphan plugin dirs (a magpie-<x> that is neither a family nor substrate).
    for pdir in sorted(PLUGINS.glob("magpie-*")):
        if pdir.name in SUBSTRATE_PLUGINS:
            continue
        family = pdir.name[len("magpie-") :]
        if family not in fam:
            errors.append(f"orphan plugin '{pdir.name}': no skill declares family '{family}'")

    return errors


def unowned_entries(pdir: Path) -> list[str]:
    """Anything in a plugin dir that `--fix` did not generate.

    A blanket `rmtree` is safe only for as long as these directories hold
    nothing but a generated manifest and symlinks. The moment a family grows a
    `commands/`, an `agents/`, or a README, a blanket delete would silently
    discard it. So enumerate what regeneration owns and report anything else,
    so the operator gets an error naming the file instead of a quiet loss.
    """
    if not pdir.is_dir():
        return []
    mdir = pdir / ".claude-plugin"
    # A substrate plugin owns its generated tool parents instead of `skills/`.
    hook_dir = None
    if spec := SUBSTRATE_PLUGINS.get(pdir.name):
        owned = {mdir} | {pdir / Path(link).parts[0] for link in spec["links"]}
        owned |= {pdir / Path(dest).parts[0] for dest in spec.get("copies", {})}
        link_dirs = [pdir / Path(link).parent for link in spec["links"]]
        if "hook_config" in spec:
            hook_dir = pdir / "hooks"
            owned.add(hook_dir)
    else:
        owned = {mdir, pdir / "skills"}
        link_dirs = [pdir / "skills"]

    unexpected = sorted(p for p in pdir.iterdir() if p not in owned)

    if mdir.is_dir():
        unexpected += sorted(p for p in mdir.iterdir() if p.name != "plugin.json")

    for sdir in link_dirs:
        if sdir.is_dir():
            unexpected += sorted(p for p in sdir.iterdir() if not p.is_symlink())

    if hook_dir is not None and hook_dir.is_dir():
        unexpected += sorted(p for p in hook_dir.iterdir() if p.name != "hooks.json")
    if not unexpected:
        return []
    return [
        f"{pdir}: refusing to regenerate — not generated by --fix: "
        f"{', '.join(str(p) for p in unexpected)} "
        f"(move it out, or teach --fix to generate it)"
    ]


def fix(fam: dict[str, set[str]]) -> int:
    # Propagate the authoritative version outward before reading the root
    # manifest's metadata, so a bump in pyproject.toml alone is enough.
    version, verr = pyproject_version()
    if verr or version is None:
        for e in verr or [f"{PYPROJECT}: no project.version"]:
            print(f"  - {e}", file=sys.stderr)
        return 1
    for path in ECOSYSTEM_MANIFESTS:
        if not path.is_file():
            print(f"  - {path}: missing (declares the framework version)", file=sys.stderr)
            return 1
        have, err = manifest_version(path)
        if err:
            print(f"  - {err}", file=sys.stderr)
            return 1
        if have != version:
            if write_errs := write_manifest_version(path, version):
                for e in write_errs:
                    print(f"  - {e}", file=sys.stderr)
                return 1
            print(f"{path}: version {have} -> {version}")

    shared, meta_errs = root_metadata()
    if meta_errs:
        for e in meta_errs:
            print(f"  - {e}", file=sys.stderr)
        print(
            f"\nCannot regenerate: the family plugins inherit {', '.join(INHERITED)} from {ROOT_MANIFEST}.",
            file=sys.stderr,
        )
        return 1

    # A plugin directory now holds the *canonical* skill directories, so the
    # old regenerate-from-scratch pass would destroy source. `--fix` rewrites
    # manifests and catalogue entries in place; the only directories it may
    # delete are orphans — a `magpie-<x>` that no skill's `family:` frontmatter
    # and no substrate spec claims any more.
    live = {f"magpie-{family}" for family in fam} | set(SUBSTRATE_PLUGINS)
    orphans = [p for p in sorted(PLUGINS.glob("magpie-*")) if p.name not in live]
    # Check every orphan *before* deleting any of them, so a stray file in the
    # last one does not leave the earlier ones already destroyed.
    if rm_errs := [e for pdir in orphans for e in unowned_entries(pdir)]:
        for e in rm_errs:
            print(f"  - {e}", file=sys.stderr)
        return 1
    for pdir in orphans:
        if any((pdir / "skills").glob("*/SKILL.md")):
            print(
                f"refusing to remove {pdir}: it contains real skills. "
                f"Move them out first — --fix will not delete source.",
                file=sys.stderr,
            )
            return 1
        shutil.rmtree(pdir)
    for name in sorted(SUBSTRATE_PLUGINS):
        write_substrate(name, shared)
    for family, skills in sorted(fam.items()):
        name = f"magpie-{family}"
        pdir = PLUGINS / name
        sdir = pdir / "skills"
        (pdir / ".claude-plugin").mkdir(parents=True, exist_ok=True)
        sdir.mkdir(parents=True, exist_ok=True)
        # Skill directories are source and are never generated: a family plugin
        # owns them, and the flat skills/<name> tree mirrors them back. --fix
        # regenerates manifests and catalog entries only.
        for alias, skill in sorted(aliases_for(family, skills).items()):
            if not (sdir / alias / "SKILL.md").is_file():
                print(
                    f"{name}: no skill directory '{alias}' for '{skill}'. Move "
                    f"skills/{skill} to {sdir / alias} and leave a symlink behind.",
                    file=sys.stderr,
                )
        manifest = {
            "name": name,
            "description": f"Apache Magpie — {DESC.get(family, family + ' family skills')}",
            **shared,
        }
        if (pdir / "hooks" / "types.d.ts").is_file():
            manifest["types"] = "./hooks/types.d.ts"
        manifest["skills"] = "./skills"
        if name == "magpie-setup" and not (pdir / "hooks" / "hooks.json").is_file():
            manifest["hooks"] = SETUP_HOOKS
        (pdir / ".claude-plugin" / "plugin.json").write_text(
            json.dumps(manifest, indent=2) + "\n", encoding="utf-8"
        )

    market, market_err = load_json(MARKETPLACE)
    if market_err:
        print(f"  - {market_err}", file=sys.stderr)
        return 1
    # Every entry is derived: the substrate plugins from their specs, the
    # families from `family:` frontmatter. Nothing is carried over — with the
    # all-in-one gone there is no entry left that `--fix` cannot reconstruct.
    if not isinstance(market.get("plugins"), list):
        print(f"  - {MARKETPLACE}: 'plugins' is missing or not a list", file=sys.stderr)
        return 1
    keep: list[dict] = []
    for name in sorted(SUBSTRATE_PLUGINS):
        keep.append(
            {
                "name": name,
                "source": f"./plugins/{name}",
                "version": shared["version"],
                "description": SUBSTRATE_PLUGINS[name]["description"],
            }
        )
    for family, skills in sorted(fam.items()):
        keep.append(
            {
                "name": f"magpie-{family}",
                "source": f"./plugins/magpie-{family}",
                "version": shared["version"],
                "description": f"Apache Magpie {family} family ({len(skills)} skills).",
            }
        )
    market["plugins"] = keep
    MARKETPLACE.write_text(json.dumps(market, indent=2) + "\n", encoding="utf-8")
    # Codex supports the same native plugin hooks, but only self-contained
    # substrate packages can be advertised: outward symlinks are not installed.
    if CODEX_CATALOG.is_file():
        catalog, catalog_error = load_json(CODEX_CATALOG)
        if catalog_error:
            print(catalog_error, file=sys.stderr)
            return 1
        entries = [e for e in catalog["plugins"] if e.get("name") not in CODEX_SUBSTRATES]
        entries += [
            {
                "name": name,
                "source": {"source": "local", "path": f"./plugins/{name}"},
                "category": "maintenance",
                "policy": {"installation": "AVAILABLE"},
            }
            for name in sorted(CODEX_SUBSTRATES)
        ]
        catalog["plugins"] = sorted(entries, key=lambda e: e["name"])
        CODEX_CATALOG.write_text(json.dumps(catalog, indent=2) + "\n", encoding="utf-8")
    if welcome_errs := welcome_families("write-constant"):
        for e in welcome_errs:
            print(f"  - {e}", file=sys.stderr)
        return 1
    print("Regenerated per-family plugins + marketplace entries from frontmatter.")
    return 0


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--fix", action="store_true", help="regenerate plugins from frontmatter")
    ap.add_argument("files", nargs="*", help="(ignored; present for pre-commit)")
    args = ap.parse_args()

    fam = families_from_frontmatter()
    if args.fix:
        return fix(fam)

    errors = check(fam)
    if errors:
        print("Family plugins are out of sync with skills' `family:` frontmatter:", file=sys.stderr)
        for e in errors:
            print(f"  - {e}", file=sys.stderr)
        print("\nRun `python3 tools/dev/check-family-plugins.py --fix` to regenerate.", file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":
    raise SystemExit(main())