Merge dev into main - v0.26.8 release

CHANGELOG.md

@@ -9,6 +9,89 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.26.8] - 2026-01-27
+
+### 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
+
+---
+
 ## [0.26.7] - 2026-01-27
 
 ### Fixed (0.26.7)

README.md

@@ -173,21 +173,26 @@ specfact validate sidecar run my-project /path/to/repo
 - **Agile/scrum ready** - DoR checklists, story points, dependencies
 - **Backlog standardization** 🆕 - Template-driven refinement with persona/framework filtering
 - **Sprint/iteration filtering** 🆕 - Filter by sprint, release, iteration for agile workflows
+- **Interactive field mapping** 🆕 - Discover and map Azure DevOps fields with arrow-key navigation
+- **Azure DevOps integration** 🆕 - Full support for ADO work items with automatic token resolution
 
 👉 **[Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md)** - Team collaboration guide  
-👉 **[Backlog Refinement](docs/guides/backlog-refinement.md)** 🆕 - Standardize backlog items with templates
+👉 **[Backlog Refinement](docs/guides/backlog-refinement.md)** 🆕 - Standardize backlog items with templates  
+👉 **[Custom Field Mapping](docs/guides/custom-field-mapping.md)** 🆕 - Map ADO fields interactively
 
 ### 🔌 Integrations
 
 - **VS Code, Cursor** - Catch bugs before you commit
 - **GitHub Actions** - Automated quality gates
 - **AI IDEs** - Generate prompts for fixing gaps
-- **DevOps tools** - Sync with GitHub Issues, Linear, Jira
+- **DevOps tools** - Sync with GitHub Issues, Azure DevOps, Linear, Jira
 - **Backlog Refinement** 🆕 - AI-assisted template-driven refinement for standardizing work items
+- **Azure DevOps field mapping** 🆕 - Interactive field discovery and mapping for custom ADO process templates
 - **Spec-Kit, OpenSpec, Specmatic** - Works with your existing tools
 
 👉 **[Integrations Overview](docs/guides/integrations-overview.md)** - All integration options  
-👉 **[Backlog Refinement Guide](docs/guides/backlog-refinement.md)** 🆕 **NEW** - Template-driven backlog standardization
+👉 **[Backlog Refinement Guide](docs/guides/backlog-refinement.md)** 🆕 **NEW** - Template-driven backlog standardization  
+👉 **[Custom Field Mapping](docs/guides/custom-field-mapping.md)** 🆕 **NEW** - Interactive ADO field mapping
 
 ---
 
@@ -252,8 +257,9 @@ specfact validate sidecar run my-project /path/to/repo
 - **[Spec-Kit Journey](docs/guides/speckit-journey.md)** - From Spec-Kit to SpecFact
 - **[OpenSpec Journey](docs/guides/openspec-journey.md)** - OpenSpec integration
 - **[Specmatic Integration](docs/guides/specmatic-integration.md)** - API contract testing
-- **[DevOps Adapter Integration](docs/guides/devops-adapter-integration.md)** - GitHub Issues, Linear, Jira
+- **[DevOps Adapter Integration](docs/guides/devops-adapter-integration.md)** - GitHub Issues, Azure DevOps, Linear, Jira
 - **[Backlog Refinement](docs/guides/backlog-refinement.md)** 🆕 **NEW** - AI-assisted template-driven backlog standardization
+- **[Custom Field Mapping](docs/guides/custom-field-mapping.md)** 🆕 **NEW** - Interactive Azure DevOps field mapping
 
 👉 **[Full Documentation Index](docs/README.md)** - Browse all documentation  
 👉 **[Online Documentation](https://docs.specfact.io/)** - Complete documentation site

docs/README.md

@@ -38,6 +38,7 @@ SpecFact isn't just a technical tool—it's designed for **real-world agile/scru
 - ✅ **Team collaboration** → Spec-Kit is single-user focused; SpecFact supports persona-based workflows for agile teams
 - ✅ **DevOps integration** 🆕 → **Bidirectional backlog sync** - Sync change proposals to GitHub Issues and Azure DevOps Work Items (and future: Linear, Jira) with automatic progress tracking
 - ✅ **Backlog refinement** 🆕 → **Template-driven standardization** - Transform arbitrary DevOps backlog input into structured, template-compliant work items with AI assistance, persona/framework filtering, and sprint/iteration support
+- ✅ **Interactive field mapping** 🆕 → **Azure DevOps field discovery** - Discover and map ADO fields interactively with arrow-key navigation, automatic default pre-population, and fuzzy matching
 - ✅ **Definition of Ready (DoR)** 🆕 → **Sprint readiness validation** - Check DoR rules before adding items to sprints, with repo-level configuration
 - ✅ **GitHub Actions integration** → Works seamlessly with your existing GitHub workflows
 
@@ -188,6 +189,7 @@ specfact enforce sdd --bundle my-project
 - [OpenSpec Journey](guides/openspec-journey.md) 🆕 - OpenSpec integration with SpecFact (DevOps export ✅, bridge adapter ✅)
 - [DevOps Adapter Integration](guides/devops-adapter-integration.md) 🆕 **NEW FEATURE** - Bidirectional GitHub Issues sync, automatic progress tracking, and agile DevOps workflow integration
 - [Backlog Refinement](guides/backlog-refinement.md) 🆕 **NEW FEATURE** - AI-assisted template-driven refinement for standardizing work items with persona/framework filtering, sprint/iteration support, and DoR validation
+- [Custom Field Mapping](guides/custom-field-mapping.md) 🆕 **NEW FEATURE** - Interactive Azure DevOps field discovery and mapping with arrow-key navigation
 - [Bridge Adapters](reference/commands.md#sync-bridge) - OpenSpec and DevOps integration
 
 #### Team Collaboration & Agile/Scrum

docs/adapters/azuredevops.md

@@ -90,13 +90,64 @@ external_base_path: ../openspec-repo  # Optional: cross-repo support
 
 **Note**: Organization, project, and API token are **not** stored in bridge config for security. They must be provided via CLI flags or environment variables.
 
+### Field Mapping
+
+The adapter supports flexible field mapping to handle different ADO process templates:
+
+- **Multiple Field Alternatives**: Supports multiple ADO field names mapping to the same canonical field (e.g., both `System.AcceptanceCriteria` and `Microsoft.VSTS.Common.AcceptanceCriteria` map to `acceptance_criteria`)
+- **Default Mappings**: Includes default mappings for common ADO fields (Scrum, Agile, SAFe, Kanban)
+- **Custom Mappings**: Supports per-project custom field mappings via `.specfact/templates/backlog/field_mappings/ado_custom.yaml`
+- **Interactive Mapping**: Use `specfact backlog map-fields` to interactively discover and map ADO fields for your project
+
+**Interactive Field Mapping Command**:
+
+```bash
+# Discover and map ADO fields interactively
+specfact backlog map-fields --ado-org myorg --ado-project myproject
+```
+
+This command:
+
+- Fetches available fields from your ADO project
+- Pre-populates default mappings
+- Uses arrow-key navigation for field selection
+- Saves mappings to `.specfact/templates/backlog/field_mappings/ado_custom.yaml`
+- Automatically used by all subsequent backlog operations
+
+See [Custom Field Mapping Guide](../guides/custom-field-mapping.md) for complete documentation.
+
+### Assignee Extraction and Display
+
+The adapter extracts assignee information from ADO work items:
+
+- **Extraction**: Assignees are extracted from `System.AssignedTo` field
+- **Display**: Assignees are always displayed in backlog refinement preview output
+- **Format**: Shows assignee names or "Unassigned" if no assignee
+- **Preservation**: Assignee information is preserved during refinement and sync operations
+
 ### Authentication
 
 The adapter supports multiple authentication methods (in order of precedence):
 
 1. **Explicit token**: `api_token` parameter or `--ado-token` CLI flag
 2. **Environment variable**: `AZURE_DEVOPS_TOKEN` (also accepts `ADO_TOKEN` or `AZURE_DEVOPS_PAT`)
-3. **Stored auth token**: `specfact auth azure-devops` (device code flow)
+3. **Stored auth token**: `specfact auth azure-devops` (device code flow or PAT token)
+
+**Token Resolution Priority**:
+
+When using ADO commands, tokens are resolved in this order:
+
+1. Explicit `--ado-token` parameter
+2. `AZURE_DEVOPS_TOKEN` environment variable
+3. Stored token via `specfact auth azure-devops`
+4. Expired stored token (shows warning with options to refresh)
+
+**Token Types**:
+
+- **OAuth Tokens**: Device code flow, expire after ~1 hour, automatically refreshed when possible
+- **PAT Tokens**: Personal Access Tokens, can last up to 1 year, recommended for automation
+
+See [Authentication Guide](../reference/authentication.md) for complete documentation.
 
 **Example:**
 
@@ -368,6 +419,7 @@ The adapter uses a three-level matching strategy to prevent duplicate work items
 3. **Org-only match**: For ADO, match by organization only when project names differ
 
 This handles cases where:
+
 - ADO URLs contain GUIDs instead of project names (e.g., `dominikusnold/69b5d0c2-2400-470d-b937-b5205503a679`)
 - Project names change but organization stays the same
 - Work items are synced across different projects in the same organization

docs/getting-started/first-steps.md

@@ -47,6 +47,11 @@ cd /path/to/your/project
 # Step 3: Initialize IDE integration (one-time)
 specfact init
 
+# This creates:
+# - .specfact/ directory structure
+# - .specfact/templates/backlog/field_mappings/ with default ADO field mapping templates
+# - IDE-specific command files for your AI assistant
+
 # Step 4: Use slash command in IDE chat
 /specfact.01-import legacy-api --repo .
 # Or let the AI assistant prompt you for bundle name
@@ -168,6 +173,7 @@ specfact plan init my-project --interactive
 - Creates `.specfact/` directory structure
 - Prompts you for project title and description
 - Creates modular project bundle at `.specfact/projects/my-project/`
+- Copies default ADO field mapping templates to `.specfact/templates/backlog/field_mappings/` for review and customization
 
 **Example output**: