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

v0.20.1

Fixed (0.20.1)

• External Repository Support: Fixed critical issue where repro command only worked on SpecFact CLI's own codebase
  • Added automatic environment manager detection (hatch, poetry, uv, pip)
  • Made all validation tools optional with clear messaging when unavailable
  • Added dynamic source directory detection (src/, lib/, or package name from pyproject.toml)
  • Commands now work on external repositories without requiring SpecFact CLI adoption
  • Enables OSS validation plan execution as designed
• generate contracts-apply Command: Fixed hardcoded paths and environment assumptions
  • Uses dynamic source directory detection instead of hardcoded src/ paths
  • Uses environment detection for Python/pytest invocations
  • Dynamic test file detection (supports multiple test directory structures)
  • Works on external repositories with different project structures
• generate test-prompt Command: Fixed hardcoded source directory detection
  • Uses dynamic source directory detection instead of hardcoded src/
  • Dynamic test file detection for better external repository support

Added (0.20.1)

• Environment Manager Detection: New env_manager utility module for detecting and working with different Python environment managers
• Test Directory Detection: New utilities for detecting test directories and finding test files dynamically
• Comprehensive Tests: Added 31 new tests for environment detection, test directory detection, and external repository support
• repro setup Command: New subcommand to automatically configure CrossHair for contract exploration
  • Automatically generates [tool.crosshair] configuration in pyproject.toml
  • Detects source directories and environment managers
  • Provides installation guidance for crosshair-tool
  • Optional --install-crosshair flag to attempt automatic installation
• init Command Environment Warning: Added warning when no compatible environment manager is detected
  • Non-blocking warning that provides guidance on supported tools
  • Helps users understand best practices for SpecFact CLI integration
  • Lists supported environment managers (hatch, poetry, uv, pip) with detection criteria

Improved (0.20.1)

• Documentation: Updated repro command documentation to clarify external repository support and environment requirements
  • Added repro setup command documentation
  • Updated all example flows to include CrossHair setup step
  • Added "Supported Project Management Tools" section to installation guide
• Error Messages: Improved messaging when tools are unavailable, providing clear guidance on installation
• Code Quality: All linting/formatting tools in generate contracts-apply now use environment detection
• Test Coverage: Added comprehensive test suite for repro setup command (15 tests) and init command environment warning (5 tests)
• init --install-deps Command: Now uses environment manager detection for package installation
  • Automatically detects and uses hatch, poetry, uv, or pip based on project configuration
  • Provides environment-specific installation commands and error guidance
  • Shows detected environment manager and command being used
  • Adds timeout handling and improved error messages
  • Tracks environment manager in telemetry

Notes (0.20.1)

This patch release fixes the critical design issue identified during OSS validation planning. The repro command can now be used to validate external repositories (Requests, Flask, FastAPI, etc.) without requiring those projects to adopt SpecFact CLI.

Reference: CRITICAL_DESIGN_ISSUE_EXTERNAL_REPO_SUPPORT.md

v0.20.0 LTS - Long-Term Stable Release

[0.20.0] - 2025-12-17

🎉 Long-Term Stable (LTS) Release

v0.20.0 is the Long-Term Stable (LTS) release for the 0.x series. This release marks the stabilization of SpecFact CLI's core analysis and enforcement capabilities, positioning the tool for public promotion and early adopter usage.

0.x Positioning: "Analyze your brownfield code, find gaps, enforce contracts"
1.x Positioning: "All of the above, PLUS AI-assisted code generation with validation"

Added (0.20.0)

• LTS Designation: v0.20.0 marked as Long-Term Stable release
• Comprehensive Documentation: Complete GitHub Pages integration with navigation and styling
• Migration Guide: Updated migration guide from v0.16.x to v0.20.0 LTS

Improved (0.20.0)

• Documentation Site: Enhanced Jekyll-based documentation with left-side navigation
• Code Block Styling: Fixed syntax highlighting for better readability
• User Experience: Improved documentation navigation and accessibility

Breaking Changes (0.20.0)

None - v0.20.0 is fully backward compatible with v0.19.0.

Deprecated (0.20.0)

• implement tasks command remains deprecated (removed in v1.0)
• Use generate fix-prompt and generate test-prompt bridge commands instead

Docs (0.20.0)

• GitHub Pages: Complete Jekyll integration with proper rendering
• Navigation: Left-side navigation sidebar for better UX
• Styling: Fixed CSS issues and improved code block readability
• Migration Guide: Updated guide for v0.16.x → v0.20.0 LTS upgrade path

Notes (0.20.0)

• LTS Support: v0.20.0 will receive bug fixes and security updates until v1.0 GA
• Next Steps: v1.0 development begins after Phase B validation (Ultimate Vision track)
• Stability: All core features (analysis, enforcement, gap detection) are stable and production-ready

---