specfact-cli 0.42.2__tar.gz → 0.42.4__tar.gz

{specfact_cli-0.42.2 → specfact_cli-0.42.4}/.gitignore

@@ -152,3 +152,6 @@ Language.mli
 .artifacts
 registry.bak/
 .pr-body.md
+
+# code review
+/review-*.json

{specfact_cli-0.42.2 → specfact_cli-0.42.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.42.2
+Version: 0.42.4
 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
@@ -308,7 +308,8 @@ Description-Content-Type: text/markdown
 - Module-specific deep docs are canonically owned by `specfact-cli-modules`.
 - The live modules docs site is currently published at `https://modules.specfact.io/`.
 
-Use this repository's docs for core runtime, lifecycle, registry, trust, and architecture guidance. Use the modules docs site for bundle-specific workflow and module-authoring deep dives.
+Use this repository's docs for the overall SpecFact workflow, CLI runtime lifecycle, module registry, trust model, and command-group topology.
+Use the modules docs site for bundle-specific deep dives, adapter details, workflow tutorials, and module-authoring guidance.
 In short, module-specific deep docs are canonically owned by `specfact-cli-modules`.
 
 ---
@@ -328,30 +329,30 @@ pip install -U specfact-cli
 ### Bootstrap and IDE Setup
 
 ```bash
-# First run: install workflow bundles (required)
+# First run: install official bundles
 specfact init --profile solo-developer
 
-# Other first-run options
+# Alternative bundle selection
 specfact init --install backlog,codebase
 specfact init --install all
 
-# First-run bundle selection (examples)
-specfact init --profile solo-developer
-specfact init --install backlog,codebase
-specfact init --install all
-
-# Configure IDE prompts/templates (interactive selector by default)
+# IDE prompt/template setup
 specfact init ide
 specfact init ide --ide cursor
 specfact init ide --ide vscode
 ```
 
+`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.
+
 ### Run Your First Flow
 
 ```bash
 # Analyze an existing codebase
 specfact code import my-project --repo .
 
+# Snapshot current project state
+specfact project snapshot --bundle my-project
+
 # Validate external code without modifying source
 specfact code validate sidecar init my-project /path/to/repo
 specfact code validate sidecar run my-project /path/to/repo
@@ -361,9 +362,9 @@ specfact code validate sidecar run my-project /path/to/repo
 
 As of `0.40.0`, flat root commands are removed. Use grouped commands:
 
-- `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`
+- `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`
 
 ### Backlog Bridge (60 seconds)
 
@@ -376,19 +377,18 @@ These commands require the backlog bundle to be installed first, for example via
 specfact backlog init-config --force
 specfact backlog map-fields --provider ado --ado-org <org> --ado-project "<project>"
 
-# 2) Run standup/refinement on real backlog scope
-specfact backlog daily ado --ado-org <org> --ado-project "<project>" --state any --assignee any --limit 5
-specfact backlog refine ado --ado-org <org> --ado-project "<project>" --id <work-item-id> --preview
+# 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
 
 # 3) Keep backlog + spec intent aligned (avoid silent drift)
 specfact backlog verify-readiness --bundle <bundle-name>
 ```
 
-For GitHub, replace adapter/org/project with:
-`specfact backlog daily github --repo-owner <owner> --repo-name <repo> ...`
+Compatibility note: `specfact backlog daily ...` and `specfact backlog refine ...` still exist, but the preferred entrypoints are `backlog ceremony standup` and `backlog ceremony refinement`.
 
-Deep dive:
-- **[Backlog Quickstart Demo (GitHub + ADO)](docs/getting-started/tutorial-backlog-quickstart-demo.md)**
+For GitHub, replace adapter/org/project with:
+`specfact backlog ceremony standup github --repo-owner <owner> --repo-name <repo> --state any --assignee any --limit 5`
 
 **AI IDE quick start**
 
@@ -399,26 +399,9 @@ Deep dive:
 
 **Next steps**
 
-- **[Getting Started](docs/getting-started/README.md)**
-- **[AI IDE Workflow](docs/guides/ai-ide-workflow.md)**
-- **[Command Chains](docs/guides/command-chains.md)**
-
----
-
-## Proof and Expectations
-
-- **Typical runtime**: 2-15 minutes depending on repo size and complexity.
-- **Checkpointing**: Progress is saved during analysis so you can resume safely.
-- **Performance**: Optimized for large codebases with cached parsing and file hashes.
-
----
-
-## Why It Matters (Plain Language)
-
-- **Clarity**: Turn messy code into clear specs your team can trust.
-- **Safety**: Catch risky changes early with validation and contract checks.
-- **Sync**: Keep backlog items, specs, tests, and code aligned end to end.
-- **Adoption**: Simple CLI, no platform lock-in, works offline.
+- **[Core CLI docs](docs/index.md)**
+- **[Reference: command topology](docs/reference/commands.md)**
+- **[Canonical modules docs site](https://modules.specfact.io/)**
 
 ---
 
@@ -430,14 +413,6 @@ Deep dive:
 
 ---
 
-## How It Works (High Level)
-
-1. **Analyze**: Read code and extract specs, gaps, and risks.
-2. **Sync**: Connect specs, backlog items, and plans in one workflow.
-3. **Validate**: Enforce contracts and block regressions before production.
-
----
-
 ## The Missing Link (Coder + DevOps Bridge)
 
 Most tools help **either** coders **or** agile teams. SpecFact does both:
@@ -455,54 +430,37 @@ Recommended command entrypoints:
 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).
-- Run structured ceremony workflows (standup, refinement, retrospective) directly from the CLI.
+- 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`
 
-**Try it now**
-
-- **Coders**: [AI IDE Workflow](docs/guides/ai-ide-workflow.md)
-- **Agile teams**: [Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md)
-
 ---
 
-## Modules and Capabilities
-
-**Core runtime**
-
-- **Permanent commands**: `init`, `module`, `upgrade`
-- **Core responsibilities**: lifecycle, registry, trust, contracts, orchestration, shared runtime utilities
-
-**Marketplace-installed bundles**
+## Core CLI Features
 
-- **Backlog**: Refinement, dependency analysis, sprint summaries, risk rollups.
-- **Ceremony**: Standup, refinement, and planning entry points.
-- **Policy**: DoR, DoD, flow, PI readiness checks.
-- **Patch**: Preview, apply, and write changes safely.
+The `specfact-cli` repository owns the platform-level features that every workflow bundle depends on:
 
-**Adapters and bridges**
+- `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`.
 
-- **Specs**: Spec-Kit and OpenSpec
-- **Backlogs**: GitHub Issues, Azure DevOps, Jira, Linear
-- **Contracts**: Specmatic, OpenAPI
+## Official Modules Integration
 
-For technical architecture details (module lifecycle, registry internals, adapters, and implementation status), use:
+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.
 
-- [Architecture Reference](docs/reference/architecture.md)
-- [Architecture Docs Index](docs/architecture/README.md)
-- [Architecture Implementation Status](docs/architecture/implementation-status.md)
+Installed official bundles expose the current grouped surfaces:
 
-### Official Marketplace Bundles
-
-SpecFact ships official bundle packages via the dedicated marketplace registry repository
-`nold-ai/specfact-cli-modules`.
-
-This core docs set remains the canonical docs entry point and release-line overview for marketplace concepts.
-Bundle-specific deep docs are canonically owned by `specfact-cli-modules` and are currently published at:
-`https://modules.specfact.io/`.
+- `specfact project ...`
+- `specfact backlog ...`
+- `specfact code ...`
+- `specfact spec ...`
+- `specfact govern ...`
 
 Install examples:
 
@@ -521,16 +479,17 @@ specfact module init --scope project
 specfact module init
 ```
 
-Official bundles are verified as `official` tier (`nold-ai` publisher). Some bundles
-auto-install dependencies:
+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.
 
-- `nold-ai/specfact-spec` pulls `nold-ai/specfact-project`
-- `nold-ai/specfact-govern` pulls `nold-ai/specfact-project`
+---
 
-Use this repo's docs for the current CLI/runtime release branch and for marketplace lifecycle overview content.
-Use the modules docs site for bundle-specific deep guidance so bundle-only changes can ship without rebuilding the core docs release branch.
+## How It Works (High Level)
 
----
+1. **Bootstrap**: install the CLI and initialize the official bundles you need.
+2. **Analyze or sync**: import code, connect backlog systems, or sync external artifacts into project bundles.
+3. **Validate**: run spec, governance, and sidecar validation flows before implementation or release.
+4. **Iterate safely**: use module-provided workflows while the core runtime keeps command mounting, trust, and lifecycle consistent.
 
 ## Where SpecFact Fits
 
@@ -539,75 +498,3 @@ SpecFact complements your stack rather than replacing it.
 - **Spec-Kit/OpenSpec** for authoring and change tracking
 - **Backlog tools** for planning and delivery
 - **CI/CD** for enforcement and regression prevention
-
-**SpecFact connects them** with adapters, policy checks, and deterministic validation.
-
-**Integrations snapshot**: GitHub, Azure DevOps, Jira, Linear, Spec-Kit, OpenSpec, Specmatic.
-
-- **[Integrations Overview](docs/guides/integrations-overview.md)**
-- **[DevOps Adapter Integration](docs/guides/devops-adapter-integration.md)**
-
----
-
-## Recommended Paths
-
-- **I want a quick win**: [Getting Started](docs/getting-started/README.md)
-- **I use an AI IDE**: [AI IDE Workflow](docs/guides/ai-ide-workflow.md)
-- **We have a team backlog**: [Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md)
-- **We have a long-lived codebase**: [Working With Existing Code](docs/guides/brownfield-engineer.md)
-
----
-
-## Documentation Map
-
-- **[Documentation Index](docs/README.md)**
-- **[Command Reference](docs/reference/commands.md)**
-- **[Backlog Refinement](docs/guides/backlog-refinement.md)**
-- **[Backlog Dependency Analysis](docs/guides/backlog-dependency-analysis.md)**
-- **[Backlog Delta Commands](docs/guides/backlog-delta-commands.md)**
-- **[Policy Engine Commands](docs/guides/policy-engine-commands.md)**
-- **[Project DevOps Flow](docs/guides/project-devops-flow.md)**
-- **[Sidecar Validation](docs/guides/sidecar-validation.md)**
-- **[OpenSpec Journey](docs/guides/openspec-journey.md)**
-
----
-
-## Contributing
-
-We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md).
-
-```bash
-git clone https://github.com/nold-ai/specfact-cli.git
-cd specfact-cli
-pip install -e ".[dev]"
-hatch run contract-test-full
-```
-
----
-
-## License
-
-**Apache License 2.0** - Open source and enterprise-friendly.
-
-[Full license](LICENSE)
-
----
-
-## Support
-
-- **GitHub Discussions**: https://github.com/nold-ai/specfact-cli/discussions
-- **GitHub Issues**: https://github.com/nold-ai/specfact-cli/issues
-- **Email**: hello@noldai.com
-- **Debug logs**: Run with `--debug` and check `~/.specfact/logs/specfact-debug.log`.
-
----
-
-<div align="center">
-
-**Built by [NOLD AI](https://noldai.com)**
-
-Copyright © 2025-2026 Nold AI (Owner: Dominikus Nold)
-
-**Trademarks**: NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). All other trademarks mentioned in this project are the property of their respective owners. See [TRADEMARKS.md](TRADEMARKS.md) for more information.
-
-</div>

specfact_cli-0.42.4/README.md

@@ -0,0 +1,219 @@
+# SpecFact CLI
+
+> **The "swiss knife" CLI that turns any codebase into a clear, safe, and shippable workflow.**
+> Keep backlog, specs, tests, and code in sync so AI-assisted changes do not break production.
+> Works for brand-new projects and long-lived codebases - even if you are new to coding.
+
+**No API keys required. Works offline. Zero vendor lock-in.**
+
+[![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)
+
+<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)**
+
+</div>
+
+---
+
+## Documentation Topology
+
+`docs.specfact.io` is the canonical docs entry 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 currently published at `https://modules.specfact.io/`.
+
+Use this repository's docs for the overall SpecFact workflow, CLI runtime lifecycle, module registry, trust model, and command-group topology.
+Use the modules docs site for bundle-specific deep dives, adapter details, workflow tutorials, and module-authoring guidance.
+In short, module-specific deep docs are canonically owned by `specfact-cli-modules`.
+
+---
+
+## Start Here (60 seconds)
+
+### Install
+
+```bash
+# Zero-install (recommended)
+uvx specfact-cli@latest
+
+# Or install globally
+pip install -U specfact-cli
+```
+
+### Bootstrap and IDE Setup
+
+```bash
+# First run: install official bundles
+specfact init --profile solo-developer
+
+# Alternative bundle selection
+specfact init --install backlog,codebase
+specfact init --install all
+
+# IDE prompt/template setup
+specfact init ide
+specfact init ide --ide cursor
+specfact init ide --ide vscode
+```
+
+`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.
+
+### Run Your First Flow
+
+```bash
+# Analyze an existing codebase
+specfact code import my-project --repo .
+
+# Snapshot current project state
+specfact project snapshot --bundle my-project
+
+# Validate external code without modifying source
+specfact code validate sidecar init my-project /path/to/repo
+specfact code validate sidecar run my-project /path/to/repo
+```
+
+### Migration Note (Flat Commands Removed)
+
+As of `0.40.0`, flat root commands are removed. Use grouped commands:
+
+- `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`
+
+### Backlog Bridge (60 seconds)
+
+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`.
+
+```bash
+# 1) Initialize backlog config + field mapping
+specfact backlog init-config --force
+specfact backlog map-fields --provider ado --ado-org <org> --ado-project "<project>"
+
+# 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
+
+# 3) Keep backlog + spec intent aligned (avoid silent drift)
+specfact backlog verify-readiness --bundle <bundle-name>
+```
+
+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`
+
+**AI IDE quick start**
+
+```bash
+# In your IDE chat (Cursor, VS Code, Copilot, etc.)
+/specfact.01-import my-project --repo .
+```
+
+**Next steps**
+
+- **[Core CLI docs](docs/index.md)**
+- **[Reference: command topology](docs/reference/commands.md)**
+- **[Canonical modules docs site](https://modules.specfact.io/)**
+
+---
+
+## Who It Is For
+
+- **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.
+
+---
+
+## The Missing Link (Coder + DevOps Bridge)
+
+Most tools help **either** coders **or** agile teams. SpecFact does both:
+
+- **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.
+
+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.
+
+Installed official bundles expose the current grouped surfaces:
+
+- `specfact project ...`
+- `specfact backlog ...`
+- `specfact code ...`
+- `specfact spec ...`
+- `specfact 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-spec
+specfact module install nold-ai/specfact-govern
+```
+
+If startup warns that bundled 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.
+
+---
+
+## How It Works (High Level)
+
+1. **Bootstrap**: install the CLI and initialize the official bundles you need.
+2. **Analyze or sync**: import code, connect backlog systems, or sync external artifacts into project bundles.
+3. **Validate**: run spec, governance, and sidecar validation flows before implementation or release.
+4. **Iterate safely**: use module-provided workflows while the core runtime keeps command mounting, trust, and lifecycle consistent.
+
+## Where SpecFact Fits
+
+SpecFact complements your stack rather than replacing it.
+
+- **Spec-Kit/OpenSpec** for authoring and change tracking
+- **Backlog tools** for planning and delivery
+- **CI/CD** for enforcement and regression prevention

{specfact_cli-0.42.2 → specfact_cli-0.42.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.42.2"
+version = "0.42.4"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -730,6 +730,11 @@ ignore = [
     "B008",   # typer.Option/Argument in defaults (common Typer pattern)
 ]
 
+# shellingham must be patched before Typer imports it; remaining imports follow the try/except.
+"src/specfact_cli/cli.py" = [
+    "E402",
+]
+
 [tool.ruff.lint.isort]
 # Match isort ruff profile configuration
 # Ruff-compatible: multi_line_output = 3, combine_as_imports = true

{specfact_cli-0.42.2 → specfact_cli-0.42.4}/src/__init__.py

@@ -3,4 +3,4 @@ SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
 """
 
 # Package version: keep in sync with pyproject.toml, setup.py, src/specfact_cli/__init__.py
-__version__ = "0.42.1"
+__version__ = "0.42.4"

{specfact_cli-0.42.2 → specfact_cli-0.42.4}/src/specfact_cli/__init__.py

@@ -42,6 +42,6 @@ def _bootstrap_bundle_paths() -> None:
 
 _bootstrap_bundle_paths()
 
-__version__ = "0.42.2"
+__version__ = "0.42.4"
 
 __all__ = ["__version__"]