ai-kit-python 1.4.2__py3-none-any.whl

aikit/scripts/check_distribution.py

@@ -0,0 +1,178 @@
+"""Validate local release archives and manual publication identity without uploading."""
+from __future__ import annotations
+
+import argparse
+import configparser
+from email import policy
+from email.parser import BytesParser
+import hashlib
+import json
+from pathlib import Path, PurePosixPath
+import re
+import stat
+import tarfile
+import zipfile
+
+ROOT = Path(__file__).resolve().parents[1]
+PROJECT_NAME = "ai-kit-python"
+LICENSES = ("LICENSE", "template/ai-kit/vendor/security-audit/LICENSE",
+            "template/ai-kit/vendor/strix/LICENSE")
+LOCAL_FILES = {"AGENTS.md", "PROJECT_CONTEXT.md", "WIKI.md"}
+PRIVATE_PARTS = {".git", ".aws", ".codex", ".claude", ".secrets", ".metrics", ".memory",
+                 ".upstream-cache", ".design", ".private", "__pycache__"}
+REQUIRED = {"VERSION", "LICENSE", "aikit_cli.py", "scripts/install.py", "scripts/check_distribution.py",
+            "template/AGENTS.md", "template/PROJECT_CONTEXT.md", "template/WIKI.md",
+            "template/ai-kit/settings.json", "docs/PYPI_DESCRIPTION.md", "docs/PYPI.md",
+            "docker/pypi-requirements.txt", ".github/workflows/publish-pypi.yml", "tests/build_distribution.py", *LICENSES}
+
+
+def release_identity(version: str, expected: str, destination: str, ref: str, repository: str) -> dict:
+    """Require an explicit matching version/tag before either registry upload."""
+    if destination not in {"validate", "testpypi", "pypi"}:
+        raise ValueError("Unknown publication destination")
+    if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+(?:(?:a|b|rc)[0-9]+)?", version):
+        raise ValueError("VERSION must be a three-part release or pre-release")
+    if expected and expected != version:
+        raise ValueError("Requested version does not match VERSION")
+    if destination != "validate":
+        if expected != version or ref != "refs/tags/v" + version:
+            raise ValueError("Publication requires an explicit matching version and vVERSION tag")
+        if repository != "tigusigalpa/ai-kit":
+            raise ValueError("Publication is restricted to the canonical repository")
+    return {"name": PROJECT_NAME, "version": version, "destination": destination,
+            "upload_performed": False}
+
+
+def _members(path: Path) -> dict[str, bytes]:
+    result: dict[str, bytes] = {}
+    total = 0
+
+    def add(name: str, size: int, read) -> None:
+        nonlocal total
+        parts = PurePosixPath(name).parts
+        if not parts or "\\" in name or name.startswith("/") or ".." in parts or ":" in parts[0]:
+            raise ValueError("Unsafe archive member path")
+        if name in result:
+            raise ValueError("Duplicate archive member")
+        total += size
+        if size > 32_000_000 or total > 128_000_000 or len(result) >= 5000:
+            raise ValueError("Archive exceeds inspection limits")
+        result[name] = read()
+
+    if path.suffix == ".whl":
+        with zipfile.ZipFile(path) as archive:
+            for item in archive.infolist():
+                if stat.S_ISLNK(item.external_attr >> 16):
+                    raise ValueError("Linked archive member")
+                if not item.is_dir():
+                    add(item.filename, item.file_size, lambda item=item: archive.read(item))
+    else:
+        with tarfile.open(path, "r:gz") as archive:
+            for item in archive.getmembers():
+                if item.isdir():
+                    continue
+                if not item.isfile():
+                    raise ValueError("Linked or special archive member")
+                def read(item=item):
+                    with archive.extractfile(item) as stream:
+                        return stream.read()
+                add(item.name, item.size, read)
+    return result
+
+
+def inspect_distribution(path: Path, version: str) -> dict:
+    """Check metadata, CLI/resources, licenses and private-file boundaries in one archive."""
+    if path.is_symlink() or not path.is_file():
+        raise ValueError("Distribution must be a regular unlinked file")
+    files = _members(path)
+    wheel = path.suffix == ".whl"
+    if wheel:
+        metadata_paths = [name for name in files if re.fullmatch(r"[^/]+\.dist-info/METADATA", name)]
+        if len(metadata_paths) != 1:
+            raise ValueError("Wheel must contain exactly one metadata record")
+        info = metadata_paths[0].rsplit("/", 1)[0]
+        payload = {name[6:]: data for name, data in files.items() if name.startswith("aikit/")}
+        metadata_bytes = files[metadata_paths[0]]
+        parser = configparser.ConfigParser(interpolation=None)
+        parser.read_string(files.get(info + "/entry_points.txt", b"").decode("utf-8"))
+        if parser.get("console_scripts", "aikit", fallback="") != "aikit.aikit_cli:main":
+            raise ValueError("Missing aikit console entry point")
+        wheel_metadata = files.get(info + "/WHEEL", b"")
+        if b"Root-Is-Purelib: true" not in wheel_metadata or b"Tag: py3-none-any" not in wheel_metadata:
+            raise ValueError("Expected a portable pure-Python wheel")
+    else:
+        roots = {name.split("/", 1)[0] for name in files}
+        if len(roots) != 1:
+            raise ValueError("Source archive must have one root")
+        prefix = next(iter(roots)) + "/"
+        payload = {name[len(prefix):]: data for name, data in files.items()}
+        metadata_bytes = payload.get("PKG-INFO", b"")
+    metadata = BytesParser(policy=policy.default).parsebytes(metadata_bytes)
+    if metadata.get("Name") != PROJECT_NAME or metadata.get("Version") != version:
+        raise ValueError("Archive name/version metadata does not match the release")
+    if metadata.get("Requires-Python") != ">=3.10" or metadata.get_all("Requires-Dist"):
+        raise ValueError("Unexpected runtime Python/dependency contract")
+    if metadata.get("License-Expression") != "MIT AND Apache-2.0":
+        raise ValueError("Missing complete distribution license expression")
+    if set(metadata.get_all("License-File", [])) != set(LICENSES):
+        raise ValueError("Missing bundled license declarations")
+    if metadata.get("Description-Content-Type") != "text/markdown":
+        raise ValueError("Missing Markdown description content type")
+    if not metadata.get("Author") or len(metadata.get_all("Project-URL", [])) < 5:
+        raise ValueError("Missing author or project URLs")
+    if not REQUIRED.issubset(payload) or payload["VERSION"].decode().strip() != version:
+        raise ValueError("Missing required distribution resources or bundled VERSION")
+    for name in payload:
+        parts = PurePosixPath(name).parts
+        if name in LOCAL_FILES or PRIVATE_PARTS.intersection(parts) or any(p.startswith(".env") for p in parts):
+            raise ValueError("Private local content included in distribution")
+        if (parts[-1] in {"auth.json", ".netrc", ".pypirc"}
+                or parts[-1].endswith((".pem", ".p12", ".pfx"))
+                or parts[-1].startswith(("id_rsa", "id_ed25519"))):
+            raise ValueError("Credential file included in distribution")
+    description = metadata.get_payload().replace("\r\n", "\n").strip()
+    if description != payload["docs/PYPI_DESCRIPTION.md"].decode("utf-8").replace("\r\n", "\n").strip():
+        raise ValueError("Package description differs from its canonical source")
+    if re.search(r"\]\((?!https://|mailto:|#)[^)]+\)", description) or "```mermaid" in description:
+        raise ValueError("PyPI description contains nonportable links or diagrams")
+    if wheel:
+        for name in LICENSES:
+            if files.get(info + "/licenses/" + name) != payload[name]:
+                raise ValueError("Wheel license payload is missing or changed")
+    return {"file": path.name, "version": version, "payload_files": len(payload),
+            "sha256": hashlib.sha256(path.read_bytes()).hexdigest()}
+
+
+def check_archives(directory: Path, version: str) -> list[dict]:
+    paths = sorted(directory.glob("*.whl")) + sorted(directory.glob("*.tar.gz"))
+    if len(paths) != 2 or sum(path.suffix == ".whl" for path in paths) != 1:
+        raise ValueError("Expected exactly one wheel and one source archive")
+    return [inspect_distribution(path, version) for path in paths]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    identity = sub.add_parser("identity", help="Validate a manual build/publication request; never uploads")
+    identity.add_argument("--expected-version", default="")
+    identity.add_argument("--destination", choices=("validate", "testpypi", "pypi"), default="validate")
+    identity.add_argument("--ref", default="")
+    identity.add_argument("--repository", default="")
+    archives = sub.add_parser("archives", help="Inspect a prepared wheel and sdist; never uploads")
+    archives.add_argument("directory", type=Path)
+    args = parser.parse_args(argv)
+    try:
+        version = (ROOT / "VERSION").read_text(encoding="utf-8").strip()
+        if args.command == "identity":
+            result = release_identity(version, args.expected_version, args.destination, args.ref, args.repository)
+        else:
+            result = {"archives": check_archives(args.directory, version), "upload_performed": False}
+        print(json.dumps(result, indent=2))
+        return 0
+    except (OSError, ValueError, KeyError, configparser.Error, tarfile.TarError, zipfile.BadZipFile) as exc:
+        print(json.dumps({"error": str(exc), "upload_performed": False}))
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aikit/scripts/check_kit.py

@@ -0,0 +1,406 @@
+"""Offline validation of reference/template boundaries, metadata, links, and visibility."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from urllib.parse import unquote
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import install
+
+ROOT = Path(__file__).resolve().parents[1]
+# User-facing onboarding/publication copy has no size quota; instruction budgets remain scoped.
+DOC_BUDGET = 12000
+UNBOUNDED_DOCUMENTS = frozenset(("README.md", "docs/DOCKER_HUB_OVERVIEW.md"))
+LOCAL_MAINTAINER_FILES = frozenset(("AGENTS.md", "PROJECT_CONTEXT.md", "WIKI.md"))
+
+
+
+def source_files(root: Path):
+    # IDE and tool state is local to a checkout, never a kit source.
+    excluded = {".git", "__pycache__", ".upstream-cache", ".pytest_cache", ".mypy_cache", ".ruff_cache",
+                ".idea", ".vscode", ".fleet", ".zed", ".nova", ".history", ".claude"}
+    for directory, dirs, files in os.walk(root, followlinks=False):
+        dirs[:] = [d for d in dirs if d not in excluded]
+        if Path(directory) == root / "ai-kit":
+            dirs[:] = [d for d in dirs if d not in {".metrics", ".memory"}]
+        for name in files:
+            path = Path(directory) / name
+            if path.parent == root and name in LOCAL_MAINTAINER_FILES:
+                continue
+            if path.suffix != ".pyc":
+                yield path
+
+
+def headings(text: str) -> set[str]:
+    result, counts = set(), {}
+    fenced = False
+    marker = ""
+    for line in text.splitlines():
+        if re.match(r"^\s*([~]{3,}|[\x60]{3,})", line):
+            token = line.strip()[0]
+            if not fenced:
+                fenced, marker = True, token
+            elif token == marker:
+                fenced = False
+            continue
+        if fenced or not re.match(r"^#{1,6}\s", line):
+            continue
+        label = re.sub(r"^#{1,6}\s+", "", line).strip().lower()
+        label = re.sub(r"<[^>]+>", "", label)
+        label = re.sub(r"[^\w -]", "", label).replace(" ", "-")
+        count = counts.get(label, 0)
+        counts[label] = count + 1
+        result.add(label + (f"-{count}" if count else ""))
+    return result
+
+
+def metadata(text: str) -> dict[str, str]:
+    match = re.match(r"\A---\n(.*?)\n---\n", text.replace("\r\n", "\n"), re.S)
+    if not match:
+        raise ValueError("Missing frontmatter")
+    fields = {}
+    for line in match.group(1).splitlines():
+        if ":" not in line:
+            raise ValueError("Unsupported frontmatter line")
+        key, value = line.split(":", 1)
+        if key in fields:
+            raise ValueError("Duplicate frontmatter field")
+        value = value.strip()
+        fields[key] = json.loads(value) if value.startswith('"') else value
+    if not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", fields.get("name", "")):
+        raise ValueError("Invalid skill name")
+    if not isinstance(fields.get("description"), str) or len(fields["description"]) < 20:
+        raise ValueError("Missing useful description")
+    return fields
+
+
+def links(text: str):
+    # Fenced examples are data, not Markdown links.
+    text = re.sub(r"(?ms)^\s*(?:~~~|[\x60]{3}).*?^\s*(?:~~~|[\x60]{3})\s*$", "", text)
+    return re.findall(r"!?\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)", text)
+
+
+def visibility(root: Path, git: str) -> list[str]:
+    errors = []
+    with tempfile.TemporaryDirectory(prefix="ai-kit-ignore-") as folder:
+        scratch = Path(folder)
+        subprocess.run([git, "init", "-q", str(scratch)], check=True, capture_output=True)
+
+        def ignored(path: str) -> bool:
+            result = subprocess.run([git, "-c", "core.excludesFile=" + os.devnull,
+                                     "-C", str(scratch), "check-ignore", "--no-index", "--", path],
+                                    capture_output=True)
+            if result.returncode not in {0, 1}:
+                raise ValueError(result.stderr.decode(errors="replace"))
+            return result.returncode == 0
+
+        (scratch / ".gitignore").write_bytes((root / ".gitignore").read_bytes())
+        for relative in sorted(LOCAL_MAINTAINER_FILES):
+            if not ignored(relative):
+                errors.append("Local maintainer file must be ignored: " + relative)
+        for p in source_files(root):
+            relative = p.relative_to(root).as_posix()
+            if ignored(relative):
+                errors.append("Reference source ignored: " + relative)
+        # Compose the policy with installer-detected module rules, as apply does.
+        (scratch / "package.json").write_text("{}\n", encoding="utf-8")
+        (scratch / "pyproject.toml").write_text("[project]\nname = \"scratch\"\n", encoding="utf-8")
+        for mode in ("private", "team"):
+            policy = (root / "templates" / ("gitignore." + mode)).read_text(encoding="utf-8")
+            merged, _ = install.merge_ignore("", policy, install.module_ignores(scratch))
+            (scratch / ".gitignore").write_bytes(merged.encode("utf-8"))
+            for path in ("AGENTS.md", "PROJECT_CONTEXT.md", "ai-kit/CORE.md", "GEMINI.md",
+                         ".agents/skills/go-work/SKILL.md", ".claude/skills/go-work/SKILL.md",
+                         ".agents/skills/security-audit/SKILL.md",
+                         ".agents/skills/security-audit/agents/openai.yaml",
+                         ".claude/skills/security-audit/SKILL.md",
+                         "ai-kit/vendor/security-audit/LICENSE", "ai-kit/vendor/security-audit/UPSTREAM.json",
+                         ".agents/skills/strix/SKILL.md", ".agents/skills/strix/agents/openai.yaml",
+                         ".claude/skills/strix/SKILL.md", "ai-kit/vendor/strix/LICENSE",
+                         "ai-kit/vendor/strix/UPSTREAM.json",
+                         ".agents/skills/context7-docs/SKILL.md", ".claude/skills/context7-docs/SKILL.md",
+                         "ai-kit/CONTEXT7.md",
+                         "ai-kit/WEB-DESIGN.md", "ai-kit/web-design/LARAVEL.md",
+                         ".agents/skills/web-design/SKILL.md", ".claude/skills/web-design/SKILL.md",
+                         ".agents/skills/laravel-blade-ui/SKILL.md", ".claude/skills/laravel-blade-ui/SKILL.md",
+                         ".agents/skills/ui-review/SKILL.md", ".claude/skills/ui-review/SKILL.md",
+                         ".agents/skills/design-extract/SKILL.md", ".claude/skills/design-extract/SKILL.md",
+                         ".agents/hooks/session-start.md", ".agents/hooks/session-start.sh",
+                         ".agents/skills/ai-kit-bootstrap/SKILL.md", ".claude/rules/ai-kit-web.md",
+                         ".cursor/rules/ai-kit-web.mdc", ".github/instructions/ai-kit-web.instructions.md",
+                         ".windsurf/rules/ai-kit-web.md", ".clinerules/ai-kit-web.md",
+                         ".windsurf/rules/ai-kit.md", "docs/DECISIONS.md",
+                         ".codex/config.toml", ".cursor/mcp.json", ".gemini/settings.json", ".clinerules",
+                         ".github/prompts/review.prompt.md", ".aider.conf.yml"):
+                if ignored(path) != (mode == "private"):
+                    errors.append(f"{mode}: wrong shared visibility: {path}")
+            for path in (".env", ".claude/settings.local.json", "ai-kit/.upstream-cache/a",
+                         "ai-kit/.metrics/tasks.jsonl", "ai-kit/.metrics/write.lock", "ai-kit/.memory/session/imports/chat.json",
+                         "ai-kit/.design/screenshots/home.png", "ai-kit/.design/extractions/DESIGN.md",
+                         "go-cache/a", "test.out", "__pycache__/a.pyc", ".idea/workspace.xml",
+                         ".netrc", ".pypirc", ".aider.chat.history.md", ".aider.tags.cache.v4/a",
+                         "AI-KIT-0.6.5/README.md", "web/.next/cache/a", "__debug_bin1234"):
+                if not ignored(path):
+                    errors.append(f"{mode}: private/generated data visible: {path}")
+            for path in ("composer.lock", "go.mod", "go.sum", "uv.lock", ".env.example",
+                         "vendor/modules.txt", "src/SKILL.md", "bin/worker.py", ".cursorignore",
+                         ".github/workflows/ci.yml", ".aiderignore"):
+                if ignored(path):
+                    errors.append(f"{mode}: intended project source ignored: {path}")
+            for path in install.OPTIONAL_DOCUMENTS["web-design"]:
+                if ignored(path):
+                    errors.append(f"{mode}: project design document ignored: {path}")
+    return errors
+
+
+def agent_registry_links(root: Path) -> list[str]:
+    """Cross-check registry entries and optional sources against the distribution."""
+    errors = []
+    registry = install.load_agent_registry(root)
+    for entry in registry["entries"]:
+        if not (root / "template" / entry).is_file():
+            errors.append("Agent registry entry missing from template: " + entry)
+    destinations: set[str] = set()
+    for agent, items in registry["optional"].items():
+        for source, destination in items:
+            if not (root / "integrations" / source).is_file():
+                errors.append("Agent registry optional source missing: " + source)
+            if destination in destinations:
+                errors.append("Agent registry destination owned by multiple agents: " + destination)
+            destinations.add(destination)
+    return errors
+
+
+def check(root: Path, *, git: str | None = None) -> tuple[list[str], list[str]]:
+    errors, warnings = [], []
+    required = ["VERSION", "LICENSE", "CONTRIBUTING.md", "README.md",
+                "Dockerfile", ".dockerignore", "docker/check_version.py", "docker/build-requirements.txt",
+                "deploy/k8s/install-preview-job.yaml", "tests/docker_smoke.py", "docs/DOCKER.md",
+                "template/AGENTS.md", "template/PROJECT_CONTEXT.md", "template/WIKI.md",
+                "template/ai-kit/CORE.md", "template/ai-kit/settings.json",
+                "template/ai-kit/project.json", "template/ai-kit/MCP.md",
+                "scripts/install.py", "scripts/router.py", "scripts/adr.py", "scripts/changelog.py",
+                "scripts/metrics.py", "scripts/context.py", "scripts/adapters.py", "scripts/evaluate.py",
+                "scripts/memory.py", "scripts/memory_import.py", "scripts/memory_store.py", "docs/DIALOGUE_MEMORY.md",
+                "scripts/benchmark.py", "scripts/adaptive.py", "scripts/learning.py",
+                "scripts/__init__.py", "template/ai-kit/METRICS.md",
+                "template/ai-kit/stacks/FILAMENT.md", "template/.agents/skills/filament-work/SKILL.md",
+                "integrations/agents.json", "integrations/claude-settings.git-ask.json",
+                "integrations/claude-settings.data-ask.json", "templates/agent-secrets.ignore",
+                "SKILL.md", "template/ai-kit/CONTEXT7.md", "template/.agents/skills/context7-docs/SKILL.md",
+                "template/.agents/hooks/session-start.md", "template/.agents/hooks/session-start.sh",
+                "template/ai-kit/router/selection.json",
+                "template/ai-kit/router/routing.json",
+                "template/ai-kit/router/providers/local.json",
+                "template/ai-kit/router/providers/gemini.json",
+                "templates/gitignore.private", "templates/gitignore.team",
+                "aikit_cli.py", "__init__.py", "MANIFEST.in", "pyproject.toml", "tests/wheel_smoke.py",
+                "scripts/check_distribution.py", "tests/test_distribution.py", "docs/PYPI.md", "docs/PYPI_DESCRIPTION.md",
+                "docker/pypi-requirements.txt", ".github/workflows/publish-pypi.yml",
+                "tests/build_distribution.py",
+                ".github/workflows/check-kit.yml", "docs/IMPLEMENTATION.md",
+                ]
+    for name in install.OPTIONAL_SKILLS:
+        required.extend(["integrations/" + name + ".json", "template/.agents/skills/" + name + "/SKILL.md",
+                         "template/.agents/skills/" + name + "/agents/openai.yaml"])
+    required.extend("template/" + path for paths in install.OPTIONAL_RESOURCES.values() for path in paths)
+    required.extend("template/" + path for paths in install.OPTIONAL_DOCUMENTS.values() for path in paths)
+    required.extend("template/.agents/skills/" + name + "/SKILL.md"
+                    for name in install.OPTIONAL_ENTRY_POINTS["web-design"])
+    for relative in required:
+        if not (root / relative).is_file():
+            errors.append("Missing: " + relative)
+    pyproject = root / "pyproject.toml"
+    if pyproject.is_file():
+        text = pyproject.read_text(encoding="utf-8")
+        if 'aikit = "aikit.aikit_cli:main"' not in text:
+            errors.append("pyproject.toml must declare the aikit console script")
+        if "version = {file = [\"VERSION\"]}" not in text:
+            errors.append("pyproject.toml must derive its version from VERSION")
+    elif not (root / "aikit_cli.py").is_file():
+        errors.append("Missing unified CLI entry point")
+    vendored_files: set[Path] = set()
+    for name in install.OPTIONAL_SKILLS:
+        try:
+            package_files = install.upstream_skill_files(name, root)
+            vendored_files.update(root / "template" / path for path in package_files
+                                 if path != "ai-kit/vendor/" + name + "/UPSTREAM.json")
+        except (OSError, ValueError) as exc:
+            errors.append(f"Invalid pinned {name} package: " + str(exc))
+    for p in source_files(root):
+        if p.is_symlink():
+            errors.append("Linked source: " + str(p))
+            continue
+        try:
+            text = p.read_text(encoding="utf-8")
+        except UnicodeError:
+            errors.append("Not UTF-8 text: " + str(p))
+            continue
+        # Pinned upstream Unicode fixtures are external data, not authored project language.
+        if p not in vendored_files and re.search(r"[\u0400-\u04ff]", text):
+            errors.append("Unexpected Cyrillic project content: " + str(p))
+        if p.suffix == ".json":
+            try:
+                json.loads(text)
+            except ValueError as exc:
+                errors.append(f"{p}: invalid JSON: {exc}")
+        if p.name == "SKILL.md":
+            try:
+                fields = metadata(text)
+                # The repository root is itself a skill; its folder name depends on the checkout.
+                expected = "ai-kit" if p.parent == root else p.parent.name
+                if fields["name"] != expected:
+                    errors.append("Skill name/folder mismatch: " + str(p))
+            except (ValueError, TypeError) as exc:
+                errors.append(f"{p}: {exc}")
+        if p.suffix != ".md":
+            continue
+        if any(line.rstrip() != line for line in text.splitlines()):
+            errors.append("Trailing whitespace: " + str(p))
+        if not text.endswith("\n"):
+            errors.append("Missing final newline: " + str(p))
+        # Immutable upstream references are conditional assets; the entry point retains its budget.
+        if p.relative_to(root).as_posix() not in UNBOUNDED_DOCUMENTS and p not in vendored_files and len(text.encode()) > DOC_BUDGET:
+            warnings.append("Large conditional document: " + str(p))
+        for target in links(text):
+            if re.match(r"^[a-z][a-z0-9+.-]*:", target, re.I):
+                continue
+            filename, _, anchor = unquote(target).partition("#")
+            destination = (p.parent / filename).resolve() if filename else p.resolve()
+            try:
+                destination.relative_to(root.resolve())
+            except ValueError:
+                errors.append(f"{p}: link escapes reference: {target}")
+                continue
+            if destination.parent == root.resolve() and destination.name in LOCAL_MAINTAINER_FILES:
+                errors.append(f"{p}: public link depends on local maintainer file: {target}")
+                continue
+            if not destination.exists():
+                errors.append(f"{p}: missing link: {target}")
+            elif anchor and destination.is_file() and destination.suffix == ".md":
+                if anchor not in headings(destination.read_text(encoding="utf-8")):
+                    errors.append(f"{p}: missing heading: {target}")
+    budgets = {"template/AGENTS.md": 2500, "template/ai-kit/CORE.md": 3000,
+               "BOOTSTRAP_PROMPT.md": 2000}
+    for relative, limit in budgets.items():
+        if (root / relative).is_file() and (root / relative).stat().st_size > limit:
+            errors.append(f"Always-loaded entry exceeds budget: {relative}")
+    registry = root / "template/ai-kit/SKILLS.md"
+    if registry.exists():
+        expected = {p.parent.name for p in (root / "template/.agents/skills").glob("*/SKILL.md")}
+        entries = re.findall(r"\.\./\.agents/skills/([^/]+)/SKILL.md", registry.read_text())
+        if expected != set(entries) or len(entries) != len(set(entries)):
+            errors.append("Skill registry differs from actual source skills")
+    for relative in ("template/PROJECT_CONTEXT.md", "template/docs/DECISIONS.md", "template/CHANGELOG.md"):
+        if (root / relative).exists() and re.search(r"2026-\d\d-\d\d|5dd530b9|voice conversation",
+                                                   (root / relative).read_text()):
+            errors.append("Kit-maintenance history leaked into project template: " + relative)
+    project_json = root / "template/ai-kit/project.json"
+    if project_json.is_file():
+        try:
+            value = json.loads(project_json.read_text(encoding="utf-8"))
+            if type(value.get("schema")) is not int or value["schema"] != 1:
+                raise ValueError("schema must be 1")
+            evidence = value.get("evidence")
+            if (value.get("modules") != [] or not isinstance(value.get("operations"), dict) or
+                    not isinstance(evidence, dict) or evidence.get("schema") != 1 or
+                    evidence.get("modules") != []):
+                errors.append("Project template project.json must start empty of module facts")
+        except (ValueError, json.JSONDecodeError) as exc:
+            errors.append("Invalid project template project.json: " + str(exc))
+    providers_dir = root / "template" / "ai-kit" / "router" / "providers"
+    model_ids: list[str] = []
+    if providers_dir.is_dir():
+        for provider_path in sorted(providers_dir.glob("*.json")):
+            try:
+                config = json.loads(provider_path.read_text(encoding="utf-8"))
+                if not isinstance(config, dict):
+                    raise ValueError("provider must be an object")
+                tier = config.get("tier", "cloud")
+                if tier not in {"cloud", "local", "free"}:
+                    errors.append(f"Unknown provider tier: {provider_path.name}")
+                user_supplied = config.get("user_supplied_models") is True
+                if "user_supplied_models" in config and not isinstance(config["user_supplied_models"], bool):
+                    raise ValueError("user_supplied_models must be a boolean")
+                status = config.get("verification_status", "verified")
+                if status not in {"verified", "pending"}:
+                    errors.append(f"Unknown verification_status: {provider_path.name}")
+                verified = config.get("verified_documentation_date")
+                if isinstance(verified, str) and re.fullmatch(r"\d{4}-\d{2}-\d{2}", verified):
+                    pass
+                elif user_supplied:
+                    pass
+                elif status == "pending":
+                    warnings.append(f"Provider {provider_path.name} verification is pending")
+                else:
+                    errors.append("Provider lacks a verified_documentation_date: " + provider_path.name)
+                supported = config.get("supported_efforts", {})
+                if not isinstance(supported, dict):
+                    raise ValueError("supported_efforts must be an object")
+                roles = config.get("roles")
+                if not isinstance(roles, dict) or not roles:
+                    raise ValueError("roles must be a nonempty object")
+                for role, spec in roles.items():
+                    if not isinstance(spec, dict):
+                        raise ValueError(f"Invalid role spec: {role}")
+                    model = spec.get("model")
+                    if model is not None and not isinstance(model, str):
+                        raise ValueError(f"Invalid model for role {role}")
+                    if model is not None:
+                        model_ids.append(model)
+                    elif not (user_supplied or status == "pending"):
+                        errors.append(f"Provider role lacks a model: {provider_path.name} role {role}")
+                    if "effort" in spec:
+                        if spec["effort"] not in supported.get(role, []):
+                            errors.append(f"Unsupported configured effort: {provider_path.name} role {role}")
+                    elif role in supported and not user_supplied:
+                        errors.append(f"Role declares supported efforts but uses none: "
+                                      f"{provider_path.name} role {role}")
+            except (ValueError, KeyError, TypeError) as exc:
+                errors.append("Invalid provider configuration: " + str(exc))
+    try:
+        errors.extend(agent_registry_links(root))
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        errors.append("Invalid agent registry: " + str(exc))
+    for p in (root / "template").rglob("*.md"):
+        if p in vendored_files:
+            # Upstream examples are immutable external data, not active routing selections.
+            continue
+        text = p.read_text()
+        if re.search(r"gpt-[0-9]", text) or any(model_id in text for model_id in model_ids):
+            errors.append("Active model IDs duplicated outside provider configuration: " + str(p))
+    for mode in ("private", "team"):
+        p = root / "templates" / ("gitignore." + mode)
+        if p.exists() and any(line in {"SKILL.md", "vendor/"} for line in p.read_text().splitlines()):
+            errors.append("Overbroad skill/vendor ignore: " + mode)
+    git = git or os.environ.get("AI_KIT_GIT") or shutil.which("git")
+    if git:
+        try:
+            errors.extend(visibility(root, git))
+        except (OSError, ValueError, subprocess.CalledProcessError) as exc:
+            errors.append("Git visibility verification failed: " + str(exc))
+    else:
+        warnings.append("Git unavailable: visibility checks were not run")
+    return errors, warnings
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=ROOT)
+    parser.add_argument("--git")
+    args = parser.parse_args(argv)
+    errors, warnings = check(args.root, git=args.git)
+    print(json.dumps({"errors": errors, "warnings": warnings}, indent=2))
+    return int(bool(errors))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())