Invigil

Linters check your code. Invigil checks whether your project is legible.

Ruff has your syntax. Dependabot has your dependencies. Scorecard has your supply chain. Nothing checks whether someone arriving cold can act on the project: boot it in ten minutes, get an error that tells them the fix, install the thing from PyPI today, read a README that's still a landing page and not a 600-line wall.

That's the test every project takes when someone new finds it — a new engineer, or increasingly an AI agent with a context window instead of patience. If they can't reach "hello world" in 10 minutes, they leave. If the published artifact is broken because CI only tests the source tree, they leave. If the error is a silent stack trace, they leave. Nobody files an issue on the way out.

Invigil turns those promises into mechanical checks, runs them in CI, and prints the exact fix for every failure — so the project speaks for itself.

invigilate — to watch over an exam and enforce its rules.

How Invigil fits in your stack

Invigil does not replace your existing tools; it covers the product-quality gaps they leave behind.

Why

You already wrote the doctrine; you just enforce it by hand. Every failing Invigil check tells you what's wrong, why it matters, and the exact command to fix it — because a gate that can't tell you how to pass it is the same broken-error-message anti-pattern it's meant to catch.

It grades against seven Gates, each a legibility promise to a different cold-start reader:

A repo reaches Gn only when every mandatory check for gates ≤ n passes, and gets a letter grade from its weighted score.

Install

One tool, four doors — pick the one that matches where you run it:

Every release ships all of it signed: cosign-signed wheel, sdist, and container image, plus an SPDX SBOM — verifiable with cosign verify against the GitHub OIDC identity.

Quick Start

Run it locally on any repo:

pip install invigil
invigil score .            # human-readable scorecard + the exact fix for every failure
invigil score . --format markdown   # a PR-comment-ready table
invigil score . --format json       # machine-readable

Add it to CI as a report-only gate (posts a scorecard comment + badge, never blocks a PR):

# .github/workflows/quality-gate.yml
name: Quality gate
on: [pull_request]
permissions: { contents: read, pull-requests: write }
jobs:
  invigil:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1        # v7.0.1
      - uses: invigil/invigil@7f31330715bb7e42f26032ce3e921fcf78d4acea        # v1.7.1
        with:
          enforce: "false"              # flip to true once the grade is stable

Flip enforce: "true" (or set project.enforce: true in .invigil.yml) when you're ready for it to block merges below the target gate.

Why the SHAs? invigil/invigil@v1 works and tracks the latest v1.x.y, but Invigil's own actions-sha-pinned check (G3) fails floating tags — including its own. Pin, and let Dependabot bump the pins; the trailing comment is what it reads.

The action exposes the report and both badges as step outputs — pipe the scorecard into the job summary, publish the badge JSON wherever shields.io can reach it:

      - uses: invigil/invigil@7f31330715bb7e42f26032ce3e921fcf78d4acea        # v1.7.1
        id: invigil
        with: { comment: "false" }
      - run: cat "${{ steps.invigil.outputs.report }}" >> "$GITHUB_STEP_SUMMARY"
      # outputs.badge → grade badge JSON · outputs.ai-badge → ai-ready badge JSON

How it works

Two layers, matching the doctrine:

• Static Doctrine Scorecard (every PR, seconds) — inspects the repo filesystem and GitHub metadata: LICENSE, README length, .env.example, a deep-health endpoint, a global error-id handler, SHA-pinned actions, an enforced lockfile, a coverage gate, a daily published-artifact smoke test, ≥5 good-first-issues, docs index, llms.txt/AGENTS.md, and more. Emits text / JSON / Markdown / a shields.io badge.
• Cold-Start Gate (nightly, reusable — invigil stranger) — on a clean runner, installs and boots each published artifact you declare and probes its core surface within a 10-minute budget. Web services get HTTP probes; a CLI image (an artifact with a command:) is run to completion and must exit 0. One reusable workflow replaces the 60-line smoke-published.yml every repo copy-pastes:

# .github/workflows/stranger-gate.yml
name: Cold-start gate
on:
  schedule: [{ cron: "0 3 * * *" }]
  workflow_dispatch:
jobs:
  stranger:
    uses: invigil/invigil/.github/workflows/stranger-gate.yml@7f31330715bb7e42f26032ce3e921fcf78d4acea  # v1.7.1

Fix by PR (Dependabot-for-legibility)

Opt in to a scheduled bot that applies Invigil's mechanical fixes on a work branch and opens one batched PR — governance scaffolds, agent context files, config hygiene. Three anti-noise rules are built in: it's opt-in only, one stable branch means one PR (never five), and a PR you close unmerged is a "no" the bot respects — it stays silent until you delete the invigil/fixes branch.

# .github/workflows/legibility-fixes.yml
name: Legibility fixes
on:
  schedule: [{ cron: "0 6 1 * *" }]   # monthly — these are one-time scaffolds, not deps
  workflow_dispatch:
jobs:
  fix:
    uses: invigil/invigil/.github/workflows/fix-pr.yml@7f31330715bb7e42f26032ce3e921fcf78d4acea  # v1.7.1

Under the hood it runs invigil score --fix --pr-mode: the fix engine's CI-lockout stays in force for protected branches — --pr-mode only permits fixes on a non-default branch, so nothing automated ever lands on main without a human merging the PR.

Configuration

Drop a .invigil.yml at the repo root. It's optional for the static scorecard (sensible defaults apply) and required for the Cold-Start Gate (it declares what to boot and probe). Full schema in schema/invigil.schema.json; examples in examples/.

version: 1
project:
  name: my-app
  language: python
  min_gate: G4
  enforce: false
artifacts:
  - type: pypi
    name: "my-app[all]"
  - type: ghcr
    image: ghcr.io/me/my-app:latest
    port: 8000
probes:
  - { url: "/", expect_status: 200 }
  - { url: "/api/things", expect_json_count: { min: 5 } }
boot_budget_minutes: 10

Lightweight & modular

A gate developers bypass is dead weight, so Invigil is built for zero friction:

• Fast offline groups for pre-commit — each check is tagged local/network/heavy. invigil check layout runs the filesystem checks with no network in ~120ms:

  yaml

  Copy

  # .pre-commit-config.yaml
  - repo: https://github.com/invigil/invigil
    rev: v1        # tracks the latest v1.x.y
    hooks: [{ id: invigil-layout }, { id: invigil-secrets }]