{"id":34881996,"url":"https://github.com/nold-ai/specfact-cli","last_synced_at":"2026-05-04T00:02:19.207Z","repository":{"id":322538985,"uuid":"1085706003","full_name":"nold-ai/specfact-cli","owner":"nold-ai","description":"The Swiss-knife CLI for validation and alignment in software delivery. Keep backlog intent, specs, tests, and code in sync across AI-assisted and brownfield delivery.","archived":false,"fork":false,"pushed_at":"2026-04-10T22:19:15.000Z","size":11001,"stargazers_count":15,"open_issues_count":77,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T22:23:39.587Z","etag":null,"topics":["ai","backlog-refinement","brownfield","code2spec","context-engineering","contract-enforcement","contract-first","contract-testing","contracts","copilot","kanban","legacy-modernization","python","requirements-engineering","scrum","sdd","spec-driven-development","spec-first","testing","value-driven"],"latest_commit_sha":null,"homepage":"http://docs.specfact.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nold-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":"CLA.md"}},"created_at":"2025-10-29T12:04:16.000Z","updated_at":"2026-04-08T21:58:16.000Z","dependencies_parsed_at":"2026-02-04T01:01:49.381Z","dependency_job_id":null,"html_url":"https://github.com/nold-ai/specfact-cli","commit_stats":null,"previous_names":["nold-ai/specfact-cli"],"tags_count":75,"template":false,"template_full_name":null,"purl":"pkg:github/nold-ai/specfact-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nold-ai%2Fspecfact-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nold-ai%2Fspecfact-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nold-ai%2Fspecfact-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nold-ai%2Fspecfact-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nold-ai","download_url":"https://codeload.github.com/nold-ai/specfact-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nold-ai%2Fspecfact-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31910585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","backlog-refinement","brownfield","code2spec","context-engineering","contract-enforcement","contract-first","contract-testing","contracts","copilot","kanban","legacy-modernization","python","requirements-engineering","scrum","sdd","spec-driven-development","spec-first","testing","value-driven"],"created_at":"2025-12-26T02:18:31.684Z","updated_at":"2026-05-04T00:02:19.201Z","avatar_url":"https://github.com/nold-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SpecFact CLI\n\n\u003e Review AI-assisted code against your own contracts.\n\u003e Catch drift before it reaches PR or main.\n\n[![PyPI version](https://img.shields.io/pypi/v/specfact-cli.svg?color=22c55e)](https://pypi.org/project/specfact-cli/)\n[![Python versions](https://img.shields.io/pypi/pyversions/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Status](https://img.shields.io/badge/status-beta-F59E0B.svg)](https://github.com/nold-ai/specfact-cli)\n\n**No API keys required. Works offline. Zero vendor lock-in.**\n\n\u003cdiv align=\"center\"\u003e\n\n**[Documentation](https://docs.specfact.io/)** • **[Modules](https://modules.specfact.io/)** • **[Support](mailto:hello@noldai.com)**\n\n\u003c/div\u003e\n\n## Try it in 60 seconds\n\n```bash\n# Zero-install, no API key, works offline\nuvx specfact-cli init --profile solo-developer\nuvx specfact-cli code review run --path . --scope full\n```\n\n**Sample output:**\n\n```text\nSpecFact CLI - v0.46.4\n\nRunning Ruff checks...\nRunning Radon complexity checks...\nRunning Semgrep rules...\nRunning AST clean-code checks...\nRunning basedpyright type checks...\nRunning pylint checks...\nRunning contract checks...\nRunning targeted tests and coverage...\n\nVerdict: FAIL | CI exit: 1 | Score: 0 | Reward delta: -80\n\nFindings:\n  - specfact_demo/enforcement.py:96   Cyclomatic complexity for run_enforcement is 16.\n  - specfact_demo/main.py:81          Avoid print() in source files; use structured logging instead.\n  - examples/buggy_math.py:4          Public function divide is missing @require/@ensure decorators.\n\nEvidence bundle: docs/_support/readme-first-contact/sample-output/\n```\n\n⭐ **Star this repo if the output is useful.** Open an issue if you want the workflow adapted for your stack.\n\n**Already installed the CLI?** Use:\n\n```bash\nspecfact init --profile solo-developer\nspecfact code review run --path . --scope full\n```\n\nThe 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/`.\n\n## What SpecFact does\n\n- **Reviews AI-assisted changes deterministically** — compare code against contracts, clean-code rules, and policy gates\n- **Extracts structure from existing code** — reverse-engineer brownfield repos before you change them\n- **Blocks drift before merge** — use the same checks locally, in pre-commit, and in CI\n- **Links backlog intent to code reality** — connect backlog, specs, validation, and implementation\n- **Stays local-first** — no cloud account, no vendor lock-in, no built-in model dependency\n\n## What is SpecFact?\n\nSpecFact is a local CLI for catching backlog/spec/code drift before it becomes expensive. It gives solo developers, legacy maintainers, and teams a validation layer around AI-assisted delivery, brownfield reverse engineering, and contract-first reviews.\n\nIt exists because delivery drifts in predictable ways:\n\n- AI-assisted code lands faster than validation catches up\n- brownfield systems rarely have trustworthy up-to-date specs\n- backlog intent gets reinterpreted before it reaches code\n- teams need the same review rules across IDEs, CI, and pull requests\n\n## Add SpecFact to your workflow\n\n### Pre-commit hook\n\nThis repository uses a **modular** local hook layout (parity with `specfact-cli-modules`: `fail_fast`,\nseparate verify / format / YAML / Markdown / workflow / lint / Block 2 hooks). If you copy\n[`.pre-commit-config.yaml`](.pre-commit-config.yaml) into another repo, you must also vendor the\nreferenced `scripts/*.sh` entrypoints (at minimum `scripts/pre-commit-quality-checks.sh`,\n`scripts/pre-commit-verify-modules.sh`, `scripts/module-verify-policy.sh`, and\n`scripts/git-branch-module-signature-flag.sh`) so hook\n`entry:` paths resolve. Alternatively, skip vendoring the modular file and use the remote hook below.\n\nFor a **single-hook** setup in downstream repos, keep using the stable id and script shim:\n\n```yaml\n- repo: https://github.com/nold-ai/specfact-cli\n  rev: v0.46.4\n  hooks:\n    - id: specfact-smart-checks\n```\n\nThe shim runs `scripts/pre-commit-quality-checks.sh all` (full pipeline including module verify).\n\n### GitHub Actions\n\n```yaml\n- name: SpecFact Gate\n  run: uvx specfact-cli@latest govern enforce stage --preset minimal\n```\n\n## How SpecFact is built\n\nSpecFact uses the same discipline it asks you to trust:\n\n1. Outside-in research on the workflow or drift problem\n2. Public **OpenSpec** proposal and spec deltas\n3. TDD evidence before implementation\n4. Dogfooding with `specfact code review`\n5. Format, type-check, contract-test, and docs quality gates\n6. PR review with evidence artifacts\n7. Release through the same reproducible CLI paths\n\n## For teams and organizations\n\nSpecFact still scales beyond the solo-developer entry path:\n\n- **Backlog + ceremony workflows** for GitHub, Azure DevOps, Jira, and Linear\n- **DoR/DoD and policy enforcement** for teams that need repeatable gates\n- **Evidence-backed PR review** with the same checks used locally\n- **CI/CD adoption path** that keeps validation deterministic instead of model-driven\n\nStart with:\n\n- `specfact backlog ceremony standup ...`\n- `specfact backlog ceremony refinement ...`\n- `specfact backlog verify-readiness --bundle \u003cbundle-name\u003e`\n- `specfact govern ...`\n\n## Module system\n\nOfficial 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`.\n\nInstall examples:\n\n```bash\nspecfact module install nold-ai/specfact-project\nspecfact module install nold-ai/specfact-backlog\nspecfact module install nold-ai/specfact-codebase\nspecfact module install nold-ai/specfact-code-review\nspecfact module install nold-ai/specfact-govern\n```\n\nIf startup warns that modules are missing or outdated, run:\n\n```bash\nspecfact module init --scope project\nspecfact module init\n```\n\n## Documentation topology\n\n`docs.specfact.io` is the canonical starting point for SpecFact.\n\n- Core CLI/runtime/platform documentation remains owned by `specfact-cli`\n- Module-specific deep docs are canonically owned by `specfact-cli-modules`\n- The live modules docs site is published at `https://modules.specfact.io/`\n\nUse 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.\n\n## How do I get started if I want more?\n\nNext steps:\n\n- **[Core CLI docs](docs/index.md)** for the core runtime, bootstrap, and validation flow\n- **[Installation guide](https://docs.specfact.io/getting-started/installation/)** for uvx-first and persistent CLI setup\n- **[Quickstart](https://docs.specfact.io/getting-started/quickstart/)** for the first repo review path\n- **[Reference: command topology](docs/reference/commands.md)** for grouped command surfaces\n- **[Canonical modules docs site](https://modules.specfact.io/)** for bundle-deep workflows\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnold-ai%2Fspecfact-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnold-ai%2Fspecfact-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnold-ai%2Fspecfact-cli/lists"}