feat: Phase 6 OpenAPI Contract Enforcement (0.16.3) (#49)

* feat: v0.13.2 - Add --install-deps option and enhance contract workflow (#42)

* feat: AI IDE contract enhancement workflow and critical bug fixes (v0.13.0)

- Added generate contracts-prompt command for AI IDE integration
- Added generate contracts-apply with comprehensive 6-step validation
- Fixed AttributeError in sync.py, import_cmd.py, enforce.py (71 test failures resolved)
- Renamed --apply all to --apply all-contracts for clarity
- Bundle-specific prompt storage (.specfact/projects/<bundle>/prompts/)
- Enhanced error messages and validation feedback
- Updated documentation (commands, directory structure, IDE integration)
- Updated internal implementation plans

Version bump: 0.12.1 → 0.13.0

* feat: v0.13.2 - Add --install-deps option and enhance contract workflow

- Add specfact init --install-deps option for streamlined setup
- Enhance contracts-apply with automatic code quality checks
- Optimize test execution in contracts-apply (scoped pytest runs)
- Strengthen LLM abort conditions in generated prompts
- Clarify contract application requirements (ALL eligible functions)
- Update documentation for new features
- Bump version to 0.13.2 and sync across all files

* fix: v0.13.3 - Improve data model detection in contract analysis

- Fix false positives for Pydantic data model files
- Properly distinguish between class methods and module-level functions
- Add support for common helper methods (compute_summary, update_summary, etc.)
- Increase E2E test timeouts from 5s to 20s for slow tests
- Files like models/plan.py and models/protocol.py now correctly identified as data models

* feat: Add /specfact.07-contracts slash command for contract enhancement workflow

- New sequential workflow: analyze contracts → generate prompts → apply contracts
- Processes files one at a time for careful review
- Supports user selection of files to enhance
- Includes validation and confirmation steps
- Updated documentation with new slash command

* docs: Update prompt validation checklist with specfact.07-contracts

* docs: Update prompt validation checklist to match actual prompt structure

- Updated required sections to match actual format:
  - User Input (with )
  - Purpose
  - Parameters (organized by groups)
  - Workflow
  - CLI Enforcement
  - Expected Output
  - Common Patterns
  - Context (with {ARGS})
- Removed outdated sections (CRITICAL, Wait States, Goal, Operating Constraints)
- Updated wait state validation to reflect actual structure

* fix: Update prompt validation tool to match actual prompt structure

- Updated required sections to match actual format:
  - User Input, Purpose, Parameters, Workflow, CLI Enforcement, Expected Output, Common Patterns, Context
- Removed outdated sections (CRITICAL, Wait States, Goal, Operating Constraints)
- Made CLI enforcement rule matching flexible (multiple variants)
- Updated dual-stack workflow markers to be flexible
- Added specfact.07-contracts to CLI_COMMANDS mapping
- Updated wait state validation to check for User Input section and
- All 9 prompts now pass validation

* fix: Resolve prompt validation warnings

- Added 'Use CLI output as grounding' to specfact.07-contracts.md
- Added explicit CLI enforcement rules to specfact.validate.md
- Added enrichment report location to specfact.01-import.md workflow
- All 9 prompts now pass validation with 0 errors and 0 warnings

* Update prompts and validation

* feat: Include specfact.07-contracts in init command

- Added specfact.07-contracts to SPECFACT_COMMANDS list in ide_setup.py
- Updated VS Code settings example in ide-integration.md to include new prompt
- New contract enhancement workflow prompt will now be copied during init

* Fix ruff linter errors

* fix: Update test_validate_structure to match new prompt structure

- Updated test to use new required sections (User Input, Purpose, Parameters, Workflow, CLI Enforcement, Expected Output, Common Patterns, Context)
- Test now matches actual prompt structure used in resources/prompts/
- All prompt validation tests passing

* Add missing contracts to analyze agent2

---------

Co-authored-by: Dominikus Nold <[email protected]>

* feat: implement Phase 4.11 Dual-Stack Enrichment Pattern (#43)

- Add dual-stack workflow documentation to all 10 prompt templates
- Enhance CLI enforcement rules with CLI vs LLM capabilities
- Create validation utilities (cli_first_validator.py) with 4 functions
- Add comprehensive tests (23 test cases, all passing)
- Create end-user guide (docs/guides/dual-stack-enrichment.md)
- Create technical specification (docs/technical/dual-stack-pattern.md)
- Fix test timeouts for 12 integration/e2e tests (add @pytest.mark.timeout(20))
- Update .cursor/commands/ prompts with dual-stack pattern

Implements:
- CLI-first principle enforcement
- Standard validation loop pattern documentation
- Three-phase workflow (CLI Grounding → LLM Enrichment → CLI Artifact Creation)
- .specfact/ folder protection validation
- Format consistency validation

All success criteria met for Phase 4.11. Future enhancements (metadata injection,
code generation workflow, plan enrichment workflow) are deferred to future phases.

Closes: Phase 4.11 implementation

Co-authored-by: Dominikus Nold <[email protected]>

* feat: Phase 4.9 (Quick Start) and Phase 4.10 (CI Performance) Optimization (#44)

* feat: implement Phase 4.9 (Quick Start) and Phase 4.10 (CI Performance)

- Phase 4.9: Quick Start Optimization
  - Add incremental results callback to CodeAnalyzer for real-time feature discovery
  - Implement _suggest_next_steps() function with contextual next commands
  - Add early feedback mechanism showing first value within < 60 seconds
  - Enhance progress indicators with incremental updates every 5 features
  - Create comprehensive e2e tests (6 tests, all passing)

- Phase 4.10: CI Performance Optimization
  - Create performance monitoring utility (src/specfact_cli/utils/performance.py)
  - Integrate performance tracking into import command with threshold-based detection
  - Add performance report display (non-CI mode only) for interactive feedback
  - Track all major operations: analyze_codebase, extract_relationships, etc.
  - Create comprehensive unit tests (8 tests, all passing)
  - Create comprehensive e2e tests (6 tests, all passing)

Files:
- src/specfact_cli/analyzers/code_analyzer.py - Added incremental callback support
- src/specfact_cli/commands/import_cmd.py - Added next steps suggestions and performance tracking
- src/specfact_cli/utils/performance.py - New performance monitoring utility
- tests/unit/utils/test_performance.py - Unit tests (8 tests)
- tests/e2e/test_quick_start_performance_e2e.py - E2E tests (6 tests)

All tests passing. Documentation updated in internal repo.

* chore: bump version to 0.14.0 and update changelog

- Bump version from 0.13.3 to 0.14.0 (minor version for new features)
- Sync version across pyproject.toml, src/__init__.py, and src/specfact_cli/__init__.py
- Add comprehensive changelog entry for Phase 4.9 and 4.10 features

---------

Co-authored-by: Dominikus Nold <[email protected]>

* feat: Natural UX Flow - Phases 4.1-4.5 Complete (#45)

* feat: implement Phases 4.1-4.5 - Natural UX Flow enhancements

- Phase 4.1: Context Detection System
  - Auto-detect project type, language, framework, specs, and configuration
  - Smart defaults based on detected context
  - Comprehensive test coverage (8 unit + 3 E2E tests)

- Phase 4.2: Progressive Disclosure
  - Hide advanced options by default
  - Reveal via --help-advanced flag
  - Custom ProgressiveDisclosureGroup for Typer
  - Test coverage (6 unit + 2 E2E tests)

- Phase 4.3: Intelligent Suggestions & Template-Driven Quality
  - Context-aware command suggestions
  - Error-specific fix suggestions
  - Template system for specification quality
  - Feature, implementation plan, and contract extraction templates
  - Test coverage (10 unit + 6 E2E tests)

- Phase 4.4: Enhanced Watch Mode
  - Hash-based change detection (SHA256)
  - Dependency tracking for incremental processing
  - LZ4 compression for cache (optional)
  - Persistent hash cache across sessions
  - Test coverage (9 unit + 2 E2E tests)

- Phase 4.5: Unified Progress Display
  - Verified consistent n/m format across all commands
  - Rich Progress integration with timing information

- Documentation Updates
  - New UX Features guide (guides/ux-features.md)
  - Updated command reference with --help-advanced
  - Updated workflows guide with watch mode enhancements
  - Updated first-steps guide with context detection info

- Plan Status Updates
  - Marked Phases 4.1-4.5 as COMPLETE in internal plan
  - Updated progress percentages and status

All tests passing (228 total, 61 new tests for these phases)

* chore: bump version to 0.14.1 - Natural UX Flow Phases 4.1-4.5

- Phase 4.1: Context Detection System
- Phase 4.2: Progressive Disclosure (--help-advanced)
- Phase 4.3: Intelligent Suggestions & Template-Driven Quality
- Phase 4.4: Enhanced Watch Mode (hash-based detection)
- Phase 4.5: Unified Progress Display

Added comprehensive documentation and 61 new tests (all passing)

* chore: bump version to 0.14.2

- Update version in src/__init__.py, pyproject.toml, setup.py
- Add changelog entry for 0.14.2
- Document Phase 4.2 Progressive Disclosure final implementation
- Fix internal plan status inconsistencies and improve readability

---------

Co-authored-by: Dominikus Nold <[email protected]>

* chore: bump version to 0.15.0

- Phase 8.5: Bundle-Specific Artifact Organization completed
- Fixed atomic bundle saves to preserve reports/ and logs/ directories
- Removed legacy directories (plans/, gates/results/) from ensure_structure()
- Migrated active bundle config to global config.yaml
- Removed GWT patterns from ControlFlowAnalyzer
- Added comprehensive tests for ControlFlowAnalyzer
- Updated all documentation to reflect bundle-specific artifact organization
- Fixed integration tests for new directory structure
- Fixed progress bar UI in import from-code command

BREAKING CHANGE: Report paths, SDD manifests, and task files now use bundle-specific locations

* fix: remove duplicate 'First value' and 'Themes detected' messages from import command

- Removed intermediate console.print messages that duplicated progress bar information
- Progress bar already shows feature count in description
- Final summary provides complete information (features, themes, stories)
- Cleaner output without redundant messages

* Fix formatting

* fix: recognize simplified acceptance criteria format and add --output-questions option

- Fixed ambiguity scanner to recognize simplified format (e.g., 'Must verify X works correctly (see contract examples)') as valid
- Added --output-questions option to save questions directly to file, avoiding complex JSON parsing
- Enhanced CLI enforcement warnings in prompt documentation
- Updated version to 0.15.1

* Improve review prompt, add cleanup script

* fix(plan): integrate INTERACTION_UX answers and improve coverage display

- Add INTERACTION_UX category to integration logic in _integrate_clarification
- Fix unclear findings count to accurately reflect findings that can generate questions
- Improve coverage summary display: show '143 Partial' when all unclear, '5/143 Partial' when partially clarified
- Fix format errors: remove unused question_id variable assignments
- Bump version to 0.15.5

* chore: add findings.json to .gitignore

* feat: Project Bundle Phase 5-6 - Persona Workflows & OpenAPI Enforcement (v0.16.1) (#46)

* chore: bump version to 0.16.0

- Fixed contract generation path resolution for bundle-specific locations
- Improved error handling for invalid personas with --list-personas flag
- Fixed sdd_path possibly unbound errors in generate command
- Enhanced persona workflow UX with optional --persona and better error messages
- Fixed SDD discovery to correctly identify bundle-specific SDDs
- Fixed contract generator logic errors
- Updated all tests to use bundle-specific paths
- Added comprehensive changelog entry for v0.16.0

* feat: complete Phase 5.1.6 - Developer & Architect template enhancements (v0.16.1)

- Enhanced Developer template with task breakdown, technical design, code mappings, sprint context, and Definition of Done
- Enhanced Architect template with architectural decisions, NFRs, protocols/state machines, contracts, risk assessment, and deployment architecture
- Fixed Markdown linting issues (MD012, MD024, MD036) in persona templates
- Fixed data model alignment issues in persona exporter (feature.constraints handling)
- Enhanced context preparation to include protocols and contracts from bundle directory
- Updated documentation to emphasize persona-based workflows and agile team integration
- Added comprehensive Agile/Scrum Workflows guide
- Added project export/import command documentation
- Updated READMEs to position SpecFact as team collaboration tool for agile/scrum teams
- Bumped version to 0.16.1 and updated CHANGELOG

All three persona templates (Product Owner, Developer, Architect) are now production-ready and aligned with real-world agile/scrum expectations.

* Add defaults for linter

---------

Co-authored-by: Dominikus Nold <[email protected]>

* feat: implement Phase 5.3 lock enforcement with E2E tests

- Add lock enforcement to project import command
- Implement check_sections_locked_for_persona() helper
- Add comprehensive E2E integration tests (5 tests, all passing)
- Fix Markdown parser to handle *(mandatory)* markers
- Disable agile validation in test mode for simpler test scenarios
- Add lock workflow documentation to agile-scrum-workflows guide
- Add lock command documentation to command reference
- Fix template path resolution for development and installed scenarios
- Update version to 0.16.2

Phase 5.3 (Lock Enforcement) complete:
- Lock/unlock commands working
- Import operations respect locks
- Persona validation against locks
- Real-world scenarios tested and working

* feat: Add contract verify command and improve mock server reliability (Phase 6.4) (#48)

* feat: implement Phase 6 OpenAPI Contract Enforcement

- Phase 6.1: Add contract index to manifest for fast lookup
- Phase 6.2: Implement contract serve and test commands
  - contract serve: Launch Specmatic mock server for contract testing
  - contract test: Generate Specmatic test suites from contracts
- Phase 6.3: SDD Integration (already complete)
  - plan harden extracts OpenAPI contracts automatically
  - enforce sdd validates OpenAPI coverage percentage
- Add comprehensive integration tests (8 tests, all passing)
- Update end user documentation with contract command reference
- Update internal plans to mark Phase 6 as complete
- Fix enum serialization in manifest save (use model_dump(mode='json'))

All tests passing, coverage maintained at 80%+

* feat: add contract verify command and improve mock server reliability

- Add contract verify command (Phase 6.4) - all-in-one verification workflow
- Improve mock server process management with port polling and better error handling
- Add automatic example generation from OpenAPI schema
- Fix path handling issues in contract commands (relative_to errors)
- Fix exit code handling in contract test command
- Update documentation with simplified workflow guide
- Add comprehensive integration tests (4 tests for contract verify)
- Update UI/UX consistency across all contract commands

Closes: Phase 6.4 Contract Verify implementation
Version: 0.16.2 → 0.16.3

* sync version

* Fix unit test

* fix: reorder contract checks and mock Specmatic in tests

- Move Specmatic availability check after contract validation in contract test command
- This ensures 'no contract' errors are shown before Specmatic errors
- Add mocks for Specmatic availability in verify command tests
- Mock generate_specmatic_examples in verify tests to avoid async issues
- All 3 previously failing tests now pass

Fixes:
- test_test_contract_no_contract: Now checks contract before Specmatic
- test_verify_contract_skip_mock: Mocks Specmatic availability
- test_verify_contract_all_contracts: Mocks Specmatic availability and example generation

* applied format

* fix: resolve type errors for optional output_dir parameter

- Add check to set default output_dir if None before using it
- Ensures output_dir is always Path type when calling relative_to() and path operations
- Fixes basedpyright errors at lines 1174 and 1191

Fixes:
- reportOptionalMemberAccess: 'relative_to' is not a known attribute of 'None'
- reportOptionalOperand: Operator '/' not supported for 'None'

---------

Co-authored-by: Dominikus Nold <[email protected]>

---------

Co-authored-by: Dominikus Nold <[email protected]>

Author: djm81

CHANGELOG.md

@@ -9,6 +9,97 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.16.3] - 2025-12-13
+
+### Added (0.16.3)
+
+- **Contract Verify Command** - Phase 6.4: All-in-one contract verification workflow
+  - **New Command**: `specfact contract verify` combines validation, example generation, mock server, and connectivity testing
+  - **Simplified Workflow**: Single command replaces multiple manual steps for contract verification
+  - **Step-by-Step Output**: Clear progress indicators showing validation, example generation, mock server startup, and connectivity testing
+  - **CI/CD Support**: `--skip-mock --no-interactive` flags for fast validation in pipelines
+  - **Multiple Contracts**: Supports verifying single contract or all contracts in bundle
+  - **Integration Tests**: Comprehensive test coverage (4 tests, all passing)
+
+- **Mock Server Improvements** - Enhanced process management and reliability
+  - **Improved Wait Logic**: Port polling with 10-second timeout ensures server is ready before returning
+  - **Better Error Handling**: Clear error messages when server fails to start or port is not accessible
+  - **Process Management**: Robust process handling with proper cleanup on errors
+  - **Example Auto-Detection**: Automatically detects and uses generated examples when available
+
+- **Documentation** - Simplified contract testing workflow guide
+  - **Quick Start Guide**: New `contract-testing-workflow.md` with simple, developer-friendly examples
+  - **Command Reference**: Complete documentation for `contract verify` command
+  - **Workflow Examples**: Clear examples for common use cases (development, CI/CD, multiple contracts)
+  - **Troubleshooting**: Added troubleshooting section with common issues and solutions
+
+### Improved (0.16.3)
+
+- **Contract Commands UX** - Consistent UI/UX across all contract commands
+  - All contract commands now use `load_bundle_with_progress` and `save_bundle_with_progress` for consistent progress indicators
+  - Standardized section headers and telemetry tracking across all commands
+  - Better error messages and user feedback
+
+- **Specmatic Integration** - Enhanced example generation and mock server reliability
+  - Automatic example generation from OpenAPI schema
+  - Improved mock server startup with port verification
+  - Better handling of Specmatic configuration warnings (non-blocking)
+
+### Fixed (0.16.3)
+
+- **Path Handling** - Fixed `relative_to()` errors in contract commands
+  - Resolves repository path to absolute before calling `relative_to()` for display paths
+  - Graceful fallback to absolute paths when relative path calculation fails
+  - Prevents errors when output directories are outside repository
+
+- **Exit Code Handling** - Fixed contract test command exit codes
+  - Corrected indentation to ensure `typer.Exit(1)` is properly executed on errors
+  - Integration tests now correctly validate error conditions
+
+---
+
+## [0.16.2] - 2025-12-12
+
+### Added (0.16.2)
+
+- **Lock Enforcement** - Phase 5.3: Section-level locking for persona-based workflows
+  - **Lock Commands**: Added `project lock` and `project unlock` commands for section-level locking
+  - **Lock Enforcement**: Import operations now check locks before saving - blocks imports when sections are locked by different personas
+  - **Persona Validation**: Added `check_sections_locked_for_persona()` helper to validate persona ownership against locks
+  - **Lock Workflow**: Complete lock/unlock workflow with clear error messages showing locked sections and owners
+  - **E2E Tests**: Comprehensive integration tests covering concurrent edits, lock conflicts, and unlock workflows (5 tests, all passing)
+
+- **Documentation** - Lock enforcement workflow documentation
+  - Added "Section Locking" section to Agile/Scrum Workflows guide with real-world examples
+  - Added `project lock`, `project unlock`, and `project locks` command documentation to command reference
+  - Documented lock enforcement behavior, best practices, and troubleshooting
+
+### Fixed (0.16.2)
+
+- **Persona Importer** - Fixed Markdown parsing for exported files
+  - Fixed regex to properly remove `*(mandatory)*` markers from section headings
+  - Handles both `*(mandatory)*` and `(mandatory)` formats
+  - Improved section name normalization for better template matching
+
+- **Template Path Resolution** - Fixed template path calculation for development and installed scenarios
+  - Enhanced template path detection to work in both development (source) and installed package environments
+  - Added fallback logic for multiple possible template locations
+  - Fixed exception handling in export command to show errors properly
+
+- **Test Mode** - Disabled agile validation in test mode
+  - Import command now disables strict DoR validation when `TEST_MODE=true`
+  - Allows tests to focus on lock enforcement without requiring complete DoR data
+
+### Improved (0.16.2)
+
+- **Project Bundle Phase 5.3** - Lock Enforcement implementation complete
+  - Lock enforcement working in practice with real-world scenarios
+  - All E2E integration tests passing (5/5)
+  - Lock enforcement prevents concurrent edits while allowing persona-owned sections to be edited
+  - Clear error messages guide users when locks block operations
+
+---
+
 ## [0.16.1] - 2025-12-12
 
 ### Added (0.16.1)

docs/README.md

@@ -148,6 +148,7 @@ SpecFact isn't just a technical tool—it's designed for **real-world agile/scru
 - [Persona Workflows](guides/agile-scrum-workflows.md#persona-based-workflows) - Role-based workflows for agile teams
 - [Definition of Ready](guides/agile-scrum-workflows.md#definition-of-ready-dor) - DoR validation and sprint planning
 - [Dependency Management](guides/agile-scrum-workflows.md#dependency-management) - Track story and feature dependencies
+- [Conflict Resolution](guides/agile-scrum-workflows.md#conflict-resolution) - Persona-aware merge conflict resolution
 
 #### General Guides