Release 0.41.0 changes from dev to main

CHANGELOG.md

@@ -8,6 +8,14 @@ All notable changes to this project will be documented in this file.
 **Important:** Changes need to be documented below this block as this is the header section. Each section should be separated by a horizontal rule. Newer changelog entries need to be added on top of prior ones to keep the history chronological with most recent changes first.
 
 
+---
+
+## [0.41.0] - 2026-03-11
+
+### Added
+
+- Added the `nold-ai/specfact-code-review` module scaffold (SP-001): structured `ReviewFinding` / `ReviewReport` models, review scoring helpers, and the `specfact code review` command surface documentation.
+
 ---
 
 ## [0.40.4] - 2026-03-11

README.md

@@ -56,7 +56,7 @@ specfact init ide --ide vscode
 
 ```bash
 # Analyze an existing codebase
-specfact project import from-code my-project --repo .
+specfact code import my-project --repo .
 
 # Validate external code without modifying source
 specfact code validate sidecar init my-project /path/to/repo

docs/_layouts/default.html

@@ -145,6 +145,7 @@ <h2 class="docs-sidebar-title">
                 <li><a href="{{ '/guides/installing-modules/' | relative_url }}">Installing Modules</a></li>
                 <li><a href="{{ '/guides/module-marketplace/' | relative_url }}">Module Marketplace</a></li>
                 <li><a href="{{ '/guides/marketplace/' | relative_url }}">Marketplace Bundles</a></li>
+                <li><a href="{{ '/modules/code-review/' | relative_url }}">Code Review Module</a></li>
                 <li><a href="{{ '/guides/command-chains/' | relative_url }}">Command Chains</a></li>
                 <li><a href="{{ '/guides/agile-scrum-workflows/' | relative_url }}">Agile/Scrum Workflows</a></li>
                 <li><a href="{{ '/guides/policy-engine-commands/' | relative_url }}">Policy Engine Commands</a></li>
@@ -192,7 +193,6 @@ <h2 class="docs-sidebar-title">
                 <li><a href="{{ '/reference/projectbundle-schema/' | relative_url }}">ProjectBundle Schema</a></li>
                 <li><a href="{{ '/reference/module-contracts/' | relative_url }}">Module Contracts</a></li>
                 <li><a href="{{ '/reference/module-security/' | relative_url }}">Module Security</a></li>
-                <li><a href="{{ '/reference/module-categories/' | relative_url }}">Module Categories</a></li>
                 <li><a href="{{ '/reference/bridge-registry/' | relative_url }}">Bridge Registry</a></li>
                 <li><a href="{{ '/guides/integrations-overview/' | relative_url }}">Integrations Overview</a></li>
               </ul>

docs/examples/brownfield-data-pipeline.md

@@ -29,7 +29,7 @@ You inherited a 5-year-old Python data pipeline with:
 
 ```bash
 # Analyze the legacy data pipeline
-specfact project import from-code customer-etl \
+specfact code import customer-etl \
   --repo ./legacy-etl-pipeline \
   --language python
 
@@ -338,7 +338,7 @@ def transform_order(raw_order: Dict[str, Any]) -> Dict[str, Any]:
 
 **Solution:**
 
-1. Ran `specfact project import from-code` → 47 features extracted in 12 seconds
+1. Ran `specfact code import` → 47 features extracted in 12 seconds
 2. Added contracts to 23 critical data transformation functions
 3. CrossHair discovered 6 edge cases in legacy validation logic
 4. Enforced contracts during migration, blocked 11 regressions

docs/examples/brownfield-django-modernization.md

@@ -29,7 +29,7 @@ You inherited a 3-year-old Django app with:
 
 ```bash
 # Analyze the legacy Django app
-specfact project import from-code customer-portal \
+specfact code import customer-portal \
   --repo ./legacy-django-app \
   --language python
 

docs/examples/brownfield-flask-api.md

@@ -27,7 +27,7 @@ You inherited a 2-year-old Flask REST API with:
 
 ```bash
 # Analyze the legacy Flask API
-specfact project import from-code customer-api \
+specfact code import customer-api \
   --repo ./legacy-flask-api \
   --language python
 

docs/examples/dogfooding-specfact-cli.md

@@ -25,7 +25,7 @@ We built SpecFact CLI and wanted to validate that it actually works in the real
 First, we analyzed the existing codebase to see what features it discovered:
 
 ```bash
-specfact project import from-code specfact-cli --repo . --confidence 0.5
+specfact code import specfact-cli --repo . --confidence 0.5
 ```
 
 **Output**:
@@ -546,7 +546,7 @@ These are **actual questions** that need answers, not false positives!
 
 ```bash
 # 1. Analyze existing codebase (3 seconds)
-specfact project import from-code specfact-cli --repo . --confidence 0.5
+specfact code import specfact-cli --repo . --confidence 0.5
 # ✅ Discovers 19 features, 49 stories
 
 # 2. Set quality gates (1 second)

docs/examples/integration-showcases/integration-showcases-testing-guide.md

@@ -159,7 +159,7 @@ def process_payment(request):
       - **Suggested plan name for Example 1**: `Payment Processing` or `Legacy Payment View`
    3. **CLI Execution**: The AI will:
       - Sanitize the name (lowercase, remove spaces/special chars)
-      - Run `specfact project import from-code <sanitized-name> --repo <workspace> --confidence 0.5`
+      - Run `specfact code import <sanitized-name> --repo <workspace> --confidence 0.5`
       - Capture CLI output and create a project bundle
    4. **CLI Output Summary**: The AI will present a summary showing:
       - Bundle name used
@@ -193,7 +193,7 @@ def process_payment(request):
    3. **Apply Enrichment**: The AI will run:
 
       ```bash
-      specfact project import from-code <name> --repo <workspace> --enrichment .specfact/projects/<name>/reports/enrichment/<name>-<timestamp>.enrichment.md --confidence 0.5
+      specfact code import <name> --repo <workspace> --enrichment .specfact/projects/<name>/reports/enrichment/<name>-<timestamp>.enrichment.md --confidence 0.5
       ```
 
    4. **Enriched Project Bundle**: The CLI will update:
@@ -238,7 +238,7 @@ uvx specfact-cli@latest --no-banner import from-code --repo . --output-format ya
 
 **CLI vs Interactive Mode**:
 
-- **CLI-only** (`uvx specfact-cli@latest import from-code` or `specfact project import from-code`): Uses AST-based analyzer (CI/CD mode)
+- **CLI-only** (`uvx specfact-cli@latest import from-code` or `specfact code import`): Uses AST-based analyzer (CI/CD mode)
   - May show "0 features" for minimal test cases
   - Limited to AST pattern matching
   - Works but may not detect all features in simple examples

docs/examples/quick-examples.md

@@ -33,7 +33,7 @@ pip install specfact-cli
 specfact project plan init my-project --interactive
 
 # Have existing code?
-specfact project import from-code my-project --repo .
+specfact code import my-project --repo .
 
 # Using GitHub Spec-Kit?
 specfact project import from-bridge --adapter speckit --repo ./my-project --dry-run
@@ -55,30 +55,30 @@ specfact project import from-bridge --adapter speckit --repo ./spec-kit-project
 
 ```bash
 # Basic import (bundle name as positional argument)
-specfact project import from-code my-project --repo .
+specfact code import my-project --repo .
 
 # With confidence threshold
-specfact project import from-code my-project --repo . --confidence 0.7
+specfact code import my-project --repo . --confidence 0.7
 
 # Shadow mode (observe only)
-specfact project import from-code my-project --repo . --shadow-only
+specfact code import my-project --repo . --shadow-only
 
 # CoPilot mode (enhanced prompts)
 specfact --mode copilot import from-code my-project --repo . --confidence 0.7
 
 # Re-validate existing features (force re-analysis)
-specfact project import from-code my-project --repo . --revalidate-features
+specfact code import my-project --repo . --revalidate-features
 
 # Resume interrupted import (features saved early as checkpoint)
 # If import is cancelled, just run the same command again
-specfact project import from-code my-project --repo .
+specfact code import my-project --repo .
 
 # Partial analysis (analyze specific subdirectory only)
-specfact project import from-code my-project --repo . --entry-point src/core
+specfact code import my-project --repo . --entry-point src/core
 
 # Large codebase with progress reporting
 # Progress bars show: feature analysis, source linking, contract extraction
-specfact project import from-code large-project --repo . --confidence 0.5
+specfact code import large-project --repo . --confidence 0.5
 
 ```
 
@@ -223,7 +223,7 @@ specfact init ide --ide cursor --force
 
 ```bash
 # Auto-detect mode (default)
-specfact project import from-code my-project --repo .
+specfact code import my-project --repo .
 
 # Force CI/CD mode
 specfact --mode cicd import from-code my-project --repo .
@@ -233,7 +233,7 @@ specfact --mode copilot import from-code my-project --repo .
 
 # Set via environment variable
 export SPECFACT_MODE=copilot
-specfact project import from-code my-project --repo .
+specfact code import my-project --repo .
 ```
 
 ## Common Workflows
@@ -258,7 +258,7 @@ specfact project plan compare --repo .
 
 ```bash
 # Step 1: Extract specs from legacy code
-specfact project import from-code my-project --repo .
+specfact code import my-project --repo .
 
 # Step 2: Create hard SDD manifest
 specfact project plan harden my-project
@@ -302,7 +302,7 @@ specfact govern enforce stage --preset minimal
 
 ```bash
 # Step 1: Analyze code
-specfact project import from-code my-project --repo . --confidence 0.7
+specfact code import my-project --repo . --confidence 0.7
 
 # Step 2: Review plan using CLI commands
 specfact project plan review my-project
@@ -320,14 +320,14 @@ specfact project sync repository --repo . --watch --interval 5
 
 ```bash
 # Bundle name is a positional argument (not --name option)
-specfact project import from-code my-project --repo .
+specfact code import my-project --repo .
 
 ```
 
 ### Custom Report
 
 ```bash
-specfact project import from-code \
+specfact code import \
   --repo . \
   --report analysis-report.md
 
@@ -341,21 +341,21 @@ specfact project plan compare \
 
 ```bash
 # Classname format (default for auto-derived)
-specfact project import from-code my-project --repo . --key-format classname
+specfact code import my-project --repo . --key-format classname
 
 # Sequential format (for manual plans)
-specfact project import from-code my-project --repo . --key-format sequential
+specfact code import my-project --repo . --key-format sequential
 
 ```
 
 ### Confidence Threshold
 
 ```bash
 # Lower threshold (more features, lower confidence)
-specfact project import from-code my-project --repo . --confidence 0.3
+specfact code import my-project --repo . --confidence 0.3
 
 # Higher threshold (fewer features, higher confidence)
-specfact project import from-code my-project --repo . --confidence 0.8
+specfact code import my-project --repo . --confidence 0.8
 ```
 
 ## Integration Examples

docs/getting-started/installation.md

@@ -341,7 +341,7 @@ specfact init
 
 ```bash
 # Analyze repository (CI/CD mode - fast)
-specfact project import from-code my-project \
+specfact code import my-project \
   --repo ./my-project \
   --shadow-only \
   --report analysis.md

docs/getting-started/tutorial-openspec-speckit.md

@@ -122,7 +122,7 @@ openspec init
 ```bash
 # Analyze legacy codebase
 cd /path/to/your-openspec-project
-specfact project import from-code legacy-api --repo .
+specfact code import legacy-api --repo .
 
 # Expected output:
 # 🔍 Analyzing codebase...
@@ -143,7 +143,7 @@ specfact project import from-code legacy-api --repo .
 **Note**: If using `hatch run specfact`, run from the specfact-cli directory:
 ```bash
 cd /path/to/specfact-cli
-hatch run specfact project import from-code legacy-api --repo /path/to/your-openspec-project
+hatch run specfact code import legacy-api --repo /path/to/your-openspec-project
 ```
 
 ### Step 4: Create an OpenSpec Change Proposal

docs/guides/ai-ide-workflow.md

@@ -62,7 +62,7 @@ Once initialized, the following slash commands are available in your IDE:
 
 | Slash Command | Purpose | Equivalent CLI Command |
 |---------------|---------|------------------------|
-| `/specfact.01-import` | Import from codebase | `specfact project import from-code` |
+| `/specfact.01-import` | Import from codebase | `specfact code import` |
 | `/specfact.02-plan` | Plan management | `specfact project plan init/add-feature/add-story` |
 | `/specfact.03-review` | Review plan | `specfact project plan review` |
 | `/specfact.04-sdd` | Create SDD manifest | `specfact govern enforce sdd` |
@@ -104,7 +104,7 @@ graph TD
 
 ```bash
 # Import from codebase
-specfact project import from-code my-project --repo .
+specfact code import my-project --repo .
 
 # Run validation to find gaps
 specfact code repro --verbose
@@ -193,7 +193,7 @@ The AI IDE workflow integrates with several command chains:
 
 ```bash
 # 1. Analyze codebase
-specfact project import from-code legacy-api --repo .
+specfact code import legacy-api --repo .
 
 # 2. Find gaps
 specfact code repro --verbose

docs/guides/brownfield-engineer.md

@@ -43,11 +43,11 @@ SpecFact CLI is designed specifically for your situation. It provides:
 
 ```bash
 # Analyze your legacy codebase
-specfact project import from-code legacy-api --repo ./legacy-app
+specfact code import legacy-api --repo ./legacy-app
 
 # For large codebases or multi-project repos, analyze specific modules:
-specfact project import from-code core-module --repo ./legacy-app --entry-point src/core
-specfact project import from-code api-module --repo ./legacy-app --entry-point src/api
+specfact code import core-module --repo ./legacy-app --entry-point src/core
+specfact code import api-module --repo ./legacy-app --entry-point src/api
 ```
 
 **What you get:**
@@ -81,10 +81,10 @@ For large codebases or monorepos with multiple projects, you can analyze specifi
 
 ```bash
 # Analyze only the core module
-specfact project import from-code core-module --repo . --entry-point src/core
+specfact code import core-module --repo . --entry-point src/core
 
 # Analyze only the API service
-specfact project import from-code api-service --repo . --entry-point projects/api-service
+specfact code import api-service --repo . --entry-point projects/api-service
 ```
 
 This enables:
@@ -227,7 +227,7 @@ You inherited a 3-year-old Django app with:
 
 ```bash
 # Step 1: Extract specs
-specfact project import from-code customer-portal --repo ./legacy-django-app
+specfact code import customer-portal --repo ./legacy-django-app
 
 # Output:
 ✅ Analyzed 47 Python files
@@ -289,7 +289,7 @@ SpecFact CLI integrates seamlessly with your existing tools:
 Begin in shadow mode to observe without blocking:
 
 ```bash
-specfact project import from-code legacy-api --repo . --shadow-only
+specfact code import legacy-api --repo . --shadow-only
 ```
 
 ### 2. Add Contracts Incrementally

docs/guides/brownfield-faq.md

@@ -164,7 +164,7 @@ For large codebases, run CrossHair on critical functions first, then expand.
 
 **Recommended workflow:**
 
-1. **Extract specs** (`specfact project import from-code`)
+1. **Extract specs** (`specfact code import`)
 2. **Add contracts** to 3-5 critical functions
 3. **Run CrossHair** to discover edge cases
 4. **Refactor incrementally** (one function at a time)

docs/guides/brownfield-journey.md

@@ -35,7 +35,7 @@ This guide walks you through the complete brownfield modernization journey:
 
 ```bash
 # Analyze your legacy codebase
-specfact project import from-code legacy-api --repo ./legacy-app
+specfact code import legacy-api --repo ./legacy-app
 ```
 
 **What happens:**
@@ -328,7 +328,7 @@ Legacy Django app:
 
 #### Week 1: Understand
 
-- Ran `specfact project import from-code legacy-api --repo .` → 23 features extracted in 8 seconds
+- Ran `specfact code import legacy-api --repo .` → 23 features extracted in 8 seconds
 - Reviewed extracted plan → Identified 5 critical features
 - Time: 2 hours (vs. 60 hours manual)
 

docs/guides/brownfield-roi.md

@@ -150,7 +150,7 @@ SpecFact's code2spec provides similar automation:
 
 **Solution:**
 
-1. Ran `specfact project import from-code` → 47 features extracted in 12 seconds
+1. Ran `specfact code import` → 47 features extracted in 12 seconds
 2. Added contracts to 23 critical data transformation functions
 3. CrossHair discovered 6 edge cases in legacy validation logic
 4. Enforced contracts during migration, blocked 11 regressions
@@ -199,7 +199,7 @@ Calculate your ROI:
 1. **Run code2spec** on your legacy codebase:
 
    ```bash
-   specfact project import from-code legacy-api --repo ./your-legacy-app
+   specfact code import legacy-api --repo ./your-legacy-app
    ```
 
 2. **Time the extraction** (typically < 10 seconds)