perf: optimize startup performance with metadata tracking and update command

CHANGELOG.md

@@ -9,6 +9,27 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.26.7] - 2026-01-27
+
+### 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
+
+---
+
 ## [0.26.6] - 2026-01-23
 
 ### Added (0.26.6)
@@ -35,6 +56,7 @@ All notable changes to this project will be documented in this file.
   - Progress indicators use `rich.progress.Progress` with transient display
 
 ---
+
 ## [0.26.5] - 2026-01-21
 
 ### Added (0.26.5)

docs/guides/backlog-refinement.md

@@ -90,6 +90,13 @@ specfact backlog refine ado --iteration "Project\\Release 1\\Sprint 1"
 
 # Refine with defect template
 specfact backlog refine ado --template defect_v1 --search "WorkItemType = 'Bug'"
+
+# Use custom field mapping for custom ADO process templates
+specfact backlog refine ado \
+  --ado-org my-org \
+  --ado-project my-project \
+  --custom-field-mapping /path/to/ado_custom.yaml \
+  --state Active
 ```
 
 ---
@@ -391,6 +398,13 @@ specfact backlog refine github \
 # Refine ADO work items with sprint filter
 specfact backlog refine ado --sprint "Sprint 1" --state Active
 
+# Refine ADO work items with custom field mapping
+specfact backlog refine ado \
+  --ado-org my-org \
+  --ado-project my-project \
+  --custom-field-mapping .specfact/templates/backlog/field_mappings/ado_custom.yaml \
+  --state Active
+
 # Refine ADO work items with iteration path
 specfact backlog refine ado --iteration "Project\\Release 1\\Sprint 1"
 ```
@@ -549,6 +563,43 @@ specfact backlog refine github --search "is:open label:feature"
 
 ---
 
+## Field Mapping and Customization
+
+### Custom Field Mappings for Azure DevOps
+
+If your Azure DevOps organization uses custom process templates with non-standard field names, you can create custom field mappings to map your ADO fields to canonical field names.
+
+**Quick Example**:
+
+```bash
+# Use custom field mapping file
+specfact backlog refine ado \
+  --ado-org my-org \
+  --ado-project my-project \
+  --custom-field-mapping .specfact/templates/backlog/field_mappings/ado_custom.yaml \
+  --state Active
+```
+
+**Custom Mapping File Format**:
+
+Create a YAML file at `.specfact/templates/backlog/field_mappings/ado_custom.yaml`:
+
+```yaml
+framework: scrum
+
+field_mappings:
+  System.Description: description
+  Custom.StoryPoints: story_points
+  Custom.BusinessValue: business_value
+  Custom.Priority: priority
+
+work_item_type_mappings:
+  Product Backlog Item: User Story
+  Requirement: User Story
+```
+
+**See Also**: [Custom Field Mapping Guide](./custom-field-mapping.md) for complete documentation on field mapping templates, framework-specific examples, and best practices.
+
 ## Template Customization
 
 ### Creating Custom Templates