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

• Generated command overview for humans
• AI-agent 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 pylint 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.

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:

1. Outside-in research on the workflow or drift problem
2. Public OpenSpec proposal and spec deltas
3. TDD evidence before implementation
4. Dogfooding with specfact code review
5. Format, type-check, contract-test, and docs quality gates
6. PR review with evidence artifacts
7. 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, and govern.

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

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