Release dev to main (0.26.14) (#165)

* perf: optimize startup performance with metadata tracking and update command (#142)

* feat: implement backlog field mapping and refinement improvements

- Add FieldMapper abstract base class with canonical field names
- Implement GitHubFieldMapper and AdoFieldMapper
- Add custom field mapping support with YAML templates
- Add field validation in refinement (story_points, business_value, priority)
- Add comprehensive unit and integration tests (42 tests)
- Add custom field mapping documentation
- Fix custom_field_mapping parameter connection
- Add early validation for custom mapping files

Implements OpenSpec change: improve-backlog-field-mapping-and-refinement

* perf: optimize startup performance with metadata tracking and update command

- Add metadata management module for tracking version and check timestamps
- Optimize startup checks to only run when needed:
  - Template checks: Only after version changes detected
  - Version checks: Limited to once per day (24h threshold)
- Add --skip-checks flag for CI/CD environments
- Add new 'specfact update' command for manual update checking and installation
- Add comprehensive unit and integration tests (35 tests, all passing)
- Update startup_checks to use metadata for conditional execution
- Ensure backward compatibility (first-time users still get all checks)

Performance Impact:
- Startup time: Reduced from several seconds to < 1-2 seconds
- Network requests: Reduced from every startup to once per day
- File system operations: Reduced from every startup to only after version changes

Fixes #140
Implements OpenSpec change: optimize-startup-performance

* feat: request offline_access scope for Azure DevOps refresh tokens

- Add offline_access scope to Azure DevOps OAuth requests
- Refresh tokens now last 90 days (vs 1 hour for access tokens)
- Automatic token refresh via persistent cache (no re-authentication needed)
- Update documentation to reflect 90-day refresh token lifetime

This addresses the issue where tokens were expiring too quickly.
Refresh tokens obtained via offline_access scope enable automatic
token renewal for 90 days without user interaction.

Fixes token lifetime limitation issue

* feat: improve CLI UX with banner control and upgrade command

- Change banner to hidden by default, shown on first run or with --banner flag
- Add simple version line (SpecFact CLI - vXYZ) for regular use
- Rename 'update' command to 'upgrade' to avoid confusion
- Update documentation for new banner behavior and upgrade command
- Update startup checks message to reference 'specfact upgrade'

* fix: suppress version line in test mode and fix field mapping issues

- Suppress version line output in test mode and for help/version commands to prevent test failures
- Fix ADO custom field mapping to honor --custom-field-mapping on writeback
- Fix GitHub issue body updates to prevent duplicate sections
- Ensure proper type handling for story points and business value calculations

* Fix failed tests

* chore: bump version to 0.26.7 and update changelog

- Fixed adapter token validation tests (ADO and GitHub)
- Resolved test timeout issues (commit history, AST parsing, Semgrep)
- Improved test file discovery to exclude virtual environments
- Added file size limits for AST parsing to prevent timeouts

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* fix: add missing ADO field mappings and assignee display (#145)

* fix: add missing ADO field mappings and assignee display

- Add Microsoft.VSTS.Common.AcceptanceCriteria to default field mappings
- Update AdoFieldMapper to support multiple field name alternatives
- Fix assignee extraction to include displayName, uniqueName, and mail
- Add assignee display in preview output
- Add interactive template mapping command (specfact backlog map-fields)
- Update specfact init to copy backlog field mapping templates
- Extend documentation with step-by-step guides

Fixes #144

* test: add unit tests for ADO field mapping and assignee fixes

- Add tests for Microsoft.VSTS.Common.AcceptanceCriteria field extraction
- Add tests for multiple field name alternatives
- Add tests for assignee extraction with displayName, uniqueName, mail
- Add tests for assignee filtering with multiple identifiers
- Add tests for assignee display in preview output
- Add tests for interactive mapping command
- Add tests for template copying in init command
- Update existing tests to match new assignee extraction behavior

* docs: update init command docstring to mention template copying

* docs: update documentation for ADO field mapping and interactive mapping features

- Update authentication guide with ADO token resolution priority
- Update custom field mapping guide with interactive mapping details
- Update backlog refinement guide with progress indicators and required field display
- Update Azure DevOps adapter guide with field mapping improvements
- Update command reference with map-fields command documentation
- Update troubleshooting guide with ADO-specific issues
- Update README files with new features
- Update getting started guide with template initialization

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: address review findings for ADO field mapping

- Prefer System.* fields over Microsoft.VSTS.Common.* when writing updates
  (fixes issue where PATCH requests could fail for Scrum templates)
- Preserve existing work_item_type_mappings when saving field mappings
  (prevents silent erasure of custom work item type mappings)

Fixes review comments:
- P1: Prefer System.AcceptanceCriteria when writing updates
- P2: Preserve existing work_item_type_mappings on save

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: mitigate code scanning vulnerabilities (#148)

* fix: mitigate code scanning vulnerabilities

- Fix ReDoS vulnerability in github_mapper.py by replacing regex with line-by-line processing
- Fix incomplete URL sanitization in github.py, bridge_sync.py, and ado.py using proper URL parsing
- Add explicit permissions blocks to 7 GitHub Actions jobs following least-privilege model

Resolves all 13 code scanning findings:
- 1 ReDoS error
- 5 URL sanitization warnings
- 7 missing workflow permissions warnings

Fixes #147

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: accept GitHub SSH host aliases in repo detection

Accept ssh.github.com (port 443) in addition to github.com when
detecting GitHub repositories via SSH remotes. This ensures
repositories using git@ssh.github.com:owner/repo.git are properly
detected as GitHub repos.

Addresses review feedback on PR #148

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: prevent async cleanup issues in test mode

Remove manual Live display cleanup that could cause EOFError.
The _safe_progress_display function already handles test mode
by skipping progress display, so direct save path is sufficient.

Fixes test_unlock_section failure with EOFError/ValueError.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: detect GitHub remotes using ssh:// and git:// URLs

Extend URL pattern matching to support ssh://git@github.com/owner/repo.git
and git://github.com/owner/repo.git formats in addition to existing
https?:// and scp-style git@host:path URLs.

This fixes a regression where these valid GitHub URL formats were not
detected, causing detect() to return false for repos using these schemes.

Addresses review feedback on PR #149

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: bump version to 0.26.9 and update changelog

- Update version from 0.26.8 to 0.26.9
- Add changelog entry for GitHub remote detection fix and code scanning fixes

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: compare GitHub SSH hostnames case-insensitively

Lowercase host_part before comparison to handle mixed-case hostnames
like git@GitHub.com:org/repo.git. This restores the case-insensitive
behavior from the previous config_content.lower() check and prevents
regression where valid GitHub repos with mixed-case hostnames would
not be detected.

Addresses review feedback on PR #150

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add openspec and workflow commands for transparency

* Add specs from openspec

* Remove aisp change which wasn't implemented

* Fix openspec gitignore pattern

* Update gitignore

* Update contribution standards to use openspec for SDD

* Migrate to new opsx openspec commands

* Migrate workflow and openspec config

* fix: bump version to 0.26.10 for PyPI publish

- Sync version across pyproject.toml, setup.py, src/__init__.py, src/specfact_cli/__init__.py
- Add CHANGELOG entry for 0.26.10 (fixes incorrect version publish issue)

Co-authored-by: Cursor <cursoragent@cursor.com>

* Update version and changelog

* Add canonical user-friendly workitem url for ado workitems

* Update to support OSPX

* feat(backlog): implement refine --import-from-tmp and fix type-check (#156)

* feat(backlog): implement --import-from-tmp for refine export/import round-trip

- Add _parse_refined_export_markdown() to parse export-format markdown (ID, Body, Acceptance Criteria, optional title/metrics)
- Import branch: read file, match by ID, update items; --write calls adapter.update_backlog_item()
- Remove 'Import functionality pending implementation' message
- Unit tests for parser (single item, AC/metrics, header-only, blocks without ID)
- Bump version to 0.26.11 and sync across pyproject.toml, setup.py, src/__init__.py, src/specfact_cli/__init__.py
- OpenSpec change: implement-backlog-refine-import-from-tmp (proposal, tasks, spec delta)

Fixes #155

Co-authored-by: Cursor <cursoragent@cursor.com>

* Fix type check issues

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* feat: debug logs under ~/.specfact/logs and release 0.26.13 (#159)

* feat: add debug logs under ~/.specfact/logs with operation metadata

- User-level log dir: get_specfact_home_logs_dir() (~/.specfact/logs, 0o755)
- debug_print() routes to console and rotating specfact-debug.log when --debug
- debug_log_operation() for structured metadata (ADO, GitHub, backlog, init)
- CLI init_debug_log_file() when --debug; help text updated

Closes #158
OpenSpec change: add-debug-logs-specfact-home

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add debug logging for selected commands at first

* release: 0.26.13 - debug log parity for upgrade, versions and changelog

- Log upgrade success (up to date) to ~/.specfact/logs/specfact-debug.log
- Bump version to 0.26.13; sync pyproject.toml, setup.py, src/__init__.py, specfact_cli/__init__.py
- CHANGELOG: 0.26.13 Fixed entry for upgrade debug parity

Co-authored-by: Cursor <cursoragent@cursor.com>

* Remove pr markdown

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* Potential fix for pull request finding 'Empty except'

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>

* Fix unused variable review

* Fix unused variable review

* Fix type and test errors

* Finalize change

* Change for debug logs archived

* fix: improve ADO backlog refine error logging and user-facing error UX (#164)

* Improving error logging capabilities

* small fix on changelog

* Archived change

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

---------

Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>
Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -9,6 +9,20 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.26.14] - 2026-01-29
+
+### Fixed (0.26.14)
+
+- **ADO backlog refine error logging and user-facing error UX** (fixes [#162](httsps://github.com/nold-ai/specfact-cli/issues/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 "<system-temp>/..."
+
+---
+
 ## [0.26.13] - 2026-01-29
 
 ### Fixed (0.26.13)
@@ -36,7 +50,7 @@ All notable changes to this project will be documented in this file.
 ### 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**)
+  - **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)
@@ -62,7 +76,7 @@ All notable changes to this project will be documented in this file.
 ### 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__)
+  - **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
 
 ---