SpecGov

Deterministic spec governance for Git

Govern the specs your code is supposed to honor.

SpecGov keeps requirements, ADRs, product docs, and spec folders aligned with pull requests without API keys, hosted services, or model calls.

Start using SpecGov View source
SpecGov pull request report showing an advisory warning for a code change without related spec impact.
No new spec format Bring your existing docs, ADRs, `.specs`, Kiro, or Spec Kit files.
No secrets Runs locally and in CI with deterministic checks.
No surprise blocking Start advisory, then opt into strict enforcement.

The drift problem

Specs fail when Git can bypass them.

Modern teams write requirements, ADRs, implementation plans, and AI-facing specs, then review code in a separate workflow. SpecGov connects those layers so reviewers can see when a pull request changes implementation without updating the artifacts that explain the intended behavior.

It is intentionally small: a YAML manifest, deterministic file discovery, code-to-spec mappings, lifecycle metadata, Markdown reports, JSON trace output, and a GitHub Action wrapper.

Mechanics

A manifest turns your repo into a governed map.

01

Declare artifacts

Mark docs, ADRs, requirements, and spec folders as governed artifacts.

02

Map code paths

Connect implementation directories to the artifacts that must move with them.

03

Check pull requests

Report missing spec impact, unmapped code, lifecycle gaps, and drift.

Quick start

Install from npm, then govern any repo.

Use the CLI locally or in CI without adopting a new spec format.

Install
npm install -g specgov
npx specgov --help
Use in your repository
specgov init
specgov scan
specgov check-pr --changed-file src/auth/session.ts
specgov trace --out .specgov.trace.json
specgov drift

Manifest

Adopt with one `.specgov.yml` file.

Start with one high-value mapping. Expand gradually after the first advisory findings make sense to reviewers. 

version: 1
mode: advisory

artifacts:
  - path: "docs/**/*.md"
    kind: documentation
    owner: docs
  - path: "adr/**/*.md"
    kind: decision
    owner: architecture

mappings:
  - code: "src/auth/**"
    specs:
      - "docs/auth/**"
      - "adr/auth/**"

rules:
  require_spec_impact_for_code_changes: true
  stale_after_days: 180

Commands

Five commands cover setup, review, and maintenance.

specgov init Create a starter manifest.
specgov scan Discover governed artifacts and lifecycle findings.
specgov check-pr Compare changed files against code-to-spec mappings.
specgov trace Write machine-readable trace JSON.
specgov drift Report stale, empty, orphaned, or superseded artifacts.

GitHub Action

Put governance in the pull request.

Advisory mode gives teams visibility without blocking adoption. Strict mode turns warnings into a failing check. 

name: SpecGov

on:
  pull_request:

jobs:
  specgov:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - uses: paladini/specgov@v0.1.0
        with:
          mode: advisory
          base-ref: ${{ github.event.pull_request.base.sha }}
          head-ref: ${{ github.event.pull_request.head.sha }}

Adoption paths

Use your existing repository style.

Docs-only

Map `src/**` to `docs/**` for product or engineering docs.

View example

ADR-heavy

Require code areas to move with matching ADR and product docs.

View example

Framework folders

Govern `.specs`, `.kiro/specs`, or custom framework folders.

View example

Searchable answers

Spec governance without a new process.

What does SpecGov check?

SpecGov checks whether changed code paths map to requirements, ADRs, product docs, or spec folders. It reports missing spec impact, stale artifacts, lifecycle gaps, and unmapped code.

Does SpecGov need API keys or model calls?

No. SpecGov runs locally and in CI with deterministic checks, so it does not require API keys, hosted services, or model calls.

Can SpecGov work with existing spec formats?

Yes. SpecGov maps existing docs, ADRs, .specs folders, Kiro specs, Spec Kit files, or custom paths through a small .specgov.yml manifest.