specfact-cli 0.46.28__tar.gz → 0.47.6__tar.gz

{specfact_cli-0.46.28 → specfact_cli-0.47.6}/.gitignore

@@ -117,6 +117,8 @@ docs/internal/
 
 .codex/skills/openspec-*/
 !.codex/skills/openspec-workflows/
+.agents/skills/
+skills-lock.json
 
 .vibe/skills/openspec-*/
 !.vibe/skills/openspec-workflows/

{specfact_cli-0.46.28 → specfact_cli-0.47.6}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.46.28
-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.
+Version: 0.47.6
+Summary: AI-bloat defense CLI for Python teams. Run deterministic code review, cleanup forecasts, and spec/contract evidence for AI-assisted and brownfield delivery.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git
 Project-URL: Documentation, https://github.com/nold-ai/specfact-cli#readme
@@ -210,7 +210,7 @@ License:                                  Apache License
            See the License for the specific language governing permissions and
            limitations under the License.
 License-File: LICENSE
-Keywords: agile,backlog,beartype,ceremonies,cli,contract-driven-development,contracts,crosshair,devops,existing-code,icontract,kanban,legacy,modernization,policy-as-code,property-based-testing,safe,scrum,specfact,specs,tdd,validation
+Keywords: agile,ai-bloat,backlog,beartype,ceremonies,clean-code,cli,code-review,contract-driven-development,contracts,crosshair,devops,existing-code,icontract,kanban,legacy,modernization,policy-as-code,property-based-testing,safe,scrum,specfact,specs,tdd,technical-debt,validation
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -283,8 +283,8 @@ Description-Content-Type: text/markdown
 
 # SpecFact CLI
 
-> Review AI-assisted code against your own contracts.
-> Catch drift before it reaches PR or main.
+> Defend AI-assisted Python code from bloat before it reaches PR.
+> Run deterministic review, cleanup forecasts, and spec/contract evidence locally.
 
 [![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/)
@@ -299,6 +299,11 @@ Description-Content-Type: text/markdown
 
 </div>
 
+## Command Overview
+
+- [Generated command overview for humans](docs/reference/commands.generated.md)
+- [AI-agent command overview](llms.txt)
+
 ## Try it in 60 seconds
 
 ```bash
@@ -310,7 +315,7 @@ uvx specfact-cli code review run --path . --scope full
 **Sample output:**
 
 ```text
-SpecFact CLI - v0.46.4
+SpecFact CLI - v0.47.4
 
 Running Ruff checks...
 Running Radon complexity checks...
@@ -342,23 +347,30 @@ 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/`.
 
-The Code Review bundle also reports `ai_bloat` advisories for code shapes that AI-assisted coding often amplifies, such as redundant wrappers, passthrough lambdas, identity `try`/`except` blocks, and avoidable intermediate lists. These findings are advisory, score-neutral, and not AI-authorship detection. Use the generated `.specfact/code-review.json` report with the Project bundle's `/specfact.08-simplify` IDE prompt to review each cleanup before accepting it. See the [AI bloat quickstart](https://modules.specfact.io/quickstart-ai-bloat/) on the modules docs site.
+## 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](https://modules.specfact.io/quickstart-ai-bloat/) and [Code Review run guide](https://modules.specfact.io/bundles/code-review/run/) on the modules docs site.
 
 ## What SpecFact does
 
-- **Reviews AI-assisted changes deterministically** — compare code against contracts, clean-code rules, and policy gates
+- **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
-- **Links backlog intent to code reality** — connect backlog, specs, validation, and implementation
+- **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 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.
+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 validation catches up
+- 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
@@ -379,7 +391,7 @@ For a **single-hook** setup in downstream repos, keep using the stable id and sc
 
 ```yaml
 - repo: https://github.com/nold-ai/specfact-cli
-  rev: v0.46.4
+  rev: v0.47.4
   hooks:
     - id: specfact-smart-checks
 ```
@@ -407,17 +419,18 @@ SpecFact uses the same discipline it asks you to trust:
 
 ## For teams and organizations
 
-SpecFact still scales beyond the solo-developer entry path:
+SpecFact still scales beyond the solo-developer entry path, but validation stays
+the center:
 
-- **Backlog + ceremony workflows** for GitHub, Azure DevOps, Jira, and Linear
+- **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
 
-Start with:
+Optional module-deep paths include:
 
-- `specfact backlog ceremony standup ...`
-- `specfact backlog ceremony refinement ...`
+- `specfact project import ...`
+- `specfact spec validate ...`
 - `specfact backlog verify-readiness --bundle <bundle-name>`
 - `specfact govern ...`
 

{specfact_cli-0.46.28 → specfact_cli-0.47.6}/README.md

@@ -1,7 +1,7 @@
 # SpecFact CLI
 
-> Review AI-assisted code against your own contracts.
-> Catch drift before it reaches PR or main.
+> Defend AI-assisted Python code from bloat before it reaches PR.
+> Run deterministic review, cleanup forecasts, and spec/contract evidence locally.
 
 [![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/)
@@ -16,6 +16,11 @@
 
 </div>
 
+## Command Overview
+
+- [Generated command overview for humans](docs/reference/commands.generated.md)
+- [AI-agent command overview](llms.txt)
+
 ## Try it in 60 seconds
 
 ```bash
@@ -27,7 +32,7 @@ uvx specfact-cli code review run --path . --scope full
 **Sample output:**
 
 ```text
-SpecFact CLI - v0.46.4
+SpecFact CLI - v0.47.4
 
 Running Ruff checks...
 Running Radon complexity checks...
@@ -59,23 +64,30 @@ 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/`.
 
-The Code Review bundle also reports `ai_bloat` advisories for code shapes that AI-assisted coding often amplifies, such as redundant wrappers, passthrough lambdas, identity `try`/`except` blocks, and avoidable intermediate lists. These findings are advisory, score-neutral, and not AI-authorship detection. Use the generated `.specfact/code-review.json` report with the Project bundle's `/specfact.08-simplify` IDE prompt to review each cleanup before accepting it. See the [AI bloat quickstart](https://modules.specfact.io/quickstart-ai-bloat/) on the modules docs site.
+## 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](https://modules.specfact.io/quickstart-ai-bloat/) and [Code Review run guide](https://modules.specfact.io/bundles/code-review/run/) on the modules docs site.
 
 ## What SpecFact does
 
-- **Reviews AI-assisted changes deterministically** — compare code against contracts, clean-code rules, and policy gates
+- **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
-- **Links backlog intent to code reality** — connect backlog, specs, validation, and implementation
+- **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 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.
+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 validation catches up
+- 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
@@ -96,7 +108,7 @@ For a **single-hook** setup in downstream repos, keep using the stable id and sc
 
 ```yaml
 - repo: https://github.com/nold-ai/specfact-cli
-  rev: v0.46.4
+  rev: v0.47.4
   hooks:
     - id: specfact-smart-checks
 ```
@@ -124,17 +136,18 @@ SpecFact uses the same discipline it asks you to trust:
 
 ## For teams and organizations
 
-SpecFact still scales beyond the solo-developer entry path:
+SpecFact still scales beyond the solo-developer entry path, but validation stays
+the center:
 
-- **Backlog + ceremony workflows** for GitHub, Azure DevOps, Jira, and Linear
+- **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
 
-Start with:
+Optional module-deep paths include:
 
-- `specfact backlog ceremony standup ...`
-- `specfact backlog ceremony refinement ...`
+- `specfact project import ...`
+- `specfact spec validate ...`
 - `specfact backlog verify-readiness --bundle <bundle-name>`
 - `specfact govern ...`
 

{specfact_cli-0.46.28 → specfact_cli-0.47.6}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.46.28"
-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."
+version = "0.47.6"
+description = "AI-bloat defense CLI for Python teams. Run deterministic code review, cleanup forecasts, and spec/contract evidence for AI-assisted and brownfield delivery."
 readme = "README.md"
 requires-python = ">=3.11"
 license = { file = "LICENSE" }  # Apache License 2.0
@@ -14,8 +14,12 @@ authors = [
 ]
 keywords = [
     "agile",
+    "ai-bloat",
     "devops",
     "backlog",
+    "code-review",
+    "clean-code",
+    "technical-debt",
     "scrum",
     "kanban",
     "safe",
@@ -220,9 +224,9 @@ security-audit = "python scripts/security_audit_gate.py"
 # Development scripts
 test = "pytest {args}"
 test-cov = "pytest --cov=src --cov-report=term-missing {args}"
-type-check = "basedpyright --pythonpath $(python -c 'import sys; print(sys.executable)') {args}"
+type-check = "basedpyright --pythonpath \"$(python -c 'import sys; print(sys.executable)')\" {args}"
 # basedpyright --level error: suppress warning noise in pre-commit (Block 1 runs `hatch run lint`).
-lint = "ruff format . --check && basedpyright --level error --pythonpath $(python -c 'import sys; print(sys.executable)') && ruff check . && pylint src tests tools && python scripts/verify_safe_project_writes.py"
+lint = "ruff format . --check && basedpyright --level error --pythonpath \"$(python -c 'import sys; print(sys.executable)')\" && ruff check . && pylint src tests tools && python scripts/verify_safe_project_writes.py"
 lint-changed = "python scripts/run_changed_lint.py {args}"
 governance = "pylint src tests tools --reports=y --output-format=parseable"
 format = "ruff check . --fix && ruff format ."
@@ -247,12 +251,15 @@ yaml-check-all = "bash scripts/yaml-tools.sh check-all {args}"
 # Docs validation (docs-12): command examples vs CLI; modules.specfact.io URLs in docs
 check-docs-commands = "python scripts/check-docs-commands.py"
 check-cross-site-links = "python scripts/check-cross-site-links.py"
+generate-command-overview = "python scripts/generate-command-overview.py --write"
+check-command-overview = "python scripts/generate-command-overview.py --check"
+check-command-contract = "python scripts/check-command-contract.py"
 doc-frontmatter-check = "python scripts/check_doc_frontmatter.py"
 validate-agent-rule-signals = "python scripts/validate_agent_rule_applies_when.py"
 check-version-sources = "python scripts/check_version_sources.py"
 check-pypi-ahead = "python scripts/check_local_version_ahead_of_pypi.py"
 release = "python scripts/check_local_version_ahead_of_pypi.py && python scripts/check_version_sources.py"
-docs-validate = "python scripts/check-docs-commands.py && python scripts/check-cross-site-links.py --warn-only && python scripts/check_doc_frontmatter.py && python scripts/validate_agent_rule_applies_when.py"
+docs-validate = "python scripts/generate-command-overview.py --check && python scripts/check-command-contract.py && python scripts/check-docs-commands.py && python scripts/check-cross-site-links.py --warn-only && python scripts/check_doc_frontmatter.py && python scripts/validate_agent_rule_applies_when.py"
 
 # Legacy entry (kept for compatibility); prefer `workflows-lint` above
 lint-workflows = "bash scripts/run_actionlint.sh {args}"

{specfact_cli-0.46.28 → specfact_cli-0.47.6}/resources/bundled-module-registry/index.json

@@ -1,16 +1,16 @@
 {
   "modules": [
     {
-      "checksum_sha256": "ce82ea7d2a48dfa8b16ad48599ec6daa922d6aa1a61c242da1143366d5d53ec4",
-      "download_url": "https://github.com/nold-ai/specfact-cli/releases/download/init-0.1.33.tar.gz",
+      "checksum_sha256": "3a563335d7a5e16e6e9ec975d6e5c77ff550d8880474eca03713b43e97d39a4a",
+      "download_url": "https://github.com/nold-ai/specfact-cli/releases/download/init-0.1.37.tar.gz",
       "id": "init",
-      "latest_version": "0.1.33"
+      "latest_version": "0.1.37"
     },
     {
-      "checksum_sha256": "49c5bcbef6ce4aba3302b8209d3641cc34430f3fe4754423d61428557f8c641d",
-      "download_url": "https://github.com/nold-ai/specfact-cli/releases/download/upgrade-0.1.19.tar.gz",
+      "checksum_sha256": "35c592374b209224af9a826c21efa66947cc16bf680b20ee0463f44bee4f9b59",
+      "download_url": "https://github.com/nold-ai/specfact-cli/releases/download/upgrade-0.1.21.tar.gz",
       "id": "upgrade",
-      "latest_version": "0.1.19"
+      "latest_version": "0.1.21"
     },
     {
       "checksum_sha256": "79359da27cb1c734a928a453a786b626e7b06654f515f32ead0cf96fa8e70bc2",

{specfact_cli-0.46.28 → specfact_cli-0.47.6}/resources/templates/pr-template.md.j2

@@ -20,7 +20,7 @@
 - **Non-interactive / CI** must bootstrap workflow bundles before `specfact code …` or `specfact project …`:
   - `specfact init --profile solo-developer --repo .` (or another profile / `specfact init --install …`), **or**
   - `specfact module install nold-ai/specfact-codebase` (and other bundles as needed).
-- Contract repro in CI uses **`specfact code repro`** (not `specfact repro`). Optional: `specfact code repro setup` for CrossHair config.
+- Contract repro in CI uses **`specfact code repro`**. Optional: `specfact code repro setup` for CrossHair config.
 - Optional `specfact project version check` needs a project under `.specfact/projects/<bundle>/` and `--bundle <name>`.
 
 **SpecFact CLI Validation Results:**
@@ -64,4 +64,3 @@
 ## 📝 Notes
 
 {{ notes | default("Add any additional notes here") }}
-

specfact_cli-0.47.6/src/__init__.py

@@ -0,0 +1,6 @@
+"""
+SpecFact CLI - AI-bloat defense CLI for Python teams.
+"""
+
+# Package version: keep in sync with pyproject.toml, setup.py, src/specfact_cli/__init__.py
+__version__ = "0.47.6"

{specfact_cli-0.46.28 → specfact_cli-0.47.6}/src/specfact_cli/__init__.py

@@ -1,7 +1,8 @@
 """
-SpecFact CLI - The swiss knife CLI for agile DevOps teams.
+SpecFact CLI - AI-bloat defense CLI for Python teams.
 
 This package provides command-line tools for:
+- Defending AI-assisted code against cleanup bloat
 - Turning code into clear specs and plans
 - Keeping backlog, specs, tests, and code in sync
 - Enforcing validation and contract checks before production
@@ -13,6 +14,7 @@ to ``sys.path`` so local development can load marketplace packages without insta
 
 from __future__ import annotations
 
+import importlib.util
 import os
 import sys
 from pathlib import Path
@@ -25,6 +27,12 @@ def _candidate_modules_repo_roots() -> list[Path]:
         roots.append(Path(configured).expanduser())
 
     this_file = Path(__file__).resolve()
+    parts = this_file.parts
+    if "specfact-cli-worktrees" in parts:
+        marker_index = parts.index("specfact-cli-worktrees")
+        base = Path(*parts[:marker_index])
+        suffix = Path(*parts[marker_index + 1 : -3])
+        roots.append(base / "specfact-cli-modules-worktrees" / suffix)
     for base in (this_file.parent.parent.parent, *this_file.parents):
         roots.append(base / "specfact-cli-modules")
         roots.append(base.parent / "specfact-cli-modules")
@@ -45,6 +53,29 @@ def _bootstrap_bundle_paths() -> None:
 
 _bootstrap_bundle_paths()
 
-__version__ = "0.46.28"
+
+def _install_progressive_disclosure() -> None:
+    module_name = "_specfact_progressive_disclosure_bootstrap"
+    if module_name in sys.modules:
+        return
+    module_path = Path(__file__).resolve().parent / "utils" / "progressive_disclosure.py"
+    spec = importlib.util.spec_from_file_location(module_name, module_path)
+    if spec is None or spec.loader is None:
+        return
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception:
+        sys.modules.pop(module_name, None)
+        raise
+
+
+# Install the shared Click/Typer usage-error contract as soon as core is imported.
+# Module packages import specfact_cli before constructing direct Typer apps, so this
+# keeps missing-command and missing-parameter UX consistent outside the root CLI too.
+_install_progressive_disclosure()
+
+__version__ = "0.47.6"
 
 __all__ = ["__version__"]