feat: Phase 4 complete - Contract generation and density scoring (v0.8.0) (#30)

* Build: Include resources in sdist and wheel builds

Co-authored-by: dominikus.nold <dominikus.nold@web.de>

* feat: Code2Spec Strategic Plan Phase 0 implementation (v0.6.9) (#26)

* feat: Add JSON/YAML support for plan bundles (#27)

* feat: add batch update support for plan review and updates (v0.7.0)

- Add --batch-updates option to plan update-feature command
- Add --batch-updates option to plan update-story command
- Add --list-findings option to plan review command with structured output
- Refactor review function to reduce complexity
- Add comprehensive e2e tests for batch updates
- Update documentation and prompts to prefer batch updates
- Update version to 0.7.0

* fix: remove whitespace from blank lines and apply formatting

* docs: align all documentation with CLI-first, integration-focused positioning

- Updated all examples and guides with CLI-first messaging
- Added Integration Showcases references throughout documentation
- Emphasized integration diversity (VS Code, Cursor, GitHub Actions, pre-commit)
- Updated brownfield showcase examples with integration workflow sections
- Updated platform-frontend CMS to link to Integration Showcases README
- Reviewed and aligned all brownfield documentation for CLI-first approach
- Updated version to 0.7.1

Files updated:
- All docs/examples/ files (6 files)
- All docs/guides/ files (6 files)
- docs/reference/directory-structure.md
- platform-frontend/iac/scripts/payload-content-helper.js
- Version files: pyproject.toml, setup.py, src/__init__.py, src/specfact_cli/__init__.py
- CHANGELOG.md with comprehensive 0.7.1 entry

* fix: resolve type checking errors in constitution_evidence_extractor

- Fixed basedpyright warnings for repo_path.exists() in contract decorators
- Added isinstance() type guard to properly narrow Path | None types
- Updated Example 3 validation status to FULLY VALIDATED (CI/CD workflow verified in production)
- Updated documentation to reflect Example 3 is validated in specfact-cli repository CI/CD

Fixes type checking errors reported in GitHub Actions workflow:
- constitution_evidence_extractor.py:65:53 - Type of "exists" is unknown
- Fixed in all three methods: extract_article_vii_evidence, extract_article_viii_evidence, extract_article_ix_evidence

Example 3 Status Update:
- Changed from "COMMANDS VERIFIED" to "FULLY VALIDATED"
- Validated in production CI/CD (specfact-cli PR #28)
- Workflow successfully runs specfact repro and blocks PRs when validation fails

* Fix typecheck error

* Fix all type check errors

* Fix type annotations

* feat: Phase 4 complete - Contract generation and density scoring

- Add contract density validator (contract_validator.py) with metrics calculation
- Integrate contract density into enforce sdd and plan review commands
- Add contract density metrics display in plan review output
- Fix plan bundle hash persistence in plan harden command
- Add integration test for plan bundle hash persistence
- Update version to 0.8.0
- Update CHANGELOG.md with Phase 4 completion details
- Update end-user documentation with new commands (plan harden, enforce sdd, generate contracts)

Phase 4 Status: ✅ COMPLETE (2025-11-24)
- 4.1 Contract Stub Generator: ✅ Complete
- 4.2 Contract Density Scoring: ✅ Complete (10 unit tests passing)

Test Coverage:
- 10 unit tests for contract density validation
- 1 integration test for hash persistence
- All tests passing

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Dominikus Nold <dominikus@nold-ai.com>

Author: 3 people

CHANGELOG.md

@@ -9,6 +9,66 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.8.0] - 2025-11-24
+
+### Added (0.8.0)
+
+- **Phase 4: Contract Generation from SDD - Complete**
+  - **Contract Density Scoring** (`src/specfact_cli/validators/contract_validator.py`)
+    - New `ContractDensityMetrics` class for tracking contract density metrics
+    - `calculate_contract_density()` function calculates contracts per story, invariants per feature, and architecture facets
+    - `validate_contract_density()` function validates metrics against SDD coverage thresholds
+    - Integrated into `specfact enforce sdd` command for automatic validation
+    - Integrated into `specfact plan review` command with metrics display
+    - Comprehensive unit test suite (10 tests) covering all validation scenarios
+
+- **Contract Density Metrics Display**
+  - `specfact plan review` now displays contract density metrics when SDD manifest is present
+  - Shows contracts/story, invariants/feature, and architecture facets with threshold comparisons
+  - Provides actionable feedback when thresholds are not met
+  - Integrated with SDD validation workflow
+
+### Changed (0.8.0)
+
+- **SDD Enforcement Integration**
+  - `specfact enforce sdd` now uses centralized contract density validator
+  - Refactored duplicate contract density calculation logic into reusable validator module
+  - Improved consistency across `enforce sdd` and `plan review` commands
+  - Contract density validation now part of standard SDD enforcement workflow
+
+- **Plan Harden Command Enhancement**
+  - `specfact plan harden` now saves plan bundle with updated hash after calculation
+  - Ensures plan bundle hash persists to disk for subsequent commands
+  - Prevents hash mismatch errors when running `specfact generate contracts` after `plan harden`
+  - Improved reliability of SDD-plan bundle linkage
+
+### Fixed (0.8.0)
+
+- **Plan Bundle Hash Persistence**
+  - Fixed bug where `plan harden` calculated hash but didn't save plan bundle to disk
+  - Plan bundle now correctly saved with updated summary metadata containing hash
+  - Subsequent commands (e.g., `generate contracts`) can now load plan and get matching hash
+  - Added integration test `test_plan_harden_persists_hash_to_disk` to prevent regression
+
+- **Contract-First Testing Coverage**
+  - Added test to verify plan bundle hash persistence after `plan harden`
+  - Test would have caught the hash persistence bug if run earlier
+  - Demonstrates value of contract-first testing approach
+
+### Testing (0.8.0)
+
+- **Contract Validator Test Suite**
+  - 10 comprehensive unit tests for contract density calculation and validation
+  - Tests cover empty plans, threshold violations, multiple violations, and edge cases
+  - All tests passing with full coverage of validation scenarios
+
+- **Integration Test Coverage**
+  - Enhanced `test_plan_harden` suite with hash persistence verification
+  - New test `test_plan_harden_persists_hash_to_disk` ensures plan bundle is saved correctly
+  - All integration tests passing (8 tests)
+
+---
+
 ## [0.7.1] - 2025-01-22
 
 ### Changed (0.7.1)

docs/examples/README.md

@@ -8,13 +8,35 @@ Real-world examples of using SpecFact CLI.
   - **CLI-First**: Works offline, no account required, integrates with any IDE
   - Start with the [Integration Showcases README](integration-showcases/README.md) for an overview
   - Read the [main showcase document](integration-showcases/integration-showcases.md) for real examples
+- **[Brownfield Examples](#brownfield-examples)** ⭐ **NEW** - Complete hard-SDD workflow demonstrations
+  - **[Django Modernization](brownfield-django-modernization.md)** - Legacy Django app → contract-enforced modern codebase
+  - **[Flask API](brownfield-flask-api.md)** - Legacy Flask API → contract-enforced modern service
+  - **[Data Pipeline](brownfield-data-pipeline.md)** - Legacy ETL pipeline → contract-enforced data processing
+  - All examples now include: `plan harden`, `enforce sdd`, `plan review`, and `plan promote` with SDD validation
+- **[Quick Examples](quick-examples.md)** - Quick code snippets for common tasks, including SDD workflow
 - **[Dogfooding SpecFact CLI](dogfooding-specfact-cli.md)** - We ran SpecFact CLI on itself (< 10 seconds!)
 
 ## Quick Start
 
 ### See It In Action
 
-Read the complete dogfooding example to see SpecFact CLI in action:
+**For Brownfield Modernization** (Recommended):
+
+Read the complete brownfield examples to see the hard-SDD workflow:
+
+**[Django Modernization Example](brownfield-django-modernization.md)**
+
+This example shows the complete workflow:
+
+1. ⚡ **Extract specs** from legacy code → 23 features, 112 stories in **8 seconds**
+2. 📋 **Create SDD manifest** → Hard spec with WHY/WHAT/HOW, coverage thresholds
+3. ✅ **Validate SDD** → Hash match, coverage threshold validation
+4. 📊 **Review plan** → SDD validation integrated, ambiguity resolution
+5. 🚀 **Promote plan** → SDD required for "review" or higher stages
+6. 🔒 **Add contracts** → Runtime enforcement prevents regressions
+7. 🔍 **Re-validate SDD** → Ensure coverage thresholds maintained
+
+**For Quick Testing**:
 
 **[Dogfooding SpecFact CLI](dogfooding-specfact-cli.md)**
 

docs/examples/brownfield-data-pipeline.md

@@ -21,6 +21,8 @@ You inherited a 5-year-old Python data pipeline with:
 
 ## Step 1: Reverse Engineer Data Pipeline
 
+> **Note**: This example demonstrates the complete hard-SDD workflow, including SDD manifest creation, validation, and plan promotion gates. The SDD manifest serves as your "hard spec" - a canonical reference that prevents drift during modernization.
+
 **CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE.
 
 ### Extract Specs from Legacy Pipeline
@@ -74,7 +76,70 @@ features:
 
 ---
 
-## Step 2: Add Contracts to Data Transformations
+## Step 2: Create Hard SDD Manifest
+
+After extracting the plan, create a hard SDD manifest:
+
+```bash
+# Create SDD manifest from the extracted plan
+specfact plan harden
+```
+
+### Output
+
+```text
+✅ SDD manifest created: .specfact/sdd.yaml
+
+📋 SDD Summary:
+   WHY: Modernize legacy ETL pipeline with zero data corruption
+   WHAT: 18 ETL jobs, 67 stories extracted from legacy code
+   HOW: Runtime contracts, data validation, incremental enforcement
+
+🔗 Linked to plan: customer-etl (hash: ghi789jkl012...)
+📊 Coverage thresholds:
+   - Contracts per story: 1.0 (minimum)
+   - Invariants per feature: 2.0 (minimum)
+   - Architecture facets: 3 (minimum)
+```
+
+---
+
+## Step 3: Validate SDD Before Modernization
+
+Validate that your SDD manifest matches your plan:
+
+```bash
+# Validate SDD manifest against plan
+specfact enforce sdd
+```
+
+### Output
+
+```text
+✅ Hash match verified
+✅ Contracts/story: 1.1 (threshold: 1.0) ✓
+✅ Invariants/feature: 2.3 (threshold: 2.0) ✓
+✅ Architecture facets: 4 (threshold: 3) ✓
+
+✅ SDD validation passed
+```
+
+---
+
+## Step 4: Promote Plan with SDD Validation
+
+Promote your plan to "review" stage (requires valid SDD):
+
+```bash
+# Promote plan to review stage
+specfact plan promote --stage review
+```
+
+**Why this matters**: Plan promotion enforces SDD presence, ensuring you have a hard spec before starting modernization work.
+
+---
+
+## Step 5: Add Contracts to Data Transformations
 
 ### Before: Undocumented Legacy Transformation
 
@@ -142,9 +207,17 @@ def transform_order(raw_order: Dict[str, Any]) -> Dict[str, Any]:
     }
 ```
 
+### Re-validate SDD After Adding Contracts
+
+After adding contracts, re-validate your SDD:
+
+```bash
+specfact enforce sdd
+```
+
 ---
 
-## Step 3: Discover Data Edge Cases
+## Step 6: Discover Data Edge Cases
 
 ### Run CrossHair on Data Transformations
 
@@ -198,7 +271,7 @@ def transform_order(raw_order: Dict[str, Any]) -> Dict[str, Any]:
 
 ---
 
-## Step 4: Modernize Pipeline Safely
+## Step 7: Modernize Pipeline Safely
 
 ### Refactor with Contract Safety Net
 
@@ -299,10 +372,13 @@ SpecFact CLI integrates seamlessly with your existing tools:
 ### What Worked Well
 
 1. ✅ **code2spec** extracted pipeline structure automatically
-2. ✅ **Contracts** enforced data validation at runtime
-3. ✅ **CrossHair** discovered edge cases in data transformations
-4. ✅ **Incremental modernization** reduced risk
-5. ✅ **CLI-first integration** - Works offline, no account required, no vendor lock-in
+2. ✅ **SDD manifest** created hard spec reference, preventing drift
+3. ✅ **SDD validation** ensured coverage thresholds before modernization
+4. ✅ **Plan promotion gates** required SDD presence, enforcing discipline
+5. ✅ **Contracts** enforced data validation at runtime
+6. ✅ **CrossHair** discovered edge cases in data transformations
+7. ✅ **Incremental modernization** reduced risk
+8. ✅ **CLI-first integration** - Works offline, no account required, no vendor lock-in
 
 ### Lessons Learned