vigil-public

README

Vigil

Vigil is a GitHub-adjacent release, configuration, preflight, and agent-safety tool for teams that want repository automation to explain itself before it mutates anything.

This public repository contains the open-source core:

• versioned JSON configuration;
• guided config creation and validation;
• local doctor, status, plan, verify, and support-bundle diagnostics;
• config-driven local preflight checks;
• git hook shims for pre-commit and pre-push;
• generic workspace hygiene, staged-secret, dependency inventory, and command catalog checks;
• extension manifest discovery and diagnostics;
• a small CLI surface that can be embedded into deployment-specific workflows.

Extension implementations can be added by deployments that need project-specific commands or policy surfaces.

Current Public Surface

Vigil is the public, standalone CLI foundation. It provides config diagnostics, local preflight checks, hooks, Scribe README automation, public adapter extensions, release-readiness checks, and a canonical GitHub Actions helper extension. Commands are composed from core plus loaded extensions, so extension commands appear only when their manifests are valid and enabled.

Repository Snapshot

Signal	Value
Repository	vigil-public
Dependency manifests	go.mod
Test paths	not detected
Vigil commands	66

Generated by Vigil Scribe from local repository facts.

Install

go install github.com/PayCal-Technologies/vigil-public/cmd/vigil@latest

Or build locally:

go build -o bin/vigil ./cmd/vigil

Quick Start

vigil init
vigil --allow-mutation setup:wizard
vigil config:validate
vigil init:ci
vigil doctor
vigil workflow:local --dry-run
vigil workflow:local
vigil extensions:doctor --json

vigil init is an alias for the interactive setup wizard. Running vigil without a command prints help and, on an interactive terminal, offers to start the wizard immediately.

GitHub-Adjacent Use

Vigil provides local preflight from vigil.config.json. Each check is a named shell command with metadata that tells humans and automation whether it is read-only. GitHub, reviewed repository configuration, and active workflow files remain the collaboration and hosted CI surfaces when a project uses them.

{
  "name": "go test",
  "command": "go test ./...",
  "read_only": true,
  "tags": ["test"]
}

Common commands:

vigil status --json
vigil plan
vigil workflow:local --dry-run
vigil workflow:local --json
vigil verify --json
vigil support:bundle --dry-run

Access Contract

Vigil reports one canonical access contract everywhere machine-readable metadata is exposed:

Canonical access	Help marker	Meaning
read	r	Does not mutate source, generated artifacts, operational state, or external systems.
write	w	Mutates by default unless the command exposes an explicit read-only override such as --dry-run or --check.
conditional-write	r/w	Read-only by default and mutates only when a registered write flag such as --write, --heal, --fix, or --execute is present.

Only vigil help uses compact markers. Manuals, command catalogs, guard summaries, extension contracts, and JSON output use canonical values. Extension commands with conditional-write access must declare write_flags; without those flags, Vigil treats the base invocation as a preview and does not require mutation confirmation.

Examples:

# Compact human index: conditional-write commands appear as r/w.
vigil help

# Canonical access values in command metadata.
vigil list --json

# Canonical guard classification for mutating commands.
vigil guards:summary --json

# Safe previews for conditional writers.
vigil init:ci
vigil github:init-ci
vigil config:migrate

# Confirm writes only when mutation is intentional.
vigil --allow-mutation init:ci --write
vigil --allow-mutation github:init-ci --write
vigil --allow-mutation config:migrate --write

# Always-write commands with real read-only overrides expose those flags.
vigil support:bundle --dry-run
vigil --allow-mutation support:bundle

# Extension contracts use write_flags to distinguish preview from mutation.
vigil github:init-ci
vigil --allow-mutation github:init-ci --write

Git hooks:

vigil hooks:install

This installs pre-commit and pre-push hook shims that run configured Vigil preflight checks.

Built-in public checks:

vigil checks:staged-sensitive
vigil checks:workspace-hygiene
vigil checks:command-catalog --json
vigil checks:public-assumptions --json
vigil checks:public-parity --json
vigil deps:inventory --json
vigil checks:dependency-security --json
vigil security:gitleaks
vigil checks:tracked-assistant-artifacts --json

Config

Vigil uses JSON for configuration. A repo-local vigil.config.json is the default. Vigil searches upward from the current directory for that file, and --config PATH can point Vigil at an explicit file.

vigil config:schema
vigil config:init --profile=go-tool --write
vigil --config ./candidate.vigil.config.json config:validate --json
vigil config:repair
vigil config:repair --yes

The current schema version is 2. config:migrate upgrades legacy v1 authority.mutation_requires into v2 coordination.mutation_requires without dropping custom requirements such as clean-tree.

config:validate --json returns machine-readable structured_issues and a repair hint. config:repair uses classic command-line stdin prompts and shows [default: value] for answers that can be accepted by pressing enter. --yes applies the default repair without prompting.

public_assumption_patterns is the config-owned deny-list used by checks:public-assumptions. Keep project-specific terms in config rather than hardcoding them into Vigil.

Terminal output uses [OK], [FAIL], and [WARN] status labels. Labels are colorized on interactive terminals and stay plain when NO_COLOR or CI is set.

Extensions

Extensions are described by extensions/<id>/extension.json. The public core validates extension manifests and reports which extensions are available. Invalid manifests fail closed: their validation issues are reported by extensions:doctor, but their commands are excluded from the loaded command set. Extension manifests currently use schema version 1; the config schema version is independent.

{
  "schema_version": "1",
  "id": "example",
  "name": "Example Extension",
  "kind": "custom",
  "status": "local",
  "private": false,
  "public_core": true,
  "description": "Example extension.",
  "source_root": "extensions/example",
  "packages": [],
  "commands": []
}

Use:

vigil extensions:list
vigil extensions:doctor --json

Command contracts must use canonical access values: read, write, or conditional-write. Shorthand such as r/w is display-only help text and is rejected in manifests. Conditional-write contracts must also declare write_flags, for example:

{
  "command": "github:init-ci",
  "access": "conditional-write",
  "write_flags": ["--write"],
  "usage": "vigil github:init-ci [--write] [--json]",
  "description": "Generate a GitHub Actions workflow from Vigil gates."
}

Public extensions included in this repository:

• file-iterator: canonical command-extension example.
• scribe: README managed-block generation and freshness checks.
• a11y-adapters: accessibility adapter commands for local route and browser audit tools.
• dependency-adapters: dependency explanation and package-manager audit commands.
• deploy-verify: generic endpoint verification.
• github-cicd: canonical GitHub Actions workflow generation.
• release-policy: generic clean-tree and version-source release readiness.
• security-adapters: local scanner command contracts.
• test-adapters: generic test history and affected-test helpers.
• repo-health: lightweight git-history diagnostics.

Golden Extension Example

The public repository includes extensions/file-iterator/ as the canonical example extension. It models a read-only CLI command, files:iterate, that would walk matching files and emit structured output.

vigil extensions:list
vigil files:iterate --root=. --glob='**/*.go' --jsonl

Scribe

Scribe is Vigil's README automation extension: a repo can keep human-authored README sections intact while a managed block is generated from stable local project signals.

vigil readme:generate
vigil readme:check

Mutation confirmation is enforced at the CLI boundary. Commands that write files require --allow-mutation, except commands explicitly marked auto_enabled in the command catalog. Today readme:generate may run with --auto because its output is deterministic and idempotent: repeated runs converge on the same managed block while preserving human-authored README content.

README freshness can also be represented as a normal config check:

{
  "name": "readme freshness",
  "command": "vigil readme:check",
  "read_only": true,
  "tags": ["docs"]
}

Public Adapters

Vigil includes public adapter extensions for common local checks:

vigil a11y:inventory
vigil a11y:pa11y https://example.test
vigil a11y:lighthouse https://example.test
vigil a11y:playwright
vigil checks:dependency-security --json
vigil deps:why react
vigil repo:health --json
vigil checks:release-policy --json
vigil deploy:verify --url https://example.test --json
vigil tests:history --json
vigil tests:affected --json
vigil javascript:quality --json
vigil php:lint --json
vigil guards:summary --json
vigil self-heal:plan --json
vigil next --json
vigil init:ci --provider=github
vigil github:init-ci --write
vigil config:migrate --json
vigil help config:report

These commands are intentionally local-first. Missing tools are reported directly, and teams can replace or supplement adapter commands with their own vigil.config.json checks.

GitHub Actions

Vigil can generate a public GitHub Actions workflow that runs local preflight checks inside GitHub Actions:

vigil init:ci --provider=github
vigil github:init-ci --write

The canonical github-cicd extension contributes github:init-ci as the GitHub-specific command contract. See examples/github-vigil.yml and examples/vigil.config.json.

Releases

Public binary release guidance lives in docs/releasing.md. Homebrew packaging guidance lives in docs/homebrew-packaging.md.

Feedback

Ideas, feature requests, packaging reports, and rough-edge notes are welcome. Open a GitHub issue using the feature request or packaging feedback templates, or start a discussion in the repository once discussions are enabled.

Security reports should follow SECURITY.md instead of public issues.

License

Vigil is open source under the 0BSD license. See LICENSE.

Ethos

Vigil treats automation as an accountable system. It should make coordination, configuration, risk, and mutation boundaries explicit enough for both a human maintainer and an AI agent to understand what is safe, what is missing, and what needs confirmation.