SpecFact CLI

Defend AI-assisted Python code from bloat before it reaches PR. Run deterministic review, cleanup forecasts, and spec/contract evidence locally.

No API keys required. Works offline. Zero vendor lock-in.

Documentation • Modules • Support

Command Overview

Try it in 60 seconds

# Zero-install, no API key, works offline
uvx specfact-cli init --profile solo-developer
uvx specfact-cli code review run --path . --scope full

Sample output:

SpecFact CLI - v0.47.4

Running Ruff checks...
Running Radon complexity checks...
Running Semgrep rules...
Running AST clean-code checks...
Running basedpyright type checks...
Running Ruff lint policy checks...
Running contract checks...
Running targeted tests and coverage...

Verdict: FAIL | CI exit: 1 | Score: 0 | Reward delta: -80

Findings:
  - specfact_demo/enforcement.py:96   Cyclomatic complexity for run_enforcement is 16.
  - specfact_demo/main.py:81          Avoid print() in source files; use structured logging instead.
  - examples/buggy_math.py:4          Public function divide is missing @require/@ensure decorators.

Evidence bundle: docs/_support/readme-first-contact/sample-output/

⭐ Star this repo if the output is useful. Open an issue if you want the workflow adapted for your stack.

Already installed the CLI? Use:

specfact init --profile solo-developer
specfact code review run --path . --scope full

The sample output comes from a pinned capture against nold-ai/specfact-demo-repo. Reproduce it with docs/_support/readme-first-contact/capture-readme-output.sh; capture metadata lives alongside the raw logs in docs/_support/readme-first-contact/sample-output/.

AI-bloat defense loop

SpecFact is the local AI-bloat defense CLI for Python-first teams using AI IDEs. The Code Review bundle reports ai_bloat advisories for code shapes that AI-assisted coding often amplifies: redundant wrappers, passthrough lambdas, identity try/except blocks, avoidable intermediate lists, and long low-branch functions.

For cleanup work, run a JSON review, inspect the cleanup forecast and AI-bloat index, hand remediation packets to your AI IDE, accept only safe changes, then re-run review for proof. The JSON report is the portable handoff artifact for Claude, Codex, Cursor, Copilot, or a headless agent.

These findings are bloat-shape detection and cleanup guidance, not AI-authorship detection. Exact simplify flags and report fields live in the AI bloat quickstart and Code Review run guide on the modules docs site.

Official workflow package IDs are nold-ai/specfact-project, nold-ai/specfact-backlog, nold-ai/specfact-codebase, nold-ai/specfact-code-review, nold-ai/specfact-spec, nold-ai/specfact-govern, and nold-ai/specfact-requirements.

What SpecFact does

Defends against AI bloat deterministically — forecast cleanup impact and route remediation packets to your AI IDE
Reviews AI-assisted changes against evidence — compare code against contracts, clean-code rules, and policy gates
Extracts structure from existing code — reverse-engineer brownfield repos before you change them
Blocks drift before merge — use the same checks locally, in pre-commit, and in CI
Consumes upstream planning inputs — treat Spec Kit, OpenSpec, backlog, specs, tests, and contracts as validation evidence
Stays local-first — no cloud account, no vendor lock-in, no built-in model dependency

What is SpecFact?

SpecFact is a local CLI for AI-bloat defense, deterministic code review, and backlog/spec/code drift control. It gives solo developers, legacy maintainers, and teams a validation layer around AI-assisted delivery, brownfield reverse engineering, and contract-first reviews.

It exists because delivery drifts in predictable ways:

AI-assisted code lands faster than cleanup and validation catch up
brownfield systems rarely have trustworthy up-to-date specs
backlog intent gets reinterpreted before it reaches code
teams need the same review rules across IDEs, CI, and pull requests

Add SpecFact to your workflow

Pre-commit hook

This repository uses a modular local hook layout (parity with specfact-cli-modules: fail_fast, separate verify / format / YAML / Markdown / workflow / lint / Block 2 hooks). If you copy .pre-commit-config.yaml into another repo, you must also vendor the referenced scripts/*.sh entrypoints (at minimum scripts/pre-commit-quality-checks.sh, scripts/pre-commit-verify-modules.sh, scripts/module-verify-policy.sh, and scripts/git-branch-module-signature-flag.sh) so hook entry: paths resolve. Alternatively, skip vendoring the modular file and use the remote hook below.

For a single-hook setup in downstream repos, keep using the stable id and script shim:

- repo: https://github.com/nold-ai/specfact-cli
  rev: v0.47.4
  hooks:
    - id: specfact-smart-checks

The shim runs scripts/pre-commit-quality-checks.sh all (full pipeline including module verify).

GitHub Actions

- name: SpecFact Gate
  run: uvx specfact-cli@latest govern enforce stage --preset minimal

How SpecFact is built

SpecFact uses the same discipline it asks you to trust:

Outside-in research on the workflow or drift problem
Public OpenSpec proposal and spec deltas
TDD evidence before implementation
Dogfooding with specfact code review
Format, type-check, contract-test, and docs quality gates
PR review with evidence artifacts
Release through the same reproducible CLI paths

For teams and organizations

SpecFact still scales beyond the solo-developer entry path, but validation stays the center:

Upstream context adapters for GitHub, Azure DevOps, Jira, Linear, OpenSpec, and Spec Kit inputs
DoR/DoD and policy enforcement for teams that need repeatable gates
Evidence-backed PR review with the same checks used locally
CI/CD adoption path that keeps validation deterministic instead of model-driven

Optional module-deep paths include:

specfact project import ...
specfact spec validate ...
specfact backlog verify-readiness --bundle <bundle-name>
specfact govern ...

Module system

Official workflow behavior ships from nold-ai/specfact-cli-modules. The core CLI owns bootstrap, runtime contracts, trust checks, logging, and the grouped command surface. Installed modules add families such as project, backlog, code, spec, govern, and requirements.

Install examples:

specfact module install nold-ai/specfact-project
specfact module install nold-ai/specfact-backlog
specfact module install nold-ai/specfact-codebase
specfact module install nold-ai/specfact-code-review
specfact module install nold-ai/specfact-govern
specfact module install nold-ai/specfact-spec
specfact module install nold-ai/specfact-requirements

If startup warns that modules are missing or outdated, run:

specfact module init --scope project
specfact module init

Documentation topology

docs.specfact.io is the canonical starting point for SpecFact.

Core CLI/runtime/platform documentation remains owned by specfact-cli
Module-specific deep docs are canonically owned by specfact-cli-modules
The live modules docs site is published at https://modules.specfact.io/

Use this repository's docs for the product story, runtime lifecycle, command topology, trust model, and getting-started flow. Use the modules docs site when you want deeper workflow, adapter, and module-authoring guidance.

How do I get started if I want more?

Next steps:

Core CLI docs for the core runtime, bootstrap, and validation flow
Installation guide for uvx-first and persistent CLI setup
Quickstart for the first repo review path
Reference: command topology for grouped command surfaces
Canonical modules docs site for bundle-deep workflows

Metadata

Release files for specfact-cli 0.55.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for specfact-cli 0.55.4
File	Interpreter	ABI	Platform	Reset
specfact_cli-0.55.4-py3-none-any.whl 788.7 kB Sep 6, 2026	Python 3	none	any	Details

Release files / specfact_cli-0.55.4-py3-none-any.whl

Download URL	specfact_cli-0.55.4-py3-none-any.whl
Size	788.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`aac27b5b1d9d96990510f22797316909ed78e38590ab77bc72eff9d51b65f4b5`
BLAKE2b-256 checksum How to use checksums	`4429b4ea0255ab7d7ccd0ba13c021745275a6ab4151349b27f070c37f3412163`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`