v0.26.14

Fixed (0.26.14)

• ADO backlog refine error logging and user-facing error UX (fixes #162)
  • Debug log: On ADO PATCH failure (backlog refine body, status update, comment, create work item), debug log now includes response body snippet and patch paths via debug_log_operation(..., extra={"response_body": snippet, "patch_paths": [...]}) when --debug is set; snippet truncated (~1–2 KB) and redacted via LoggerSetup.redact_secrets
  • User-facing messages: Console shows ADO error message (e.g. "Cannot find field System.AcceptanceCriteria") and actionable hint ("Check custom field mapping; see ado_custom.yaml or documentation."); when ADO message contains a field reference, visible message quotes it (e.g. "Field 'System.AcceptanceCriteria' not found")
  • Helper: New _log_ado_patch_failure() in ado.py used at all PATCH failure sites for consistent logging and user messages; re-raised exception carries ADO context
  • Non-JSON/large body: Non-JSON or oversized response body handled safely (no crash, truncated safe string in log/user message)
  • Docs: debug-logging.md (ADO PATCH failure content, "Examining ADO API Errors"), troubleshooting.md ("Backlog refine or work item PATCH fails (400/422)"), adapters/azuredevops.md (error diagnostics link), README.md (debug note for ADO errors)
  • OS temp dir: Export/import default paths use system temp directory (tempfile.gettempdir()) in backlog refine and sync bridge (backlog_commands.py, bridge_sync.py); help strings describe "/..."

v0.26.13

Fixed (0.26.13)

• Debug log parity for specfact upgrade: When --debug is set, the "up to date" success path now writes to ~/.specfact/logs/specfact-debug.log (same as the "installed" path), with debug_log_operation and narrative "upgrade: success (up to date)" including version in extra

v0.26.11

Fixed (0.26.11)

• Backlog refine --import-from-tmp: Implemented import path so refined content from a temporary file is applied to backlog items
  • Parser: Added _parse_refined_export_markdown() to parse the same markdown format produced by --export-to-tmp (## Item blocks, ID, Body in markdown ... , Acceptance Criteria, optional Metrics)
  • Import flow: When --import-from-tmp (and optional --tmp-file) is used, the CLI reads the file, matches blocks to fetched items by ID, updates body_markdown, acceptance_criteria, and optionally title/metrics; without --write shows "Would update N item(s)", with --write calls adapter.update_backlog_item() for each and prints success summary
  • Removed: "Import functionality pending implementation" message and TODO
  • Tests: Unit tests for the parser (single item, acceptance criteria and metrics, header-only, blocks without ID)

v0.26.10

Added (0.26.10)

• OpenSpec OPSX migration documentation: Align docs and references with OPSX and migration guide
  • New: docs/openspec-opsx-migration.md — OPSX vs legacy, project context resolution (config.yaml primary, project.md fallback), contributor guidance
  • Canonical spec: openspec/specs/bridge-adapter/spec.md updated for project_context = config.yaml (OPSX) or project.md (legacy), detection and parse scenarios

Changed (0.26.10)

• OpenSpec OPSX documentation updates: Point contributors to OPSX and config.yaml while keeping legacy project.md references where relevant
  • CONTRIBUTING.md: OpenSpec workflow links to OPSX migration doc; OpenSpec Resources and Documentation Structure list openspec/config.yaml (OPSX) first, openspec/project.md (legacy)
  • docs/reference/architecture.md: Adapter detect snippet and comment updated to config.yaml (OPSX), project.md (legacy), specs/
  • docs/getting-started/tutorial-openspec-speckit.md: ls openspec/ comment updated for config.yaml (OPSX) and legacy project.md/AGENTS.md
  • .cursor/rules/automatic-openspec-workflow.mdc: Review step uses config.yaml (OPSX) or project.md (legacy)

Fixed (0.26.10)

• Version Bump: Corrected package version to 0.26.10 for PyPI publish (fixes incorrect version 0.26.9 publish issue)
  • Synced locations: pyproject.toml (project.version), setup.py (version=), src/__init__.py (version), src/specfact_cli/__init__.py (version)
  • When bumping version, update all four locations and add a CHANGELOG entry

v0.26.9

Fixed (0.26.9)

• GitHub Remote Detection: Extended URL pattern matching to support all valid GitHub URL formats

  • Added Support: Now detects ssh://git@github.com/owner/repo.git and git://github.com/owner/repo.git formats
  • Root Cause: Previous regex only matched https?:// and scp-style git@host:path URLs, causing regression for repos using ssh:// or git:// schemes
  • Solution: Extended regex pattern to include ssh:// and git:// schemes, with proper URL parsing for hostname validation
  • Impact: All valid GitHub URL formats are now properly detected, ensuring GitHub adapter is selected correctly

• Code Scanning Vulnerabilities: Mitigated all 13 code scanning findings

  • ReDoS Fix: Replaced regex-based section removal with line-by-line processing in github_mapper.py
  • URL Sanitization: Replaced substring matching with proper URL parsing using urllib.parse.urlparse() in multiple files
  • Workflow Permissions: Added explicit permissions: contents: read blocks to 7 GitHub Actions jobs
  • SSH Host Aliases: Added support for ssh.github.com SSH host alias detection
  • Test Fixes: Fixed async cleanup issues in test mode for progress display utilities

v0.26.8

Fixed (0.26.8)

• ADO Field Mapping - Acceptance Criteria: Fixed missing Acceptance Criteria field in backlog refinement output for Azure DevOps

  • Root Cause: Default field mappings used System.AcceptanceCriteria, but ADO API returns Microsoft.VSTS.Common.AcceptanceCriteria for many process templates
  • Solution: Added Microsoft.VSTS.Common.AcceptanceCriteria as alternative mapping for acceptance_criteria canonical field (backward compatible with System.AcceptanceCriteria)
  • Impact: Acceptance criteria now properly extracted and displayed in specfact backlog refine preview output
  • Templates Updated: All default ADO field mapping templates (ado_default.yaml, ado_scrum.yaml, ado_agile.yaml, ado_safe.yaml, ado_kanban.yaml) updated with alternative field mappings

• ADO Field Mapping - Assignee Display: Fixed missing assignee information in backlog refinement preview output

  • Root Cause: Assignee was extracted from ADO work items but not displayed in preview output
  • Solution: Added assignee display to preview output showing all assignees or "Unassigned" status
  • Impact: Users can now see assignee information in preview mode and filter by assignee

• ADO Assignee Extraction: Improved assignee extraction from ADO System.AssignedTo object

  • Enhanced Logic: Now extracts displayName, uniqueName, and mail fields from ADO assignee object
  • Deduplication: Filters out empty strings and duplicate assignee identifiers
  • Priority: Prioritizes displayName over uniqueName for better user experience
  • Impact: More reliable assignee extraction and filtering across different ADO configurations

Added (0.26.8)

• Interactive Field Mapping Command: Added specfact backlog map-fields command for guided ADO field mapping

  • Purpose: Helps users discover available ADO fields and map them to canonical field names interactively
  • Features:
    • Fetches live ADO fields from API (_apis/wit/fields endpoint)
    • Filters out system-only fields (e.g., System.Id, System.Rev)
    • Interactive selection of ADO fields for each canonical field (description, acceptance_criteria, story_points, business_value, priority, work_item_type)
    • Supports multiple field alternatives for same canonical field
    • Validates mappings before saving
    • Saves to .specfact/templates/backlog/field_mappings/ado_custom.yaml (per-project configuration)
  • Usage: specfact backlog map-fields --ado-org <org> --ado-project <project> --ado-token <token>
  • Benefits: Eliminates need for manual YAML creation and API exploration for custom ADO process templates

• Template Initialization in specfact init: Extended specfact init command to copy backlog field mapping templates

  • New Behavior: Automatically creates .specfact/templates/backlog/field_mappings/ directory during initialization
  • Templates Copied: Copies all default ADO field mapping templates (ado_default.yaml, ado_scrum.yaml, ado_agile.yaml, ado_safe.yaml, ado_kanban.yaml) from resources/templates/backlog/field_mappings/
  • Smart Copying: Skips existing files unless --force flag is used
  • User Benefit: Users can review and modify templates directly in their project after initialization

Changed (0.26.8)

• AdoFieldMapper Field Extraction: Enhanced _extract_field() method to support multiple field name alternatives

  • Behavior: Now checks all alternative ADO field names that map to the same canonical field
  • Backward Compatibility: Existing mappings continue to work (e.g., System.AcceptanceCriteria still supported)
  • Flexibility: Supports custom ADO process templates with different field naming conventions

• Backlog Filtering - Assignee: Improved assignee filtering logic in specfact backlog refine

  • Enhanced Matching: Now matches against displayName, uniqueName, and mail fields (case-insensitive)
  • Robustness: Handles empty assignee fields and unassigned items correctly
  • User Experience: More reliable filtering when using --assignee filter option

Documentation (0.26.8)

• Custom Field Mapping Guide: Extensively updated docs/guides/custom-field-mapping.md

  • New Section: "Discovering Available ADO Fields" with API endpoint instructions
  • New Section: "Using Interactive Mapping Command (Recommended)" with step-by-step instructions
  • Enhanced Section: "Manually Creating Field Mapping Files" with YAML schema reference and examples
  • Updated Section: "Default Field Mappings" to mention multiple field alternatives
  • New Section: "Troubleshooting" covering common issues (fields not extracted, mappings not applied, interactive mapping failures)

• Backlog Refinement Guide: Updated docs/guides/backlog-refinement.md

  • Preview Mode Section: Explicitly states that assignee information and acceptance criteria are now displayed
  • Filtering Section: Enhanced assignee filtering documentation

Testing (0.26.8)

• Unit Tests: Added comprehensive unit tests for new and modified functionality

  • AdoFieldMapper: Tests for multiple field alternatives, backward compatibility
  • Converter: Tests for assignee extraction (displayName, uniqueName, mail, combinations, unassigned)
  • Backlog Commands: Tests for assignee display, interactive mapping command, field fetching, system field filtering
  • Backlog Filtering: Tests for assignee filtering (case-insensitive matching, unassigned items)
  • Init Command: E2E tests for template copying, skipping existing files, force overwrite

• Test Coverage: Maintained ≥80% test coverage with all new features fully tested

Related Issues

• GitHub Issue #144: Fixed missing Acceptance Criteria and Assignee fields in ADO backlog refinement output

v0.26.7

Fixed (0.26.7)

• Adapter Token Validation Tests: Fixed test failures in ADO and GitHub adapter token validation tests

  • ADO Adapter: Added proper mocking of get_token() to prevent stored tokens from interfering with missing token tests
  • GitHub Adapter: Fixed token validation tests by properly mocking both get_token() and _get_github_token_from_gh_cli() functions
  • Test Reliability: Tests now correctly validate error handling when API tokens are missing

• Test Timeout Issues: Resolved multiple test timeout failures in E2E and integration tests

  • Commit History Analysis: Skip commit history analysis in TEST_MODE to prevent git operation timeouts
  • AST Parsing: Added filtering to exclude virtual environment directories (.venv, venv, site-packages) from test file discovery and AST parsing
  • Large File Handling: Added file size limit (1MB) check before AST parsing to prevent timeouts on large dependency files
  • Semgrep Integration Tests: Set TEST_MODE=true in Semgrep integration tests to skip actual Semgrep execution and prevent ThreadPoolExecutor deadlocks

• Test File Discovery: Improved test file discovery to exclude virtual environment directories

  • TestPatternExtractor: Enhanced _discover_test_files() to filter out .venv, venv, .env, env, __pycache__, and site-packages directories
  • Test File Validation: Added path validation to ensure test files are within repository boundaries

v0.26.6

Added (0.26.6)

• Startup Checks: Added automatic checks on CLI startup for template file validation and version updates
  • IDE Template Validation: Checks if template files in detected IDE (e.g., .cursor/commands/) differ from bundled templates and suggests running specfact init --force if outdated
  • Version Update Notifications: Checks PyPI for available CLI updates (minor/major/patch) and notifies users with appropriate warnings
  • Progress Indicators: Added progress spinners during startup checks to provide user feedback
  • Graceful Error Handling: Startup checks are wrapped with contextlib.suppress to prevent failures from crashing the CLI
  • Comprehensive Tests: Added 28 unit and integration tests for startup checks functionality

Fixed (0.26.6)

• Backlog Refinement Preview Mode: Fixed issue where interactive refinement prompts were shown in preview mode (without --write flag)
  • Preview Mode Behavior: In preview mode, items needing refinement are now skipped with informative messages instead of prompting for user input
  • User Experience: Preview mode now truly previews what would happen without requiring interactive input
  • Clear Guidance: Users are informed to use --write flag when they want to actually refine items

Changed (0.26.6)

• Startup Checks Integration: Integrated startup checks into CLI main entry point
  • Checks run automatically for all commands (except help/version/completion)
  • Checks are non-blocking and don't interfere with command execution
  • Progress indicators use rich.progress.Progress with transient display

v0.26.5

Added (0.26.5)

• Global Debug Mode: Added --debug global CLI flag for diagnostic output
  • Debug Print Helper: Added debug_print() function in runtime module that only outputs when --debug flag is set
  • Debug State Management: Added set_debug_mode() and is_debug_mode() functions for debug state control
  • Conditional Output: Debug messages (URLs, authentication status, API details) are now only shown when --debug is specified
  • Usage: specfact --debug <command> enables debug output for the entire command execution
• ADO Adapter Automatic Token Refresh: Implemented automatic OAuth token refresh using persistent token cache (like Azure CLI)
  • Persistent Token Cache: Enabled TokenCachePersistenceOptions in auth command with shared cache name "specfact-azure-devops"
  • Automatic Refresh: ADO adapter automatically refreshes expired OAuth tokens using cached refresh token
  • Seamless Operation: Tokens refresh automatically for ~90 days without user interaction
  • Fallback Handling: Provides helpful error messages when refresh fails (suggests PAT or re-authentication)
• Personal Access Token (PAT) Support: Added --pat option to auth azure-devops command
  • Long-Lived Tokens: PATs can have expiration up to 1 year (vs OAuth tokens which expire after ~1 hour)
  • Direct Storage: Users can store PATs directly via specfact auth azure-devops --pat your_pat_token
  • Basic Authentication: PATs are stored with token_type: "basic" and use base64-encoded Basic auth
  • Documentation: Comprehensive guidance on creating PATs in Azure DevOps UI with up to 1 year expiration

Fixed (0.26.5)

• ADO Adapter Authentication: Fixed missing API token in ADO API requests
  • Centralized Authentication: All ADO API requests now use _auth_headers() helper method consistently
  • WIQL POST Request: Fixed Authorization header construction in fetch_backlog_items WIQL query
  • Work Items Batch GET: Fixed Authorization header construction in work items batch fetch
  • Work Item Update PATCH: Fixed Authorization header construction in update_backlog_item
  • PAT Token Encoding: All ADO API requests now properly encode PAT tokens using base64 encoding (:token) for Basic authentication
  • Consistent Authentication: All ADO API calls now use centralized _auth_headers() method for consistent token handling (supports both Basic PAT and Bearer OAuth tokens)
• ADO Adapter URL Construction: Fixed URL construction to ensure org is always included before project
  • Project-Based Permissions: Org must always be part of _apis URL path before project for project-based permissions in larger organizations
  • URL Format: Ensures format {base_url}/{org}/{project}/_apis/... for all ADO API calls
  • On-Premise Support: Works correctly for both cloud (Azure DevOps Services) and on-premise (Azure DevOps Server) configurations
  • Error Messages: Improved error messages to separate org vs project requirements with helpful guidance
• ADO Adapter Error Messages: Enhanced error messages for authentication and token issues
  • Missing Token: Provides three options (env var, CLI option, stored token)
  • Expired Token: Suggests PAT for longer-lived tokens or re-authentication
  • Token Refresh: Shows helpful guidance when automatic refresh fails

Changed (0.26.5)

• ADO Adapter: Replaced manual Authorization header construction with _auth_headers() helper method in three locations:
  • fetch_backlog_items() - WIQL POST request
  • fetch_backlog_items() - Work items batch GET request
  • update_backlog_item() - Work item PATCH request
• Auth Command: Enhanced auth azure-devops command with PAT option and persistent token cache
  • Added --pat option for direct PAT storage
  • Enabled TokenCachePersistenceOptions for automatic token refresh
  • Updated documentation to explain PAT vs OAuth token options
• Debug Output: Converted debug console.print statements to use debug_print() helper
  • init.py: All debug messages now use debug_print() helper
  • ado.py: URL and authentication debug output uses debug_print()

v0.26.2

Fixed (0.26.2)

• ADO Adapter API Endpoints: Fixed Azure DevOps API endpoint issues
  • WIQL Query Endpoint: Added required api-version=7.1 parameter to WIQL query URL (POST to {base_url}/{org}/{project}/_apis/wit/wiql?api-version=7.1)
  • Work Items Batch GET Endpoint: Fixed to use organization-level endpoint instead of project-level ({base_url}/{org}/_apis/wit/workitems?ids={ids}&api-version=7.1)
  • Error Handling: Improved error messages with URL details, organization, project, and base URL information for better troubleshooting
  • API Version Requirement: All ADO API calls now include api-version=7.1 parameter to ensure correct API version targeting
• ADO Adapter On-Premise Support: Enhanced Azure DevOps Server (on-premise) support
  • URL Format Detection: Added _is_on_premise() method to detect cloud vs on-premise environments
  • Smart URL Construction: Added _build_ado_url() helper method that handles both cloud and on-premise URL formats
  • Collection Handling: Supports both URL formats:
    • Collection in base URL: https://server/tfs/collection/{project}/_apis/...
    • Collection provided separately: https://server/{collection}/{project}/_apis/...
  • Cloud Format: https://dev.azure.com/{org}/{project}/_apis/...
  • On-Premise Format: Automatically detects and handles /tfs/collection or /collection patterns in base URL

Added (0.26.2)

• ADO Adapter Documentation: Comprehensive documentation for Azure DevOps adapter configuration
  • Backlog Refinement Guide: Added "Azure DevOps Adapter Configuration" section with cloud vs on-premise differences, URL format examples, API endpoint requirements, and troubleshooting
  • Command Reference: Expanded ADO adapter configuration section with --ado-base-url parameter, cloud vs on-premise requirements, API endpoint documentation, and troubleshooting section
  • AI IDE Prompt: Updated specfact.backlog-refine.md with ADO adapter configuration examples (cloud and on-premise), API endpoint requirements, and troubleshooting tips
  • Configuration Examples: Added examples for both Azure DevOps Services (cloud) and Azure DevOps Server (on-premise) configurations

Changed (0.26.2)

• ADO Adapter URL Building: Centralized URL construction logic in _build_ado_url() method for consistent URL formatting across all ADO API calls
• ADO Adapter Error Messages: Enhanced error messages to include constructed URL, organization, project, base URL, and expected format for easier troubleshooting