specfact-cli 0.45.1__tar.gz → 0.46.2__tar.gz

{specfact_cli-0.45.1 → specfact_cli-0.46.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.45.1
+Version: 0.46.2
 Summary: The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git
@@ -229,6 +229,7 @@ Requires-Dist: gitpython>=3.1.45
 Requires-Dist: graphviz>=0.20.1
 Requires-Dist: icontract>=2.7.1
 Requires-Dist: jinja2>=3.1.6
+Requires-Dist: json5>=0.9.28
 Requires-Dist: jsonschema>=4.23.0
 Requires-Dist: networkx>=3.4.2
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
@@ -266,7 +267,7 @@ Requires-Dist: pytest>=8.4.2; extra == 'dev'
 Requires-Dist: radon>=6.0.1; extra == 'dev'
 Requires-Dist: ruff>=0.14.2; extra == 'dev'
 Requires-Dist: semgrep>=1.144.0; extra == 'dev'
-Requires-Dist: setuptools>=69.0.0; extra == 'dev'
+Requires-Dist: setuptools<82,>=69.0.0; extra == 'dev'
 Requires-Dist: tomlkit>=0.13.3; extra == 'dev'
 Requires-Dist: types-pyyaml>=6.0.12.20250516; extra == 'dev'
 Provides-Extra: enhanced-analysis
@@ -280,295 +281,144 @@ Description-Content-Type: text/markdown
 
 # SpecFact CLI
 
-> **SpecFact is the validation and alignment layer for software delivery.**
-> It adds the missing validation layer that keeps backlog intent, specifications, tests, and code
-> from drifting apart across AI-assisted coding, brownfield systems, and governed delivery.
-> Use it to move fast without losing rigor.
-
-**No API keys required. Works offline. Zero vendor lock-in.**
-
-SpecFact CLI does **not** include built-in AI. It is a deterministic local CLI
-that can be paired with IDE slash-command prompts so your chosen AI copilot can
-invoke SpecFact as part of a command chain.
+> Review AI-assisted code against your own contracts.
+> Catch drift before it reaches PR or main.
 
 [![PyPI version](https://img.shields.io/pypi/v/specfact-cli.svg?color=22c55e)](https://pypi.org/project/specfact-cli/)
 [![Python versions](https://img.shields.io/pypi/pyversions/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Status](https://img.shields.io/badge/status-beta-F59E0B.svg)](https://github.com/nold-ai/specfact-cli)
 
+**No API keys required. Works offline. Zero vendor lock-in.**
+
 <div align="center">
 
-**[specfact.com](https://specfact.com)** • **[specfact.io](https://specfact.io)** • **[specfact.dev](https://specfact.dev)** • **[Documentation](https://docs.specfact.io/)** • **[Support](mailto:hello@noldai.com)**
+**[Documentation](https://docs.specfact.io/)** • **[Modules](https://modules.specfact.io/)** • **[Support](mailto:hello@noldai.com)**
 
 </div>
 
----
-
-## What is SpecFact?
-
-SpecFact is the validation and alignment layer for software delivery.
-
-It is a local CLI that helps you keep the intent behind a change aligned from
-backlog or idea through specifications, implementation, and checks. The “Swiss-knife CLI” metaphor
-fits because SpecFact gives you a set of focused tools for specific delivery problems, not a vague
-bag of features.
-
-In practice, SpecFact helps you:
-- add guardrails to AI-assisted and fast-moving greenfield work
-- reverse-engineer large brownfield codebases into trustworthy structured understanding
-- reduce the “I wanted X but got Y” drift between backlog, spec, and implementation
-- move from local rigor toward team and enterprise policy enforcement
-
-## Why does it exist?
-
-Modern delivery drifts in predictable ways:
-- AI-generated quick wins often lack the validation layer needed for mid- and long-term reliability
-- brownfield systems often have missing or drifted specs, so teams need to reverse-engineer reality
-- backlog intent gets reinterpreted into something else before it reaches code
-- teams working with different skill levels, opinions, and AI IDE setups need consistent review and
-  policy enforcement
-
-SpecFact exists to reduce that drift. It helps teams understand what is really there, express what
-should happen more accurately, and validate that the result still matches the original intent.
-
-## Why should I use it?
-
-Use SpecFact if you want one of these outcomes:
-- ship AI-assisted changes faster without accepting fragile “looks fine to me” quality
-- understand a legacy or unfamiliar codebase before changing it
-- hand brownfield insight into OpenSpec, Spec-Kit, or other spec-first workflows
-- keep backlog expectations, specifications, and implementation from silently diverging
-- enforce shared rules consistently across developers and CI/CD
-
-## What do I get?
-
-With SpecFact, you get:
-- a deterministic local CLI instead of another opaque SaaS dependency
-- a validation layer around fast-moving implementation work
-- codebase analysis and sidecar flows for brownfield understanding
-- stronger backlog/spec/code alignment for real delivery workflows
-- a path from individual rigor to organization-level policy enforcement
-
-## How do I get started?
-
-### Start Here (about 2 minutes): scored code review — no `pip install`
-
-**Point SpecFact at your code.** From a **git repository** (any branch), run two commands:
+## Try it in 60 seconds
 
 ```bash
+# Zero-install, no API key, works offline
 uvx specfact-cli init --profile solo-developer
 uvx specfact-cli code review run --path . --scope full
 ```
 
-You should see a **Verdict** (PASS/FAIL), a **Score**, and categorized **findings** — the fastest way to see SpecFact on real code before you dive into backlog, specs, or CI.
+**Sample output:**
 
-- **Command 1** installs the `solo-developer` bundles (including `specfact-codebase` and `specfact-code-review`) into your user module store so `code review` and related commands are available on the next invocation.
-- **Command 2** runs the clean-code review on the repo at `.`. Use **`--scope full`** on the first run so review does not depend on having local git changes.
+```text
+SpecFact CLI - v0.46.1
 
-**Already installed the CLI?** Use the same flow with `specfact` instead of `uvx specfact-cli`:
+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...
 
-```bash
-specfact init --profile solo-developer
-specfact code review run --path . --scope full
-```
-
-**Read the canonical walkthrough:** **[Documentation — Quickstart](https://docs.specfact.io/getting-started/quickstart/)** · **[Installation](https://docs.specfact.io/getting-started/installation/)** (uvx-first, then persistent install).
+Verdict: FAIL | CI exit: 1 | Score: 0 | Reward delta: -80
 
-### Install (persistent CLI for daily use)
+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.
 
-```bash
-pip install -U specfact-cli
+Evidence bundle: docs/_support/readme-first-contact/sample-output/
 ```
 
-You can still use **`uvx specfact-cli@latest ...`** anytime without installing; it always fetches the latest published CLI.
-
-### After the wow path: deeper workflows
-
-When you want analysis, snapshots, or sidecar validation on top of the review layer:
-
-```bash
-# Analyze a codebase you care about
-specfact code import my-project --repo .
-
-# Snapshot the project state for follow-up workflows
-specfact project snapshot --bundle my-project
-
-# Validate external code without modifying the target repo
-specfact code validate sidecar init my-project /path/to/repo
-specfact code validate sidecar run my-project /path/to/repo
-```
+⭐ **Star this repo if the output is useful.** Open an issue if you want the workflow adapted for your stack.
 
-### AI IDE setup
+**Already installed the CLI?** Use:
 
 ```bash
-specfact init ide
-specfact init ide --ide cursor
-specfact init ide --ide vscode
+specfact init --profile solo-developer
+specfact code review run --path . --scope full
 ```
 
-`specfact init ide` discovers prompt resources from installed workflow modules and exports them to
-your IDE. If module prompt payloads are not installed yet, the CLI uses packaged fallback resources.
-
-## Choose Your Path
-
-### Greenfield and AI-assisted delivery
-
-Use SpecFact as the validation layer around fast-moving implementation work.
-
-Start with:
-- `uvx specfact-cli init --profile solo-developer` then `uvx specfact-cli code review run --path . --scope full` (see **Start Here** above)
-- `specfact code validate sidecar init <bundle> /path/to/repo`
-- `specfact code validate sidecar run <bundle> /path/to/repo`
-
-### Brownfield and reverse engineering
-
-Use SpecFact to understand an existing system before you change it, then hand that understanding
-into spec-first tools such as OpenSpec or Spec-Kit.
-
-Start with:
-- `specfact code import my-project --repo .`
-- `specfact project snapshot --bundle my-project`
-- `specfact code validate sidecar init my-project /path/to/repo`
-- `specfact code validate sidecar run my-project /path/to/repo`
-
-### Backlog to code alignment
-
-Use SpecFact when the problem is not only code quality, but drift between expectations and delivery.
-Backlog commands require a backlog-enabled profile or installed backlog bundle before the workflow
-commands are available.
-
-Start with:
-- `specfact init --profile backlog-team`
-- `specfact backlog ceremony standup ...`
-- `specfact backlog ceremony refinement ...`
-- `specfact backlog verify-readiness --bundle <bundle-name>`
-
-### Team and policy enforcement
-
-Use SpecFact when multiple developers and AI IDEs need consistent checks and review behavior.
-
-Start with:
-- `specfact backlog verify-readiness --bundle <bundle-name>`
-- `specfact govern ...`
-- CI validation flows that keep the same rules active outside local development
-
-## How do I get started if I want more?
-
-**Next steps**
+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/`.
 
-- **[Core CLI docs](docs/index.md)** for the core runtime, bootstrap, validation, and command topology
-- **[Reference: command topology](docs/reference/commands.md)** for grouped command surfaces
-- **[Canonical modules docs site](https://modules.specfact.io/)** for bundle-deep workflows
-
-## Documentation Topology
-
-`docs.specfact.io` is the canonical starting point for SpecFact.
+## What SpecFact does
 
-- 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/`.
+- **Reviews AI-assisted changes deterministically** — 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
+- **Links backlog intent to code reality** — connect backlog, specs, validation, and implementation
+- **Stays local-first** — no cloud account, no vendor lock-in, no built-in model dependency
 
-Use this repository's docs for the overall 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.
+## What is SpecFact?
 
-### Migration Note (Flat Commands Removed)
+SpecFact 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.
 
-As of `0.40.0`, flat root commands are removed. Use grouped commands:
+It exists because delivery drifts in predictable ways:
 
-- `specfact validate ...` -> `specfact code validate ...`
-- `specfact plan ...` -> removed; use `specfact project devops-flow` or `specfact project snapshot`
-- `specfact policy ...` -> removed; use `specfact backlog verify-readiness`
+- AI-assisted code lands faster than validation catches 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
 
-### Backlog Bridge (60 seconds)
+## Add SpecFact to your workflow
 
-SpecFact's USP is closing the drift gap between **backlog -> specs -> code**.
-These commands require the backlog bundle to be installed first, for example via
-`specfact init --profile backlog-team` or `specfact init --install backlog`.
+### Pre-commit hook
 
-```bash
-# 1) Initialize backlog config + field mapping
-specfact backlog init-config --force
-specfact backlog map-fields --provider ado --ado-org <org> --ado-project "<project>"
+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`](.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`, 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.
 
-# 2) Run ceremony workflows on real backlog scope
-specfact backlog ceremony standup ado --ado-org <org> --ado-project "<project>" --state any --assignee any --limit 5
-specfact backlog ceremony refinement ado --ado-org <org> --ado-project "<project>" --id <work-item-id> --preview
+For a **single-hook** setup in downstream repos, keep using the stable id and script shim:
 
-# 3) Keep backlog + spec intent aligned (avoid silent drift)
-specfact backlog verify-readiness --bundle <bundle-name>
+```yaml
+- repo: https://github.com/nold-ai/specfact-cli
+  rev: v0.46.1
+  hooks:
+    - id: specfact-smart-checks
 ```
 
-Compatibility note: `specfact backlog daily ...` and `specfact backlog refine ...` still exist, but the preferred entrypoints are `backlog ceremony standup` and `backlog ceremony refinement`.
-
-For GitHub, replace adapter/org/project with:
-`specfact backlog ceremony standup github --repo-owner <owner> --repo-name <repo> --state any --assignee any --limit 5`
+The shim runs `scripts/pre-commit-quality-checks.sh all` (full pipeline including module verify).
 
-**AI IDE quick start**
+### GitHub Actions
 
-```bash
-# In your IDE chat (Cursor, VS Code, Copilot, etc.)
-/specfact.01-import my-project --repo .
+```yaml
+- name: SpecFact Gate
+  run: uvx specfact-cli@latest govern enforce stage --preset minimal
 ```
 
----
+## How SpecFact is built
 
-## Who It Is For
+SpecFact uses the same discipline it asks you to trust:
 
-- **Vibe coders and new builders** who want to ship fast with guardrails and confidence.
-- **Legacy professionals** who want AI speed without lowering standards.
-- **DevOps and engineering leaders** who need evidence and repeatable workflows.
+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
 
-## The Missing Link (Coder + DevOps Bridge)
+SpecFact still scales beyond the solo-developer entry path:
 
-Most tools help **either** coders **or** agile teams. SpecFact does both:
+- **Backlog + ceremony workflows** for GitHub, Azure DevOps, Jira, and Linear
+- **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
 
-- **Backlog sync that is actually strong**: round-trip sync + refinement with GitHub, Azure DevOps, Jira, Linear.
-- **Ceremony support teams can run**: standup, refinement, sprint planning, flow metrics (Scrum/Kanban/SAFe).
-- **Policy + validation**: DoR/DoD/flow checks plus contract enforcement for production-grade stability.
+Start with:
 
-Recommended command entrypoints:
 - `specfact backlog ceremony standup ...`
 - `specfact backlog ceremony refinement ...`
 - `specfact backlog verify-readiness --bundle <bundle-name>`
-- `specfact backlog analyze-deps --bundle <bundle-name>`
-
-What the backlog readiness and ceremony commands do in practice:
-- Turns team agreements (DoR, DoD, flow checks) into executable checks against your real backlog data.
-- Shows exactly what is missing per item (for example missing acceptance criteria or definition of done).
-- Runs structured ceremony workflows directly from the CLI.
-
-Start with:
-- `specfact backlog ceremony standup --help`
-- `specfact backlog verify-readiness --bundle <bundle-name>`
-- `specfact backlog refine --help`
-
----
-
-## Core CLI Features
-
-The `specfact-cli` repository owns the platform-level features that every workflow bundle depends on:
-
-- `specfact init` for first-run bootstrap and IDE setup.
-- `specfact module` for install/list/show/search/enable/disable/uninstall/upgrade lifecycle flows.
-- `specfact upgrade` for CLI upgrades.
-- Runtime contracts, registry bootstrapping, trust checks, logging, and shared orchestration.
-- The grouped command surface that mounts installed bundle families under `project`, `backlog`, `code`, `spec`, and `govern`.
-
-## Official Modules Integration
-
-Official workflow behavior now ships from `nold-ai/specfact-cli-modules`.
-The core CLI discovers those bundle packages, mounts their command groups, and enforces compatibility, trust, and lifecycle rules.
+- `specfact govern ...`
 
-Installed official bundles expose the current grouped surfaces:
+## Module system
 
-- `specfact project ...`
-- `specfact backlog ...`
-- `specfact code ...`
-- `specfact spec ...`
-- `specfact govern ...`
+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:
 
@@ -576,34 +426,33 @@ 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-spec
+specfact module install nold-ai/specfact-code-review
 specfact module install nold-ai/specfact-govern
 ```
 
-If startup warns that bundled modules are missing or outdated, run:
+If startup warns that modules are missing or outdated, run:
 
 ```bash
 specfact module init --scope project
 specfact module init
 ```
 
-Use this repo's docs for the current CLI/runtime release branch and the overall process of how official modules plug into the core platform.
-Use `https://modules.specfact.io/` for the in-depth backlog, project, spec, govern, adapter, and module-authoring guides.
+## Documentation topology
 
----
+`docs.specfact.io` is the canonical starting point for SpecFact.
 
-## How It Works (High Level)
+- 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/`
 
-1. **Bootstrap**: use **uvx** or **pip**, then `init --profile` to install the bundles you need (for example `solo-developer` for a scored **code review** first).
-2. **Review or analyze**: run **`code review run`** on a repo, or import code and snapshot state for deeper workflows.
-3. **Sync**: connect backlog systems or sync external artifacts into project bundles when you are ready.
-4. **Validate**: run spec, governance, and sidecar validation flows before implementation or release.
-5. **Iterate safely**: use module-provided workflows while the core runtime keeps command mounting, trust, and lifecycle consistent.
+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.
 
-## Where SpecFact Fits
+## How do I get started if I want more?
 
-SpecFact complements your stack rather than replacing it.
+Next steps:
 
-- **Spec-Kit/OpenSpec** for authoring and change tracking
-- **Backlog tools** for planning and delivery
-- **CI/CD** for enforcement and regression prevention
+- **[Core CLI docs](docs/index.md)** for the core runtime, bootstrap, and validation flow
+- **[Installation guide](https://docs.specfact.io/getting-started/installation/)** for uvx-first and persistent CLI setup
+- **[Quickstart](https://docs.specfact.io/getting-started/quickstart/)** for the first repo review path
+- **[Reference: command topology](docs/reference/commands.md)** for grouped command surfaces
+- **[Canonical modules docs site](https://modules.specfact.io/)** for bundle-deep workflows

specfact_cli-0.46.2/README.md

@@ -0,0 +1,177 @@
+# SpecFact CLI
+
+> Review AI-assisted code against your own contracts.
+> Catch drift before it reaches PR or main.
+
+[![PyPI version](https://img.shields.io/pypi/v/specfact-cli.svg?color=22c55e)](https://pypi.org/project/specfact-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-beta-F59E0B.svg)](https://github.com/nold-ai/specfact-cli)
+
+**No API keys required. Works offline. Zero vendor lock-in.**
+
+<div align="center">
+
+**[Documentation](https://docs.specfact.io/)** • **[Modules](https://modules.specfact.io/)** • **[Support](mailto:hello@noldai.com)**
+
+</div>
+
+## Try it in 60 seconds
+
+```bash
+# 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:**
+
+```text
+SpecFact CLI - v0.46.1
+
+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:
+
+```bash
+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/`.
+
+## What SpecFact does
+
+- **Reviews AI-assisted changes deterministically** — 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
+- **Links backlog intent to code reality** — connect backlog, specs, validation, and implementation
+- **Stays local-first** — no cloud account, no vendor lock-in, no built-in model dependency
+
+## What is SpecFact?
+
+SpecFact 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.
+
+It exists because delivery drifts in predictable ways:
+
+- AI-assisted code lands faster than validation catches 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`](.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`, 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:
+
+```yaml
+- repo: https://github.com/nold-ai/specfact-cli
+  rev: v0.46.1
+  hooks:
+    - id: specfact-smart-checks
+```
+
+The shim runs `scripts/pre-commit-quality-checks.sh all` (full pipeline including module verify).
+
+### GitHub Actions
+
+```yaml
+- 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:
+
+- **Backlog + ceremony workflows** for GitHub, Azure DevOps, Jira, and Linear
+- **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
+
+Start with:
+
+- `specfact backlog ceremony standup ...`
+- `specfact backlog ceremony refinement ...`
+- `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:
+
+```bash
+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:
+
+```bash
+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](docs/index.md)** for the core runtime, bootstrap, and validation flow
+- **[Installation guide](https://docs.specfact.io/getting-started/installation/)** for uvx-first and persistent CLI setup
+- **[Quickstart](https://docs.specfact.io/getting-started/quickstart/)** for the first repo review path
+- **[Reference: command topology](docs/reference/commands.md)** for grouped command surfaces
+- **[Canonical modules docs site](https://modules.specfact.io/)** for bundle-deep workflows