invigil 0.1.0__py3-none-any.whl

invigil/__init__.py

@@ -0,0 +1,9 @@
+"""Invigil — grade a repo against a product-quality doctrine, not code style.
+
+The doctrine is the QUALITY-PLAYBOOK: a stranger boots it in 10 minutes (G1),
+every error tells the fix (G2), published artifacts are machine-verified daily
+(G3), supply-chain evidence is public (G4), five doors open (G5). Invigil turns
+those Gates into mechanical, exact-fix-reporting checks.
+"""
+
+__version__ = "0.1.0"

invigil/checks/__init__.py

@@ -0,0 +1,132 @@
+"""The check registry.
+
+Each check is a function `(Context) -> CheckResult` decorated with `@register`,
+which pins its Check metadata (id, gate, weight, discipline). `run_all` executes
+every registered check against a repo, honouring `checks.disable` from config.
+
+Modules are imported for their side effect of registering checks. Add a new
+discipline module here and its checks light up automatically.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from ..context import Context
+from ..model import Check, CheckResult, Status
+
+REGISTRY: list[tuple[Check, Callable[[Context], CheckResult]]] = []
+
+
+def register(**meta):
+    """Decorator: attach Check metadata to a check function and register it."""
+
+    def wrap(fn: Callable[[Context], CheckResult]) -> Callable[[Context], CheckResult]:
+        check = Check(**meta)
+        # Expose the Check on the function so its body can build CheckResults
+        # without repeating the metadata.
+        fn.__invigil__ = check  # type: ignore[attr-defined]
+        REGISTRY.append((check, fn))
+        return fn
+
+    return wrap
+
+
+def run_all(
+    ctx: Context,
+    *,
+    only_layers: set[str] | None = None,
+    only_groups: set[str] | None = None,
+    offline: bool = False,
+) -> list[CheckResult]:
+    """Run the registered checks, optionally filtered by layer/group.
+
+    - `only_layers` / `only_groups`: run just that subset (the rest are omitted,
+      not reported — used by `invigil check <group>` and `--layer`).
+    - `offline`: never touch the network; `network`-layer checks become a SKIP
+      instead of running (used by pre-commit and `--offline`).
+    """
+    results: list[CheckResult] = []
+    for check, fn in REGISTRY:
+        if only_layers and check.layer not in only_layers:
+            continue
+        if only_groups and check.group not in only_groups:
+            continue
+        if check.id in ctx.config.disabled_checks:
+            results.append(CheckResult(check, Status.SKIP, detail="disabled in .invigil.yml"))
+            continue
+        if offline and check.layer == "network":
+            results.append(CheckResult(check, Status.SKIP, detail="offline — network check skipped"))
+            continue
+        try:
+            results.append(fn(ctx))
+        except Exception as exc:  # a check must never crash the gate
+            results.append(CheckResult(check, Status.WARN, detail=f"check errored: {exc}", fix="file an Invigil bug"))
+    return results
+
+
+# Import check modules for their registration side effects. Order is cosmetic;
+# checks are grouped in the report by gate, not by import order.
+from . import (  # noqa: E402,F401
+    ai_native,
+    g1_stranger,
+    g2_errors,
+    g3_supply,
+    g4_evidence,
+    g5_doors,
+    tier1_secrets,
+)
+
+# Central layer/group tagging — one place to maintain, so the 20+ `@register`
+# call sites stay clean. id -> (layer, group). Anything unlisted keeps the Check
+# defaults (local, "").
+TAGS: dict[str, tuple[str, str]] = {
+    # layout (G1 stranger-readiness)
+    "license-apache2": ("local", "layout"),
+    "readme-present": ("local", "layout"),
+    "readme-length": ("local", "layout"),
+    "readme-quickstart": ("local", "layout"),
+    "env-example": ("local", "layout"),
+    # secrets (Tier-1)
+    "no-tracked-secrets": ("local", "secrets"),
+    "gitleaks-clean": ("local", "secrets"),
+    # errors (G2)
+    "deep-health": ("local", "errors"),
+    "error-correlation-id": ("local", "errors"),
+    "error-path-tests": ("local", "errors"),
+    # supply-chain (G3)
+    "smoke-published": ("local", "supply-chain"),
+    "dependabot": ("local", "supply-chain"),
+    "actions-sha-pinned": ("local", "supply-chain"),
+    "lockfile-enforced": ("local", "supply-chain"),
+    "coverage-gate": ("local", "supply-chain"),
+    "version-matrix": ("local", "supply-chain"),
+    # evidence (G4)
+    "scorecard-workflow": ("local", "evidence"),
+    "scorecard-score": ("network", "evidence"),
+    "signed-releases-sbom": ("local", "evidence"),
+    "security-policy": ("local", "evidence"),
+    "changelog": ("local", "evidence"),
+    # doors (G5) + ai
+    "docs-index": ("local", "doors"),
+    "contributor-door": ("local", "doors"),
+    "code-of-conduct": ("local", "doors"),
+    "operator-door": ("local", "doors"),
+    "ai-door": ("local", "ai"),
+    "good-first-issues": ("network", "doors"),
+    # ai-native (M5)
+    "llms-no-secrets": ("local", "ai"),
+    "agent-scope-visibility": ("local", "ai"),
+}
+
+
+def _apply_tags() -> None:
+    for check, _ in REGISTRY:
+        check.layer, check.group = TAGS.get(check.id, (check.layer, check.group))
+
+
+_apply_tags()
+
+# Group/layer names the CLI exposes (for `invigil check <group>` / `--layer`).
+GROUPS = sorted({g for _, g in TAGS.values()})
+LAYERS = ("local", "network", "heavy")

invigil/checks/ai_native.py

@@ -0,0 +1,94 @@
+"""AI-native checks (group `ai`) — Invigil's answer to the architecture shift
+toward autonomous agents and micro-context payloads (survival Threat 2).
+
+Legacy linters are blind to `llms.txt` leaking a key or an agent wired to tools
+with no declared scope. These are the statically-honest slice of the "agent blast
+radius" idea: they don't compute *effective* IAM permissions (that needs
+code→credential→policy correlation — out of scope here), they ensure the
+preconditions for reasoning about blast radius exist: no secrets in the machine-
+readable surface, and a declared tool inventory whenever an agent framework is used.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ..context import Context
+from ..model import CheckResult, Status
+from . import register
+
+# High-signal secret patterns — specific enough not to fire on doc prose.
+SECRET_PATTERNS = (
+    re.compile(r"AKIA[0-9A-Z]{16}"),  # AWS access key id
+    re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),
+    re.compile(r"sk-[A-Za-z0-9]{32,}"),  # OpenAI-style secret key
+    re.compile(r"ghp_[A-Za-z0-9]{36}"),  # GitHub PAT
+    re.compile(r"xox[baprs]-[A-Za-z0-9-]{10,}"),  # Slack token
+)
+
+AI_FILES = ("llms.txt", "llms-full.txt", "AGENTS.md")
+
+# Agent/LLM-framework import markers — presence means this repo builds agents.
+AGENT_MARKERS = (
+    "langchain",
+    "langgraph",
+    "llama_index",
+    "llamaindex",
+    "import mcp",
+    "from mcp",
+    "autogen",
+    "crewai",
+    "semantic_kernel",
+)
+
+
+@register(
+    id="llms-no-secrets",
+    gate="G5",
+    title="Machine-readable surface leaks no secrets",
+    weight=1,
+    mandatory=False,
+    discipline="D5",
+)
+def llms_no_secrets(ctx: Context) -> CheckResult:
+    check = llms_no_secrets.__invigil__  # type: ignore[attr-defined]
+    present = [f for f in AI_FILES if ctx.exists(f)]
+    if not present:
+        return CheckResult(check, Status.SKIP, "no llms.txt / AGENTS.md to scan")
+    for f in present:
+        text = ctx.read(f)
+        for pat in SECRET_PATTERNS:
+            if pat.search(text):
+                return CheckResult(
+                    check,
+                    Status.FAIL,
+                    f"{f} contains a secret-looking token",
+                    f"remove the credential from {f} and rotate it — the AI surface is world-readable and crawled",
+                )
+    return CheckResult(check, Status.PASS, f"clean: {', '.join(present)}")
+
+
+@register(
+    id="agent-scope-visibility",
+    gate="G5",
+    title="Agents declare their tool inventory (blast-radius precondition)",
+    weight=1,
+    mandatory=False,
+    discipline="D5",
+)
+def agent_scope_visibility(ctx: Context) -> CheckResult:
+    check = agent_scope_visibility.__invigil__  # type: ignore[attr-defined]
+    uses_agents = ctx.source_contains(*AGENT_MARKERS, suffixes=(".py", ".ts", ".js"))
+    if not uses_agents:
+        return CheckResult(check, Status.SKIP, "no agent framework in use")
+    # An AGENTS.md (or a tools manifest) is the declared inventory of what the
+    # agent can touch — the thing you'd reason about a blast radius from.
+    if ctx.first_existing("AGENTS.md", "agents.yaml", "tools.yaml", "docs/agents.md"):
+        return CheckResult(check, Status.PASS, "agent tool inventory declared")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "agent framework used but no declared tool inventory",
+        "add AGENTS.md listing each tool the agent can call and its permission scope "
+        "(the blast radius if the agent is prompt-injected)",
+    )

invigil/checks/g1_stranger.py

@@ -0,0 +1,114 @@
+"""G1 — a stranger succeeds in 10 minutes on a clean machine (Discipline D1).
+
+These are the "is this even approachable?" checks: a real license, a landing-page
+README that stays a landing page, a copy-paste quickstart, and an env-var config
+surface instead of hardcoded values. Full G1 (the timed clean-machine boot) is
+proven dynamically by the Stranger Gate; these are its static preconditions.
+"""
+
+from __future__ import annotations
+
+from ..context import Context
+from ..model import CheckResult, Status
+from . import register
+
+README_MAX_LINES = 300
+
+
+@register(id="license-apache2", gate="G1", title="LICENSE present and Apache-2.0", weight=2, discipline="D1")
+def license_apache2(ctx: Context) -> CheckResult:
+    p = ctx.first_existing("LICENSE", "LICENSE.txt", "LICENSE.md")
+    check = license_apache2.__invigil__  # type: ignore[attr-defined]
+    if p is None:
+        return CheckResult(check, Status.FAIL, "no LICENSE file", "add an Apache-2.0 LICENSE at repo root")
+    text = p.read_text(errors="replace")
+    if "Apache License" in text and "Version 2.0" in text:
+        return CheckResult(check, Status.PASS, f"{p.name}: Apache-2.0")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        f"{p.name} is not Apache-2.0",
+        "replace with the Apache-2.0 text (project standard); see https://apache.org/licenses/LICENSE-2.0.txt",
+    )
+
+
+@register(id="readme-present", gate="G1", title="README exists", weight=1, discipline="D1")
+def readme_present(ctx: Context) -> CheckResult:
+    check = readme_present.__invigil__  # type: ignore[attr-defined]
+    p = ctx.first_existing("README.md", "README.rst", "README")
+    if p:
+        return CheckResult(check, Status.PASS, p.name)
+    return CheckResult(check, Status.FAIL, "no README", "add a README.md landing page")
+
+
+@register(
+    id="readme-length",
+    gate="G1",
+    title=f"README <= {README_MAX_LINES} lines (landing page, not the building)",
+    weight=1,
+    discipline="D1",
+)
+def readme_length(ctx: Context) -> CheckResult:
+    check = readme_length.__invigil__  # type: ignore[attr-defined]
+    p = ctx.first_existing("README.md", "README.rst", "README")
+    if p is None:
+        return CheckResult(check, Status.FAIL, "no README", "add a README.md")
+    n = len(p.read_text(errors="replace").splitlines())
+    if n <= README_MAX_LINES:
+        return CheckResult(check, Status.PASS, f"{n} lines")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        f"{n} lines (> {README_MAX_LINES})",
+        f"move deep sections into doc/ and link them; target <= {README_MAX_LINES} lines",
+    )
+
+
+@register(id="readme-quickstart", gate="G1", title="README has a Quick Start section", weight=1, discipline="D1")
+def readme_quickstart(ctx: Context) -> CheckResult:
+    check = readme_quickstart.__invigil__  # type: ignore[attr-defined]
+    text = ctx.read("README.md").lower()
+    if any(h in text for h in ("## quick start", "## quickstart", "## getting started", "## install")):
+        return CheckResult(check, Status.PASS, "quickstart heading found")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "no quickstart heading",
+        'add a "## Quick Start" section with <=5 copy-paste commands to first success',
+    )
+
+
+@register(
+    id="env-example",
+    gate="G1",
+    title="Config is env-var driven (.env.example present)",
+    weight=1,
+    mandatory=False,
+    discipline="D1",
+)
+def env_example(ctx: Context) -> CheckResult:
+    check = env_example.__invigil__  # type: ignore[attr-defined]
+    if ctx.first_existing(".env.example", ".env.sample", ".env.template"):
+        return CheckResult(check, Status.PASS, ".env.example present")
+    # Only fail if the repo clearly reads runtime env config: a compose file, or
+    # source that actually pulls from the environment. A `config.py` that parses a
+    # local YAML is NOT a runtime env surface — don't false-positive on it.
+    # Match call sites, not bare identifiers. Skip Invigil's own package source
+    # (which names these patterns) — a scanned app never contains it except when
+    # Invigil grades itself, so this only prevents a self-trigger.
+    env_patterns = ("os.getenv(", "os.environ[", "os.environ.get", "(BaseSettings)")
+    reads_env = any(
+        m in p.read_text(errors="replace")
+        for p in ctx.rglob("**/*.py")
+        if "/invigil/" not in str(p)
+        for m in env_patterns
+    )
+    has_surface = ctx.exists("docker-compose.yml") or ctx.exists("compose.yml") or reads_env
+    if not has_surface:
+        return CheckResult(check, Status.SKIP, "no runtime env-config surface")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "config surface exists but no .env.example",
+        "add a .env.example documenting every env var; replace hardcoded values (e.g. localhost)",
+    )

invigil/checks/g2_errors.py

@@ -0,0 +1,79 @@
+"""G2 — every failure mode tells the user the fix (Discipline D2).
+
+Errors are a product surface: a deep-health/preflight surface that names missing
+prerequisites before work starts, a global handler that returns a correlatable
+id instead of a leaked traceback, and error-path tests written first. These are
+detected heuristically from source; they're best-effort on non-Python stacks, so
+the softer ones are non-mandatory.
+"""
+
+from __future__ import annotations
+
+from ..context import Context
+from ..model import CheckResult, Status
+from . import register
+
+
+@register(
+    id="deep-health", gate="G2", title="Deep-health / dependency-preflight surface exists", weight=1, discipline="D2"
+)
+def deep_health(ctx: Context) -> CheckResult:
+    check = deep_health.__invigil__  # type: ignore[attr-defined]
+    if not ctx.is_web_service():
+        return CheckResult(check, Status.SKIP, "not an HTTP service")
+    # A health route that inspects deps, or a dedicated sysdeps/preflight module.
+    has_module = bool(ctx.rglob("**/sysdeps.py") or ctx.rglob("**/preflight.py"))
+    has_route = ctx.source_contains('"/health"', "'/health'", "/api/system/deps", "health?deep")
+    if has_module or has_route:
+        return CheckResult(check, Status.PASS, "sysdeps/health surface found")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "no deep-health / preflight surface",
+        "add a /health?deep=1 endpoint (or a sysdeps.py) that reports missing prereqs with the install command",
+    )
+
+
+@register(
+    id="error-correlation-id",
+    gate="G2",
+    title="Global handler returns a correlatable error id",
+    weight=1,
+    discipline="D2",
+)
+def error_correlation_id(ctx: Context) -> CheckResult:
+    check = error_correlation_id.__invigil__  # type: ignore[attr-defined]
+    if not ctx.is_web_service():
+        return CheckResult(check, Status.SKIP, "not an HTTP service")
+    has_handler = ctx.source_contains("exception_handler", "errorhandler", "add_exception_handler")
+    has_id = ctx.source_contains("error_id", "correlation_id", "request_id", "trace_id")
+    if has_handler and has_id:
+        return CheckResult(check, Status.PASS, "global handler + correlation id found")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "no global handler with a correlation id",
+        "add a global exception handler that logs a traceback under an error_id and returns that id (no leaked stack)",
+    )
+
+
+@register(
+    id="error-path-tests",
+    gate="G2",
+    title="Error-path tests exist (write them first)",
+    weight=1,
+    mandatory=False,
+    discipline="D2",
+)
+def error_path_tests(ctx: Context) -> CheckResult:
+    check = error_path_tests.__invigil__  # type: ignore[attr-defined]
+    named = bool(ctx.rglob("**/test_error*.py") or ctx.rglob("**/*error*_test.go"))
+    tagged = ctx.source_contains("ERR-", suffixes=(".py", ".go", ".ts", ".js"))
+    if named or tagged:
+        return CheckResult(check, Status.PASS, "error-path tests found")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "no obvious error-path tests",
+        "add tests for the failure modes (e.g. tests/test_error_surfacing.py), ideally before the fix",
+    )

invigil/checks/g3_supply.py

@@ -0,0 +1,120 @@
+"""G3 — machines watch what users won't report (Discipline D3).
+
+Repo CI tests source; these checks prove the supply-chain gates that make quality
+non-optional: a scheduled smoke-test of the *published* artifact, an enforced
+lockfile, a coverage floor, SHA-pinned actions, a version matrix, and Dependabot.
+All are read straight out of `.github/`.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ..context import Context
+from ..model import CheckResult, Status
+from . import register
+
+# `uses: owner/repo@REF` — a pin is a 40-hex SHA; anything else (tag/branch) is mutable.
+_USES = re.compile(r"uses:\s*([^\s@]+)@([^\s#]+)")
+_SHA = re.compile(r"^[0-9a-f]{40}$")
+
+
+@register(
+    id="smoke-published", gate="G3", title="Scheduled smoke-test of the published artifact", weight=2, discipline="D3"
+)
+def smoke_published(ctx: Context) -> CheckResult:
+    check = smoke_published.__invigil__  # type: ignore[attr-defined]
+    for p in ctx.workflow_files():
+        text = p.read_text(errors="replace")
+        looks_smoke = "smoke" in p.name.lower() or "published" in text.lower() or "clean venv" in text.lower()
+        if looks_smoke and "schedule:" in text:
+            return CheckResult(check, Status.PASS, f"{p.name} runs on a schedule")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "no scheduled published-artifact smoke test",
+        "add a scheduled workflow (or `uses: invigil/invigil/.github/workflows/stranger-gate.yml@v1`) "
+        "that installs+boots the published artifact daily",
+    )
+
+
+@register(id="dependabot", gate="G3", title="Dependabot configured", weight=1, discipline="D3")
+def dependabot(ctx: Context) -> CheckResult:
+    check = dependabot.__invigil__  # type: ignore[attr-defined]
+    if ctx.first_existing(".github/dependabot.yml", ".github/dependabot.yaml") or ctx.exists("renovate.json"):
+        return CheckResult(check, Status.PASS, "dependabot/renovate present")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "no dependency update bot",
+        "add .github/dependabot.yml for your ecosystems (pip/npm/docker/github-actions)",
+    )
+
+
+@register(
+    id="actions-sha-pinned",
+    gate="G3",
+    title="All GitHub Actions are SHA-pinned",
+    weight=1,
+    mandatory=False,
+    discipline="D3",
+)
+def actions_sha_pinned(ctx: Context) -> CheckResult:
+    check = actions_sha_pinned.__invigil__  # type: ignore[attr-defined]
+    unpinned: list[str] = []
+    for p in ctx.workflow_files():
+        for owner_repo, ref in _USES.findall(p.read_text(errors="replace")):
+            if owner_repo.startswith((".", "docker://")):  # local/composite or docker refs are fine
+                continue
+            if not _SHA.match(ref):
+                unpinned.append(f"{owner_repo}@{ref}")
+    if not unpinned:
+        return CheckResult(check, Status.PASS, "all actions pinned to SHAs")
+    sample = ", ".join(sorted(set(unpinned))[:3])
+    return CheckResult(
+        check,
+        Status.FAIL,
+        f"{len(set(unpinned))} unpinned action(s): {sample}",
+        "pin every `uses:` to a 40-char commit SHA (keep the version in a trailing comment)",
+    )
+
+
+@register(id="lockfile-enforced", gate="G3", title="Lockfile enforced in CI", weight=1, discipline="D3")
+def lockfile_enforced(ctx: Context) -> CheckResult:
+    check = lockfile_enforced.__invigil__  # type: ignore[attr-defined]
+    text = ctx.workflows_text()
+    if any(tok in text for tok in ("--locked", "--frozen", "npm ci", "--frozen-lockfile", "go mod verify")):
+        return CheckResult(check, Status.PASS, "lockfile enforced")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "CI installs without enforcing the lockfile",
+        "use `uv sync --locked` / `npm ci` / `--frozen-lockfile` so CI fails on lockfile drift",
+    )
+
+
+@register(id="coverage-gate", gate="G3", title="Coverage floor enforced in CI", weight=1, discipline="D3")
+def coverage_gate(ctx: Context) -> CheckResult:
+    check = coverage_gate.__invigil__  # type: ignore[attr-defined]
+    text = ctx.workflows_text() + ctx.read("pyproject.toml") + ctx.read("setup.cfg")
+    if any(tok in text for tok in ("--cov-fail-under", "fail_under", "cov-fail-under", "-covermode")):
+        return CheckResult(check, Status.PASS, "coverage floor enforced")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "no coverage floor in CI",
+        "add `--cov-fail-under=<N>` (or equivalent) so a coverage drop fails the build",
+    )
+
+
+@register(id="version-matrix", gate="G3", title="CI runs a version matrix", weight=1, mandatory=False, discipline="D3")
+def version_matrix(ctx: Context) -> CheckResult:
+    check = version_matrix.__invigil__  # type: ignore[attr-defined]
+    if "matrix:" in ctx.workflows_text():
+        return CheckResult(check, Status.PASS, "matrix build present")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "no build matrix",
+        "add a matrix over the runtimes you claim to support (e.g. python 3.11 + 3.12)",
+    )

invigil/checks/g4_evidence.py

@@ -0,0 +1,109 @@
+"""G4 — supply-chain evidence is public (Discipline D3, the enterprise door).
+
+A security-branded project is held to a higher bar, and meeting it publicly is
+itself marketing: an OpenSSF Scorecard workflow (and a >=7 score), signed
+releases with an SBOM, a security policy, and a changelog. The Scorecard score
+is read live from scorecard.dev; if the repo isn't published there yet the check
+degrades to SKIP rather than punishing an un-pushed repo.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+
+from ..context import Context
+from ..model import CheckResult, Status
+from . import register
+
+SCORECARD_MIN = 7.0
+
+
+@register(id="scorecard-workflow", gate="G4", title="OpenSSF Scorecard workflow present", weight=1, discipline="D3")
+def scorecard_workflow(ctx: Context) -> CheckResult:
+    check = scorecard_workflow.__invigil__  # type: ignore[attr-defined]
+    if "ossf/scorecard-action" in ctx.workflows_text() or ctx.first_existing(".github/workflows/scorecard.yml"):
+        return CheckResult(check, Status.PASS, "scorecard workflow present")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "no Scorecard workflow",
+        "add ossf/scorecard-action (scheduled) and publish the badge once >=7",
+    )
+
+
+@register(
+    id="scorecard-score",
+    gate="G4",
+    title=f"OpenSSF Scorecard >= {SCORECARD_MIN:.0f}",
+    weight=1,
+    mandatory=False,
+    discipline="D3",
+)
+def scorecard_score(ctx: Context) -> CheckResult:
+    check = scorecard_score.__invigil__  # type: ignore[attr-defined]
+    slug = ctx.repo_slug()
+    if not slug:
+        return CheckResult(check, Status.SKIP, "no github remote to look up")
+    try:
+        url = f"https://api.scorecard.dev/projects/github.com/{slug}"
+        with urllib.request.urlopen(url, timeout=8) as resp:  # noqa: S310 (fixed https host)
+            score = float(json.load(resp).get("score", 0))
+    except (urllib.error.URLError, TimeoutError, OSError):
+        # Network flake / not published yet: SKIP (excluded from the grade) so a
+        # timeout can never move the score. Resilience over a spurious downgrade.
+        return CheckResult(check, Status.SKIP, "scorecard.dev unreachable — excluded from grade")
+    except ValueError:
+        return CheckResult(check, Status.SKIP, "scorecard.dev returned no score yet")
+    if score >= SCORECARD_MIN:
+        return CheckResult(check, Status.PASS, f"score {score}")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        f"score {score} < {SCORECARD_MIN:.0f}",
+        "triage the Scorecard findings (branch protection, token perms, pinned deps) to reach >=7",
+    )
+
+
+@register(id="signed-releases-sbom", gate="G4", title="Releases are signed and ship an SBOM", weight=2, discipline="D3")
+def signed_releases_sbom(ctx: Context) -> CheckResult:
+    check = signed_releases_sbom.__invigil__  # type: ignore[attr-defined]
+    text = ctx.workflows_text()
+    signed = "cosign" in text or "sigstore" in text
+    sbom = "syft" in text or "sbom" in text.lower() or "spdx" in text.lower()
+    if signed and sbom:
+        return CheckResult(check, Status.PASS, "cosign + SBOM in release workflow")
+    missing = ", ".join(m for m, ok in (("signing (cosign)", signed), ("SBOM (syft)", sbom)) if not ok)
+    return CheckResult(
+        check,
+        Status.FAIL,
+        f"release evidence missing: {missing}",
+        "sign release artifacts with cosign (keyless) and attach a syft SPDX SBOM",
+    )
+
+
+@register(id="security-policy", gate="G4", title="SECURITY.md present", weight=1, discipline="D3")
+def security_policy(ctx: Context) -> CheckResult:
+    check = security_policy.__invigil__  # type: ignore[attr-defined]
+    if ctx.first_existing("SECURITY.md", ".github/SECURITY.md", "docs/SECURITY.md"):
+        return CheckResult(check, Status.PASS, "SECURITY.md present")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "no SECURITY.md",
+        "add SECURITY.md with a private report channel and a supported-versions table",
+    )
+
+
+@register(id="changelog", gate="G4", title="CHANGELOG.md present", weight=1, mandatory=False, discipline="D4")
+def changelog(ctx: Context) -> CheckResult:
+    check = changelog.__invigil__  # type: ignore[attr-defined]
+    if ctx.first_existing("CHANGELOG.md", "CHANGELOG.rst", "docs/CHANGELOG.md"):
+        return CheckResult(check, Status.PASS, "CHANGELOG present")
+    return CheckResult(
+        check,
+        Status.FAIL,
+        "no CHANGELOG",
+        "keep a CHANGELOG.md (Keep a Changelog format) with honest caveats per release",
+    )