v0.24.1

Fixed (0.24.1)

• Flask Route Extraction: Fixed Flask extractor to capture all HTTP methods

  • Issue: When a Flask route declared multiple methods (e.g., methods=['GET','POST']), only the first method was extracted
  • Fix: Modified _extract_route_from_function() to return one RouteInfo per HTTP method
  • Impact: All HTTP methods are now properly extracted and included in generated contracts
  • Example: @app.route('/path', methods=['GET', 'POST']) now generates both GET and POST routes

• Flask Path Parameter Names: Fixed parameter name extraction for converter-based paths

  • Issue: For Flask routes using converters with explicit names (e.g., <uuid:user_id>), the parameter name was overwritten with the converter name, resulting in {uuid} instead of {user_id}
  • Fix: Updated _extract_path_parameters() to preserve parameter names from the second regex group when present
  • Impact: Converter-based paths now correctly extract parameter names (e.g., <uuid:user_id> → {user_id})
  • Example: Routes like <uuid:user_id> and custom converters now preserve the actual parameter name

v0.24.0

Added (0.24.0)

• Sidecar Validation CLI Integration: Native CLI integration for sidecar validation workflow

  • New Command: specfact validate sidecar init <bundle-name> <repo-path> - Initialize sidecar workspace for validation
  • New Command: specfact validate sidecar run <bundle-name> <repo-path> - Run complete sidecar validation workflow
  • Framework Detection: Automatic detection of Django, FastAPI, DRF, and pure Python frameworks
  • Route Extraction: Framework-specific route and schema extraction (Django URLs, FastAPI routes, DRF serializers)
  • Contract Population: Automatic population of OpenAPI contracts with extracted routes and schemas
  • Harness Generation: CrossHair harness generation from populated contracts
  • Tool Execution: Integration with CrossHair symbolic execution and Specmatic contract testing
  • Environment Manager Support: Automatic detection and use of hatch, poetry, uv, and pip environments
  • Venv Detection: Automatic detection and configuration of .venv and venv virtual environments
  • Progress Reporting: Rich console progress indicators for long-running operations
  • Backward Compatibility: Full compatibility with existing template-based sidecar workspaces

• CrossHair Summary Reporting: Enhanced CrossHair output parsing and reporting

  • Summary Parser: New crosshair_summary.py module for parsing CrossHair stdout/stderr
  • Summary File Generation: Automatic generation of crosshair-summary-{timestamp}.json files
  • Console Display: Formatted summary line showing confirmed/not confirmed/violations counts
  • Integration: Summary parsing integrated into sidecar validation orchestrator
  • Testing: Comprehensive unit tests (15 tests) covering various output scenarios

• Specmatic Auto-Skip: Intelligent detection and skipping of Specmatic when no service is available

  • Service Detection: New has_service_configuration() function to detect available service endpoints
  • Auto-Skip Logic: Specmatic automatically skipped when no test_base_url, host/port, or app server configuration detected
  • Clear Messaging: User-friendly warning messages when Specmatic is skipped
  • Manual Override: --run-specmatic flag to force execution even without service configuration
  • Testing: Unit tests (8 tests) for service detection and auto-skip logic
  • Documentation: Updated sidecar validation guide and command reference with auto-skip behavior

• Repro Sidecar Integration: Sidecar validation integrated into specfact repro command

  • New Options: --sidecar and --sidecar-bundle <name> options for repro command
  • Unannotated Code Detection: AST-based detection of functions without icontract/beartype decorators
    • New unannotated_detector.py module with AST parsing
    • Detects unannotated functions across repositories
    • Skips test files and harness files automatically
    • Comprehensive unit tests (7 tests)
  • Safe Defaults: Automatic application of safe timeout defaults for repro mode
    • TimeoutConfig.safe_defaults_for_repro() method with conservative timeouts
    • CrossHair timeout: 30s (vs 60s default)
    • Per-path timeout: 5s
    • Per-condition timeout: 2s
    • Unit tests (2 tests) for safe defaults
  • Deterministic Inputs: Support for deterministic inputs from harness inputs.json
    • use_deterministic_inputs flag in CrossHairConfig
    • Per-path and per-condition timeout support in CrossHair runner
    • Automatic application in repro mode
  • Integration Tests: Comprehensive integration tests (3 tests) for repro sidecar workflow
  • Documentation: Updated command reference and sidecar validation guide with repro integration examples

• New Python Modules: Complete sidecar validation package

  • src/specfact_cli/validators/sidecar/ - Sidecar validation orchestrator and utilities
  • src/specfact_cli/validators/sidecar/frameworks/ - Framework-specific extractors (Django, FastAPI, DRF)
  • src/specfact_cli/commands/validate.py - Validation command group with sidecar subcommands
  • src/specfact_cli/validators/sidecar/crosshair_summary.py - CrossHair output parsing and summary generation
  • src/specfact_cli/validators/sidecar/unannotated_detector.py - AST-based unannotated code detection
  • tests/unit/specfact_cli/validators/sidecar/test_crosshair_summary.py - Summary parser tests
  • tests/unit/specfact_cli/validators/sidecar/test_specmatic_runner_auto_skip.py - Auto-skip logic tests
  • tests/unit/specfact_cli/validators/sidecar/test_unannotated_detector.py - Unannotated detection tests
  • tests/unit/specfact_cli/validators/sidecar/test_timeout_config_safe_defaults.py - Safe defaults tests
  • tests/integration/commands/test_repro_sidecar.py - Repro sidecar integration tests

• Environment Manager Integration: Enhanced environment detection for sidecar validation

  • Venv detection and Python path configuration
  • PYTHONPATH building with venv site-packages, source directories, and repo root
  • Tool execution with environment manager prefixes (hatch run, poetry run, uv run)

• Testing: Comprehensive test coverage (69 sidecar-related tests, ≥80% coverage)

  • Unit tests for all framework extractors and core workflow components
  • Integration tests for CLI commands and backward compatibility
  • End-to-end tests for complete validation workflows
  • Verification tests against real-world repositories
  • 35 new tests for CrossHair summary, Specmatic auto-skip, unannotated detection, safe defaults, and repro integration

Changed (0.24.0)

• Init Command: Updated specfact init --install-deps to include sidecar validation tools

  • Added comment about sidecar validation tools (crosshair-tool already included)
  • Note: specmatic may need separate installation (Java-based tool)

• CrossHair Runner: Enhanced with per-path and per-condition timeout support

  • Added per_path_timeout and per_condition_timeout parameters
  • Support for deterministic inputs via inputs_path parameter
  • Improved timeout handling for long-running symbolic execution paths

• Sidecar Orchestrator: Extended to support unannotated code detection

  • Added unannotated_functions parameter to run_sidecar_validation()
  • Integration with CrossHair summary generation
  • Enhanced result dictionary with unannotated function information

• Repro Command: Extended with sidecar validation integration

  • Automatic unannotated code detection when --sidecar flag is used
  • Automatic application of safe defaults for repro mode
  • Sidecar results displayed in repro output

• TimeoutConfig Model: Added safe defaults factory method

  • New safe_defaults_for_repro() class method
  • Conservative timeout values for repro mode
  • Per-path and per-condition timeout defaults

• CrossHairConfig Model: Added configuration flags

  • use_deterministic_inputs flag for deterministic input support
  • safe_defaults flag for safe default application

Fixed (0.24.0)

• Flask Framework Detection: Fixed incorrect detection of Flask as Django
  • Added Flask pattern detection before Django urls.py check
  • Framework detection accuracy improved from 85.7% (6/7) to 100% (7/7)
  • Flask correctly detected as PURE_PYTHON

Documentation (0.24.0)

• New Guides: Added comprehensive documentation for sidecar validation

  • docs/guides/sidecar-validation.md - Complete user guide with examples
  • docs/reference/commands.md - Updated with validate sidecar commands
  • Verification and test results documentation

• Sidecar Validation Guide: Updated with new features

  • Auto-skip behavior documentation with examples
  • Troubleshooting section for Specmatic auto-skip
  • Repro integration section with usage examples
  • Safe defaults documentation

• Command Reference: Updated with repro sidecar options

  • Added --sidecar and --sidecar-bundle options to repro command
  • Updated examples with sidecar usage
  • Added sidecar to tool requirements list

v0.23.1

Fixed (0.23.1)

• Contract Extraction Performance: Fixed critical performance bottleneck causing extremely slow contract extraction

  • Nested Parallelism Removal: Eliminated GIL contention from nested ThreadPoolExecutor instances
    • Removed file-level parallelism within features (features already processed in parallel at command level)
    • Files within each feature now processed sequentially to avoid thread contention
    • Performance improvement: contract extraction for large codebases (300+ features) now completes in reasonable time instead of hours
    • Resolves issue where CPU usage was low despite long processing times due to GIL contention
  • Cache Invalidation Logic: Fixed cache update logic to properly detect and handle file changes
    • Changed double-check pattern to compare file hashes before updating cache
    • Cache now correctly updates when file content changes, not just on cache misses
    • Ensures AST cache reflects current file state after modifications
  • Test Robustness: Enhanced cache invalidation test to handle Path object differences
    • Test now handles both test_file and resolved_file as cache keys
    • Path objects are compared by value, ensuring correct cache lookups
    • Added assertions to verify cache keys exist before accessing

• Import Command Bug Fixes: Fixed critical bugs in enrichment and contract extraction workflow

  • Unhashable Type Error: Fixed TypeError: unhashable type: 'Feature' when applying enrichment reports
    • Changed dict[Feature, list[Path]] to dict[str, list[Path]] using feature keys instead of Feature objects
    • Added feature_objects: dict[str, Feature] mapping to maintain Feature object references
    • Prevents runtime errors during contract extraction when enrichment adds new features
  • Enrichment Performance Regression: Fixed severe performance issue where enrichment forced full contract regeneration
    • Removed or enrichment condition from _check_incremental_changes that forced full regeneration
    • Enrichment now only triggers contract extraction for new features (without contracts)
    • Existing contracts are not regenerated when only metadata changes (confidence adjustments, business context)
    • Performance improvement: enrichment with unchanged files now completes in seconds instead of 80+ minutes for large bundles
  • Contract Extraction Order: Fixed contract extraction to run after enrichment application
    • Ensures new features from enrichment reports are included in contract extraction
    • New features without contracts now correctly get contracts extracted

Added (0.23.1)

• Contract Extraction Profiling Tool: Added diagnostic tool for performance analysis

  • New tools/profile_contract_extraction.py script for profiling contract extraction bottlenecks
  • Helps identify performance issues in contract extraction process
  • Provides detailed timing and profiling information for individual features

• Comprehensive Test Coverage: Added extensive test suite for import and enrichment bugs

  • Integration Tests: New test_import_enrichment_contracts.py with 5 test cases (552 lines)
    • Tests enrichment not forcing full contract regeneration
    • Tests new features from enrichment getting contracts extracted
    • Tests incremental contract extraction with enrichment
    • Tests feature objects not used as dictionary keys
    • Tests performance regression prevention
  • Unit Tests: New test_import_contract_extraction.py with 5 test cases (262 lines)
    • Tests Feature objects not being hashable (regression test)
    • Tests contract extraction using feature keys, not objects
    • Tests incremental contract regeneration logic
    • Tests enrichment not forcing contract regeneration
    • Tests new features from enrichment getting contracts
  • Updated Existing Tests: Enhanced test_import_command.py with enrichment regression test

v0.23.0

Added (0.23.0)

• Import Command Performance Optimizations: Major performance improvements for large codebases
  • Pre-computed Caches: AST parsing and file hashes are pre-computed once before parallel processing (5-15x faster)
  • Function Mapping Cache: Function names are extracted once per file and cached for reuse
  • Optimized for Large Codebases: Handles 3000+ features efficiently (6-15 minutes vs 90+ minutes previously)
  • Progress Reporting: Real-time progress bars for feature analysis, source linking, and contract extraction
  • Early Save Checkpoint: Features are saved immediately after initial analysis to prevent data loss on interruption
  • Feature Validation: Automatic validation of existing features when resuming imports
    • Detects orphaned features (all source files missing)
    • Identifies invalid features (some files missing or structure issues)
    • Reports validation results with actionable tips
  • Re-validation Flag: --revalidate-features flag to force re-analysis even if files haven't changed
    • Useful when analysis logic improves or confidence threshold changes
    • Forces full codebase analysis regardless of incremental change detection

Changed (0.23.0)

• Import Command Performance: Source file linking is now 5-15x faster for large codebases
  • Pre-computes all AST parsing before parallel processing
  • Caches file hashes to avoid repeated computation
  • Optimized matching logic with pre-computed feature title words
• Import Command Progress: Enhanced progress reporting with detailed status messages
  • Shows feature count, themes, and stories during analysis
  • Real-time progress bars for source file linking
  • Clear checkpoint messages when features are saved
  • Enhanced Analysis Setup: Added spinner progress for file discovery (repo.rglob("*.py")), filtering, and hash collection phases
    • Eliminates 30-60 second silent wait periods during file discovery
    • Shows real-time status: "Preparing enhanced analysis..." → "Discovering Python files..." → "Filtering X files..." → "Ready to analyze X files"
  • Contract Loading: Added progress bar for parallel YAML contract loading
    • Shows "Loading X existing contract(s)..." with completion count
    • Provides visibility during potentially slow contract file I/O operations
  • Enrichment Context Operations: Added spinner progress for hash comparison, context building, and file writing
    • Shows progress during hash comparison (reading existing file, building temp context)
    • Shows progress during context building (iterating through features and contracts)
    • Shows progress during markdown conversion and file writing
  • Incremental Change Detection: Improved progress feedback with completion status message
  • Changed File Collection: Added status message during file path collection

Documentation (0.23.0)

• Import Features Guide: New comprehensive guide docs/guides/import-features.md
  • Progress reporting details
  • Feature validation explanation
  • Early save checkpoint benefits
  • Performance optimization details
  • Re-validation flag usage
  • Best practices for large codebases
  • Troubleshooting tips
• Command Reference: Updated docs/reference/commands.md with new --revalidate-features flag
• Quick Examples: Updated docs/examples/quick-examples.md with new import features
• README: Updated timing information and checkpoint details

Fixed (0.23.0)

• Linting Errors: Fixed unused progress_columns variable warnings in enrichment context functions
  • Prefixed unused variables with underscore (_progress_columns) to indicate intentional non-usage
  • All linting checks now pass without errors

v0.22.1 - Terminal Output Auto-Detection

Release v0.22.1

Terminal Output Auto-Detection

This release introduces automatic terminal capability detection and adaptive output formatting for optimal user experience across different terminal environments.

Key Features

• Automatic Terminal Detection: Detects terminal capabilities (colors, animations, progress bars) and adapts output accordingly
• Three Terminal Modes:
  • GRAPHICAL: Full Rich output with animations and colors (interactive terminals)
  • BASIC: Plain text progress updates (embedded terminals, CI/CD)
  • MINIMAL: Minimal output (test mode)
• Zero Configuration: Works out of the box - no manual setup required
• CI/CD Optimized: Automatically uses plain text output in CI/CD for better log readability
• Standard Compliance: Respects NO_COLOR standard for color disabling

Bridge Probe Priority Fix

• Layout-specific adapters (SpecKit, OpenSpec) are now tried before generic adapters (GitHub)
• Prevents false positives when repositories have both GitHub remotes and specific tool layouts

Documentation

• Comprehensive terminal output troubleshooting guide
• Testing guide for terminal output modes
• Updated UX features, IDE integration, and use cases documentation

Technical Details

• New TerminalCapabilities dataclass and detection functions
• get_configured_console() for cached, configured Rich Console instances
• get_progress_config() for adaptive Progress column configurations
• All CLI commands updated to use adaptive terminal output

See CHANGELOG.md for complete details.

v0.22.0

Breaking Changes (0.22.0)

• Bridge Command Removal: Removed specfact bridge command group entirely

  • Constitution Commands Moved: specfact bridge constitution * commands moved to specfact sdd constitution *
  • Migration Required: Update all scripts and workflows:
    • specfact bridge constitution bootstrap → specfact sdd constitution bootstrap
    • specfact bridge constitution enrich → specfact sdd constitution enrich
    • specfact bridge constitution validate → specfact sdd constitution validate
  • Rationale: Bridge adapters are internal connectors, not user-facing commands. Constitution management belongs under SDD (Spec-Driven Development) commands.

• SpecKitSync Class Removal: Removed SpecKitSync class and speckit_sync.py module

  • Replacement: Use SpecKitAdapter via AdapterRegistry for all Spec-Kit operations
  • Breaking: Code that directly imports or instantiates SpecKitSync will fail
  • Migration: Use AdapterRegistry.get_adapter("speckit") to get SpecKitAdapter instance
  • Rationale: Eliminates deprecated code and enforces universal abstraction layer pattern

Added (0.22.0)

• OpenSpec Bridge Adapter (Phase 1 - Read-Only Sync): Plugin-based OpenSpec integration for importing specifications and change tracking

  • OpenSpec Adapter: OpenSpecAdapter implements BridgeAdapter interface for read-only sync from OpenSpec to SpecFact
  • OpenSpec Parser: OpenSpecParser for parsing OpenSpec markdown artifacts (project.md, specs/, changes/)
  • Cross-Repository Support: external_base_path configuration for OpenSpec in different repositories
  • Change Tracking Import: Loads change proposals and feature deltas from openspec/changes/ directory
  • Source Tracking: Stores OpenSpec paths and metadata in source_tracking.source_metadata field
  • Alignment Report: generate_alignment_report() method to compare SpecFact features vs OpenSpec specs
  • CLI Integration: specfact sync bridge --adapter openspec --mode read-only command with --external-base-path option
  • Adapter Registry: OpenSpec adapter registered in AdapterRegistry for plugin-based architecture
  • Bridge Configuration: BridgeConfig.preset_openspec() method with OpenSpec artifact mappings
  • Universal Abstraction Layer: Refactored BridgeProbe and BridgeSync to use AdapterRegistry (no hard-coded adapter checks)
  • BridgeAdapter Interface: Extended with get_capabilities() method for adapter capability detection

• SpecKitAdapter: New SpecKitAdapter class implementing BridgeAdapter interface

  • Bidirectional Sync: Full bidirectional sync support via adapter registry
  • Public Helper Methods: discover_features(), detect_changes(), detect_conflicts(), export_bundle()
  • Adapter Registry Integration: Registered in AdapterRegistry for plugin-based architecture
  • Contract Decorators: All methods have @beartype, @require, and @ensure decorators

• Spec-Kit .specify/specs/ Detection: Added support for canonical Spec-Kit layout

  • Canonical Layout Support: Added BridgeConfig.preset_speckit_specify() for .specify/specs/ structure (recommended by Spec-Kit)
  • Priority Detection: Detection now prioritizes .specify/specs/ > docs/specs/ > specs/ (root)
  • Scanner Updates: SpecKitScanner now checks .specify/specs/ first before falling back to root-level specs/
  • Backward Compatibility: Maintains support for root-level specs/ and docs/specs/ layouts
  • Rationale: According to Spec-Kit documentation, .specify/specs/ is the canonical location; root-level specs/ may be inconsistent

Changed (0.22.0)

• Bridge Probe Refactoring: Removed hard-coded Spec-Kit detection, now uses AdapterRegistry for universal adapter support

• Bridge Sync Refactoring: Removed hard-coded adapter checks, now uses AdapterRegistry.get_adapter() for all adapters

• Source Tracking Model: Extended SourceTracking with tool and source_metadata fields for tool-specific metadata storage

• Bridge Configuration: Added external_base_path field to BridgeConfig for cross-repository integrations

• Adapter Type Enum: Added AdapterType.OPENSPEC enum value

• Sync Command Refactoring: Refactored specfact sync bridge to use adapter registry pattern

  • Removed Hard-Coded Checks: All if adapter_type == AdapterType.SPECKIT: checks removed
  • Adapter-Agnostic: Sync command now works with any registered adapter via AdapterRegistry
  • Capability-Based: Sync mode detection now uses adapter.get_capabilities().supported_sync_modes
  • Universal Pattern: All adapters accessed via AdapterRegistry.get_adapter() - no hard-coded checks

• Import Command Refactoring: Refactored specfact import from-bridge to use adapter registry

  • Removed Hard-Coded Logic: All Spec-Kit-specific instantiation removed
  • Adapter Registry: Uses AdapterRegistry for all adapter operations

• Bridge Probe Refactoring: Removed Spec-Kit-specific validation suggestions

  • Generic Capabilities: Uses adapter capabilities for validation suggestions

• Bridge Sync Refactoring: Removed hard-coded OpenSpec check in alignment report

  • Adapter-Agnostic: Alignment report generation is now adapter-agnostic

• Command References: Updated all help text and error messages

  • Constitution Commands: All references updated from specfact bridge constitution to specfact sdd constitution
  • Probe Command: Updated references from specfact bridge probe to specfact sync bridge probe

• Schema Version Management: Improved schema version handling for new bundles

  • Latest Schema Reference: Added get_latest_schema_version() function for semantic clarity when creating new bundles
  • Schema Constant: Added LATEST_SCHEMA_VERSION alias for CURRENT_SCHEMA_VERSION (currently "1.1")
  • Bundle Creation: Updated import_cmd.py and sync.py to use get_latest_schema_version() instead of hardcoded "1.0"
  • Future-Proofing: New bundles now automatically use the latest schema version without code changes

Removed (0.22.0)

• SpecKitSync Class: Deleted src/specfact_cli/sync/speckit_sync.py file

  • SyncResult Dataclass: Removed speckit_sync.SyncResult (note: BridgeSync.SyncResult remains)
  • All References: Removed all imports and usages of SpecKitSync throughout codebase

• Bridge Command: Deleted src/specfact_cli/commands/bridge.py file

  • Command Registration: Removed bridge command registration from cli.py

• Deprecated Commands: Removed specfact implement and specfact generate tasks commands

  • Rationale: SpecFact CLI focuses on analysis and enforcement, not code generation. Use Spec-Kit, OpenSpec, or other SDD tools for plan → feature → task workflows
  • Migration: Use specfact generate fix-prompt and specfact generate test-prompt for AI IDE integration instead

Documentation (0.22.0)

• README Enhancements: Comprehensive updates to main README and sub-level README files

  • Added "How SpecFact Compares" Section: Prominent comparison table (similar to OpenSpec's approach) showing SpecFact vs. Spec-Kit, OpenSpec, and Traditional Testing
  • Enhanced Value Proposition: Added "Why SpecFact?" section explaining brownfield-first analysis workflow and key outcomes
  • Improved Structure: Reorganized README for better clarity and intuitive flow for new users
  • Updated Version References: Changed all "Version 0.21.1" references to "Version 0.22.0" with current release notes
  • Copyright Updates: Updated copyright years from "2025" to "2025-2026" in all README files
  • Link Verification: Fixed broken internal links and verified all documentation links are valid

• New Tutorial: Created comprehensive beginner-friendly tutorial docs/getting-started/tutorial-openspec-speckit.md

  • Complete Step-by-Step Guide: 18 detailed steps covering both OpenSpec and Spec-Kit integration paths
  • Prerequisites Section: Clear installation and setup instructions
  • Path A (OpenSpec): 9 steps covering change proposal creation, GitHub Issues export, progress tracking, and sync
  • Path B (Spec-Kit): 9 steps covering import, bidirectional sync, contract enforcement, and drift detection
  • Key Concepts: Bridge adapters, sync modes, and troubleshooting sections
  • Verified Commands: All commands tested and verified with accurate syntax and expected outputs
  • Command Syntax Fixes: Corrected command usage (bundle as positional vs option, --repo usage, etc.)

• Comparison Guides Updates: Enhanced comparison documentation

  • speckit-comparison.md: Added adapter registry pattern notes and FAQ section about working with other specification tools
  • competitive-analysis.md: Added "Building on Specification Tools" section with OpenSpec, Spec-Kit, and GitHub Issues adapters
  • openspec-journey.md: Updated status from "PLANNED" to "✅ IMPLEMENTED" for OpenSpec bridge adapter (v0.22.0+)

• Command Reference Updates: Updated docs/reference/commands.md

  • Removed Commands: Marked implement and generate tasks as "REMOVED in v0.22.0" with migration guidance
  • Constitution Commands: Updated all references from specfact bridge constitution to specfact sdd constitution
  • Bridge Adapters: Added clear examples for sync bridge --adapter openspec and adapter registry pattern

• Migration Guides: Updated migration documentation

  • migration-0.16-to-0.19.md: Updated to reflect implement tasks and generate tasks commands removal
  • Troubleshooting Guide: Updated all specfact constitution commands to specfact sdd constitution

• Architecture Documentation: Updated docs/reference/architecture.md

  • **Ver...

v0.21.1 - Change Tracking Data Model & Code Change Tracking

Change Tracking Data Model (v1.1 Schema)

Tool-agnostic change tracking models for delta spec tracking (ADDED/MODIFIED/REMOVED)

• Change Models: ChangeType, FeatureDelta, ChangeProposal, ChangeTracking, ChangeArchive models
• Bundle Extensions: BundleManifest and ProjectBundle extended with optional change_tracking and change_archive fields (schema v1.1)
• Helper Methods: ProjectBundle.get_active_changes() and get_feature_deltas() for querying change proposals
• Schema Versioning: Support for schema v1.1 with backward compatibility for v1.0 bundles
• BridgeAdapter Interface: Extended BridgeAdapter interface with load_change_tracking(), save_change_tracking(), load_change_proposal(), save_change_proposal() methods
• Cross-Repository Support: Adapter methods support external_base_path for cross-repository configurations
• Tool-Agnostic Design: All tool-specific metadata stored in source_tracking, ensuring models work with any tool (OpenSpec, Linear, Jira, etc.)

Code Change Tracking and Progress Comments

Detect code changes and add progress comments to GitHub issues

• Code Change Detection: detect_code_changes() utility to detect git commits related to change proposals
• Progress Comment Generation: format_progress_comment() to format implementation progress details (commits, files changed, milestones)
• Progress Comment Sanitization: Sanitization support for public repositories - removes sensitive information from commit messages, file paths, author emails, and timestamps
• GitHubAdapter Extension: _add_progress_comment() method and code_change_progress artifact key support with sanitization flag
• BridgeSync Integration: Code change tracking integrated into export_change_proposals_to_devops() with duplicate detection and automatic sanitization based on repository setup
• CLI Flags: --track-code-changes and --add-progress-comment flags for specfact sync bridge command
• Source Tracking Metadata: Progress comments tracked in source_metadata.progress_comments with comment hash deduplication
• Cross-Repository Support: Code change detection works across repositories with proper issue targeting and sanitization

Backward Compatibility

All change tracking fields are optional - existing v1.0 bundles continue to work without modification.

Foundation for OpenSpec

This change provides the data model foundation for OpenSpec bridge adapter implementation (Phase 2).

See CHANGELOG.md for full details.

v0.21.0 - DevOps Backlog Tracking and OpenSpec Integration

[0.21.0] - 2025-12-29

Added

• DevOps Backlog Tracking Integration: Export OpenSpec change proposals to DevOps backlog tools (GitHub Issues, ADO, Linear, Jira)
  • GitHub Adapter: GitHubAdapter implements BridgeAdapter interface for creating/updating GitHub Issues from OpenSpec change proposals
  • Export-Only Sync Mode: specfact sync bridge --adapter github --mode export-only command for syncing change proposals to DevOps tools
  • Status Synchronization: Automatic issue status updates when change proposals are applied, deprecated, or discarded
  • Source Tracking: Issue IDs automatically saved back to OpenSpec proposal files in "## Source Tracking" section
  • GitHub CLI Integration: --use-gh-cli option to automatically derive GitHub token from gh auth token (useful in enterprise environments)
  • Content Sanitization: ContentSanitizer utility to remove competitive analysis, internal strategy, and implementation details from proposals for public issues
  • Conditional Sanitization: Auto-detection of sanitization need based on repository setup (different repos → sanitize, same repo → no sanitization)
  • Sanitization CLI Options: --sanitize/--no-sanitize, --target-repo, --interactive options for content sanitization control
  • Slash Command: /specfact.sync-backlog interactive command for AI-assisted backlog synchronization with content sanitization
  • Cross-Repository Support: Full support for managing OpenSpec proposals in separate repository from codebase
  • Architecture: Extensible bridge adapter pattern supports future tools (ADO, Linear, Jira) via same interface
  • Proposal Filtering: Per-proposal filtering based on sanitization status (public repos only sync "applied" proposals, internal repos sync all active proposals)

Changed

• Bridge Configuration: Extended BridgeConfig with preset_github() for DevOps backlog tracking
• Adapter Registry: Added GitHubAdapter to adapter registry for plugin-based DevOps tool integration
• Bridge Sync: Extended BridgeSync with export_change_proposals_to_devops() method for export-only sync mode
• Proposal Filtering Logic: Enhanced filtering to check each proposal individually based on sanitization status
  • Per-proposal filtering ensures proposals are only synced when appropriate for target repository type
  • Clear warning messages when proposals are filtered out (shows count and reason)
  • Filtering happens before processing, improving performance and clarity
• Documentation Updates: Updated command reference and slash command prompt to reflect new filtering behavior
  • Added "Proposal Filtering (export-only mode)" section to docs/reference/commands.md
  • Updated resources/prompts/specfact.sync-backlog.md with filtering behavior and warning examples
  • Clarified that public repos only sync archived/completed proposals

Fixed

• Proposal Filtering for Public Repositories: Fixed issue where proposals with "proposed" status were being synced to public repositories

  • Public repos (--sanitize): Now only syncs proposals with status "applied" (archived/completed), regardless of existing source tracking entries
  • Internal repos (--no-sanitize): Syncs all active proposals (proposed, in-progress, applied, deprecated, discarded)
  • Prevents premature exposure of work-in-progress proposals to public repositories
  • Filtering warnings displayed when proposals are filtered out based on status

• Source Tracking Metadata Updates: Fixed issue where sanitized flag wasn't updated when syncing to existing issues

  • Source tracking metadata (including sanitized flag) now always updated during sync operations
  • Metadata updates tracked as sync operations even when issue status hasn't changed
  • Ensures accurate tracking of which issues were sanitized vs exported directly

• Duplicate Source Tracking Blocks: Fixed regex pattern in _save_openspec_change_proposal() to prevent duplicate "Source Tracking" sections

  • Updated regex to correctly match and replace entire "Source Tracking" section including --- separator
  • Prevents duplicate blocks when updating source tracking metadata

• Variable Redeclaration Errors: Fixed reportRedeclaration errors in bridge_sync.py

  • Renamed source_tracking_list to archive_source_tracking_list in archived changes processing block
  • Renamed source_tracking_final to archive_source_tracking_final to avoid name conflicts

• GitHub Adapter Source Tracking Handling: Fixed 'list' object has no attribute 'get' error in _update_issue_status()

  • Normalized source_tracking to list format before accessing dictionary methods
  • Handles both single dict and list of dicts formats for backward compatibility

Improved

• CLI Validation: Added comprehensive validation of sync bridge command with hatch run
  • Verified filtering works correctly for both public and internal repositories
  • Confirmed warning messages display appropriately when proposals are filtered
  • Validated that only "applied" proposals sync to public repos while all active proposals sync to internal repos

---

Full Changelog: v0.20.6...v0.21.0

v0.20.6 - PlanBundle Schema Hotpatch

Fixed (0.20.6)

• PlanBundle Schema Hotpatch: Automatic fix for incorrect schema definitions in OpenAPI contracts
  • Root cause: Contract extraction/generation incorrectly inferred Product.themes as array of objects instead of array of strings
  • Hotpatch implementation: Added automatic schema correction in _resolve_schema_refs() function
  • Detection: Hotpatch detects and fixes incorrect PlanBundle schemas when resolve_schema_refs_in_contracts() is called
  • Schema change detection: Enhanced resolve_schema_refs_in_contracts() to detect schema modifications (not just additions) and save fixed contracts
  • Type safety: Fixed unbound variable error (original_schemas_str) with proper initialization and guards
  • Transparency: Fix is automatic and transparent - no user action required when running sidecar workflow

Full Changelog

See CHANGELOG.md for complete release history.

v0.20.5 - Sidecar Template Code Quality Improvements

Fixed

Sidecar Template Code Quality

Fixed formatting and linting issues in sidecar template files:

• adapters.py: Removed whitespace from blank line, removed unused imports (HttpRequest, QueryDict), fixed exception chaining with raise ... from None
• crosshair_django_wrapper.py: Combined nested if statements to reduce complexity (SIM102)
• populate_contracts.py: Replaced for loop with any() expression for better Pythonic code (SIM110)
• django_form_extractor.py: Combined nested if statements, fixed indentation issues throughout the file
• django_url_extractor.py: Combined nested if statements, improved code formatting
• All files now pass hatch run format checks with no errors
• Improves code maintainability and follows Python best practices