Skip to content

[codex] raise README standard #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
paladini merged 1 commit into from
Jun 28, 2026
Merged

[codex] raise README standard #3

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 129 additions & 52 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,49 +3,106 @@
[![CI](https://github.com/paladini/specgov/actions/workflows/ci.yml/badge.svg)](https://github.com/paladini/specgov/actions/workflows/ci.yml)
[![MIT License](https://img.shields.io/badge/license-MIT-0f766e.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-2f6f4e.svg)](https://paladini.github.io/specgov/)

Govern the specs your code is supposed to honor.

SpecGov is a framework-agnostic governance layer for spec-driven development in
Git repositories. It does not invent a new spec format. It lets you declare the
requirements, ADRs, product docs, `.specs` folders, Kiro specs, Spec Kit plans,
or custom artifacts that already define your system, then checks whether code
changes keep those artifacts in the loop.

The core is deterministic by design: no API keys, no hosted service, no model
calls, and no vendor lock-in. You can run it locally, in CI, or as a GitHub
Action.
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](package.json)
[![Status](https://img.shields.io/badge/status-pre--release-f59e0b.svg)](#project-status)

**Spec governance for Git repositories. Keep code, docs, ADRs, requirements,
and spec folders aligned in every pull request.**

SpecGov is a deterministic CLI and GitHub Action for teams that use specs as
engineering contracts. It maps implementation paths to the source-of-truth
artifacts that explain them, then reports when code changes bypass those
artifacts.

It is not another spec framework. SpecGov works with the files you already
have: product requirements, ADRs, design docs, `.specs` folders, Kiro specs,
Spec Kit plans, and custom Markdown contracts.

- **Framework agnostic:** Bring any spec convention and describe it in one
`.specgov.yml` manifest.
- **PR native:** Run locally or as a GitHub Action during review.
- **Advisory first:** Start with warnings, then move trusted areas to strict
enforcement.
- **Audit friendly:** Emit Markdown for humans and JSON for automation.
- **Private by default:** No hosted service, API key, model call, telemetry, or
repository upload.

## Contents

- [Why SpecGov exists](#why-specgov-exists)
- [How it works](#how-it-works)
- [Core capabilities](#core-capabilities)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Manifest](#manifest)
- [Commands](#commands)
- [GitHub Action](#github-action)
- [Adoption recipes](#adoption-recipes)
- [Report example](#report-example)
- [Enterprise-friendly defaults](#enterprise-friendly-defaults)
- [How SpecGov differs from SpecTrace](#how-specgov-differs-from-spectrace)
- [Development](#development)
- [Security and privacy](#security-and-privacy)
- [Project status](#project-status)

## Why SpecGov exists

Spec-driven development works until Git quietly merges implementation changes
that bypass the spec layer. Over time, reviewers stop trusting requirements,
ADRs become archaeology, and AI-assisted changes become harder to audit.

SpecGov gives teams a small, explicit contract:
Spec-driven development breaks down when Git accepts code-only pull requests
for behavior that was supposed to be governed by requirements, ADRs, product
docs, or design plans. The result is familiar:

- requirements become stale after the implementation moves on;
- ADRs lose authority because reviewers cannot see when they were bypassed;
- AI-assisted changes become hard to audit after the conversation is gone;
- teams adopt multiple spec formats, then lose one shared governance layer;
- compliance and platform teams need traceability without a heavyweight tool.

SpecGov gives repositories a small contract:

1. Declare the artifacts that define expected behavior.
2. Map code paths to the artifacts that must move with them.
3. Check pull requests for missing spec impact.
4. Generate trace and drift reports that humans and automation can inspect.

## How it works

```mermaid
flowchart LR
artifacts["Docs, ADRs, specs, and plans"]
manifest[".specgov.yml"]
changes["Changed code paths"]
specgov["SpecGov CLI or Action"]
report["Markdown or JSON report"]
review["Reviewers and CI"]

artifacts --> specgov
manifest --> specgov
changes --> specgov
specgov --> report
report --> review
```

- Which files are governed artifacts?
- Which code paths depend on which artifacts?
- Did this pull request update the right spec, doc, ADR, or plan?
- Which artifacts are stale, orphaned, superseded, or missing ownership?
- Can a human or future AI auditor reconstruct the trace later?
SpecGov does not parse your business logic or invent a new workflow. It reads
your manifest, discovers governed artifacts, compares changed files with your
declared mappings, and reports whether the review has enough spec context.

## What SpecGov checks
## Core capabilities

| Capability | What it does |
| ------------------ | ---------------------------------------------------------------- |
| Artifact discovery | Finds governed docs, ADRs, specs, and requirements from globs. |
| Lifecycle metadata | Reads optional YAML frontmatter such as `status` and `owner`. |
| PR impact checks | Flags code changes that do not touch mapped spec artifacts. |
| Unmapped code | Finds changed files outside your declared code-to-spec map. |
| Trace index | Emits JSON linking artifacts, mappings, and matched files. |
| Drift report | Reports stale, empty, orphaned, or superseded artifacts. |
| GitHub Action | Runs the same deterministic check inside pull request workflows. |
| Capability | What it gives you |
| ----------------------- | ------------------------------------------------------------ |
| Artifact discovery | Finds governed docs, ADRs, specs, and requirements by glob. |
| Lifecycle metadata | Reads optional `status`, `owner`, and verification metadata. |
| PR impact checks | Flags code changes that skip mapped spec artifacts. |
| Unmapped code detection | Finds changed files outside your declared governance map. |
| Trace index | Emits JSON linking artifacts, mappings, and matched files. |
| Drift report | Reports stale, empty, orphaned, or superseded artifacts. |
| GitHub Action | Runs the same deterministic checks inside pull requests. |
| Advisory/strict modes | Lets teams observe first, then block trusted paths later. |

## Installation

SpecGov is currently pre-release. Until the first npm package and version tag
are published, install it from source:
SpecGov is pre-release. Until the first npm package and version tag are
published, install it from source:

```bash
git clone https://github.com/paladini/specgov.git
Expand Down Expand Up @@ -79,13 +136,13 @@ specgov trace --out .specgov.trace.json
specgov drift
```

`specgov init` creates `.specgov.yml`. Start in `advisory` mode so teams can
see findings without blocking merges, then switch selected repositories or
paths to `strict` when the mapping is trusted.
Start in `advisory` mode so contributors can see findings without blocking
merges. Move selected repositories or paths to `strict` after the mapping has
earned trust in real pull requests.

## Manifest

SpecGov uses one YAML manifest:
SpecGov is configured with one YAML file:

```yaml
version: 1
Expand Down Expand Up @@ -124,19 +181,19 @@ ignore:

### Governed artifacts

Each entry in `artifacts` tells SpecGov which files belong to your spec layer.
Use any folder convention you already have:
Each `artifacts` entry tells SpecGov which files belong to your spec layer. Use
the folder convention your team already has:

- `docs/**/*.md` for product or engineering docs.
- `adr/**/*.md` for architectural decisions.
- `.specs/**/*.md` for TLC Spec Driven or custom specs.
- `.kiro/specs/**/*.md` for Kiro-style spec folders.
- `specs/**/*.md` for Spec Kit or other repository-local plans.
- `specs/**/*.md` for Spec Kit or repository-local plans.

### Code-to-spec mappings

Each entry in `mappings` connects implementation paths to the artifacts that
must move with them. If `src/auth/**` changes and no mapped artifact changes,
Each `mappings` entry connects implementation paths to the artifacts that must
move with them. If `src/auth/**` changes and no mapped artifact changes,
SpecGov reports `SPEC_IMPACT_MISSING`.

When `require_spec_impact_for_code_changes` is enabled, SpecGov also reports
Expand All @@ -154,7 +211,7 @@ owner: platform
last_verified: 2026-06-27
---

# Authentication Session Contract
# Authentication session contract
```

Supported statuses are `draft`, `active`, `superseded`, `deprecated`, and
Expand All @@ -171,8 +228,8 @@ where the current source of truth moved.
| `specgov trace` | Generate a machine-readable trace index. | Automation and audits. |
| `specgov drift` | Report stale, empty, orphaned, or superseded specs. | Maintenance reviews. |

All report commands default to Markdown output. Use `--format json` for
automation:
All report commands default to Markdown output. Use `--format json` when
another tool needs to consume the result:

```bash
specgov scan --format json
Expand All @@ -181,13 +238,13 @@ specgov check-pr --format json --changed-file src/payments/checkout.ts

Exit codes:

- `0`: pass, or warning in `advisory` mode.
- `0`: pass, or warnings in `advisory` mode.
- `1`: governance failure in `strict` mode.
- `2`: runtime or configuration error.

## GitHub Action

Add SpecGov to pull requests with a workflow like this:
Run SpecGov on pull requests:

```yaml
name: SpecGov
Expand Down Expand Up @@ -235,7 +292,7 @@ Use `mode: strict` when governance findings should block the pull request.

## Adoption recipes

The `examples/` folder includes starter manifests:
The `examples/` folder includes starter manifests for common repository shapes:

| Repository style | Example |
| ----------------- | ------------------------------------------------------------------------------------ |
Expand Down Expand Up @@ -275,6 +332,20 @@ Findings: 1 (0 errors, 1 warnings, 0 info)
this mapping is ready to enforce.
```

## Enterprise-friendly defaults

SpecGov is small, but its defaults are designed for serious engineering teams:

- **No data leaves your runner.** SpecGov reads local files and git metadata.
- **No vendor workflow lock-in.** The manifest points to any docs, ADRs, or
spec folders your organization already uses.
- **No all-at-once migration.** Advisory mode lets teams learn before
enforcement.
- **Machine-readable outputs.** JSON reports can feed dashboards, policy jobs,
or release evidence.
- **Review-first governance.** Findings appear where engineers already make
decisions: pull requests and local checks.

## How SpecGov differs from SpecTrace

SpecTrace for AI Coding verifies whether a specific AI-assisted change
Expand Down Expand Up @@ -305,10 +376,16 @@ request.
## Security and privacy

SpecGov runs locally or in your CI runner. Version 0.1 does not call external
services, require API keys, or send repository contents to a model. See
[`SECURITY.md`](SECURITY.md) for vulnerability reporting.
services, require API keys, or send repository contents to a model.

See [`SECURITY.md`](SECURITY.md) for vulnerability reporting.

## Project status

SpecGov is in pre-release development. The CLI, report shape, and Action inputs
are usable today, but may still change before the first tagged release.

## Project links
Current project links:

- Website: <https://paladini.github.io/specgov/>
- Repository: <https://github.com/paladini/specgov>
Expand Down